@codedology/code-forge 0.7.7 → 0.9.0

package/src/util/tmp.mjs

@@ -130,18 +130,30 @@ export function tmpBase(root) {
 }
 
 /**
- * Create (if needed) the run root `<base>/<runId>/`, record this process as its owner, and
- * return its real absolute path.
+ * The run root's path `<base>/<runId>`, without creating anything (B69: doctor looks for old
+ * review-state files there). The same run id check as {@link runRoot}.
  * @param {string} runId
  * @param {{root?: string}} [opts]
  * @returns {string}
+ * @throws {TypeError} a bad run id, or a `root` that is not absolute.
  */
-export function runRoot(runId, opts = {}) {
+export function runRootPath(runId, opts = {}) {
   if (typeof runId !== 'string' || !RUN_ID.test(runId)) {
     throw new TypeError('tmp: runId must be one path segment of letters, digits, ".", "_" or "-"');
   }
+  return path.join(tmpBase(opts.root), runId);
+}
+
+/**
+ * Create (if needed) the run root `<base>/<runId>/`, record this process as its owner, and
+ * return its real absolute path.
+ * @param {string} runId
+ * @param {{root?: string}} [opts]
+ * @returns {string}
+ */
+export function runRoot(runId, opts = {}) {
+  const dir = runRootPath(runId, opts);
   const base = tmpBase(opts.root);
-  const dir = path.join(base, runId);
   // A parallel sweep that claimed a dead root of this name renames it away (see the claim rule)
   // between our mkdir and our write: the directory is then "missing" or the write fails with
   // ENOENT, and the retry creates a fresh directory in its place. A tombstone itself can never be

package/src/worker/engine.mjs

@@ -17,6 +17,13 @@
  *  - `stopped` (`review_cap`, `l3_patch_exhausted`, `split_required`) ⇒ no session: the result
  *    repeats the stop — only the human moves on (§4.11 rule 5). A `split_required` result (round 1
  *    or a recheck stop) carries `tokens_in` and `budget` (B54).
+ * A state that does not load is refused with no session: `review-state-tampered` (a wrong file or
+ * anchor) or `review-state-lost` (the file is gone and its anchor has no `state_body`). A file
+ * that is gone but whose anchor carries the signed body is `restored` (B68): saved as a new seq,
+ * one signed `review.state_restored {block, file, seq, from_seq}` row, then the round runs as if
+ * it had loaded. B69: the state file lives under the code-forge home (`runs/<run>/review-state/`),
+ * not the temp root; a valid file still at the old temp path is moved there on its first load
+ * (status `ok`, no restored row).
  * The round's outcome: `approved: true` ONLY when the loop is `complete` AND its signed
  * `review.approved` row (keyed `run, block, file, content_hash` = the ticket's hash) was written;
  * else `findings` = the open fix list, `next` = what the orchestrator does (`fix` at `level`,
@@ -40,31 +47,79 @@
  * The review NEVER approves an empty or failed session: that is `unavailable` (§4.2 stub guard).
  * A throw inside the round is `unavailable` too, with the state saved as `next: retry` (see
  * `fixLoopRound`): the next ticket re-runs that round, never a fresh round 1.
+ * B62b: for a block the run record gives a worktree (`proof.isolation: worktree`) every content
+ * read — the file, its diff against the block base, the peers' diffs, the fix hunks and the
+ * budget's file set — happens in that tree, against the tree's `base_sha` (`contentRootFor`; the
+ * tree comes from the run record, never from the coder-writable ticket), and the packet's facts
+ * slot names the tree and its branch. A file changed only in the main tree is never seen. The
+ * base, the tree and the facts come from ONE read of the run record. A ticket is `unavailable`
+ * with one of these reasons:
+ *  - `worktree-missing`: the recorded tree is gone;
+ *  - `worktree-not-dir`: its path is not a directory;
+ *  - `worktree-malformed`: no absolute path, a branch that is empty or has control characters, or
+ *    a base_sha that is not a full hex id;
+ *  - `worktree-branch-mismatch`: the tree is not on its recorded branch;
+ *  - `worktree-foreign`: the tree belongs to another repository;
+ *  - `worktree-workspace-missing`: the workspace's subdirectory is not in the tree;
+ *  - `worktree-mismatch`: the tree the worker hashed the ticket in (`ctx.contentRoot`, from the
+ *    ticket's `tree` or its absence) is not the record's tree;
+ *  - `git-failed`: git could not be run on the tree;
+ *  - `run-record-unreadable`: the record cannot be parsed, or names no workspace.
+ * A block without a worktree, or one the run record does not know, reads the main tree as before.
+ * B63a: a ticket is also `unavailable` with `context-unreadable` when the config's `context` key
+ * is bad or one of its rules or lessons files is missing, outside the repository or unreadable at
+ * review time; no session runs and the packet dir is removed. The worker does not retry it (the
+ * ticket is done); `review-file` on the same content is a fresh attempt every time (`retry: true`).
+ * The tree is passed as `contentRoot`: `repoRoot` stays the main tree, and the fix-loop state
+ * stays under the run root.
+ * B72: a verified `review.reopened {by: human}` row of this run for the file whose `at_seq` is the
+ * file's latest anchor seq (`reopenRowFor`, `review/reopen.mjs`) restarts a `stopped` file whose
+ * content changed since the stop, or a `lost` one: a new state (round 1, a FULL review with no
+ * `reviewed_content`, the level from the run record), saved at `at_seq + 1`, so the row works
+ * once; no `review.state_restored` row then. The block's L3 rung stays spent (it is read from the
+ * anchors). A row that does not verify, of another run, not `by: human`, at another seq, or a
+ * stopped file on the stop's own content changes nothing: the stop (or the lost refusal) repeats.
+ * Every stop records the ticket's content hash as the state's `stop_content_hash` (signed with
+ * the state), the content `block reopen` and this check compare against.
+ * B71: a ticket with `kind: 'answers'` (`review-file --answers`) runs no fix-loop round: after the
+ * same run-record, tree and mismatch checks it goes to `reviewAnswers` (`review/answers.mjs`) —
+ * one fresh L2 session that judges whether the answering file resolves the named open findings of
+ * the source, with signed `review.answered` rows for the resolved ones; the source's fix-loop
+ * state is neither read for a round nor saved.
  */
 
-import { rmSync } from 'node:fs';
+import { realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { blockKind } from '../decide/escalation.mjs';
 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 { 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 { StateError } from '../state/paths.mjs';
+import { blockTree, worktreeRecord } from '../proof/worktree.mjs';
 import { ledgerSchemaHistory } from '../review/schema-fallback.mjs';
 import { verifyRow } from '../state/signer.mjs';
 import { redact } from '../util/redact.mjs';
 import { keyedLock } from '../util/locks.mjs';
-import { blockAnchors, blockRungUsed, loadState, saveState } from './review-state.mjs';
-import { assertTicketId } from './ticket.mjs';
+import { blockAnchors, blockRungUsed, loadState, RESTORED_EVENT, saveState } from './review-state.mjs';
+import { assertAnswers } from './queue.mjs';
+import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } from './ticket.mjs';
 
 /**
  * @typedef {object} ReviewContext
- * @property {string} repoRoot
+ * @property {string} repoRoot - the main tree (the queue, the worker).
+ * @property {string} [contentRoot] - B62b: the tree the ticket's content is read in (the block's
+ *   worktree); `repoRoot` when absent.
  * @property {string} runId
- * @property {string} runRootDir - the run's temp root (packets and session dirs live under it).
+ * @property {string} runRootDir - the run's temp root (packets and session dirs live under it; the
+ *   review state no longer does — B69 — it is only read there once, to move an old file).
  * @property {Record<string, any>} cfg - the project config.
  * @property {string | null} jevKey - resolved once by the worker through B2's chain; never print.
  * @property {(opts: Record<string, any>) => Promise<Record<string, any>>} spawn - one isolated
@@ -86,6 +141,7 @@ import { assertTicketId } from './ticket.mjs';
  * @property {string} engine - `adaptive` or `consensus`.
  * @property {Array<Record<string, any>>} sessions - one summary per session run.
  * @property {string} [reason] - why it is not `reviewed` (stub-guard reason, `needs_file-refused`, …).
+ * @property {string} [message] - a refusal's human-readable explanation (`review-state-lost`).
  * @property {Array<Record<string, any>>} [findings] - the open fix list (`reviewed` / `stopped`).
  * @property {number} [round] - the fix-loop round this ticket ran (patch_check rounds not counted).
  * @property {string} [kind] - `full`, `recheck` or `patch_check`.
@@ -110,14 +166,17 @@ import { assertTicketId } from './ticket.mjs';
  * of its owned files. `ownedKinds` is the recorded `owned_kinds` (B57: which exact entries were
  * regular files at `block open`/`claim`), `{}` when there is none (every exact entry directory-like).
  *   With no run record the kind is null: `reviewTicket` takes the ticket file's kind.
- * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, acceptance?: unknown, kind: string | null}>}
+ * `tree` (B62b) is the recorded `worktree` `{path, branch, base_sha}`, null when the block has
+ * none; `base` is then the tree's `base_sha`. A recorded worktree that `worktreeRecord` refuses
+ * (path, branch, hex base_sha) throws `worktree-malformed`.
+ * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, acceptance?: unknown, kind: string | null, tree: WorktreeEntry | null, workspace: string | null}>}
  */
 export async function blockEntryFor(runId, block) {
   let record;
   try {
     record = await readRun(runId);
   } catch (err) {
-    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, acceptance: undefined, kind: null };
+    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, acceptance: undefined, kind: null, tree: null, workspace: null };
     throw new Error('run-record-unreadable');
   }
   if (!record || typeof record !== 'object' || !record.blocks || typeof record.blocks !== 'object') throw new Error('run-record-unreadable');
@@ -128,7 +187,85 @@ export async function blockEntryFor(runId, block) {
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files.filter((f) => typeof f === 'string') : [];
   const kinds = entry.owned_kinds;
   const ownedKinds = kinds && typeof kinds === 'object' && !Array.isArray(kinds) ? kinds : {};
-  return { base: sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }) };
+  /** @type {WorktreeEntry | null} */
+  let tree = null;
+  if (entry.worktree !== undefined && entry.worktree !== null) {
+    try {
+      tree = worktreeRecord(entry.worktree);
+    } catch {
+      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, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
+}
+
+/** @typedef {{path: string, branch: string, base_sha: string}} WorktreeEntry */
+
+/** The refusals of {@link blockTree} a ticket answers with, as its `reason`. */
+const TREE_CODES = new Set(['worktree-malformed', 'worktree-missing', 'worktree-not-dir', 'worktree-branch-mismatch', 'worktree-workspace-missing', 'worktree-foreign', 'git-failed']);
+
+/**
+ * B62b: where the content of a ticket of `block` is read — the top of the block's worktree from
+ * the run record (`blockTree`: present, a directory, on its recorded branch, of this repository),
+ * else `repoRoot`. `repoRoot` exactly as before B62b when there is no run record, the block is not
+ * in it, or it has no `worktree`: only a block WITH a worktree record can be refused here.
+ * @param {string} runId @param {string} block @param {string} repoRoot
+ * @returns {Promise<string>}
+ * @throws {WorkerError} a code of {@link TREE_CODES}, or `run-record-unreadable` for a record that
+ *   cannot be parsed or is not a record; any other failure (an I/O error) is rethrown.
+ */
+export async function contentRootFor(runId, block, repoRoot) {
+  let record;
+  try {
+    record = await readRun(runId);
+  } catch (err) {
+    if (/** @type {any} */ (err)?.code === 'no-run') return repoRoot;
+    if (err instanceof SyntaxError) throw new WorkerError('run-record-unreadable', `block ${block}: the run record cannot be read`);
+    throw err;
+  }
+  if (record === null || typeof record !== 'object') throw new WorkerError('run-record-unreadable', `block ${block}: the run record cannot be read`);
+  const blocks = record.blocks;
+  const entry = blocks && typeof blocks === 'object' && typeof block === 'string' && Object.hasOwn(blocks, block) ? blocks[block] : null;
+  if (entry?.worktree === undefined || entry.worktree === null) return repoRoot;
+  return treeTopOf(record.workspace, block, entry.worktree);
+}
+
+/**
+ * The realpath'd top of the recorded worktree `worktree` of `block` (`blockTree`).
+ * @param {string} workspace @param {string} block @param {unknown} worktree
+ * @returns {Promise<string>}
+ * @throws {WorkerError} a code of {@link TREE_CODES}; any other failure is rethrown.
+ */
+async function treeTopOf(workspace, block, worktree) {
+  if (typeof workspace !== 'string' || !path.isAbsolute(workspace)) throw new WorkerError('run-record-unreadable', `block ${block}: the run record names no workspace`);
+  try {
+    return /** @type {import('../proof/worktree.mjs').BlockTree} */ (await blockTree(workspace, { worktree })).top;
+  } catch (err) {
+    const code = /** @type {any} */ (err)?.code;
+    if (err instanceof StateError && TREE_CODES.has(code)) throw new WorkerError(code, `block ${block}: ${err.message}`);
+    throw err;
+  }
+}
+
+/** @param {string} p @returns {string} `p` realpath'd, or `p` itself when it cannot be resolved. */
+export function canonicalPath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * The packet's facts slot: the acceptance clauses, and for a block with a worktree (B62b) a line
+ * naming the tree and its branch the file is reviewed in.
+ * @param {{acceptance?: unknown, tree: WorktreeEntry | null}} entry @param {Record<string, any> | undefined} cfg
+ * @returns {string}
+ */
+function factsFor(entry, cfg) {
+  const excerpt = acceptanceExcerpt(entry.acceptance, cfg);
+  if (!entry.tree) return excerpt;
+  return `${excerpt}\nWorktree: the file is reviewed as it is in the block's worktree ${redact(entry.tree.path)} (branch ${redact(entry.tree.branch)}), against the block base.`;
 }
 
 /** The acceptance line written when the block's clauses cannot be read. */
@@ -213,15 +350,51 @@ export async function reviewTicket(ticket, ctx) {
     return { status: 'unavailable', reason: err instanceof Error ? err.message : 'run-record-unreadable', approved: false, engine: 'adaptive', sessions: [] };
   }
   if (entry.kind === null) entry = { ...entry, kind: blockKind({ owned: [ticket.file] }) };
-  const peerDiffs = blockPeerDiffs(ctx.repoRoot, { base: entry.base, owned: entry.owned, ownedKinds: entry.ownedKinds, file: ticket.file });
+  // B62b: every content read of this ticket happens in the block's tree (the main tree without
+  // one), taken from the SAME entry as the base and the facts. The worker passes the tree it
+  // hashed the ticket in as `ctx.contentRoot`; a record that changed since names another tree.
+  let contentRoot;
+  try {
+    contentRoot = entry.tree ? await treeTopOf(entry.workspace, ticket.block, entry.tree) : ctx.repoRoot;
+  } catch (err) {
+    return { status: 'unavailable', reason: err instanceof WorkerError ? err.code : 'run-record-unreadable', approved: false, engine: 'adaptive', sessions: [] };
+  }
+  if (ctx.contentRoot !== undefined && canonicalPath(ctx.contentRoot) !== canonicalPath(contentRoot)) {
+    return { status: 'unavailable', reason: 'worktree-mismatch', approved: false, engine: 'adaptive', sessions: [] };
+  }
+  /** @type {ReviewContext} */
+  const tctx = { ...ctx, contentRoot };
+  if (ticket.kind === 'answers') {
+    // B71: an answers ticket is no review round: one answers session, the fix-loop state untouched
+    try {
+      return await reviewAnswers(ticket, tctx, { entry, workDir, io: { readFile: readRegularFileNoFollow, loadState, assertAnswers } });
+    } finally {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  }
+  const factsExcerpt = factsFor(entry, ctx.cfg);
+  const peerDiffs = blockPeerDiffs(contentRoot, { base: entry.base, owned: entry.owned, ownedKinds: entry.ownedKinds, file: ticket.file });
   try {
+    // B63a: the `context` rules and lessons, read from the MAIN tree (`ctx.repoRoot`, never the
+    // block's worktree) with the config in force for this ticket; '' without a `context` key, so
+    // the packet stays as it was. A bad `context` value or a rules/lessons file that is missing,
+    // outside the repository or unreadable makes the ticket `unavailable` (`context-unreadable`,
+    // re-queued by `review-file` on the same content, as often as asked): no review runs without the rules it was promised.
+    let rulesDigest;
+    try {
+      rulesDigest = reviewDigest({ repoRoot: ctx.repoRoot, cfg: ctx.cfg });
+    } catch (err) {
+      if (!(err instanceof ContextError)) throw err;
+      return { status: 'unavailable', reason: 'context-unreadable', approved: false, engine: 'adaptive', sessions: [] };
+    }
+    const digest = rulesDigest === '' ? {} : { rulesDigest };
     if (!ctx.key) {
       return await reviewFile(
-        { repoRoot: ctx.repoRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg), peerDiffs },
+        { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs },
         { spawn: ctx.spawn, ...(ctx.writeRow ? { writeRow: ctx.writeRow } : {}) },
       );
     }
-    return await fixLoopRound(ticket, ctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg), peerDiffs });
+    return await fixLoopRound(ticket, tctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt, rulesDigest, peerDiffs });
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -274,6 +447,9 @@ export function blockPeerDiffs(repoRoot, { base, owned, ownedKinds, file }) {
  */
 export const blockLockKey = (runId, block) => `block:${runId}\0${block}`;
 
+/** B68: the `review-state-lost` refusal's message (the file is gone and the ledger has no body). */
+export const LOST_MESSAGE = 'the review state file is gone and the ledger cannot rebuild it (its anchor carries no state_body); the file is not reviewed again from round 1 — the owner can run `code-forge block reopen`';
+
 /**
  * Whether the block's one L3 rung is taken: a verified anchor says so (`blockRungUsed`), OR another
  * file of the block has a saved state whose round decided `next: patch` — that round took the rung,
@@ -290,11 +466,12 @@ export function rungTaken(where) {
   for (const file of siblings) {
     let other;
     try {
-      other = loadState({ ...where, file });
+      other = loadState({ ...where, file, migrate: false }); // B69: a sibling's old file is read, never moved here
     } catch {
       return { status: 'ok', used: true };
     }
-    if (other.status !== 'ok' || other.state?.next?.action === 'patch') return { status: 'ok', used: true };
+    // a sibling that would be restored (B68) counts by its rebuilt state; lost or tampered fails closed
+    if ((other.status !== 'ok' && other.status !== 'restored') || other.state?.next?.action === 'patch') return { status: 'ok', used: true };
   }
   return rung;
 }
@@ -329,10 +506,10 @@ export function mayTakeRung(state, kind, cfg, rungUsed) {
  * first full round, or any round once the rung is gone) runs outside the block lock, in parallel
  * with the block's other files.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, rulesDigest?: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, peerDiffs }) {
+async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, rulesDigest = '', peerDiffs }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
   const readRows = ctx.readRows;
   /** @type {{outcome: ReviewOutcome} | {round: () => Promise<ReviewOutcome>}} */
@@ -349,11 +526,34 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
       await recordBlockBudget(ticket, ctx, { base, owned, ownedKinds });
     }
     const where = { runRootDir: ctx.runRootDir, runId: ctx.runId, block: ticket.block, file: ticket.file, key, rows };
-    const loaded = loadState(where);
+    const loaded = loadState({ ...where, contentRoot: ctx.contentRoot ?? ctx.repoRoot });
     const rung = rungTaken(where);
     if (loaded.status === 'tampered' || rung.status === 'tampered') return { outcome: /** @type {ReviewOutcome} */ ({ status: 'refused', reason: 'review-state-tampered', approved: false, engine: 'adaptive', sessions: [] }) };
+    // B72: the human's `block reopen` row for this file's latest anchor seq restarts a stopped
+    // (on changed content) or lost file: a new state, saved at that seq + 1 — the row works once
+    // (`rows`: this run's rows read above under the block lock; `key`: the run key from opts)
+    const reopenAt = {
+      runId: ctx.runId,
+      block: ticket.block,
+      file: ticket.file,
+      key,
+      status: loaded.status,
+      state: loaded.state,
+      seq: loaded.seq,
+      contentHash: ticket.content_hash,
+    };
+    const reopened = reopenRowFor(rows, reopenAt) !== null;
+    if (loaded.status === 'lost' && !reopened) return { outcome: /** @type {ReviewOutcome} */ ({ status: 'refused', reason: 'review-state-lost', message: LOST_MESSAGE, approved: false, engine: 'adaptive', sessions: [] }) };
+    let seq = loaded.seq;
+    if (loaded.status === 'restored' && loaded.state !== null && !reopened) {
+      // B68: the lost file is rebuilt from the anchor's signed body; saved as a new seq, then recorded
+      const writeRow = /** @type {(row: Record<string, any>) => Promise<unknown>} */ (ctx.writeRow);
+      await saveState({ ...where, state: loaded.state, seq, writeRow, contentRoot: ctx.contentRoot ?? ctx.repoRoot });
+      seq += 1;
+      await writeRow({ event: RESTORED_EVENT, block: ticket.block, file: ticket.file, seq, from_seq: loaded.seq });
+    }
     const rungUsed = rung.used;
-    let state = loaded.state;
+    let state = reopened ? null : loaded.state;
     if (state === null || state.status === 'complete') state = newFileState({ file: ticket.file, level, l3RungUsed: rungUsed });
     state.l3_rung_used = state.l3_rung_used || rungUsed;
     // B47: an autopilot extra round raises the file's cap; a file stopped at the old cap reopens
@@ -372,7 +572,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
       state.l3_rung_used = true; // the orchestrator ran the block's one L3 patch before this ticket
     }
     const fixed = state;
-    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq: loaded.seq, base, blockKindOf, workDir, factsExcerpt, extraRounds, peerDiffs });
+    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest, extraRounds, peerDiffs });
     // a round that could take the rung keeps the block lock until its state is saved
     if (mayTakeRung(fixed, kind, ctx.cfg, rungUsed)) return { outcome: await round() };
     return { round };
