@codedology/code-forge 0.11.0 → 0.13.0

package/src/cli/review-file.mjs

@@ -5,6 +5,8 @@
  *   review-file --wait <ticket> [--max <90s>]      poll; prints {ticket, status: done, result} or
  *                                                  {ticket, status: pending, reason: wait_timeout}
  *                                                  when --max elapses (the review is still running)
+ *   review-file --wait-block <id> --run <id>       join owned changed files' current tickets;
+ *                                                  prints {block, files, done}; never reviews here
  *   review-file <answering file> --block <id> --answers <ids> --of <source> [--run <id>]
  *                                                  B71: enqueue an answers ticket; prints {ticket,
  *                                                  status, kind: answers, file: source, by_file, answers}
@@ -67,20 +69,22 @@
 
 import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { answersTicketId, assertAnswers, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { answersTicketId, assertAnswers, blockTickets, deliverBlockFindings, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
 import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
-import { namedOnHash } from '../review/gate-check.mjs';
+import { blockFileSet, namedOnHash } from '../review/gate-check.mjs';
 import { STOP_EXITS } from '../review/stop-exits.mjs';
 import { ownsFile } from '../state/registry.mjs';
 import { readAllRows } from '../ledger/write.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
+import { assertRunId } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
 const USAGE =
   'usage: code-forge review-file <path> --block <id> [--run <id>] [--fresh] | review-file --wait <ticket> [--max <seconds>s]\n' +
+  '       code-forge review-file --wait-block <id> --run <id> [--max <seconds>s]\n' +
   '       code-forge review-file <answering file> --block <id> --answers <id,id,…> --of <source> [--run <id>]\n';
 
 export const DEFAULT_WAIT_MS = 90_000;
@@ -355,6 +359,106 @@ export function fixList(result) {
   return out;
 }
 
+/**
+ * B100: read block scope from the workspace mirror, never the private run record. This is a
+ * progress summary, not an approval: block close still verifies the authoritative signed rows.
+ * @param {string} repoRoot @param {string} cwd @param {string} run @param {string} block
+ * @returns {Promise<{entry: Record<string, any>, tree: string}>}
+ */
+async function waitBlockScope(repoRoot, cwd, run, block) {
+  const top = await repoRootOf(cwd);
+  const candidates = new Set([repoRoot]);
+  for (let dir = realpathSync(cwd); ; dir = path.dirname(dir)) {
+    candidates.add(dir);
+    if (dir === top || dir === path.dirname(dir)) break;
+  }
+  for (const dir of candidates) {
+    let record;
+    try {
+      record = JSON.parse(readFileSync(path.join(dir, '.code-forge', 'runs', `${run}.json`), 'utf8'));
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+    }
+    const entry = record?.blocks?.[block];
+    if (record?.run_id !== run || !entry || !Array.isArray(entry.owned_files) || entry.owned_files.length === 0) {
+      throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+    }
+    const tree = (await blockTree(record.workspace, entry))?.top ?? repoRoot;
+    return { entry, tree };
+  }
+  throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+}
+
+/** A block wait reads only the marker, never review results or the signing key.
+ * @param {string} repoRoot @param {string} ticket @returns {Record<string, any> | null}
+ */
+function blockTicketMarker(repoRoot, ticket) {
+  try {
+    const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
+    if (marker?.ticket === ticket && typeof marker.status === 'string' && marker.status.length > 0) return marker;
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+  }
+  throw new WorkerError('result-unreadable', 'a ticket completion marker cannot be read');
+}
+
+/**
+ * A block wait reads only completion/delivery markers, never review results or the signing key.
+ * Re-scan current content on every poll. Deliver unseen findings of the newest earlier ticket
+ * before rechecking a blind edit; the next join queues the fix. Stopped files stay finished.
+ * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown}} opts
+ */
+async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
+  const { entry, tree } = await waitBlockScope(repoRoot, cwd, run, block);
+  const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree: realpathSync(tree) };
+  const deadline = Date.now() + maxMs;
+  let downPolls = 0;
+  const deliveredHere = new Set();
+  for (;;) {
+    const worker = liveWorker(repoRoot);
+    const live = worker?.run === run;
+    downPolls = live ? 0 : downPolls + 1;
+    const tickets = blockTickets({ repoRoot, run, block, ...where });
+    const current = await blockFileSet({ repoRoot: tree, base: entry.base_sha, owned: entry.owned_files, ownedKinds: entry.owned_kinds });
+    const files = current.map(({ file }) => {
+      const opts = { repoRoot, run, block, file, ...where };
+      const { ticket } = resolveTicket(opts);
+      const previous = tickets.filter((t) => t.file === file);
+      let present = previous.find((t) => t.ticket === ticket);
+      if (!present && previous.length > 0) {
+        const newest = previous[previous.length - 1];
+        const marker = blockTicketMarker(repoRoot, newest.ticket);
+        if (marker?.status === 'stopped') return { file, ticket: newest.ticket, status: 'done' };
+        if (marker?.status === 'reviewed' && marker.open_findings === true && live) {
+          if (deliveredHere.has(newest.ticket) || deliverBlockFindings({ repoRoot, block, file, ticket: newest.ticket })) {
+            deliveredHere.add(newest.ticket);
+            return { file, ticket: newest.ticket, status: 'findings' };
+          }
+        }
+      }
+      if (!present && previous.length > 0 && live) {
+        enqueue(opts);
+        present = { ...previous[previous.length - 1], ticket };
+      }
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : blockTicketMarker(repoRoot, ticket) ? 'done' : 'pending' };
+    });
+    if (downPolls >= 2) {
+      say({ block, files, done: false, status: 'worker_down' });
+      return 3;
+    }
+    if (live && files.every((f) => f.status === 'done' || f.status === 'findings')) {
+      say({ block, files, done: true });
+      return 0;
+    }
+    if (live && (files.some((f) => f.status === 'not_queued') || Date.now() >= deadline)) {
+      say({ block, files, done: false, reason: files.some((f) => f.status === 'not_queued') ? 'not_queued' : 'wait_timeout' });
+      return 0;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 /**
  * @param {string[]} args
  * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number, dropDone?: typeof dropDoneIf}} [deps] - `dropDone`: B75's claim, for tests.
@@ -366,10 +470,17 @@ export async function runReviewFile(args, deps = {}) {
   const say = (/** @type {Record<string, any>} */ obj) => writeSafe(stdout, `${JSON.stringify(obj)}\n`);
   const cwd = deps.cwd ?? process.cwd();
   try {
-    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max', 'answers', 'of'], booleans: ['fresh'] });
+    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'wait-block', 'max', 'answers', 'of'], booleans: ['fresh'] });
     // the queue and the worker: the main tree, also from inside a block's worktree
     const repoRoot = await mainRootOf(cwd);
 
