Spec: Oh My Pi session format compatibility in the Pi adapter

Traceability

• Spec ID: OMP-01
• Story: none; maintainer-approved review follow-up on PR #143
• Status: implemented

Intent

Oh My Pi (OMP) is a fork of Pi that shares the session transcript schema but diverges in three observable ways. The Pi session adapter should read OMP session trees when it is pointed at an OMP agent directory, without loosening any of the workspace-isolation guarantees the Pi adapter already makes.

OMP is not a new host adapter: it has no host id, no capability profile, no install shell, and no lifecycle target of its own. It is a recognized session layout for the existing pi platform, reached with PI_CODING_AGENT_DIR=~/.omp/agent.

Observed OMP divergences

Divergence	Pi	OMP
Session directory name	absolute slug --Users-ooxx-src-dotai--	home-relative slug -src-dotai
JSONL preamble	first record is the session header	a title record precedes the header
Session forking	not observed	/fork copies every parent entry into a new file carrying parentSession

Acceptance scenarios

• AC-1 — Home-relative discovery. A workspace under the home directory resolves an additional homeExact variant (~/src/dotai → -src-dotai), and a session directory with that name is discovered.
• AC-2 — Bounded home-relative prefix. Subdirectory session directories match through homePrefix only across a separator boundary (-src-dotai-packages-app matches, -src-dotaix does not). A workspace whose only prefix-similar sibling has sessions reports its source root as absent.
• AC-3 — Non-home workspaces unchanged. A workspace outside the home directory exposes no home-relative variant, and the absolute exact/prefix contract is byte-identical to before.
• AC-4 — Foreign-platform slug integrity. A Windows-shaped workspace string keeps its drive letter on every host (C:\workspace\project → --C--workspace-project--) and never resolves against the host cwd. Only a host-native absolute path is eligible for a home-relative variant.
• AC-5 — Title preamble. Leading title records are skipped when locating the session header. Any other non-session record before the header still rejects the transcript fail-closed, and a second session header still rejects the whole file.
• AC-6 — Fork deduplication. When a fork's parentSession is also discovered in the same result, entries stamped before the fork point are read as the parent's and excluded from the fork, so each entry is counted once.
• AC-7 — Orphan fork retention. When the parent is not in the discovery result, the fork keeps its inherited entries: nothing else owns them, so dropping them would silently lose evidence.
• AC-8 — Time range agreement. A session's reported firstSeen/lastSeen always covers exactly the entries it yields, whether or not the fork cutoff applies.

Design

workspaceToPiSessionDirVariants keeps the absolute slug derivation untouched and adds homeExact/homePrefix when the workspace is a host-native absolute path under the home directory. Slug normalization and home-relative derivation read different inputs on purpose: the slug body keeps path.win32 handling so a Windows-shaped workspace string survives on a POSIX host, while the home-relative body needs the host-native path because a foreign-platform path can never be home-relative.

probeTranscript records parentSessionId, forkTimestamp, and a second "owned" time range that excludes inherited entries. discoverSessions collects every probe first, then decides per file whether the fork cutoff applies, because the parent may be probed after its fork. The cutoff is stored on the source ref rather than the session, so a session with several transcripts cannot leak one file's cutoff onto another. isInheritedForkEntry is shared by discovery and readSession so the reported time range and the yielded events cannot disagree.

Non-goals

• Adding OMP to scripts/host-support as a distinct host id or capability profile.
• An OMP install shell, plugin manifest, or npm-packaged host artifact.
• Promoting OMP into the verified Quickstart set.
• Detecting an OMP agent directory automatically; the operator points at it with PI_CODING_AGENT_DIR.

Risks

• The parentSession field name and the header-timestamp-as-fork-point rule come from observed OMP transcripts, not a published schema. If OMP renames the field, fork deduplication silently stops applying and forks report inherited entries again — the fail-open direction, which over-counts rather than loses evidence.
• Fork deduplication compares timestamps. An inherited entry without a timestamp, or one sharing the fork millisecond, stays with the fork.

Test evidence

test/sessions/session-analysis-providers.test.mjs:

• Pi derives OMP home-relative session directory names with a bounded prefix (AC-1, AC-2, AC-3)
• Pi discovers OMP home-relative session directories and skips the title preamble (AC-1, AC-5)
• Pi keeps a sibling OMP workspace out of the home-relative prefix match (AC-2)
• Pi discovers OMP subdirectory session dirs under the home-relative prefix (AC-2)
• Pi counts OMP inherited fork entries once when the parent session is discovered (AC-6, AC-8)
• Pi retains OMP inherited fork entries when the parent session is absent (AC-7, AC-8)
• Claude, Cursor, and Qwen workspace slugs cover Unix and Windows layouts (AC-4)
• Pi provider requires one authoritative first session header (AC-5)

Each new assertion was mutation-checked: reverting the prefix boundary, the path.win32 slug handling, or the parent-existence condition fails exactly the test that covers it.