@codedology/code-forge 0.14.1 → 0.15.1

package/src/cli/gates.mjs

@@ -39,11 +39,12 @@ import { writeSafe, redactJSON } from '../util/redact.mjs';
 import { appendRow } from '../ledger/write.mjs';
 import { loadProjectConfig } from '../config/load.mjs';
 import { detectGates } from '../gates/detect.mjs';
-import { printableGates, scopeFields, thresholdOf } from '../gates/expand.mjs';
+import { printableGates, scopeFields, testScope, thresholdOf } from '../gates/expand.mjs';
 import { runGates } from '../gates/run.mjs';
 import { runGatesGuarded } from '../proof/lock.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { readRun } from '../state/run.mjs';
+import { loadKey, signRow } from '../state/signer.mjs';
 import { StateError } from '../state/paths.mjs';
 import { scanFiles } from '../gates/secret-scan.mjs';
 import { checkSafeEdit } from '../gates/safe-edit.mjs';
@@ -279,7 +280,29 @@ export async function runGatesVerb(args, deps = {}) {
       let ran;
       if (runFlag.value !== undefined && blockFlag.value !== undefined) {
         const threshold = thresholdOf(configured?.full_suite_threshold_files);
-        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, threshold, changed, slug, ...(timeoutMs ? { timeoutMs } : {}) });
+        /** @type {typeof gates & {repeatNewTests?: import('../gates/run.mjs').RepeatNewTests, lightTestFiles?: string[]}} */
+        let planned = gates;
+        if (configured?.repeat_new_tests !== undefined) {
+          const record = await readRun(runFlag.value);
+          const block = record.blocks?.[blockFlag.value];
+          if (block) planned = { ...gates,
+            repeatNewTests: { n: configured.repeat_new_tests, base: block.worktree?.base_sha ?? block.base_sha, owned: block.owned_files, kinds: block.owned_kinds, onSkip: (line) => err(`${line}\n`) },
+          };
+        }
+        // Missing records are diagnosed by the guarded runner, after its lock decision.
+        const block = await readRun(runFlag.value).then((record) => record.blocks?.[blockFlag.value]).catch((error) => {
+          if (error.code === 'no-run') return null;
+          throw error;
+        });
+        const light = block?.kind === 'light';
+        if (light) {
+          const scope = testScope({ testFiles: block.test_files, owned: block.owned_files, threshold: Infinity });
+          const command = planned.test;
+          const argv = Array.isArray(command) ? command : command?.argv;
+          if (scope.scope !== 'related' || !argv?.includes('{test_files}')) throw new StateError('light-tests', 'light-tests: block tests and a gates.test {test_files} item are required');
+          planned = { ...planned, lightTestFiles: scope.files };
+        }
+        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates: planned, cwd, threshold, changed: light ? false : changed, slug, ...(timeoutMs ? { timeoutMs } : {}) });
         if (guarded.result === 'proof.busy') {
           out({ result: 'proof.busy', holder: /** @type {{holder: string}} */ (guarded).holder });
           return 1;
@@ -289,24 +312,31 @@ export async function runGatesVerb(args, deps = {}) {
         ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
       }
       const { results, allOk } = ran;
+      const repeats = results.find((r) => r.repeats)?.repeats;
 
       const ledgerSlug = slug ?? ran.ledger_slug;
       if (ledgerSlug) {
+        // Preserve the existing rows when off; repeat evidence is covered by the run signature.
+        const writeGateRow = async (/** @type {Record<string, any>} */ row) => repeats && runFlag.value !== undefined
+          ? appendRow(signRow({ run: runFlag.value, ...row }, await loadKey(runFlag.value)), { slug: ledgerSlug })
+          : appendRow(row, { slug: ledgerSlug });
         // B60: with --run/--block the rows name the run and the block, so the run's binnacle reads them
         const owner = runFlag.value !== undefined ? { run: runFlag.value, block: blockFlag.value, ...inTree } : {};
         for (const result of results) {
           if (!result.skipped && !result.ok) {
-            await appendRow({ ...owner, event: 'gate.red', gate: result.gate, code: result.code, ...scopeOf(result) }, { slug: ledgerSlug });
+            await writeGateRow({ ...owner, event: 'gate.red', gate: result.gate, code: result.code, ...scopeOf(result),
+              ...(result.reason === 'flaky-test' ? { reason: 'flaky-test' } : {}),
+              ...(result.repeats ? { repeats: result.repeats } : {}) });
           }
         }
         // B60: one scope per run (every `{test_files}` gate shares it), named on gate.done too;
         // without --run/--block that is `scope: full, reason: no_tests`
         const scoped = results.find((r) => r.scope !== undefined);
-        await appendRow({ ...owner, event: 'gate.done', stack: gates.stack, all_ok: allOk,
+        await writeGateRow({ ...owner, event: 'gate.done', stack: gates.stack, all_ok: allOk,
           ...(ran.changed_scope ? scopeFields(ran.changed_scope) : scoped ? scopeOf(scoped) : {}),
-          ...(ran.files ? { files: ran.files } : {}) }, { slug: ledgerSlug });
+          ...(ran.files ? { files: ran.files } : {}), ...(repeats ? { repeats } : {}) });
       }
-      out({ stack: gates.stack, ...inTree, results, allOk });
+      out({ stack: gates.stack, ...inTree, results, allOk, ...(repeats ? { repeats } : {}) });
       return allOk ? 0 : 1;
     }
 

