@codedology/code-forge 0.14.0 → 0.15.0

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/cli/upgrade.mjs

@@ -1,5 +1,5 @@
 /**
- * `code-forge upgrade [--source <path>]` — re-points every recorded install at a skill source
+ * `code-forge upgrade [--source <path>] [--plain]` — re-points every recorded install at a skill source
  * (plan §10.3 acceptance: "`upgrade` re-points all 3 recorded links"; research/installer-patterns.md
  * point 8, "a self `upgrade` command"). A symlink record is re-created to point at the new
  * source; a copy record is re-copied from it. With no `--source`, defaults to this running
@@ -8,33 +8,93 @@
  * (tests, or a power user working from a git checkout of the skill).
  */
 
-import { stat } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { stripVTControlCharacters } from 'node:util';
 import { writeSafe } from '../util/redact.mjs';
-import { installsPath, upgradeAll } from '../install/link.mjs';
+import { installsPath, readInstalls, upgradeAll } from '../install/link.mjs';
 
-const USAGE = 'usage: code-forge upgrade [--source <path>]\n';
+const USAGE = 'usage: code-forge upgrade [--source <path>] [--plain]\n';
+const LOGO = ' ___  __   __   ___       ___  __   __   __   ___\n|    |  | |  \\ |__   __  |__  |  | |__/ | _  |__\n|___ |__| |__/ |___      |    |__| |  \\ |__] |___\n';
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+const CHANGELOG_PATH = fileURLToPath(new URL('../../CHANGELOG.md', import.meta.url));
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /** This package's own skill directory: `<package root>/skill`, i.e. two levels above `src/cli/`. */
 export const DEFAULT_SKILL_SOURCE = path.join(__dirname, '..', '..', 'skill');
 
 /**
- * Strict parse: `[--source <path>]` only.
+ * Strict parse: optional source and plain flags, each at most once, in either order.
  * @param {string[]} args
- * @returns {{source?: string} | null}
+ * @returns {{source?: string, plain?: boolean} | null}
  */
 export function parseUpgradeArgs(args) {
-  if (args.length === 0) {
-    return {};
+  /** @type {{source?: string, plain?: boolean}} */
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--plain' && !parsed.plain) {
+      parsed.plain = true;
+    } else if (args[i] === '--source' && parsed.source === undefined) {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) return null;
+      parsed.source = value;
+    } else {
+      return null;
+    }
   }
-  const [flag, value, ...extra] = args;
-  if (flag !== '--source' || typeof value !== 'string' || value.length === 0 || extra.length > 0) {
-    return null;
+  return parsed;
+}
+
+/** Semver ordering, including numeric prerelease identifiers (rc.2 precedes rc.10).
+ * @param {string} a @param {string} b @returns {number}
+ */
+function compareVersions(a, b) {
+  const [coreA, preA] = a.split('+')[0].split(/-(.*)/);
+  const [coreB, preB] = b.split('+')[0].split(/-(.*)/);
+  const coreOrder = coreA.localeCompare(coreB, 'en', { numeric: true });
+  if (coreOrder) return coreOrder;
+  if (preA === undefined) return preB === undefined ? 0 : 1;
+  if (preB === undefined) return -1;
+  const idsA = preA.split('.');
+  const idsB = preB.split('.');
+  for (let i = 0; i < Math.max(idsA.length, idsB.length); i++) {
+    if (idsA[i] === undefined) return -1;
+    if (idsB[i] === undefined) return 1;
+    if (idsA[i] === idsB[i]) continue;
+    const numericA = /^\d+$/.test(idsA[i]);
+    const numericB = /^\d+$/.test(idsB[i]);
+    if (numericA !== numericB) return numericA ? -1 : 1;
+    return numericA ? Number(idsA[i]) - Number(idsB[i]) : (idsA[i] < idsB[i] ? -1 : 1);
   }
-  return { source: value };
+  return 0;
+}
+
+/** Read only bullets in the exact release section; unavailable notes are a silent omission.
+ * @param {string} file @param {string} version @returns {Promise<string[]>}
+ */
+async function releaseBullets(file, version) {
+  let text;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const bullets = [];
+  let inRelease = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^##\s/.test(line)) {
+      if (inRelease) break;
+      inRelease = /^## \[([^\]]+)\](?:\s|$)/.exec(line)?.[1] === version;
+    } else if (inRelease && line.startsWith('- ')) {
+      const chars = Array.from(stripVTControlCharacters(line.slice(2)));
+      bullets.push(chars.length > 100 ? `${chars.slice(0, 97).join('')}...` : chars.join(''));
+      if (bullets.length === 5) break;
+    }
+  }
+  return bullets;
 }
 
 /**
@@ -44,6 +104,8 @@ export function parseUpgradeArgs(args) {
  * @param {{write: (s: string) => unknown}} [deps.stderr]
  * @param {string} [deps.home]
  * @param {string} [deps.defaultSource]
+ * @param {string} [deps.packageVersion] - running package version, injectable for tests.
+ * @param {string} [deps.changelogPath] - packaged release notes, injectable for tests.
  * @param {string} [deps.cwd] - a relative `--source` is resolved against this, never against the
  *   link's own directory (which `symlink()` would otherwise silently use).
  * @returns {Promise<number>}
@@ -55,11 +117,13 @@ export async function runUpgrade(
     stderr = process.stderr,
     home = os.homedir(),
     defaultSource = DEFAULT_SKILL_SOURCE,
+    packageVersion = PACKAGE_VERSION,
+    changelogPath = CHANGELOG_PATH,
     cwd = process.cwd(),
   } = {},
 ) {
-  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
-  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+  const out = (/** @type {string} */ s) => writeSafe(stdout, stripVTControlCharacters(s));
+  const err = (/** @type {string} */ s) => writeSafe(stderr, stripVTControlCharacters(s));
 
   const parsed = parseUpgradeArgs(args);
   if (!parsed) {
@@ -84,13 +148,29 @@ export async function runUpgrade(
     return 1;
   }
 
-  const updated = await upgradeAll({ installsFile: installsPath(home), source: resolvedSource });
+  const installsFile = installsPath(home);
+  const previous = await readInstalls(installsFile);
+  const updated = await upgradeAll({ installsFile, source: resolvedSource, version: packageVersion });
+  if (!parsed.plain) {
+    const versions = previous.map((r) => r.version).filter((v) => v !== undefined).sort(compareVersions);
+    const oldest = versions[0];
+    const change = oldest === undefined ? 'first versioned upgrade'
+      : oldest === packageVersion ? `already on ${packageVersion}` : `${oldest} -> ${packageVersion}`;
+    out(`${LOGO}code-forge ${packageVersion}\n${change}\n`);
+  }
   for (const record of updated) {
     out(`upgraded ${record.harness} (${record.scope}) -> ${record.source}\n`);
   }
   if (updated.length === 0) {
     out('nothing to upgrade\n');
   }
+  if (!parsed.plain) {
+    const notesPath = path.resolve(changelogPath);
+    const bullets = await releaseBullets(notesPath, packageVersion);
+    if (bullets.length > 0) {
+      out(`What's new in ${packageVersion}:\n${bullets.join('\n')}\nFull notes: ${notesPath}\n`);
+    }
+  }
   return 0;
 }
 

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: '' };
     }