Fire one occupancy shot after a missed fleet-dry edge

A last-lane terminal while the parent is still processing dropped the wentDry edge, then settle idled with open tasks. Occupancy now latches that edge and drives once from settle. Send failure no longer consumes mailbox reports.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -112,7 +112,10 @@ In TUI chat mode there is no completion gate — the session stays open across t
 
 Two directors, selected by role:
 
-- **ChatDirector** (interactive, `src/agent/director.ts`) — Extends `DefaultDirector` with task list tracking, workflow nudges, LSP auto-activation, and multi-turn chat semantics. It never terminates the session: operator declines are surfaced as replies and the reactor stays alive for the next message. Yielding while a live fleet is running is allowed (idle-with-fleet); the open-task nudge does not rewrite that wait/reply. When the fleet goes dry with tasks still todo/doing, the TUI runtime re-enters the parent with collected worker reports rather than settling idle. Auto mode is toggled by CLI flags (`--auto` / `--no-auto`); there is currently no in-session key to toggle it (default on; constrained envelope — workspace writes and unconstrained shell auto-allow; installs, recursive rm, force/uncontained worktree changes, sensitive-path and opaque-wrapper shell still ask; contained non-force `git worktree add`/`remove`/`prune` and `list` auto-allow; shell file-mutation denied). It is not a separate edit/plan mode.
+- **ChatDirector** (interactive, `src/agent/director.ts`) — Extends `DefaultDirector` with task list tracking, workflow nudges, LSP auto-activation, and multi-turn chat semantics. It never terminates the session: operator declines are surfaced as replies and the reactor stays alive for the next message. Yielding while a live fleet is running is allowed (idle-with-fleet); the open-task nudge does not rewrite that wait/reply. When the fleet goes dry with tasks still todo/doing, the TUI runtime re-enters the parent with collected worker reports rather than settling idle.
+
+  Auto mode is toggled by CLI flags (`--auto` / `--no-auto`); there is currently no in-session key to toggle it (default on; constrained envelope — workspace writes and unconstrained shell auto-allow; installs, recursive rm, force/uncontained worktree changes, sensitive-path and opaque-wrapper shell still ask; contained non-force `git worktree add`/`remove`/`prune` and `list` auto-allow; shell file-mutation denied). It is not a separate edit/plan mode.
+
 - **SubAgentDirector** (delegated work, `src/subagent/index.ts`) — Drives a dispatched worker until a turn arrives with no tool calls, then replies with the final assistant text and ends the run. A tool-less turn **after tools** completes only with the four-heading envelope (Summary, Findings, Blockers, Paths); a missing envelope nudges once (**incomplete-report**) and a second tool-less turn still without the envelope salvages as **incomplete-report-stop**. Explore/read-only workers that used tools then replied with findings remain normal completes; `requireEvidence` (off by default, set per director) additionally requires at least one read before a tool-less spawn-only reply can complete. Reads done through `run_shell` count as evidence too — `src/subagent/shell-evidence.ts` classifies shell reads (`cat`, `grep`, `sed` without `-i`, …) over the same subject expansion the auto-shell policy uses — but there is no corresponding shell-write evidence or file-write requirement: a run that never touches a file still completes normally once it replies with the envelope. There is no turn budget. Operator/parent cancel after any progress returns a **cancelled** salvage report (partial findings + tool activity) instead of a bare cancel string; cancel before progress still surfaces as cancelled-by-operator. There is no repetition/no-progress/never-acted/never-edited hard stop and no fingerprint-based re-dispatch block — a genuinely stuck worker runs until it completes, stalls, hits an opt-in wall-clock deadline, or is cancelled.
   `spawn_agent` starts each worker and records it in the caller's fleet mailbox; `wait_agents` collects terminal reports from that mailbox. Wait JSON includes `stop_reason` from the session when present so a salvage that is wait-`done` is not mistaken for a clean complete, and so parent-initiated interrupt (`interrupted`) is not mistaken for operator-cancel (`cancelled`). Deadline salvage prepends an advisory parent hint suggesting continuation plus a longer deadline if more wall-clock time is warranted. Failed and incomplete-report salvage tell the parent to diagnose from the report or error and MAY spawn one successor with a changed brief. A parent-initiated interrupt is a resumable pause: wait unblocks with `stop_reason: interrupted` (often while the session is still running and has no report); the parent should `resume_agent` or re-wait, and must not spawn a successor against a still-live worker. Successor only if that session is no longer resumable. Operator-cancelled salvage asks the parent to synthesize Findings and Paths and wait for the operator instead of auto-starting another specialist. Identical re-dispatch of the same brief stays refused at the prompt / spawn-handoff layer; there is no fingerprint-based re-dispatch hard-block. Deadline hints are advisory only — an identical re-dispatch is still admitted at runtime. Parent hints are prepended on salvage reports returned to the parent. The runtime does not auto-spawn successors.
 