+    if (flags['wait-block'] !== undefined) {
+      if (positionals.length > 0 || flags.block !== undefined || flags.wait !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true || typeof flags.run !== 'string') {
+        throw new WorkerError('usage', '--wait-block takes a block, --run and --max only');
+      }
+      return await waitBlock({ repoRoot, cwd, block: assertBlockId(flags['wait-block']), run: assertRunId(flags.run), maxMs: flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max), pollMs: deps.pollMs ?? POLL_MS, say });
+    }
+
     if (typeof flags.wait === 'string') {
       if (positionals.length > 0 || flags.block !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true) throw new WorkerError('usage', '--wait takes only a ticket and --max');
       const ticket = assertTicketId(flags.wait);

package/src/cli/review.mjs

@@ -48,7 +48,7 @@ import { semaphore } from '../util/locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { isAlive, listEntries, readStartTime, UNKNOWN_START_TIME } from '../util/reaper.mjs';
 import { pidsDir, runRoot, setRunRoot, tmpBase } from '../util/tmp.mjs';
-import { readWorker } from '../worker/queue.mjs';
+import { liveWorker } from '../worker/queue.mjs';
 import { gitChildEnv, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
 
 const BIN = fileURLToPath(new URL('../../bin/code-forge.mjs', import.meta.url));
@@ -288,7 +288,7 @@ async function runWorkers(repoRoot, runId) {
   } catch {
     // no record: nothing pinned
   }
-  const w = readWorker(repoRoot);
+  const w = liveWorker(repoRoot);
   if (w?.run === runId && !found.some((f) => f.pid === w.pid)) {
     found.push({ pid: w.pid, same: async () => w.start_time === UNKNOWN_START_TIME || readStartTime(w.pid) === w.start_time });
   }

package/src/config/validate.mjs

@@ -66,7 +66,7 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import schema from '../../schema/code-forge.schema.json' with { type: 'json' };
 import { redact } from '../util/redact.mjs';
-import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
@@ -484,10 +484,10 @@ function gateMessages(key, value) {
   // full-suite run would be an empty argv
   /** @param {string[]} argv @returns {string[]} */
   const tokenMessages = (argv) =>
-    argv.length === 1 && argv[0] === TEST_FILES_TOKEN
-      ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the only item (the full suite would run an empty command)`]
-      : argv[0] === TEST_FILES_TOKEN
-        ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the command (argv[0])`]
+    argv.length === 1 && [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].includes(argv[0])
+      ? [`gates.${key}: '${argv[0]}' cannot be the only item (the full suite would run an empty command)`]
+      : [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].includes(argv[0])
+        ? [`gates.${key}: '${argv[0]}' cannot be the command (argv[0])`]
         : [];
   if (typeof value !== 'object' || Array.isArray(value)) {
     if (!isArgvArray(value)) return [`gates.${key} must be a non-empty argv array of strings, an {argv, env} object, or null`];
@@ -1162,3 +1162,10 @@ export function validateConfig(cfg, opts = {}) {
 }
 
 export { schema as configSchema };
+
+/** The effective file loop for a validated config, including opt-in commit watch.
+ * @param {Record<string, any>} cfg @returns {string}
+ */
+export function reviewFileLoop(cfg) {
+  return cfg?.review?.file_loop ?? 'wait';
+}

package/src/context/pack.mjs

@@ -12,11 +12,11 @@
  *
  * `assemblePack` turns it into ONE pack for a block, in this order: the header (run, block, level,
  * owned files, test files when the block has them, worktree path and branch when it has one), the
- * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), each
- * rules file, then the lessons file — every file section headed by its source path (an empty
- * file: the heading alone). Over `max_lines` the lessons are cut first, then the
+ * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), the
+ * built-in proof rule, each rules file, then the lessons file — every file section headed by its
+ * source path (an empty file: the heading alone). Over `max_lines` the lessons are cut first, then the
  * rules from the last file backwards, each cut section ending in `[cut: N lines dropped]`; the
- * header and the commands are never cut.
+ * header, commands and proof rule are never cut; all count toward the budget.
  *
  * `reviewDigest` is the ONE builder of the review packets' rules digest (`## project rules`, ≤ 60
  * lines, `packet.mjs`): the rules files' text, then a `### lessons` subheading and the lessons.
