@jwilger/pi-development-system 0.46.0 → 0.47.0

package/extensions/development-system.ts

@@ -1,3 +1,4 @@
+// pi-lens-ignore: high-import-coupling -- composition root: it imports every module it wires, by design
 import { readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { cadenceLine, DEFAULT_PUSH_MINUTES } from "../src/context/cadence.ts";
@@ -34,6 +35,7 @@ const nonNegotiables = readFileSync(
 );
 
 /** Composition root: wires modules, holds no logic. */
+// pi-lens-ignore: high-fan-out -- composition root: wiring every module is its whole job
 export function createDevelopmentSystem(pi: ExtensionAPI) {
   const state = createSessionState(pi);
   const approvals = createApprovalStore(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/src/context/turn-verifier.ts

@@ -1,5 +1,9 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
 import { redactSecrets } from "../core/redact.ts";
 import { exitCodeOf, summarizeOutput } from "../core/test-runner.ts";
 import type { DevsysState, Phase } from "../core/types.ts";
@@ -77,6 +81,46 @@ const note = (content: string) => ({
   display: true,
 });
 
+/** What a finished tool call proves, for Jev: the target, the output tail and (for bash) the real exit code. */
+function evidenceOf(event: ToolResultEvent): ToolEvidence {
+  const text = event.content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("\n");
+  const summary = summarizeOutput(text);
+  const command = typeof event.input.command === "string" ? event.input.command : undefined;
+  // exitCodeOf sees through `npm test | tail`, which would otherwise show a failing run as exit 0.
+  const exitCode = exitCodeOf({
+    isError: event.isError,
+    text,
+    structured: event.structuredContent,
+    ...(command === undefined ? {} : { command }),
+  });
+  // Name what ran or which file: a check that passes silently (`tsc --noEmit`) prints nothing.
+  const target = redactSecrets(
+    command ?? (typeof event.input.path === "string" ? event.input.path : ""),
+  )
+    .replace(/\s+/g, " ")
+    .slice(0, TARGET_MAX);
+  const described = target === "" ? summary : `${target} → ${summary}`;
+  return event.toolName === "bash"
+    ? { tool: "bash", summary: described, exitCode }
+    : { tool: event.toolName, summary: described };
+}
+
+/** The corrective notes a judged turn earns: an unverified claim, and drift not yet covered by a departure. */
+function correctionsFor(
+  judged: { unverifiedClaim: number; driftFromSlice: number },
+  state: DevsysState,
+) {
+  const slice = state.activeSlice;
+  const drifted =
+    judged.driftFromSlice >= VERIFIER_THRESHOLD &&
+    slice !== undefined &&
+    !expansionRecorded(state, slice);
+  return [
+    ...(judged.unverifiedClaim >= VERIFIER_THRESHOLD ? [note(claimMessage())] : []),
+    ...(drifted && slice !== undefined ? [note(driftMessage(slice))] : []),
+  ];
+}
+
 /**
  * At turn end, asks Jev whether the final message claims results no tool call supports, or wanders
  * from the active slice, and forces ONE corrective continuation. Bounded: never on a turn that
@@ -98,28 +142,7 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
     justCorrected = false;
   });
   deps.pi.on("tool_result", (event) => {
-    const text = event.content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("\n");
-    const summary = summarizeOutput(text);
-    const command = typeof event.input.command === "string" ? event.input.command : undefined;
-    // exitCodeOf sees through `npm test | tail`, which would otherwise show a failing run as exit 0.
-    const exitCode = exitCodeOf({
-      isError: event.isError,
-      text,
-      structured: event.structuredContent,
-      ...(command === undefined ? {} : { command }),
-    });
-    // Name what ran or which file: a check that passes silently (`tsc --noEmit`) prints nothing.
-    const target = redactSecrets(
-      command ?? (typeof event.input.path === "string" ? event.input.path : ""),
-    )
-      .replace(/\s+/g, " ")
-      .slice(0, TARGET_MAX);
-    const described = target === "" ? summary : `${target} → ${summary}`;
-    const item: ToolEvidence =
-      event.toolName === "bash"
-        ? { tool: "bash", summary: described, exitCode }
-        : { tool: event.toolName, summary: described };
-    evidence = [...evidence, item].slice(-MAX_EVIDENCE);
+    evidence = [...evidence, evidenceOf(event)].slice(-MAX_EVIDENCE);
   });
 
   deps.pi.on("turn_end", async (event, ctx) => {
@@ -142,14 +165,7 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
       ...(state.activeSlice === undefined ? {} : { activeSlice: state.activeSlice }),
     });
     if (!judged.ok) return undefined;
-    const entries = [
-      ...(judged.value.unverifiedClaim >= VERIFIER_THRESHOLD ? [note(claimMessage())] : []),
-      ...(judged.value.driftFromSlice >= VERIFIER_THRESHOLD &&
-      state.activeSlice !== undefined &&
-      !expansionRecorded(state, state.activeSlice)
-        ? [note(driftMessage(state.activeSlice))]
-        : []),
-    ];
+    const entries = correctionsFor(judged.value, state);
     if (entries.length === 0) return undefined;
     corrected += 1;
     justCorrected = true;

package/src/core/git-intent.ts

@@ -24,7 +24,8 @@ const worst = (a: GitIntent, b: GitIntent): GitIntent =>
   SEVERITY.indexOf(a) <= SEVERITY.indexOf(b) ? a : b;
 
 /** Splits a command string on newlines that are outside quotes; backslash-newline is a continuation. */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: a shell lexer is one flat branch per character class; splitting it would scatter a single state machine across helpers
+// biome-ignore-start lint/complexity/noExcessiveCognitiveComplexity: a shell lexer is one flat branch per character class; splitting it would scatter a single state machine across helpers
+// pi-lens-ignore: high-complexity -- a shell lexer is one flat branch per character class; splitting it would scatter one state machine across helpers
 export function splitLines(command: string): string[] {
   const lines: string[] = [];
   let current = "";
@@ -56,6 +57,7 @@ export function splitLines(command: string): string[] {
   lines.push(current);
   return lines;
 }
+// biome-ignore-end lint/complexity/noExcessiveCognitiveComplexity: end of the shell lexer above
 
 const isRedirect = (op: string): boolean => /^[<>]/.test(op) && !op.endsWith("(");
 
@@ -216,6 +218,7 @@ function splitGlobals(rest: string[]): {
   return { globals, sub: rest[j], args: rest.slice(j + 1) };
 }
 
+// pi-lens-ignore: high-fan-out -- the classifier dispatches one git word to many small predicates; it is a table, not coordination
 function classifySegment(tokens: string[]): GitIntent {
   const { index: i, hookSkip } = skipPrefix(tokens);
   if (i < 0) return "ordinary";
@@ -251,6 +254,7 @@ function classifySegment(tokens: string[]): GitIntent {
  * The parts of a line bash may still execute or treat as syntax: single-quoted text and
  * backslash-escaped characters are dropped; double-quoted text is kept unless `dropDouble`.
  */
+// pi-lens-ignore: high-complexity -- a shell lexer is one flat branch per character class; splitting it would scatter one state machine across helpers
 export function live(line: string, dropDouble: boolean): string {
   let out = "";
   let quote: "'" | '"' | undefined;
@@ -292,6 +296,7 @@ export function substitutions(text: string): string[] {
 const HEREDOC = /^<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/;
 
 /** The delimiter of a heredoc started by an unquoted `<<` on this line, if any. */
+// pi-lens-ignore: high-complexity -- a shell lexer is one flat branch per character class; splitting it would scatter one state machine across helpers
 export function heredocDelimiter(line: string): string | undefined {
   let quote: "'" | '"' | undefined;
   for (let i = 0; i < line.length; i++) {

package/src/core/model-advice.ts

@@ -47,7 +47,7 @@ const direct = (matrix: ModelMatrix, tier: Tier): string[] =>
  * frontier but lives in strong). Undefined when it is in none of them.
  */
 export function tierOf(matrix: ModelMatrix, model: string): Tier | undefined {
-  return [...TIERS].reverse().find((tier) => matches(direct(matrix, tier), model));
+  return TIERS.findLast((tier) => matches(direct(matrix, tier), model));
 }
 
 /** The best tier that lists the model at all: what a slot resolving to it is asking for. */

package/src/core/push-command.ts

@@ -34,18 +34,23 @@ type ParsedArgs = {
 
 const VALUE_PREFIX = "--repo=";
 
+function applyFlag(parsed: ParsedArgs, a: string): void {
+  if (a.startsWith(VALUE_PREFIX)) parsed.repo = a.slice(VALUE_PREFIX.length);
+  else if (a === "--all" || a === "--mirror") parsed.all = true;
+  else if (a === "--tags") parsed.tags = true;
+  else if (!a.startsWith("-")) parsed.positional.push(a);
+}
+
 function positionalArgs(args: readonly string[]): ParsedArgs {
   const parsed: ParsedArgs = { positional: [], all: false, tags: false, repo: undefined };
   let valueFor: "repo" | "skip" | undefined;
   for (const a of args) {
-    if (valueFor === "repo") parsed.repo = a;
-    if (valueFor !== undefined) valueFor = undefined;
-    else if (a === "--repo") valueFor = "repo";
-    else if (a.startsWith(VALUE_PREFIX)) parsed.repo = a.slice(VALUE_PREFIX.length);
+    if (valueFor !== undefined) {
+      if (valueFor === "repo") parsed.repo = a;
+      valueFor = undefined;
+    } else if (a === "--repo") valueFor = "repo";
     else if (VALUE_OPTIONS.has(a)) valueFor = "skip";
-    else if (a === "--all" || a === "--mirror") parsed.all = true;
-    else if (a === "--tags") parsed.tags = true;
-    else if (!a.startsWith("-")) parsed.positional.push(a);
+    else applyFlag(parsed, a);
   }
   return parsed;
 }

package/src/core/review-flow.ts

@@ -144,8 +144,11 @@ export function adoptSeverity(
   };
 }
 
-const where = (f: Finding): string =>
-  f.path === undefined ? "" : ` \`${f.path}${f.line === undefined ? "" : `:${f.line}`}\``;
+const where = (f: Finding): string => {
+  if (f.path === undefined) return "";
+  const line = f.line === undefined ? "" : `:${f.line}`;
+  return ` \`${f.path}${line}\``;
+};
 
 /**
  * Nits are never stored. Each is reported back so the coordinator fixes it now or drops it

package/src/core/review-packet.ts

@@ -10,11 +10,7 @@ export type ReviewPacket = {
   readonly verdict: "no-blocking" | "blocking";
 };
 
-const SEP = "[—–-]";
-const HEADER = new RegExp(
-  `^##\\s+Review\\s+${SEP}\\s+(.+?)\\s+${SEP}\\s+round\\s+(\\S+)\\s+${SEP}\\s+lenses:\\s*(.*)$`,
-  "m",
-);
+const HEADER = /^##\s+Review\s+[—–-]\s+(.+?)\s+[—–-]\s+round\s+(\S+)\s+[—–-]\s+lenses:\s*(.*)$/m;
 // Reviewers add text after the location (`fn`, a second location); the first backticked one is the finding's.
 const FINDING = /^-\s*\[([^\]]+)\]\s+(\S+)\s+(?:`([^`]+)`[^—–]*?\s+)?[—–-]\s+(.+)$/;
 // An indented line under a finding is its detail (trigger, fix), unless it is itself a finding.
@@ -24,8 +20,11 @@ const isDetail = (line: string): boolean =>
 // `until` ends a section; by default any heading does. Findings ends only at a known section so a stray
 // heading inside it (### Nits) makes its lines errors instead of silently cutting the findings off.
 const section = (text: string, name: string, until = /^###?\s/m): string | undefined => {
-  const match = new RegExp(`^###\\s+${name}\\s*$`, "im").exec(text);
-  if (match === null) return undefined;
+  const wanted = name.toLowerCase();
+  const match = [...text.matchAll(/^###\s+(.+?)\s*$/gim)].find(
+    (m) => m[1]?.toLowerCase() === wanted,
+  );
+  if (match === undefined) return undefined;
   const rest = text.slice(match.index + match[0].length);
   const next = until.exec(rest);
   return next === null ? rest : rest.slice(0, next.index);
@@ -65,6 +64,45 @@ function parseFinding(line: string, lens: string[], index: number): Finding | Pa
   };
 }
 
+const FINDINGS_MISSING =
+  'missing "### Findings" section: write "- none" under it when there are no findings';
+const NO_FINDINGS = /^(?:-\s*)?[([]?(?:none|no findings?)[)\]]?\.?$/i;
+
+/** The packet's verdict word, or the parse error explaining what is wrong with it. */
+function verdictOf(text: string): "blocking" | "no-blocking" | ParseError {
+  const word = section(text, "Verdict")?.trim().split(/\s+/)[0]?.toLowerCase();
+  if (word === "no-blocking" || word === "blocking") return word;
+  return parseError(
+    'missing or invalid verdict: end the packet with "### Verdict" then no-blocking or blocking',
+  );
+}
+
+/** Every finding line of the Findings section; a line that is not a finding is an error, never dropped. */
+function findingsOf(text: string, lenses: string[]): Finding[] | ParseError {
+  const body = section(text, "Findings", AFTER_FINDINGS);
+  if (body === undefined) return parseError(FINDINGS_MISSING);
+  const lines = body
+    .split("\n")
+    .flatMap((l) => (isDetail(l) ? [] : [l.trim()]))
+    .filter((l) => l !== "" && !NO_FINDINGS.test(l));
+  const findings: Finding[] = [];
+  for (const [i, line] of lines.entries()) {
+    const finding = parseFinding(line, lenses, i + 1);
+    if (isParseError(finding)) return finding;
+    findings.push(finding);
+  }
+  return findings;
+}
+
+const isBlocking = (f: Finding): boolean =>
+  f.severity === "blocking" || f.severity === "should-fix";
+
+const listOf = (text: string): string[] =>
+  text
+    .split(",")
+    .map((l) => l.trim())
+    .filter((l) => l !== "");
+
 /** Parse the reviewer packet of plan Appendix A. Strict about structure, tolerant of dash style. */
 export function parseReviewPacket(text: string): ReviewPacket | ParseError {
   const header = HEADER.exec(text);
@@ -75,51 +113,19 @@ export function parseReviewPacket(text: string): ReviewPacket | ParseError {
   if (!Number.isInteger(round) || round < 1) {
     return parseError(`round "${header[2]}" is not a positive integer`);
   }
-  const lenses = (header[3] ?? "")
-    .split(",")
-    .map((l) => l.trim())
-    .filter((l) => l !== "");
-  const verdictText = section(text, "Verdict")?.trim().split(/\s+/)[0]?.toLowerCase();
-  if (verdictText !== "no-blocking" && verdictText !== "blocking") {
-    return parseError(
-      'missing or invalid verdict: end the packet with "### Verdict" then no-blocking or blocking',
-    );
-  }
-  const findings: Finding[] = [];
-  const findingsText = section(text, "Findings", AFTER_FINDINGS);
-  if (findingsText === undefined) {
+  const lenses = listOf(header[3] ?? "");
+  const verdict = verdictOf(text);
+  if (isParseError(verdict)) return verdict;
+  const findings = findingsOf(text, lenses);
+  if (isParseError(findings)) return findings;
+  if (findings.some(isBlocking) !== (verdict === "blocking")) {
     return parseError(
-      'missing "### Findings" section: write "- none" under it when there are no findings',
-    );
-  }
-  const lines = findingsText
-    .split("\n")
-    .filter((l) => !isDetail(l))
-    .map((l) => l.trim())
-    .filter((l) => l !== "" && !/^(?:-\s*)?[([]?(?:none|no findings?)[)\]]?\.?$/i.test(l));
-  for (const [i, line] of lines.entries()) {
-    const finding = parseFinding(line, lenses, i + 1);
-    if (isParseError(finding)) return finding;
-    findings.push(finding);
-  }
-  const hasBlocking = findings.some(
-    (f) => f.severity === "blocking" || f.severity === "should-fix",
-  );
-  if (hasBlocking !== (verdictText === "blocking")) {
-    return parseError(
-      `verdict "${verdictText}" contradicts the findings: blocking/should-fix findings mean "blocking", otherwise "no-blocking"`,
+      `verdict "${verdict}" contradicts the findings: blocking/should-fix findings mean "blocking", otherwise "no-blocking"`,
     );
   }
   const sources = (section(text, "Sources inspected") ?? "")
     .split("\n")
     .map((l) => l.replace(/^-\s*/, "").trim())
     .filter((l) => l !== "");
-  return {
-    slice: (header[1] ?? "").trim(),
-    round,
-    lenses,
-    sources,
-    findings,
-    verdict: verdictText,
-  };
+  return { slice: (header[1] ?? "").trim(), round, lenses, sources, findings, verdict };
 }

package/src/core/test-paths.ts

@@ -18,22 +18,20 @@ const PATTERNS: readonly RegExp[] = [
   /_tests\.rs$/,
 ];
 
+/** Whether `rest` matches some suffix of `path`; a `*` may not cross a `/` when `withinSegment`. */
+function matchesSuffix(rest: string, path: string, withinSegment: boolean): boolean {
+  for (let i = 0; i <= path.length; i++) {
+    if (matchGlob(rest, path.slice(i))) return true;
+    if (withinSegment && (path[i] === "/" || i === path.length)) return false;
+  }
+  return false;
+}
+
 /** Glob match without building a RegExp: `**` spans directories, `*` stays within a segment. */
 function matchGlob(glob: string, path: string): boolean {
   if (glob === "") return path === "";
-  if (glob.startsWith("**")) {
-    const rest = glob.slice(2);
-    for (let i = 0; i <= path.length; i++) if (matchGlob(rest, path.slice(i))) return true;
-    return false;
-  }
-  if (glob.startsWith("*")) {
-    const rest = glob.slice(1);
-    for (let i = 0; i <= path.length; i++) {
-      if (matchGlob(rest, path.slice(i))) return true;
-      if (path[i] === "/" || i === path.length) return false;
-    }
-    return false;
-  }
+  if (glob.startsWith("**")) return matchesSuffix(glob.slice(2), path, false);
+  if (glob.startsWith("*")) return matchesSuffix(glob.slice(1), path, true);
   return path !== "" && path[0] === glob[0] && matchGlob(glob.slice(1), path.slice(1));
 }
 

package/src/core/test-runner.ts

@@ -9,17 +9,20 @@ const SUMMARY_MAX = 300;
 
 /** Words after wrappers (`time`, `timeout 60`, `env`), assignments and `+toolchain` selectors. */
 function commandWords(words: readonly string[]): string[] {
-  let i = 0;
-  while (i < words.length) {
-    const word = words[i] ?? "";
-    const wrapper = WRAPPERS.has(basename(word)) || basename(word) === "timeout";
-    if (isAssignment(word)) i += 1;
-    else if (wrapper) {
-      i += 1;
-      while (i < words.length && /^(?:-|\d+[smhd]?$)/.test(words[i] ?? "")) i += 1;
-    } else break;
+  const flagOrDuration = (w: string | undefined): boolean => /^(?:-|\d+[smhd]?$)/.test(w ?? "");
+  let next = 0;
+  for (const [index, word] of words.entries()) {
+    if (index < next) continue;
+    if (isAssignment(word)) {
+      next = index + 1;
+    } else if (WRAPPERS.has(basename(word)) || basename(word) === "timeout") {
+      next = index + 1;
+      while (flagOrDuration(words[next])) next += 1;
+    } else {
+      return words.slice(index);
+    }
   }
-  return words.slice(i);
+  return [];
 }
 
 function isRunner(words: readonly string[]): boolean {

package/src/core/test-weakening.ts

@@ -125,7 +125,8 @@ type Segment = { words: string[]; truncates: string[] };
 type Token = { kind: "word"; value: string } | { kind: "op"; op: string };
 
 /** Turns unquoted newlines into `;` (and joins backslash continuations) so shell-quote sees every command. */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: a shell lexer is one flat branch per character class; splitting it would scatter a single state machine across helpers
+// biome-ignore-start lint/complexity/noExcessiveCognitiveComplexity: a shell lexer is one flat branch per character class; splitting it would scatter a single state machine across helpers
+// pi-lens-ignore: high-complexity -- a shell lexer is one flat branch per character class; splitting it would scatter one state machine across helpers
 function splitLines(command: string): string {
   let out = "";
   let quote: "'" | '"' | undefined;
@@ -155,6 +156,7 @@ function splitLines(command: string): string {
   }
   return out;
 }
+// biome-ignore-end lint/complexity/noExcessiveCognitiveComplexity: end of the shell lexer above
 
 /** Boundary decode of shell-quote's output into domain tokens; globs count as words. */
 function tokenize(command: string): Token[] {

package/src/gates/commit-guard.ts

@@ -174,7 +174,7 @@ const stagedThenEdited = (
   // re-staged from the work tree, which was reviewed. Message text is one argument and never equals a path.
   const named = upto
     .filter((i) => (i.sub === "commit" || i.sub === "add") && !isDryRun(i) && inThisDir(i, cwd))
-    .flatMap((i) => i.args.filter((a) => !a.startsWith("-")).map(cleanPath));
+    .flatMap((i) => i.args.flatMap((a) => (a.startsWith("-") ? [] : [cleanPath(a)])));
   const covered = (name: string) => named.some((n) => name === n || name.startsWith(`${n}/`));
   return names.staged.filter(
     (name) => names.unstaged.includes(name) && !covered(name) && !DECISION_LOG.test(name),

package/src/gates/departure-use.ts

@@ -1,8 +1,13 @@
-import type { GateId } from "../core/types.ts";
+import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { SessionState } from "../state/session-state.ts";
 
 /** Open recorded departures for one soft gate: whether one applies now, and spending a once-scoped one. */
-export type DepartureUse = { hasOpen(): boolean; consume(): void };
+export type DepartureUse = {
+  hasOpen(): boolean;
+  consume(): void;
+  /** True when an open departure covers this call; spends it when it is once-scoped. */
+  covers(): boolean;
+};
 
 export function departureUse(state: SessionState, gate: GateId): DepartureUse {
   const applicable = () => {
@@ -11,18 +16,31 @@ export function departureUse(state: SessionState, gate: GateId): DepartureUse {
       (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
     );
   };
-  return {
-    hasOpen: () => applicable().length > 0,
-    consume() {
-      const open = applicable();
-      // A broader departure covers the call without being spent; only a lone once-scoped one is used up.
-      if (open.some((d) => d.scope.kind !== "once")) return;
-      const used = open[0];
-      if (used === undefined) return;
-      state.update((s) => ({
-        ...s,
-        openDepartures: s.openDepartures.filter((d) => d.id !== used.id),
-      }));
-    },
+  const hasOpen = () => applicable().length > 0;
+  const consume = () => {
+    const open = applicable();
+    // A broader departure covers the call without being spent; only a lone once-scoped one is used up.
+    if (open.some((d) => d.scope.kind !== "once")) return;
+    const used = open[0];
+    if (used === undefined) return;
+    state.update((s) => ({
+      ...s,
+      openDepartures: s.openDepartures.filter((d) => d.id !== used.id),
+    }));
   };
+  const covers = () => {
+    if (!hasOpen()) return false;
+    consume();
+    return true;
+  };
+  return { hasOpen, consume, covers };
+}
+
+/** The parsed gate id with its departures; `undefined` when the id is malformed (the guard stays off). */
+export function openGate(
+  state: SessionState,
+  id: string,
+): { gate: GateId; departure: DepartureUse } | undefined {
+  const gate = parseGateId(id);
+  return isParseError(gate) ? undefined : { gate, departure: departureUse(state, gate) };
 }

package/src/gates/lint-suppression-guard.ts

@@ -10,9 +10,8 @@ import { findUnreasonedSuppressions, MIN_RATIONALE } from "../core/lint-suppress
 import { classifyPath } from "../core/path-class.ts";
 import { normalizeRepoPath } from "../core/test-paths.ts";
 import { applyEdits, normalizeText } from "../core/test-weakening.ts";
-import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { departureUse } from "./departure-use.ts";
+import { openGate } from "./departure-use.ts";
 
 export type LintSuppressionGuardDeps = { pi: ExtensionAPI; state: SessionState };
 
@@ -54,20 +53,16 @@ function resultingText(
  * (at least {@link MIN_RATIONALE} characters) or a recorded departure.
  */
 export function registerLintSuppressionGuard(deps: LintSuppressionGuardDeps): void {
-  const parsed = parseGateId(GATE_ID);
-  if (isParseError(parsed)) return;
-  const gate: GateId = parsed;
-  const departure = departureUse(deps.state, gate);
+  const opened = openGate(deps.state, GATE_ID);
+  if (opened === undefined) return;
+  const { departure } = opened;
 
   deps.pi.on("tool_call", (event, ctx) => {
     const change = resultingText(event, ctx.cwd);
     if (change === undefined) return undefined;
     const found = findUnreasonedSuppressions(change.before, change.after);
     if (found.length === 0) return undefined;
-    if (departure.hasOpen()) {
-      departure.consume();
-      return undefined;
-    }
+    if (departure.covers()) return undefined;
     const list = found.map((s) => `${s.marker} (line ${s.line})`).join(", ");
     return {
       block: true,

package/src/gates/red-first-guard.ts

@@ -4,9 +4,8 @@ import { resolve } from "node:path";
 import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import { classifyPath } from "../core/path-class.ts";
 import { normalizeRepoPath } from "../core/test-paths.ts";
-import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { departureUse } from "./departure-use.ts";
+import { openGate } from "./departure-use.ts";
 
 export type RedFirstGuardDeps = { pi: ExtensionAPI; state: SessionState };
 
@@ -63,10 +62,9 @@ const JUDGED_EXEMPTIONS =
  * judged exemptions go through one recorded departure, which covers its whole slice.
  */
 export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
-  const parsed = parseGateId(GATE_ID);
-  if (isParseError(parsed)) return;
-  const gate: GateId = parsed;
-  const departure = departureUse(deps.state, gate);
+  const opened = openGate(deps.state, GATE_ID);
+  if (opened === undefined) return;
+  const { departure } = opened;
 
   deps.pi.on("tool_call", (event, ctx) => {
     if (!(isToolCallEventType("edit", event) || isToolCallEventType("write", event)))
@@ -77,10 +75,7 @@ export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
     const path = normalizeRepoPath(ctx.cwd, event.input.path, homedir());
     if (classifyPath(path) !== "source") return undefined;
     if (touchesInlineTest(event.input, () => existing(ctx.cwd, path))) return undefined;
-    if (departure.hasOpen()) {
-      departure.consume();
-      return undefined;
-    }
+    if (departure.covers()) return undefined;
     const seen =
       lastTestRun === undefined
         ? "no test run has been observed in this session"

package/src/gates/test-guard.ts

@@ -99,129 +99,136 @@ function jevVerdict(
     : undefined;
 }
 
+const parsedGate = (): GateId | undefined => {
+  const parsed = parseGateId(GATE_ID);
+  return isParseError(parsed) ? undefined : parsed;
+};
+
+const judge = async (
+  deps: TestGuardDeps,
+  change: Change,
+  ctx: ExtensionContext,
+): Promise<Verdict> => {
+  const deleted = change.after === undefined && change.rewritten === undefined;
+  const after = change.after ?? change.rewritten ?? "";
+  const signals = deleted ? NO_SIGNALS : weakeningSignals(change.before, after);
+  if (!deleted && isHarmlessAddition(change.before, after, signals)) return { kind: "allow" };
+  const deterministic = describeSignals(deleted, signals);
+  const judged = await judgeTestChange(deps.jev(ctx), {
+    path: change.path,
+    before: change.before,
+    after: after === "" ? undefined : redactSecrets(after),
+  });
+  const fromJev = judged.ok ? jevVerdict(judged.value, deterministic !== undefined) : undefined;
+  if (fromJev !== undefined) return fromJev;
+  return deterministic !== undefined
+    ? { kind: "require-departure", why: `this change ${deterministic}` }
+    : { kind: "allow" };
+};
+
+const bashChanges = (command: string, cwd: string): Change[] =>
+  bashMutations(command).flatMap(({ path: written, kind }): Change[] => {
+    const target = repoPath(cwd, written);
+    // Missing plain paths have nothing to weaken; globs and directories may still hide tests.
+    const touched = GLOB.test(target) || existsSync(join(cwd, target));
+    if (!(isTestPath(target) && touched)) return [];
+    const rewritten = kind === "overwrite" ? `(rewritten by shell command) ${command}` : undefined;
+    return [
+      { path: target, before: readIfExists(join(cwd, target)) ?? "", after: undefined, rewritten },
+    ];
+  });
+
+const editChange = (
+  path: string,
+  before: string,
+  edits: ReadonlyArray<{ oldText: string; newText: string }>,
+): Change => {
+  const after = applyEdits(before, edits);
+  if (after !== undefined) return { path, before, after };
+  // The edit text does not match statically; let Jev read what the agent intends to write.
+  const intended = edits.map((e) => e.newText).join("\n");
+  return { path, before, after: undefined, rewritten: `(edit not matched statically) ${intended}` };
+};
+
+const fileChanges = (event: ToolCallEvent, cwd: string): Change[] => {
+  if (!(isToolCallEventType("write", event) || isToolCallEventType("edit", event))) return [];
+  const path = repoPath(cwd, event.input.path);
+  const raw = isTestPath(path) ? readIfExists(join(cwd, path)) : undefined;
+  if (raw === undefined) return [];
+  const before = normalizeText(raw);
+  return isToolCallEventType("write", event)
+    ? [{ path, before, after: normalizeText(event.input.content) }]
+    : [editChange(path, before, event.input.edits)];
+};
+
+const collectChanges = (event: ToolCallEvent, ctx: ExtensionContext): Change[] =>
+  isToolCallEventType("bash", event)
+    ? bashChanges(event.input.command, ctx.cwd)
+    : fileChanges(event, ctx.cwd);
+
+type Call = { deps: TestGuardDeps; gate: GateId; event: ToolCallEvent; ctx: ExtensionContext };
+
+const hardStop = async (
+  { deps, gate, event, ctx }: Call,
+  change: Change,
+  why: string,
+): Promise<{ block: true; reason: string } | undefined> => {
+  const command = `${isToolCallEventType("bash", event) ? "delete" : "change"} ${change.path}`;
+  if (deps.approvals.consume(gate, command)) return undefined;
+  const outcome = await requestHardStop({
+    pi: deps.pi,
+    ctx,
+    gate,
+    command,
+    why,
+    costIfWrong: "the tests verify less behaviour, so regressions can ship undetected",
+    toolCallId: event.toolCallId,
+    now: deps.now,
+  });
+  if (outcome.kind === "approved") return undefined;
+  return {
+    block: true,
+    reason:
+      outcome.kind === "unavailable"
+        ? `hard stop ${GATE_ID}: ${why} (${change.path}); requires user approval; run interactively`
+        : `hard stop ${GATE_ID}: the user declined this change to ${change.path}. Fix the code instead of weakening the test.`,
+  };
+};
+
+const departureReason = (needing: ReadonlyArray<{ change: Change; why: string }>): string =>
+  `${GATE_ID}: ${needing[0]?.why} (${needing.map((n) => n.change.path).join(", ")}). Tests are the oracle; ` +
+  "weakening them needs a recorded decision. If this is deliberate, call devsys_record_departure " +
+  `with gate "${GATE_ID}", what you are doing instead, why, and the cost if wrong; then retry. ` +
+  "Otherwise fix the code, not the test.";
+
 /**
  * Soft gate `tests.weaken`: deleting, skipping, emptying or loosening tests needs a recorded
  * departure; a change Jev reads as gaming a failing gate escalates to a hard stop.
  */
 export function registerTestGuard(deps: TestGuardDeps): void {
-  const gate: GateId | undefined = (() => {
-    const parsed = parseGateId(GATE_ID);
-    return isParseError(parsed) ? undefined : parsed;
-  })();
+  const gate = parsedGate();
   if (gate === undefined) return;
-
   const departure = departureUse(deps.state, gate);
 
-  const judge = async (change: Change, ctx: ExtensionContext): Promise<Verdict> => {
-    const deleted = change.after === undefined && change.rewritten === undefined;
-    const after = change.after ?? change.rewritten ?? "";
-    const signals = deleted ? NO_SIGNALS : weakeningSignals(change.before, after);
-    if (!deleted && isHarmlessAddition(change.before, after, signals)) return { kind: "allow" };
-    const deterministic = describeSignals(deleted, signals);
-    const judged = await judgeTestChange(deps.jev(ctx), {
-      path: change.path,
-      before: change.before,
-      after: after === "" ? undefined : redactSecrets(after),
-    });
-    const fromJev = judged.ok ? jevVerdict(judged.value, deterministic !== undefined) : undefined;
-    if (fromJev !== undefined) return fromJev;
-    return deterministic !== undefined
-      ? { kind: "require-departure", why: `this change ${deterministic}` }
-      : { kind: "allow" };
-  };
-
-  const collectChanges = (event: ToolCallEvent, ctx: ExtensionContext): Change[] => {
-    if (isToolCallEventType("bash", event)) {
-      const { command } = event.input;
-      return bashMutations(command).flatMap(({ path: written, kind }): Change[] => {
-        const target = repoPath(ctx.cwd, written);
-        // Missing plain paths have nothing to weaken; globs and directories may still hide tests.
-        const touched = GLOB.test(target) || existsSync(join(ctx.cwd, target));
-        if (!(isTestPath(target) && touched)) return [];
-        const rewritten =
-          kind === "overwrite" ? `(rewritten by shell command) ${command}` : undefined;
-        return [
-          {
-            path: target,
-            before: readIfExists(join(ctx.cwd, target)) ?? "",
-            after: undefined,
-            rewritten,
-          },
-        ];
-      });
-    }
-    if (!(isToolCallEventType("write", event) || isToolCallEventType("edit", event))) return [];
-    const path = repoPath(ctx.cwd, event.input.path);
-    const raw = isTestPath(path) ? readIfExists(join(ctx.cwd, path)) : undefined;
-    if (raw === undefined) return [];
-    const before = normalizeText(raw);
-    if (isToolCallEventType("write", event)) {
-      return [{ path, before, after: normalizeText(event.input.content) }];
-    }
-    const after = applyEdits(before, event.input.edits);
-    if (after !== undefined) return [{ path, before, after }];
-    // The edit text does not match statically; let Jev read what the agent intends to write.
-    const intended = event.input.edits.map((e) => e.newText).join("\n");
-    return [
-      { path, before, after: undefined, rewritten: `(edit not matched statically) ${intended}` },
-    ];
-  };
-
-  const hardStop = async (
-    event: ToolCallEvent,
-    ctx: ExtensionContext,
-    change: Change,
-    why: string,
-  ): Promise<{ block: true; reason: string } | undefined> => {
-    const command = `${isToolCallEventType("bash", event) ? "delete" : "change"} ${change.path}`;
-    if (deps.approvals.consume(gate, command)) return undefined;
-    const outcome = await requestHardStop({
-      pi: deps.pi,
-      ctx,
-      gate,
-      command,
-      why,
-      costIfWrong: "the tests verify less behaviour, so regressions can ship undetected",
-      toolCallId: event.toolCallId,
-      now: deps.now,
-    });
-    if (outcome.kind === "approved") return undefined;
-    return {
-      block: true,
-      reason:
-        outcome.kind === "unavailable"
-          ? `hard stop ${GATE_ID}: ${why} (${change.path}); requires user approval; run interactively`
-          : `hard stop ${GATE_ID}: the user declined this change to ${change.path}. Fix the code instead of weakening the test.`,
-    };
-  };
-
   deps.pi.on("tool_call", async (event, ctx) => {
     const verdicts: Array<{ change: Change; verdict: Verdict }> = [];
     for (const change of collectChanges(event, ctx)) {
-      verdicts.push({ change, verdict: await judge(change, ctx) });
+      verdicts.push({ change, verdict: await judge(deps, change, ctx) });
     }
     for (const { change, verdict } of verdicts) {
       if (verdict.kind !== "hard-stop") continue;
-      const blocked = await hardStop(event, ctx, change, verdict.why);
+      const blocked = await hardStop({ deps, gate, event, ctx }, change, verdict.why);
       if (blocked !== undefined) return blocked;
     }
     const needing = verdicts.flatMap(({ change, verdict }) =>
       verdict.kind === "require-departure" ? [{ change, why: verdict.why }] : [],
     );
-    const first = needing[0];
-    if (first === undefined) return undefined;
+    if (needing.length === 0) return undefined;
     if (departure.hasOpen()) {
       // One departure covers every path in this single tool call.
       departure.consume();
       return undefined;
     }
-    return {
-      block: true,
-      reason:
-        `${GATE_ID}: ${first.why} (${needing.map((n) => n.change.path).join(", ")}). Tests are the oracle; ` +
-        "weakening them needs a recorded decision. If this is deliberate, call devsys_record_departure " +
-        `with gate "${GATE_ID}", what you are doing instead, why, and the cost if wrong; then retry. ` +
-        "Otherwise fix the code, not the test.",
-    };
+    return { block: true, reason: departureReason(needing) };
   });
 }

package/src/review/digest.ts

@@ -37,6 +37,45 @@ const PLAIN_DIFF = [
   "--ignore-submodules=dirty",
 ];
 
+type GitReads = { diff: string; stat: string; listed: string[] };
+
+const NO_OUTPUT = { code: 0, stdout: "", stderr: "" };
+
+/** The three git reads a snapshot is made of, or the error that stopped them. */
+async function readGit(exec: Exec, cwd: string, range: string): Promise<Result<GitReads, string>> {
+  // Plain, parseable output whatever the user's git config says: an external diff driver or
+  // forced colour removes the `diff --git` headers the per-file digests are cut from.
+  const [diff, stat, others] = await Promise.all([
+    exec("git", [...PLAIN_DIFF, "--full-index", "--no-renames", range], { cwd, timeout: 15_000 }),
+    exec("git", [...PLAIN_DIFF, "--stat", range], { cwd, timeout: 15_000 }),
+    // Any range that ends in the work tree (HEAD, HEAD~1, a branch) leaves untracked files out of git diff.
+    range.includes("..")
+      ? Promise.resolve(NO_OUTPUT)
+      : exec(
+          "git",
+          ["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"],
+          { cwd, timeout: 15_000 },
+        ),
+  ]);
+  if (diff.code !== 0) return err(diff.stderr.trim() || `git diff ${range} failed`);
+  if (others.code !== 0) return err(others.stderr.trim() || "git ls-files --others failed");
+  return ok({
+    diff: diff.stdout,
+    stat: stat.stdout,
+    listed: others.stdout.split("\0").filter((p) => p !== ""),
+  });
+}
+
+/** Per-file digests of the tracked diff; an unparseable non-empty diff is an error, never an empty digest. */
+function trackedDigests(diff: string): Result<Record<string, string>, string> {
+  const files: Record<string, string> = {};
+  for (const [path, text] of Object.entries(splitDiffByFile(diff))) files[path] = fileDigest(text);
+  if (diff.trim() !== "" && Object.keys(files).length === 0) {
+    return err("could not read the diff: no per-file sections were found");
+  }
+  return ok(files);
+}
+
 /**
  * The change in `range` (default `HEAD`: everything not yet committed) with its digest. `git diff`
  * leaves out untracked files, so for a range that includes the work tree they are listed and
@@ -48,41 +87,21 @@ export async function snapshotDiff(
   range: string,
 ): Promise<Result<DiffSnapshot, string>> {
   try {
-    // Plain, parseable output whatever the user's git config says: an external diff driver or
-    // forced colour removes the `diff --git` headers the per-file digests are cut from.
-    const [diff, stat, others] = await Promise.all([
-      exec("git", [...PLAIN_DIFF, "--full-index", "--no-renames", range], { cwd, timeout: 15_000 }),
-      exec("git", [...PLAIN_DIFF, "--stat", range], { cwd, timeout: 15_000 }),
-      // Any range that ends in the work tree (HEAD, HEAD~1, a branch) leaves untracked files out of git diff.
-      !range.includes("..")
-        ? exec(
-            "git",
-            ["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"],
-            { cwd, timeout: 15_000 },
-          )
-        : Promise.resolve({ code: 0, stdout: "", stderr: "" }),
-    ]);
-    if (diff.code !== 0) return err(diff.stderr.trim() || `git diff ${range} failed`);
-    if (others.code !== 0) return err(others.stderr.trim() || "git ls-files --others failed");
-    const listed = others.stdout.split("\0").filter((p) => p !== "");
+    const git = await readGit(exec, cwd, range);
+    if (!git.ok) return git;
     // A nested repository is listed as `dir/` and has no blob to hash.
-    const nested = listed.filter((p) => p.endsWith("/"));
-    const untracked = listed.filter((p) => !p.endsWith("/"));
+    const nested = git.value.listed.filter((p) => p.endsWith("/"));
+    const untracked = git.value.listed.filter((p) => !p.endsWith("/"));
     if (untracked.length > MAX_UNTRACKED) {
       return err(
         `${untracked.length} untracked files (more than ${MAX_UNTRACKED}); stage (git add) or ignore some so they can be reviewed`,
       );
     }
-    const files: Record<string, string> = {};
-    for (const [path, text] of Object.entries(splitDiffByFile(diff.stdout))) {
-      files[path] = fileDigest(text);
-    }
-    if (diff.stdout.trim() !== "" && Object.keys(files).length === 0) {
-      return err("could not read the diff: no per-file sections were found");
-    }
+    const tracked = trackedDigests(git.value.diff);
+    if (!tracked.ok) return tracked;
     const hashed = await hashUntracked(exec, cwd, untracked);
     if (!hashed.ok) return hashed;
-    Object.assign(files, hashed.value);
+    const files = { ...tracked.value, ...hashed.value };
     const names = Object.keys(files).sort((a, b) => a.localeCompare(b));
     const untrackedStat = [
       ...untracked.map((p) => ` ${p} (untracked)`),
@@ -91,8 +110,8 @@ export async function snapshotDiff(
     return ok({
       digest: digestOf(names.map((p) => `${p}\0${files[p]}`).join("\n")),
       files,
-      stat: [stat.stdout.trimEnd(), untrackedStat].filter((p) => p !== "").join("\n"),
-      sample: diff.stdout.slice(0, 16_000),
+      stat: [git.value.stat.trimEnd(), untrackedStat].filter((p) => p !== "").join("\n"),
+      sample: git.value.diff.slice(0, 16_000),
     });
   } catch (cause) {
     return err(cause instanceof Error ? cause.message : String(cause));

package/src/review/review-tools.ts

@@ -118,6 +118,92 @@ function spawnPayload(input: {
   };
 }
 
+type Reply = ReturnType<typeof reply>;
+type Config = Extract<Awaited<ReturnType<typeof loadConfig>>, { ok: true }>["value"];
+type Snapshot = Extract<Awaited<ReturnType<typeof snapshotDiff>>, { ok: true }>["value"];
+type Prepared = { slice: SliceRef; config: Config; range: string; snap: Snapshot };
+
+const requiredRounds = (config: Config): number =>
+  Math.max(config.review.requiredCleanRounds, config.review.minRounds);
+
+const rangeOf = (given: string | undefined): string => given?.trim() || "HEAD";
+
+/** The slice, config and diff snapshot both tools need, or the error reply that explains why not. */
+async function prepare(
+  deps: ReviewToolDeps,
+  ctx: ExtensionContext,
+  given: { slice?: string | undefined; diffRange?: string | undefined },
+  failure: (range: string, error: string) => string,
+): Promise<{ ok: true; value: Prepared } | { ok: false; reply: Reply }> {
+  const slice = sliceOf(given.slice, deps.state);
+  if (slice === undefined) return { ok: false, reply: reply(NO_SLICE, true) };
+  const config = await loadConfig(ctx.cwd);
+  if (!config.ok)
+    return { ok: false, reply: reply(`${CONFIG_FILE}: ${config.error.message}`, true) };
+  const range = rangeOf(given.diffRange);
+  const snap = await snapshotDiff(deps.exec, ctx.cwd, range);
+  if (!snap.ok) return { ok: false, reply: reply(failure(range, snap.error), true) };
+  return { ok: true, value: { slice, config: config.value, range, snap: snap.value } };
+}
+
+const rangeNote = (range: string): string => (range === "HEAD" ? "" : ` ${GATE_RANGE_NOTE}`);
+
+/** The reply for a round that must not start: already satisfied, or findings still open. */
+function startRefusal(review: ReviewState, p: Prepared): Reply | undefined {
+  const action = nextAction(review, p.snap.digest);
+  if (action === "done") {
+    return reply(
+      `${reviewLabel(review)}. Review of ${p.slice} is already satisfied on this diff; nothing to run.${rangeNote(p.range)}`,
+    );
+  }
+  if (action === "fix-findings") {
+    return reply(
+      `${reviewLabel(review)}. Round ${review.rounds.length} of ${p.slice} has blocking or should-fix findings and the diff has not changed since: fix them first, then start again. ` +
+        "Re-running the review on unchanged code does not clear a finding. If a finding is wrong, record a `review.unsatisfied` departure with the evidence (devsys_record_departure).",
+      true,
+    );
+  }
+  return undefined;
+}
+
+async function startRound(
+  deps: ReviewToolDeps,
+  ctx: ExtensionContext,
+  p: Prepared,
+): Promise<Reply> {
+  const judged = await judgeLenses(deps.jev(ctx), {
+    diffStat: p.snap.stat,
+    diffSample: p.snap.sample,
+    profiles: deps.state.get().profiles ?? [],
+  });
+  const { lenses, basis } = chooseLenses(judged);
+  const required = requiredRounds(p.config);
+  const existing = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
+  const review: ReviewState = { ...existing, required };
+  deps.state.update((s) => upsertReview(s, review));
+  const refusal = startRefusal(review, p);
+  if (refusal !== undefined) return refusal;
+
+  const round = review.rounds.length + 1;
+  const spawn = spawnPayload({
+    slice: p.slice,
+    round,
+    lenses,
+    range: p.range,
+    model: resolveSlot(p.config.models, "reviewer", availableModels(ctx.modelRegistry)),
+    now: deps.now?.() ?? new Date(),
+  });
+  const rangeArg = p.range === "HEAD" ? "" : ` and diffRange "${p.range}"`;
+  return reply(
+    [
+      `${reviewLabel(review)}; round ${round}; diff ${p.snap.digest}. ${basis}`,
+      `lenses: ${lenses.join(", ")}`,
+      `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with slice "${p.slice}", diffDigest "${p.snap.digest}"${rangeArg}:`,
+      JSON.stringify(spawn),
+    ].join("\n"),
+  );
+}
+
 /** `devsys_review_start`: Jev picks lenses for the diff; the reply carries the agent_spawn payload for a fresh reviewer. */
 export function createReviewStartTool(
   deps: ReviewToolDeps,
@@ -137,62 +223,16 @@ export function createReviewStartTool(
       _onUpdate,
       ctx: ExtensionContext,
     ) {
-      const slice = sliceOf(params.slice, deps.state);
-      if (slice === undefined) return reply(NO_SLICE, true);
-      const config = await loadConfig(ctx.cwd);
-      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
-      const range = params.diffRange?.trim() || "HEAD";
-      const snap = await snapshotDiff(deps.exec, ctx.cwd, range);
-      if (!snap.ok) return reply(`cannot read the diff for ${range}: ${snap.error}`, true);
-      if (snap.value.stat.trim() === "")
-        return reply(`the diff for ${range} is empty; nothing to review`, true);
-
-      const judged = await judgeLenses(deps.jev(ctx), {
-        diffStat: snap.value.stat,
-        diffSample: snap.value.sample,
-        profiles: deps.state.get().profiles ?? [],
-      });
-      const { lenses, basis } = chooseLenses(judged);
-
-      const required = Math.max(
-        config.value.review.requiredCleanRounds,
-        config.value.review.minRounds,
-      );
-      const existing = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
-      const review: ReviewState = { ...existing, required };
-      deps.state.update((s) => upsertReview(s, review));
-      const action = nextAction(review, snap.value.digest);
-      if (action === "done") {
-        return reply(
-          `${reviewLabel(review)}. Review of ${slice} is already satisfied on this diff; nothing to run.${range === "HEAD" ? "" : ` ${GATE_RANGE_NOTE}`}`,
-        );
-      }
-
-      if (action === "fix-findings") {
-        return reply(
-          `${reviewLabel(review)}. Round ${review.rounds.length} of ${slice} has blocking or should-fix findings and the diff has not changed since: fix them first, then start again. ` +
-            "Re-running the review on unchanged code does not clear a finding. If a finding is wrong, record a `review.unsatisfied` departure with the evidence (devsys_record_departure).",
-          true,
-        );
-      }
-
-      const round = review.rounds.length + 1;
-      const spawn = spawnPayload({
-        slice,
-        round,
-        lenses,
-        range,
-        model: resolveSlot(config.value.models, "reviewer", availableModels(ctx.modelRegistry)),
-        now: deps.now?.() ?? new Date(),
-      });
-      return reply(
-        [
-          `${reviewLabel(review)}; round ${round}; diff ${snap.value.digest}. ${basis}`,
-          `lenses: ${lenses.join(", ")}`,
-          `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with slice "${slice}", diffDigest "${snap.value.digest}"${range === "HEAD" ? "" : ` and diffRange "${range}"`}:`,
-          JSON.stringify(spawn),
-        ].join("\n"),
+      const prepared = await prepare(
+        deps,
+        ctx,
+        params,
+        (range, error) => `cannot read the diff for ${range}: ${error}`,
       );
+      if (!prepared.ok) return prepared.reply;
+      if (prepared.value.snap.stat.trim() === "")
+        return reply(`the diff for ${prepared.value.range} is empty; nothing to review`, true);
+      return startRound(deps, ctx, prepared.value);
     },
   };
 }
@@ -233,7 +273,82 @@ async function adjusted(
   return { findings: out, notes };
 }
 
-/** `devsys_review_record`: parse packets, let Jev adjust severities, record the round, file the nits. */
+/** Parses every packet, or the reply naming the first malformed one. */
+function parsePackets(
+  raw: readonly string[],
+): { ok: true; value: ReviewPacket[] } | { ok: false; reply: Reply } {
+  if (raw.length === 0)
+    return {
+      ok: false,
+      reply: reply("no packets: pass the reviewer's packet markdown in `packets`", true),
+    };
+  const packets: ReviewPacket[] = [];
+  for (const [i, text] of raw.entries()) {
+    const parsed = parseReviewPacket(text);
+    if (isParseError(parsed))
+      return { ok: false, reply: reply(`packet ${i + 1} is malformed: ${parsed.message}`, true) };
+    packets.push(parsed);
+  }
+  return { ok: true, value: packets };
+}
+
+/** The refusal for a packet written for another slice or round, if there is one. */
+function wrongPacket(packets: readonly ReviewPacket[], slice: SliceRef, expected: number) {
+  const wrong = packets.findIndex((p) => p.round !== expected || p.slice !== slice);
+  if (wrong === -1) return undefined;
+  return reply(
+    `packet ${wrong + 1} is for slice "${packets[wrong]?.slice}" round ${packets[wrong]?.round}; this is round ${expected} of slice "${slice}". A packet is recorded once, in the round it was written for; ask the reviewer for a packet with the right header.`,
+    true,
+  );
+}
+
+const countOf = (findings: readonly Finding[], sev: Finding["severity"]): number =>
+  findings.filter((f) => f.severity === sev).length;
+
+function recordSummary(
+  review: ReviewState,
+  findings: readonly Finding[],
+  notes: readonly string[],
+  p: Prepared,
+): string {
+  return [
+    `Round ${review.rounds.length} recorded: ${countOf(findings, "blocking")} blocking, ${countOf(findings, "should-fix")} should-fix, ${countOf(findings, "nit")} nit, ${countOf(findings, "false-positive")} false-positive.`,
+    reviewLabel(review),
+    ...notes,
+    ...nitLines(findings),
+    `next: ${nextAction(review, p.snap.digest)}`,
+    ...(p.range === "HEAD" ? [] : [GATE_RANGE_NOTE]),
+  ].join("\n");
+}
+
+async function recordRound(
+  deps: ReviewToolDeps,
+  ctx: ExtensionContext,
+  p: Prepared,
+  packets: readonly ReviewPacket[],
+): Promise<Reply> {
+  const required = requiredRounds(p.config);
+  const before = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
+  const refusal = wrongPacket(packets, p.slice, before.rounds.length + 1);
+  if (refusal !== undefined) return refusal;
+
+  const merged = combinePackets(packets);
+  const { findings, notes } = await adjusted(deps, ctx, merged.findings, p.snap.sample);
+  const review = addRound(
+    { ...before, required },
+    {
+      lenses: merged.lenses,
+      findings,
+      reviewedAt: (deps.now?.() ?? new Date()).toISOString(),
+      diffDigest: p.snap.digest,
+      files: p.snap.files,
+    },
+  );
+  deps.state.update((s) => upsertReview(s, review));
+  return reply(recordSummary(review, findings, notes, p));
+}
+
+/** `devsys_review_record`: parse packets, let Jev adjust severities, record the round. */
 export function createReviewRecordTool(
   deps: ReviewToolDeps,
 ): ToolDefinition<typeof RecordParameters> {
@@ -252,69 +367,23 @@ export function createReviewRecordTool(
       _onUpdate,
       ctx: ExtensionContext,
     ) {
-      const slice = sliceOf(params.slice, deps.state);
-      if (slice === undefined) return reply(NO_SLICE, true);
-      if (params.packets.length === 0)
-        return reply("no packets: pass the reviewer's packet markdown in `packets`", true);
-      const packets: ReviewPacket[] = [];
-      for (const [i, raw] of params.packets.entries()) {
-        const parsed = parseReviewPacket(raw);
-        if (isParseError(parsed))
-          return reply(`packet ${i + 1} is malformed: ${parsed.message}`, true);
-        packets.push(parsed);
-      }
-      const config = await loadConfig(ctx.cwd);
-      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
-      const range = params.diffRange?.trim() || "HEAD";
-      const snap = await snapshotDiff(deps.exec, ctx.cwd, range);
-      if (!snap.ok) return reply(`cannot read the diff: ${snap.error}`, true);
-
-      if (params.diffDigest !== snap.value.digest) {
-        return reply(
-          `the diff changed since the review started (reviewed ${params.diffDigest}, now ${snap.value.digest}); the reviewer did not see the current code. Run devsys_review_start again.`,
-          true,
-        );
-      }
-      const required = Math.max(
-        config.value.review.requiredCleanRounds,
-        config.value.review.minRounds,
+      if (sliceOf(params.slice, deps.state) === undefined) return reply(NO_SLICE, true);
+      const packets = parsePackets(params.packets);
+      if (!packets.ok) return packets.reply;
+      const prepared = await prepare(
+        deps,
+        ctx,
+        params,
+        (_range, error) => `cannot read the diff: ${error}`,
       );
-      const before = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
-      const expected = before.rounds.length + 1;
-      const wrong = packets.findIndex((p) => p.round !== expected || p.slice !== slice);
-      if (wrong !== -1) {
+      if (!prepared.ok) return prepared.reply;
+      if (params.diffDigest !== prepared.value.snap.digest) {
         return reply(
-          `packet ${wrong + 1} is for slice "${packets[wrong]?.slice}" round ${packets[wrong]?.round}; this is round ${expected} of slice "${slice}". A packet is recorded once, in the round it was written for; ask the reviewer for a packet with the right header.`,
+          `the diff changed since the review started (reviewed ${params.diffDigest}, now ${prepared.value.snap.digest}); the reviewer did not see the current code. Run devsys_review_start again.`,
           true,
         );
       }
-
-      const merged = combinePackets(packets);
-      const { findings, notes } = await adjusted(deps, ctx, merged.findings, snap.value.sample);
-      const reviewed = snap.value;
-      const review = addRound(
-        { ...before, required },
-        {
-          lenses: merged.lenses,
-          findings,
-          reviewedAt: (deps.now?.() ?? new Date()).toISOString(),
-          diffDigest: reviewed.digest,
-          files: reviewed.files,
-        },
-      );
-      deps.state.update((s) => upsertReview(s, review));
-      const counts = (sev: Finding["severity"]) =>
-        findings.filter((f) => f.severity === sev).length;
-      return reply(
-        [
-          `Round ${review.rounds.length} recorded: ${counts("blocking")} blocking, ${counts("should-fix")} should-fix, ${counts("nit")} nit, ${counts("false-positive")} false-positive.`,
-          reviewLabel(review),
-          ...notes,
-          ...nitLines(findings),
-          `next: ${nextAction(review, reviewed.digest)}`,
-          ...(range === "HEAD" ? [] : [GATE_RANGE_NOTE]),
-        ].join("\n"),
-      );
+      return recordRound(deps, ctx, prepared.value, packets.value);
     },
   };
 }