src/agent/directors/skywalker/package.ts

@@ -16,7 +16,7 @@ You do not do the specialists' jobs by default. For tiny bounded product edits,
 
 Do not run long-blocking jobs on the parent (evals, full test suites, long installs, long-running implementation). Dispatch intern (mechanical shell), tester (suite / repro), or builder (substantial code). Path tools (write_file/edit_file/delete_file) are the DIY surface; shell file-writes stay denied.
 
-Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and what happens next before you block. Prefer ending that turn (or calling wait_agents with a short timeout_ms) so Enter can land; do not immediately fuse into a long wait_agents right after spawn. wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). list_agents shows that same fleet without blocking. Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents holds those steers. A bare spawn_agent does not. When the fleet goes dry the runtime re-enters with collected reports; do not tight-loop wait_agents.
+Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and what happens next before you block. Prefer ending that turn (or calling wait_agents with a short timeout_ms) so Enter can land; do not immediately fuse into a long wait_agents right after spawn. wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). list_agents shows that same fleet without blocking. Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents holds those steers. A bare spawn_agent does not. When the fleet goes dry the runtime re-enters with collected reports.
 
 # Operator updates (mandatory while fleet is live)
 

src/session/runtime-assembly.ts

@@ -382,8 +382,10 @@ export function buildCompactionContinuationMessage(): InboundMessage {
 
 /**
  * System-originated inbound that re-enters the parent after the fleet goes dry
- * with todo/doing tasks still open. No OPERATOR_ORIGINATED_FLAG — this is not
- * an operator prompt and must not reset the tool-only loop-protection backstop.
+ * with todo/doing tasks still open. Not operator input, so no
+ * OPERATOR_ORIGINATED_FLAG. ChatDirector still resets idle and tool-only
+ * nudge counters on any message.received — occupancy therefore fires one
+ * deferred shot per dry edge rather than re-driving on every settle.
  */
 export function buildFleetDryContinuationMessage(text: string): InboundMessage {
   return {

src/subagent/agent-fleet.ts

@@ -94,6 +94,7 @@ import { formatSubAgentSpawnAuthFailureMessage } from "./inference-auth-failure.
 import { isResolvedProviderFailureError } from "../inference-error-message.js";
 import { isSubAgentCancelError } from "./dispose.js";
 import { createInterventionLog, type InterventionSink } from "./intervention-log.js";
+import { takeAndProjectMailboxRecord } from "./fleet-dry-drive.js";
 
 const log = getLogger([LOG_NAMESPACE_ROOT, "subagent", "agent-fleet"]);
 
@@ -1398,20 +1399,14 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
         if (isLiveWaitStatus(record.status)) {
           return { agent_id: id, status: record.status };
         }
-        const taken = deps.fleetRecords.take(id) ?? record;
+        const projected = takeAndProjectMailboxRecord(deps.fleetRecords, id);
+        if (projected === undefined) {
+          return { agent_id: id, status: "unknown" as const };
+        }
         return {
-          agent_id: id,
-          status: taken.status,
-          ...(taken.question !== undefined ? { question: taken.question } : {}),
-          ...(taken.questionId !== undefined ? { question_id: taken.questionId } : {}),
-          ...(taken.description !== undefined ? { description: taken.description } : {}),
-          ...(taken.status !== "failed" && taken.report !== undefined
-            ? { report: taken.report }
-            : {}),
-          ...(taken.error !== undefined ? { error: taken.error } : {}),
-          ...(taken.stopReason !== undefined ? { stop_reason: taken.stopReason } : {}),
-          ...(taken.providerFailure === true ? { provider_failure: true } : {}),
-          ...(taken.hint !== undefined ? { hint: taken.hint } : {}),
+          ...projected,
+          ...(record.question !== undefined ? { question: record.question } : {}),
+          ...(record.questionId !== undefined ? { question_id: record.questionId } : {}),
         };
       });
 

src/subagent/fleet-dry-drive.test.ts

@@ -61,6 +61,45 @@ describe("shouldDriveOpenTasks", () => {
       }),
     ).toBe(false);
   });
