Let an agent archive its own session

[selfcontained]

Idea: agent-self-archive — Give an agent the ability to archive itself.

dispatch_archive_agent was scoped to direct children, so an agent that had finished its work and reported it had no way to retire itself — archiving was only ever something done to it from outside. It now accepts the caller's own ID.

# before
$ tools/call dispatch_archive_agent {"agentId": "<its own id>"}
"You can only archive agents you launched via dispatch_launch_agent or dispatch_launch_persona."
# after
$ tools/call dispatch_archive_agent {"agentId": "<its own id>"}
Archiving agent "self archiver" (agt_selfa). This is your own session — it will stop momentarily.

Same tool, same rules, one path

No new tool and no new guardrails. Archiving yourself is not more dangerous than archiving a child — the same worktree can be lost either way — so the rules don't fork: still rejects an agent you neither launched nor are, still defaults cleanupWorktree to auto, so a worktree with unmerged or uncommitted work is preserved on disk.

The one thing self-archiving genuinely needs is that the teardown can't be awaited: the session being stopped is the one waiting for the response. So the handler claims the archive, answers, and runs teardown in the background — gated on the response actually having been written, which the MCP route hands down from the hijacked reply's finish/close. Holding teardown until the response flushes costs a child archive nothing, so both targets take the identical path and the handler has no branch in it.

agentLifecycleRuntime.beginBackgroundArchive owns claim → publish → background teardown → shutdown tracking, so the archive is still awaited at shutdown and still publishes its UI events.

Two guards came out of review. A job agent can't archive itself — a job agent leaves by reporting its outcome, and the run's terminal state is what auto-archives it; archiving around that made the job monitor report the run as crashed and page whoever the job notifies. dispatch_archive_agent now rejects any target with an active run and names job_complete / job_failed / job_needs_input. That applies to both targets, and only to agent-initiated archives — the HTTP archive route and the job runner's own auto-archive are untouched, since a human still needs to be able to kill a job agent that has genuinely gone wrong.

Second, handleLaunchAgent now refuses to create a child under a parent whose status is archiving. Only review children cascade, so a child launched after the claim would be orphaned the instant it started. That window existed before this change — a child being archived stays alive through its own teardown — but self-archive widens it, since the parent is deliberately kept alive until its response is written and is the one holding the MCP connection. The guard applies to every archive target, not only self.

One behavioural change to archiving a child: the tool returns archiving: true when teardown is scheduled rather than archived: true once it finished — matching what the HTTP archive route already reports.

Verified on a dev instance

Over the real agent-scoped MCP route:

check	result
tools/list	one archive tool, unchanged name
agent you neither launched nor are	rejected
child you launched	archives, as before
your own ID	archives; response says the session is stopping
worktree with 1 uncommitted file	preserved on disk after teardown (auto default)
response-before-teardown	server log: request completed, teardown 837ms later
launch inside the grace window	refused; zero orphan rows created
job agent self-archiving	refused, pointing at job_complete; run and agent intact
DELETE /api/v1/agents/:id on a job agent	still 202, still archives (human path unaffected)
job_complete on a job agent	run goes terminal, agent auto-archived as before

Review

Three personas (release-readiness, backend-security, infra) reviewed this specifically for release side effects.

• release-readiness: approved, no findings — no schema/config change, no rollback incompatibility.
• backend-security: two findings. The orphan-child window is fixed above. The second reported a job run left stuck running after its agent self-archived; measured on the dev stack, a run the JobService is monitoring goes to crashed in under 2s (agentSessionCrashed returns true once getAgent finds no row), and reconcileActiveRuns restarts monitors at boot. The observed row had been inserted outside that lifecycle; the reviewer confirmed and dismissed it. The underlying concern was still worth acting on, though — crashed is a false alarm for a deliberate exit — hence the active-run guard above.
• infra: flagged that finish is kernel handoff, not client receipt, so the 750ms settle can't be a hard bound. Accepted as a best-effort UX race rather than a correctness one — the archive is claimed and durable before the response, and MCP offers no client acknowledgement to wait on. Reviewer withdrew it and advised keeping 750ms.

Checks

pnpm run check, pnpm run test (3780 passing), pnpm run finalize:web green.

_{An earlier revision of this PR added a second tool plus reason/force/live-children guardrails and the locking to make those guardrails correct — ~1.3k lines. Those rules didn't apply to archiving a child, so they had no business applying only to archiving yourself; dropping them took the change to ~156 lines of src.}