@@ -41,6 +41,7 @@ import path from 'node:path';
 import { estimateTokens } from '../review/packet.mjs';
 import { splitLines } from '../review/context.mjs';
 import { redact } from '../util/redact.mjs';
+import { PROOF_RULE } from '../proof/rule.mjs';
 
 /** The pack's line cap when `context.max_lines` is not set. */
 export const DEFAULT_MAX_LINES = 300;
@@ -58,7 +59,7 @@ export const DIGEST_LESSONS_HEADING = '### lessons';
  * A refusal with a stable `code`. Thrown here: `bad-context` (a bad `context` value),
  * `control-character` (in a path or a header value), `outside`, `missing` (ENOENT), `unreadable`
  * (any other lstat or read error, with its code), `not-file`. Thrown by `src/cli/context.mjs`:
- * `no-block`, `bad-config`, `no-context`, `no-run-root`, `write-failed`.
+ * `no-block`, `bad-config`, `no-run-root`, `write-failed`.
  */
 export class ContextError extends Error {
   /** @param {string} code @param {string} message */
@@ -215,11 +216,12 @@ function readLines(repoRoot, rel, key) {
 
 /**
  * Every rules file and the lessons file, read. A missing or outside file is a refusal.
- * @param {string} repoRoot @param {ContextSettings} settings
+ * @param {string} repoRoot @param {ContextSettings | null} settings
  * @returns {{rules: Array<{path: string, lines: string[]}>, lessons: {path: string, lines: string[]} | null}}
  * @throws {ContextError}
  */
 export function readSources(repoRoot, settings) {
+  if (settings === null) return { rules: [], lessons: null };
   const rules = settings.rules.map((rel) => ({ path: rel, lines: readLines(repoRoot, rel, 'context.rules') }));
   const lessons = settings.lessons === null ? null : { path: settings.lessons, lines: readLines(repoRoot, settings.lessons, 'context.lessons') };
   return { rules, lessons };
@@ -248,7 +250,8 @@ export const argvText = (argv) => argv.map(argvToken).join(' ');
 
 /**
  * Build the pack text for a block (pure over what it is given).
- * @param {{settings: ContextSettings, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
+ * Missing settings give a header and proof rule only, with the default line cap.
+ * @param {{settings: ContextSettings | null, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
  * @returns {{text: string, lines: number, cut: number}} `cut`: the lines dropped.
  * @throws {ContextError} `control-character` when a header value holds one.
  */
@@ -266,11 +269,15 @@ export function assemblePack({ settings, sources, block }) {
     for (const f of block.tests) header.push(`- ${f}`);
   }
   if (block.worktree) header.push(`worktree: ${block.worktree.path}`, `branch: ${block.worktree.branch}`);
-  header.push('## commands (never run by code-forge)');
-  const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
-  if (keys.length === 0) header.push('(none)');
-  // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
-  for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+  if (settings !== null) {
+    header.push('## commands (never run by code-forge)');
+    const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
+    if (keys.length === 0) header.push('(none)');
+    // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
+    for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+  }
+
+  header.push(...splitLines(PROOF_RULE));
 
   /** @type {Array<{heading: string, body: string[], dropped: number}>} */
   const sections = sources.rules.map((r) => ({ heading: `## rules: ${r.path}`, body: [...r.lines], dropped: 0 }));
@@ -279,7 +286,7 @@ export function assemblePack({ settings, sources, block }) {
   const total = () => header.length + sections.reduce((n, s) => n + 1 + s.body.length + (s.dropped > 0 ? 1 : 0), 0);
   // cut order: the lessons first, then the rules from the last file backwards
   for (const s of [...sections].reverse()) {
-    let excess = total() - settings.maxLines;
+    let excess = total() - (settings?.maxLines ?? DEFAULT_MAX_LINES);
     if (excess <= 0) break;
     // the marker takes one line: a section is only cut when that leaves it shorter
     if (s.body.length < 2) continue;

package/src/doctor/index.mjs

@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkLocks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
 import { checkCoderSandbox, configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -67,6 +67,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   };
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
+  rows.push(...(await checkLocks()));
   rows.push(...checkTmp(cfg));
   rows.push(...(await checkReviewState(cfg)));
   rows.push(checkReviewConcurrency(cfg));

package/src/doctor/local.mjs

@@ -25,13 +25,32 @@ import { assertRunId, runsDir } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { loadKey } from '../state/signer.mjs';
 import { listEntries } from '../util/reaper.mjs';
+import { listBadLocks } from '../util/file-locks.mjs';
 import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
+import { workerRegistry } from '../worker/queue.mjs';
+import { mainRootOf } from '../worker/ticket.mjs';
 import { missingStateFiles } from '../worker/review-state.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
 
+/** @param {string} [cwd] @returns {Promise<Row[]>} */
+export async function checkLocks(cwd = process.cwd()) {
+  try {
+    const paths = listBadLocks();
+    const rows = paths.length === 0
+      ? [row('locks', 'OK', 'locks', 'no unreadable or malformed locks')]
+      : paths.map((file) => row('locks', 'WARN', 'locks', file));
+    let repoRoot = cwd;
+    try { repoRoot = await mainRootOf(cwd); } catch { /* non-repository doctor */ }
+    rows.push(...workerRegistry(repoRoot).filter((entry) => entry.worker === null).map((entry) => row('worker-registry', 'WARN', 'worker registry', entry.file)));
+    return rows;
+  } catch (err) {
+    return [row('locks', 'WARN', 'locks', `could not list locks (${err?.code ?? 'error'})`)];
+  }
+}
+
 /** The ids of the `--quick` rows, in print order. */
 export const QUICK_IDS = Object.freeze(['config', 'links', 'keys']);
 

package/src/doctor/worker-probe.mjs

@@ -11,8 +11,9 @@
  * MAC is tamper evidence within ordinary tool use, never a boundary against a same-user process.
  */
 
-import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { copyFileSync, mkdirSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
 import path from 'node:path';
+import { commandOnPath } from '../install/detect.mjs';
 import { runsDir } from '../state/paths.mjs';
 import { startRun } from '../state/run.mjs';
 import { loadKey, signRow, verifyRow } from '../state/signer.mjs';
@@ -94,7 +95,19 @@ export async function probeWorkerAndSigner(ctx) {
     const signerOk = verifyRow(signed, key).ok && verifyRow(flipped, key).reason === 'mismatch';
     rows.push(row('signer-key', signerOk ? 'OK' : 'FAIL', 'signer key', signerOk ? 'generated; a signed row verifies, a changed one is refused' : 'sign/verify round trip failed'));
 
-    const started = await launchWorker({ runId, workspace: repo, env });
+    // The boot lock needs ps even with a restricted provider PATH. Expose just that utility.
+    let workerEnv = env;
+    if (!await commandOnPath('ps', { pathEnv: env.PATH ?? '' })) {
+      const tools = path.join(repo, 'worker-tools');
+      for (const systemDir of ['/bin', '/usr/bin']) {
+        if (!await commandOnPath('ps', { pathEnv: systemDir })) continue;
+        mkdirSync(tools, { mode: 0o700 });
+        symlinkSync(path.join(systemDir, 'ps'), path.join(tools, 'ps'));
+        workerEnv = { ...env, PATH: [env.PATH, tools].filter(Boolean).join(path.delimiter) };
+        break;
+      }
+    }
+    const started = await launchWorker({ runId, workspace: repo, env: workerEnv });
     pid = started.pid;
     registerPid(pidsDir(ctx.runRootDir), pid, 'code-forge worker'); // a killed doctor's worker is reaped by the next sweep
     const announced = liveWorker(started.repoRoot)?.pid === pid;

package/src/gates/expand.mjs

@@ -1,6 +1,7 @@
 /**
  * B60 (issue #13 item 3): run only the block's related tests, and give a gate its own environment.
- * Pure — no filesystem, no child process. A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
+ * Scope and argv rules are pure; B99's fileBaseline reads bounded hashes from the workspace.
+ * A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
  * (one whole item, never a substring, never a shell string) stands for the block's test files:
  *
  *  - the block's `test_files` (`block open --tests`), else its owned entries that are concrete
@@ -20,8 +21,14 @@
  * `CI=1` or `MODE=test` would otherwise mask unrelated text (`npm test`).
  */
 
-import { isExactEntry } from '../state/registry.mjs';
-import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+import { createHash } from 'node:crypto';
+import { access, lstat, readFile, realpath } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isExactEntry, ownsFile } from '../state/registry.mjs';
+import { pairsFor } from '../review/paired.mjs';
+import { exec } from '../util/exec.mjs';
+import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 
 export { TEST_FILES_TOKEN };
 
@@ -67,6 +74,7 @@ const isConcreteFile = (p) => typeof p === 'string' && p.length > 0 && isExactEn
 
 /**
  * @typedef {{scope: 'related', files: string[]} | {scope: 'full', reason: 'threshold' | 'no_tests'}} TestScope
+ * @typedef {{scope: 'changed', files: string[], changedFiles: string[], reason?: 'no_baseline'|'unpaired'|'threshold'|'no_changes'}} ChangedScope
  */
 
 /** A gate run with no block: no test file is known. */
@@ -108,30 +116,115 @@ export function hasTestFilesItem(gates) {
   return Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(TEST_FILES_TOKEN) === true);
 }
 
+/** @param {Record<string, unknown> | null | undefined} gates @returns {boolean} */
+export function hasScopeItem(gates) {
+  return hasTestFilesItem(gates) || Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(CHANGED_FILES_TOKEN));
+}
+
+/** A safe repo-relative path that cannot turn into an argv option. @param {string} file */
+function safeFile(file) {
+  return file.length > 0 && !file.startsWith('-') && !path.isAbsolute(file) && !/[\\\x00-\x1f]/.test(file) && !file.split('/').some((s) => s === '' || s === '.' || s === '..');
+}
+
+/**
+ * Bounded content baseline. Missing listed files are omitted from hashes and candidates; an
+ * owned entry with no current file has no hash. More than 200 owned files, a symlink, a
+ * non-regular owned file, a path outside the root or another read error means no record;
+ * callers retain the old scope. Git sees only argv and an isolated git environment.
+ * @param {string} cwd @param {string[]} owned @param {Record<string, string>} [kinds]
+ * @returns {Promise<{files: Record<string, string>, candidates: string[]} | null>}
+ */
+export async function fileBaseline(cwd, owned, kinds) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_CONFIG_GLOBAL = os.devNull;
+  const listed = await exec(['git', 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd, env, timeoutMs: 30000 });
+  if (listed.result !== 'ok') return null;
+  const listedFiles = [...new Set(listed.stdout.split('\0').filter(Boolean))].sort();
+  const candidates = [];
+  const files = /** @type {Record<string, string>} */ (Object.create(null));
+  try {
+    const root = await realpath(cwd);
+    for (const file of listedFiles) {
+      const isOwned = ownsFile(owned, file, kinds);
+      if (isOwned && !safeFile(file)) return null;
+      const absolute = path.join(root, file);
+      if (!isOwned) {
+        const exists = await access(absolute).then(() => true).catch((error) => {
+          if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+          throw error;
+        });
+        if (exists) candidates.push(file);
+        continue;
+      }
+      const stat = await lstat(absolute).catch((error) => {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+        throw error;
+      });
+      if (stat === null) continue;
+      candidates.push(file);
+      if (Object.keys(files).length >= 200 || !stat.isFile() || !(await realpath(absolute)).startsWith(root + path.sep)) return null;
+      files[file] = createHash('sha256').update(await readFile(absolute)).digest('hex');
+    }
+  } catch { return null; }
+  return { files, candidates };
+}
+
+/**
+ * Compare the last green record. A source without a stem pair cannot narrow the test gate.
+ * @param {{baseline: unknown, current: Awaited<ReturnType<typeof fileBaseline>>, fallback: TestScope, threshold?: number, owned?: string[], kinds?: Record<string, string>}} opts
+ * @returns {ChangedScope}
+ */
+export function changedScope({ baseline, current, fallback, threshold = DEFAULT_FULL_SUITE_THRESHOLD, owned, kinds }) {
+  const old = /** @type {Record<string, string> | null} */ (baseline);
+  const candidates = new Set(current?.candidates);
+  const fallbackFiles = fallback.scope === 'related' ? fallback.files.filter((file) => !current || candidates.has(file)) : [];
+  if (!current || !old || typeof old !== 'object' || Array.isArray(old) || Object.keys(old).length > 200 ||
+      Object.entries(old).some(([file, hash]) => !safeFile(file) || (owned && !ownsFile(owned, file, kinds)) || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))) {
+    return { scope: 'changed', files: fallbackFiles, changedFiles: [], reason: 'no_baseline' };
+  }
+  const changes = [...new Set([...Object.keys(old), ...Object.keys(current.files)])].filter((file) => old[file] !== current.files[file]).sort();
+  if (changes.length > threshold) return { scope: 'changed', files: [], changedFiles: [], reason: 'threshold' };
+  const changedFiles = changes.filter((file) => candidates.has(file));
+  // B97 also pairs Swift Tests names outside lowercase test directories.
+  const isChangedTest = (/** @type {string} */ file) => isTestPath(file) || file.endsWith('Tests.swift');
+  const tests = new Set(changedFiles.filter(isChangedTest));
+  for (const file of changes.filter((f) => !isChangedTest(f))) {
+    const pairs = pairsFor(file, current.candidates).filter(isChangedTest);
+    if (pairs.length === 0) return { scope: 'changed', files: fallbackFiles, changedFiles, reason: 'unpaired' };
+    for (const paired of pairs) tests.add(paired);
+  }
+  if (tests.size === 0) return { scope: 'changed', files: fallbackFiles, changedFiles, reason: 'no_changes' };
+  return { scope: 'changed', files: [...tests].sort(), changedFiles };
+}
+
 /**
  * One gate argv with every item that is exactly {@link TEST_FILES_TOKEN} replaced by the related
  * test files, or dropped for a full run. Always a new array; `scoped` is false (and the items
  * unchanged) when the gate has no such item.
- * @param {ReadonlyArray<string>} argv @param {TestScope} scope
+ * @param {ReadonlyArray<string>} argv @param {TestScope | ChangedScope} scope
  * @returns {{argv: string[], scoped: boolean}}
  * @throws {TypeError} a test path that starts with `-` (it would be read as an option; `block
  *   open --tests` refuses one too).
  */
 export function expandArgv(argv, scope) {
-  if (!argv.includes(TEST_FILES_TOKEN)) return { argv: [...argv], scoped: false };
-  const files = scope.scope === 'related' ? scope.files : [];
+  if (!argv.includes(TEST_FILES_TOKEN) && !argv.includes(CHANGED_FILES_TOKEN)) return { argv: [...argv], scoped: false };
+  const files = scope.scope === 'full' ? [] : scope.files;
+  const changed = scope.scope === 'changed' ? scope.changedFiles : [];
+  if (changed.some((file) => !safeFile(file))) throw new TypeError('expandArgv: unsafe changed path');
   const dashed = files.find((f) => f.startsWith('-'));
   if (dashed !== undefined) throw new TypeError(`expandArgv: test path ${JSON.stringify(dashed)} starts with "-"`);
-  return { argv: argv.flatMap((item) => (item === TEST_FILES_TOKEN ? files : [item])), scoped: true };
+  return { argv: argv.flatMap((item) => item === TEST_FILES_TOKEN ? files : item === CHANGED_FILES_TOKEN ? changed : [item]), scoped: true };
 }
 
 /**
  * The fields a scoped gate's result and ledger row carry: `scope`, plus `test_count` when related
  * or `reason` when full.
- * @param {TestScope} scope
- * @returns {{scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold' | 'no_tests'}}
+ * @param {TestScope | ChangedScope} scope
+ * @returns {{scope: 'changed', test_count: number, reason?: 'no_baseline'|'unpaired'|'threshold'|'no_changes'} | {scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold'|'no_tests'}}
  */
 export function scopeFields(scope) {
+  if (scope.scope === 'changed') return { scope: 'changed', test_count: scope.files.length, ...(scope.reason ? { reason: scope.reason } : {}) };
   return scope.scope === 'related' ? { scope: 'related', test_count: scope.files.length } : { scope: 'full', reason: scope.reason };
 }
 

package/src/gates/run.mjs

@@ -8,6 +8,7 @@
 
 import { exec } from '../util/exec.mjs';
 import { registerSecret } from '../util/redact.mjs';
+import { CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } from './expand.mjs';
 
 /** @typedef {import('./detect.mjs').Gate} Gate */
@@ -25,9 +26,9 @@ import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } fro
  * @property {number | null} code
  * @property {string} stdout
  * @property {string} stderr
- * @property {'related'|'full'} [scope] - B60: only on a gate whose argv has the `{test_files}` item.
+ * @property {'related'|'full'|'changed'} [scope] - only on a gate with a scope token.
  * @property {number} [test_count] - B60: with `scope: related`, how many test files it ran.
- * @property {'threshold'|'no_tests'} [reason] - B60: with `scope: full`, why the item was dropped.
+ * @property {'threshold'|'no_tests'|'no_baseline'|'unpaired'|'no_changes'} [reason] - why narrowing fell back.
  * @property {string[]} [env_keys] - B60: only on a gate given with a non-empty `env`: the variable
  *   NAMES, sorted (the values are never in a result).
  */
@@ -53,7 +54,7 @@ function normalizeCommand(command) {
  * no test file is known (`scope: full, reason: no_tests`). A gate with `env` runs with those
  * variables added to the inherited environment; a gate with neither runs exactly as before B60.
  * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate}} gates