+
+  test("deferred dry edge fires once when still dry+open and parent is idle", () => {
+    expect(
+      shouldDriveOpenTasks({
+        previousRunning: 0,
+        running: 0,
+        hasOpenTasks: true,
+        parentProcessing: false,
+        deferredDryEdge: true,
+      }),
+    ).toBe(true);
+    expect(
+      shouldDriveOpenTasks({
+        previousRunning: 0,
+        running: 0,
+        hasOpenTasks: true,
+        parentProcessing: true,
+        deferredDryEdge: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldDriveOpenTasks({
+        previousRunning: 0,
+        running: 0,
+        hasOpenTasks: false,
+        parentProcessing: false,
+        deferredDryEdge: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldDriveOpenTasks({
+        previousRunning: 0,
+        running: 1,
+        hasOpenTasks: true,
+        parentProcessing: false,
+        deferredDryEdge: true,
+      }),
+    ).toBe(false);
+  });
 });
 
 describe("buildFleetDryContinuationPrompt", () => {
@@ -264,4 +303,69 @@ describe("driveOpenTasksAfterFleetDry", () => {
       }),
     ).toBe(false);
   });
+
+  test("deferred dry edge after parentProcessing still collects and sends", () => {
+    const records = new Map<string, FleetDryMailboxRecord>([
+      ["w1", { status: "done", report: "ok" }],
+    ]);
+    const mailbox: FleetDryMailbox = {
+      ids: () => [...records.keys()],
+      peek: (id) => records.get(id),
+      take: (id) => {
+        const existing = records.get(id);
+        if (existing === undefined) return undefined;
+        const taken = { ...existing, collected: true };
+        records.set(id, taken);
+        return taken;
+      },
+    };
+    const sent: string[] = [];
+    const driven = driveOpenTasksAfterFleetDry({
+      previousRunning: 0,
+      running: 0,
+      deferredDryEdge: true,
+      openTasks: [openTask],
+      parentProcessing: false,
+      mailbox,
+      lanes: [],
+      beginSystemContinuation: () => undefined,
+      send: (prompt) => {
+        sent.push(prompt);
+      },
+    });
+    expect(driven).toBe(true);
+    expect(sent[0]).toContain("w1");
+    expect(records.get("w1")?.collected).toBe(true);
+  });
+
+  test("send failure after take leaves reports waitable", () => {
+    const records = new Map<string, FleetDryMailboxRecord>([
+      ["w1", { status: "done", report: "ok" }],
+    ]);
+    const mailbox: FleetDryMailbox = {
+      ids: () => [...records.keys()],
+      peek: (id) => records.get(id),
+      take: (id) => {
+        const existing = records.get(id);
+        if (existing === undefined) return undefined;
+        const taken = { ...existing, collected: true };
+        records.set(id, taken);
+        return taken;
+      },
+    };
+    const driven = driveOpenTasksAfterFleetDry({
+      previousRunning: 1,
+      running: 0,
+      openTasks: [openTask],
+      parentProcessing: false,
+      mailbox,
+      lanes: [],
+      beginSystemContinuation: () => undefined,
+      send: () => {
+        throw new Error("send failed");
+      },
+    });
+    expect(driven).toBe(false);
+    expect(records.get("w1")?.collected).not.toBe(true);
+  });
 });

src/subagent/fleet-dry-drive.ts

@@ -1,7 +1,7 @@
 /**
  * Drive the parent back into a turn when the live fleet goes dry while
- * todo/doing tasks remain. Pure: the TUI subscriber decides when to call,
- * this module decides whether to drive and what to send.
+ * todo/doing tasks remain. Pure: occupancy (settleRunToIdle) decides when
+ * to call; this module decides whether to drive and what to send.
  */
 
 import { hasActiveTasks, type Task } from "../agent/tasks.js";
