@codedology/code-forge 0.7.6 → 0.8.0

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);
   }
 
   /**

package/src/worker/queue.mjs

@@ -9,10 +9,13 @@
  *
  * The forbidden list (§8.4 ★) denies a coder any write under `reviews/` and to `queue/*.done`;
  * the MAC makes an edit visible anyway (T1/T2). Writes are atomic (temp file + rename).
+ *
+ * B62b: `<repo>` is always the MAIN tree's top level, where the worker runs — a block with its own
+ * worktree still queues there; only the reviewed content is read in the block's tree.
  */
 
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { loadKey, signRow, verifyRow } from '../state/signer.mjs';
 import { isAlive, readStartTime, UNKNOWN_START_TIME } from '../util/reaper.mjs';
@@ -54,26 +57,48 @@ function readJSON(file) {
 }
 
 /**
- * @typedef {{ticket: string, run: string, block: string, file: string, content_hash: string, enqueued_at: string}} Ticket
+ * @typedef {{ticket: string, run: string, block: string, file: string, content_hash: string, enqueued_at: string, tree?: string}} Ticket
+ *   `tree` (B62b): the block's worktree the content was hashed in. It is part of the ticket id,
+ *   and the worker only checks it against the tree it takes from the run record (a ticket whose
+ *   tree is not that one is `unavailable`, `worktree-mismatch`); it never reads content there.
  */
 
 /**
  * Enqueue `file` (already repo-root-relative) for review. Idempotent by content hash: the same
- * content returns the same ticket and never rewrites it.
- * @param {{repoRoot: string, run: string, block: string, file: string, now?: Date}} opts
- * @returns {{ticket: string, status: 'queued' | 'done', file: string, content_hash: string}}
+ * content returns the same ticket and never rewrites it. The queue is under `repoRoot`; the
+ * content is hashed under `tree` when given (B62b: the block's worktree, realpath'd here), else
+ * under `repoRoot`. The tree is part of the ticket id, so a main-tree ticket and a tree ticket for
+ * the same bytes differ, and the answer names the tree given here, never a stored value.
+ * @param {{repoRoot: string, run: string, block: string, file: string, tree?: string | null, now?: Date}} opts
+ * @returns {{ticket: string, status: 'queued' | 'done', file: string, content_hash: string, tree?: string}}
+ * @throws {WorkerError} `bad-path` for a relative `tree` or one that cannot be resolved.
  */
