@codedology/code-forge 0.15.1 → 0.15.3

package/src/cli/review-file.mjs

@@ -67,30 +67,85 @@
  * needs its own review.
  */
 
-import { readFileSync, realpathSync, rmSync } from 'node:fs';
+import { lstatSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { answersTicketId, assertAnswers, blockTickets, deliverBlockFindings, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { answersTicketId, assertAnswers, blockTickets, deliverBlockFindings, dropDoneIf, enqueue, enqueueAnswers, enqueueHash, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveHashTicket, resolveTicket, reviewExclusionFor } from '../worker/queue.mjs';
 import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
-import { blockFileSet, namedOnHash } from '../review/gate-check.mjs';
+import { changedFiles, 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 { appendRow, 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 { rebaseBlock } from '../state/block.mjs';
 import { configInForce } from '../state/config-snapshot.mjs';
+import { reviewExcludeRule } from '../config/validate.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' +
+  'usage: code-forge review-file [--cwd <dir>] <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';
+  '       code-forge review-file --rebase-check --block <id> --run <id>\n' +
+  '       code-forge review-file <answering file> --block <id> --answers <id,id,…> --of <source> [--run <id>]\n' +
+  '       --cwd <dir> applies to queueing and both wait modes\n';
 
 export const DEFAULT_WAIT_MS = 90_000;
 const POLL_MS = 200;
+const MAX_IDLE_MS = 5000;
+
+/** Metadata only: never open file content during an idle poll.
+ * @param {string} file @returns {string}
+ */
+function fileStamp(file) {
+  try {
+    const s = lstatSync(file);
+    return `${s.mtimeMs}:${s.size}:${s.mode}:${s.ino}`;
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return 'missing';
+    throw err;
+  }
+}
+
+/** Scan literal ownership prefixes, including directory entries so new files are noticed.
+ * @param {string} tree @param {string[]} owned @param {string[]} gitPaths
+ */
+function waitTreeStamp(tree, owned, gitPaths) {
+  const entries = new Map();
+  /** @param {string} full */
+  function visit(full) {
+    if (entries.has(full)) return;
+    const stamp = fileStamp(full);
+    entries.set(full, stamp);
+    if (stamp !== 'missing' && lstatSync(full).isDirectory()) {
+      for (const name of readdirSync(full).sort()) {
+        if (name !== '.git' && name !== '.code-forge') visit(path.join(full, name));
+      }
+    }
+  }
+  for (const pattern of owned) {
+    const segments = pattern.split('/');
+    const glob = segments.findIndex((s) => /[*?{]/.test(s));
+    visit(path.join(tree, ...(glob < 0 ? segments : segments.slice(0, glob))));
+  }
+  for (const full of gitPaths) visit(full);
+  return JSON.stringify([...entries].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/** Git may store worktree metadata outside the content tree.
+ * @param {string} tree @returns {string[]}
+ */
+function waitGitPaths(tree) {
+  let gitDir = path.join(tree, '.git');
+  if (lstatSync(gitDir).isFile()) gitDir = path.resolve(tree, readFileSync(gitDir, 'utf8').trim().replace(/^gitdir: /, ''));
+  let common = gitDir;
+  try { common = path.resolve(gitDir, readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()); }
+  catch (err) { if (err.code !== 'ENOENT') throw err; }
+  return [path.join(tree, '.gitignore'), ...new Set([gitDir, common])].flatMap((dir, i) => i === 0 ? [dir] : ['HEAD', 'index', 'packed-refs', 'refs', 'info/exclude'].map((f) => path.join(dir, f)));
+}
 
 /**
  * `90s`, `90`, `1500ms` → milliseconds.
@@ -394,9 +449,11 @@ export function fixList(result) {
  * 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}>}
+ * @param {{scopeFile: string, stamp: string, entry: Record<string, any>, tree: string, cfg: Record<string, any> | null, project: string} | null} [cached]
+ * @returns {Promise<{scopeFile: string, stamp: string, entry: Record<string, any>, tree: string, cfg: Record<string, any> | null, project: string}>}
  */
-async function waitBlockScope(repoRoot, cwd, run, block) {
+async function waitBlockScope(repoRoot, cwd, run, block, cached = null) {
+  if (cached && fileStamp(cached.scopeFile) === cached.stamp) return cached;
   const top = await repoRootOf(cwd);
   const candidates = new Set([repoRoot]);
   for (let dir = realpathSync(cwd); ; dir = path.dirname(dir)) {
@@ -416,7 +473,8 @@ async function waitBlockScope(repoRoot, cwd, run, block) {
       throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
     }
     const tree = (await blockTree(record.workspace, entry))?.top ?? repoRoot;
-    return { entry, tree };
+    const scopeFile = path.join(dir, '.code-forge', 'runs', `${run}.json`);
+    return { entry, tree, cfg: configInForce(record), project: record.project, scopeFile, stamp: fileStamp(scopeFile) };
   }
   throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
 }
@@ -445,16 +503,32 @@ function blockTicketOutcome(marker) {
   return 'unavailable';
 }
 
+/** Completion timings are progress metadata; old markers remain readable.
+ * @param {Record<string, any> | null} value @returns {Record<string, any>} */
+function ticketTimings(value) {
+  return Object.fromEntries(['queued_at', 'started_at', 'finished_at', 'duration_ms']
+    .filter((key) => value && Object.hasOwn(value, key)).map((key) => [key, value[key]]));
+}
+
 /**
  * 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
+ * Re-scan metadata each poll and read content only after its stamp changes. 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, dropDone?: typeof dropDoneIf}} opts
+ * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, now?: () => number, sleep?: (ms: number) => Promise<unknown>}} opts
  */
-async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDone = dropDoneIf }) {
-  const { entry, tree } = await waitBlockScope(repoRoot, cwd, run, block);
+async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDone = dropDoneIf, now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+  let scope = await waitBlockScope(repoRoot, cwd, run, block);
+  const { tree } = scope;
+  const gitPaths = waitGitPaths(tree);
   const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree: realpathSync(tree) };
-  const deadline = Date.now() + maxMs;
+  const deadline = now() + maxMs;
+  let interval = pollMs;
+  let seen = '';
+  let treeStamp = '';
+  /** @type {string[]} */
+  let current = [];
+  /** @type {Map<string, {stamp: string, content_hash: string}>} */
+  const hashes = new Map();
   let downPolls = 0;
   const deliveredHere = new Set();
   for (;;) {
@@ -462,25 +536,46 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDo
     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);
+    scope = await waitBlockScope(repoRoot, cwd, run, block, scope);
+    const { entry, cfg, project } = scope;
+    const stamp = waitTreeStamp(tree, entry.owned_files, gitPaths) + scope.stamp;
+    if (stamp !== treeStamp) {
+      current = (await changedFiles({ repoRoot: tree, base: entry.base_sha })).filter((file) => ownsFile(entry.owned_files, file, entry.owned_kinds));
+      treeStamp = stamp;
+    }
+    // Progress only, like answersPrecheck: sandboxed callers may not read the private ledger.
+    // Reopens issued here also renew the workspace ticket, which needs no private read to join.
+    let rows = [];
+    try { rows = await readAllRows(project); } catch { /* The worker verifies the signed row. */ }
+    const reopens = new Map();
+    for (const row of rows) {
+      if (row.event !== 'review.reopened' || row.run !== run || row.block !== block || !Number.isFinite(Date.parse(row.ts))) continue;
+      if (row.by !== 'human' && !(row.by === 'agent' && row.verdict?.verdict === 'agree')) continue;
+      if (!reopens.has(row.file) || row.ts > reopens.get(row.file)) reopens.set(row.file, row.ts);
+    }
+    const files = current.map((file) => {
+      const rule = reviewExcludeRule(cfg, file);
+      if (rule !== null) return { file, ticket: null, status: 'excluded', outcome: null, rule };
+      const after = reopens.get(file);
+      const stamp = fileStamp(path.join(tree, file));
+      if (hashes.get(file)?.stamp !== stamp) hashes.set(file, { stamp, content_hash: contentHash(tree, file) });
+      const opts = { repoRoot, run, block, file, ...where, after, content_hash: hashes.get(file).content_hash };
+      const { ticket } = resolveHashTicket(opts);
+      const previous = tickets.filter((t) => t.file === file && (after === undefined || Date.parse(t.enqueued_at) > Date.parse(after)));
       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', outcome: blockTicketOutcome(marker) };
+        if (marker?.status === 'stopped') return { file, ticket: newest.ticket, status: 'done', outcome: blockTicketOutcome(marker), ...ticketTimings(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', outcome: blockTicketOutcome(marker) };
+            return { file, ticket: newest.ticket, status: 'findings', outcome: blockTicketOutcome(marker), ...ticketTimings(marker) };
           }
         }
       }
       if (!present && live) {
-        enqueue(opts);
+        enqueueHash(opts);
         present = { ...previous[previous.length - 1], ticket };
       }
       let marker = present ? blockTicketMarker(repoRoot, ticket) : null;
@@ -488,7 +583,7 @@ 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', outcome: blockTicketOutcome(marker) };
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : marker ? 'done' : 'pending', outcome: blockTicketOutcome(marker), ...ticketTimings(marker) };
     });
     if (downPolls >= 2) {
       say({ block, files, done: false, status: 'worker_down' });
@@ -499,38 +594,65 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDo
       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')) {
+    if (live && files.every((f) => f.status === 'done' || f.status === 'findings' || f.status === 'excluded')) {
       say({ block, files, done: true });
       return 0;
     }
-    if (live && (files.some((f) => f.status === 'not_queued') || Date.now() >= deadline)) {
+    if (live && (files.some((f) => f.status === 'not_queued') || 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));
+    const ticketIds = [...new Set([...tickets.map((t) => t.ticket), ...files.map((f) => f.ticket).filter(Boolean)])].sort();
+    const state = JSON.stringify([stamp, live, ticketIds, files]);
+    interval = seen === state ? Math.min(MAX_IDLE_MS, interval * 2) : pollMs;
+    seen = state;
+    await sleep(Math.min(interval, Math.max(0, deadline - now())));
   }
 }
 
 /**
  * @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.
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number, dropDone?: typeof dropDoneIf, now?: () => number, sleep?: (ms: number) => Promise<unknown>}} [deps] - `dropDone`: B75's claim, for tests.
  * @returns {Promise<number>}
  */
 export async function runReviewFile(args, deps = {}) {
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
   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', 'wait-block', 'max', 'answers', 'of'], booleans: ['fresh'] });
+    const { flags, positionals } = parseFlags(args, { values: ['cwd', 'block', 'run', 'wait', 'wait-block', 'max', 'answers', 'of'], booleans: ['fresh', 'rebase-check'] });
+    let cwd = deps.cwd ?? process.cwd();
+    if (typeof flags.cwd === 'string') {
+      cwd = path.resolve(cwd, flags.cwd);
+      try {
+        if (!statSync(cwd).isDirectory()) throw new Error('not a directory');
+      } catch {
+        throw new WorkerError('usage', '--cwd must name an existing directory');
+      }
+    }
     // the queue and the worker: the main tree, also from inside a block's worktree
     const repoRoot = await mainRootOf(cwd);
 
+    if (flags['rebase-check'] === true) {
+      if (positionals.length || typeof flags.block !== 'string' || typeof flags.run !== 'string' || ['wait', 'wait-block', 'max', 'answers', 'of', 'fresh'].some((key) => flags[key] !== undefined)) {
+        throw new WorkerError('usage', '--rebase-check takes --block and --run only');
+      }
+      const block = assertBlockId(flags.block);
+      const runId = assertRunId(flags.run);
+      const worker = liveWorker(repoRoot);
+      if (!worker || worker.run !== runId) { say({ status: 'worker_down', block }); return 3; }
+      const record = await readRun(runId);
+      if (await mainRootOf(record.workspace) !== repoRoot) throw new WorkerError('other-workspace', 'the run belongs to another workspace');
+      const result = await rebaseBlock({ runId, id: block, rebaseCheck: true, writeRow: (row) => appendRow(row, { slug: record.project }) });
+      say({ block, status: 'queued', ...result, next: `code-forge block rebase ${block} --run ${runId}` });
+      return 0;
+    }
+
     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, dropDone: deps.dropDone });
+      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, dropDone: deps.dropDone, now: deps.now, sleep: deps.sleep });
     }
 
     if (typeof flags.wait === 'string') {
@@ -542,7 +664,7 @@ export async function runReviewFile(args, deps = {}) {
       for (;;) {
         if (isDone(repoRoot, ticket)) {
           const result = doneResult(repoRoot, ticket);
-          say({ ticket, status: 'done', result, ...fixList(result) });
+          say({ ticket, status: 'done', result, ...ticketTimings(result), ...fixList(result) });
           return 0;
         }
         downPolls = liveWorker(repoRoot) ? 0 : downPolls + 1;
@@ -561,9 +683,23 @@ export async function runReviewFile(args, deps = {}) {
     if (positionals.length !== 1 || typeof flags.block !== 'string' || flags.max !== undefined) throw new WorkerError('usage', 'give one path and --block');
     const block = assertBlockId(flags.block);
     if (flags.fresh === true && (flags.answers !== undefined || flags.of !== undefined)) throw new WorkerError('usage', '--fresh takes no --answers or --of');
-    if (flags.answers !== undefined || flags.of !== undefined) return await enqueueAnswersTicket({ flags, answering: positionals[0], block, cwd, repoRoot, say });
     const file = normalizeRequestPath(positionals[0], cwd, await repoRootOf(cwd));
     const worker = liveWorker(repoRoot);
+    let cfg = null;
+    const requestedRun = typeof flags.run === 'string' ? flags.run : worker?.run;
+    if (requestedRun) {
+      try { cfg = configInForce(await readRun(requestedRun)); }
+      catch { /* The workspace mirror below also serves sandboxed callers. */ }
+    }
+    const candidates = [file, ...(typeof flags.of === 'string' ? [normalizeRequestPath(flags.of, cwd, await repoRootOf(cwd))] : [])];
+    for (const candidate of candidates) {
+      const rule = requestedRun ? reviewExclusionFor(repoRoot, requestedRun, candidate, cfg) : reviewExcludeRule(cfg, candidate);
+      if (rule !== null) {
+        writeSafe(stdout, `not reviewed (review.exclude ${rule}): ${candidate}\n`);
+        return 0;
+      }
+    }
+    if (flags.answers !== undefined || flags.of !== undefined) return await enqueueAnswersTicket({ flags, answering: positionals[0], block, cwd, repoRoot, say });
     if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
       say({ status: 'worker_down', file });
       return 3;
@@ -574,12 +710,6 @@ 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 };
-    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 });
     const cached = queued.status === 'done' ? doneResult(repoRoot, queued.ticket) : null;

package/src/cli/run.mjs

@@ -40,7 +40,8 @@ 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 { sweepProcesses } from '../util/reaper.mjs';
+import { 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';
@@ -173,7 +174,7 @@ export async function runRun(args, deps = {}) {
       const project = slugFor(loaded.config, workspace);
       const engine = typeof flags.engine === 'string' ? flags.engine : undefined;
       const tmpRoot = typeof loaded.config?.tmp?.root === 'string' ? loaded.config.tmp.root : undefined;
-      await sweepRoots({ root: tmpBase(tmpRoot) }); // dead runs' temp roots and orphans (§9.6, V12)
+      await sweepProcesses({ apply: true, root: tmpBase(tmpRoot), zombies: false });
       let record = await startRun({ workspace, project, config: loaded.config, engine, mode, runId, workerPid, writeRow: ledgerWriter(project), probe });
       if (!record.worker && startWorker) {
         const launched = await startWorker({ runId: record.run_id, workspace });

package/src/cli/sweep.mjs

@@ -0,0 +1,28 @@
+import { parseFlags } from '../state/cli-args.mjs';
+import { sweepProcesses } from '../util/reaper.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const HELP = 'usage: code-forge sweep [--apply] [--json]\nDry run by default: list stale workers, dead-run registry children and marked orphans with RSS and total MB.\n--apply stops proven stale processes with SIGTERM, then SIGKILL after a grace period.\nZombies are reported by parent only; neither they nor their parents are signalled. Live engines have no memory limit.\n';
+
+/** @param {string[]} args @param {{sweep?:typeof sweepProcesses}} [deps] */
+export default async function runSweep(args, deps = {}) {
+  let flags;
+  try {
+    const parsed = parseFlags(args, { booleans: ['apply', 'json', 'help'] });
+    if (parsed.positionals.length) throw new Error('unexpected positional argument');
+    flags = parsed.flags;
+  } catch {
+    writeSafe(process.stderr, HELP);
+    return 2;
+  }
+  if (flags.help) { writeSafe(process.stdout, HELP); return 0; }
+  const report = await (deps.sweep ?? sweepProcesses)({ apply: flags.apply === true });
+  if (flags.json) writeSafe(process.stdout, `${JSON.stringify(report)}\n`);
+  else {
+    for (const item of report.items) writeSafe(process.stdout,
+      `${report.apply ? item.action ?? 'stopped' : 'would stop'} ${item.kind} pid ${item.pid} ${item.rssMb.toFixed(1)} MB ${item.command}\n`);
+    for (const group of report.zombies) writeSafe(process.stdout, `${group.count} zombies (parent ${group.ppid} ${group.command}) — report only\n`);
+    writeSafe(process.stdout, `${report.apply ? 'sweep' : 'dry run'}: ${report.items.length} processes, total ${report.totalRssMb.toFixed(1)} MB; ${report.registryRoots.length} dead-run roots\n`);
+  }
+  return 0;
+}

package/src/cli/validate.mjs

@@ -11,6 +11,7 @@ import { loadConfigFile, DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
 import { loadSeenInCache } from '../config/refresh.mjs';
 import { maskSecretTokens } from '../config/secret-patterns.mjs';
 import { validateConfig } from '../config/validate.mjs';
+import { loadPipeline } from '../pipeline/pipeline.mjs';
 import * as log from '../util/log.mjs';
 
 /** Provider -> the CLI binary name `engine: subprocess` would spawn for it. */
@@ -100,6 +101,11 @@ export default async function validate(args) {
   }
 
   if (result.valid) {
+    const pipeline = loadPipeline(path.dirname(parsed.file));
+    if (pipeline.exists && !pipeline.ok) {
+      for (const problem of pipeline.problems) log.error(maskSecretTokens(problem));
+      return 1;
+    }
     log.info(`${parsed.file}: valid (${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'})`);
     return 0;
   }

package/src/config/schema-compile.mjs

@@ -4,7 +4,7 @@
  *
  * OpenAI's structured-output "strict" mode has three rules a hand-written schema violates by
  * default: (1) every property under an object must be listed in `required` (optional fields are
- * instead modeled as **nullable** required fields), (2) every object must set
+ * instead modeled as **nullable** required fields; source-required keys stay as they are), (2) every object must set
  * `additionalProperties: false`, (3) nothing may be missing from `required`. Claude and Grok take
  * the source schema unchanged (they support ordinary JSON Schema `required`/optional).
  *
@@ -149,8 +149,9 @@ function childSchemas(node) {
 }
 
 /**
- * Recursively rewrites every object node: a `properties` map makes every property `required` and
- * nullable and closes the node (unless it already has an open-ended `additionalProperties`); a
+ * Recursively rewrites every object node: a `properties` map makes every property `required`;
+ * optional keys become nullable; required keys stay as they are. It closes the node (unless it
+ * already has an open-ended `additionalProperties`); a
  * bare `{type: 'object'}` is closed to an empty strict object. `visited` guards against revisiting
  * the same shared node twice — not against a genuine schema cycle, which this project's schema
  * does not have.
@@ -165,12 +166,13 @@ function compileForOpenAI(node, visited) {
 
   if (node.properties && typeof node.properties === 'object') {
     const keys = Object.keys(node.properties);
+    const wasRequired = new Set(Array.isArray(node.required) ? node.required : []);
     node.required = keys;
     if (node.additionalProperties === undefined) {
       node.additionalProperties = false;
     }
     for (const key of keys) {
-      makeNullable(node.properties[key]);
+      if (!wasRequired.has(key)) makeNullable(node.properties[key]);
     }
   } else if (isObjectTyped(node) && node.additionalProperties === undefined && node.patternProperties === undefined) {
     node.properties = {};

package/src/config/validate.mjs

@@ -66,7 +66,9 @@
 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 { packageVersion } from '../util/error-log.mjs';
 import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
+import { BLOCK_KINDS } from '../decide/escalation.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';
@@ -75,6 +77,7 @@ import { isKnownId, resolveLevel } from './known-ids.mjs';
 import { ROUTE_LEVELS, ruleProvider } from '../review/route.mjs';
 import { DEFAULT_SANDBOX_PROFILE, SANDBOX_PROFILES, sandboxDirRefusals, SANDBOX_DIR_REFUSED } from '../engines/sandbox-dirs.mjs';
 import { tmpBase } from '../util/tmp.mjs';
+import { expandBraces, globMatch } from '../state/registry.mjs';
 import { looksLikeSecret, maskSecretTokens, SECRET_MASK, secretTokensIn } from './secret-patterns.mjs';
 
 /**
@@ -211,7 +214,7 @@ function runSchemaValidation(cfg) {
       if (err.keyword === 'propertyNames' && typeof err.params?.propertyName === 'string') {
         detail = `property name "${safeSegment(err.params.propertyName)}" is not allowed (propertyNames)`;
       } else if (err.keyword === 'additionalProperties' && typeof err.params?.additionalProperty === 'string') {
-        detail = `must NOT have additional property "${safeSegment(err.params.additionalProperty)}"`;
+        detail = `must NOT have additional property "${safeSegment(err.params.additionalProperty)}" (unknown key; if it comes from a newer code-forge, upgrade: this is code-forge ${packageVersion()})`;
       }
       return {
         rule: 'schema',
@@ -512,12 +515,76 @@ function gateMessages(key, value) {
   return messages;
 }
 
+/** Custom gate refusals are also checked before running commands or reading evidence.
+ * @param {unknown} custom @returns {string[]}
+ */
+export function customGateMessages(custom) {
+  if (custom === undefined) return [];
+  if (!Array.isArray(custom)) return ['gates.custom must be an array of at most 20 named object gates'];
+  const messages = custom.length > 20 ? ['gates.custom must contain at most 20 entries'] : [];
+  const names = new Set();
+  for (const [i, value] of custom.entries()) {
+    const key = `custom[${i}]`;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      messages.push(`gates.${key} must be a named object gate`);
+      continue;
+    }
+    const { name, evidence, ...command } = value;
+    const label = `${key}${typeof name === 'string' ? ` (${safeSegment(name)})` : ''}`;
+    if (typeof name !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(name)) messages.push(`gates.${label}.name must match ^[a-z][a-z0-9_-]{0,31}$`);
+    if (GATE_KEYS.includes(name)) messages.push(`gates.${label}.name must not be a fixed gate name`);
+    if (names.has(name)) messages.push(`gates.${label}.name must be unique`);
+    names.add(name);
+    messages.push(...gateMessages(label, command));
+    if (Array.isArray(command.argv) && command.argv.some((arg) => typeof arg === 'string' && [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].some((token) => arg.includes(token)))) {
+      messages.push(`gates.${label}.argv: {test_files} and {changed_files} are refused in custom gates`);
+    }
+    if (evidence !== undefined) {
+      if (!Array.isArray(evidence)) messages.push(`gates.${label}.evidence must be an array of safe relative paths or simple globs`);
+      else for (const [j, pattern] of evidence.entries()) {
+        // Backslashes are refused as well so a Windows absolute/traversal path is never
+        // interpreted differently by validation and the POSIX evidence matcher.
+        if (typeof pattern !== 'string' || pattern.length === 0 || pattern.startsWith('/') || /[\\\0]/.test(pattern) || pattern.split('/').some((segment) => segment === '..' || /^[A-Za-z]:/.test(segment))) {
+          messages.push(`gates.${label}.evidence[${j}] must be a non-empty relative path or glob without absolute paths or a .. segment`);
+        }
+      }
+    }
+  }
+  return messages;
+}
+
+/** Gate names in a kind set must resolve to an available configured or detected gate.
+ * @param {Record<string, any> | undefined} gates @returns {string[]}
+ */
+export function kindGateMessages(gates) {
+  const custom = new Set(Array.isArray(gates?.custom) ? gates.custom.map((gate) => gate?.name) : []);
+  const messages = [];
+  for (const kind of BLOCK_KINDS) {
+    const names = gates?.kinds?.[kind];
+    if (!Array.isArray(names)) continue; // The schema handles invalid shapes.
+    for (const name of names) {
+      if (typeof name !== 'string') continue;
+      const label = `gates.kinds.${kind}: ${safeSegment(name)}`;
+      const fixed = GATE_KEYS.some((key) => key === name);
+      if (!fixed && !custom.has(name)) messages.push(`${label} is an unknown gate name`);
+      else if (fixed && gates[name] === null) messages.push(`${label} is a null fixed gate`);
+    }
+  }
+  return messages;
+}
+
 function checkGatesNotArgvArray(cfg) {
   const messages = GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]));
+  messages.push(...customGateMessages(cfg?.gates?.custom));
+  messages.push(...kindGateMessages(cfg?.gates));
   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');
   }
