Retry a failed fleet worker with a changed brief

After 0.3.15 the parent idled on fail and incomplete-report as if
the operator had cancelled. Fail-path salvage now invites one
successor with a changed brief; operator-cancel still waits;
identical briefs stay refused at the prompt layer.

Author: TheGreatAxios

CHANGELOG.md

@@ -11,6 +11,15 @@ matching `## [X.Y.Z]` section (plus install instructions). Do not maintain
 parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, then run the release script.
 
+## [Unreleased]
+
+### Changed
+
+- Skywalker may spawn one successor with a changed brief after a failed,
+  incomplete-report, or interrupted-incomplete fleet worker. Operator-cancelled
+  salvage still waits for the operator. Identical briefs stay refused. This
+  reverses the 0.3.15 fail-path idle, not operator-cancel.
+
 ## [0.3.18] - 2026-09-08
 
 ### Added

docs/ARCHITECTURE.md

@@ -114,7 +114,7 @@ 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 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. Deadline salvage prepends an advisory parent hint suggesting continuation plus a longer deadline if more wall-clock time is warranted. Cancelled salvage asks the parent to synthesize Findings and Paths and wait for the operator instead of auto-starting another specialist. Deadline hints are advisory only — an identical re-dispatch is still admitted.
+  `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. Deadline salvage prepends an advisory parent hint suggesting continuation plus a longer deadline if more wall-clock time is warranted. Failed, incomplete-report, and interrupted-incomplete salvage tell the parent to diagnose from the report or error and MAY spawn one successor with a changed brief. 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.
 
 #### Model-family policy (`src/agent/model-family-policy.ts`)
 

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

@@ -146,6 +146,20 @@ describe("skywalkerPackage", () => {
     expect(p).not.toContain("if the job still needs doing");
   });
 
+  test("systemPrompt fail-then-successor is distinct from operator-cancel wait", () => {
+    const p = skywalkerPackage.systemPrompt;
+    expect(p).toContain("incomplete-report");
+    expect(p).toContain("interrupted-incomplete");
+    expect(p).toContain("MAY `spawn_agent` **one** successor");
+    expect(p).toContain("changed** brief");
+    expect(p).toContain("wait for the operator");
+    expect(p).toContain("Do not auto-retry");
+    expect(p).toContain("Identical re-dispatch of the same brief stays refused");
+    expect(p).toContain("Operator-cancel is not a re-dispatch");
+    expect(p).not.toContain("Then start the next worker");
+    expect(p).not.toContain("if the job still needs doing");
+  });
+
   test("systemPrompt simple path skips explorer+critic for tiny work", () => {
     const p = skywalkerPackage.systemPrompt;
     expect(p).toContain("DIY on the parent");

src/agent/directors/skywalker/package.ts

@@ -76,7 +76,9 @@ Do **not** turn a "why is this stalled / why no thinking / spawn looks broken" d
 - Classify digs, screenshots of worker rows, and "why/how does X work" as COMMUNICATION first.
 - Answer from mounted tools + known architecture; at most **one** explorer worker if a single unknown path blocks the answer.
 - Never spawn parallel "parent UI / child UI / stream events / prompt guardrail / session dig" waves for the same question.
-- When workers stall, loop, or come back unfinished: synthesize what returned, report Blockers, and change approach — do **not** re-fan-out another diagnostic wave on the same topic.
+- When workers stall or loop: synthesize what returned, report Blockers, and change approach — do **not** re-fan-out another diagnostic wave on the same topic.
+- Failed wait (\`status: failed\` plus \`error\`), salvage \`incomplete-report\`, or interrupted-incomplete (\`stop_reason: interrupted\`, not operator-cancel): diagnose from the wait report or error; MAY \`spawn_agent\` **one** successor with a **changed** brief (new \`success_criteria\` / \`do_not\` / continuation from Findings). Cap is one successor for that stall. Spawn the successor — do not search the repo as a substitute.
+- Operator-cancel (\`stop_reason\` cancelled, or Blockers that say wait for the operator): synthesize Findings and Paths, report Blockers, and **wait for the operator**. Do not auto-retry. Do not spawn a successor because the worker was cancelled.
 - Do **not** search the repo yourself after a worker stops without finishing.
 - Permission asks and long run_shell clocks on worker rows are not a signal to spawn more diggers.
 
@@ -85,6 +87,8 @@ Do **not** turn a "why is this stalled / why no thinking / spawn looks broken" d
 Child starts blank. Parent writes a complete packet: Goal, contracts copied verbatim, Scope/do_not, Done-when/success_criteria, What to report.
 Runtime requires success_criteria for implement/review and their default directors; recommended otherwise.
 Re-dispatch after a blocker is a new handoff (new criteria / new do_not), not a retry of the old one-liner.
+Identical re-dispatch of the same brief stays refused.
+Operator-cancel is not a re-dispatch — wait for the operator.
 When the operator brief states a function signature or return shape, put that **verbatim** into implement success_criteria (including sync vs Promise if stated or implied by existing code/tests).
 
 # Verify after ship

src/agent/prompts.ts

@@ -170,7 +170,7 @@ export function buildGuidelines(
           "Orchestration:",
           "- Break multi-step or parallel work into focused worker dispatches with distinct lenses; prefer `spawn_agent` (fire several in one turn when jobs are independent), then reply with who is running and end the turn — workers keep running while you are idle, and `wait_agents` / `list_agents` on a later turn collect their reports without holding this conversation blocked.",
           "- Pass the typed spawn contract: `intent`, `success_criteria` (done-when; required for implement/review and their default directors), `do_not` (scope fence), and `report_focus`. Free-form `prompt` without `success_criteria` fail-closes for implement/review and their default directors.",
-          "- After workers return, merge their Summary/Findings into a coherent answer for the operator; do not paste raw fleet-agent dumps.",
+          "- After workers return, classify fail / incomplete-report / interrupted-incomplete vs operator-cancel vs clean complete. Fail-path: diagnose from the report or error and MAY spawn one successor with a changed brief. Operator-cancel: wait for the operator; do not auto-retry. Identical brief: refuse. Merge Summary/Findings into a coherent answer for the operator; do not paste raw fleet-agent dumps.",
           "- Use manage_tasks for your own coordination checklist; spawning workers is `spawn_agent` / `wait_agents`, not manage_tasks.",
           "- If context is compacted automatically, do not stop tasks early due to token fear; persist progress via manage_tasks and worker reports.",
         ]),

src/prompts.test.ts

@@ -129,11 +129,17 @@ test("orchestrator guidelines teach the typed task spawn contract", () => {
   expect(guidelines).not.toContain("weaker");
 });
 
-test("primary chat prompt does not invite auto-starting the next worker after unfinished specialists", () => {
+test("primary chat prompt classifies fail-path successor vs operator-cancel wait", () => {
   const prompt = buildChatSystemPrompt();
   const guidelines = buildGuidelines({ sessionMode: "orchestrator" });
-  expect(guidelines).not.toContain("change the brief rather than repeating it");
+  expect(guidelines).toContain("MAY spawn one successor with a changed brief");
+  expect(guidelines).toContain("wait for the operator");
+  expect(guidelines).toContain("do not auto-retry");
+  expect(guidelines).toContain("Identical brief: refuse");
   expect(guidelines).not.toContain("start the next worker");
+  expect(prompt).toContain("MAY `spawn_agent` **one** successor");
+  expect(prompt).toContain("wait for the operator");
+  expect(prompt).toContain("Identical re-dispatch of the same brief stays refused");
   expect(prompt).not.toContain("Then start the next worker");
   expect(prompt).not.toContain("if the job still needs doing");
 });

src/subagent/agent-fleet.test.ts

@@ -391,12 +391,14 @@ describe("spawn_agent + wait_agents", () => {
       agent_id: string;
       status: string;
       report?: string;
+      stop_reason?: string;
     }[];
     expect(results).toHaveLength(1);
     expect(results[0]!.status).toBe("interrupted");
     expect(results[0]!.report).toContain("## Summary");
     expect(results[0]!.report).toContain("## Findings");
     expect(results[0]!.report).toContain("gate.ts");
+    expect(results[0]!.stop_reason).toBe("cancelled");
     // Strip stays cancelled — salvage is for wait_agents, not a resurrection.
     expect(deps.sessions.get(id)?.status).toBe("cancelled");
     expect(deps.sessions.get(id)?.lifecycle.state).toBe("cancelled");
@@ -433,6 +435,87 @@ describe("spawn_agent + wait_agents", () => {
     expect(results[0]!.error).toBeUndefined();
     expect(deps.sessions.get(id)?.status).toBe("cancelled");
   });
+
+  test("incomplete-report complete is wait done with stop_reason", async () => {
+    const deps = makeDeps(async () => ({
+      report: forcedStopReport("incomplete-report", "Still narrating"),
+      stopReason: "incomplete-report",
+    }));
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
+
+    const spawned = await callTool(spawn, {
+      description: "incomplete salvage",
+      prompt: "probe",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+    const waited = await callTool(wait, { targets: [id], timeout_ms: 5000 });
+    const results = waited.results as {
+      status: string;
+      report?: string;
+      error?: string;
+      stop_reason?: string;
+    }[];
+    expect(results[0]!.status).toBe("done");
+    expect(results[0]!.stop_reason).toBe("incomplete-report");
+    expect(results[0]!.report).toContain("narrated instead of writing a report envelope");
+    expect(results[0]!.error).toBeUndefined();
+  });
+
+  test("failed spawn_agent wait_agents returns error not report", async () => {
+    const deps = makeDeps(async () => {
+      throw new Error("provider blew up");
+    });
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
+
+    const spawned = await callTool(spawn, {
+      description: "failed run",
+      prompt: "probe",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+    const waited = await callTool(wait, { targets: [id], timeout_ms: 5000 });
+    const results = waited.results as {
+      status: string;
+      report?: string;
+      error?: string;
+      stop_reason?: string;
+    }[];
+    expect(results[0]!.status).toBe("failed");
+    expect(results[0]!.error).toContain("provider blew up");
+    expect(results[0]!.report).toBeUndefined();
+    expect(results[0]!.stop_reason).toBeUndefined();
+  });
+
+  test("interrupt salvage wait_agents includes stop_reason interrupted", async () => {
+    const deps = makeDeps(async () => ({
+      report: forcedStopReport("interrupted", "partial"),
+      stopReason: "interrupted",
+      interrupted: true,
+    }));
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
+
+    const spawned = await callTool(spawn, {
+      description: "interrupt salvage",
+      prompt: "probe",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+    const waited = await callTool(wait, { targets: [id], timeout_ms: 5000 });
+    const results = waited.results as {
+      status: string;
+      report?: string;
+      error?: string;
+      stop_reason?: string;
+    }[];
+    expect(results[0]!.status).toBe("interrupted");
+    expect(results[0]!.stop_reason).toBe("interrupted");
+    expect(results[0]!.report).toContain("interrupted before finishing");
+    expect(results[0]!.error).toBeUndefined();
+  });
 });
 
 describe("spawn_agent same-cwd concurrency", () => {
@@ -2079,8 +2162,14 @@ describe("admission queue", () => {
     const elapsed = Date.now() - startedAt;
     expect(elapsed).toBeLessThan(200);
     expect(waited.timed_out).toBe(false);
-    const results = waited.results as { agent_id: string; status: string }[];
-    expect(results).toEqual([{ agent_id: queuedId, status: "interrupted" }]);
+    const results = waited.results as {
+      agent_id: string;
+      status: string;
+      stop_reason?: string;
+    }[];
+    expect(results).toEqual([
+      { agent_id: queuedId, status: "interrupted", stop_reason: "cancelled" },
+    ]);
     expect(started).toBe(1);
 
     gate.resolve({ report: "ok" });

src/subagent/agent-fleet.ts

@@ -102,6 +102,7 @@ interface FleetRecord {
   status: WaitJSONStatus;
   report?: string;
   error?: string;
+  stopReason?: string;
   providerFailure?: true;
   /** Set once a wait_agents caller has been handed this result. */
   collected?: boolean;
@@ -344,6 +345,7 @@ class FleetMailbox {
       ...(overlay.hint !== undefined ? { hint: overlay.hint } : {}),
       ...(payload?.report !== undefined ? { report: payload.report } : {}),
       ...(payload?.error !== undefined && status === "failed" ? { error: payload.error } : {}),
+      ...(payload?.stopReason !== undefined ? { stopReason: payload.stopReason } : {}),
       ...(overlay.providerFailure === true ? { providerFailure: true } : {}),
       ...(ask !== undefined ? { question: ask.question, questionId: ask.questionId } : {}),
       ...(status === "awaiting_director" && session !== undefined
@@ -1197,13 +1199,17 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
                 const followupLive =
                   now?.lifecycle.state === "running" && overlay?.status === "interrupted";
                 if (!followupLive) {
-                  deps.sessions.attachReport(session.id, result.report);
+                  deps.sessions.attachReport(session.id, result.report, {
+                    ...(result.stopReason !== undefined ? { stopReason: result.stopReason } : {}),
+                  });
                 }
                 return;
               }
               const alreadyCancelled = deps.sessions.get(session.id)?.status === "cancelled";
               if (alreadyCancelled) {
-                deps.sessions.attachReport(session.id, result.report);
+                deps.sessions.attachReport(session.id, result.report, {
+                  ...(result.stopReason !== undefined ? { stopReason: result.stopReason } : {}),
+                });
                 return;
               }
               const agentRetained = result.agentRetained === true;
@@ -1397,6 +1403,7 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
             ? { 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 } : {}),
         };