Gate addressing fleet verbs with subtree authority

Nested interrupt/close/resume/followup now share send_input's
assertCanTargetAgent check and fail closed without an actorId.
Soft-interrupt wait_agents collects so a later followup cannot
resurrect an already-observed interrupt as done.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -219,8 +219,8 @@ 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`, `interrupt_agent`, `close_agent`, `resume_agent`, `followup_task`, `read_agent_trace`, `search_agents`) plus reserved names (`list_agents`, `send_input`) so a later mount site inherits the same gate.
-- **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. `read_agent_trace` is a production call site. `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 own `fleetRecords`, not every running session in the shared store. `interrupt_agent` terminalizes the wait mailbox immediately.
+- **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`, `followup_task`, `read_agent_trace`, `search_agents`) so every mount site inherits the same gate.
+- **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`, `resume_agent`, and `followup_task`. 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 own `fleetRecords`, not every running session in the shared store. `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.
 - `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

@@ -643,6 +643,35 @@ describe("interrupt_agent unblocks wait_agents", () => {
     expect(results[0]!.status).toBe("interrupted");
     followupGate.resolve("later");
   });
+
+  test("soft-interrupt wait collects so a later followup cannot resurrect done", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetRecords();
+    const worker = sessions.start({
+      id: "soft-int",
+      description: "looping",
+      agentId: "explorer",
+      brief: "b",
+      retained: true,
+    });
+    sessions.markRunning(worker.id);
+    // Running fleet record + soft-interrupted session (lifecycle only) —
+    // the wait soft path must interrupt+take before returning.
+    fleetRecords.register(worker.id);
+    sessions.registerInterrupt(worker.id, () => {});
+    sessions.interruptOne(worker.id);
+
+    const wait = createWaitAgentsTool({ sessions, fleetRecords });
+    const waited = await callTool(wait, { targets: [worker.id], timeout_ms: 1000 });
+    expect(waited.timed_out).toBe(false);
+    const results = waited.results as { status: string }[];
+    expect(results[0]!.status).toBe("interrupted");
+    expect(fleetRecords.peek(worker.id)?.collected).toBe(true);
+
+    fleetRecords.completeAfterInterrupt(worker.id, "resurrected reply");
+    expect(fleetRecords.peek(worker.id)?.status).toBe("interrupted");
+    expect(fleetRecords.peek(worker.id)?.collected).toBe(true);
+  });
 });
 
 describe("list_agents", () => {

src/subagent/agent-fleet.ts

@@ -715,10 +715,18 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
         }
         const session = deps.sessions.get(id);
         if (isSoftInterrupted(session)) {
+          // Match the mailbox to what we report, then collect so a later
+          // completeAfterInterrupt cannot resurrect this wait as "done".
+          deps.fleetRecords.interrupt(id);
+          const taken = deps.fleetRecords.take(id);
           return {
             agent_id: id,
             status: "interrupted" as const,
-            ...(session.report !== undefined ? { report: session.report } : {}),
+            ...(taken?.report !== undefined
+              ? { report: taken.report }
+              : session.report !== undefined
+                ? { report: session.report }
+                : {}),
           };
         }
         if (record === undefined) {

src/subagent/authority.ts

@@ -106,20 +106,15 @@ function isDescendant(
 }
 
 /**
- * SEAM, NOT YET A LIVE GATE: this function has no production call site today.
- * No verb in this codebase currently lets one live agent target another
- * (`task` only spawns; it never addresses an existing session), so the
- * subtree rule below is exercised only by authority.test.ts — it is not
- * enforced at runtime yet. It exists now so future verbs that make one
- * agent addressable by another can call it from day one instead of
- * inventing their own check. Until one of those wires a call site here, do
- * not describe this rule as enforced; only assertTierMayMountFleetVerb is.
- *
  * Authority rule (root owns its tree; a child manages only its own
  * descendants): throws unless `actor` is Tier 1, or `targetId` is `actor.id`
  * itself, or a descendant of `actor.id` in `nodes`. A Tier 3 leaf holds no
  * fleet verbs at all and can never reach this check with a real call, so it
  * always fails closed here too.
+ *
+ * Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`,
+ * `close_agent`, `resume_agent`, and `followup_task` (nested mounts pass
+ * authority from run.ts; Tier-1 primary omits it and stays unrestricted).
  */
 export function assertCanTargetAgent(
   actor: { readonly id: string; readonly tier: SubagentTier },

src/subagent/lifecycle-tools.test.ts

@@ -387,4 +387,169 @@ describe("send_input", () => {
     );
     expect(denied.isError).toBe(true);
   });
+
+  test("fails closed when nested authority has no actorId", async () => {
+    const sessions = createSubAgentSessionStore();
+    const worker = sessions.start({
+      id: "worker",
+      description: "worker",
+      agentId: "a",
+      brief: "b",
+    });
+    sessions.markRunning(worker.id);
+    sessions.registerDeliver(worker.id, () => {});
+    const sendInput = createSendInputTool({
+      sessions,
+      authority: {
+        actorId: undefined,
+        tier: "nested-orchestrator",
+        getNodes: () => sessions.list(),
+      },
+    });
+    if (sendInput.kind !== "full") throw new Error("expected full tool");
+    const denied = await sendInput.handler(
+      { id: "no-actor", name: "send_input", arguments: { target: worker.id, message: "x" } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+    expect(String(denied.content)).toContain("no resolvable session");
+  });
+});
+
+describe("nested lifecycle authority", () => {
+  function nestAuthority(sessions: ReturnType<typeof createSubAgentSessionStore>, actorId: string) {
+    return {
+      actorId,
+      tier: "nested-orchestrator" as const,
+      getNodes: () => sessions.list(),
+    };
+  }
+
+  test("interrupt_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+    });
+    const sibling = sessions.start({ id: "sibling", description: "s", agentId: "a", brief: "b" });
+    for (const s of [child, sibling]) {
+      sessions.markRunning(s.id);
+      sessions.registerInterrupt(s.id, () => {});
+    }
+    const interrupt = createInterruptAgentTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(interrupt, { target: child.id })).status).toBe("interrupted");
+    if (interrupt.kind !== "full") throw new Error("expected full tool");
+    const denied = await interrupt.handler(
+      { id: "d", name: "interrupt_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
+
+  test("close_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+    });
+    const sibling = sessions.start({ id: "sibling", description: "s", agentId: "a", brief: "b" });
+    for (const s of [child, sibling]) sessions.registerClose(s.id, async () => {});
+    const close = createCloseAgentTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(close, { target: child.id })).status).toBe("shutdown");
+    if (close.kind !== "full") throw new Error("expected full tool");
+    const denied = await close.handler(
+      { id: "d", name: "close_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+    expect(sessions.get(sibling.id)?.lifecycleStatus).not.toBe("shutdown");
+  });
+
+  test("followup_task denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+      retained: true,
+    });
+    const sibling = sessions.start({
+      id: "sibling",
+      description: "s",
+      agentId: "a",
+      brief: "b",
+      retained: true,
+    });
+    for (const s of [child, sibling]) {
+      sessions.complete(s.id, "done");
+      sessions.registerFollowup(s.id, async () => "reply");
+    }
+    const followup = createFollowupTaskTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(followup, { target: child.id, message: "more" })).status).toBe(
+      "completed",
+    );
+    if (followup.kind !== "full") throw new Error("expected full tool");
+    const denied = await followup.handler(
+      {
+        id: "d",
+        name: "followup_task",
+        arguments: { target: sibling.id, message: "more" },
+      },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
+
+  test("resume_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+      retained: true,
+    });
+    const sibling = sessions.start({
+      id: "sibling",
+      description: "s",
+      agentId: "a",
+      brief: "b",
+      retained: true,
+    });
+    sessions.complete(child.id, "done");
+    sessions.complete(sibling.id, "done");
+    const resume = createResumeAgentTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(resume, { target: child.id })).status).toBe("running");
+    if (resume.kind !== "full") throw new Error("expected full tool");
+    const denied = await resume.handler(
+      { id: "d", name: "resume_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
 });