-export function enqueue({ repoRoot, run, block, file, now = new Date() }) {
+export function enqueue({ repoRoot, run, block, file, tree = null, now = new Date() }) {
   const rel = assertRowPath(file);
-  const content_hash = contentHash(repoRoot, rel);
-  const ticket = ticketId({ run, block, file: rel, content_hash });
+  const root = tree === null ? null : realTree(tree);
+  const content_hash = contentHash(root ?? repoRoot, rel);
+  const ticket = ticketId({ run, block, file: rel, content_hash, tree: root });
   const target = path.join(queueDir(repoRoot), `${ticket}.json`);
+  const named = root === null ? {} : { tree: root };
   if (!existsSync(target)) {
     /** @type {Ticket} */
-    const body = { ticket, run, block, file: rel, content_hash, enqueued_at: now.toISOString() };
+    const body = { ticket, run, block, file: rel, content_hash, enqueued_at: now.toISOString(), ...named };
     writeAtomic(target, `${JSON.stringify(body)}\n`);
   }
-  return { ticket, status: isDone(repoRoot, ticket) ? 'done' : 'queued', file: rel, content_hash };
+  return { ticket, status: isDone(repoRoot, ticket) ? 'done' : 'queued', file: rel, content_hash, ...named };
+}
+
+/**
+ * @param {string} tree @returns {string} `tree` realpath'd.
+ * @throws {WorkerError} `bad-path` when it is relative or cannot be resolved.
+ */
+function realTree(tree) {
+  if (!path.isAbsolute(tree)) throw new WorkerError('bad-path', `the content tree ${tree} is not an absolute path`);
+  try {
+    return realpathSync(tree);
+  } catch {
+    throw new WorkerError('bad-path', `the content tree ${tree} cannot be resolved`);
+  }
 }
 
 /** @param {string} repoRoot @param {string} ticket */
@@ -113,6 +138,7 @@ export function readTicket(repoRoot, id) {
   const t = readJSON(path.join(queueDir(repoRoot), `${assertTicketId(id)}.json`));
   if (!t || typeof t !== 'object') throw new WorkerError('bad-ticket', `ticket ${id} is not readable JSON`);
   assertRowPath(t.file);
+  if (t.tree !== undefined && (typeof t.tree !== 'string' || !path.isAbsolute(t.tree))) throw new WorkerError('bad-ticket', `ticket ${id} names a tree that is not an absolute path`);
   if (typeof t.run !== 'string' || typeof t.block !== 'string' || typeof t.content_hash !== 'string' || ticketId(t) !== id) {
     throw new WorkerError('bad-ticket', `ticket ${id} does not match its id`);
   }

package/src/worker/ticket.mjs

@@ -1,6 +1,7 @@
 /**
  * Review tickets (plan §4.8, V4; block B11): repo-root-relative paths, content hashes and ticket
- * ids. Pure functions plus the one `git rev-parse --show-toplevel` call.
+ * ids. Pure functions plus the `git rev-parse` calls that find the repository root (and, B62b,
+ * the main working tree of a linked worktree: `mainRootOf`).
  *
  * Path rule (V4): a ticket's `file` — and every `review.*` row the worker writes — is relative to
  * the REPOSITORY ROOT (realpath'd `git rev-parse --show-toplevel`), whatever directory the coder
@@ -8,8 +9,9 @@
  * `bad-path` before anything is written; so is a result outside the root or under `.git/` or
  * `.code-forge/`. A stored value is re-checked by `assertRowPath` (tickets are coder-writable).
  *
- * Ticket id = the first 24 hex chars of `sha256(run \0 block \0 file \0 content_hash)`: the same
- * content enqueued twice is the same ticket (idempotent), an edited file is a new one.
+ * Ticket id = the first 24 hex chars of `sha256(run \0 block \0 file \0 content_hash)`, plus
+ * `\0 tree` for content hashed in a block's worktree (B62b): the same content enqueued twice is
+ * the same ticket (idempotent), an edited file is a new one.
  */
 
 import { createHash } from 'node:crypto';
@@ -73,6 +75,39 @@ export async function repoRootOf(cwd) {
   return realpathSync(top);
 }
 
+/**
+ * B62b: the top level of the MAIN working tree of the repository containing `cwd`, realpath'd —
+ * `cwd`'s own top level ({@link repoRootOf}) unless `cwd` is inside a linked worktree (`git
+ * worktree add`), whose main tree is the first record `git worktree list` prints. The review queue
+ * and the worker live there, whichever tree the coder works in. A repository whose main entry is
+ * bare has no main working tree to hold them, and is refused.
+ * @param {string} cwd
+ * @returns {Promise<string>}
+ * @throws {WorkerError} `no-repo` (also for git older than 2.36), `bare-main`, `no-main-tree`
+ */
+export async function mainRootOf(cwd) {
+  const top = await repoRootOf(cwd);
+  const opts = { cwd, env: gitChildEnv(), timeoutMs: 10000 };
+  const dirs = await exec(['git', 'rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], opts);
+  if (dirs.result !== 'ok') throw new WorkerError('no-repo', `not inside a git repository, or git is older than 2.36 (code-forge needs git >= 2.36): ${dirs.stderr.trim()}`);
+  const [gitDir, commonDir] = dirs.stdout.split('\n');
+  if (!gitDir || !commonDir) throw new WorkerError('no-repo', 'git rev-parse printed no git directory');
+  if (realOrSelf(gitDir) === realOrSelf(commonDir)) return top;
+  const list = await exec(['git', 'worktree', 'list', '--porcelain', '-z'], opts);
+  if (list.result !== 'ok') throw new WorkerError('no-repo', `the main working tree of the repository cannot be listed (code-forge needs git >= 2.36): ${list.stderr.trim()}`);
+  // records end with an empty field; the first record is the main tree's
+  const first = list.stdout.split('\0\0')[0].split('\0');
+  const where = first.find((line) => line.startsWith('worktree '));
+  if (!where) throw new WorkerError('no-repo', 'git worktree list printed no main working tree');
+  if (first.includes('bare')) throw new WorkerError('bare-main', `the repository's main entry ${where.slice('worktree '.length)} is bare: it has no main working tree for the review queue`);
+  const main = where.slice('worktree '.length);
+  try {
+    return realpathSync(main);
+  } catch {
+    throw new WorkerError('no-main-tree', `the repository's main working tree ${main} does not exist (moved or removed): the review queue lives there`);
+  }
+}
+
 /**
  * Refuse a stored row path that is not a plain repo-root-relative POSIX path (V4).
  * @param {unknown} value
@@ -187,9 +222,14 @@ export function readRegularFileNoFollow(repoRoot, file) {
 }
 
 /**
- * @param {{run: string, block: string, file: string, content_hash: string}} t
+ * B62b: a ticket that names the tree its content was hashed in (`tree`, a block's worktree) has
+ * the tree in its identity too — `sha256(run \0 block \0 file \0 content_hash \0 tree)` — so a
+ * main-tree ticket and a tree ticket for the same bytes are two tickets. Without a tree the id is
+ * the one from before B62b.
+ * @param {{run: string, block: string, file: string, content_hash: string, tree?: string | null}} t
  * @returns {string} the ticket id.
  */
-export function ticketId({ run, block, file, content_hash }) {
-  return createHash('sha256').update([run, block, file, content_hash].join('\0')).digest('hex').slice(0, 24);
+export function ticketId({ run, block, file, content_hash, tree = null }) {
+  const parts = tree === null ? [run, block, file, content_hash] : [run, block, file, content_hash, tree];
+  return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 24);
 }