@codedology/code-forge 0.10.0 → 0.11.0

package/src/review/packet.mjs

@@ -10,6 +10,7 @@
  *   ## project rules   the rules digest (≤ 60 lines)
  *   ## facts           the facts-sheet excerpt
  *   ## context         the current file (whole, or hunk windows — `context.mjs`)
+ *   ## paired          optional paired-file names and summary (B97), dropped first over budget
  *   ## moved code      only when code moved to/from another file of the block (`moved.mjs`, B56)
  *   ## diff            `file:`, the `hunks:` list the reviewer must echo, then the diff
  *
@@ -20,7 +21,7 @@
  * Budget (§4.3): `review.budgets.full_in` (`quick_in` for the quick lens), in tokens estimated as
  * bytes / 4. A diff that alone exceeds it ⇒ `split_required` (a Markdown file is then reviewed
  * section by section — `sections.mjs`, B54). Otherwise over budget ⇒ the context shrinks to
- * ± `min_context_lines` (`minimal`) FIRST, then the digest is trimmed from the end; the diff is
+ * ± `min_context_lines` (`minimal`) after dropping paired, then the digest is trimmed from the end; the diff is
  * never cut. The `## moved code` section (B56) is part of that measure: it is counted in the diff-only
  * size (`diffOnlyTokens`, `split_required`) and never trimmed.
  *
@@ -190,11 +191,11 @@ export async function readFileDiff({ repoRoot, file, base }) {
  * Assemble a reviewer packet (pure).
  * @param {{
  *   diff: FileDiff, lens: string, rulesDigest?: string, factsExcerpt?: string,
- *   cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', budget?: number, moved?: string,
+ *   cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', budget?: number, moved?: string, paired?: string,
  * }} opts - `moved`: the file's `## moved code` section (`moved.mjs`), '' for none.
  * @returns {Packet | {status: 'split_required', tokensIn: number, budget: number}}
  */
-export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = '', cfg, contextMode = 'auto', budget, moved = '' }) {
+export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = '', cfg, contextMode = 'auto', budget, moved = '', paired = '' }) {
   const lensText = loadLens(lens);
   const limit = budget ?? budgetFor(cfg, lens === 'quick' ? 'quick_in' : 'full_in');
   const hunkHeaders = diff.hunks.map((h) => h.header);
@@ -204,7 +205,12 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
 
   let digest = splitLines(rulesDigest).slice(0, DIGEST_MAX_LINES);
   let ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: contextMode });
-  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+  let pairedSection = boundedPaired(paired, budgetFor(cfg, 'full_in'));
+  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection);
+  if (estimateTokens(text) > limit && pairedSection.length > 0) {
+    pairedSection = '';
+    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+  }
   if (estimateTokens(text) > limit) {
     ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: 'minimal' });
     text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
@@ -217,6 +223,22 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   return { status: 'ok', text, hunkHeaders, contextMode: ctx.mode, contextLines: ctx.lineCount, digestLines: digest.length, tokensIn, budget: limit, overBudget: tokensIn > limit };
 }
 
+/** Cap the entire section at full_in / 16 tokens, without cutting a UTF-8 character.
+ * @param {string} paired @param {number} fullIn @returns {string}
+ */
+function boundedPaired(paired, fullIn) {
+  if (paired.trim().length === 0) return '';
+  const heading = '## paired\n';
+  let left = Math.floor(fullIn / 16) * 4 - Buffer.byteLength(heading) - 1;
+  let body = '';
+  for (const char of paired) {
+    left -= Buffer.byteLength(char);
+    if (left < 0) break;
+    body += char;
+  }
+  return body.length > 0 ? heading + body.trimEnd() : '';
+}
+
 /**
  * The tokens of the diff-only packet (lens + moved code + diff, no digest, facts or context): what
  * `assemblePacket` holds against the budget before it says `split_required`. Pass the SAME `moved`
@@ -244,8 +266,9 @@ function diffSectionOf(diff) {
 /**
  * @param {string} lensText @param {string[]} digest @param {string} facts @param {string} context
  * @param {string} diffSection @param {string} [moved] - the `## moved code` section (heading included), '' for none.
+ * @param {string} [paired] - the bounded `## paired` section (heading included).
  */
