fix(server): resume after self_exit fails with 'resumeAgentId not found'

[aterrylu]

Problem

Resuming an agent that called self_exit fails with resumeAgentId "<id>" not found.

Root cause: two "terminate" paths that look equivalent are asymmetric:

Path	Route	Effect	Resumable?
kill_agent	POST /api/agents/:id/kill → killAttachment → markExited	record kept as status:"exited"	✅
self_exit	DELETE /api/agents/:id → deleteAgentRaw → rmSync + cache.delete	record hard-deleted	❌

The resume path (spawnAgent with resumeAgentId) looks the agent up via getAgent(id) — a pure cache/disk read. After self_exit the record was rmSync'd off disk, so getAgent returns undefined and runtime.ts throws resumeAgentId "<id>" not found.

The reporting agent's theory ("autonomOS purges the session record on self_exit") was correct — the precise mechanism is the DELETE route's rmSync, not markExited.

sequenceDiagram
    participant A as Agent
    participant CS as channel-server
    participant API as server API
    participant Store as agents store

    rect rgb(255,235,235)
    note over A,Store: BEFORE — self_exit hard-deletes, resume fails
    A->>CS: self_exit
    CS->>API: DELETE /api/agents/:id
    API->>Store: deleteAgentRaw → rmSync + cache.delete
    Note over Store: record GONE
    A-->>API: create_agent({resumeSessionId})
    API->>Store: getAgent(id) → undefined
    API-->>A: ❌ resumeAgentId "id" not found
    end

    rect rgb(235,255,235)
    note over A,Store: AFTER — self_exit soft-exits, resume works
    A->>CS: self_exit
    CS->>API: POST /:id/kill {reason:"self_exited"}
    API->>Store: killAttachment → markExited("self_exited")
    Note over Store: record KEPT (status: exited)
    A-->>API: create_agent({resumeSessionId})
    API->>Store: getAgent(id) → record ✓
    API-->>A: ✅ resumed (status: running)
    end

Loading

Not a recent regression

self_exit has hard-DELETEd since it was introduced (#124); #165 retargeted it /api/sessions → /api/agents (per-file hard delete) at the same time the resume feature began requiring a persisted exited record — a latent design conflict since the #165 unification. Verified not from #249 (UI-only, zero server files) or #237 (Codex providerThreadId path only).

Solution

Route self_exit through the same soft-exit path as kill/crash, keeping the record resumable with an honest exit reason:

• agents/runtime.ts — killAttachment(id, reason: ExitReason = "user_killed") parametrized; threads reason into markExited + the agent.exited WS delta.
• routes/agents.ts — POST /:id/kill accepts an optional {reason} body, validated via isExitReason (defaults to user_killed; logs unrecognized values rather than silently coercing). Guards a null JSON body.
• channel-server/index.ts — self_exit POSTs /:id/kill {reason:"self_exited"} instead of DELETE. Also surfaces HTTP-level kill failures to stderr (serverFetch resolves non-2xx as isError, so the prior .catch couldn't see them). Bundle (dist.mjs) regenerated.
• core/types/agent.ts — ExitReason now derives from a single EXIT_REASONS tuple + isExitReason typeguard, so adding a reason can't desync a hand-maintained allowlist.

Testing

Unit (resume-after-self-exit.test.ts, 5 tests): self-exited record stays findable across in-memory + on-disk reload; old deleteAgentRaw path documented as the breakage; isExitReason accepts the union and rejects 8 malformed inputs.

Real-spawn e2e (live dev server, isolated config, real claude PTY):

1. spawn → running
2. POST /:id/kill {reason:"self_exited"} → GET /:id returns 200 exited/self_exited (was 404)
3. POST /api/agents {resumeAgentId} → 201, re-attached (was "not found")
4. DELETE /:id → 200 then 404 (hard-delete path unchanged)
5. /kill no-body → user_killed; bogus reason → user_killed + server logs unrecognized reason

Full make check green: 558 server + 318 dashboard tests.

Risks / trade-offs

• Behavior change: a self-exiting manager's reports are no longer reparented (DELETE did this; /kill doesn't). Intentional — now symmetric with kill_agent, and keeping the exited manager in the chart is the point of the fix.
• Disk growth: self_exit was the only auto-cleanup path. Self-exited agents now accumulate like killed/crashed ones already do (there is no exited-record pruning anywhere today). This makes growth consistent rather than introducing a new unbounded class — but a bounded-retention prune is a sensible follow-up (filed separately, out of scope here).

🤖 Generated with Claude Code

[nox-0x]

Approving — clean fix for the self_exit / resume asymmetry, and the implementation is tight.

Reviewed the incremental diff. Verified:

• Diagnosis is correct. runtime.ts:243-245 does getAgent(params.resumeAgentId) and throws resumeAgentId "<id>" not found on undefined — exactly the symptom. Routing self_exit through POST /:id/kill → killAttachment → markExited("self_exited") keeps the record on disk so the resume lookup resolves.
• killAttachment signature change is backward-compatible. The new reason: ExitReason = "user_killed" parameter is defaulted; the lone other caller (mcp.ts:249, single-arg) is unaffected.
• /:id/kill body parsing is safe. c.req.json().catch(() => null) handles the no-body case (dashboard killSession at store.ts:1192 and kill_agent MCP at channel-server/index.ts:435 both send none) → silent user_killed default. Unknown reasons get logged, not silently coerced — good call.
• isExitReason + EXIT_REASONS single-source-of-truth removes the desync risk that motivated the type refactor.
• serverFetch error surfacing in channel-server/index.ts:520-524 is correct. Confirmed serverFetch resolves (not rejects) on non-2xx with { isError: true } (see channel-server/index.ts:235-241), so the prior .catch-only path really was blind to HTTP-level failures.
• markExited is idempotent ("first reason wins", store.ts:341), so the inevitable onExit handler firing after pty.kill() won't overwrite "self_exited" with "crashed" on disk. (There's a pre-existing stale-WS-delta race in runtime.ts:605-623 where the onExit handler emits an agent.exited delta with its locally-computed reason regardless of what markExited actually persisted — but that's not introduced by this PR and applies equally to operator kill.)
• Bundle (dist.mjs) regenerated in sync with channel-server/index.ts.
• Behavior-change trade-offs are honest. Self-exiting manager's reports no longer reparenting is intentional and symmetric with operator kill; unbounded exited-record growth from self_exit now matches existing kill/crash paths (already unpruned) — a separate retention prune is a reasonable follow-up, not a blocker.

Tests cover the store-level invariant the fix hinges on. Ship it.