- * @param {{cwd: string, timeoutMs?: number, scope?: TestScope}} opts
+ * @param {{cwd: string, timeoutMs?: number, scope?: TestScope | import('./expand.mjs').ChangedScope}} opts
  * @returns {Promise<{results: GateResult[], allOk: boolean}>}
  */
 export async function runGates(gates, opts) {
@@ -77,8 +78,9 @@ export async function runGates(gates, opts) {
     const command = gates[gate] ?? null;
     if (command === null) return { gate, command: null };
     const normalized = normalizeCommand(command);
+    if (normalized.argv[0] === CHANGED_FILES_TOKEN) throw new TypeError(`gates.${gate}: '{changed_files}' cannot be the command (argv[0])`);
     const { argv, scoped } = expandArgv(normalized.argv, scope);
-    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once '{test_files}' is dropped for the full suite — put the test command before it`);
+    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once ${normalized.argv.map((item) => `'${item}'`).join(' and ')} is dropped for the full suite — put the test command before it`);
     return { gate, command: { argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } };
   });
   /** @type {GateResult[]} */

package/src/install/wizard/flags.mjs

@@ -3,7 +3,7 @@
  * wizard answer (`ANSWER_FLAGS` maps flag -> answer key); `--no-interaction` is a mode switch and
  * overrides no answer.
  *