-function render(lensText, digest, facts, context, diffSection, moved = '') {
+function render(lensText, digest, facts, context, diffSection, moved = '', paired = '') {
   return [
     '# code-forge review packet',
     '## lens',
@@ -256,6 +279,7 @@ function render(lensText, digest, facts, context, diffSection, moved = '') {
     facts.trim().length > 0 ? facts.trimEnd() : '(none)',
     '## context',
     context.length > 0 ? context : '(none)',
+    ...(paired.length > 0 ? [paired] : []),
     ...(moved.length > 0 ? [moved] : []),
     '## diff',
     diffSection,
@@ -319,9 +343,10 @@ function readRepoText(repoRoot, rel) {
 
 /**
  * Why `rel` may not be attached, or null.
- * @param {string} repoRoot @param {string} rel @returns {Promise<string | null>}
+ * @param {string} repoRoot @param {string} rel @param {ReadonlyArray<string>} ownedFiles
+ * @param {ReadonlyArray<string>} changedFiles @returns {Promise<string | null>}
  */
-async function attachRefusal(repoRoot, rel) {
+async function attachRefusal(repoRoot, rel, ownedFiles, changedFiles) {
   if (isSecretLike(rel)) return 'refused: secret-like path';
   let st;
   try {
@@ -330,20 +355,29 @@ async function attachRefusal(repoRoot, rel) {
     return 'missing';
   }
   if (!st.isFile()) return 'not a file';
-  const res = await exec(['git', 'ls-files', '-z', '--error-unmatch', '--', rel], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GIT_TIMEOUT_MS });
-  if (res.result !== 'ok' || res.stdout.length === 0) return 'refused: not tracked by git';
+  const res = await exec(['git', 'ls-files', '-z', '--', rel], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') return 'refused: git failed';
+  if (res.stdout === `${rel}\0`) return null;
+  if (res.stdout.length > 0) return 'refused: git failed';
+  if (!ownedFiles.includes(rel)) return 'refused: untracked, not owned by this block';
+  if (!changedFiles.includes(rel)) return 'refused: untracked, not changed in this block';
+  const ignored = await exec(['git', 'check-ignore', '-q', '--', rel], { cwd: repoRoot, env: plainGitEnv(), timeoutMs: GIT_TIMEOUT_MS, okExitCodes: [0, 1] });
+  if (ignored.result !== 'ok' || (ignored.code !== 0 && ignored.code !== 1)) return 'refused: git failed';
+  if (ignored.code === 0) return 'refused: gitignored';
   return null;
 }
 
 /**
  * The `needs_file` follow-up (§4.2): the requested files, read-only, appended AFTER the packet
- * (the stable prefix stays stable). Only regular files git TRACKS are attached — an untracked or
- * ignored file (`.env`, a key) never reaches a provider — and secret-like paths are refused even
+ * (the stable prefix stays stable). Regular tracked files, or untracked files present in BOTH
+ * concrete path lists of this block, are attached. Ignored untracked files never reach a provider,
+ * and secret-like paths are refused even
  * when tracked; every refusal is named in the section. The attachment is trimmed to `budgetTokens`.
- * @param {{repoRoot: string, paths: ReadonlyArray<unknown>, budgetTokens: number}} opts
+ * @param {{repoRoot: string, paths: ReadonlyArray<unknown>, budgetTokens: number, ownedFiles?: ReadonlyArray<string>, changedFiles?: ReadonlyArray<string>}} opts
+ * `ownedFiles` and `changedFiles`: resolved paths from the SAME block in this repoRoot; no globs.
  * @returns {Promise<string>} the section to append.
  */
-export async function attachFiles({ repoRoot, paths, budgetTokens }) {
+export async function attachFiles({ repoRoot, paths, budgetTokens, ownedFiles = [], changedFiles = [] }) {
   const out = ['## attached files (read-only, requested in needs_file)'];
   let left = budgetTokens * 4;
   for (const raw of paths.slice(0, 10)) {
@@ -356,7 +390,7 @@ export async function attachFiles({ repoRoot, paths, budgetTokens }) {
       out.push(notFile ? `### ${String(raw)} (not a file)` : '### (refused: not a repo-relative path)');
       continue;
     }
-    const refusal = await attachRefusal(repoRoot, rel);
+    const refusal = await attachRefusal(repoRoot, rel, ownedFiles, changedFiles);
     if (refusal) {
       out.push(`### ${rel} (${refusal})`);
       continue;

package/src/review/paired.mjs

@@ -0,0 +1,80 @@
+/** Stem pairs and bounded names for closed-book review packets (B97). No file reads. */
+import path from 'node:path';
+import { findSecret } from '../util/gh.mjs';
+import { redact } from '../util/redact.mjs';
+
+/** @param {string} file */
+function identity(file) {
+  if (typeof file !== 'string' || file.startsWith('/') || /[\\\x00-\x1f]/.test(file) || file.split('/').some((s) => s === '.' || s === '..' || s === '')) return null;
+  const ext = path.posix.extname(file);
+  let stem = path.posix.basename(file, ext);
+  let test = /(^|\/)(?:test|tests)\//.test(file);
+  if (ext === '.mjs' || ext === '.ts') {
+    if (/\.(test|spec)$/.test(stem)) { test = true; stem = stem.replace(/\.(test|spec)$/, ''); }
+  } else if (ext === '.php') {
+    if (stem.endsWith('Test')) { test = true; stem = stem.slice(0, -4); }
+  } else if (ext === '.go') {
+    if (stem.endsWith('_test')) { test = true; stem = stem.slice(0, -5); }
+  } else if (ext === '.py') {
+    if (stem.startsWith('test_')) { test = true; stem = stem.slice(5); }
+  } else if (ext === '.swift') {
+    if (stem.endsWith('Tests')) { test = true; stem = stem.slice(0, -5); }
+  } else return null;
+  return { ext, stem, test };
+}
+
+/** @param {string} file @param {ReadonlyArray<string>} candidates @returns {string[]} */
+export function pairsFor(file, candidates) {
+  const source = identity(file);
+  if (!source) return [];
+  return [...new Set(candidates)].filter((candidate) => {
+    const other = identity(candidate);
+    return candidate !== file && other?.ext === source.ext && other.stem === source.stem && other.test !== source.test;
+  });
+}
+
+/**
+ * A best-effort list, not a parser or proof of coverage. Names only, never function bodies.
+ * Redact before truncating so a token crossing the 120-character boundary cannot leak.
+ * @param {string} text @param {string} file @returns {string[]}
+ */
+export function summarize(text, file) {
+  const id = identity(file);
+  if (!id) return [];
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const line of text.split(/\r?\n/)) {
+    /** @type {RegExpMatchArray | null} */
+    let match = null;
+    if (id.test) {
+      if (id.ext === '.mjs' || id.ext === '.ts' || id.ext === '.php') {
+        match = line.match(/^\s*(?:await\s+)?(?:test|it)(?:\.(?:only|skip|todo))?\(\s*(['"`])([^\r\n]+?)\1/);
+        if (match) { names.add(match[2]); match = null; }
+        else if (id.ext === '.php') match = line.match(/^\s*(?:(?:public|protected)\s+)?function\s+(test\w+)\s*\(/);
+        else continue;
+      } else if (id.ext === '.go') match = line.match(/^\s*func\s+(Test\w+)\s*\(/);
+      else if (id.ext === '.py') match = line.match(/^\s*(?:async\s+)?def\s+(test_\w+)\s*\(/);
+      else if (id.ext === '.swift') match = line.match(/^\s*func\s+(test\w+)\s*\(/);
+    } else {
+      if (id.ext === '.mjs' || id.ext === '.ts') {
+        match = line.match(/^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+(\w+)/);
+        const list = line.match(/^\s*export\s*\{([^}]+)\}/);
+        if (list) {
+          for (const item of list[1].split(',')) {
+            const symbol = item.trim().match(/^(?:type\s+)?(\w+)(?:\s+as\s+(\w+))?$/);
+            if (symbol) names.add(symbol[2] ?? symbol[1]);
+          }
+        }
+      } else if (id.ext === '.php') match = line.match(/^\s*(?:(?:public|protected|private|static|final|abstract)\s+)*(?:function|class|interface|trait)\s+(\w+)/);
+      else if (id.ext === '.go') match = line.match(/^\s*(?:func\s+(?:\([^)]*\)\s+)?|(?:type|var|const)\s+)([A-Z]\w*)/);
+      else if (id.ext === '.py') match = line.match(/^\s*(?:async\s+)?(?:def|class)\s+([a-zA-Z]\w*)/);
+      else if (id.ext === '.swift') match = line.match(/^\s*(?:public|open)\s+(?:final\s+)?(?:func|class|struct|enum|protocol|let|var)\s+(\w+)/);
+    }
+    if (match) names.add(match[1]);
+    if (names.size >= 40) break;
+  }
+  return [...names].slice(0, 40).map((name) => {
+    const safe = redact(name);
+    return Array.from(findSecret(safe) ? '[REDACTED]' : safe).slice(0, 120).join('');
+  });
+}

package/src/review/reviewed-lines.mjs

@@ -0,0 +1,94 @@
+/**
+ * B96 (E1): the close report is built by the tool. After the review gate passed (`reviewGateCheck`
+ * over `checkBlockReviews`), every file the gate checked is accepted at its current hash, either
+ * by a signed `review.approved` row or — the gate's `waivedAll` list (B70/B71) — because every
+ * finding its review left open was waived or answered. This module turns that verdict into one
+ * line per file: `{file, ticket, via}`, `via` one of `approved`, `waiver`, `answered`, and
+ * `ticket` the queue's ticket for that file and hash (the caller passes `ticketOf`, the queue's
+ * own rule: `src/review` never imports the worker). It never re-decides the acceptance: the gate
+ * is the only judge, and a file the gate did not accept is never passed here.
+ *
+ * It also reads the coder's hand lines (`reviewed <path> ticket <id>`), to name a hand line that
+ * names another ticket (D1: a warning, the tool lines are the record).
+ *
+ * Its warnings (`onNoTicket`, `onBadTicket`) are callbacks: the close holds what they report and
+ * prints it only when the block closes (src/cli/block.mjs).
+ */
+
+/** @typedef {'approved' | 'waiver' | 'answered'} Via */
+/** @typedef {{file: string, ticket: string, via: Via}} ReviewedLine */
+
+/**
+ * The `via` of a file the gate accepted, read from the gate's own record (`WaivedAll`, built by
+ * `waivedAllOf` in gate-check.mjs): no record at the same hash ⇒ `approved` (a signed approval);
+ * a record whose `by` is null ⇒ `answered` (the gate sets `by` to null exactly when every open
+ * finding was answered); any other `by` (`human` or `autopilot`) ⇒ `waiver` — also for a file
+ * with some findings answered and at least one waived (the waiver is what a human or a grant
+ * decided, so the line names it).
+ * @param {import('./gate-check.mjs').WaivedAll | undefined} record @returns {Via}
+ */
+export function viaOf(record) {
+  if (record === undefined) return 'approved';
+  return record.by === null ? 'answered' : 'waiver';
+}
+
+/** A ticket id as the queue gives it: 24 lowercase hex characters (`assertTicketId`). */
+const TICKET_ID = /^[0-9a-f]{24}$/;
+
+/**
+ * The tool's reviewed lines, sorted by file. Pure but for `onNoTicket` and `onBadTicket`.
+ * @param {{
+ *   files: ReadonlyArray<{file: string, content_hash: string}>,
+ *   waivedAll: ReadonlyArray<import('./gate-check.mjs').WaivedAll>,
+ *   ticketOf: (file: {file: string, content_hash: string}) => unknown,
+ *   onNoTicket?: (file: string) => void,
+ *   onBadTicket?: (file: string) => void,
+ * }} opts `files`: the files the review gate checked and ACCEPTED (it passed); `waivedAll`: the
+ *   gate's `reviewed_by_waiver` files ({@link viaOf}); every other file passed through a signed
+ *   approval. `ticketOf`: the queue's ticket for that file at that hash, or null (or undefined)
+ *   when it cannot be given — then the file has no line (fail closed) and `onNoTicket(file)` is
+ *   called once. Any other value that is not 24 lowercase hex characters (a string of another
+ *   shape, a number…) is a bad ticket: the file has no line either and `onBadTicket(file)` is
+ *   called once instead.
+ * @returns {ReviewedLine[]}
+ */
+export function reviewedLines({ files, waivedAll, ticketOf, onNoTicket = () => {}, onBadTicket = () => {} }) {
+  /** @type {ReviewedLine[]} */
+  const lines = [];
+  for (const f of files) {
+    const via = viaOf(waivedAll.find((w) => w.file === f.file && w.content_hash === f.content_hash));
+    const ticket = ticketOf(f);
+    if (ticket === null || ticket === undefined) onNoTicket(f.file);
+    else if (typeof ticket === 'string' && TICKET_ID.test(ticket)) lines.push({ file: f.file, ticket, via });
+    else onBadTicket(f.file);
+  }
+  return lines.sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0));
+}
+
+/**
+ * A hand line: exactly `reviewed <path> ticket <id>` once trimmed, with backticks dropped and an
+ * optional leading list marker (`- `, `* ` or a number and a dot, `1. `). The id is 24 hex
+ * characters of either case: a ticket id is lowercase, so an id in capitals is read here and then
+ * never equals the tool's ticket ({@link reportMismatches} compares exactly).
+ */
+const HAND_LINE = /^(?:(?:[-*]|\d{1,9}\.)\s+)?reviewed\s+(\S+)\s+ticket\s+([0-9a-fA-F]{24})$/;
+
+/**
+ * D1: the files whose hand line in `report` names a ticket id other than the tool's (compared
+ * exactly, so an id in capitals is another ticket). Only a `reviewed <path> ticket <id>` line
+ * counts ({@link HAND_LINE}); a hash of another length, or a line of any other shape that names
+ * the file, never does.
+ * @param {string} report @param {ReadonlyArray<ReviewedLine>} lines
+ * @returns {string[]} the files with a mismatched hand line, in the order of `lines`.
+ */
+export function reportMismatches(report, lines) {
+  /** @type {Set<string>} */
+  const other = new Set();
+  for (const raw of report.split('\n')) {
+    const m = HAND_LINE.exec(raw.replaceAll('`', '').trim());
+    if (m === null) continue;
+    const line = lines.find((l) => l.file === m[1]);
+    if (line !== undefined && line.ticket !== m[2]) other.add(line.file);
+  }
+  return lines.filter((l) => other.has(l.file)).map((l) => l.file);
+}

package/src/state/block-end.mjs

@@ -54,11 +54,13 @@ function safeId(id) {
  * @param {{
  *   block: string, runId: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
  *   commit: string | null, spend: {usd: number, unknown: number} | null, findings: number | null, at: Date,
- * }} facts
+ *   reviewed?: ReadonlyArray<{file: string, ticket: string, via: string}>,
+ * }} facts `reviewed` (B96): the close's reviewed lines, sorted by file; the key is added last, and only when given.
  * @returns {{block: string, run_id: string, status: string, event: string, reason: string | null, commit: string | null,
- *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string}}
+ *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string,
+ *   reviewed?: Array<{file: string, ticket: string, via: string}>}}
  */
-export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at }) {
+export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at, reviewed }) {
   return {
     block,
     run_id: runId,
@@ -71,6 +73,7 @@ export function doneFileContent({ block, runId, status, event, reason = null, co
     unknown_usd_sessions: spend && Number.isInteger(spend.unknown) ? spend.unknown : null,
     findings: Number.isInteger(findings) ? findings : null,
     at: at.toISOString(),
+    ...(Array.isArray(reviewed) ? { reviewed: reviewed.map((r) => ({ file: r.file, ticket: r.ticket, via: r.via })).sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0)) } : {}),
   };
 }
 
@@ -97,12 +100,13 @@ async function headCommit(cwd) {
  * @param {{
  *   record: Record<string, any>, id: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
  *   openFindings: (rows: Record<string, any>[]) => Promise<number>, err: (s: string) => unknown, now?: Date,
+ *   reviewed?: ReadonlyArray<{file: string, ticket: string, via: string}>,
  * }} opts - `record` is the run record read before the end (its `workspace` and the block's
  *   `worktree` do not change at an end); `openFindings` counts the block's open findings exactly
- *   as `code-forge status` does.
+ *   as `code-forge status` does. `reviewed` (B96): the close's reviewed lines, kept as the last key.
  * @returns {Promise<string | null>} the done file's absolute path, or null when it was not written.
  */
-export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date() }) {
+export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date(), reviewed }) {
   const runId = String(record?.run_id);
   try {
     const file = doneFilePath(runId, id);
@@ -127,7 +131,7 @@ export async function writeDoneFile({ record, id, status, event, reason = null,
     }
     const tree = record.blocks?.[id]?.worktree?.path;
     const commit = await headCommit(typeof tree === 'string' && tree.length > 0 ? tree : record.workspace);
-    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now });
+    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now, ...(reviewed === undefined ? {} : { reviewed }) });
     const dir = path.dirname(file);
     await mkdir(dir, { recursive: true, mode: 0o700 });
     const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);

package/src/worker/engine.mjs

@@ -42,7 +42,7 @@
  * second `schema` miss — this round's first try after the earlier ticket's — is tried once on
  * `review.second_levels.<level>` when one is configured.
  * B56: every round gets ONE memoised reader of the block's OTHER changed files' diffs
- * (`blockPeerDiffs`: listed and read at most once per ticket) so the review can name code moved
+ * (the ticket's `fileContext`: listed once, diffs read lazily at most once per ticket) so the review can name code moved
  * between them in a `## moved code` packet section (round 1, rechecks and patch check alike).
  * The review NEVER approves an empty or failed session: that is `unavailable` (§4.2 stub guard).
  * A throw inside the round is `unavailable` too, with the state saved as `next: retry` (see
@@ -169,14 +169,14 @@ import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } fro
  * `tree` (B62b) is the recorded `worktree` `{path, branch, base_sha}`, null when the block has
  * none; `base` is then the tree's `base_sha`. A recorded worktree that `worktreeRecord` refuses
  * (path, branch, hex base_sha) throws `worktree-malformed`.
- * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, acceptance?: unknown, kind: string | null, tree: WorktreeEntry | null, workspace: string | null}>}
+ * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, testFiles: string[], acceptance?: unknown, kind: string | null, tree: WorktreeEntry | null, workspace: string | null}>}
  */
 export async function blockEntryFor(runId, block) {
   let record;
   try {
     record = await readRun(runId);
   } catch (err) {
-    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, acceptance: undefined, kind: null, tree: null, workspace: null };
+    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, testFiles: [], acceptance: undefined, kind: null, tree: null, workspace: null };
     throw new Error('run-record-unreadable');
   }
   if (!record || typeof record !== 'object' || !record.blocks || typeof record.blocks !== 'object') throw new Error('run-record-unreadable');
