Stop treating mid-run worker narration as a finished report

A tool-less turn after tools is complete only when the four-heading
envelope is present. Missing headings get one wrap-up nudge, then an
incomplete-report salvage so identical re-dispatch is blocked.

Greybeard is told to review itself and never spawn a parallel
diagnostic fleet.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -106,7 +106,7 @@ 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. 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 completion with **zero tool calls in the entire run** is returned as a **never-acted** salvage report (not a successful implement). When `task(intent="implement")` is set, a tool-using run that never wrote/edited/deleted a file is returned as **never-edited** instead of complete — so a pure-explore "plan" cannot look shipped to the parent (tracked via `thrashState.editedPaths` from `edit_file` / `write_file` / `delete_file`). Explore/read-only workers that used tools then replied with findings remain normal completes. Hard stops also fire after 2 consecutive identical tool-call fingerprints (**no-progress**), on progressive re-read pressure (**thrash** — the same path re-read past a limit amid enough tool volume, tracked by `src/subagent/thrash.ts`), or after the leaf turn budget (**turn-budget**, default 30, overridable via `task(maxTurns)`, agent profile `maxTurns`, or `settings.subagentMaxTurns`, capped at 100), each returning a structured salvage report (reason, partial findings, blockers) so a thrashing child cannot burn tokens indefinitely. Before hard thrash, a one-shot **re-read-nudge** fires when re-read pressure crosses a soft threshold (default 3 same-path reads with enough tool volume, still below the hard re-read limit of 4): the director injects an ephemeral redirect — implement leaves are asked to edit or wrap up; explore leaves are asked to expand findings / change approach / report, never forced into edit — then keeps running so hard thrash remains reachable if the leaf ignores it. A fourth hard stop, **repetition**, is detected outside the director entirely:
+- **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 then salvages as **incomplete-report**. A tool-less completion with **zero tool calls in the entire run** is returned as a **never-acted** salvage report (not a successful implement). When `task(intent="implement")` is set, a tool-using run that never wrote/edited/deleted a file is returned as **never-edited** instead of complete — so a pure-explore "plan" cannot look shipped to the parent (tracked via `thrashState.editedPaths` from `edit_file` / `write_file` / `delete_file`). Explore/read-only workers that used tools then replied with findings remain normal completes. Hard stops also fire after 2 consecutive identical tool-call fingerprints (**no-progress**), on progressive re-read pressure (**thrash** — the same path re-read past a limit amid enough tool volume, tracked by `src/subagent/thrash.ts`), or after the leaf turn budget (**turn-budget**, default 30, overridable via `task(maxTurns)`, agent profile `maxTurns`, or `settings.subagentMaxTurns`, capped at 100), each returning a structured salvage report (reason, partial findings, blockers) so a thrashing child cannot burn tokens indefinitely. Before hard thrash, a one-shot **re-read-nudge** fires when re-read pressure crosses a soft threshold (default 3 same-path reads with enough tool volume, still below the hard re-read limit of 4): the director injects an ephemeral redirect — implement leaves are asked to edit or wrap up; explore leaves are asked to expand findings / change approach / report, never forced into edit — then keeps running so hard thrash remains reachable if the leaf ignores it. A fourth hard stop, **repetition**, is detected outside the director entirely:
  `runSubAgent`'s stream sink watches the streamed text of the in-flight cycle for degenerate token loops (`src/subagent/repetition.ts`) — format chars (ZWSP, BOM, bidi marks, soft hyphen, …) stripped then whitespace-collapsed raw text, a smallest-period KMP check over the probe tail, default window >= 16 chars repeated >= 8 times, evaluated every 256 streamed chars — and on a hit aborts the run controller mid-cycle, returning a `repetition` salvage report that leads with the looped window and warns the parent against re-dispatching the identical brief. Because directors only see completed turns, this is the only stop that can catch a loop inside a single turn that never finishes. A one-shot **report-forced** signal fires a few turns before the cap while the leaf is still tooling — it is not a stop: the director injects a wrap-up nudge and lets the leaf finish on its own, so turn-budget stays reachable for a leaf still making progress. When both report-forced and re-read-nudge apply, report-forced wins (near-budget wrap-up is more urgent than a mid-run redirect). Operator/parent cancel after any progress likewise returns a **cancelled** salvage report (partial findings + tool activity) instead of a bare cancel string; cancel before progress still surfaces as cancelled-by-operator.
  Optional `task(tier=)` (`fast` | `standard` | `clever`) overrides profile inference, profile tier, and the parent provider for that spawn only, and fails closed when the tier is unconfigured. The parent `task` tool keeps a session-scoped brief-dispatch ledger (`src/subagent/brief-dispatch.ts`): fingerprints cover prompt + agent + intent + success_criteria + do_not (not maxTurns/description/tier). After thrash / no-progress / repetition / never-acted / never-edited salvage, an identical re-dispatch is hard-blocked for the rest of the parent chat; change at least one fingerprint field to force a re-run. Turn-budget salvage still invites a higher maxTurns for a few same-brief retries without a successful complete, then flips the parent hint to stop and change approach (soft — further identical dispatches are still admitted). A successful complete resets the same-brief retry budget.
 