package/src/cli/ledger.mjs

@@ -20,7 +20,9 @@
  * coder one. A later call for the same PR replaces the earlier row in every reader.
  */
 
+import { readdir, stat } from 'node:fs/promises';
 import { buildCalibration } from '../ledger/calibration.mjs';
+import { ledgerDir, ledgerPath } from '../ledger/paths.mjs';
 import { recordCiOutcome, reviewedEntriesFromRows, scanGitAndRecord } from '../ledger/outcome.mjs';
 import { OUTSIDE_REVIEW_EVENT, OUTSIDE_REVIEW_USAGE, outsideReviewRecordedLine, parseOutsideReviewArgs } from '../ledger/outside-review.mjs';
 import { roundUsd, runSpend } from '../ledger/spend.mjs';
@@ -62,6 +64,23 @@ function parseNonNegativeInt(raw) {
   return Number.parseInt(raw, 10);
 }
 
+/** Readers distinguish an absent ledger from an existing empty file. @param {string} slug */
+async function readExistingRows(slug) {
+  try {
+    await stat(ledgerPath(slug));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const entries = await readdir(ledgerDir(), { withFileTypes: true }).catch((e) => {
+      if (e.code === 'ENOENT') return [];
+      throw e;
+    });
+    const slugs = [...new Set(entries.filter((e) => e.isFile() && /^[a-z0-9][a-z0-9-]*(?:\.\d+)?\.jsonl$/.test(e.name))
+      .map((e) => e.name.replace(/(?:\.\d+)?\.jsonl$/, '')))].sort();
+    throw new Error(`no ledger for slug "${slug}"; known slugs: ${slugs.join(', ') || 'none'}`);
+  }
+  return readAllRows(slug);
+}
+
 /**
  * @param {string[]} args
  * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
@@ -89,7 +108,7 @@ export async function runLedger(args, deps = {}) {
         err('ledger calibration: --question requires a value\n');
         return 2;
       }
-      const rows = await readAllRows(slug);
+      const rows = await readExistingRows(slug);
       const answers = rows.filter((r) => r.event === 'decision' && typeof r.confidence === 'number');
       const outcomes = rows.filter((r) => r.event === 'outcome' && r.decision_id);
       const { buckets, unbacked, unmapped } = buildCalibration(answers, outcomes, { questionId: question.value });
@@ -161,7 +180,7 @@ export async function runLedger(args, deps = {}) {
         err(`ledger tail: --n/-n must be a non-negative integer, got "${nArg}"\n`);
         return 2;
       }
-      const rows = await readAllRows(slug);
+      const rows = await readExistingRows(slug);
       for (const row of n === 0 ? [] : rows.slice(-n)) {
         out(`${JSON.stringify(row)}\n`);
       }

package/src/cli/report.mjs

@@ -6,7 +6,9 @@
  * printed as text lines under its header (`outside review: none`, or one line per PR).
  */
 
+import { readdir, stat } from 'node:fs/promises';
 import { writeSafe } from '../util/redact.mjs';
+import { ledgerDir, ledgerPath } from '../ledger/paths.mjs';
 import { buildReport, buildRunModes, buildSpend } from '../ledger/report.mjs';
 import { exportReportSections } from '../ledger/export.mjs';
 import { outsideReviewLines } from '../ledger/outside-review.mjs';
