@codedology/code-forge 0.14.1 → 0.15.0

package/src/state/block.mjs

@@ -12,7 +12,7 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto';
-import { createReadStream, existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import { createReadStream, existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
@@ -25,6 +25,8 @@ import { StateError } from './paths.mjs';
 import { assertOwned, blocksOverlap, isExactEntry, ownsFile, scopeGate } from './registry.mjs';
 import { checkWorkerPin, readRun, saveRun, withRunLock, writeSigned } from './run.mjs';
 import { verifyRow, loadKey } from './signer.mjs';
+import * as reviewQueue from '../worker/queue.mjs';
+import { repoRootOf } from '../worker/ticket.mjs';
 
 /** @typedef {import('./run.mjs').WriteRow} WriteRow */
 
@@ -216,16 +218,18 @@ export function briefPointer(relPath, content) {
 
 /**
  * @param {unknown} clauses
- * @returns {{clause: string, tests: string[]}[]}
+ * @returns {import('../gates/acceptance.mjs').AcceptanceClause[]}
  */
 function assertAcceptance(clauses) {
   const ok =
     Array.isArray(clauses) &&
     clauses.length > 0 &&
     clauses.every(
-      (c) => typeof c?.clause === 'string' && c.clause.length > 0 && Array.isArray(c.tests) && c.tests.length > 0 && c.tests.every((t) => typeof t === 'string' && t.length > 0),
+      (c) => typeof c?.clause === 'string' && c.clause.length > 0 && (c.kind === 'human_check'
+        ? !Object.hasOwn(c, 'tests')
+        : Array.isArray(c.tests) && c.tests.length > 0 && c.tests.every((t) => typeof t === 'string' && t.length > 0)),
     );
-  if (!ok) throw new StateError('bad-acceptance', 'acceptance: a non-empty list of {clause, tests: [test ids…]} is required');
+  if (!ok) throw new StateError('bad-acceptance', 'acceptance: a non-empty list of {clause, tests: [test ids…]} or {clause, kind: human_check} without tests is required');
   return clauses;
 }
 
@@ -315,6 +319,7 @@ function refuseConfigOwner(owned, kinds, guarded) {
  * and the dispatch row carry the floor level, and the row adds `requested_level` and
  * `trigger: 'docs_floor'`. B52: the entry also records `tree_at_open` ({@link treeAtOpen}), the
  * tree's changes at open, which `block close` reads to tell the coder's changes from earlier ones.
+ * B134: `base_branch` is the workspace's current branch, or null when detached.
  * B58: with `review.external.required` set, an owned entry that owns the project's config is
  * refused (`config-owned`, {@link refuseConfigOwner}).
  * B59: `decision` (the rules lane of a brief-mode block) is written as a signed `decision` row
@@ -352,12 +357,13 @@ export async function openBlock(opts) {
   if (typeof level !== 'string' || !LEVEL.test(level)) throw new StateError('bad-level', 'level must be L0..L3');
   if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
   if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
-  if (opts.kind !== undefined && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${BLOCK_KINDS.join(', ')}`);
+  if (opts.kind !== undefined && opts.kind !== 'light' && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${[...BLOCK_KINDS, 'light'].join(', ')}`);
   if (opts.decision && opts.decision.answer !== level) throw new StateError('bad-decision', `the decision answer ${opts.decision.answer} is not the requested level ${level}`);
   const owned = assertOwned(opts.owned);
   const acceptance = assertAcceptance(opts.acceptance);
+  const humanChecks = acceptance.filter((c) => c.kind === 'human_check').map((c) => c.clause);
   const tests = opts.tests === undefined ? null : [...assertOwned(opts.tests, { label: 'test files', code: 'bad-tests' })];
-  const kind = blockKind({ owned, declared: opts.kind });
+  const kind = opts.kind === 'light' ? 'light' : blockKind({ owned, declared: opts.kind });
   const dispatched = dispatchLevel({ lane: level, kind, cfg: opts.cfg });
   const pointer = opts.brief ? briefPointer(opts.brief.path, opts.brief.content) : null;
 
@@ -384,6 +390,7 @@ export async function openBlock(opts) {
   try {
     const { block, reused } = await mutateRun(runId, null, writeRow, async (record) => {
       if (record.blocks[id]?.status === 'open') throw new StateError('already-open', `block ${id} is already open`);
+      if (record.blocks[id]?.status === 'awaiting_human_check') throw new StateError('already-open', `block ${id} is awaiting a human check`);
       // B57: what each exact owned entry is on disk, under the lock (as `block claim`) — a regular
       // file owns only itself, here and in every later check
       const kinds = ownedKinds(record.workspace, owned);
@@ -391,6 +398,8 @@ export async function openBlock(opts) {
       const prior = previousTree(record);
       const baseSha = await resolveCommit(prior ? prior.base_sha : opts.base ?? 'HEAD', record.workspace);
       if (baseSha !== stampedBase || record.workspace !== workspace) throw new StateError('base-moved', `the base moved while block ${id} was being opened; run block open again`);
+      const branch = await git(['git', 'symbolic-ref', '--quiet', '--short', 'HEAD'], record.workspace, [0, 1]);
+      const baseBranch = branch.code === 0 ? branch.stdout.trim() : null;
       // B62a: the tree is planned (read-only checks) before the overlap check, which needs its path
       const planned = opts.worktree ? await opts.worktree({ baseSha, previous: prior }) : null;
       const self = { owned_files: owned, owned_kinds: kinds, worktree: planned ? { path: planned.path } : null };
@@ -402,7 +411,8 @@ export async function openBlock(opts) {
       // passed; a tree made here is rolled back below if the rows or the save then fail
       made = planned ? await planned.make() : null;
       const tree = made;
-      const entry = { block: id, base_sha: baseSha, owned_files: [...owned], owned_kinds: { ...kinds }, level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open', tree_at_open: treeOpen, ...(tests ? { test_files: tests } : {}), ...(tree ? { worktree: tree.worktree } : {}) };
+      const entry = { block: id, base_sha: baseSha, base_branch: baseBranch, owned_files: [...owned], owned_kinds: { ...kinds }, level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open', tree_at_open: treeOpen, ...(tests ? { test_files: tests } : {}), ...(tree ? { worktree: tree.worktree } : {}) };
+      if (humanChecks.length > 0) Object.assign(entry, { human_checks: humanChecks });
       record.blocks[id] = entry;
       const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
       const created = tree?.created ? [{ event: 'worktree.created', block: id, path: tree.worktree.path, branch: tree.worktree.branch, base: tree.worktree.base_sha }] : [];
@@ -411,7 +421,7 @@ export async function openBlock(opts) {
         rows: [
           ...(opts.decision ? [{ ...opts.decision, event: 'decision', decision_id: opts.decisionId ?? randomUUID(), block: id }] : []),
           ...created,
-          { event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines, ...(tests ? { test_files: tests } : {}) },
+          { event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, base_branch: baseBranch, owned_files: entry.owned_files, lines_forecast: lines, ...(tests ? { test_files: tests } : {}) },
         ],
       };
     });
@@ -444,11 +454,14 @@ export async function attemptBlock({ runId, id, writeRow }) {
  * in between touched a file this block owns (that is a conflict ⇒ stop). Rename detection is OFF
  * (`--no-renames`): a rename lists both its old and its new path, so moving an owned file away
  * is a conflict too. Never silent. Owned means `ownsFile` (B57: a directory entry owns the files
- * below it). B62a: refused for a block with its own worktree (`worktree-rebase`).
+ * below it). B62a: refused for an open block with its own worktree (`worktree-rebase`).
+ * B134: a closed worktree block instead rebases its branch onto its recorded base branch,
+ * retaining every changed owned file's blob; a conflict or changed blob restores the old head.
  * @param {{runId: string, id: string, head?: string, writeRow: WriteRow}} opts
  * @returns {Promise<{old_base: string, new_base: string}>}
  */
 export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
+  if (['closed', 'awaiting_human_check'].includes((await readRun(runId)).blocks[id]?.status)) return rebaseClosedBlock({ runId, id, writeRow });
   return mutateRun(runId, id, writeRow, async (record, block) => {
     // B62a: a worktree block's base is the commit its tree started from; moving it would leave the
     // tree on its old base, so the rebase is refused
@@ -466,6 +479,75 @@ export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
   });
 }
 
+/**
+ * Hash committed paths, with null for a deletion. NUL-delimited tree entries preserve unusual
+ * file names; filter exact names because git's path selection may also return descendants.
+ * @param {string} cwd @param {string} ref @param {string[]} files
+ * @returns {Promise<Map<string, string | null>>}
+ */
+async function committedBlobs(cwd, ref, files) {
+  const hashes = new Map(files.map((file) => [file, /** @type {string | null} */ (null)]));
+  if (files.length === 0) return hashes;
+  const tree = await git(['git', 'ls-tree', '-r', '-z', '--full-tree', ref, '--', ...files], cwd);
+  for (const entry of tree.stdout.split('\0').filter(Boolean)) {
+    const tab = entry.indexOf('\t');
+    const file = entry.slice(tab + 1);
+    if (hashes.has(file)) hashes.set(file, entry.slice(0, tab).split(' ')[2]);
+  }
+  return hashes;
+}
+
+/**
+ * Closed blocks have a separate mutation path: check their status again under the lock,
+ * restore the branch on failure (including a failed signed write), and retain closed/awaiting status.
+ * @param {{runId: string, id: string, writeRow: WriteRow}} opts
+ * @returns {Promise<{old_base: string, new_base: string}>}
+ */
+async function rebaseClosedBlock({ runId, id, writeRow }) {
+  return withRunLock(runId, async () => {
+    const record = await readRun(runId);
+    if (record.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
+    const block = record.blocks[id];
+    if (!['closed', 'awaiting_human_check'].includes(block?.status) || !block.worktree) throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
+    if (!block.base_branch) throw new StateError('rebase-no-base', `block ${id} has no recorded base branch`);
+    const tree = block.worktree.path;
+    const branch = await git(['git', 'symbolic-ref', '--quiet', 'HEAD'], tree, [0, 1]);
+    if (branch.stdout.trim() !== `refs/heads/${block.worktree.branch}`) throw new StateError('worktree-rebase', `block ${id}: its worktree is not on branch ${block.worktree.branch}`);
+    // A reset must never discard edits made after close, or abort an earlier rebase.
+    const status = await git(['git', 'status', '--porcelain'], tree);
+    if (status.stdout.length > 0) throw new StateError('rebase-conflict', 'rebase-conflict');
+    const oldHead = await resolveCommit('HEAD', tree);
+    const newBase = await resolveCommit(`refs/heads/${block.base_branch}`, record.workspace);
+    const top = await repoTop(record.workspace);
+    const prefix = path.relative(top, realpathSync(record.workspace)).split(path.sep).join('/');
+    const diff = await git(['git', 'diff', '--no-renames', '--name-only', '-z', block.base_sha, oldHead, '--'], tree);
+    const files = diff.stdout.split('\0').filter((file) => file.length > 0 && (
+      ownsFile(block.owned_files, file, block.owned_kinds) ||
+      (prefix !== '' && file.startsWith(`${prefix}/`) && ownsFile(block.owned_files, file.slice(prefix.length + 1), block.owned_kinds))
+    )).sort();
+    const before = await committedBlobs(tree, oldHead, files);
+    const moved = { old_base: block.base_sha, new_base: newBase };
+    try {
+      const rebased = await exec(['git', '-C', tree, 'rebase', newBase], { cwd: record.workspace, env: gitEnv(), timeoutMs: 30000 });
+      if (rebased.result !== 'ok') throw new StateError('rebase-conflict', 'rebase-conflict');
+      const after = await committedBlobs(tree, 'HEAD', files);
+      const changed = files.filter((file) => before.get(file) !== after.get(file));
+      if (changed.length > 0) throw new StateError('rebase-changed-reviewed', `rebase-changed-reviewed ${changed.join(', ')}`);
+      block.base_sha = newBase;
+      block.worktree.base_sha = newBase;
+      await writeSigned(runId, writeRow, { event: 'block.rebase', block: id, ...moved, closed: true });
+      await saveRun(record);
+      return moved;
+    } catch (err) {
+      // --abort restores a conflicted rebase; after a completed rebase there is nothing to
+      // abort, and reset restores the old branch head. The tree was clean before either.
+      await exec(['git', '-C', tree, 'rebase', '--abort'], { cwd: record.workspace, env: gitEnv(), timeoutMs: 30000 });
+      await git(['git', 'reset', '--hard', oldHead], tree);
+      throw err;
+    }
+  });
+}
+
 /**
  * `block claim` — assign one EXACT path (an orphan, or any unowned path) to `id`; refused for a
  * glob, and when another open block owns it — or anything it would own: the claimed path becomes an
@@ -513,13 +595,35 @@ export async function checkScope({ runId, id, files, writeRow }) {
 
 /** @param {{runId: string, id: string, reason: string, writeRow: WriteRow, event?: string}} opts */
 export async function stopBlock({ runId, id, reason, writeRow, event = 'block.stop' }) {
-  await mutateRun(runId, id, writeRow, (_record, block) => {
+  await mutateRun(runId, null, writeRow, (record) => {
+    const block = record.blocks[id];
+    if (!['open', 'awaiting_human_check'].includes(block?.status)) throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
     block.status = 'stopped';
     block.stop_reason = reason;
     return { result: undefined, rows: [{ event, block: id, reason }] };
   });
 }
 
+/**
+ * Called only after the CLI's terminal confirmation; recheck under the lock before signing.
+ * @param {{runId: string, id: string, note: string, proof?: string | null, writeRow: WriteRow, now?: Date}} opts
+ */
+export async function humanPassBlock({ runId, id, note, proof = null, writeRow, now = new Date() }) {
+  return mutateRun(runId, null, writeRow, (record) => {
+    const block = record.blocks[id];
+    if (block?.status !== 'awaiting_human_check') throw new StateError('not-awaiting', `block ${id} is not awaiting a human check`);
+    if (typeof note !== 'string' || note.trim().length === 0) throw new StateError('usage', 'block human-pass needs --note <text>');
+    if (proof !== null && (typeof proof !== 'string' || !existsSync(proof))) throw new StateError('usage', '--proof must name an existing directory or file');
+    const grant = record.autopilot;
+    if (grant && !['stopped', 'expired'].includes(grant.status) && !(now.getTime() >= Date.parse(grant.until))) {
+      throw new StateError('autopilot-active', `block human-pass is refused while an autopilot grant is active on run ${runId}`);
+    }
+    const row = { event: 'block.human_pass', block: id, note, proof, checks: [...block.human_checks], by: 'human' };
+    block.status = 'closed';
+    return { result: row, rows: [row] };
+  });
+}
+
 /**
  * B8's rows of the block gate, in order: worker pin ⇒ `worker.replaced`/`worker.down` (block
  * stopped); the block's signed `dispatch` row must exist and verify, and every other
@@ -533,16 +637,44 @@ export async function stopBlock({ runId, id, reason, writeRow, event = 'block.st
  *   livePid?: number, probe?: import('./run.mjs').StartTimeProbe,
  *   extraChecks?: Array<() => Promise<{ok: boolean, reason?: string}>>,
  *   closeRows?: Record<string, any>[],
+ *   dryRun?: boolean,
  * }} opts
- * @returns {Promise<{ok: boolean, status: 'closed' | 'stopped' | 'open', reason?: string, event?: string}>}
+ * @returns {Promise<{ok: boolean, status: 'closed' | 'awaiting_human_check' | 'stopped' | 'open', reason?: string, event?: string}>}
  */
-export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, extraChecks = [], closeRows = [] }) {
+export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, extraChecks = [], closeRows = [], dryRun = false }) {
   const record = await readRun(runId);
   if (record.blocks[id]?.status !== 'open') throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
 
-  const pin = await checkWorkerPin(record, { livePid, probe });
+  let pin = await checkWorkerPin(record, { livePid, probe });
+  const pins = record.workers ?? (record.worker ? [record.worker] : []);
+  const counted = rows.filter((row) => row.block === id && (row.run === undefined || row.run === runId) && row.event === 'review.result' && !['stale', 'unavailable', 'answers'].includes(row.status) && !(row.status === 'refused' && row.reason === 'other-run'));
+  // Ledgers written before B107 omit worker identity and use the run's pin check above.
+  if (counted.some((row) => row.worker !== undefined && !pins.some((p) => p.pid === row.worker?.pid && p.started_at === row.worker?.started_at))) {
+    pin = { ok: false, event: 'worker.replaced', reason: 'a counted review result does not name a pinned worker' };
+  }
+  if (pin.ok) {
+    const repoRoot = await repoRootOf(record.workspace);
+    let names;
+    try { names = readdirSync(reviewQueue.queueDir(repoRoot)); }
+    catch (err) { if (err.code !== 'ENOENT') throw err; names = []; }
+    for (const name of names.filter((n) => /^[0-9a-f]{24}\.json$/.test(n))) {
+      const ticket = name.slice(0, 24);
+      const queued = reviewQueue.readTicket(repoRoot, ticket);
+      if (queued.run !== runId || queued.block !== id) continue;
+      const claimKey = `ticket\0${runId}\0${ticket}`;
+      const file = path.join(os.homedir(), '.code-forge', 'locks', `${createHash('sha256').update(claimKey).digest('hex')}.lock`);
+      let claim;
+      try { claim = JSON.parse(readFileSync(file, 'utf8')); }
+      catch (err) { if (err.code === 'ENOENT') continue; throw err; }
+      const owner = pins.find((p) => p.pid === claim.pid && p.started_at === claim.start);
+      if (owner && !(await checkWorkerPin({ worker: owner }, { probe })).ok) {
+        pin = { ok: false, event: 'worker.down', reason: `dead pinned worker pid ${owner.pid} holds ticket ${ticket}` };
+        break;
+      }
+    }
+  }
   if (!pin.ok) {
-    await stopBlock({ runId, id, reason: pin.reason, writeRow, event: pin.event });
+    if (!dryRun) await stopBlock({ runId, id, reason: pin.reason, writeRow, event: pin.event });
     return { ok: false, status: 'stopped', event: pin.event, reason: pin.reason };
   }
 
@@ -555,25 +687,35 @@ export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, ex
     const reasons = bad.map((x) => `${x.row.event}: ${x.result.reason}`);
     if (!dispatchOk) reasons.push('no verified dispatch row');
     const reason = reasons.join('; ');
-    await stopBlock({ runId, id, reason, writeRow, event: 'ledger.tamper' });
+    if (!dryRun) await stopBlock({ runId, id, reason, writeRow, event: 'ledger.tamper' });
     return { ok: false, status: 'stopped', event: 'ledger.tamper', reason };
   }
 
+  const failures = [];
   for (const check of extraChecks) {
     const result = await check();
-    if (!result.ok) return { ok: false, status: 'open', reason: result.reason ?? 'check failed' };
+    if (!result.ok) {
+      if (!dryRun) return { ok: false, status: 'open', reason: result.reason ?? 'check failed' };
+      failures.push(result.reason ?? 'check failed');
+    }
+  }
+  if (dryRun) {
+    if (record.orphans.length > 0) failures.push(`orphans: ${record.orphans.join(', ')}`);
+    return { ok: failures.length === 0, status: 'open', ...(failures.length ? { reason: failures.join('; ') } : {}) };
   }
 
-  /** @typedef {{ok: boolean, status: 'closed' | 'stopped' | 'open', reason?: string, event?: string}} CloseResult */
+  /** @typedef {{ok: boolean, status: 'closed' | 'awaiting_human_check' | 'stopped' | 'open', reason?: string, event?: string}} CloseResult */
   return mutateRun(runId, id, writeRow, (current, block) => {
     if (current.orphans.length > 0) {
       /** @type {CloseResult} */
       const refused = { ok: false, status: 'open', reason: `orphans: ${current.orphans.join(', ')}` };
       return { result: refused, rows: [] };
     }
-    block.status = 'closed';
+    const checks = block.human_checks ?? [];
+    block.status = checks.length > 0 ? 'awaiting_human_check' : 'closed';
     /** @type {CloseResult} */
-    const closed = { ok: true, status: 'closed' };
-    return { result: closed, rows: [...closeRows, { event: 'block.close', block: id, status: 'complete' }] };
+    const closed = { ok: true, status: block.status };
+    return { result: closed, rows: [...closeRows, { event: 'block.close', block: id, status: 'complete' },
+      ...(checks.length > 0 ? [{ event: 'block.awaiting_human_check', block: id, checks }] : [])] };
   });
 }

package/src/state/run.mjs

@@ -12,6 +12,7 @@
  * parameter; the CLI verb does the static import) and are SIGNED with the run key first.
  */
 
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, rmdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { exec } from '../util/exec.mjs';
@@ -31,7 +32,7 @@ const LOCK_POLL_MS = 25;
  */
 export async function processStartTime(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return null;
-  const res = await exec(['ps', '-o', 'lstart=', '-p', String(pid)], {
+  const res = await exec([existsSync('/bin/ps') ? '/bin/ps' : 'ps', '-o', 'lstart=', '-p', String(pid)], {
     env: { ...process.env, LC_ALL: 'C' },
     okExitCodes: [0, 1],
     timeoutMs: 10000,
@@ -177,6 +178,7 @@ export async function startRun(opts) {
     orchestrator_pid: opts.orchestratorPid ?? process.pid,
     solo_pid: opts.soloPid ?? null,
     worker,
+    workers: worker ? [worker] : [],
     status: 'active',
     blocks: {},
     orphans: [],
@@ -250,6 +252,10 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
     if (oldHash === newHash) return { changed: [], oldHash, newHash, pinned: 0, rowError: null };
     const before = state && Object.hasOwn(stored, state.hash) ? stored[state.hash] : undefined;
     if (state && (before === null || typeof before !== 'object')) throw new StateError('config-snapshot', `run ${runId}: the current config snapshot is missing from the run record`);
+    // B138: close authority belongs to the run-start snapshot, including legacy runs.
+    if (before?.close?.require_human !== config.close?.require_human) {
+      throw new StateError('immutable-key', 'close.require_human cannot change mid-run (fixed by the owner before the run starts)');
+    }
     /** @type {string[]} */
     let frozen;
     if (state) {
@@ -309,15 +315,18 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
 
 /**
  * `run start --reattach`: re-pin a restarted worker (the orchestrator only — §4.8).
- * @param {{runId: string, workerPid: number, writeRow: WriteRow, probe?: StartTimeProbe}} opts
+ * @param {{runId: string, workerPid: number, writeRow: WriteRow, probe?: StartTimeProbe, add?: boolean}} opts
  */
-export async function reattachWorker({ runId, workerPid, writeRow, probe = processStartTime }) {
+export async function reattachWorker({ runId, workerPid, writeRow, probe = processStartTime, add = false }) {
   if (!isSignalablePid(workerPid)) throw new StateError('bad-worker-pid', 'worker pid must be an integer > 1');
   return withRunLock(runId, async () => {
     const current = await readRun(runId);
     if (current.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
-    current.worker = await pinWorker(workerPid, probe);
-    await writeSigned(runId, writeRow, { event: 'worker.reattach', pid: workerPid });
+    const pin = await pinWorker(workerPid, probe);
+    const pins = current.workers ?? (current.worker ? [current.worker] : []);
+    current.workers = add ? [...pins, pin] : [pin];
+    current.worker = current.workers[0];
+    await writeSigned(runId, writeRow, { event: add ? 'worker.add' : 'worker.reattach', pid: workerPid });
     await saveRun(current);
     return current;
   });
@@ -331,7 +340,18 @@ export async function reattachWorker({ runId, workerPid, writeRow, probe = proce
  * @returns {Promise<{ok: boolean, event?: 'worker.replaced' | 'worker.down', reason?: string}>}
  */
 export async function checkWorkerPin(record, { livePid, probe = processStartTime } = {}) {
-  const pin = record.worker;
+  let pin = record.worker;
+  if (record.workers?.length > 1) {
+    const pins = record.workers;
+    if (pins.some((p) => !isSignalablePid(p.pid)) || (livePid !== undefined && !pins.some((p) => p.pid === livePid))) {
+      return { ok: false, event: 'worker.replaced', reason: 'the live worker does not match a pinned worker' };
+    }
+    if (livePid === undefined) {
+      const live = await Promise.all(pins.map(async (p) => (await probe(p.pid)) === p.started_at));
+      return live.some(Boolean) ? { ok: true } : { ok: false, event: 'worker.down', reason: 'no pinned worker is running' };
+    }
+    pin = pins.find((p) => p.pid === livePid);
+  }
   if (!pin) return { ok: false, event: 'worker.down', reason: 'no worker is pinned for this run' };
   if (!isSignalablePid(pin.pid)) return { ok: false, event: 'worker.replaced', reason: 'the pinned worker pid is not an integer > 1' };
   if (livePid !== undefined && livePid !== pin.pid) {
@@ -380,14 +400,21 @@ export async function endRun({ runId, writeRow, stopWorker = stopPinnedWorker, p
   return withRunLock(runId, async () => {
     const current = await readRun(runId);
     if (current.status !== 'active') throw new StateError('run-ended', `run ${runId} has already ended`);
+    const awaiting = Object.keys(current.blocks).filter((id) => current.blocks[id].status === 'awaiting_human_check');
+    if (awaiting.length > 0) throw new StateError('awaiting-human-check', `run ${runId} has blocks awaiting human check: ${awaiting.join(', ')}; human-pass or stop them first`);
     const open = Object.keys(current.blocks).filter((id) => current.blocks[id].status === 'open');
     if (open.length > 0) throw new StateError('open-blocks', `run ${runId} still has open blocks: ${open.join(', ')}`);
     const pin = await checkWorkerPin(current, { probe });
     if (!pin.ok) await writeSigned(runId, writeRow, { event: pin.event, reason: pin.reason });
-    const stop = pin.ok ? await stopWorker(current.worker, { probe }) : { stopped: false };
+    let stopped = false;
+    for (const worker of current.workers ?? (current.worker ? [current.worker] : [])) {
+      if ((await checkWorkerPin({ worker }, { probe })).ok) {
+        stopped = (await stopWorker(worker, { probe })).stopped || stopped;
+      }
+    }
     current.status = 'ended';
     current.ended_at = new Date().toISOString();
-    await writeSigned(runId, writeRow, { event: 'run.end', worker_check: pin.ok ? 'ok' : pin.event, worker_stopped: stop.stopped });
+    await writeSigned(runId, writeRow, { event: 'run.end', worker_check: pin.ok ? 'ok' : pin.event, worker_stopped: stopped });
     await saveRun(current);
     return current;
   });

package/src/util/forbidden.mjs

@@ -282,6 +282,7 @@ export const FORBIDDEN = Object.freeze(
  *  - `--no-require-reviews` — the human's way out of `block close`'s per-file review check;
  *  - `--remove-worktree` (B62a) — `block close` removing the block's worktree, the orchestrator's
  *    alone. `block close` itself is not on this list, so the flag is listed on its own.
+ *  - `code-forge block human-pass` (B137) — passing a human device check is human-only.
  * @type {ReadonlyArray<ForbiddenEntry>}
  */
 export const CODER_ONLY_FORBIDDEN = Object.freeze(
@@ -346,6 +347,19 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
       prefixes: [['code-forge', 'block', 'ack-waivers'], ['forge', 'block', 'ack-waivers']],
       description: 'Acknowledge agent waivers — human-only, confirmed in the human terminal (B124b)',
     },
+    {
+      id: 'code-forge-block-human-pass-from-coder',
+      kind: 'anyPrefix',
+      prefixes: [['code-forge', 'block', 'human-pass'], ['forge', 'block', 'human-pass']],
+      description: 'Pass a human device check — human-only, confirmed in the human terminal (B137)',
+    },
+    {
+      id: 'code-forge-add-worker-from-coder',
+      kind: 'commandFlag',
+      command: ['code-forge', 'run', 'start'],
+      groups: [{ anyOf: ['--add-worker'] }],
+      description: 'Add a review worker to a run — the orchestrator only (B107)',
+    },
   ].map(freezeEntry),
 );
 

package/src/util/reaper.mjs

@@ -27,7 +27,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 
@@ -85,7 +85,7 @@ export function isAlive(pid) {
 export function readStartTime(pid) {
   if (!isValidPid(pid)) return null;
   try {
-    const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+    const out = execFileSync(existsSync('/bin/ps') ? '/bin/ps' : 'ps', ['-o', 'lstart=', '-p', String(pid)], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
       env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
@@ -165,7 +165,7 @@ export function groupMembers(pgid) {
   const members = new Map();
   let out = '';
   try {
-    out = execFileSync('ps', ['-A', '-o', 'pid=,pgid=,lstart='], {
+    out = execFileSync(existsSync('/bin/ps') ? '/bin/ps' : 'ps', ['-A', '-o', 'pid=,pgid=,lstart='], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
       env: { ...process.env, LC_ALL: 'C', LANG: 'C' },

package/src/worker/engine.mjs

@@ -95,13 +95,13 @@ import { askJev } from '../decide/jev-client.mjs';
 import { planAndRecord, tierOf } from '../review/budget.mjs';
 import { budgetFor } from '../review/packet.mjs';
 import { ContextError, reviewDigest } from '../context/pack.mjs';
-import { reviewFile, rulesRisk } from '../review/engine.mjs';
+import { reviewFile, reviewLightBatch, rulesRisk } from '../review/engine.mjs';
 import { reviewAnswers } from '../review/answers.mjs';
 import { peerDiffReader } from '../review/moved.mjs';
 import { computeFileSet, ownsFile } from '../gates/scope.mjs';
 import { extraRoundsFor, newFileState, reopenForExtraRound, runRound } from '../review/fixloop.mjs';
 import { reopenRowFor } from '../review/reopen.mjs';
-import { readRun } from '../state/run.mjs';
+import { processStartTime, readRun } from '../state/run.mjs';
 import { StateError } from '../state/paths.mjs';
 import { blockTree, worktreeRecord } from '../proof/worktree.mjs';
 import { ledgerSchemaHistory } from '../review/schema-fallback.mjs';
@@ -109,7 +109,7 @@ import { verifyRow } from '../state/signer.mjs';
 import { redact } from '../util/redact.mjs';
 import { withLock } from '../util/file-locks.mjs';
 import { blockAnchors, blockRungUsed, loadState, RESTORED_EVENT, saveState } from './review-state.mjs';
-import { assertAnswers } from './queue.mjs';
+import { assertAnswers, enqueueHash, isDone, writeResult } from './queue.mjs';
 import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } from './ticket.mjs';
 
 /**
@@ -127,6 +127,8 @@ import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } fro
  *   the worker's and a per-call `cfg` wins).
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow] - a signed ledger row
  *   (the worker adds `run`, `block`, `file`, `content_hash`).
+ * @property {(row: Record<string, any>) => Promise<unknown>} [writeBlockRow] - light fanout rows;
+ *   the worker pins run and block, while the batch supplies each file and content hash.
  * @property {Buffer} [key] - the run's HMAC key: signs the fix-loop state. Absent ⇒ engine only.
  * @property {() => Promise<Array<Record<string, any>>>} [readRows] - the run's ledger rows (the
  *   `review.state` anchors the state is checked against); required with `key`.
@@ -197,7 +199,7 @@ export async function blockEntryFor(runId, block) {
       throw new Error('worktree-malformed');
     }
   }
-  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, testFiles, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
+  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, testFiles, acceptance: entry.acceptance, kind: entry.kind === 'light' ? 'light' : blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
 }
 
 /** @typedef {{path: string, branch: string, base_sha: string}} WorktreeEntry */
@@ -411,6 +413,10 @@ export async function reviewTicket(ticket, ctx) {
       return { status: 'unavailable', reason: 'context-unreadable', approved: false, engine: 'adaptive', sessions: [] };
     }
     const digest = rulesDigest === '' ? {} : { rulesDigest };
+    if (entry.kind === 'light' && ctx.key) {
+      const batch = await lightRound(ticket, tctx, { entry, workDir, factsExcerpt, rulesDigest });
+      if (batch) return batch;
+    }
     if (!ctx.key) {
       return await reviewFile(
         { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs, ...(await fileContext()) },
@@ -423,6 +429,56 @@ export async function reviewTicket(ticket, ctx) {
   }
 }
 
+/** Serialize a light block across tickets/workers; durable signed rows enforce the two-batch cap.
+ * A batch completes every file's queue ticket, including files queued after this ticket started.
+ * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
+ * @param {{entry: Awaited<ReturnType<typeof blockEntryFor>>, workDir: string, factsExcerpt: string, rulesDigest: string}} input
+ * @returns {Promise<ReviewOutcome | null>} null enters the ordinary per-file loop.
+ */
+async function lightRound(ticket, ctx, { entry, workDir, factsExcerpt, rulesDigest }) {
+  if (!ctx.key || !ctx.readRows || !ctx.writeBlockRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
+  const key = ctx.key, readRows = ctx.readRows, writeRow = ctx.writeBlockRow;
+  const worker = { pid: process.pid, started_at: await processStartTime(process.pid) };
+  return withLock(`light:${ctx.runId}\0${ticket.block}`, async () => {
+    const root = ctx.contentRoot ?? ctx.repoRoot;
+    const files = (await computeFileSet({ cwd: root, base: entry.base ?? 'HEAD' })).all.filter((file) => ownsFile(entry.owned, file, entry.ownedKinds)).sort();
+    const hashes = files.map((file) => ({ file, content_hash: contentHash(root, file) }));
+    if (!hashes.some((f) => f.file === ticket.file && f.content_hash === ticket.content_hash)) return { status: 'stale', approved: false, engine: 'adaptive', sessions: [] };
+    const signature = JSON.stringify([entry.base, hashes]);
+    const rows = (await readRows()).filter((r) => r.run === ctx.runId && r.block === ticket.block && verifyRow(r, key).ok);
+    const cached = rows.filter((r) => r.event === 'review.light_result' && r.signature === signature).at(-1)?.outcomes?.[ticket.file];
+    if (cached && (cached.status === 'reviewed' || isDone(ctx.repoRoot, ticket.ticket))) return cached;
+    const count = rows.filter((r) => r.event === 'review.light_batch').length;
+    if (count >= 2) return null;
+    const round = count + 1;
+    // Reserve before the session: a crash cannot reset the cap on a worker restart.
+    await writeRow({ event: 'review.light_batch', round, signature });
+    const batch = await reviewLightBatch({ repoRoot: root, files, base: entry.base, cfg: ctx.cfg, workDir, factsExcerpt, rulesDigest }, { spawn: ctx.spawn, writeRow });
+    const moved = hashes.some((f) => contentHash(root, f.file) !== f.content_hash);
+    const findings = batch.findings ?? [];
+    const blocking = findings.some((f) => f.severity === 'critical' || f.severity === 'warning');
+    /** @type {Record<string, ReviewOutcome>} */
+    const outcomes = {};
+    for (const { file, content_hash } of hashes) {
+      const own = findings.filter((f) => f.file === file);
+      const approved = !moved && batch.status === 'reviewed' && (batch.approved || blocking) && own.every((f) => f.severity === 'nit');
+      const outcome = { ...batch, ...(moved ? { status: 'stale' } : {}), approved, findings: own, round, kind: 'full', level: entry.level,
+        next: { action: approved ? 'complete' : 'fix', level: entry.level } };
+      outcomes[file] = outcome;
+      if (batch.status === 'reviewed' && !moved) {
+        await writeRow({ event: 'review.round', file, content_hash, round, kind: 'full', level: entry.level, open_after: own.filter((f) => f.severity !== 'nit').length });
+        if (approved) await writeRow({ event: 'review.approved', file, content_hash });
+      }
+      const queued = enqueueHash({ repoRoot: ctx.repoRoot, run: ctx.runId, block: ticket.block, file, content_hash, ...(ticket.tree ? { tree: ticket.tree } : {}) });
+      const open = approved ? [] : own;
+      await writeRow({ event: 'review.result', ticket: queued.ticket, file, content_hash, status: outcome.status, approved, open, worker });
+      writeResult({ repoRoot: ctx.repoRoot, runId: ctx.runId, ticket: queued.ticket, result: { ...outcome, block: ticket.block, file, content_hash, open, worker }, key });
+    }
+    await writeRow({ event: 'review.light_result', signature, outcomes });
+    return outcomes[ticket.file];
+  });
+}
+
 /**
  * B56: the block's OTHER changed files — the §4.1 file set since the block base (tracked changes ∪
  * untracked), filtered to the block's owned files (`ownsFile`, as the budget row does), minus the