Fix resumed-agent fail teardown and wait pin reuse

fail() of a live persisted agent must invoke the registered close so
close_agent can recover after a resume followup throw. Mailbox register
re-pins on call-id reuse, and a pruned mailbox member is a tombstone
instead of eternal running. Wait/task cancel stays interrupted.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,11 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Changed
+
+- Cancelling a `task` or `wait_agents` worker reports wait status `interrupted`,
+  not `failed`.
+
 ### Fixed
 
 - Codex ChatGPT subscription sessions no longer show a public-rate dollar

docs/ARCHITECTURE.md

@@ -219,7 +219,7 @@ Every director package carries a required `tier: SubagentTier` field (`src/agent
 Enforcement is runtime code at the existing tool-mount point, not prompt wording — this is the fix for four prior mechanisms (`writePaths`, `report.requiredSections`, a `--config` comment, the thrash matcher) that were documented-as-enforced while enforcing nothing:
 
 - **Mount-time gate — live today, and fails closed.** `task-tool.ts` resolves the caller's tier at dispatch time — a closed director's `DirectorPackage.tier` — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing fleet verbs, treating a **missing** `orchestratorTier` as `"leaf"` — deny, not skip. This is the case that matters most: a project-local or plugin `AgentProfile` with `orchestrator: true` is outside the closed director set and is **not** trusted with fleet verbs just because `orchestrator: true` is set — there is no profile-level opt-in today, so the mount always throws `FleetAuthorityError` for a profile-sourced orchestrator. `FLEET_VERBS` in `authority.ts` names the live verbs (`task`, `spawn_agent`, `wait_agents`, `list_agents`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `read_agent_trace`, `search_agents`) so every mount site inherits the same gate. `list_agents` is the non-blocking mailbox-scoped list of this install's own `spawn_agent` workers (same scope as `wait_agents`); nested orchestrators may mount it. Fleet discovery (`search_agents`) remains Tier 1 only.
-- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`, `close_agent`, and `resume_agent`. Nested mounts pass `{actorId, tier, getNodes}` from `run.ts`; a missing `actorId` fails closed. Tier-1 primary omits authority and stays unrestricted. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's per-install wait mailbox over the shared session store, not every running session. Wait JSON is a projection of stored lifecycle plus mailbox membership/pin/collected/interrupt override — not a second terminal store. `list_agents` reports that same mailbox without blocking. `interrupt_agent` / `send_input` with `interrupt:true` terminalize the wait mailbox immediately; the soft-interrupt wait path collects so a later followup cannot resurrect an already-observed interrupt. `close_agent` also terminalizes the wait mailbox before teardown. Operator cancel (`cancel` / `cancelAll`) projects wait status `interrupted`.
+- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`, `close_agent`, and `resume_agent`. Nested mounts pass `{actorId, tier, getNodes}` from `run.ts`; a missing `actorId` fails closed. Tier-1 primary omits authority and stays unrestricted. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's per-install wait mailbox over the shared session store, not every running session. Wait JSON is a projection of stored lifecycle plus mailbox membership/pin/collected/interrupt override — not a second terminal store. `list_agents` reports that same mailbox without blocking. `interrupt_agent` stamps the session `interrupted`; wait JSON projects that stored lifecycle and does not write a mailbox overlay. `send_input` with `interrupt:true` sets the mailbox interrupt overlay so wait unblocks while a queued followup may already be running. The wait path collects a terminal status so a later followup cannot resurrect an already-observed interrupt. `close_agent` terminalizes the wait mailbox before teardown. Operator cancel (`cancel` / `cancelAll`) projects wait status `interrupted`.
 - `task()` remains the deprecated fused spawn+wait fallback. `spawn_agent` + `wait_agents` is the supported parallel path. The tier check still gates which packages may mount any fleet verb.
 
 #### Closed director fleet (`src/agent/directors/`)

src/subagent/agent-fleet.test.ts

@@ -415,6 +415,59 @@ describe("wait mailbox session tombstone and pin", () => {
     expect(results[0]!.report).toBeUndefined();
     expect(results[0]!.hint).toContain("read_agent_trace");
   });
+
+  test("spawn_agent call.id reuse still pins the new session", async () => {
+    let t = 0;
+    const sessions = createSubAgentSessionStore({
+      maxCompleted: 1,
+      now: () => ++t,
+    });
+    const deps = makeDeps(async () => ({ report: "ok" }), { sessions });
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({ sessions, fleetRecords: deps.fleetRecords });
+    if (spawn.kind !== "full") throw new Error("expected full tool");
+    const args = { description: "job", prompt: "do it", intent: "explore" };
+    const signal = new AbortController().signal;
+
+    await spawn.handler({ id: "reuse-id", name: "spawn_agent", arguments: args }, signal);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    await spawn.handler({ id: "reuse-id", name: "spawn_agent", arguments: args }, signal);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    const extra1 = sessions.start({ description: "flood-1", agentId: "a", brief: "b" });
+    sessions.complete(extra1.id, "flood-1");
+    const extra2 = sessions.start({ description: "flood-2", agentId: "a", brief: "b" });
+    sessions.complete(extra2.id, "flood-2");
+
+    expect(sessions.get("reuse-id")).toBeDefined();
+    const waited = await callTool(wait, { targets: ["reuse-id"], timeout_ms: 1000 });
+    expect(waited.timed_out).toBe(false);
+    const results = waited.results as { status: string }[];
+    expect(results[0]!.status).toBe("done");
+  });
+
+  test("wait on a pruned mailbox member is tombstone not eternal running", () => {
+    let t = 0;
+    const sessions = createSubAgentSessionStore({
+      maxCompleted: 1,
+      now: () => ++t,
+    });
+    const mailbox = createFleetMailbox(sessions);
+    sessions.start({ id: "reuse", description: "old", agentId: "a", brief: "b" });
+    mailbox.register("reuse");
+    sessions.complete("reuse", "old report");
+    sessions.start({ id: "reuse", description: "new", agentId: "a", brief: "b" });
+    sessions.complete("reuse", "new report");
+    const extra = sessions.start({ description: "other", agentId: "a", brief: "b" });
+    sessions.complete(extra.id, "other");
+    const extra2 = sessions.start({ description: "prune", agentId: "a", brief: "b" });
+    sessions.complete(extra2.id, "prune");
+    expect(sessions.get("reuse")).toBeUndefined();
+    const snap = mailbox.peek("reuse");
+    expect(snap?.status).not.toBe("running");
+    expect(snap?.tombstoned).toBe(true);
+    expect(snap?.hint).toContain("read_agent_trace");
+  });
 });
 
 describe("spawn_agent parentage", () => {

src/subagent/agent-fleet.ts

@@ -129,10 +129,11 @@ class FleetMailbox {
 
   register(id: string): void {
     const existing = this.records.get(id);
-    const alreadyPinned =
-      existing !== undefined && existing.collected !== true && existing.pinHeld === true;
+    // start() drops pinCounts on call-id reuse. Re-pin whenever the overlay
+    // thought it still held a pin, so wait cannot desync against an empty map.
+    if (existing?.pinHeld === true) this.sessions.unpin(id);
     this.records.set(id, { pinHeld: true });
-    if (!alreadyPinned) this.sessions?.pin(id);
+    this.sessions.pin(id);
     this.enforceCap();
   }
 
@@ -212,16 +213,29 @@ class FleetMailbox {
   private projectedStatus(id: string, overlay: FleetOverlay): WaitJSONStatus {
     if (overlay.frozenStatus !== undefined) return overlay.frozenStatus;
     if (overlay.forceInterrupted === true) return "interrupted";
-    return this.sessionWaitStatus(id) ?? "running";
+    return this.sessionWaitStatus(id) ?? "interrupted";
   }
 
   snapshot(id: string): FleetRecord {
     const overlay = this.records.get(id);
     if (overlay === undefined) {
       return { status: "running" };
     }
+    const session = this.sessions.get(id);
+    if (
+      session === undefined &&
+      overlay.tombstoned !== true &&
+      overlay.frozenStatus === undefined
+    ) {
+      overlay.tombstoned = true;
+      overlay.hint = RECOVERY_HINT;
+      overlay.frozenStatus = "interrupted";
+      if (overlay.pinHeld === true) {
+        overlay.pinHeld = false;
+        this.sessions.unpin(id);
+      }
+    }
     const status = this.projectedStatus(id, overlay);
-    const session = this.sessions?.get(id);
     const sessionWait = this.sessionWaitStatus(id);
     const payload =
       overlay.tombstoned !== true && session !== undefined && sessionWait === status

src/subagent/lifecycle-tools.test.ts

@@ -132,9 +132,9 @@ describe("resume_agent", () => {
 
     finish("done, history now 2 turns");
     await new Promise((resolve) => setTimeout(resolve, 0));
-    expect(sessions.get(retained.id)?.lifecycleStatus).toBe("completed");
+    expect(sessions.get(retained.id)?.lifecycleStatus).toBe("interrupted");
     expect(sessions.get(retained.id)?.id).toBe(retained.id);
-    expect(sessions.get(retained.id)?.report).toBe("done, history now 2 turns");
+    expect(sessions.get(retained.id)?.report).toBe("## Summary\nDone.");
 
     if (resumeAgent.kind !== "full") throw new Error("expected full tool");
     const rejected = await resumeAgent.handler(
@@ -298,6 +298,40 @@ describe("resume_agent", () => {
     expect(results[0]!.status).toBe("done");
     expect(results[0]!.report).toBe("second report");
   });
+
+  test("resume followup rejection invokes close; close_agent tears down leftover", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetMailbox(sessions);
+    const worker = sessions.start({
+      description: "worker",
+      agentId: "a",
+      brief: "b",
+      retained: true,
+    });
+    let closeCalls = 0;
+    sessions.registerClose(worker.id, async () => {
+      closeCalls++;
+    });
+    sessions.registerFollowup(worker.id, async () => {
+      throw new Error("send failed");
+    });
+    sessions.complete(worker.id, "first report");
+
+    const resumeAgent = createResumeAgentTool({ sessions, fleetRecords });
+    const closeAgent = createCloseAgentTool({ sessions, fleetRecords });
+    const resumed = await callTool(resumeAgent, { target: worker.id, message: "again" });
+    expect(resumed.status).toBe("running");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(closeCalls).toBe(1);
+    expect(sessions.get(worker.id)?.lifecycle.state).toBe("failed");
+
+    const started = Date.now();
+    const closed = await callTool(closeAgent, { target: worker.id });
+    expect(Date.now() - started).toBeLessThan(1000);
+    expect(closed.status).toBe("shutdown");
+    expect(sessions.get(worker.id)?.lifecycle.state).toBe("failed");
+    expect(closeCalls).toBe(1);
+  });
 });
 
 describe("interrupt_agent", () => {

src/subagent/lifecycle-tools.ts

@@ -121,7 +121,7 @@ export type CloseAgentToolDeps = LifecycleToolDeps & {
   fleetRecords: FleetMailboxHandle;
 };
 
-/** interrupt_agent always terminalizes the wait mailbox — no silent skip. */
+/** interrupt_agent stamps session interrupted; wait JSON projects that lifecycle. */
 export type InterruptAgentToolDeps = LifecycleToolDeps & {
   fleetRecords: FleetMailboxHandle;
 };

src/subagent/session-store.test.ts

@@ -365,8 +365,9 @@ describe("CL-6943 reusable worker sessions", () => {
 
     finish("later");
     await new Promise((resolve) => setTimeout(resolve, 0));
-    expect(store.get(session.id)?.status).toBe("done");
-    expect(store.get(session.id)?.lifecycleStatus).toBe("completed");
+    expect(store.get(session.id)?.status).toBe("running");
+    expect(store.get(session.id)?.lifecycleStatus).toBe("interrupted");
+    expect(store.get(session.id)?.report).toBe("## Summary\nDone.");
   });
 
   test("rejected followup restores strip status so interrupt_agent fails closed", async () => {
@@ -698,9 +699,9 @@ describe("interrupt stamps finishedAt once", () => {
     t = 5000;
     finish("later");
     await new Promise((resolve) => setTimeout(resolve, 0));
-    expect(store.get(session.id)?.status).toBe("done");
-    expect(store.get(session.id)?.lifecycleStatus).toBe("completed");
-    expect(store.get(session.id)?.finishedAt).toBe(5000);
+    expect(store.get(session.id)?.status).toBe("running");
+    expect(store.get(session.id)?.lifecycleStatus).toBe("interrupted");
+    expect(store.get(session.id)?.finishedAt).toBe(4000);
   });
 
   test("a follow-up turn keeps the lane live past the linger window until it completes", async () => {
@@ -756,6 +757,54 @@ describe("interrupt stamps finishedAt once", () => {
 });
 
 describe("CL-7269 one stored worker lifecycle", () => {
+  test("complete() after interrupt_agent does not overwrite interrupted", () => {
+    const store = createSubAgentSessionStore();
+    const session = store.start({ description: "d", agentId: "a", brief: "b", retained: true });
+    store.markRunning(session.id);
+    store.registerInterrupt(session.id, () => {});
+    expect(store.interruptOne(session.id).ok).toBe(true);
+    store.complete(session.id, "late original send");
+    const after = store.get(session.id);
+    expect(after?.lifecycle.state).toBe("interrupted");
+    expect(after?.lifecycleStatus).toBe("interrupted");
+    expect(after?.report).toBeUndefined();
+  });
+
+  test("fail() of a live persisted agent invokes the registered close", async () => {
+    const store = createSubAgentSessionStore();
+    const session = store.start({ description: "d", agentId: "a", brief: "b", retained: true });
+    store.markRunning(session.id);
+    let closeCalls = 0;
+    store.registerClose(session.id, async () => {
+      closeCalls++;
+    });
+    store.fail(session.id, "send failed");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(closeCalls).toBe(1);
+    expect(store.get(session.id)?.lifecycle.state).toBe("failed");
+    const started = Date.now();
+    const status = await store.closeOne(session.id, 5000);
+    expect(Date.now() - started).toBeLessThan(200);
+    expect(status).toBe("shutdown");
+    expect(store.get(session.id)?.lifecycle.state).toBe("failed");
+    expect(closeCalls).toBe(1);
+  });
+
+  test("closeOne still tears down a leftover close handle after fail()", async () => {
+    const store = createSubAgentSessionStore();
+    const session = store.start({ description: "d", agentId: "a", brief: "b", retained: true });
+    store.markRunning(session.id);
+    let closeCalls = 0;
+    store.fail(session.id, "send failed");
+    store.registerClose(session.id, async () => {
+      closeCalls++;
+    });
+    const status = await store.closeOne(session.id, 5000);
+    expect(status).toBe("shutdown");
+    expect(closeCalls).toBe(1);
+    expect(store.get(session.id)?.lifecycle.state).toBe("failed");
+  });
+
   test("fail() stores failed, projects strip failed and verb shutdown", () => {
     const store = createSubAgentSessionStore();
     const session = store.start({ description: "d", agentId: "a", brief: "b" });