@@ -46,6 +48,18 @@ export async function runReport(args, deps = {}) {
   // try/catch below turns that, and any other I/O failure, into a clean CLI message instead of a
   // raw stack trace that skips the `writeSafe` redaction path.
   try {
+    try {
+      await stat(ledgerPath(slug));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const entries = await readdir(ledgerDir(), { withFileTypes: true }).catch((e) => {
+        if (e.code === 'ENOENT') return [];
+        throw e;
+      });
+      const slugs = [...new Set(entries.filter((e) => e.isFile() && /^[a-z0-9][a-z0-9-]*(?:\.\d+)?\.jsonl$/.test(e.name))
+        .map((e) => e.name.replace(/(?:\.\d+)?\.jsonl$/, '')))].sort();
+      throw new Error(`no ledger for slug "${slug}"; known slugs: ${slugs.join(', ') || 'none'}`);
+    }
     const rows = await readAllRows(slug);
     const { sections } = buildReport(rows);
 

package/src/cli/review-file.mjs

@@ -73,12 +73,14 @@ import { answersTicketId, assertAnswers, blockTickets, deliverBlockFindings, dro
 import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
 import { blockFileSet, namedOnHash } from '../review/gate-check.mjs';
 import { STOP_EXITS } from '../review/stop-exits.mjs';
+import { budgetFor } from '../review/packet.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 { configInForce } from '../state/config-snapshot.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
@@ -132,6 +134,18 @@ function resultOfMarker(repoRoot, text) {
 /** B75: the refused reasons that are not a verdict on the content (`--fresh` re-runs them). */
 const FRESH_REFUSED = new Set(['other-run', 'context-unreadable']);
 
+/**
+ * A split is reusable only under the budget it measured; absent metadata fails closed.
+ * @param {Record<string, any> | null} result @param {Record<string, any> | null} cfg
+ * @returns {{old: number, current: number} | null}
+ */
+function splitBudgetChange(result, cfg) {
+  if (!cfg || !result || (result.status !== 'split_required' && !(result.status === 'stopped' && result.stopped === 'split_required'))) return null;
+  if (!['quick', 'full', 'A', 'B', 'recheck'].includes(result.lens) || !Number.isFinite(result.budget) || result.budget <= 0) return null;
+  const current = budgetFor(cfg, result.lens === 'quick' ? 'quick_in' : 'full_in');
+  return result.budget !== current ? { old: result.budget, current } : null;
+}
+
 /**
  * B75: may `--fresh` drop this cached result? An allow-list, fail closed: `rerun` only for a
  * result that never counted as a review — `stale`, `unavailable`, round-1 `split_required`, or
@@ -141,9 +155,10 @@ const FRESH_REFUSED = new Set(['other-run', 'context-unreadable']);
  * ran, `review-state-lost`, an answers result, an unknown status or reason, an unreadable marker or
  * result).
  * @param {string} text - the done marker's text @param {Record<string, any> | null} result
+ * @param {Record<string, any> | null} [cfg] - the reloaded config, when readable.
  * @returns {'rerun' | 'tampered' | 'counted'}
  */
-export function freshVerdict(text, result) {
+export function freshVerdict(text, result, cfg = null) {
   let marker;
   try {
     marker = JSON.parse(text);
@@ -151,6 +166,7 @@ export function freshVerdict(text, result) {
     return 'counted';
   }
   if (result === null || marker === null || typeof marker !== 'object' || marker.status !== result.status) return 'counted';
+  if (splitBudgetChange(result, cfg)) return 'rerun';
   if (result.status === 'stale' || result.status === 'unavailable' || result.status === 'split_required') return 'rerun';
   if (result.status !== 'refused' || typeof result.reason !== 'string') return 'counted';
   if (result.reason === 'review-state-tampered') return 'tampered';
@@ -168,10 +184,10 @@ const RETRY_STATUSES = new Set(['stale', 'unavailable', 'split_required']);
 
 /**
  * Classify in place and use the same byte-checked claim for fresh and automatic retries.
- * @param {{repoRoot: string, ticket: string, file: string, dropDone?: typeof dropDoneIf, once?: boolean, statuses?: Set<string>}} opts
- * @returns {{verdict: 'rerun' | 'tampered' | 'counted', outcome: 'dropped' | 'gone' | 'kept'}}
+ * @param {{repoRoot: string, ticket: string, file: string, dropDone?: typeof dropDoneIf, once?: boolean, statuses?: Set<string>, cfg?: Record<string, any> | null}} opts
+ * @returns {{verdict: 'rerun' | 'tampered' | 'counted', outcome: 'dropped' | 'gone' | 'kept', budgetChange?: {old: number, current: number} | null}}
  */
-function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = false, statuses }) {
+function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = false, statuses, cfg = null }) {
   const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
   /** @type {'rerun' | 'tampered' | 'counted'} */
   let verdict = 'counted';
@@ -189,7 +205,7 @@ function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = f
     // classified IN PLACE: a refusal never moves, renames or touches the marker
     const text = bytes.toString('utf8');
     const result = resultOfMarker(repoRoot, text);
-    verdict = freshVerdict(text, result);
+    verdict = freshVerdict(text, result, cfg);
     if (statuses && !statuses.has(result?.status)) verdict = 'counted';
     if (verdict !== 'rerun') break;
     /** @type {unknown} */
@@ -208,7 +224,7 @@ function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = f
     if (outcome === 'kept') break;
     // an allow-list of outcomes: anything else is refused and nothing is queued
     if (outcome !== 'dropped' && outcome !== 'gone') throw new WorkerError('fresh-claim-unknown', `the claim of the cached result of ${file} gave an unknown outcome; nothing was queued`);
-    return { verdict, outcome };
+    return { verdict, outcome, budgetChange: outcome === 'dropped' ? splitBudgetChange(result, cfg) : null };
   }
   return { verdict, outcome: 'kept' };
 }
@@ -223,14 +239,15 @@ function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = f
  * `fresh-needs-reopen` (names `block reopen` and `block waive`) or `fresh-tampered` (names only
  * the owner's `block close --no-require-reviews`; reopen refuses a tampered state).
  * B110: a plain cached round-1 `split_required` uses the same claim, with `retry: true`.
- * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean}} opts
+ * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean, cfg?: Record<string, any> | null, stderr: {write: (s: string) => unknown}}} opts
  * @returns {number} the exit code.
  */
