@amenophis1er/foreman 0.1.13 → 0.1.14

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.14",
   "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/orchestrator.ts

@@ -604,6 +604,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 +748,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
@@ -1983,7 +1998,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 +2011,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 +2057,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 +2077,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.

package/src/server.ts

@@ -72,7 +72,8 @@ import { readMemory } from './memory.js';
 import { budgetAnchor, modelRecords, projectRecord, recordLine } from './track-record.js';
 import { reconcileRole } from './role-provider.js';
 import { detectBrowser, installChromium } from './browser.js';
-import { closeMissionBranch, compareUrl, createPullRequest, ensureMissionBranch, ghReady, gitInfo, prDraft, pullRequestState, pushBranch, startMissionBranch, type GitInfo } from './gitwork.js';
+import { frozenDeck, frozenMissionDoc, parkMissionDoc, restoreMissionDoc, snapshotRun } from './snapshot.js';
+import { closeMissionBranch, compareUrl, createPullRequest, ensureMissionBranch, ghReady, gitInfo, missionBranchName, prDraft, pullRequestState, pushBranch, renameMissionBranch, startMissionBranch, type GitInfo } from './gitwork.js';
 import { detectTailscale, tailnetUrl } from './tailscale.js';
 import { checkForUpdate, currentVersion, type UpdateInfo } from './update.js';
 import { ServiceRegistry, portOpen, servicesHandler } from './services.js';
