fix(server): resume external Claude Code sessions — adopt-into-managed (ADR-056)

[aterrylu]

Problem

A real user hit this during onboarding: Claude Code sessions started from a terminal (claude, outside autonomOS) show up in the dashboard Projects panel, but clicking resume returns failed to resume session. Terry: "I don't think we had it work in a very long time."

Discovery was never broken. GET /api/projects lists external sessions correctly. The break was entirely resume-side — and it was one throw:

flowchart TD
    A["Click resume in Projects panel<br/>Sidebar.tsx"] --> B["store.ts sends<br/>resumeSessionId = CC uuid ✓"]
    B --> C["store.ts REWRITES<br/>resumeSessionId → resumeAgentId ✗<br/>(assumes agent.id == CC uuid)"]
    C --> D["POST /api/agents → spawnAgent"]
    D --> E["getAgent(resumeAgentId) → undefined<br/>throw 'not found' → HTTP 404"]
    E --> F["UI: 'failed to resume session'"]
    style C fill:#e8b4b4,color:#000
    style E fill:#e8b4b4,color:#000

Loading

Root cause, precisely dated: commit 9ac5d5b — "unify Agent + Session (#165)", 2026-05-04. It deleted routes/sessions.ts (whose POST /api/sessions passed resumeSessionId straight to claude --resume <id>, no record required) for the agent-record-gated spawnAgent, collapsing two distinct id-spaces — a raw CC session id vs. an internal agent-record id — into one resumeAgentId resolved only by getAgent(). External sessions have no record, so every entry point (UI, POST /api/agents, /attach, MCP create_agent) 404'd. Never captured as an ADR — silent drift.

The provider's --resume <uuid> argv and the lazy-JSONL hasResumableSession probe survived intact. This PR reconnects the plumbing; it doesn't rebuild the engine.

Solution

spawnAgent gains a distinctly-named resumeSessionId (raw CC session id), separate from resumeAgentId:

flowchart TD
    R["resumeSessionId (raw CC id)"] --> L{"resolve in agent store<br/>by providerSessionId, or agent id"}
    L -->|hit| RA["REATTACH managed record<br/>markRunning + --resume"]
    L -->|miss| G{"assertAdoptable<br/>provider can probe? id is a UUID?"}
    G -->|no| X["reject 422 / 400<br/>no record created"]
    G -->|yes| P{"hasResumableSession<br/>transcript on disk?"}
    P -->|no| X2["reject 422 'nothing to resume'<br/>no orphan record"]
    P -->|yes| AD["ADOPT → new persistent<br/>managed record + --resume"]
    style RA fill:#b4d7e8,color:#000
    style AD fill:#b4e8c0,color:#000
    style X fill:#e8b4b4,color:#000
    style X2 fill:#e8b4b4,color:#000

Loading

resumeAgentId and /attach are untouched, so the ADR-049 dev-restart path carries no regression risk. Two names for two id-spaces is also the exact lesson of the bug being fixed.

Also fixes the dual-id footgun (reported by Terry during implementation): resuming a managed agent needed the autonomOS id, but the CC session id got tried first, 404'd, then retried. New spawns (fresh/fork/adopt) now use one id for both (id == providerSessionId). Pre-existing split-id agents resolve via a providerSessionId fallback on /attach — no id migration, since an id is referenced by managerId, layout panes, and persisted sessions.

Fail-closed by design

A silently-empty session is worse than an error, so adoption refuses rather than guesses. Each of these was found by /polish review agents and is covered by tests or QA:

Guard	Behavior
Provider can't probe disk (Codex, Gemini)	reject 422 — ADR-056's scope is now enforced, not just documented
Session id isn't a UUID	reject 400 — the id becomes a record filename; blocks path traversal
No transcript on disk	reject 422, no orphan record
Probe throws	fail closed on adopt (fail-open is only correct for reattach)
Adopt crashes on boot	safety net not armed — it would overwrite providerSessionId and erase the only pointer to the conversation
Reattach with a wrong cwd	uses the record's workingDirectory, not the caller's guess
Empty-string resume id	reject 400 instead of silently spawning fresh

Dashboard: stop rewriting resumeSessionId → resumeAgentId (client-side root cause), surface the server's error reason instead of a generic status, and match sessions on both id-spaces so a running split-id agent switches panes instead of erroring.