-function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false }) {
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false, cfg = null, stderr }) {
   const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
-  const { verdict, outcome } = dropFreshDone({ repoRoot, ticket, file, dropDone });
+  const { verdict, outcome, budgetChange } = dropFreshDone({ repoRoot, ticket, file, dropDone, cfg });
   if (outcome === 'dropped' || outcome === 'gone') {
     const queued = enqueue({ repoRoot, run, block, file, ...where });
+    if (budgetChange) writeSafe(stderr, `split_required at budget ${budgetChange.old}; budget is now ${budgetChange.current}: reviewing again\n`);
     say(outcome === 'dropped' ? { ...queued, ...(retry ? { retry: true } : { fresh: true }) } : queued);
     return 0;
   }
@@ -417,6 +434,17 @@ function blockTicketMarker(repoRoot, ticket) {
   throw new WorkerError('result-unreadable', 'a ticket completion marker cannot be read');
 }
 
+/** Progress only: legacy reviewed markers encode approval by absence of open_findings.
+ * @param {Record<string, any> | null} marker
+ * @returns {'approved' | 'findings' | 'stopped' | 'split_required' | 'unavailable' | null}
+ */
+function blockTicketOutcome(marker) {
+  if (!marker) return null;
+  if (marker.status === 'reviewed') return marker.open_findings === true || marker.approved === false ? 'findings' : 'approved';
+  if (marker.status === 'stopped' || marker.status === 'split_required') return marker.status;
+  return 'unavailable';
+}
+
 /**
  * A block wait uses unsigned results only to classify retries; it never reads the signing key.
  * Re-scan current content on every poll. Deliver unseen findings of the newest earlier ticket
@@ -443,15 +471,15 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDo
       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 === 'stopped') return { file, ticket: newest.ticket, status: 'done', outcome: blockTicketOutcome(marker) };
         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' };
+            return { file, ticket: newest.ticket, status: 'findings', outcome: blockTicketOutcome(marker) };
           }
         }
       }
-      if (!present && previous.length > 0 && live) {
+      if (!present && live) {
         enqueue(opts);
         present = { ...previous[previous.length - 1], ticket };
       }
@@ -460,12 +488,17 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDo
         dropFreshDone({ repoRoot, ticket, file, dropDone, once: true, statuses: RETRY_STATUSES });
         marker = blockTicketMarker(repoRoot, ticket);
       }
-      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : marker ? 'done' : 'pending' };
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : marker ? 'done' : 'pending', outcome: blockTicketOutcome(marker) };
     });
     if (downPolls >= 2) {
       say({ block, files, done: false, status: 'worker_down' });
       return 3;
     }
+    const split = files.find((f) => f.outcome === 'split_required');
+    if (live && split) {
+      say({ block, files, done: false, reason: 'split_required', next: `The owner raises review.budgets for ${split.file}, runs run reload, then review-file ${split.file} --fresh.` });
+      return 0;
+    }
     if (live && files.every((f) => f.status === 'done' || f.status === 'findings')) {
       say({ block, files, done: true });
       return 0;
@@ -541,10 +574,17 @@ export async function runReviewFile(args, deps = {}) {
     const tree = recorded === null ? await repoRootOf(cwd) : (recorded.top ?? repoRoot);
     assertInsideRoot(tree, file); // the path, re-checked in the tree its content is read from
     const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
-    if (flags.fresh === true) return freshTicket({ repoRoot, run: worker.run, block, file, where, say, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
+    let cfg = null;
+    try {
+      cfg = configInForce(await readRun(worker.run));
+    } catch {
+      // No readable snapshot: retain the existing cache and --fresh rules.
+    }
+    if (flags.fresh === true) return freshTicket({ repoRoot, run: worker.run, block, file, where, say, cfg, stderr, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     const queued = enqueue({ repoRoot, run: worker.run, block, file, ...where });
-    if (queued.status === 'done' && ['unavailable', 'split_required'].includes(doneResult(repoRoot, queued.ticket)?.status)) {
-      return freshTicket({ repoRoot, run: worker.run, block, file, where, say, retry: true, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
+    const cached = queued.status === 'done' ? doneResult(repoRoot, queued.ticket) : null;
+    if (cached && (['unavailable', 'split_required'].includes(cached.status) || splitBudgetChange(cached, cfg))) {
+      return freshTicket({ repoRoot, run: worker.run, block, file, where, say, retry: true, cfg, stderr, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     }
     say(queued);
     return 0;

package/src/cli/run.mjs

@@ -31,14 +31,18 @@
 import path from 'node:path';
 import { reloadFailureText, reloadWorkspace } from '../autopilot/limits.mjs';
 import { DEFAULT_CONFIG_FILENAME, loadProjectConfig, projectRootFor, slugFor } from '../config/load.mjs';
+import { reviewWorkers } from '../config/validate.mjs';
 import { budgetUsdOf, runSpend } from '../ledger/spend.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
+import { configInForce } from '../state/config-snapshot.mjs';
 import { endRun, processStartTime, readRun, reattachWorker, RUN_MODES, startRun, stopPinnedWorker } from '../state/run.mjs';
 import { writeSafe } from '../util/redact.mjs';
+import { withLock } from '../util/file-locks.mjs';
 import { sweepRoots, tmpBase } from '../util/tmp.mjs';
 import { launchWorker, repinWorker } from '../worker/loop.mjs';
+import { liveWorker, workerRegistry } from '../worker/queue.mjs';
 import { repoRootOf } from '../worker/ticket.mjs';
 
 /**
@@ -69,15 +73,18 @@ const ledgerWriter = (slug) => (/** @type {Record<string, any>} */ row) => appen
  * A worker that `run start` launched but could not pin must not outlive the command as an orphan:
  * stop it through the pinned-worker stopper (pid > 1, start time re-checked right before the
  * signal, so a recycled pid is never signalled) and name the pid on stderr. `startedAt` is the