@@ -383,10 +583,10 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
 /**
  * Run the prepared round and save the file's state: the ticket's outcome.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, rulesDigest?: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, extraRounds = 0, peerDiffs }) {
+async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest = '', extraRounds = 0, peerDiffs }) {
   /** @type {Record<string, any> | null} */
   let engineOutcome = null;
   let approvalWritten = false;
@@ -429,18 +629,19 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     await runRound(
       state,
       {
-        repoRoot: ctx.repoRoot,
+        repoRoot: ctx.contentRoot ?? ctx.repoRoot,
         cfg: ctx.cfg,
         workDir,
         base,
         writeRow,
         factsExcerpt,
+        ...(rulesDigest !== '' ? { rulesDigest } : {}),
         extraRounds,
         ...(peerDiffs ? { peerDiffs } : {}),
         ...(jev ? { jev } : {}),
         ...(schemaHistory ? { schemaHistory } : {}),
         review: async () => {
-          engineOutcome = await reviewFile({ repoRoot: ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
+          engineOutcome = await reviewFile({ repoRoot: ctx.contentRoot ?? ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...(rulesDigest !== '' ? { rulesDigest } : {}), ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
           return engineOutcome;
         },
         spawn: async (opts) => {
@@ -466,7 +667,12 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
       state.pending_kind = kind;
     }
   }
-  await saveState({ ...where, state, seq, writeRow: /** @type {(row: Record<string, any>) => Promise<unknown>} */ (ctx.writeRow) });
+  // B72: a stop (any reason) records the content it reviewed — the ticket's — in the signed state,
+  // so `block reopen` and the worker know which content this stop saw (`stopContentHash`)
+  const stamped = /** @type {Record<string, any>} */ (state);
+  if (state.status === 'stopped') stamped.stop_content_hash = ticket.content_hash;
+  else delete stamped.stop_content_hash;
+  await saveState({ ...where, state, seq, writeRow: /** @type {(row: Record<string, any>) => Promise<unknown>} */ (ctx.writeRow), contentRoot: ctx.contentRoot ?? ctx.repoRoot });
 
   const eng = /** @type {Record<string, any> | null} */ (engineOutcome);
   const head = { ...loopFields(state, kind), engine: eng?.engine ?? 'adaptive', sessions: eng?.sessions ?? rechecks };
@@ -500,7 +706,7 @@ async function recordBlockBudget(ticket, ctx, { base, owned, ownedKinds }) {
     let changed = [];
     if (base !== null && owned.length > 0) {
       try {
-        changed = (await computeFileSet({ cwd: ctx.repoRoot, base })).all.filter((f) => ownsFile(owned, f, ownedKinds));
+        changed = (await computeFileSet({ cwd: ctx.contentRoot ?? ctx.repoRoot, base })).all.filter((f) => ownsFile(owned, f, ownedKinds));
       } catch {
         // no row on a git failure: a ticket-only forecast would be permanent (the row is written
         // once per block); the block's next keyed ticket retries

package/src/worker/loop.mjs

@@ -50,7 +50,7 @@ import { keyedLock } from '../util/locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { runRoot, setRunRoot } from '../util/tmp.mjs';
 import { openFindings } from '../review/gate-check.mjs';
-import { reviewTicket } from './engine.mjs';
+import { canonicalPath, contentRootFor, reviewTicket } from './engine.mjs';
 import { announceWorker, beatWorker, HEARTBEAT_MS, liveWorker, pendingTickets, readTicket, retractWorker, writeResult } from './queue.mjs';
 import { contentHash, DELETED_HASH, repoRootOf, WorkerError } from './ticket.mjs';
 
@@ -285,13 +285,15 @@ export async function createWorker(opts, deps = {}) {
    * One ticket through the engine hook with `tcfg` (the ticket's config snapshot): the unsigned result.
    * @param {import('./queue.mjs').Ticket} ticket @param {Record<string, any>} base
    * @param {Record<string, any>} tcfg
+   * @param {string} contentRoot - B62b: the tree the content was hashed in, and is reviewed in.
    * @returns {Promise<Record<string, any>>}
    */
-  async function reviewWith(ticket, base, tcfg) {
+  async function reviewWith(ticket, base, tcfg, contentRoot) {
     const timeoutS = Number.isInteger(tcfg?.review?.session_timeout_s) && tcfg.review.session_timeout_s > 0 ? tcfg.review.session_timeout_s : DEFAULT_SESSION_TIMEOUT_S;
     /** @type {import('./engine.mjs').ReviewContext} */
     const ctx = {
       repoRoot,
+      contentRoot,
       runId,
       runRootDir,
       cfg: tcfg,
@@ -316,6 +318,7 @@ export async function createWorker(opts, deps = {}) {
         approved: outcome.approved === true,
         engine: outcome.engine,
         ...(typeof outcome.reason === 'string' ? { reason: outcome.reason } : {}),
+        ...(typeof outcome.message === 'string' ? { message: outcome.message } : {}),
         ...(Array.isArray(outcome.findings) ? { findings: outcome.findings } : {}),
         ...packetSize(outcome),
         ...loopResult(outcome),
@@ -360,24 +363,42 @@ export async function createWorker(opts, deps = {}) {
    */
   async function reviewOne(id, ticket) {
     const base = { event: 'review.result', block: ticket.block, file: ticket.file, content_hash: ticket.content_hash };
-    /** @type {string | null} */
+    if (ticket.run !== runId) return { ...base, status: 'refused', reason: 'other-run', approved: false };
+    // B62b: the tree the content is hashed AND reviewed in — a block's worktree (from the run
+    // record, as review-file did), else the main tree. A tree that cannot be used (gone, malformed)
+    // or a block entry that cannot be read is `unavailable` with its code: never approval, and a
+    // later ticket for the same content runs again once it is fixed.
+    let contentRoot;
+    try {
+      contentRoot = await contentRootFor(runId, ticket.block, repoRoot);
+    } catch (err) {
+      // only the codes contentRootFor answers with; an I/O failure goes to runOne (`worker-error`)
+      if (!(err instanceof WorkerError)) throw err;
+      return { ...base, status: 'unavailable', reason: err.code, approved: false };
+    }
+    // a ticket was hashed in the tree it names (the main tree when it names none): never review it
+    // in another one — also a ticket with no tree for a block the record gives a worktree
+    const hashedIn = typeof ticket.tree === 'string' ? ticket.tree : repoRoot;
+    if (canonicalPath(hashedIn) !== canonicalPath(contentRoot)) return { ...base, status: 'unavailable', reason: 'worktree-mismatch', approved: false };
+    /** @type {string} */
     let current;
     try {
-      current = ticket.run === runId ? contentHash(repoRoot, ticket.file) : null;
+      current = contentHash(contentRoot, ticket.file);
     } catch (err) {
       // the path no longer passes the on-disk check, or the file cannot be read
-      return { ...base, status: 'refused', reason: err instanceof WorkerError ? err.code : 'unreadable', approved: false };
+      const reason = err instanceof WorkerError ? err.code : 'unreadable';
+      return { ...base, status: 'refused', reason, approved: false };
     }
-    if (ticket.run !== runId) return { ...base, status: 'refused', reason: 'other-run', approved: false };
     if (current === DELETED_HASH && ticket.content_hash !== DELETED_HASH) return { ...base, status: 'stale', reason: 'missing-file', approved: false };
-    if (current !== ticket.content_hash) return { ...base, status: 'stale', approved: false };
+    // B71: an answers ticket names why (its source moved); a review ticket keeps no reason
+    if (current !== ticket.content_hash) return { ...base, status: 'stale', ...(ticket.kind === 'answers' ? { reason: 'source-changed' } : {}), approved: false };
     let ticketCfg;
     try {
       ticketCfg = await configFor(id);
     } catch {
       return { ...base, status: 'unavailable', reason: 'config-snapshot', approved: false };
     }
-    return reviewWith(ticket, base, ticketCfg);
+    return reviewWith(ticket, base, ticketCfg, contentRoot);
   }
 
   /**