spike: prove ctx.switchSession re-camps a live session

[neilwashere]

Before rewriting any transition, establish that an in-process switch actually delivers what a relaunch delivers. Everything downstream assumes it does.

Do this behind a flag on /worktree enter only: command-driven, human-initiated, already idle. Lowest possible blast radius.

Shape worth trying

Mirror the prior art's src/session.ts:

await ctx.waitForIdle();
const forked = SessionManager.forkFrom(sourceSessionFile, worktreePath);
await ctx.switchSession(forked.getSessionFile(), {
 withSession: async (ctx) => { /* report from the replacement ctx only */ },
});

Then verify, in a real session, against a real worktree:

• bash runs in the worktree — pwd reports the worktree path
• read/edit resolve repo-relative paths against the worktree
• the worktree's own .pi/ extensions load, and its skills and AGENTS.md are in context
• conversation history survives the hop and the transcript is continuous
• process.cwd() is unchanged — confirm the divergence exists and note everything that reads it
• an ephemeral (--no-session) session survives; the prior art copies the active branch into a persisted target rather than losing it
• a session with zero turns yet does not produce an empty or broken target (this is what fix: a hop from a session with no turns yet leaves a shell, not pi #11 was)
• session_before_switch firing does not let an unrelated extension silently cancel our hop without us noticing
• the same flow under -p / print mode, since modes/print-mode.js:71 wires switchSession too

Constraints

Flag-gated, no default behaviour change, no deletions. The relaunch path stays fully intact and reachable for the whole spike.

Deliverable is a findings note plus a go/no-go, not a merged feature. A red result on tool rebinding or resource reloading stops the epic; a red result on the ephemeral or zero-turn cases is a scope note, not a stop.

[neilwashere]

Green — proceed

A real AgentSessionRuntime was switched between a repo and its linked worktree against a temp agentDir. Every checklist item passes. Findings written up in docs/spikes/2026-08-22-in-process-session-switch.md, behaviour pinned by test/session-switch.test.ts (7 cases, suite green at 11 files).

Checklist item	Result
bash runs in the worktree	pass — pwd reports the worktree after the switch
read/edit resolve against the worktree	pass — _buildRuntime calls createAllToolDefinitions(this._cwd, …), so every built-in is constructed from the session cwd
worktree extensions/skills/AGENTS.md load	pass — createAgentSessionServices({cwd}) rebuilds SettingsManager and the resource loader; the worktree's AGENTS.md replaces the main checkout's
history survives, transcript continuous	pass
process.cwd() unchanged	confirmed — see below
ephemeral / --no-session survives	pass, via the in-memory entry path
zero-turn session does not break	pass, but not the way we assumed — see below
session_before_switch cancellation visible	pass — switchSession returns {cancelled:true} rather than throwing
works under print mode	wired at modes/print-mode.js:71; not exercised here, deferred to #20 where it is load-bearing

Two findings that change the downstream issues

A session file is not written until it holds an assistant message. SessionManager._persist buffers every entry in memory and flushes the whole document only once an assistant message arrives. Before that the file is empty on disk and forkFrom rejects it outright:

Cannot fork: source session file is empty or invalid

This hits a brand-new session and a turn still in flight. The in-memory entries are the reliable source: building the target document from getEntries() and writing it to a session created at the target cwd preserves cwd, active leaf and content. Verified for both the unflushed and zero-entry cases.

Note this is strictly better than what we do today. FORK_IF_USABLE tests the source file with [ -s "$1" ] and starts a fresh session when it is empty — discarding a conversation that was recoverable all along. So #19 and #20 should build targets from entries, never from the source file, and never assume a source file exists.

process.cwd() never moves. Confirmed: pi calls process.chdir nowhere. After a switch runtime.cwd is the target while process.cwd() is still the launch directory. Harmless for tools, which take an explicit cwd. It only becomes material when the original directory is deleted — so it is a #21 problem specifically, and that issue's requirement to enumerate process.cwd() readers before dropping the relaunch fallback stands.

Scope note

The bash pwd proof was run manually rather than committed, because reaching the tool definition means asserting against private session state. The committed test sticks to public API; the structural evidence (createAllToolDefinitions(this._cwd, …)) is the durable version of the same claim and is cited in the findings doc.

Unblocks #19, #20, #21.

[neilwashere]

Correction — mechanism proven, product spike failed

The earlier green verdict is withdrawn. switchSession itself rebinds cwd-bound runtime services, but the flag-gated product spike abandoned the live session twice in an unoriented temp worktree. The mechanism is usable; our transition protocol is not yet.

The missing boundary is the handoff: relaunches pass PI_WT_HANDOFF to a new process, while an in-process replacement has no explicit channel. The replacement therefore arrived without instruction. A second defect leaves PI_WT_HANDOFF process-scoped and unconsumed, so a later extension instance can re-read stale transition data and report target-conflict, target-not-found. Filed as #24.

No further runtime-switch verification will run on a developer host. #19 will be developed and exercised only in a disposable container. This spike remains open until that isolated end-to-end proof passes.

[neilwashere]

Container proof — green

The product spike now passes without touching a developer session.

test/container/enter-switch.e2e.ts runs only when both /.dockerenv and PI_WORKTREE_CONTAINER_TEST=1 are present. The normal npm test discovery cannot see it. test/container/run-enter-switch.sh builds a disposable image from node:24-bookworm, runs the real switch there, removes the container and removes the final image in a trap.

The proof loads the real extension into a real AgentSessionRuntime, resolves the registered /worktree command, invokes enter feat/x, and verifies:

• runtime, services and session-manager cwd all become the linked worktree;
• no tmux/cmux/herdr transport is present;
• exactly one pi-worktree-transition custom message is persisted after the carried branch;
• the orientation names the real source and target, is visible, and participates in the next model context;
• idle enter creates no synthetic user or assistant turn;
• a pending predecessor PI_WT_HANDOFF does not reach the replacement;
• a relaunch handoff is consumed once, and an actual extension reload cannot consume it again.

The first container run correctly failed on an over-strict test assumption: Pi adds session-name metadata during session_start, so an idle target has two entries rather than one. The invariant was corrected to “one transition orientation, zero user/assistant messages.” The implementation did not change for that failure.

Commands green:

npm run check
npm run test:container-enter

Implemented by ad4c7c2; mechanism findings in fef832e. Closing the spike. #19 and #24 remain open until their implementation merges.