@codedology/code-forge 0.7.7 → 0.8.0

package/src/state/config-snapshot.mjs

@@ -34,6 +34,16 @@ export const IMMUTABLE_KEYS = Object.freeze({
   // B58: the owner's switch past the local per-file review is set before the run starts or not at
   // all, so nobody turns it on (or off) mid-run
   'review.external': 'the outside reviewer is fixed by the owner before the run starts',
+  // B62a: every block of the run is isolated the same way — only two blocks that each have their
+  // own worktree may share owned paths — so neither key changes mid-run
+  'proof.isolation': 'every block of the run is isolated the same way',
+  'proof.worktree': 'the worktrees and branches of the open blocks were made with it',
+  // B63b: it tightens `block close` (the coder's green test run), so it is authority like
+  // `review.external`; the rest of `context` stays live
+  'context.require_coder_tests': 'whether close needs the coder\'s green test run is fixed by the owner before the run starts',
+  // B64b: the block-end hook runs a command on the owner's machine at every block end, so only
+  // the owner sets it, before the run starts
+  'hooks.on_block_end': 'it runs a command on the owner\'s machine at every block end; fixed by the owner before the run starts',
 });
 
 /** @param {unknown} v @returns {boolean} what `JSON.stringify` drops from an object. */
@@ -184,3 +194,44 @@ export function externalReviewer(record) {
   const name = typeof external.name === 'string' ? external.name.trim() : '';
   return name === '' ? null : name; // trimmed: no row ever carries padding
 }
+
+/**
+ * B63b: whether `block close` needs the coder's `TESTS <command> exit=0` line — true only when the
+ * snapshot in force sets `context.require_coder_tests: true` (false for the key absent or false,
+ * or a record from before snapshots). The key is immutable ({@link IMMUTABLE_KEYS}), so this is
+ * the value `run start` stored; the live config is never read.
+ * @param {Record<string, any>} record
+ * @returns {boolean}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function requireCoderTests(record) {
+  const context = configInForce(record)?.context;
+  return isMapping(context) && context.require_coder_tests === true;
+}
+
+/** The default `hooks.on_block_end.timeout_s`. */
+export const HOOK_TIMEOUT_DEFAULT_S = 60;
+/** The schema's bounds of `hooks.on_block_end.timeout_s`. */
+export const HOOK_TIMEOUT_MIN_S = 1;
+export const HOOK_TIMEOUT_MAX_S = 600;
+
+/**
+ * `hooks.on_block_end` of the run-start config snapshot (never the live config), or null when it
+ * is absent or malformed (the schema refuses a malformed one at `run start`).
+ * @param {Record<string, any>} record
+ * @returns {{argv: string[], timeoutS: number} | null}
+ */
+export function blockEndHook(record) {
+  let hook;
+  try {
+    hook = configInForce(record)?.hooks?.on_block_end;
+  } catch {
+    return null;
+  }
+  if (hook === null || typeof hook !== 'object') return null;
+  const { argv, timeout_s: timeout } = hook;
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) return null;
+  const timeoutS = timeout === undefined ? HOOK_TIMEOUT_DEFAULT_S : timeout;
+  if (!Number.isInteger(timeoutS) || timeoutS < HOOK_TIMEOUT_MIN_S || timeoutS > HOOK_TIMEOUT_MAX_S) return null;
+  return { argv: [...argv], timeoutS };
+}

package/src/state/registry.mjs

@@ -34,6 +34,10 @@
  * vs `src/**` and vs `src/feature/*.swift` overlap, vs `src/*.mjs` and `src/featureX/*` do not);
  * a `file` entry against a glob overlaps only when the glob matches it (`src/README` vs
  * `src/**\/*.mjs` does not).
+ *
+ * B62a — between two OPEN BLOCKS the rule is `blocksOverlap`: two blocks that each have their own
+ * worktree (`proof.isolation: worktree`) may own the same path; any pair with a shared-tree block
+ * in it is checked with `findOverlap` exactly as above.
  */
 
 import { StateError } from './paths.mjs';