@@ -187,6 +187,7 @@ export async function blockEntryFor(runId, block) {
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files.filter((f) => typeof f === 'string') : [];
   const kinds = entry.owned_kinds;
   const ownedKinds = kinds && typeof kinds === 'object' && !Array.isArray(kinds) ? kinds : {};
+  const testFiles = Array.isArray(entry.test_files) ? entry.test_files.filter((f) => typeof f === 'string' && !/[*?\[\]{}]/.test(f) && ownsFile(owned, f, ownedKinds)) : [];
   /** @type {WorktreeEntry | null} */
   let tree = null;
   if (entry.worktree !== undefined && entry.worktree !== null) {
@@ -196,10 +197,11 @@ export async function blockEntryFor(runId, block) {
       throw new Error('worktree-malformed');
     }
   }
-  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
+  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, testFiles, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
 }
 
 /** @typedef {{path: string, branch: string, base_sha: string}} WorktreeEntry */
+/** @typedef {{peers: string[], changedFiles: string[], ownedFiles: string[], testFiles: string[]}} FileContext */
 
 /** The refusals of {@link blockTree} a ticket answers with, as its `reason`. */
 const TREE_CODES = new Set(['worktree-malformed', 'worktree-missing', 'worktree-not-dir', 'worktree-branch-mismatch', 'worktree-workspace-missing', 'worktree-foreign', 'git-failed']);
