@amenophis1er/foreman 0.1.13 → 0.1.15

package/README.md

@@ -230,7 +230,7 @@ result.
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test                     # 373 tests, node:test
+npm test                     # 379 tests, node:test
 npm run typecheck            # server and dashboard
 npm run dev                  # API + Vite together
 scripts/dev-restart.sh       # restarts the server only when nothing would be lost
@@ -247,10 +247,12 @@ codex mcp add foreman -- foreman mcp
 agy mcp add foreman -- foreman mcp
 ```
 
-Tools: `fleet_status`, `list_runs`, `run_status` (with `wait_seconds`: one call
-that returns when the run changes), `run_transcript`, `mission_doc`,
+Tools: `fleet_status`, `list_runs`, `run_status` (with `wait_seconds` and
+`until`: one call that blocks until the run changes, finishes, or needs you),
+`run_report` (a finished run in one call: the director's report, DONE WHEN,
+changed files, branch and pull request), `run_transcript`, `mission_doc`,
 `project_memory`, `search_runs`, `doctor`, `link_project` (folder or Git URL),
-`start_mission`, `steer`. It talks to the running server at `FOREMAN_URL`
+`start_mission`, `steer`. Start, wait until finished, read the report: three calls. It talks to the running server at `FOREMAN_URL`
 (default `http://localhost:4177`) and has no logic of its own.
 
 Deliberately absent: approving or denying, answering the director's questions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Autonomous mission runner on the Claude Agent SDK: a director plans, delegates to workers, verifies, and reports — from one dashboard, your phone, or the CLI.",
   "keywords": [
     "claude",

package/src/deck.ts

@@ -847,7 +847,7 @@ function sendJson(res: ServerResponse, code: number, body: unknown): void {
  */
 export async function handleDeckRoute(
   req: IncomingMessage, res: ServerResponse, url: URL,
-  lookup: (scope: 'runs' | 'projects', id: string) => Promise<{ folder: string } | null>,
+  lookup: (scope: 'runs' | 'projects', id: string) => Promise<{ folder: string; deck?: Deck } | null>,
 ): Promise<boolean> {
   // The same jail and the same viewer serve two scopes: a run (its deck,
   // relative to a baseline) and a project (its tree as it stands, no baseline).
@@ -863,7 +863,9 @@ export async function handleDeckRoute(
     if (!run) { sendJson(res, 404, { error: 'not found' }); return true; }
 
     if (what === 'deck') {
-      sendJson(res, 200, await deckFor(run.folder, runId));
+      // A finished run's deck is the one frozen when it ended (snapshot.ts);
+      // the caller hands it over. A running run is diffed live.
+      sendJson(res, 200, run.deck ?? await deckFor(run.folder, runId));
       return true;
     }
     if (what === 'tree') {

package/src/gitwork.test.ts

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { mkdtemp, writeFile } from 'node:fs/promises';
-import { closeMissionBranch, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch } from './gitwork.js';
+import { closeMissionBranch, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch, renameMissionBranch } from './gitwork.js';
 
 const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
 
@@ -93,3 +93,18 @@ test('prDraft: the run title, the brief, the boxes as the mission left them, and
   assert.match(d.body, /## Done when\n\n- \[x\] footer\.html exists\n- \[ \] linked from index/);
   assert.match(d.body, /branch `foreman\/add-a-footer-ab12` from `main` · spend \$0\.42/);
 });
+
+
+test('renameMissionBranch takes the run title once there is one, and leaves a branch that moved on', async () => {
+  const dir = await repo();
+  const g = await startMissionBranch(dir, 'Repo: this folder is a git worktree. Do the thing.', '1788713434983-226123af');
+  assert.ok(!('error' in g));
+  assert.equal(g.branch, 'foreman/repo-this-folder-is-a-git-23af');
+  const renamed = await renameMissionBranch(dir, g.branch, 'Studio data sanitization and null handling', '1788713434983-226123af');
+  assert.equal(renamed, 'foreman/studio-data-sanitization-and-null-23af');
+  assert.equal(sh(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(), renamed);
+  // Same name again: nothing to do. Not on the branch any more: left alone.
+  assert.equal(await renameMissionBranch(dir, renamed!, 'Studio data sanitization and null handling', '1788713434983-226123af'), null);
+  sh(dir, 'checkout', '-q', 'main');
+  assert.equal(await renameMissionBranch(dir, renamed!, 'Another title', '1788713434983-226123af'), null);
+});

package/src/gitwork.ts

@@ -70,7 +70,12 @@ export async function gitInfo(folder: string): Promise<GitInfo> {
 /** `foreman/<first words of the brief>-<id tail>`: readable in `git branch`, unique per run. */
 export function missionBranchName(mission: string, runId: string): string {
   const first = mission.split('\n').find((l) => l.trim())?.trim() ?? 'mission';
-  const slug = first.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').split('-').filter(Boolean).slice(0, 6).join('-').slice(0, 40).replace(/-+$/, '') || 'mission';
+  // Whole words up to six and forty characters: a name cut mid-word
+  // ("null-handli") reads worse than a shorter one.
+  const words = first.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').split('-').filter(Boolean).slice(0, 6);
+  let slug = '';
+  for (const w of words) { const next = slug ? `${slug}-${w}` : w; if (next.length > 40) break; slug = next; }
+  slug = slug || words[0]?.slice(0, 40) || 'mission';
   const tail = runId.replace(/[^a-z0-9]/gi, '').slice(-4).toLowerCase();
   return `foreman/${slug}-${tail}`;
 }
@@ -92,6 +97,27 @@ export async function startMissionBranch(folder: string, mission: string, runId:
   return { branch, base: info.branch ?? 'HEAD', baseHead: info.head ?? null };
 }
 
+/**
+ * The branch takes the run's title once there is one. Branches are created
+ * before the title exists (the title is a model call that lands seconds
+ * later), so they started from the brief's first words — and briefs that all
+ * open with the same boilerplate gave every run the same name. Renamed in
+ * place, only while nothing has been committed on it and it is still checked
+ * out. Returns the new name, or null when it was left as it was.
+ */
+export async function renameMissionBranch(folder: string, from: string, title: string, runId: string): Promise<string | null> {
+  const to = missionBranchName(title, runId);
+  if (to === from) return null;
+  const info = await gitInfo(folder);
+  if (!info.repo || info.branch !== from) return null;
+  try {
+    await git(['branch', '-m', from, to], folder);
+    return to;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Back on the mission's branch for a resume. Returns null when already or
  * now there, else why not — a dirty tree that would be clobbered, typically.

package/src/mcp.test.ts

@@ -54,12 +54,12 @@ test('run_status: crew, DONE WHEN from the mission doc, needs, and no wait on a
   assert.match(r.text, /stopped at its budget cap/);
   assert.match(r.text, /DONE WHEN 1\/2\n  open: docs updated/);
   assert.match(r.text, /worker-1 · done/);
-  assert.match(r.text, /changed: no/);
+  assert.match(r.text, /^finished$/m);
   assert.ok(!calls.some((c) => c.path.startsWith('/events')), 'a finished run is never waited on');
 });
 
-test('run_status with a wait subscribes to /events and returns on the first event for that run', async () => {
-  const sse = new ReadableStream<Uint8Array>({
+test('run_status with a wait returns when the run\'s picture changes, not on a bare event', async () => {
+  const sse = () => new ReadableStream<Uint8Array>({
     start(c) {
       const enc = new TextEncoder();
       c.enqueue(enc.encode(': connected\n\n'));
@@ -67,18 +67,68 @@ test('run_status with a wait subscribes to /events and returns on the first even
       c.enqueue(enc.encode('event: worker_started\ndata: {"runId":"r1","projectId":"p1","data":{"id":"worker-2"}}\n\n'));
     },
   });
+  let rounds = 0;
   const { fetchImpl } = fakeServer({
-    'GET /runs': { runs: [run()] },
+    // First round: an event, but the same run — no change. Second: a new worker.
+    'GET /runs': () => ({ runs: [run(rounds >= 2 ? { workers: [{ id: 'worker-1', status: 'done', costUsd: 0.4, task: 'write tests' }, { id: 'worker-2', status: 'running', costUsd: 0, task: 'more' }] } : {})] }),
     'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: run(), needs: [{ kind: 'perm', id: 'a1', runId: 'r1', text: 'director wants Bash — rm -rf dist' }] }] },
     'GET /missiondoc': { doc: '' },
-    'GET /events': new Response(sse, { status: 200, headers: { 'content-type': 'text/event-stream' } }),
+    'GET /events': () => { rounds += 1; return new Response(sse(), { status: 200, headers: { 'content-type': 'text/event-stream' } }); },
   });
   const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_status').run({ runId: 'r1', wait_seconds: 5 });
   assert.match(r.text, /changed: yes/);
+  assert.ok(rounds >= 2, 'the first event changed nothing visible, so it kept waiting');
+  assert.match(r.text, /worker-2 · running/);
   assert.match(r.text, /NEEDS YOU \(1\) — only a human can answer/);
   assert.match(r.text, /\[perm\] director wants Bash/);
 });
 
+test('run_status until=finished waits through events that are not the end, and stops at the end', async () => {
+  // Two rounds: a cost tick (not finished) then the run turns done.
+  let rounds = 0;
+  const sseOnce = () => new ReadableStream<Uint8Array>({ start(c) { c.enqueue(new TextEncoder().encode('event: cost\ndata: {"runId":"r1","projectId":"p1","data":{}}\n\n')); } });
+  const { fetchImpl, calls } = fakeServer({
+    'GET /runs': () => ({ runs: [run({ status: rounds >= 2 ? 'done' : 'running' })] }),
+    'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: null, needs: [] }] },
+    'GET /missiondoc': { doc: '' },
+    'GET /events': () => { rounds += 1; return new Response(sseOnce(), { status: 200 }); },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_status').run({ runId: 'r1', wait_seconds: 10, until: 'finished' });
+  assert.match(r.text, /r1 · done/);
+  assert.match(r.text, /^finished$/m);
+  assert.ok(calls.filter((c) => c.path.startsWith('/events')).length >= 2, 'kept waiting past the first event');
+});
+
+test('run_status until=needs_you returns when an approval appears', async () => {
+  let asked = false;
+  const { fetchImpl } = fakeServer({
+    'GET /runs': { runs: [run()] },
+    'GET /projects': () => ({ projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: run(), needs: asked ? [{ kind: 'perm', id: 'a1', runId: 'r1', text: 'director wants Bash' }] : [] }] }),
+    'GET /missiondoc': { doc: '' },
+    'GET /events': () => { asked = true; return new Response(new ReadableStream<Uint8Array>({ start(c) { c.enqueue(new TextEncoder().encode('event: permission_request\ndata: {"runId":"r1","projectId":"p1","data":{}}\n\n')); } }), { status: 200 }); },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_status').run({ runId: 'r1', wait_seconds: 5, until: 'needs_you' });
+  assert.match(r.text, /^needs you$/m);
+  assert.match(r.text, /\[perm\] director wants Bash/);
+});
+
+test('run_report: the director\'s last words, DONE WHEN, changed files and the branch in one call', async () => {
+  const say = (agent: string, text: string) => ({ ts: 1, event: 'message', data: { agent, msg: { type: 'assistant', message: { content: [{ type: 'text', text }] } } } });
+  const { fetchImpl } = fakeServer({
+    'GET /runs': { runs: [run({ status: 'done', git: { branch: 'foreman/fix-r1', base: 'main', commits: 1, pr: 'https://github.com/o/r/pull/9', prState: 'merged' } })] },
+    'GET /runs/r1/events': { events: [say('director', 'Starting.'), say('worker-1', 'A long worker message that must not be mistaken for the report.'), say('director', 'All done: tests pass, docs updated, nothing left undone in this mission.')] },
+    'GET /missiondoc': { doc: '- [x] tests pass\n- [x] docs updated\n' },
+    'GET /runs/r1/deck': { baseline: { kind: 'git' }, files: [{ path: 'src/a.ts', status: 'modified', additions: 10, deletions: 2 }, { path: 'old.txt', status: 'modified', additions: 1, deletions: 1, preexisting: true }], artifacts: [{ path: 'shot.png', kind: 'image' }], totals: { files: 2, additions: 11, deletions: 3 } },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_report').run({ runId: 'r1' });
+  assert.match(r.text, /branch foreman\/fix-r1 from main · 1 commit · PR https:\/\/github.com\/o\/r\/pull\/9 \(merged\)/);
+  assert.match(r.text, /DONE WHEN 2\/2/);
+  assert.match(r.text, /changed: 1 file · \+11 −3 · 1 screenshot · 1 already dirty before the run/);
+  assert.match(r.text, /modified src\/a\.ts  \+10 −2/);
+  assert.match(r.text, /Director's report:\nAll done: tests pass/);
+  assert.doesNotMatch(r.text, /worker message/);
+});
+
 test('waitForRunEvent gives up at the timeout when nothing arrives for the run', async () => {
   const quiet = new ReadableStream<Uint8Array>({ start(c) { c.enqueue(new TextEncoder().encode(': connected\n\n')); } });
   const { fetchImpl } = fakeServer({ 'GET /events': new Response(quiet, { status: 200 }) });
@@ -114,7 +164,7 @@ test('the tool set has no human-only actions', () => {
   for (const forbidden of ['approve', 'deny', 'permission', 'answer', 'interrupt', 'resume', 'budget', 'pull_request', 'open_pr', 'settings', 'key']) {
     assert.ok(!names.some((n) => n.split('_').includes(forbidden) || n === forbidden), `${forbidden} must not be a tool`);
   }
-  assert.deepEqual(names, ['fleet_status', 'list_runs', 'run_status', 'run_transcript', 'mission_doc', 'project_memory', 'search_runs', 'doctor', 'link_project', 'start_mission', 'steer']);
+  assert.deepEqual(names, ['fleet_status', 'list_runs', 'run_status', 'run_report', 'run_transcript', 'mission_doc', 'project_memory', 'search_runs', 'doctor', 'link_project', 'start_mission', 'steer']);
 });
 
 test('a server that is not there is said in one sentence with the start command', async () => {

package/src/mcp.ts

@@ -222,22 +222,63 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
     },
   };
 
+  /**
+   * What a reader of run_status would notice changing. `until: 'any'` waits
+   * for THIS to move, not for the next event: a fresh run emits a cost frame
+   * per SDK message, and returning on those meant "changed: true" twice in a
+   * row with identical payloads — a client had to poll after all.
+   */
+  async function digestOf(id: string): Promise<string> {
+    const r = await findRun(id);
+    const needs = await needsOf(id);
+    const doc = await get<{ doc: string }>(`/missiondoc?run=${encodeURIComponent(id)}`).then((d) => d.doc ?? '').catch(() => '');
+    const dw = doneWhen(doc);
+    return JSON.stringify([r.status, r.stopReason ?? null, (r.costUsd ?? 0).toFixed(2), (r.workers ?? []).map((w) => `${w.id}:${w.status}`), dw.done.length, dw.open.length, needs.map((n) => n.id), r.git?.commits ?? 0, r.git?.pr ?? null]);
+  }
+
+  /** What is pending on a run right now, from the fleet payload. */
+  async function needsOf(id: string): Promise<Need[]> {
+    const projects = (await get<{ projects: ProjectCard[] }>('/projects')).projects;
+    const card = projects.find((p) => p.activeRun?.id === id);
+    return (card?.needs ?? []).filter((n) => !n.runId || n.runId === id);
+  }
+
   const runStatus: ToolDef = {
     name: 'run_status',
-    description: 'One run: status, spend against cap, crew and their states, DONE WHEN ticks, what needs a human, branch and pull request. With wait_seconds > 0 it returns as soon as anything changes on that run (or at the timeout) — use it instead of polling.',
-    schema: { runId: z.string(), wait_seconds: z.number().int().min(0).max(maxWait).default(0) },
-    run: async ({ runId, wait_seconds }) => {
+    description: 'One run: status, spend against cap, crew and their states, DONE WHEN ticks, what needs a human, branch and pull request. With wait_seconds > 0 it blocks until `until` is met — "any" change on the run, the run "finished", or it "needs_you" (a pending approval or question, or finished) — or until the timeout. Use it instead of polling; call again if it timed out.',
+    schema: {
+      runId: z.string(),
+      wait_seconds: z.number().int().min(0).max(maxWait).default(0),
+      until: z.enum(['any', 'finished', 'needs_you']).default('any'),
+    },
+    run: async ({ runId, wait_seconds, until }) => {
       const id = String(runId);
+      const cond = String(until ?? 'any');
       let changed: boolean | undefined;
       if (Number(wait_seconds) > 0) {
-        const before = await findRun(id);
-        if (before.status === 'running') changed = await waitForRunEvent(base, id, Number(wait_seconds), f);
-        else changed = false;
+        // Wait in rounds: each round ends on the first event for the run,
+        // then the condition is checked against fresh state; an event that
+        // does not satisfy it (a cost tick, under "finished") starts another
+        // round with the time that is left. The clock is the outer bound.
+        const deadline = Date.now() + Number(wait_seconds) * 1000;
+        changed = false;
+        const before = await digestOf(id);
+        for (;;) {
+          const now = await findRun(id);
+          const satisfied = now.status !== 'running'
+            || (cond === 'needs_you' && (await needsOf(id)).length > 0)
+            || (cond === 'any' && changed);
+          if (satisfied) break;
+          const left = Math.ceil((deadline - Date.now()) / 1000);
+          if (left <= 0) break;
+          const got = await waitForRunEvent(base, id, left, f);
+          if (!got) break;
+          // An event arrived; only count it when the picture it paints differs.
+          if ((await digestOf(id)) !== before) changed = true;
+        }
       }
       const r = await findRun(id);
-      const projects = (await get<{ projects: ProjectCard[] }>('/projects')).projects;
-      const card = projects.find((p) => p.activeRun?.id === id);
-      const needs = (card?.needs ?? []).filter((n) => !n.runId || n.runId === id);
+      const needs = await needsOf(id);
       const doc = await get<{ doc: string }>(`/missiondoc?run=${encodeURIComponent(id)}`).then((d) => d.doc).catch(() => '');
       const dw = doneWhen(doc);
       const workers = (r.workers ?? []).map((w) => `  ${w.id} · ${w.status} · ${usd(w.costUsd)} · ${w.task.slice(0, 80)}`);
@@ -248,9 +289,47 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
         dw.done.length + dw.open.length ? `DONE WHEN ${dw.done.length}/${dw.done.length + dw.open.length}${dw.open.length ? `\n  open: ${dw.open.join('\n  open: ')}` : ''}` : null,
         workers.length ? `crew:\n${workers.join('\n')}` : null,
         needs.length ? `NEEDS YOU (${needs.length}) — only a human can answer these, on the dashboard or the phone:\n${needs.map((n) => `  [${n.kind}] ${n.text}`).join('\n')}` : null,
-        changed !== undefined ? (changed ? 'changed: yes' : 'changed: no (timeout)') : null,
+        changed !== undefined ? (r.status !== 'running' ? 'finished' : needs.length && cond === 'needs_you' ? 'needs you' : changed ? 'changed: yes' : 'changed: no (timeout — call again)') : null,
+      ].filter(Boolean);
+      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, needs, changed, waitedFor: Number(wait_seconds) > 0 ? cond : undefined } };
+    },
+  };
+
+  const runReport: ToolDef = {
+    name: 'run_report',
+    description: 'What a finished run produced, in one call: the director\'s final report, DONE WHEN ticks, the files it changed with +/− counts, the branch, commit and pull request, spend and crew. For a running run it reports the state so far.',
+    schema: { runId: z.string() },
+    run: async ({ runId }) => {
+      const id = String(runId);
+      const r = await findRun(id);
+      const [events, docRes, deck] = await Promise.all([
+        get<{ events: Array<{ ts: number; event: string; data: Record<string, unknown> }> }>(`/runs/${encodeURIComponent(id)}/events`).then((d) => d.events).catch(() => []),
+        get<{ doc: string }>(`/missiondoc?run=${encodeURIComponent(id)}`).catch(() => ({ doc: '' })),
+        get<{ files: Array<{ path: string; status: string; additions: number; deletions: number; preexisting?: boolean }>; artifacts: Array<{ path: string; kind: string }>; totals: { files: number; additions: number; deletions: number }; baseline: { kind: string } }>(`/runs/${encodeURIComponent(id)}/deck`).catch(() => null),
+      ]);
+      // The director's last words: the final assistant text before the run ended.
+      let report = '';
+      for (const e of events) {
+        if (e.event !== 'message' || e.data?.agent !== 'director') continue;
+        const msg = e.data.msg as { type?: string; message?: { content?: Array<{ type: string; text?: string }> } } | undefined;
+        const text = msg?.type === 'assistant' ? msg.message?.content?.filter((c) => c.type === 'text' && c.text).map((c) => c.text).join('\n') : '';
+        if (text && text.trim().length > 40) report = text.trim();
+      }
+      const dw = doneWhen(docRes.doc);
+      const files = deck?.files ?? [];
+      const own = files.filter((x) => !x.preexisting);
+      const fileLines = own.slice(0, 40).map((x) => `  ${x.status.padEnd(8)} ${x.path}  +${x.additions} −${x.deletions}`);
+      const images = (deck?.artifacts ?? []).filter((a) => a.kind === 'image').length;
+      const lines = [
+        runLine(r),
+        r.git ? `branch ${r.git.branch} from ${r.git.base}${r.git.commits ? ` · ${r.git.commits} commit${r.git.commits === 1 ? '' : 's'}` : ''}${r.git.pr ? ` · PR ${r.git.pr}${r.git.prState ? ` (${r.git.prState})` : ''}` : ' · no pull request yet (the human opens it from the run page)'}` : 'not a git repository',
+        `DONE WHEN ${dw.done.length}/${dw.done.length + dw.open.length}${dw.open.length ? ` · open: ${dw.open.join(' · ')}` : ''}`,
+        deck ? `changed: ${own.length} file${own.length === 1 ? '' : 's'} · +${deck.totals.additions} −${deck.totals.deletions}${images ? ` · ${images} screenshot${images === 1 ? '' : 's'}` : ''}${files.length > own.length ? ` · ${files.length - own.length} already dirty before the run` : ''}` : null,
+        fileLines.length ? fileLines.join('\n') + (own.length > 40 ? `\n  … ${own.length - 40} more` : '') : null,
+        `crew: ${(r.workers ?? []).length} worker${(r.workers ?? []).length === 1 ? '' : 's'} · ${(r.workers ?? []).filter((w) => w.status === 'done').length} done`,
+        report ? `\nDirector's report:\n${report.slice(0, 4000)}` : '\nNo final report from the director yet.',
       ].filter(Boolean);
-      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, needs, changed } };
+      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, files: own, totals: deck?.totals, report } };
     },
   };
 
@@ -377,7 +456,7 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
     },
   };
 
-  return [fleet, listRuns, runStatus, transcript, missionDoc, memory, search, doctor, link, start, steer];
+  return [fleet, listRuns, runStatus, runReport, transcript, missionDoc, memory, search, doctor, link, start, steer];
 }
 
 /** Runs the MCP server over stdio until the client goes away. Nothing may be written to stdout but the protocol. */

package/src/notify.ts

@@ -234,10 +234,14 @@ export function shape(env: Envelope, ctx: NotifyContext): Shaped | null {
     // --- money and completion -----------------------------------------
     case 'budget_alert':
       return { key: `budget:${env.runId}:${d.level}`, gate: 'budget',
-        text: `${head(d.level === 'exceeded' ? 'Budget exceeded — run interrupted' : 'Budget cap reached')}${runLine}\n${esc(clip(d.text))}${foot}` };
+        text: `${head(d.level === 'exceeded' ? 'Budget exceeded — run interrupted'
+          : d.level === 'warn' ? 'Budget warning — winding down' : 'Budget cap reached')}${runLine}\n${esc(clip(d.text))}${foot}` };
     case 'budget_stop':
       return { key: `stop:${env.runId}`, gate: 'budget',
         text: `${head('Run winding down')}${runLine}\n${esc(clip(d.reason))}${foot}` };
+    case 'mission_done_at_cap':
+      return { key: `donecap:${env.runId}`, gate: 'done',
+        text: `${head('Done, at the cap')}${runLine}\n${esc(clip(d.text))}${foot}` };
     case 'mission_incomplete':
       return { key: `incomplete:${env.runId}`, gate: 'done',
         text: `${head('Not done')}${runLine}\n${esc(clip(d.text))}${foot}` };

package/src/orchestrator.test.ts

@@ -9,7 +9,7 @@ import {
   stalledWorkerReport, workerStatusBlock,
   watchRepeats, watchSilence, REPEAT_EXEMPT, observeToolUse,
   DEFAULT_ASK_TIMEOUT_MS, armAskTimeout, unattendedAnswer, unattendedDenyMessage,
-  tokenCapLabel, stopReasonOf,
+  tokenCapLabel, stopReasonOf, budgetWarnDue, doneAtCap,
 } from './orchestrator.js';
 import { makePolicy, type PendingPermission } from './policy.js';
 import type { AgentEnv } from './provider.js';
@@ -1256,3 +1256,27 @@ test('stopReasonOf names the cap behind a capReached sentence', () => {
   assert.equal(stopReasonOf('TIME CAP REACHED: 240 minutes.'), 'time');
   assert.equal(stopReasonOf('TOKEN CAP REACHED: 20.1M tokens.'), 'tokens');
 });
+
+test('budgetWarnDue: once past the threshold, and only while still under the cap', () => {
+  assert.equal(budgetWarnDue(7.9, 10, 80), false);
+  assert.equal(budgetWarnDue(8, 10, 80), true);
+  assert.equal(budgetWarnDue(9.99, 10, 80), true);
+  // At and past the cap the wind-down order speaks instead.
+  assert.equal(budgetWarnDue(10, 10, 80), false);
+  assert.equal(budgetWarnDue(12, 10, 80), false);
+  // No threshold, a nonsensical one, or no cap: nothing to warn about.
+  assert.equal(budgetWarnDue(9, 10, undefined), false);
+  assert.equal(budgetWarnDue(9, 10, 0), false);
+  assert.equal(budgetWarnDue(9, 10, 100), false);
+  assert.equal(budgetWarnDue(9, 0, 80), false);
+});
+
+test('doneAtCap: budget-stopped with every criterion ticked is done, and nothing else is', () => {
+  const budget = { budgetStopped: true, wasInterrupted: false, usageLimited: false };
+  assert.equal(doneAtCap(budget, []), true);
+  assert.equal(doneAtCap(budget, ['screenshots saved']), false, 'an unticked box is not done');
+  assert.equal(doneAtCap(budget, null), false, 'no DONE WHEN section says nothing either way');
+  assert.equal(doneAtCap({ ...budget, wasInterrupted: true }, []), false, 'a human stop is not a finish');
+  assert.equal(doneAtCap({ ...budget, usageLimited: true }, []), false, 'a usage limit is not a finish');
+  assert.equal(doneAtCap({ ...budget, budgetStopped: false }, []), false);
+});

package/src/orchestrator.ts

@@ -266,6 +266,31 @@ const DEFAULT_MAX_TURNS = 150;
 export const DEFAULT_MAX_TOKENS = 20_000_000;
 
 /** The cap behind a capReached() sentence, as the run record stores it. */
+/**
+ * Is it time to tell the director to start winding down? True once spend
+ * crosses the warn threshold and while it is still under the cap — past the
+ * cap the wind-down order takes over, and a warning then would be noise.
+ */
+export function budgetWarnDue(costUsd: number, budgetUsd: number, warnAt: number | undefined): boolean {
+  if (!Number.isFinite(warnAt as number) || (warnAt as number) <= 0 || (warnAt as number) >= 100) return false;
+  if (!(budgetUsd > 0)) return false;
+  return costUsd >= budgetUsd * ((warnAt as number) / 100) && costUsd < budgetUsd;
+}
+
+/**
+ * A run the budget stopped, whose own DONE WHEN criteria are all ticked, is
+ * done: it reached its criteria and then reached its limit, in that order.
+ * Only for the budget — a human interrupt or a usage limit says nothing
+ * about the work — and only when the doc actually had criteria to tick.
+ */
+export function doneAtCap(
+  flags: { budgetStopped: boolean; wasInterrupted: boolean; usageLimited: boolean },
+  unmet: string[] | null,
+): boolean {
+  if (!flags.budgetStopped || flags.wasInterrupted || flags.usageLimited) return false;
+  return Array.isArray(unmet) && unmet.length === 0;
+}
+
 export function stopReasonOf(cap: string): 'budget' | 'turns' | 'time' | 'tokens' {
   if (cap.startsWith('TURN')) return 'turns';
   if (cap.startsWith('TIME')) return 'time';
@@ -604,6 +629,8 @@ type AgentRole = 'director' | 'worker';
  * and which role's rates price the tokens.
  */
 interface WorkerOverrides {
+  /** Set on the one continuation a worker gets after the turn cap. */
+  continued?: boolean;
   env?: AgentEnv;
   model?: string;
   priceRole?: AgentRole;
@@ -746,6 +773,19 @@ const USAGE_LIMIT_RE = /out of usage credits|usage limit reached|upgrade to incr
 /** One worker's outcome, as runWorker hands it back. */
 interface WorkerOutcome { report: string; isError: boolean }
 
+/**
+ * Turns a worker gets before the SDK stops it. Raised from 60: five workers
+ * in four missions hit the cap mid-task on legitimate, brief-sized work
+ * (a hundred TypeScript errors in one package; a test-suite port), and each
+ * time the director paid to respawn one that re-read the same files.
+ */
+const WORKER_MAX_TURNS = 100;
+/** What a worker stopped by the cap is told when its session is picked back up. */
+const WORKER_CONTINUE_PROMPT =
+  'You were stopped by the turn cap, not by a failure. Your session and your files are as you left them; ' +
+  '`git status` and `git diff` show your uncommitted work. Continue the same task from where you were — do not ' +
+  'start over or re-read what you already know — finish it, report with report_progress, and end your turn.';
+
 /**
  * A worker record plus the in-process handles that must never be persisted:
  * the live query (for interrupts), the run promise (so nothing is left
@@ -1065,6 +1105,7 @@ export class MissionRun {
         // overrun quiet.
         this.budgetNoticeSent = false;
         this.budgetKillSent = false;
+        this.budgetWarnSent = false;
         this.budgetStopped = false;
       }
     }
@@ -1317,6 +1358,23 @@ export class MissionRun {
       // the one lie a mission runner cannot afford. Downgrading to
       // 'interrupted' is also the useful answer: it is what makes the run
       // resumable rather than closed.
+      // A mission whose own record says every criterion is verified is done,
+      // even if the cap ended the turn it was writing its report in. Calling
+      // that 'interrupted' told the fleet a finished mission had failed, and
+      // invited a resume that spent more to rewrite a report already on disk.
+      // The stop reason stays on the record, so nothing is hidden.
+      if (this.meta.status === 'interrupted' && this.budgetStopped
+          && !this.wasInterrupted && !this.usageLimited) {
+        const unmet = await this.unmetCriteria();
+        if (doneAtCap({ budgetStopped: this.budgetStopped, wasInterrupted: this.wasInterrupted, usageLimited: this.usageLimited }, unmet)) {
+          this.meta.status = 'done';
+          this.emit('mission_done_at_cap', {
+            costUsd: this.meta.costUsd, budgetUsd: this.meta.budgetUsd, reason: this.meta.stopReason,
+            text: 'Every DONE WHEN criterion was verified before the cap ended the run, so this mission is done. ' +
+              'It stopped at its limit rather than finishing under it — the report may be shorter than usual.',
+          });
+        }
+      }
       if (this.meta.status === 'done') {
         const unmet = await this.unmetCriteria();
         if (unmet?.length) {
@@ -1467,6 +1525,7 @@ export class MissionRun {
 
   private budgetNoticeSent = false;
   private budgetKillSent = false;
+  private budgetWarnSent = false;
 
   /**
    * Keeps an "always allow" grant out of `git status`.
@@ -1637,6 +1696,26 @@ export class MissionRun {
       void this.interrupt();
       return;
     }
+    // Before the fence, a nudge. A director that only learns of the cap when
+    // it hits it does its verification and its report inside the one turn it
+    // has left — which is how two missions that had finished their work were
+    // cut mid-report and read as failures. Warn while there is still room to
+    // wind down deliberately.
+    if (!this.budgetWarnSent && budgetWarnDue(costUsd, budgetUsd, this.meta.budgetWarnAt)) {
+      this.budgetWarnSent = true;
+      const pct = Math.round((costUsd / budgetUsd) * 100);
+      this.emit('budget_alert', {
+        level: 'warn', costUsd, budgetUsd,
+        text: `${pct}% of the budget spent ($${costUsd.toFixed(2)} of $${budgetUsd.toFixed(2)}) — director told to start verifying.`,
+      });
+      this.directorInput?.push(
+        '[BUDGET — automated notice]\n' +
+        `You have spent $${costUsd.toFixed(2)} of the $${budgetUsd.toFixed(2)} cap (${pct}%). ` +
+        'Start winding down now: finish or stop the work in flight, do not begin anything you ' +
+        'cannot complete and verify within what is left, and get your verification and MISSION.md ' +
+        'up to date. At the cap you get one final turn, and at 125% the run is interrupted.',
+      );
+    }
     if (!this.budgetNoticeSent && costUsd >= budgetUsd) {
       this.budgetNoticeSent = true;
       this.emit('budget_alert', {
@@ -1983,7 +2062,7 @@ export class MissionRun {
         permissionMode: 'default',
         resume: resumeSessionId,
         model: overrides?.model || this.meta.workerModel,
-        maxTurns: 60,
+        maxTurns: WORKER_MAX_TURNS,
         systemPrompt: { type: 'preset', preset: 'claude_code', append: WORKER_CHARTER },
         ...(overrides?.env ?? this.agentEnv.worker),
         // Built per worker: the report_progress handler closes over this id,
@@ -1996,6 +2075,7 @@ export class MissionRun {
     w.q = q;
 
     let report = '';
+    let hitTurnCap = false;
     let isError = false;
 
     // The stall watchdog. A silent worker no longer blocks the director, but
@@ -2041,6 +2121,7 @@ export class MissionRun {
         if (m.type === 'result') {
           report = String(m.result ?? '');
           isError = Boolean(m.is_error);
+          hitTurnCap = m.subtype === 'error_max_turns' || /maximum number of turns/i.test(report);
           this.noteUsageLimit(report);
           // Same ordering rule as the director loop: the cost event carries
           // usage, so usage has to be current before it is emitted.
@@ -2060,6 +2141,16 @@ export class MissionRun {
       w.q = undefined;
     }
 
+    // A worker stopped by the turn cap mid-task is not a failed worker. Its
+    // session is resumed once with a continue turn — the same context, the
+    // same files — instead of handing the director an error it can only
+    // answer by spawning a replacement that re-reads everything. Once: a
+    // worker that burns two allowances is stuck, and that IS the director's.
+    if (hitTurnCap && !overrides?.continued && w.sessionId && !stalled && !looping) {
+      this.emit('worker_progress', { id: workerId, status: `reached the ${WORKER_MAX_TURNS}-turn cap mid-task; continuing the same session once` });
+      return this.runWorker(workerId, WORKER_CONTINUE_PROMPT, w.sessionId, { ...overrides, continued: true });
+    }
+
     // Told to the director as a fact plus its options, not as an order: it is
     // the agent with the context to know whether this needs a different
     // approach, a different worker, or a human.