@@ -50,9 +50,11 @@ export function shouldDriveOpenTasks(input: {
   running: number;
   hasOpenTasks: boolean;
   parentProcessing: boolean;
+  deferredDryEdge?: boolean;
 }): boolean {
   const wentDry = input.running === 0 && input.previousRunning > 0;
-  return wentDry && input.hasOpenTasks && !input.parentProcessing;
+  const dryEdge = wentDry || input.deferredDryEdge === true;
+  return dryEdge && input.running === 0 && input.hasOpenTasks && !input.parentProcessing;
 }
 
 function clipField(text: string | undefined): string | undefined {
@@ -61,9 +63,56 @@ function clipField(text: string | undefined): string | undefined {
   return `${text.slice(0, FLEET_DRY_REPORT_CHARS - 1).trimEnd()}…`;
 }
 
+export function projectMailboxRecord(
+  id: string,
+  taken: FleetDryMailboxRecord,
+  lane?: FleetDryLane,
+): CollectedWorkerReport {
+  const report = taken.report ?? lane?.report;
+  const error = taken.error ?? lane?.error;
+  const description = taken.description ?? lane?.description;
+  return {
+    agent_id: id,
+    status: taken.status,
+    ...(description !== undefined && description.length > 0 ? { description } : {}),
+    ...(taken.status !== "failed" && report !== undefined ? { report } : {}),
+    ...(error !== undefined ? { error } : {}),
+    ...(taken.hint !== undefined ? { hint: taken.hint } : {}),
+    ...(taken.providerFailure === true ? { provider_failure: true } : {}),
+  };
+}
+
+/**
+ * Mailbox take plus the wait_agents/fleet-dry projection. Live statuses are
+ * not collected. Callers that need question fields (wait_agents) spread them
+ * from the pre-take peek.
+ */
+export function takeAndProjectMailboxRecord(
+  mailbox: FleetDryMailbox,
+  id: string,
+  lane?: FleetDryLane,
+): CollectedWorkerReport | undefined {
+  const peeked = mailbox.peek(id);
+  if (peeked === undefined) return undefined;
+  if (isLiveWaitStatus(peeked.status)) return undefined;
+  const taken = mailbox.take(id) ?? peeked;
+  return projectMailboxRecord(id, taken, lane);
+}
+
+function clipCollectedReport(report: CollectedWorkerReport): CollectedWorkerReport {
+  const clippedReport = clipField(report.report);
+  const clippedError = clipField(report.error);
+  return {
+    ...report,
+    ...(clippedReport !== undefined ? { report: clippedReport } : {}),
+    ...(clippedError !== undefined ? { error: clippedError } : {}),
+  };
+}
+
 export function collectUncollectedTerminals(
   mailbox: FleetDryMailbox | undefined,
   lanes: readonly FleetDryLane[],
+  consume = true,
 ): CollectedWorkerReport[] {
   if (mailbox === undefined) return [];
   const byId = new Map(lanes.map((lane) => [lane.id, lane]));
@@ -73,20 +122,11 @@ export function collectUncollectedTerminals(
     if (peeked === undefined) continue;
     if (peeked.collected === true) continue;
     if (isLiveWaitStatus(peeked.status)) continue;
-    const taken = mailbox.take(id) ?? peeked;
-    const lane = byId.get(id);
-    const report = clipField(taken.report ?? lane?.report);
-    const error = clipField(taken.error ?? lane?.error);
-    const description = taken.description ?? lane?.description;
-    reports.push({
-      agent_id: id,
-      status: taken.status,
-      ...(description !== undefined && description.length > 0 ? { description } : {}),
-      ...(taken.status !== "failed" && report !== undefined ? { report } : {}),
-      ...(error !== undefined ? { error } : {}),
-      ...(taken.hint !== undefined ? { hint: taken.hint } : {}),
-      ...(taken.providerFailure === true ? { provider_failure: true } : {}),
-    });
+    const projected = consume
+      ? takeAndProjectMailboxRecord(mailbox, id, byId.get(id))
+      : projectMailboxRecord(id, peeked, byId.get(id));
+    if (projected === undefined) continue;
+    reports.push(clipCollectedReport(projected));
   }
   return reports;
 }
@@ -115,6 +155,7 @@ export function driveOpenTasksAfterFleetDry(args: {
   running: number;
   openTasks: readonly Task[];
   parentProcessing: boolean;
+  deferredDryEdge?: boolean;
   mailbox: FleetDryMailbox | undefined;
   lanes: readonly FleetDryLane[];
   beginSystemContinuation: (prompt: string) => void;
@@ -127,13 +168,21 @@ export function driveOpenTasksAfterFleetDry(args: {
       running: args.running,
       hasOpenTasks: hasActiveTasks(tasks),
       parentProcessing: args.parentProcessing,
+      ...(args.deferredDryEdge === true ? { deferredDryEdge: true } : {}),
     })
   ) {
     return false;
   }
-  const reports = collectUncollectedTerminals(args.mailbox, args.lanes);
+  const reports = collectUncollectedTerminals(args.mailbox, args.lanes, false);
   const prompt = buildFleetDryContinuationPrompt(tasks, reports);
-  args.beginSystemContinuation(prompt);
-  args.send(prompt);
+  try {
+    args.beginSystemContinuation(prompt);
+    args.send(prompt);
+  } catch {
+    return false;
+  }
+  for (const report of reports) {
+    args.mailbox?.take(report.agent_id);
+  }
   return true;
 }

src/subagent/index.ts

@@ -30,7 +30,9 @@ export {
   collectUncollectedTerminals,
   driveOpenTasksAfterFleetDry,
   FLEET_DRY_CONTINUATION_PREFIX,
+  projectMailboxRecord,
   shouldDriveOpenTasks,
+  takeAndProjectMailboxRecord,
   type CollectedWorkerReport,
   type FleetDryLane,
   type FleetDryMailbox,