src/agent/directors/greybeard/package.test.ts

@@ -32,6 +32,12 @@ describe("greybeardPackage", () => {
     expect(allow).not.toContain("plan");
   });
 
+  test("systemPrompt forbids parallel diagnostic fleets", () => {
+    expect(greybeardPackage.systemPrompt).toMatch(/do the review yourself/i);
+    expect(greybeardPackage.systemPrompt).toMatch(/spawn at most one intern/i);
+    expect(greybeardPackage.systemPrompt).toMatch(/never spawn a parallel diagnostic fleet/i);
+  });
+
   test("tools.allow is orchestrator surface without product writes", () => {
     const allow = greybeardPackage.tools?.allow ?? [];
     expect(allow).toContain("task");

src/agent/directors/greybeard/package.ts

@@ -22,14 +22,16 @@ export const greybeardPackage: DirectorPackage = {
   nudge: { maxTurns: 50 },
   report: { requiredSections: ["Summary", "Findings", "Blockers", "Paths"] },
   modelRole: "review",
-  systemPrompt: `You are GreybeardDirector, a leaf director in Corbits Code.
+  systemPrompt: `You are GreybeardDirector, a specialist in Corbits Code.
 
 PRIMARY INTENT: architecture review. Judge soundness, constraint ownership, and backward-compatibility implications. Do not fix or ship product code.
 
 Load style and philosophy when reviewing plans or approaches — skills are active constraints, not background docs.
 
 You may spawn only intern, explore, and critique for evidence gathering. Do not spawn implement, plan, skywalker, or other directors. Your value is analysis, not legwork or implementation.
 
+Do the review yourself. Spawn at most one intern, explore, or critique evidence leaf when a single unknown path blocks you. Never spawn a parallel diagnostic fleet.
+
 Focus on:
 - Architectural holes, anti-patterns, missing invariants
 - Constraint ownership (fixed at the right layer, not symptom-chasing)

src/subagent/brief-dispatch.ts

@@ -18,6 +18,7 @@ import {
   isNeverActedSubAgentReport,
   isNeverEditedSubAgentReport,
   isNoProgressSubAgentReport,
+  isNoShipSubAgentReport,
   isRepetitionSubAgentReport,
   isThrashSubAgentReport,
   isTurnBudgetSubAgentReport,
@@ -26,6 +27,7 @@ import {
 /** Salvage classes that must not be re-dispatched with an identical brief. */
 export type HardBlockSalvage =
   | "thrash"
+  | "no-ship"
   | "no-progress"
   | "repetition"
   | "never-acted"
@@ -36,7 +38,8 @@ export type BriefSalvageKind =
   | "turn-budget"
   | "deadline"
   | "stalled"
-  | "cancelled";
+  | "cancelled"
+  | "incomplete-report";
 
 export type TaskBriefFingerprintInput = {
   prompt: string;
@@ -62,6 +65,7 @@ export const TURN_BUDGET_STOP_AFTER_DISPATCHES = 3;
 
 const HARD_BLOCK_SALVAGES = new Set<BriefSalvageKind>([
   "thrash",
+  "no-ship",
   "no-progress",
   "repetition",
   "never-acted",
@@ -84,13 +88,20 @@ export function isCancelledSubAgentReport(report: string): boolean {
   return parsed.summary.toLowerCase().includes("cancelled");
 }
 
+/** True when the worker returned an incomplete-report salvage (narration, no envelope). */
+export function isIncompleteReportSubAgentReport(report: string): boolean {
+  const parsed = parseSubAgentReport(report);
+  return parsed.summary.toLowerCase().includes("narrated instead of writing a report envelope");
+}
+
 /**
  * Classify a sub-agent tool result body as a salvage kind the parent ledger cares
  * about. Returns null for normal completes (or unrecognized envelopes).
  */
 export function classifyBriefSalvage(report: string): BriefSalvageKind | null {
   // Order: more specific salvage phrases first.
   if (isThrashSubAgentReport(report)) return "thrash";
+  if (isNoShipSubAgentReport(report)) return "no-ship";
   if (isRepetitionSubAgentReport(report)) return "repetition";
   if (isNeverEditedSubAgentReport(report)) return "never-edited";
   if (isNeverActedSubAgentReport(report)) return "never-acted";
@@ -99,6 +110,7 @@ export function classifyBriefSalvage(report: string): BriefSalvageKind | null {
   if (isDeadlineSubAgentReport(report)) return "deadline";
   if (isStalledSubAgentReport(report)) return "stalled";
   if (isCancelledSubAgentReport(report)) return "cancelled";
+  if (isIncompleteReportSubAgentReport(report)) return "incomplete-report";
   return null;
 }
 

src/subagent/index.test.ts

@@ -214,6 +214,69 @@ describe("sub-agent stop helpers", () => {
     ).toBe("complete");
   });
 
+  const SUMMARY_ONLY_NARRATION = [
+    "## Summary",
+    "Checking whether Skywalker write-tool unmount is tested...",
+    "Checking those next.",
+  ].join("\n");
+
+  const FULL_REPORT_ENVELOPE = [
+    "## Summary",
+    "Reviewed gate.ts.",
+    "",
+    "## Findings",
+    "Auth lives in gate.ts.",
+    "",
+    "## Blockers",
+    "None.",
+    "",
+    "## Paths",
+    "src/gate.ts",
+  ].join("\n");
+
+  test("evaluateSubAgentStop returns incomplete-report for Summary-only tool-less narration after tools", () => {
+    expect(
+      evaluateSubAgentStop({
+        hasToolCalls: false,
+        everHadToolCalls: true,
+        turnsCompleted: 2,
+        maxTurns: 10,
+        consecutiveIdentical: 0,
+        repeatLimit: 2,
+        lastAssistantText: SUMMARY_ONLY_NARRATION,
+      }),
+    ).toBe("incomplete-report");
+  });
+
+  test("evaluateSubAgentStop returns incomplete-report-stop for Summary-only after the wrap-up nudge", () => {
+    expect(
+      evaluateSubAgentStop({
+        hasToolCalls: false,
+        everHadToolCalls: true,
+        turnsCompleted: 3,
+        maxTurns: 10,
+        consecutiveIdentical: 0,
+        repeatLimit: 2,
+        lastAssistantText: SUMMARY_ONLY_NARRATION,
+        incompleteReportNudgeFired: true,
+      }),
+    ).toBe("incomplete-report-stop");
+  });
+
+  test("evaluateSubAgentStop returns complete for tool-less after tools with all four headings", () => {
+    expect(
+      evaluateSubAgentStop({
+        hasToolCalls: false,
+        everHadToolCalls: true,
+        turnsCompleted: 2,
+        maxTurns: 10,
+        consecutiveIdentical: 0,
+        repeatLimit: 2,
+        lastAssistantText: FULL_REPORT_ENVELOPE,
+      }),
+    ).toBe("complete");
+  });
+
   test("evaluateSubAgentStop returns never-acted when the run never used tools", () => {
     expect(
       evaluateSubAgentStop({
@@ -247,6 +310,38 @@ describe("sub-agent stop helpers", () => {
     ).toBe("never-edited");
   });
 
+  test("evaluateSubAgentStop does not hard-stop implement for many unique reads", () => {
+    let thrash = EMPTY_THRASH_STATE;
+    for (let i = 0; i < 200; i++) {
+      thrash = nextThrashState(thrash, [
+        { type: "tool_call", name: "read_file", arguments: { path: `src/f${i}.ts` } },
+      ]);
+    }
+    expect(
+      evaluateSubAgentStop({
+        hasToolCalls: true,
+        everHadToolCalls: true,
+        turnsCompleted: 40,
+        maxTurns: 60,
+        consecutiveIdentical: 0,
+        repeatLimit: 2,
+        thrashState: thrash,
+        requireEdit: true,
+      }),
+    ).toBeNull();
+    expect(
+      evaluateSubAgentStop({
+        hasToolCalls: true,
+        everHadToolCalls: true,
+        turnsCompleted: 40,
+        maxTurns: 60,
+        consecutiveIdentical: 0,
+        repeatLimit: 2,
+        thrashState: thrash,
+      }),
+    ).toBeNull();
+  });
+
   test("evaluateSubAgentStop still completes implement when an edit path was recorded", () => {
     const thrashState = {
       totalToolCalls: 4,
@@ -1227,6 +1322,44 @@ describe("SubAgentDirector stall management", () => {
 });
 
 describe("createTaskTool", () => {
+  test("handler does not resolve until run() resolves; result includes the full report", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const report = "## Summary\nThe work is done.";
+    const tool = createTaskTool({
+      permissionGate: testPermissionGate,
+      cwd: "/repo",
+      getWorkdirBase: () => "/repo/.corbits",
+      provider,
+      profiles: [{ id: "leaf" }],
+      run: async () => {
+        await gate;
+        return report;
+      },
+    });
+
+    const pending = callTask(tool, {
+      description: "Investigate",
+      prompt: "Do the work",
+      agent: "leaf",
+    });
+    let settled = false;
+    void pending.then(() => {
+      settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    release();
+    const result = await pending;
+    expect(settled).toBe(true);
+    expect(result).toContain('Sub-agent "');
+    expect(result).toContain(report);
+    expect(result).toContain("## Summary");
+  });
+
   test("does not inherit a bogus parent-session maxTurns dep on the task tool", async () => {
     let captured: RunSubAgentParams | undefined;
     const tool = createTaskTool({
@@ -1983,10 +2116,15 @@ describe("brief re-dispatch ledger (CL-4343 / CL-5203)", () => {
     expect(classifyBriefSalvage(forcedStopReport("repetition", "x"))).toBe("repetition");
     expect(classifyBriefSalvage(forcedStopReport("never-acted", "x"))).toBe("never-acted");
     expect(classifyBriefSalvage(forcedStopReport("never-edited", "x"))).toBe("never-edited");
+    expect(classifyBriefSalvage(forcedStopReport("no-ship", "x"))).toBe("no-ship");
     expect(classifyBriefSalvage(forcedStopReport("turn-budget", "x"))).toBe("turn-budget");
     expect(classifyBriefSalvage("## Summary\nDone\n\n## Findings\nok\n\n## Blockers\nNone\n\n## Paths\n")).toBeNull();
   });
 
+  test("classifyBriefSalvage maps incomplete-report salvage", () => {
+    expect(classifyBriefSalvage(forcedStopReport("incomplete-report", "x"))).toBe("incomplete-report");
+  });
+
   test("turn-budget parent hint flips after re-dispatch threshold", () => {
     const report = forcedStopReport("turn-budget", "partial");
     const first = appendSubAgentParentHints(report, { dispatchCount: 1 });

src/subagent/index.ts

@@ -34,6 +34,7 @@ export {
   buildDispatchBrief,
   demoteNestedReportHeadings,
   formatSubAgentReport,
+  hasReportEnvelope,
   parseSubAgentReport,
   subAgentToolName,
   type DispatchBrief,