- * start time read right after the launch; null means the process was already gone.
- * @param {{pid: number, startedAt: string | null}} launched
+ * start time read right after the launch; null means the process was already gone. When that
+ * probe threw (`undefined`), use the OS probe to obtain and re-check the identity for cleanup.
+ * @param {{pid: number, startedAt: string | null | undefined}} launched
  * @param {{stopWorker: StopWorker, probe?: import('../state/run.mjs').StartTimeProbe, err: (s: string) => void}} deps
  */
 async function stopLaunched({ pid, startedAt }, { stopWorker, probe, err }) {
   /** @type {{stopped: boolean, reason?: string}} */
   let outcome;
   try {
-    outcome = startedAt === null ? { stopped: false, reason: 'not running' } : await stopWorker({ pid, started_at: startedAt }, { ...(probe ? { probe } : {}) });
+    const cleanupProbe = startedAt === undefined ? processStartTime : probe;
+    if (startedAt === undefined) startedAt = await processStartTime(pid);
+    outcome = startedAt === null ? { stopped: false, reason: 'not running' } : await stopWorker({ pid, started_at: startedAt }, { ...(cleanupProbe ? { probe: cleanupProbe } : {}) });
   } catch (thrown) {
     outcome = { stopped: false, reason: thrown?.message ?? String(thrown) };
   }
@@ -107,13 +114,42 @@ export async function runRun(args, deps = {}) {
     return 2;
   }
   try {
-    const { flags } = parseFlags(rest, { values: ['run', 'cwd', 'engine', 'worker-pid', 'mode'], booleans: ['reattach'] });
+    const { flags } = parseFlags(rest, { values: ['run', 'cwd', 'engine', 'worker-pid', 'mode'], booleans: ['reattach', 'add-worker'] });
     const runId = typeof flags.run === 'string' ? flags.run : undefined;
     const workerPid = intFlag(flags['worker-pid'], 'worker-pid');
     const mode = typeof flags.mode === 'string' ? flags.mode : undefined;
-    if (mode !== undefined && (sub !== 'start' || flags.reattach)) throw new StateError('usage', '--mode is set once, by a new run start (the mode is fixed for the run)');
+    if (mode !== undefined && (sub !== 'start' || flags.reattach || flags['add-worker'])) throw new StateError('usage', '--mode is set once, by a new run start (the mode is fixed for the run)');
     if (mode !== undefined && !RUN_MODES.includes(mode)) throw new StateError('usage', `--mode must be one of ${RUN_MODES.join(', ')}`);
 
+    if (flags['add-worker']) {
+      if (sub !== 'start' || !runId || flags.reattach || workerPid !== undefined) throw new StateError('usage', 'run start --add-worker needs --run and cannot use --reattach or --worker-pid');
+      if (!startWorker) throw new StateError('usage', 'run start --add-worker needs a worker launcher');
+      return await withLock(`worker-add:${runId}`, async () => {
+        const record = await readRun(runId);
+        if (record.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
+        const repoRoot = await repoRootOf(record.workspace);
+        const loaded = record.config ? { ok: true, config: configInForce(record) } : await loadProjectConfig(record.workspace);
+        if (!loaded.ok) throw new StateError('config', 'the project config cannot be loaded');
+        const limit = reviewWorkers(loaded.config);
+        const entries = workerRegistry(repoRoot, { prune: true });
+        const legacy = liveWorker(repoRoot);
+        const count = entries.filter((e) => e.live).length + (legacy && !entries.some((e) => e.worker?.pid === legacy.pid && e.worker.start_time === legacy.start_time) ? 1 : 0);
+        if (count >= limit) throw new StateError('worker-running', `review.workers limit ${limit} reached`);
+        const launched = await startWorker({ runId, workspace: record.workspace });
+        /** @type {string | null | undefined} */
+        let startedAt;
+        try {
+          startedAt = await (probe ?? processStartTime)(launched.pid);
+          await repinWorker({ runId, repoRoot: launched.repoRoot, expectPid: launched.pid, add: true, writeRow: ledgerWriter(record.project), ...(probe ? { probe } : {}) });
+        } catch (thrown) {
+          await stopLaunched({ pid: launched.pid, startedAt }, { stopWorker: stopWorker ?? stopPinnedWorker, probe, err });
+          throw thrown;
+        }
+        out(`run ${runId}: added worker pid ${launched.pid} (review.workers limit ${limit})\n`);
+        return 0;
+      });
+    }
+
     if (sub === 'start' && flags.reattach) {
       if (!runId) throw new StateError('usage', 'run start --reattach needs --run');
       const { project, workspace } = await readRun(runId);
@@ -159,7 +195,8 @@ export async function runRun(args, deps = {}) {
       const record = await readRun(runId);
       const { run_id, status, engine, blocks, orphans } = record;
       const spend = await spendOf(record);
-      out(`${JSON.stringify({ run_id, status, engine, worker_pinned: Boolean(record.worker), blocks, orphans, ...spend }, null, 2)}\n`);
+      const awaiting = Object.keys(blocks).filter((id) => blocks[id].status === 'awaiting_human_check').sort();
+      out(`${JSON.stringify({ run_id, status, engine, worker_pinned: Boolean(record.worker), blocks, orphans, ...spend, ...(awaiting.length > 0 ? { awaiting_human_check: awaiting } : {}) }, null, 2)}\n`);
       // on stderr, so stdout stays one JSON document
       const n = spend.unknown_usd_sessions;
       if (n > 0) err(`${n} session${n === 1 ? ' has' : 's have'} no known price; the budget does not count ${n === 1 ? 'it' : 'them'}\n`);
@@ -221,7 +258,7 @@ async function reloadVerb(runId, { out, err }) {
 }
 
 const USAGE =
-  'usage: code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] [--mode plan|brief] | start --reattach --run <id> [--worker-pid <pid>] | status --run <id> | reload --run <id> | end --run <id>\n';
+  'usage: code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] [--mode plan|brief] | start --add-worker --run <id> | start --reattach --run <id> [--worker-pid <pid>] | status --run <id> | reload --run <id> | end --run <id>\n';
 
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function run(args) {

package/src/cli/status.mjs

@@ -65,7 +65,7 @@ const USAGE = 'usage: code-forge status [--run <id>] [--json]\n';
 const STATUS_MAX_LINES = 10;
 
 /**
- * @typedef {import('../state/brief-status.mjs').RunStatus} RunStatus
+ * @typedef {import('../state/brief-status.mjs').RunStatus & {awaiting_human_check?: string[]}} RunStatus
  */
 
 /** @param {string} p @returns {Promise<string>} */
@@ -108,7 +108,9 @@ async function statusOf(record) {
     if (list) list.push(r);
     else byBlock.set(r.block, [r]);
   }
-  return briefStatus({ record, rows, budget, findingsOf: (block) => openFindingsOf({ block, runId, mine: byBlock.get(block) ?? [], rows: all, key }) });
+  const awaiting = Object.keys(record.blocks ?? {}).filter((id) => record.blocks[id].status === 'awaiting_human_check').sort();
+  return { ...briefStatus({ record, rows, budget, findingsOf: (block) => openFindingsOf({ block, runId, mine: byBlock.get(block) ?? [], rows: all, key }) }),
+    ...(awaiting.length > 0 ? { awaiting_human_check: awaiting } : {}) };
 }
 
 /**
@@ -152,12 +154,14 @@ export function runLines(s) {
   const spent = s.spent_usd === null ? '$?' : `${usd(s.spent_usd)}${(s.unknown_usd_sessions ?? 0) > 0 ? '+?' : ''}`;
   const lines = [`run ${s.run_id} · ${s.status ?? '-'} · ${s.mode} · spent ${spent}${s.budget_usd !== null ? ` of ${usd(s.budget_usd)}` : ''}`];
   const tally = s.closed + s.stopped > 0 ? `closed ${s.closed} · stopped ${s.stopped}` : null;
-  const room = STATUS_MAX_LINES - 1 - (tally === null ? 0 : 1);
+  const awaiting = s.awaiting_human_check?.length ? `awaiting_human_check: ${JSON.stringify(s.awaiting_human_check)}` : null;
+  const room = STATUS_MAX_LINES - 1 - (tally === null ? 0 : 1) - (awaiting === null ? 0 : 1);
   const shown = s.blocks.length <= room ? s.blocks : s.blocks.slice(0, room - 1);
   for (const b of shown) {
     lines.push(`${b.id} ${b.state} ${b.level ?? '-'} · ${b.model ?? '-'} · gate ${b.gate.result}${b.gate.name ? ` (${b.gate.name})` : ''} · findings ${b.findings}`);
   }
   if (shown.length < s.blocks.length) lines.push(`… +${s.blocks.length - shown.length} more blocks`);
+  if (awaiting !== null) lines.push(awaiting);
   if (tally !== null) lines.push(tally);
   return lines;
 }

package/src/config/validate.mjs

@@ -513,7 +513,12 @@ function gateMessages(key, value) {
 }
 
 function checkGatesNotArgvArray(cfg) {
-  return GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]).map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message })));
+  const messages = GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]));
+  if (Object.hasOwn(cfg?.gates ?? {}, 'repeat_new_tests')) {
+    const n = cfg.gates.repeat_new_tests;
+    if (!Number.isInteger(n) || n < 2 || n > 10) messages.push('gates.repeat_new_tests must be an integer 2..10');
+  }
+  return messages.map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message }));
 }
 
 // ── 10. secret-looking-value (ERROR) ────────────────────────────────────────
@@ -1169,3 +1174,10 @@ export { schema as configSchema };
 export function reviewFileLoop(cfg) {
   return cfg?.review?.file_loop ?? 'wait';
 }
+
+/** Maximum workers for a validated config (the schema restricts it to 1..4).
+ * @param {Record<string, any>} cfg @returns {number}
+ */
+export function reviewWorkers(cfg) {
+  return cfg?.review?.workers ?? 1;
+}

package/src/gates/acceptance.mjs

@@ -1,5 +1,5 @@
 /**
- * Acceptance-clause coverage (plan §4.6 row 4, O17): "every clause names ≥ 1 test id; each named
+ * Acceptance-clause coverage (plan §4.6 row 4, O17): "every code clause names ≥ 1 test id; each named
  * test exists in the tree and passed in this gate run (parsed from the runner output)." This is
  * DETERMINISTIC — S1's `scope` question (§3.2) judges only whether hunks OUTSIDE the named tests
  * are unrelated; whether a named test id actually passed is a fact, never a model's opinion.
@@ -12,7 +12,7 @@
  */
 
 /**
- * @typedef {{clause: string, tests: string[]}} AcceptanceClause
+ * @typedef {{clause: string, kind?: string, tests?: string[]}} AcceptanceClause
  * @typedef {{ok: true} | {ok: false, reason: string, clause: string, test: string}} AcceptanceResult
  */
 
@@ -57,7 +57,7 @@ export function parseTapPassed(output) {
 }
 
 /**
- * @param {ReadonlyArray<AcceptanceClause>} clauses - each must name ≥ 1 test id.
+ * @param {ReadonlyArray<AcceptanceClause>} clauses - code clauses name ≥ 1 test id; human checks name none.
  * @param {Set<string> | ReadonlyArray<string>} passed - test ids that passed in THIS gate run.
  * @param {Set<string> | ReadonlyArray<string>} [failed] - test ids that FAILED in this gate run.
  *   `parseTapPassed` flattens every file's/describe-block's TAP subtests into one global name set,
@@ -77,6 +77,10 @@ export function checkAcceptance(clauses, passed, failed = new Set()) {
   for (const entry of clauses) {
     const clause = entry?.clause;
     const tests = entry?.tests;
+    if (entry?.kind === 'human_check' && typeof clause === 'string' && clause.length > 0) {
+      if (Object.hasOwn(entry, 'tests')) return { ok: false, reason: 'human_check clause must not name tests', clause, test: '' };
+      continue;
+    }
     if (typeof clause !== 'string' || clause.length === 0 || !Array.isArray(tests) || tests.length === 0) {
       return { ok: false, reason: 'clause names no test id', clause: String(clause ?? ''), test: '' };
     }

package/src/gates/expand.mjs

@@ -27,6 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { isExactEntry, ownsFile } from '../state/registry.mjs';
 import { pairsFor } from '../review/paired.mjs';
+import { computeFileSet } from './scope.mjs';
 import { exec } from '../util/exec.mjs';
 import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 
@@ -66,6 +67,30 @@ export function isTestPath(p) {
   return /\.(test|spec)\.[^/]+$/.test(name) || name.endsWith('Test.php') || name.endsWith('_test.go') || /^test_.*\.py$/.test(name);
 }
 
+/** The changed-test predicate, including Swift's conventional Tests suffix. @param {string} file */
+export function isChangedTest(file) {
+  return isTestPath(file) || file.endsWith('Tests.swift');
+}
+
+/**
+ * Existing block tests added or changed since its base, independent of the last green scope
+ * and its threshold. Deleted tests and unchanged source-paired tests are not repeat candidates.
+ * @param {{cwd: string, base: string, owned: string[], kinds?: Record<string, string>}} opts
+ * @returns {Promise<string[]>}
+ */
+export async function changedTestFiles({ cwd, base, owned, kinds }) {
+  const { all } = await computeFileSet({ cwd, base });
+  const files = all.filter((file) => ownsFile(owned, file, kinds) && isChangedTest(file));
+  const existing = await Promise.all(files.map(async (file) => {
+    const stat = await lstat(path.join(cwd, file)).catch((error) => {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+      throw error;
+    });
+    return stat?.isFile() === true;
+  }));
+  return files.filter((_, i) => existing[i]);
+}
+
 /**
  * An owned entry that names one file: no glob character (`*`, `?`, `{`) and no trailing `/`.
  * @param {string} p @returns {boolean}
@@ -186,8 +211,6 @@ export function changedScope({ baseline, current, fallback, threshold = DEFAULT_
   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);