feat(session): switch a session's agent mid-flight

[Pulkit7070]

What & why

A session's agent (harness) is currently fixed at spawn (SessionRecord.Harness, resolved once by effectiveHarness in session_manager) and can never change. Mixing agents on a single task — e.g. codex to test, claude-code to write, a cheaper model for cost — is impossible without throwing the work away and respawning.

This PR lets you change a session's agent in place, keeping the same git worktree (all code + uncommitted work preserved). The new agent launches fresh — there is no native resume, since a different harness cannot read the outgoing agent's session. An optional model override rides the same path.

Behaviour

Two cases are handled:

• Live session → swap in place. The old agent is torn down only after the new launch command validates, so a bad/unknown harness never disrupts the running session. A BeginSwitch/EndSwitch guard on the lifecycle manager makes the reaper ignore the brief window where the old runtime is gone and the new one isn't up yet — otherwise a "dead" probe would wrongly terminate the session mid-switch.
• Terminated session → relaunch-as. When an agent exits (e.g. codex ends its process on completion) the session is marked terminated. Switching such a session restores its worktree and launches the chosen agent fresh under it — the way to bring a finished task back under a different agent (plain restore keeps the original harness). Only fully merged sessions stay locked.

lifecycle.MarkSwitched atomically changes the persisted harness, points at the new runtime handle, and clears the harness-specific AgentSessionID (which MarkSpawned's metadata merge cannot, since it only sets non-empty fields), resetting activity/first-signal so the new agent re-proves its hook pipeline.

Surfaces

• Backend: sessionmanager.SwitchHarness (live + terminated paths) and lifecycle guard + MarkSwitched.
• API: POST /sessions/{id}/switch {harness, model?} — 400 unknown harness, 404 unknown session, 409 switch-in-progress. OpenAPI spec + frontend/src/api/schema.ts regenerated (pinned openapi-typescript@7.4.4).
• CLI: ao session switch <id> --harness <agent> [--model ...].
• UI: the session inspector's Overview → Agent row is now a dropdown that switches the agent in place (or relaunches a terminated one), built from the existing dropdown-menu primitive and AGENT_OPTIONS; merged sessions stay read-only.

Tests

• live swap clears AgentSessionID
• unknown harness leaves the running agent untouched (validate-before-destroy)
• terminated session relaunches under the new agent (restore-as)
• create-failure terminates cleanly (no live-session-with-dead-handle)
• reaper guard suppresses termination during a switch
• MarkSwitched changes harness, clears AgentSessionID, resets first-signal

go build ./..., go vet ./..., the full backend go test ./..., and frontend tsc all pass.

Notes / follow-ups

• No migration: the harness column and UpdateSession already exist.
• The target agent's CLI must be installed on PATH — the existing pre-flight binary check rejects otherwise, surfaced inline in the UI.
• Context handoff (carrying the outgoing agent's transcript into the new one) is intentionally out of scope; this leaves a clean seam (the fresh launch's prompt) for it.

🤖 Generated with Claude Code

[nikhilachale]

1. P1: switch-in-progress guard is not atomic, so duplicate switches can still race
   internal/session_manager/manager.go:591 checks IsSwitching, but internal/session_manager/manager.go:656 sets the guard later and BeginSwitch is idempotent with no failure return. Two
   concurrent requests can both pass the check, both enter BeginSwitch, and then both destroy/create runtimes against the same worktree. The terminated path is worse because internal/
   session_manager/manager.go:691 never begins the guard at all, so two relaunch-as switches can create two runtimes. This needs an atomic TryBeginSwitch/compare-and-set style API used by
   both live and terminated switch paths.

2. P2: terminated switch bypasses the existing not-resumable guard
   Restore refuses promptless, unresumable worker sessions via restoreArgv at internal/session_manager/manager.go:1433, but relaunchTerminatedWithHarness always calls fresh
   GetLaunchCommand with meta.Prompt at internal/session_manager/manager.go:707. That means ao session switch can resurrect a terminated worker with no prompt/native resume context into a
   blank agent session, which the existing restore path deliberately prevents. If switch-relaunch is meant to preserve restore semantics except for harness selection, it should reject the
   same promptless worker case.

[Pulkit7070]

Thanks @nikhilachale — both good catches, fixed in 551742c.

P1 (atomic switch guard): Replaced the check-then-act (IsSwitching + later BeginSwitch) with an atomic lifecycle.TryBeginSwitch — a single-critical-section compare-and-set. It's now claimed once at the top of SwitchHarness for both the live and terminated paths and released via defer, so two concurrent requests can't both pass, and the terminated path is no longer unguarded. Added TestSwitchHarness_RejectsConcurrentSwitch and a compare-and-set test on the lifecycle side.

P2 (terminated resumability): relaunchTerminatedWithHarness now mirrors restoreArgv's guard — since the new harness can't native-resume the old agent's session, a terminated worker with no saved prompt would blank-relaunch, which Restore deliberately refuses. It now returns ErrNotResumable for that case (orchestrators stay promptless by design). Added TestSwitchHarness_TerminatedPromptlessWorkerRejected.

Full backend go test ./... + frontend tsc pass.

[Pulkit7070]

Flow — SwitchHarness

One entry point, forking on whether the agent is still alive, converging on one atomic write. Validate-before-destroy + an atomic guard mean a bad agent never disrupts a running session and the reaper never mistakes the swap for a crash.

flowchart TD
  A["POST /sessions/{id}/switch { harness, model? }"] --> B{session found +<br/>worktree present?}
  B -- no --> E1["reject: ErrNotFound /<br/>ErrIncompleteHandle"]
  B -- yes --> C{"TryBeginSwitch(id)<br/>atomic compare-and-set"}
  C -- already switching --> E2["reject: ErrSwitchInProgress"]
  C -- claimed (defer EndSwitch) --> D{"validate agent:<br/>known + adapter + binary on PATH"}
  D -- invalid --> E3["reject: ErrUnknownHarness /<br/>binary not found"]
  D -- ok --> S{session terminated?}

  S -- "no · LIVE (swap in place)" --> L1["prepareWorkspace"]
  L1 --> L2["runtime.Destroy old handle"]
  L2 --> L3["runtime.Create new"]
  L3 -- fail --> LF["MarkTerminated<br/>(no dead-handle-live)"]

  S -- "yes · TERMINATED (relaunch-as)" --> T0{promptless worker?}
  T0 -- yes --> E4["reject: ErrNotResumable"]
  T0 -- no --> T1["workspace.Restore"]
  T1 --> T2["prepareWorkspace → runtime.Create new"]

  L3 --> M["lifecycle.MarkSwitched<br/>set harness · point at new handle ·<br/>clear AgentSessionID · reset activity"]
  T2 --> M
  M --> R["EndSwitch (defer) →<br/>updated session streamed over CDC<br/>(terminal re-attaches, UI reflects new agent)"]

Loading

While the guard is held, the lifecycle reducer ignores this session's reaper "dead" probe — that's what makes the brief runtime gap safe. The worktree (code + uncommitted work) is preserved throughout; only the runtime handle is disposable.

[Pulkit7070]

@nikhilachale re-requesting your review both of your comments are addressed (atomic TryBeginSwitch guard for P1, promptless-worker ErrNotResumable for P2), merge conflicts resolved, and the flow diagram is posted above. Ready for another pass

[Pulkit7070]

Fixed in 1e6d9a3.

Medium (workspace path not persisted): MarkSwitched now takes the full domain.SessionMetadata and persists WorkspacePath/Branch from the launch, so the terminated relaunch-as records the restored worktree instead of leaving the stale one. Added a MarkSwitched test that passes a different path/branch and asserts the session metadata is updated.

Bonus — also fixed a related runtime bug I hit while testing: switching to a harness that had already run the session relaunched it fresh and collided with the agent's own prior native session — Claude Code pins a deterministic --session-id, so a fresh relaunch failed with Session ID <uuid> is already in use. Sessions now track the set of harnesses they've launched (SessionMetadata.LaunchedHarnesses); a previously-used harness resumes via the adapter's restore command, a new one launches fresh. The promptless-worker ErrNotResumable guard now applies only to fresh launches (a resume needs no saved prompt). Tests cover resume-vs-fresh both ways.

Backend go test ./... + go vet pass.