@@ -99,21 +103,24 @@ export function expandBraces(pattern) {
 
 /**
  * @param {unknown} owned
+ * @param {{label?: string, code?: string}} [as] - B60: `block open --tests` checks its test files by
+ *   the same rules, named `test files` with the code `bad-tests`.
  * @returns {string[]}
  * An EXACT entry (no `*`, `?` or `{`) may contain `[ ] ( ) ! + @ }` — real routes such as
  * `pages/[id].vue`, `app/(group)/page.tsx`, `@types/x.d.ts` — and is matched literally by
  * string equality. A GLOB entry may not: there those characters would be character-class or
  * extglob syntax this matcher does not implement, so it is refused with that reason rather than
  * silently read one way by us and another way by git or a shell.
- * @throws {StateError} `bad-owned` — empty, absolute, `.`/`..`/empty segments (checked on every
+ * @throws {StateError} with code `as.code` (default `bad-owned`) and a message that starts with
+ *   `as.label` (default `owned files`) — empty, absolute, `.`/`..`/empty segments (checked on every
  *   brace alternative), backslashes, unbalanced braces, or unsupported glob syntax in a glob.
  */
-export function assertOwned(owned) {
-  if (!Array.isArray(owned) || owned.length === 0) throw new StateError('bad-owned', 'owned files: at least one path is required');
+export function assertOwned(owned, { label = 'owned files', code = 'bad-owned' } = {}) {
+  if (!Array.isArray(owned) || owned.length === 0) throw new StateError(code, `${label}: at least one path is required`);
   for (const entry of owned) {
     /** @param {string} why */
     const refuse = (why) => {
-      throw new StateError('bad-owned', `owned files: invalid path ${JSON.stringify(entry)}: ${why}`);
+      throw new StateError(code, `${label}: invalid path ${JSON.stringify(entry)}: ${why}`);
     };
     if (typeof entry !== 'string' || entry.length === 0) refuse('must be a non-empty string');
     if (entry.includes('\\')) refuse('backslashes are not allowed (POSIX paths only)');
@@ -240,6 +247,30 @@ export function findOverlap(ownedA, ownedB, { kindsA, kindsB } = {}) {
   return null;
 }
 
+/**
+ * One open block as the overlap rule sees it: its owned entries, their kinds (B57) and its own
+ * worktree, if any (B62a). `worktree` is the run record's `{path, branch, base_sha}` (or, for a
+ * block being opened, `{path}` of the tree it is about to get); `null` or absent means it works in
+ * the shared tree (export or lock isolation). Every caller passes this one shape.
+ * @typedef {{owned_files: ReadonlyArray<string>, owned_kinds?: OwnedKinds, worktree?: {path: string} | null}} OverlapBlock
+ */
+
+/**
+ * B62a: the owned-files overlap rule between two open blocks. Two blocks that EACH have their own
+ * worktree, at different paths, may own the same path — each edits its own copy on its own branch,
+ * and nothing is merged by code-forge — so the pair never overlaps. Two blocks on the SAME tree
+ * path edit one tree, and a block without a worktree (export or lock isolation) edits the shared
+ * tree: both are checked exactly as before B62a ({@link findOverlap}, B57's kinds included).
+ * @param {OverlapBlock} a @param {OverlapBlock} b
+ * @returns {[string, string] | null} the first overlapping pair (a's entry, b's entry), or null.
+ */
+export function blocksOverlap(a, b) {
+  const treeA = a.worktree ?? null;
+  const treeB = b.worktree ?? null;
+  if (treeA !== null && treeB !== null && treeA.path !== treeB.path) return null;
+  return findOverlap(a.owned_files, b.owned_files, { kindsA: a.owned_kinds, kindsB: b.owned_kinds });
+}
+
 /**
  * Does `owned` own repo-relative `file`? A directory-like exact entry owns its path and every path
  * below it, a `file` one (per `kinds`) only itself (B57); a glob entry owns what it matches. A

package/src/state/run.mjs

@@ -217,7 +217,9 @@ export async function startRun(opts) {
  * Fixed keys ({@link IMMUTABLE_KEYS}): every one that changed is refused at once
  * (`immutable-key`, nothing written). A record from before snapshots (no `config`) is checked
  * against what it does store: `engine` and the ledger slug (`effectiveSlug`, computed by the
- * caller the same way `run start` did), and B58's `review.external.required` must not turn true;
+ * caller the same way `run start` did), B58's `review.external.required` must not turn true,
+ * B62a's `proof.isolation` must not turn to `worktree`, and B63b's `context.require_coder_tests`
+ * must not turn true;
  * it then gets its first snapshot, `changed_keys: null`, `old_hash: null`.
  *
  * No change (same hash) ⇒ nothing written, no row. Otherwise the record is saved FIRST (it is the
@@ -260,6 +262,13 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
       // B58: a run started without the key has none to keep — turning it on now is a change; an
       // entry that leaves it off (`required` false or absent, as the schema default) is not
       if (config.review?.external?.required === true) frozen.push('review.external');
+      // B62a: a run started without a snapshot was isolated by export (or lock); turning worktree
+      // isolation on now is a change
+      if (config.proof?.isolation === 'worktree') frozen.push('proof.isolation');
+      // B63b: likewise, a run started without a snapshot never required the coder's tests
+      if (config.context?.require_coder_tests === true) frozen.push('context.require_coder_tests');
+      // B64b: and never had a block-end hook
+      if (config.hooks?.on_block_end !== undefined) frozen.push('hooks.on_block_end');
     }
     if (frozen.length > 0) {
       const why = frozen.map((key) => `${key} cannot change mid-run (${IMMUTABLE_KEYS[/** @type {keyof typeof IMMUTABLE_KEYS} */ (key)]})`);

package/src/util/breadcrumbs.mjs

@@ -27,6 +27,7 @@ import path from 'node:path';
 export const SUBCOMMANDS = Object.freeze({
   autopilot: ['start', 'status', 'stop'],
   block: ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'],
+  context: ['pack'],
   gates: ['detect', 'run', 'secret-scan', 'safe-edit', 'scope', 'acceptance', 'transcript-grep'],
   jev: ['ask'],
   keys: ['list', 'set', 'test', 'remove'],

package/src/util/forbidden.mjs

@@ -277,7 +277,9 @@ export const FORBIDDEN = Object.freeze(
  * always appends them, so every list built for a coder carries them.
  *  - `code-forge block waive` — waiving a review finding is human-only;
  *  - `code-forge autopilot` (any subcommand, B45) — the owner's grant to a delegate;
- *  - `--no-require-reviews` — the human's way out of `block close`'s per-file review check.
+ *  - `--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.
  * @type {ReadonlyArray<ForbiddenEntry>}
  */
 export const CODER_ONLY_FORBIDDEN = Object.freeze(
@@ -306,6 +308,12 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
       tokens: ['--no-require-reviews'],
       description: 'Close a block without the per-file review check (--no-require-reviews) — human-only',
     },
+    {
+      id: 'code-forge-remove-worktree',
+      kind: 'contains',
+      tokens: ['--remove-worktree'],
+      description: "Remove a block's worktree at close (block close --remove-worktree, B62a) — the orchestrator only",
+    },
   ].map(freezeEntry),
 );
 