@@ -593,6 +594,21 @@ function makeEmitter(runId: string, projectId: string) {
       runLabelCache.set(runId, { ...runLabelCache.get(runId), mission: String(d.mission ?? '') });
     } else if (event === 'run_titled') {
       runLabelCache.set(runId, { ...runLabelCache.get(runId), title: String(d.title ?? '') });
+      // The branch was named from the brief before the title existed; now it
+      // can carry the title. Only while it is still the brief-derived name and
+      // nothing is committed on it — the mission's first turns.
+      const run = activeRuns().find((r) => r.meta.id === runId);
+      const title = String(d.title ?? '').trim();
+      if (run?.meta.git && title && run.meta.git.branch === missionBranchName(run.meta.mission, runId) && !(run.meta.git.commits)) {
+        void renameMissionBranch(run.meta.folder, run.meta.git.branch, title, runId).then(async (renamed) => {
+          if (!renamed || !run.meta.git) return;
+          const was = run.meta.git.branch;
+          run.meta.git = { ...run.meta.git, branch: renamed };
+          await store.writeMeta(run.meta).catch(() => {});
+          gitInfoCache.delete(run.meta.folder);
+          makeEmitter(runId, projectId)('git_branch', { branch: renamed, base: run.meta.git.base, text: `Branch renamed to ${renamed} (was ${was}) now that the run has a title.` });
+        });
+      }
     }
     if (!projectsCache.has(projectId)) {
       void store.getProject(projectId).then((p) => { if (p) projectsCache.set(projectId, { name: p.name }); });
@@ -1595,6 +1611,15 @@ async function driveRun(
     // However the run ended, it no longer needs its gateways.
     releaseGateways(meta.id);
     if (activeByProject.get(projectId) === run) activeByProject.delete(projectId);
+    // Freeze the record: the mission doc and the deck as they stand at this
+    // moment, beside the run's meta and log. Done first, before the branch
+    // closes, so the record is what the crew left — a later mission in the
+    // same folder rewrites MISSION.md and the live diff, never this copy.
+    const frozen = await snapshotRun(store.runDirectory(meta.id), meta.folder, meta.id);
+    if (frozen.doc || frozen.deck) {
+      meta.snapshotAt = Date.now();
+      await store.writeMeta(meta).catch(() => {});
+    }
     // A finished mission on its own branch closes with a commit of whatever
     // the crew left uncommitted. Done only: an interrupted run resumes on
     // the same branch and its tree, and an error is not a result to record.
@@ -1681,6 +1706,7 @@ async function startRun(
     // choosing a model chooses where that role runs.
     directorProviderId: roleProviders.director ?? settings.directorProviderId,
     workerProviderId: roleProviders.worker ?? settings.workerProviderId,
+    ownerPid: process.pid,
     browserTools: browserTools || undefined,
     toolPolicy: settings.toolPolicy,
     autoAllowReadOnly: settings.autoAllowReadOnly,
@@ -1699,6 +1725,14 @@ async function startRun(
     return;
   }
   await consumeProposal(projectId, meta.id, mission).catch(() => {});
+  // The folder's MISSION.md belongs to whichever run wrote it. Parked into
+  // that run's record (when it lacks one) and cleared, so this run's status
+  // reads empty until its own director writes the plan — not 13/14 done.
+  {
+    const previous = (await store.listRuns().catch(() => [] as RunMeta[]))
+      .find((r) => r.projectId === projectId && r.id !== meta.id && r.status !== 'running');
+    await parkMissionDoc(folder, previous ? store.runDirectory(previous.id) : null).catch(() => {});
+  }
   // In a repository, the mission gets a branch of its own before the crew
   // touches anything — so the deck's baseline, taken at the director's first
   // turn, is the branch point, and the diff is exactly the mission.
@@ -1761,6 +1795,7 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
   meta.stopReason = undefined;
   meta.status = 'running';
   meta.endedAt = undefined;
+  meta.ownerPid = process.pid;
   meta.resumes = (meta.resumes ?? 0) + 1;
   if (meta.budgetUsd !== budgetWas) {
     makeEmitter(meta.id, projectId)('settings_changed', {
@@ -1773,6 +1808,15 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
     if (back) makeEmitter(meta.id, projectId)('git_note', { text: `Could not return to ${meta.git.branch} (${back}); the resumed mission runs on whatever is checked out.` });
     gitInfoCache.delete(meta.folder);
   }
+  // The director resumes from MISSION.md. If another mission ran here since,
+  // the folder's copy is that mission's; this run's own goes back first.
+  const restored = await restoreMissionDoc(store.runDirectory(meta.id), meta.folder).catch(() => 'none' as const);
+  if (restored === 'restored') {
+    const emit = makeEmitter(meta.id, projectId);
+    emit('mission_doc_restored', {
+      text: 'Restored this run\'s own MISSION.md into the folder before resuming; a later mission had overwritten it.',
+    });
+  }
   await store.writeMeta(meta).catch((err) => {
     console.error(`failed to persist resume of ${meta.id}:`, err);
   });
@@ -1895,7 +1939,9 @@ const server = http.createServer(async (req, res) => {
       return project ? { folder: project.folder } : null;
     }
     const m = await store.readMeta(id).catch(() => null);
-    return m ? { folder: m.folder } : null;
+    if (!m) return null;
+    const frozen = m.status !== 'running' ? await frozenDeck(store.runDirectory(m.id)) : null;
+    return { folder: m.folder, ...(frozen ? { deck: frozen } : {}) };
   })) return;
   const runResumeMatch = url.pathname.match(/^\/runs\/([^/]+)\/resume$/);
   const prMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr$/);
@@ -2779,9 +2825,11 @@ const server = http.createServer(async (req, res) => {
       if (!runId) return json(res, 400, { error: 'run parameter is required' });
       const meta = await store.readMeta(runId);
       if (!meta) return json(res, 404, { error: 'unknown run' });
-      const doc = await readFile(path.join(meta.folder, '.foreman', 'MISSION.md'), 'utf8')
-        .catch(() => null);
-      json(res, 200, { doc });
+      // A finished run answers with the doc as it ended; only a running run
+      // reads the folder, which is the one mission running there right now.
+      const frozen = meta.status !== 'running' ? await frozenMissionDoc(store.runDirectory(meta.id)) : null;
+      const doc = frozen ?? await readFile(path.join(meta.folder, '.foreman', 'MISSION.md'), 'utf8').catch(() => null);
+      json(res, 200, { doc, frozen: frozen !== null });
 
     } else if (req.method === 'GET' && url.pathname === '/browse') {
       const requested = url.searchParams.get('path') || os.homedir();

package/src/snapshot.test.ts

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { frozenDeck, frozenMissionDoc, hasSnapshot, parkMissionDoc, restoreMissionDoc, snapshotRun } from './snapshot.js';
+
+async function site() {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'foreman-snap-'));
+  const folder = path.join(root, 'proj'); const runDir = path.join(root, 'runs', 'r1');
+  await mkdir(path.join(folder, '.foreman'), { recursive: true });
+  await mkdir(runDir, { recursive: true });
+  return { root, folder, runDir };
+}
+
+test('snapshotRun freezes the mission doc and a deck beside the run, and reads them back', async () => {
+  const { root, folder, runDir } = await site();
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission A\n- [x] done\n');
+  await writeFile(path.join(folder, 'a.txt'), 'hello\n');
+  const r = await snapshotRun(runDir, folder, 'r1', 1234);
+  assert.deepEqual(r, { doc: true, deck: true });
+  assert.equal(await frozenMissionDoc(runDir), '# Mission A\n- [x] done\n');
+  const deck = await frozenDeck(runDir);
+  assert.equal(deck?.frozenAt, 1234);
+  assert.match(deck?.note ?? '', /As the folder stood when the run ended/);
+  assert.equal(await hasSnapshot(runDir), true);
+  // A later mission overwrites the folder's doc; the record does not move.
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission B\n');
+  assert.equal(await frozenMissionDoc(runDir), '# Mission A\n- [x] done\n');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('restoreMissionDoc puts the run\'s own doc back, and says whether it had to', async () => {
+  const { root, folder, runDir } = await site();
+  assert.equal(await restoreMissionDoc(runDir, folder), 'none', 'no record yet');
+  await writeFile(path.join(runDir, 'MISSION.md'), '# Mission A\n');
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission B\n');
+  assert.equal(await restoreMissionDoc(runDir, folder), 'restored');
+  assert.equal(await readFile(path.join(folder, '.foreman', 'MISSION.md'), 'utf8'), '# Mission A\n');
+  assert.equal(await restoreMissionDoc(runDir, folder), 'same');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('a run with no mission doc still freezes its deck; a missing folder freezes nothing and does not throw', async () => {
+  const { root, folder, runDir } = await site();
+  const r = await snapshotRun(runDir, folder, 'r1');
+  assert.equal(r.doc, false);
+  assert.equal(await hasSnapshot(runDir), r.deck);
+  const gone = await snapshotRun(path.join(root, 'runs', 'r2'), path.join(root, 'nowhere'), 'r2');
+  assert.equal(gone.doc, false);
+  assert.equal(await hasSnapshot(path.join(root, 'runs', 'r2')), gone.deck);
+  await rm(root, { recursive: true, force: true });
+});
+
+
+test('parkMissionDoc clears the folder for a new run and keeps the old doc with the run that wrote it', async () => {
+  const { root, folder, runDir } = await site();
+  assert.equal(await parkMissionDoc(folder, runDir), 'none', 'nothing to park');
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Old mission\n- [x] all done\n');
+  assert.equal(await parkMissionDoc(folder, runDir), 'parked');
+  assert.equal(await readFile(path.join(folder, '.foreman', 'MISSION.md'), 'utf8').catch(() => null), null, 'the folder starts clean');
+  assert.equal(await frozenMissionDoc(runDir), '# Old mission\n- [x] all done\n', 'kept with the previous run');
+  // A previous run that already has its own copy is not overwritten by a later folder state.
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Something else\n');
+  await parkMissionDoc(folder, runDir);
+  assert.equal(await frozenMissionDoc(runDir), '# Old mission\n- [x] all done\n');
+  await rm(root, { recursive: true, force: true });
+});