Testing

Real end-to-end — a genuine terminal-started claude session (outside autonomOS, env stripped), conversed to force the lazy JSONL write, then resumed through autonomOS:

Check	Result
External session discovered by /api/projects	✅ isAutonomosAgent: null
POST /api/agents {resumeSessionId} → adopt	✅ 201, id == providerSessionId == CC id
--resume <external id> in argv, no --session-id	✅ real resume, not fresh
Same transcript continued, not forked	✅ 1 file, grew 56959→57315 bytes
Prior context actually loaded	✅ recalled PURPLE-OTTER-42
MCP create_agent(resumeSessionId)	✅ 201, recalled SILVER-BADGER-99
Re-resume → reattach, no duplicate	✅ same id, count stays 1
Codex adopt	✅ rejected 422
../../../../tmp/pwn as id	✅ rejected 400, no traversal write
Empty-string id	✅ rejected 400
No-transcript id	✅ rejected 422, agent count unchanged
Reattach with wrong cwd	✅ warned, used the record's, resume succeeded

The context-recall checks are the ones that matter — a session can spawn successfully with --resume and still come up empty, which is exactly the failure mode this bug class produces.

Automated: 11 new unit tests (store resolver, id == providerSessionId invariant, and the assertAdoptable guard — including path-traversal and unsupported-provider rejection). Full gate green: biome check (no --write), make check, and AUTONOMOS_INTEGRATION=1 make check → 653 server + 254 dashboard tests, 0 failures.

Risks

• Adopt → managed (Terry's call): an adopted session becomes a first-class managed agent that survives restart. Intended, but it does mean resuming an external session now creates a persistent record.
• id-unification applies to new spawns only. Existing split-id agents keep their ids and rely on the providerSessionId fallback. Migrating them was rejected as too high-blast-radius.
• Error classification is substring-based in the route handler. Ordering is now explicit and commented, but typed Error subclasses + a central onError would be the durable shape — deliberately out of scope.
• Codex/Gemini external resume is not shipped. The Projects panel discovers sessions via the CC SDK listSessions(), which doesn't enumerate Codex threads; that needs its own discovery source. The guard makes this an honest 422 rather than a silent empty session.

Alternatives considered

• One universal resumeSessionId replacing resumeAgentId//attach — rejected: risks the tested managed-restart path and re-conflates the id-spaces that caused this bug.
• Migrate existing split-id records to id == providerSessionId — rejected: ids are referenced by managerId, layout panes, persisted sessions.
• Adopt as an ephemeral attach — rejected per Terry: the value is that a discovered session becomes managed.
• Silently start fresh when an adopt target has no transcript — rejected: the user asked for that conversation.

Notes

• ADR-055 is intentionally skipped — reserved for AppSecurityAudit's planned two-listener split (referenced in ADR-054). This PR takes ADR-056.
• No conflict with PR fix(security): require auth on /mcp — closes an unauthenticated RCE (ADR-054) #281 (server auth surface) — providers/claude-code.ts is unmodified; its argv builder and probe are reused as-is.
• docs/FEATURES.md F-004 updated: resume-into-managed is no longer N/A for discovered sessions.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HnRSVXE4eMY4ZehhCBB3Qi

[nox-0x]

Approving — restores an entry point that had been silently dead since #165, and the fail-closed adopt guards (UUID shape check, provider-capability gate, no-transcript reject, fail-closed probe, safety-net disarm) are the right calls given the alternative is a phantom empty conversation over the user's real one. The dual id-space naming (resumeSessionId vs resumeAgentId) is the direct antidote to the bug being fixed; test coverage on the store resolver + assertAdoptable is proportionate to their blast radius; dashboard client-side change removes exactly the rewrite that caused the 404. Real-terminal QA (context-recall, path-traversal, wrong-cwd, empty-string, no-transcript) covers the meaningful failure modes.

One minor follow-up (posted inline, non-blocking): the empty-string sanity check for resume/fork ids lives in the REST handler, but the HTTP MCP create_agent in mcp.ts calls spawnAgent directly and bypasses it — same silent-fresh-spawn class the check exists to prevent. Promoting the guard into spawnAgent itself (or a shared boundary) would cover both entry points and any future callers; can land separately.