Rename the wait overlay to FleetMailbox

Wait JSON is a projection of stored WorkerLifecycle plus a per-install
mailbox. Drop leftover resolve/reject methods that no longer write a
second terminal store. Keep the dependency field name fleetRecords so
call-site churn stays a rename of the type and factory.

Author: TheGreatAxios

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 own `fleetRecords`, not every running session in the shared 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.
+- **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`.
 - `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/`)
@@ -288,6 +288,8 @@ Every shipped specialist is a **director package** — a prompt-first `DirectorP
 
 **Session records** (`src/subagent/session-store.ts`): each spawn is retained as an inspectable child session (id, profile, description, brief, status, tool activity, transcript entries). Child events land only in this store — not in the parent chat transcript. Live progress still uses the light `onProgress` channel for the status bar. Completed sessions are capped (`maxCompleted`) so a long chat does not grow without bound.
 
+**Wait mailbox** (`src/subagent/agent-fleet.ts` `FleetMailbox`): per-install overlay over that session store. Wait JSON is a projection of stored lifecycle plus mailbox membership, pin, collected, and optional interrupt override — not a second terminal store. Mailbox `register` pins an uncollected result (honored by prune); past `MAX_FLEET_RECORDS` the oldest never-collected pin is compacted to a tombstone. Operator cancel projects wait status `interrupted`.
+
 **Observe (OpenTUI)**: `shell.ts:enterSubagentObserve` swaps the transcript for a child's stream (live while running, historical when done) without stealing the parent reactor; child events are mapped to stream rows by `src/tui/observe-map.ts`. Esc leaves observe and restores the parent transcript. Parent Esc/stop and `/clear` still call `cancelAll` so live children close (`agent.close`) instead of continuing after the parent stops. The host-injection point that resolves a live session (`onObserveRequest` → `observeSessionFromSubAgents`, `src/tui/runner-host.ts`, picking the newest running child else the most recent session of any status) is triggered by Alt+O (`shell.ts:observeActiveSubagent`) — the command palette action that used to call it is gone along with `src/tui/palette.ts` itself, but the chord replaces it rather than dropping the feature.
 
 Data-only agent plugins (`src/plugins/data-only-agent.ts`) synthesize `agentPlugin.agents[]` from `agents/*.md` or flat `*.md` in the plugin directory, with optional co-located `skills/`. `loadPluginEntry` tries JS entrypoints first, then falls back to this layout (`/plugins` add-by-path supports filesystem completion via `listPathSuggestions`).

src/agent/tools.ts

