feat: add pi as a direct-session provider

[Kunde21]

Summary

Adds pi (the @earendil-works/pi-coding-agent harness) as a fourth direct-session provider alongside Claude, Codex, and OpenCode. Pi sessions are tree-structured JSONL on disk, so this mirrors the Claude filesystem model while porting pi's own active-branch resolution so imported transcripts match what a resumed pi session actually sees.

Discovery, transcript import/follow, linking, and takeover all resolve through the existing shared seam (getDirectSessionProviderOps('pi') via the backend catalog), keeping shared orchestration provider-agnostic.

Changes

• Protocol (packages/protocol): add 'pi' to AgentProviderIdV1 and a piAgentDir source variant to DirectSessionsSource.
• Provider (apps/cli/src/backends/pi/directSessions/): full DirectSessionProviderOps implementation — discovery (cwd-encoded directory scan), paging (whole-file tree-walk → active-branch item-list paging), readAfter/follow, activity, working-directory (from authoritative header cwd), and takeover spawn options (pi --session <uuid> from the session's cwd, PI_CODING_AGENT_DIR env).
• Catalog (backends/pi/index.ts): wire getDirectSessionProviderOps.
• Linking (ensureDirectSessionLink): pi arms for source-keyed identity (piAgentDir:<agentDir>), piSessionId metadata, and pi marker recognition.
• Security gate (validateDirectMachineSource): pi arm mirroring Claude's model (daemon-controlled agent dir, client override must match — path-traversal guard).

Key implementation notes

• Active-branch resolution: ports pi's own buildContextEntries / buildSessionPath / _buildIndex (last-in-file leaf derivation, firstKeptEntryId compaction fold) so imports never include abandoned sibling branches or duplicate history. Faithful to the installed binary.
• Paging cursor: backward paging uses an endExclusive cursor (collect newest-first, byte-limit truncates the older end) so pages stay gap-free and overlap-free even when maxBytes truncates below maxItems — reconstructable into full chronological order.
• Takeover: resumes in place via pi --session <uuid> (not --fork), launched from the header cwd (authoritative; the --<cwd>-- directory name is not decoded since its encoding collapses separators and drive colons).

Two bugs found and fixed via testing

1. Paging overlap: the original backward pager's consumed cursor caused overlapping windows when maxBytes truncated pages → duplicated/gapped, out-of-order imports of any substantial session. Caught by live validation against a real 700-item pi session.
2. Security gate: validateDirectMachineSource had a closed switch over the provider enum with no pi arm → every pi RPC request rejected at runtime with unsupported direct session provider, despite TypeScript compiling. Caught by an RPC-handler integration test.

Testing

• Unit: pi provider module suite (entry-context, mapping, paging, title, discovery) + linking + validation.
• Integration: RPC-handler tests exercising list/page/readAfter/link.ensure/takeover through the real catalog + real pi providerOps with fixture pi sessions (including an abandoned sibling branch so active-branch selection comes through the RPC stack).
• Live validation (throwaway, not committed): ran the provider against real ~/.pi/agent — discovered 119 sessions, paged a 700-item session across 7 pages (chronological, gap-free, duplicate-free).
• No regressions across the direct-session corridor (Claude/Codex/OpenCode unaffected).

Out of scope / residual

• The literal pi --session <uuid> process spawn was not run against a live daemon+server (needs a running daemon build + server auth). The spawn options are proven correct and match pi's verified resume semantics.
• Protocol dist is a gitignored build artifact; CI will regenerate it from source.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Note

Add pi as a direct-session provider with transcript paging, candidate listing, and takeover support

• Registers pi as a valid AgentProviderIdV1 and extends DirectSessionsSourceSchema with a new piAgentDir source kind.
• Adds piDirectSessionProviderOps implementing the full DirectSessionProviderOps interface: listing session candidates, paging transcripts (backward with byte/item limits), tail-reading via polling forward cursor, retrieving activity from file mtime, and resolving spawn options to resume pi in-place.
• Session files are discovered by scanning <agentDir>/sessions subdirectories, extracting UUIDs from JSONL filenames, and sorting by mtime. Candidate listing supports pagination via base64url index cursors and optional title/metadata search.
• Transcript mapping walks the active branch via parentId links, handles compaction (firstKeptEntryId), and normalizes entries to DirectTranscriptRawMessageV1 with stable pi:<relPath>:<id> identifiers.
• validateDirectMachineSource enforces that client-supplied agentDir matches the daemon-configured path, mirroring the existing claude policy.

^{Macroscope summarized db3805b. (Automatic summaries will resume when PR exits draft mode or review begins).}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 88b8bb60-a5e5-4eeb-b981-024d87b015d6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}