@@ -373,7 +375,28 @@ export async function reviewTicket(ticket, ctx) {
     }
   }
   const factsExcerpt = factsFor(entry, ctx.cfg);
-  const peerDiffs = blockPeerDiffs(contentRoot, { base: entry.base, owned: entry.owned, ownedKinds: entry.ownedKinds, file: ticket.file });
+  // Resolve concrete paths in this block's tree; neither globs nor another block's tests
+  // authorize an untracked attachment. Read lazily so a stopped ticket needs no file listing.
+  /** @type {Promise<FileContext> | undefined} */
+  let contextOnce;
+  /** @type {() => Promise<import('../review/moved.mjs').PeerDiff[]>} */
+  let readDiffs = () => Promise.resolve([]);
+  const fileContext = () => contextOnce ??= (async () => {
+    try {
+      // Read the listing directly: blockPeers' [] fallback would hide a git failure and
+      // still authorize explicit tests. Context and peer diffs must fail soft together.
+      const peers = entry.base === null || entry.owned.length === 0 ? [] : (await computeFileSet({ cwd: contentRoot, base: entry.base })).all.filter((f) => f !== ticket.file && ownsFile(entry.owned, f, entry.ownedKinds));
+      readDiffs = peerDiffReader({ repoRoot: contentRoot, base: entry.base, file: ticket.file, peers });
+      const changedFiles = [...peers, ticket.file].filter((f) => ownsFile(entry.owned, f, entry.ownedKinds));
+      return { peers, changedFiles, ownedFiles: [...new Set([...changedFiles, ...entry.testFiles])], testFiles: entry.testFiles };
+    } catch {
+      return { peers: [], changedFiles: [], ownedFiles: [], testFiles: [] };
+    }
+  })();
+  const peerDiffs = async () => {
+    await fileContext();
+    return readDiffs();
+  };
   try {
     // B63a: the `context` rules and lessons, read from the MAIN tree (`ctx.repoRoot`, never the
     // block's worktree) with the config in force for this ticket; '' without a `context` key, so
@@ -390,11 +413,11 @@ export async function reviewTicket(ticket, ctx) {
     const digest = rulesDigest === '' ? {} : { rulesDigest };
     if (!ctx.key) {
       return await reviewFile(
-        { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs },
+        { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs, ...(await fileContext()) },
         { spawn: ctx.spawn, ...(ctx.writeRow ? { writeRow: ctx.writeRow } : {}) },
       );
     }
-    return await fixLoopRound(ticket, tctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt, rulesDigest, peerDiffs });
+    return await fixLoopRound(ticket, tctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt, rulesDigest, peerDiffs, fileContext });
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -506,10 +529,10 @@ export function mayTakeRung(state, kind, cfg, rungUsed) {
  * first full round, or any round once the rung is gone) runs outside the block lock, in parallel
  * with the block's other files.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, rulesDigest?: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, rulesDigest?: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>, fileContext: () => Promise<FileContext>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, rulesDigest = '', peerDiffs }) {
