@amenophis1er/foreman 0.1.17 → 0.1.18

package/src/crew.ts

@@ -0,0 +1,330 @@
+/**
+ * Crew presets, and the reviewer gate that stands between a run and "done".
+ *
+ * A mission that runs unattended has nobody reading its diff. The director is
+ * the same kind of agent as the workers, judging its own homework, and asking
+ * it nicely to fetch a second opinion is worth exactly as much as any other
+ * instruction in a prompt. So a crew preset — a named role a human opts into
+ * at compose time — can be marked `requiredForDone`, and Foreman itself refuses
+ * to record the run as done until that reviewer has returned PASS on the diff
+ * the run actually ends with.
+ *
+ * Everything here is pure on purpose: the gate is a rule about a run, not a
+ * conversation with a model, and a rule that decides whether work counts as
+ * finished has to be provable by a test rather than observed in a log.
+ */
+import { createHash } from 'node:crypto';
+import type { ModelChoice, ToolPolicy } from './types.js';
+
+export type CrewKind = 'reviewer' | 'specialist';
+
+export interface CrewPreset {
+  id: string;
+  name: string;
+  kind: CrewKind;
+  model?: ModelChoice;
+  providerId?: string;
+  brief: string;
+  toolPolicy?: 'read-only' | 'default';
+  requiredForDone: boolean;
+}
+
+/** One reviewer's answer about one diff. `at` is what makes a later one later. */
+export interface ReviewVerdict {
+  presetId: string;
+  name: string;
+  pass: boolean;
+  findings: string;
+  diffHash: string;
+  workerId: string;
+  costUsd?: number;
+  at: number;
+}
+
+const REVIEWER_BRIEF = [
+  'You are the reviewer on this mission. Review the diff below against MISSION.md and the',
+  'mission brief the way a demanding senior engineer reviews a colleague\'s pull request.',
+  'Look for correctness first — does this actually do what was asked, and does it break',
+  'anything that already worked. Then missing or shallow tests, security, and anything the',
+  'DONE WHEN criteria did not name but a careful reader would insist on.',
+  'The verdict is PASS only when you would merge this yourself.',
+].join(' ');
+
+const SECURITY_BRIEF = [
+  'You are the security reviewer on this mission. Review the diff below for the ways this',
+  'change could be abused: secrets or tokens committed or logged, injection of any kind',
+  '(shell, SQL, HTML, prompt), path handling that can escape its intended root, and',
+  'permissions — anything newly reachable without authentication, or granted more access',
+  'than the task needs. Ignore style; say plainly what an attacker could do.',
+  'The verdict is PASS only when you would ship this yourself.',
+].join(' ');
+
+/**
+ * The crew a human sees before they have edited anything. Defaults, not law:
+ * the moment they change one, their list replaces this one whole.
+ *
+ * Frozen, and every path out of this module hands back copies, because these
+ * objects are shared by every project on the server — a caller that "just"
+ * flipped requiredForDone on one would be rewriting the gate for all of them.
+ */
+export const BUILT_IN_PRESETS: readonly CrewPreset[] = Object.freeze([
+  Object.freeze({
+    id: 'reviewer',
+    name: 'Reviewer',
+    kind: 'reviewer' as const,
+    model: 'opus',
+    toolPolicy: 'read-only' as const,
+    requiredForDone: true,
+    brief: REVIEWER_BRIEF,
+  }),
+  Object.freeze({
+    id: 'security-review',
+    name: 'Security review',
+    kind: 'reviewer' as const,
+    model: 'opus',
+    toolPolicy: 'read-only' as const,
+    requiredForDone: false,
+    brief: SECURITY_BRIEF,
+  }),
+]) as readonly CrewPreset[];
+
+/**
+ * What "read-only" means for a reviewer: these four tools denied outright, and
+ * nothing else configured.
+ *
+ * The alternative — letting Bash through and classifying each command — is the
+ * kind of rule that is right until someone writes `sh -c 'cat > f'`. A flat
+ * deny is something a test can prove. It costs the reviewer nothing it needs:
+ * AUTO_ALLOW_TOOLS in src/policy.ts already lets Read/Glob/Grep/WebFetch/
+ * WebSearch through, and the diff it is judging arrives in its brief, so the
+ * only thing it loses is the ability to change the code it is judging.
+ */
+export const REVIEWER_TOOL_POLICY: ToolPolicy = Object.freeze({
+  Write: 'deny',
+  Edit: 'deny',
+  NotebookEdit: 'deny',
+  Bash: 'deny',
+}) as ToolPolicy;
+
+function copy(p: CrewPreset): CrewPreset {
+  const out: CrewPreset = { id: p.id, name: p.name, kind: p.kind, brief: p.brief, requiredForDone: p.requiredForDone };
+  if (p.model) out.model = p.model;
+  if (p.providerId) out.providerId = p.providerId;
+  if (p.toolPolicy) out.toolPolicy = p.toolPolicy;
+  return out;
+}
+
+function nonEmptyString(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+
+/**
+ * A `crewPresets` value read off settings JSON, which nobody validated on the
+ * way in. Anything shaped wrongly is dropped rather than repaired: a preset
+ * with no id cannot be referenced by a run, and a preset with no name has
+ * nothing to put in the sentence that blocks the run.
+ *
+ * null and [] mean different things, and that difference is why this returns
+ * null at all: null is "not configured, fall back", [] is "the human deleted
+ * every preset", and answering [] with the built-ins would resurrect a
+ * reviewer they had just removed.
+ */
+export function normalizePresets(raw: unknown): CrewPreset[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: CrewPreset[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const e = entry as Record<string, unknown>;
+    const id = nonEmptyString(e.id);
+    const name = nonEmptyString(e.name);
+    if (!id || !name || seen.has(id)) continue;
+    seen.add(id);
+    const preset: CrewPreset = {
+      id,
+      name,
+      // A preset of an unknown kind is still a worker with a brief; reviewer is
+      // the safe reading, since the only thing kind decides is how it is run.
+      kind: e.kind === 'specialist' ? 'specialist' : 'reviewer',
+      brief: typeof e.brief === 'string' ? e.brief : '',
+      // Anything other than a literal true is not consent to block a run.
+      requiredForDone: e.requiredForDone === true,
+    };
+    const model = nonEmptyString(e.model);
+    if (model) preset.model = model;
+    const providerId = nonEmptyString(e.providerId);
+    if (providerId) preset.providerId = providerId;
+    if (e.toolPolicy === 'read-only' || e.toolPolicy === 'default') preset.toolPolicy = e.toolPolicy;
+    out.push(preset);
+  }
+  return out;
+}
+
+/**
+ * The crew presets in force for a project. A project's list replaces the
+ * global one whole rather than merging with it — the same way the rest of
+ * Settings overlays — because a merge would make "I removed the reviewer here"
+ * unsayable.
+ */
+export function crewPresetsFrom(global: unknown, project: unknown): CrewPreset[] {
+  const read = (blob: unknown): CrewPreset[] | null => {
+    if (!blob || typeof blob !== 'object') return null;
+    return normalizePresets((blob as Record<string, unknown>).crewPresets);
+  };
+  return (read(project) ?? read(global) ?? BUILT_IN_PRESETS).map(copy);
+}
+
+/**
+ * The crew a run starts with, copied onto the run record. Deep copies, because
+ * editing a preset next week must not change what a run that is still going —
+ * or one that finished in March — was reviewed against.
+ */
+export function freezeCrew(ids: readonly string[], presets: readonly CrewPreset[]): CrewPreset[] {
+  const wanted = new Set(ids);
+  const taken = new Set<string>();
+  const out: CrewPreset[] = [];
+  for (const p of presets) {
+    if (!wanted.has(p.id) || taken.has(p.id)) continue;
+    taken.add(p.id);
+    out.push(copy(p));
+  }
+  return out;
+}
+
+/** Past this, findings are a wall of text nobody reads and a row nobody wants to store. */
+const MAX_FINDINGS = 8000;
+
+/**
+ * The reviewer's verdict, dug out of its report. It is told to end with a line
+ * that is exactly `VERDICT: PASS` or `VERDICT: FAIL`; the last such line wins,
+ * because a report that quotes the format while explaining itself and then
+ * states its verdict at the end has stated it at the end.
+ *
+ * null is not FAIL. A report that never says either has not been reviewed —
+ * the model ran out of turns, or answered in prose — and the caller has to be
+ * able to tell that apart from a reviewer that looked and said no.
+ */
+export function parseVerdict(report: string): { pass: boolean; findings: string } | null {
+  if (typeof report !== 'string' || report === '') return null;
+  const lines = report.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    // Markdown decoration is what a model reaches for when told to make a line
+    // stand out; `**VERDICT: PASS**` is the instruction followed, not broken.
+    const line = lines[i].replace(/\*\*/g, '').replace(/^\s*#+\s*/, '');
+    const m = /^\s*VERDICT:\s*(PASS|FAIL)\s*$/i.exec(line);
+    if (!m) continue;
+    let findings = lines.slice(i + 1).join('\n').trim();
+    if (findings.length > MAX_FINDINGS) {
+      findings = findings.slice(0, MAX_FINDINGS) + '\n\n[findings truncated]';
+    }
+    return { pass: m[1].toUpperCase() === 'PASS', findings };
+  }
+  return null;
+}
+
+/**
+ * A fingerprint of what a run has changed, so a PASS can be pinned to the diff
+ * it was given. Canonical: sorted by path and field-separated, so the same
+ * files listed in a different order are the same hash, while one changed line
+ * anywhere is a different one.
+ */
+export function diffHash(deck: {
+  files?: Array<{ path: string; status: string; additions: number; deletions: number; diff?: string }>;
+}): string {
+  const files = deck?.files ?? [];
+  const canon = [...files]
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .map((f) => [f.path, f.status, f.additions, f.deletions, f.diff ?? ''].join('\0'))
+    .join('\n');
+  // A run that changed nothing still has a stable hash, so "reviewed, then
+  // nothing moved" holds for an empty diff too.
+  return createHash('sha256').update(canon).digest('hex');
+}
+
+export interface ReviewBlocker {
+  presetId: string;
+  name: string;
+  reason: 'missing' | 'fail' | 'stale';
+}
+
+/**
+ * THE GATE. Every required reviewer that has not passed the run's current
+ * diff, in crew order. An empty array is the only thing that lets a run be
+ * recorded as done.
+ *
+ * 'stale' is the case worth the machinery: a reviewer passed, then the
+ * director kept working. That PASS was about code that no longer exists, and
+ * treating it as consent for whatever came afterwards would make the gate
+ * trivially walk-around-able — review early, then commit anything.
+ */
+export function reviewBlockers(
+  crew: readonly CrewPreset[] | undefined,
+  verdicts: readonly ReviewVerdict[] | undefined,
+  currentDiffHash: string,
+): ReviewBlocker[] {
+  const out: ReviewBlocker[] = [];
+  for (const preset of crew ?? []) {
+    if (preset.requiredForDone !== true) continue;
+    // Latest by `at`, ties going to the one that arrived later in the array —
+    // two verdicts written in the same millisecond are in the order they were
+    // appended.
+    let latest: ReviewVerdict | undefined;
+    for (const v of verdicts ?? []) {
+      if (v.presetId !== preset.id) continue;
+      if (!latest || v.at >= latest.at) latest = v;
+    }
+    if (!latest) out.push({ presetId: preset.id, name: preset.name, reason: 'missing' });
+    else if (!latest.pass) out.push({ presetId: preset.id, name: preset.name, reason: 'fail' });
+    else if (latest.diffHash !== currentDiffHash) out.push({ presetId: preset.id, name: preset.name, reason: 'stale' });
+  }
+  return out;
+}
+
+/** One human sentence for the `mission_unreviewed` event. */
+export function unreviewedText(blockers: readonly ReviewBlocker[]): string {
+  if (!blockers.length) return '';
+  const clause = (b: ReviewBlocker): string => {
+    if (b.reason === 'fail') return `${b.name} returned FAIL`;
+    if (b.reason === 'stale') return `${b.name} passed an earlier version of the diff; the code changed after it`;
+    return `${b.name} has not reviewed this run`;
+  };
+  const parts = blockers.map(clause);
+  const list = parts.length === 1
+    ? parts[0]
+    : `${parts.slice(0, -1).join('; ')}; and ${parts[parts.length - 1]}`;
+  const lead = blockers.length === 1 ? 'A required reviewer has not passed this run' : 'Required reviewers have not passed this run';
+  return `${lead}: ${list}. This run is not done. Resume to continue it.`;
+}
+
+/**
+ * The prompt the reviewer worker is started with. The diff is handed over in
+ * the brief rather than left to be discovered, because a read-only worker with
+ * no Bash cannot run `git diff` for itself — and because the thing being
+ * reviewed should be the thing Foreman will hash, not whatever the model
+ * happened to look at.
+ */
+export function reviewBriefFor(
+  preset: CrewPreset,
+  opts: { mission: string; doneWhen: string; diff: string; truncated: boolean },
+): string {
+  const parts: string[] = [preset.brief.trim()];
+  parts.push(`## The mission\n\n${opts.mission.trim() || '(no brief was recorded)'}`);
+  parts.push(`## DONE WHEN\n\n${opts.doneWhen.trim() || '(no criteria were recorded)'}`);
+  parts.push(`## The diff\n\n\`\`\`diff\n${opts.diff}\n\`\`\``);
+  if (opts.truncated) {
+    parts.push(
+      'That diff was cut short because it is large. Read the files you need directly — ' +
+      'Read, Glob and Grep are available to you.',
+    );
+  }
+  parts.push(
+    'You cannot modify files: Write, Edit and Bash are denied to you, and attempting them ' +
+    'wastes the run. Report, do not fix.',
+  );
+  parts.push(
+    'End your report with a line that is exactly `VERDICT: PASS` or `VERDICT: FAIL`, and ' +
+    'then list your findings under it, each with a `file:line` where you can give one. ' +
+    'Only what follows that line is kept as your findings.',
+  );
+  return parts.join('\n\n');
+}

package/src/gitwork.test.ts

@@ -3,9 +3,10 @@ import assert from 'node:assert/strict';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { mkdtemp, realpath, writeFile } from 'node:fs/promises';
-import { closeMissionBranch, defaultBranch, worktreeGrant, worktreeParent, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
+import { mkdir, mkdtemp, realpath, symlink, unlink, writeFile } from 'node:fs/promises';
+import { changeFingerprint, closeMissionBranch, defaultBranch, worktreeGrant, worktreeParent, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
 } from './gitwork.js';
+import type { ReviewVerdict } from './crew.js';
 
 const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
 
@@ -93,6 +94,26 @@ test('prDraft: the run title, the brief, the boxes as the mission left them, and
   assert.match(d.body, /## Mission\n\nAdd a footer to the page\.\nKeep it small\./);
   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/);
+  assert.ok(!/## Review/.test(d.body), 'a run nobody reviewed says nothing about review');
+});
+
+test('prDraft: the reviewers and their verdicts, with the head of the findings', async () => {
+  const { prDraft } = await import('./gitwork.js');
+  const verdict = (over: Partial<ReviewVerdict>): ReviewVerdict => ({
+    presetId: 'reviewer', name: 'Reviewer', pass: true, findings: '', diffHash: 'h', workerId: 'w1', at: 1, ...over,
+  });
+  const d = prDraft(
+    { mission: 'Add a footer.', costUsd: 1, costBasis: 'priced', git: { branch: 'b', base: 'main', baseHead: null } },
+    null,
+    [
+      verdict({ findings: '- footer.html:12 the year is hard-coded' }),
+      verdict({ presetId: 'security-review', name: 'Security review', pass: false, findings: `x${'y'.repeat(2000)}` }),
+    ],
+  );
+  assert.match(d.body, /## Review\n\n\*\*Reviewer: PASS\*\*\n\n- footer\.html:12 the year is hard-coded/);
+  assert.match(d.body, /\*\*Security review: FAIL\*\*/);
+  assert.match(d.body, /… the rest is in the run's record\./, 'a long findings list is cut, not pasted whole');
+  assert.ok(d.body.length < 2000, 'the body stays a pull request, not an archive');
 });
 
 
@@ -195,3 +216,64 @@ test('a worktree kept inside the repository is not opened by opening the reposit
   assert.equal(decision.grant, null, 'so the parent is not opened automatically');
   assert.match(decision.reason ?? '', /would also open/);
 });
+
+test('the fingerprint copes with awkward filenames and with a repository that has no commit', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'fingerprint-git-'));
+  sh(dir, 'init', '-q', '-b', 'main');
+  sh(dir, 'config', 'user.email', 'me@example.com');
+  sh(dir, 'config', 'user.name', 'Me');
+
+  // No commit yet: `git diff HEAD` has nothing to diff against, and a run that
+  // starts a repository from nothing is an ordinary mission.
+  await writeFile(path.join(dir, 'first.txt'), 'work\n');
+  const empty = await changeFingerprint(dir);
+  assert.ok(empty, 'a repository with no HEAD still has a fingerprint');
+
+  // A name git C-quotes in `ls-files`: a quoted path handed to hash-object
+  // fails, which used to silently drop the file's content from the hash.
+  const awkward = path.join(dir, 'répertoire "odd" name.txt');
+  await writeFile(awkward, 'one\n');
+  const withAwkward = await changeFingerprint(dir);
+  assert.ok(withAwkward);
+  assert.notEqual(withAwkward, empty);
+
+  await writeFile(awkward, 'two\n');
+  assert.notEqual(await changeFingerprint(dir), withAwkward, 'editing it moves the fingerprint');
+
+  // And once there is a commit, the same file is tracked and still counts.
+  sh(dir, 'add', '-A'); sh(dir, 'commit', '-q', '-m', 'one');
+  const committed = await changeFingerprint(dir);
+  await writeFile(awkward, 'three\n');
+  assert.notEqual(await changeFingerprint(dir), committed);
+});
+
+test('the fingerprint is scoped to the project folder, and sees a retargeted symlink', async () => {
+  // A project that is a subdirectory of a bigger repository: a sibling's
+  // changes are not this mission's, and must not invalidate its review.
+  const repoRoot = await repo();
+  const project = path.join(repoRoot, 'packages', 'app');
+  await mkdir(project, { recursive: true });
+  await writeFile(path.join(project, 'index.ts'), 'export const a = 1;\n');
+  await mkdir(path.join(repoRoot, 'packages', 'other'), { recursive: true });
+  await writeFile(path.join(repoRoot, 'packages', 'other', 'index.ts'), 'export const b = 1;\n');
+  sh(repoRoot, 'add', '-A'); sh(repoRoot, 'commit', '-q', '-m', 'two packages');
+
+  const reviewed = await changeFingerprint(project);
+  assert.ok(reviewed);
+  await writeFile(path.join(repoRoot, 'packages', 'other', 'index.ts'), 'export const b = 2;\n');
+  assert.equal(await changeFingerprint(project), reviewed, 'a sibling package is not this mission');
+  await writeFile(path.join(project, 'index.ts'), 'export const a = 2;\n');
+  assert.notEqual(await changeFingerprint(project), reviewed, 'its own change still counts');
+
+  // Non-git folder: a symlink is neither file nor directory, and retargeting
+  // one changes the project without changing any content.
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'links-'));
+  await writeFile(path.join(plain, 'one.txt'), 'one\n');
+  await writeFile(path.join(plain, 'two.txt'), 'two\n');
+  await symlink('one.txt', path.join(plain, 'current'));
+  const linked = await changeFingerprint(plain);
+  assert.ok(linked);
+  await unlink(path.join(plain, 'current'));
+  await symlink('two.txt', path.join(plain, 'current'));
+  assert.notEqual(await changeFingerprint(plain), linked, 'a retargeted link moves the fingerprint');
+});