@@ -342,6 +350,33 @@ export function mergeForbidden(extraTokens = []) {
   return [...FORBIDDEN, ...CODER_ONLY_FORBIDDEN, ...extras];
 }
 
+/** B64b: the id of the entry {@link hookForbidden} builds. */
+export const HOOK_FORBIDDEN_ID = 'code-forge-on-block-end-hook';
+
+/**
+ * B64b: the owner's `hooks.on_block_end` command as a coder-forbidden `prefix` entry — the hook
+ * runs only from the orchestrator's block-end verbs, never for a coder. The tokens are TRIMMED:
+ * the command name of `argv[0]` (its basename, as every reading normalizes it), plus `argv[1]`
+ * when there is one that is not blank (clause 3, "if any"). `argv[1]` stays ONE token even with
+ * inner whitespace — a literal match, as ruled. No entry (`[]`, so a list built with it is
+ * unchanged) when there is no hook (`argv` absent, empty, or not all non-empty strings), or when
+ * `argv[0]` is blank, names a directory (`/`, `dir/`), or is `.` or `..`. Appended by the caller
+ * after the static entries; it never replaces or weakens one.
+ * @param {unknown} argv
+ * @returns {ForbiddenEntry[]}
+ */
+export function hookForbidden(argv) {
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) return [];
+  const first = argv[0].trim();
+  // a command name that is blank, a directory (`/`, `dir/`), `.` or `..` matches nothing a coder runs
+  if (first.length === 0 || /[/\\]$/.test(first)) return [];
+  const name = commandName(first).trim();
+  if (name.length === 0 || name === '.' || name === '..') return [];
+  const arg = argv.length > 1 ? argv[1].trim() : '';
+  const tokens = arg.length > 0 ? [name, arg] : [name];
+  return [freezeEntry({ id: HOOK_FORBIDDEN_ID, kind: 'prefix', tokens, description: 'Run the configured on_block_end hook (hooks.on_block_end) — it runs only at a block end, from the orchestrator\'s verbs' })];
+}
+
 // ── Normalization ────────────────────────────────────────────────────────────
 
 /** git global options that take the NEXT argv token as their value (when not written `--opt=value`). */

package/src/util/gate-token.mjs

@@ -0,0 +1,8 @@
+/**
+ * The one argv item a gate uses for the block's related tests. It lives in `util` because two
+ * layers need the same value: `gates/expand.mjs` expands it, and `config/validate.mjs` refuses it as
+ * a gate's command (`config` may not import `gates`).
+ */
+
+/** A gate argv item that is EXACTLY this string expands to the block's test files. */
+export const TEST_FILES_TOKEN = '{test_files}';

package/src/worker/engine.mjs

@@ -40,29 +40,59 @@
  * 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.
  */
 
-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 { peerDiffReader } from '../review/moved.mjs';
 import { computeFileSet, ownsFile } from '../gates/scope.mjs';
 import { extraRoundsFor, newFileState, reopenForExtraRound, runRound } from '../review/fixloop.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 { assertTicketId, 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 {Record<string, any>} cfg - the project config.
@@ -110,14 +140,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 +161,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 +324,43 @@ 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 };
+  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 });
   }
@@ -329,10 +468,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>}} */
@@ -372,7 +511,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: loaded.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 +522,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 +568,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) => {
@@ -500,7 +640,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,
@@ -360,15 +362,32 @@ 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 };
     let ticketCfg;
@@ -377,7 +396,7 @@ export async function createWorker(opts, deps = {}) {
     } catch {
       return { ...base, status: 'unavailable', reason: 'config-snapshot', approved: false };
     }
-    return reviewWith(ticket, base, ticketCfg);
+    return reviewWith(ticket, base, ticketCfg, contentRoot);
   }
 
   /**