+  if (Object.hasOwn(cfg?.gates ?? {}, 'timeout_s')) {
+    const n = cfg.gates.timeout_s;
+    if (!Number.isInteger(n) || n < 30 || n > 7200) messages.push('gates.timeout_s must be an integer 30..7200');
+  }
   return messages.map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message }));
 }
 
@@ -1181,3 +1248,18 @@ export function reviewFileLoop(cfg) {
 export function reviewWorkers(cfg) {
   return cfg?.review?.workers ?? 1;
 }
+
+/** Common generated lock files, matched at the root and at any depth. */
+export const DEFAULT_REVIEW_EXCLUDE = Object.freeze([
+  'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb',
+  'composer.lock', 'Cargo.lock', 'Gemfile.lock', 'poetry.lock', 'uv.lock', 'go.sum',
+  'Package.resolved', 'Podfile.lock', 'pubspec.lock', 'mix.lock', 'flake.lock',
+].map((name) => `**/${name}`));
+
+/** The first matching repo-relative rule, or null. A supplied list replaces the defaults.
+ * @param {Record<string, any> | null} cfg @param {string} file @returns {string | null}
+ */
+export function reviewExcludeRule(cfg, file) {
+  const rules = cfg?.review?.exclude ?? DEFAULT_REVIEW_EXCLUDE;
+  return rules.find((rule) => expandBraces(rule).some((pattern) => globMatch(file, pattern))) ?? null;
+}