@@ -42,7 +42,7 @@ import {
   type SubAgentSessionStore,
 } from "../subagent/index.js";
 import {
-  createFleetRecords,
+  createFleetMailbox,
   createSpawnAgentTool,
   createWaitAgentsTool,
   createListAgentsTool,
@@ -329,7 +329,7 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
   const orchestratorTools: AgentTool[] = [];
   if (subAgentsEnabled && args.subAgent !== undefined) {
     const sa = args.subAgent;
-    const fleetRecords = sa.sessions !== undefined ? createFleetRecords(sa.sessions) : undefined;
+    const fleetRecords = sa.sessions !== undefined ? createFleetMailbox(sa.sessions) : undefined;
     orchestratorTools.push(
       createTaskTool({
         cwd,

src/subagent/agent-fleet.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import {
-  createFleetRecords,
+  createFleetMailbox,
   createSpawnAgentTool,
   createWaitAgentsTool,
   createListAgentsTool,
@@ -58,7 +58,7 @@ function makeDeps(
     provider,
     run,
     sessions,
-    fleetRecords: createFleetRecords(sessions),
+    fleetRecords: createFleetMailbox(sessions),
   };
 }
 
@@ -205,8 +205,8 @@ describe("spawn_agent + wait_agents", () => {
   test("reports survive well past the session store's display cap (20) until wait_agents collects them", async () => {
     // DEFAULT_MAX_COMPLETED on SubAgentSessionStore is 20 finished sessions;
     // spawn (and complete) enough workers to blow well past it before any of
-    // them is collected, proving fleetRecords does not depend on the store's
-    // cap.
+    // them is collected, proving the wait mailbox pin keeps reports past the
+    // store's display cap.
     //
     // CL-7007: this test previously asserted (as CL-7001's fix left it) that
     // the store itself had already evicted and released the earliest
@@ -215,8 +215,8 @@ describe("spawn_agent + wait_agents", () => {
     // ticket fixes (resume_agent failed with a bare
     // "not_found" past 20 spawned workers, blaming the caller for nothing).
     // Open retained sessions now have their own cap (`maxRetained`, default
-    // 50), so 25 of them all stay resumable; fleetRecords/wait_agents is
-    // still asserted below as the durable source of truth regardless.
+    // 50), so 25 of them all stay resumable; mailbox pin + wait_agents is
+    // still asserted below as the collect path regardless.
     const COUNT = 25;
     const deps = makeDeps(async () => ({ report: "irrelevant", agentRetained: true }));
     const spawn = createSpawnAgentTool(deps);
@@ -250,7 +250,7 @@ describe("spawn_agent + wait_agents", () => {
   });
 
   // CL-6915: operator cancel aborts the child signal, but run() still returns a
-  // salvage body (partial findings). Dropping that body left fleetRecords
+  // salvage body (partial findings). Dropping that body left the wait mailbox
   // "running" forever so wait_agents never saw the salvage.
   test("cancelled spawn_agent still resolves wait_agents with salvage findings", async () => {
     const deps = makeDeps(async (params) => {
@@ -356,7 +356,7 @@ describe("spawn_agent same-cwd concurrency", () => {
   });
 });
 
-describe("fleetRecords retention cap", () => {
+describe("wait mailbox session tombstone and pin", () => {
   test("many spawned-and-completed workers whose reports are never collected leave memory bounded", async () => {
     const COUNT = MAX_FLEET_RECORDS + 50;
     const deps = makeDeps(async () => ({ report: "x".repeat(1000) }));
@@ -838,7 +838,7 @@ describe("interrupt_agent unblocks wait_agents", () => {
 
   test("soft-interrupt wait collects so a later followup cannot resurrect done", async () => {
     const sessions = createSubAgentSessionStore();
-    const fleetRecords = createFleetRecords(sessions);
+    const fleetRecords = createFleetMailbox(sessions);
     const worker = sessions.start({
       id: "soft-int",
       description: "looping",

src/subagent/agent-fleet.ts

@@ -10,17 +10,17 @@
  *
  * Running state is the session store's `WorkerLifecycle`. wait_agents blocks
  * on that store's `subscribe` raced against a timeout timer, never polling.
- * Wait JSON is a projection of stored lifecycle plus a per-install overlay
- * (`fleetRecords`): membership, pin, collected, and an optional wait-status
- * override. Spawn/resume settlement writes only the session store.
+ * Wait JSON is a projection of stored lifecycle plus a per-install wait
+ * mailbox (`FleetMailbox`): membership, pin, collected, and an optional
+ * wait-status override. Spawn/resume settlement writes only the session store.
  *
  * The store's finished-session retention is a TUI display cap (`maxCompleted`,
  * default 20): `complete()`/`fail()` evict the oldest finished session —
  * report and all — once more than that many have finished. task() never hit
  * this because it awaits its own single result before the tool call returns;
  * here a caller can spawn far more workers than the cap in one turn and only
  * `wait_agents` them later, so an evicted report would otherwise vanish
- * silently. Overlay `register` pins the session (honored by pruneCompleted
+ * silently. Mailbox `register` pins the session (honored by pruneCompleted
  * and pruneRetained) until collect unpins. Heavy payloads are still capped at
  * `MAX_FLEET_RECORDS`: past that, the oldest never-collected pin is compacted
  * to a tombstone (status only, plus a pointer at `read_agent_trace`).
@@ -114,31 +114,19 @@ const RECOVERY_HINT =
 export const MAX_FLEET_RECORDS = 200;
 
 /**
- * Per-install wait overlay. Session lifecycle is the source of wait status
- * unless this overlay forces interrupted or has frozen a collected result.
- * See the module doc for pin/tombstone policy.
+ * Per-install wait mailbox over the session store. Session lifecycle is the
+ * source of wait status unless this overlay forces interrupted or has frozen
+ * a collected result. See the module doc for pin/tombstone policy.
  */
-class FleetRecords {
+class FleetMailbox {
   private readonly records = new Map<string, FleetOverlay>();
-  private readonly listeners = new Set<() => void>();
   private readonly sessions: SubAgentSessionStore;
 
   constructor(sessions: SubAgentSessionStore) {
     this.sessions = sessions;
     sessions?.subscribe(() => this.enforceCap());
   }
 
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  private notify(): void {
-    for (const listener of this.listeners) listener();
-  }
-
   register(id: string): void {
     const existing = this.records.get(id);
     const alreadyPinned =
@@ -148,16 +136,6 @@ class FleetRecords {
     this.enforceCap();
   }
 
-  /**
-   * Leftover dual-write. Settlement writes the session store; commit 3 deletes this.
-   */
-  resolve(_id: string, _report: string): void {}
-
-  /**
-   * Leftover dual-write. Settlement writes the session store; commit 3 deletes this.
-   */
-  reject(_id: string, _error: string): void {}
-
   /**
    * Overlay wait-status override so wait unblocks while the session may still
    * be running (send_input interrupt:true followup, close_agent teardown).
@@ -168,13 +146,11 @@ class FleetRecords {
     if (existing === undefined) return;
     if (existing.collected === true) {
       this.sessions?.wake();
-      this.notify();
       return;
     }
     existing.forceInterrupted = true;
     this.sessions?.wake();
     this.enforceCap();
-    this.notify();
   }
 
   /**
@@ -188,7 +164,6 @@ class FleetRecords {
     if (existing.forceInterrupted !== true) return;
     delete existing.forceInterrupted;
     this.sessions?.wake();
-    this.notify();
   }
 
   ids(): string[] {
@@ -296,9 +271,9 @@ class FleetRecords {
 // One overlay per orchestrator install (shared by its spawn_agent and
 // wait_agents tool instances), not a module singleton — created in
 // createSpawnAgentTool and threaded to createWaitAgentsTool by the caller.
-export type FleetRecordsHandle = FleetRecords;
-export function createFleetRecords(sessions: SubAgentSessionStore): FleetRecordsHandle {
-  return new FleetRecords(sessions);
+export type FleetMailboxHandle = FleetMailbox;
+export function createFleetMailbox(sessions: SubAgentSessionStore): FleetMailboxHandle {
+  return new FleetMailbox(sessions);
 }
 
 const SpawnAgentArgs = type({
@@ -403,7 +378,7 @@ export type AgentFleetDeps = SubAgentSandboxDeps & {
   provider: SubAgentProvider | (() => SubAgentProvider);
   run: (params: RunSubAgentParams) => Promise<RunSubAgentResult>;
   sessions: SubAgentSessionStore;
-  fleetRecords: FleetRecordsHandle;
+  fleetRecords: FleetMailboxHandle;
   /**
    * Session id of the caller that is mounting this spawn_agent. Nested
    * orchestrators pass their own worker id so close_agent can walk the tree.
@@ -833,10 +808,10 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
 
 interface WaitAgentsDeps {
   sessions: SubAgentSessionStore;
-  fleetRecords: FleetRecordsHandle;
+  fleetRecords: FleetMailboxHandle;
 }
 
-function isWaitTerminal(id: string, fleetRecords: FleetRecordsHandle): boolean {
+function isWaitTerminal(id: string, fleetRecords: FleetMailboxHandle): boolean {
   const record = fleetRecords.peek(id);
   return record !== undefined && record.status !== "running";
 }
@@ -850,7 +825,7 @@ function isWaitTerminal(id: string, fleetRecords: FleetRecordsHandle): boolean {
  */
 async function waitForTerminal(
   sessions: SubAgentSessionStore,
-  fleetRecords: FleetRecordsHandle,
+  fleetRecords: FleetMailboxHandle,
   targets: readonly string[],
   timeoutMs: number,
   mode: "any" | "all",