package/src/gitwork.ts

@@ -9,7 +9,10 @@
  * the button that says so — once, for that branch, to open the pull request.
  */
 import path from 'node:path';
+import { readdir, readFile, readlink, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import type { ReviewVerdict } from './crew.js';
 
 export interface GitInfo {
   repo: boolean;
@@ -160,6 +163,116 @@ export function worktreeGrant(
   return { grant: parent };
 }
 
+/**
+ * A fingerprint of everything this checkout has changed, for pinning a
+ * reviewer's PASS to the code it actually read.
+ *
+ * Deliberately not computed from the deck: the deck is a *view* — it stops at
+ * 200 files and carries no binary content — so a change to the 201st file, or
+ * a swapped image, would leave a deck-derived hash identical and a stale PASS
+ * looking current. This asks git instead: the full diff against HEAD including
+ * binary deltas, plus the blob hash of every untracked file. Null when the
+ * folder is not a repository or git will not answer, which callers must treat
+ * as "cannot verify", never as "nothing changed".
+ */
+/** git's empty tree, for diffing a repository that has no commit yet. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+const FINGERPRINT_FILE_CAP = 20_000;
+const FINGERPRINT_HASH_MAX_BYTES = 1024 * 1024;
+const FINGERPRINT_SKIP = new Set(['.git', '.foreman', 'node_modules']);
+
+/**
+ * The same fingerprint for a folder that is not a repository — Foreman links
+ * plain folders too, and a gate that only worked in git would make every
+ * mission in one impossible to finish.
+ *
+ * Content-hashed up to a megabyte a file, size and mtime beyond that, since
+ * reading a large binary on every gate check costs more than it proves.
+ * Dependency trees and Foreman's own directory are skipped: they are not the
+ * work under review. Null past the file cap, which the caller reads as
+ * "cannot verify" — the honest answer for a tree too large to pin.
+ */
+async function walkFingerprint(folder: string): Promise<string | null> {
+  const parts: string[] = [];
+  const walk = async (dir: string, rel: string): Promise<boolean> => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    // A directory we cannot read may be where the change is. Failing open
+    // would let a PASS stand over work nobody could see.
+    if (!entries) return false;
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (FINGERPRINT_SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const here = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!await walk(full, here)) return false;
+        continue;
+      }
+      // A symlink is neither a file nor a directory to readdir, and retargeting
+      // one changes what the project is without touching a byte of content.
+      if (e.isSymbolicLink()) {
+        const target = await readlink(full).catch(() => null);
+        if (target === null) return false;
+        parts.push(`${here}\0link\0${target}`);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (parts.length >= FINGERPRINT_FILE_CAP) return false;
+      const st = await stat(full).catch(() => null);
+      if (!st) continue;
+      if (st.size <= FINGERPRINT_HASH_MAX_BYTES) {
+        const buf = await readFile(full).catch(() => null);
+        parts.push(`${here}\0${st.size}\0${buf ? createHash('sha256').update(buf).digest('hex') : 'unreadable'}`);
+      } else {
+        parts.push(`${here}\0${st.size}\0${st.mtimeMs}`);
+      }
+    }
+    return true;
+  };
+  if (!await walk(folder, '')) return null;
+  return createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+
+export async function changeFingerprint(folder: string): Promise<string | null> {
+  try {
+    const inside = await git(['rev-parse', '--is-inside-work-tree'], folder).catch(() => '');
+    if (inside.trim() !== 'true') return walkFingerprint(folder);
+    // HEAD is part of the fingerprint, not just the dirty tree: a director
+    // that commits its work after a PASS leaves `git diff HEAD` empty, and a
+    // fingerprint of the diff alone would call the new commit unchanged and
+    // let the old PASS stand.
+    // A repository with no commit yet has no HEAD to diff against, and a
+    // mission that starts one is ordinary — so the comparison falls back to
+    // git's empty tree rather than failing, which would make every run with a
+    // required reviewer impossible to finish until someone committed.
+    const head = (await git(['rev-parse', 'HEAD'], folder).catch(() => '')).trim();
+    // Scoped to this folder, like the deck: a project linked as a subdirectory
+    // of a bigger repository must not have its review invalidated because a
+    // sibling project changed. `ls-files` below is already limited to the cwd.
+    const tracked = await git(
+      ['diff', head || EMPTY_TREE, '--binary', '--no-color', '--no-ext-diff', '--', '.'], folder, 60_000,
+    );
+    // -z, because `ls-files` C-quotes any path with a quote, a tab or a
+    // non-ASCII character, and a quoted path handed back to `hash-object`
+    // fails — which used to leave those files with no content in the hash at
+    // all, so edits to them were invisible to the gate.
+    const untracked = (await git(['ls-files', '--others', '--exclude-standard', '-z'], folder))
+      .split('\0')
+      // The mission doc and the crew's scratch space are Foreman's own and
+      // change constantly; they are not the work under review.
+      .filter((p) => p && !p.startsWith('.foreman/'));
+    const parts: string[] = [`HEAD\0${head || 'none'}`, tracked];
+    for (const p of untracked.sort()) {
+      // No catch: a file whose hash cannot be read is a fingerprint that
+      // cannot be trusted, and the honest answer is "cannot verify".
+      const blob = await git(['hash-object', '--', p], folder);
+      parts.push(`${p}\0${blob.trim()}`);
+    }
+    return createHash('sha256').update(parts.join('\n')).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
 export async function dirtyPaths(folder: string, limit = 8): Promise<string[]> {
   try {
     const out = await git(['status', '--porcelain', '--untracked-files=normal'], folder);
@@ -275,8 +388,22 @@ export function compareUrl(remote: string | undefined, base: string, branch: str
   return `${r.web}`;
 }
 
-/** The pull request as Foreman drafts it: the run's title, and a body a reviewer can read without opening Foreman. */
-export function prDraft(run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit }, missionDoc: string | null): { title: string; body: string } {
+/** How much of a reviewer's findings go in the body; the rest is in the run's record. */
+const FINDINGS_HEAD = 800;
+
+/**
+ * The pull request as Foreman drafts it: the run's title, and a body a reviewer
+ * can read without opening Foreman.
+ *
+ * `reviews` is passed in rather than read from the run's record here, because
+ * this module knows about git and nothing else — and because the caller is the
+ * only one that knows which verdicts are the ones this branch was judged by.
+ */
+export function prDraft(
+  run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit },
+  missionDoc: string | null,
+  reviews?: readonly ReviewVerdict[],
+): { title: string; body: string } {
   const first = run.mission.split('\n').find((l) => l.trim())?.trim() ?? 'Mission';
   const title = (run.title || first).slice(0, 120);
   const boxes = (missionDoc ?? '').split('\n').filter((l) => /^\s*[-*] \[[ xX]\]/.test(l)).map((l) => l.trim());
@@ -285,6 +412,20 @@ export function prDraft(run: { title?: string; mission: string; costUsd: number;
     '## Mission', '', run.mission.trim(), '',
   ];
   if (boxes.length) parts.push('## Done when', '', ...boxes, '');
+  // Who reviewed this before it was offered to a human, and what they said.
+  // The whole point of the reviewer gate is that the answer travels with the
+  // work; a PASS nobody outside Foreman can see is worth nothing on a branch.
+  if (reviews?.length) {
+    parts.push('## Review', '');
+    for (const v of reviews) {
+      parts.push(`**${v.name}: ${v.pass ? 'PASS' : 'FAIL'}**`);
+      const head = v.findings.trim();
+      if (head) {
+        parts.push('', head.length > FINDINGS_HEAD ? `${head.slice(0, FINDINGS_HEAD).trimEnd()}\n\n… the rest is in the run's record.` : head);
+      }
+      parts.push('');
+    }
+  }
   parts.push('---', `Run by [Foreman](https://github.com/amenophis1er/foreman) on branch \`${run.git?.branch ?? ''}\` from \`${run.git?.base ?? ''}\` · spend ${spend}.`);
   return { title, body: parts.join('\n') };
 }

package/src/mcp.ts

@@ -24,6 +24,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import { describeCadence, type Cadence } from './schedule.js';
+import type { CrewPreset, ReviewVerdict } from './crew.js';
+import { reviewReportLines } from './run-crew.js';
 
 export interface ToolResult {
   /** What the model reads. */
@@ -65,6 +67,9 @@ interface RunSummary {
   workers?: Array<{ id: string; status: string; costUsd: number; task: string }>;
   git?: { branch: string; base: string; commits?: number; pr?: string; prState?: string };
   usage?: { inputTokens: number; outputTokens: number };
+  /** Frozen at dispatch; read here only to say who was meant to review. */
+  crew?: CrewPreset[];
+  reviews?: ReviewVerdict[];
 }
 interface Need { kind: string; id: string; runId?: string; text: string; options?: string[]; toolName?: string; since?: number }
 interface ProjectCard {
@@ -339,7 +344,7 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
 
   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.',
+    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, crew and any review verdicts. For a running run it reports the state so far.',
     schema: { runId: z.string() },
     run: async ({ runId }) => {
       const id = String(runId);
@@ -369,9 +374,13 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
         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`,
+        // The verdicts, and any required reviewer standing between this run and
+        // done. Read-only, like everything else here: presets are configuration
+        // and configuration is edited on the dashboard.
+        ...reviewReportLines(r.crew, r.reviews),
         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, files: own, totals: deck?.totals, report } };
+      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, files: own, totals: deck?.totals, report, reviews: r.reviews ?? [] } };
     },
   };