- * **Q16 = cut (Ricardo, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
+ * **Q16 = cut (the owner, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
  * v1.2 `--no-nightly` flag is gone and `--proof` takes only the keys the schema still has
  * (`isolation`, `high`, `link_dirs`, `copy_untracked`). With `-g` and `-p` counted as two flags
  * (two tokens that each set the scope answer) there are 21 answer flags: B65 added

package/src/ledger/spend.mjs

@@ -12,7 +12,7 @@
  */
 
 import { logWarning } from '../util/error-log.mjs';
-import { keyedLock } from '../util/locks.mjs';
+import { withLock } from '../util/file-locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { estimateCostUsd } from './prices.mjs';
 
@@ -199,7 +199,7 @@ export const SPEND_UNREADABLE_MESSAGE = "budget.usd is set but the run's spend c
  * Several sessions of one run can start at once (B40 slots, B42 ticket pool). The ledger only
  * learns a session's cost when its row is written, so a plain "spent < budget" check lets every
  * session that starts before the first row lands go through. Instead the check AND a reservation
- * of the session's estimated cost happen under ONE in-process lock per run (`withBudgetLock`):
+ * of the session's estimated cost happen under ONE cross-process lock per run (`withBudgetLock`):
  *
  *   spent ≥ budget, or spent + reserved + estimate > budget ⇒ refused (the B33 message, unchanged)
  *
@@ -275,7 +275,7 @@ export function reserveBudget(run, usd) {
  */
 export function withBudgetLock(run, fn) {
   lockCalls += 1;
-  return keyedLock(`budget:${run}`, fn);
+  return withLock(`budget:${run}`, fn);
 }
 
 /** Test spy: how many times {@link withBudgetLock} was entered since the last reset. */