+async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, rulesDigest = '', peerDiffs, fileContext }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
   const readRows = ctx.readRows;
   /** @type {{outcome: ReviewOutcome} | {round: () => Promise<ReviewOutcome>}} */
@@ -572,7 +595,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
       state.l3_rung_used = true; // the orchestrator ran the block's one L3 patch before this ticket
     }
     const fixed = state;
-    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest, extraRounds, peerDiffs });
+    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest, extraRounds, peerDiffs, fileContext });
     // a round that could take the rung keeps the block lock until its state is saved
     if (mayTakeRung(fixed, kind, ctx.cfg, rungUsed)) return { outcome: await round() };
     return { round };
@@ -583,10 +606,10 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
 /**
  * Run the prepared round and save the file's state: the ticket's outcome.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, rulesDigest?: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, rulesDigest?: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>, fileContext: () => Promise<FileContext>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest = '', extraRounds = 0, peerDiffs }) {
+async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest = '', extraRounds = 0, peerDiffs, fileContext }) {
   /** @type {Record<string, any> | null} */
   let engineOutcome = null;
   let approvalWritten = false;
@@ -626,6 +649,7 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     const schemaHistory = ctx.readRows
       ? ledgerSchemaHistory({ readRows: ctx.readRows, verify: (row) => verifyRow(row, where.key).ok, runId: ctx.runId, file: ticket.file, contentHash: ticket.content_hash })
       : undefined;
+    const files = await fileContext();
     await runRound(
       state,
       {
@@ -637,16 +661,20 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
         factsExcerpt,
         ...(rulesDigest !== '' ? { rulesDigest } : {}),
         extraRounds,
+        ...files,
         ...(peerDiffs ? { peerDiffs } : {}),
         ...(jev ? { jev } : {}),
         ...(schemaHistory ? { schemaHistory } : {}),
         review: async () => {
-          engineOutcome = await reviewFile({ repoRoot: ctx.contentRoot ?? ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...(rulesDigest !== '' ? { rulesDigest } : {}), ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
+          engineOutcome = await reviewFile({ repoRoot: ctx.contentRoot ?? ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...files, ...(rulesDigest !== '' ? { rulesDigest } : {}), ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
           return engineOutcome;
         },
         spawn: async (opts) => {
           const res = await ctx.spawn(opts);
-          rechecks.push({ lens: opts?.rowExtra?.lens ?? null, role: opts?.role ?? null, level: opts?.level ?? null, provider: res?.provider ?? null, model: res?.model ?? null });
+          rechecks.push({ lens: opts?.rowExtra?.lens ?? null, role: opts?.role ?? null, level: opts?.level ?? null, provider: res?.provider ?? null, model: res?.model ?? null,
+            status: res?.status ?? null, tokens_in: res?.usage?.tokens_in ?? res?.row?.tokens_in ?? null, tokens_out: res?.usage?.tokens_out ?? res?.row?.tokens_out ?? null,
+            ...(typeof res?.status === 'string' && res.status !== 'ok' ? { reason: res.reason ?? res.status } : {}),
+          });
           return res;
         },
       },
@@ -689,7 +717,7 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     return { ...head, status: 'reviewed', approved: true, findings: [] };
   }
   if (status === 'stopped') return { ...head, status: 'stopped', stopped: next?.reason ?? 'stopped', ...stopSize(state), approved: false, findings: state.open };
-  return { ...head, status: 'reviewed', approved: false, reason: 'findings-open', findings: state.open };
+  return { ...head, status: 'reviewed', approved: false, reason: next?.reason === 'no-fix-hunks' ? 'no-fix-hunks' : 'findings-open', findings: state.open };
 }
 
 /**

package/src/worker/loop.mjs

@@ -35,6 +35,8 @@
  */
 
 import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { expiryChecks } from '../autopilot/limits.mjs';
@@ -43,6 +45,7 @@ import { cacheHoursFrom, createDefaultKeyStore, resolveKey } from '../keys/store
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { spawnSession } from '../session/spawn.mjs';
 import { snapshotFor } from '../state/config-snapshot.mjs';
+import { runRecordPath } from '../state/paths.mjs';
 import { readRun, reattachWorker } from '../state/run.mjs';
 import { loadKey, signRow } from '../state/signer.mjs';
 import { logWarning } from '../util/error-log.mjs';
@@ -220,6 +223,7 @@ export function recordedVerdict(result) {
  * @property {string} slug - ledger project slug (the run record's `project`).
  * @property {Buffer} key - the run's HMAC key.
  * @property {number} [pollMs]
+ * @property {string} [guardRunRecordPath] - booted workers stop when this authoritative record disappears.
  * @property {number} [heartbeatMs] - how often `heartbeat_at` is refreshed: an integer ≥ `MIN_HEARTBEAT_MS`,
  *   else `HEARTBEAT_MS`.
  */
@@ -598,6 +602,20 @@ export async function createWorker(opts, deps = {}) {
     /** @type {Set<string>} */
     const started = new Set();
     for (;;) {
+      // One cheap stat per scheduler tick, including while tickets are in flight. Removing a
+      // test HOME (or the run record) stops new tickets; an open real run remains untouched.
+      if (!stopping && opts.guardRunRecordPath) {
+        try {
+          statSync(opts.guardRunRecordPath);
+        } catch (err) {
+          if (err.code === 'ENOENT' || err.code === 'ENOTDIR') {
+            stop();
+            // The error log lives under HOME: never write it when HOME itself is gone, or the
+            // log write would create the removed HOME again.
+            if (existsSync(os.homedir())) await logWarning({ warning: 'worker_orphan_stop', message: `run record missing: ${opts.guardRunRecordPath}` }).catch(() => null);
+          }
+        }
+      }
       if (!stopping) {
         for (const id of pendingTickets(repoRoot)) {
           if (poisoned.has(id) || started.has(id)) continue;
@@ -750,7 +768,7 @@ export async function bootWorker(opts, deps = {}) {
   const runRootDir = runRoot(opts.runId, { root: tmpRoot });
   setRunRoot(runRootDir);
   const key = await loadKey(opts.runId);
-  const worker = await createWorker({ runId: opts.runId, repoRoot, cfg, runRootDir, slug: record.project, key, pollMs: opts.pollMs }, deps);
+  const worker = await createWorker({ runId: opts.runId, repoRoot, cfg, runRootDir, slug: record.project, key, pollMs: opts.pollMs, guardRunRecordPath: runRecordPath(opts.runId) }, deps);
   return { ...worker, repoRoot, runRootDir };
 }