@codedology/code-forge 0.7.7 → 0.9.0

package/src/state/block.mjs

@@ -18,11 +18,11 @@ import path from 'node:path';
 import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
-import { externalReviewer } from './config-snapshot.mjs';
+import { blockEndHook, externalReviewer } from './config-snapshot.mjs';
 import { ownedKinds, pathKind } from './owned-kinds.mjs';
 import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
 import { StateError } from './paths.mjs';
-import { assertOwned, findOverlap, isExactEntry, ownsFile, scopeGate } from './registry.mjs';
+import { assertOwned, blocksOverlap, isExactEntry, ownsFile, scopeGate } from './registry.mjs';
 import { checkWorkerPin, readRun, saveRun, withRunLock, writeSigned } from './run.mjs';
 import { verifyRow, loadKey } from './signer.mjs';
 
@@ -261,34 +261,42 @@ function activeBlocks(record) {
  * is the owner's switch past the local per-file review, so no block may own it. These are the
  * spellings an owned entry may match it by: relative to the workspace and, for a workspace in a
  * subdirectory, relative to the repository top level (the close gate matches both, `ownsAt`).
- * Empty when the key is not set.
- * @param {Record<string, any>} record @returns {Promise<string[]>}
+ * Empty when the key is not set. B64b: `hooks.on_block_end` in the snapshot guards it the same way
+ * — the file names a command the orchestrator runs at every block end — and `why` names the key
+ * that guards it (`review.external.required` first, so its message is unchanged).
+ * @param {Record<string, any>} record @returns {Promise<{paths: string[], why: string}>}
  * @throws {StateError} `config-snapshot`, `git-failed`
  */
 async function guardedConfigPaths(record) {
-  if (externalReviewer(record) === null) return [];
+  const why = externalReviewer(record) !== null ? 'review.external.required is true' : blockEndHook(record) !== null ? 'hooks.on_block_end is set' : null;
+  if (why === null) return { paths: [], why: '' };
   const top = await repoTop(record.workspace);
   // the repo-top spelling `<prefix>/.code-forge.yml` may also match a different file of the same
   // name under the workspace (`<ws>/<prefix>/.code-forge.yml`): that over-match only refuses more,
   // never less, and is the one `ownsAt` gives the close gate
   const prefix = path.relative(top, realpathSync(record.workspace)).split(path.sep).join('/');
-  return prefix === '' ? [DEFAULT_CONFIG_FILENAME] : [DEFAULT_CONFIG_FILENAME, `${prefix}/${DEFAULT_CONFIG_FILENAME}`];
+  return { paths: prefix === '' ? [DEFAULT_CONFIG_FILENAME] : [DEFAULT_CONFIG_FILENAME, `${prefix}/${DEFAULT_CONFIG_FILENAME}`], why };
 }
 
 /**
  * B58: refuse an owned entry that owns one of `guarded` (B57's rule, `ownsFile`: the exact path,
  * a directory above it, or a glob that matches it).
- * @param {ReadonlyArray<string>} owned @param {import('./registry.mjs').OwnedKinds} kinds @param {ReadonlyArray<string>} guarded
+ * @param {ReadonlyArray<string>} owned @param {import('./registry.mjs').OwnedKinds} kinds @param {{paths: ReadonlyArray<string>, why: string}} guarded
  * @throws {StateError} `config-owned`
  */
 function refuseConfigOwner(owned, kinds, guarded) {
   for (const entry of owned) {
-    if (guarded.some((file) => ownsFile([entry], file, kinds))) {
-      throw new StateError('config-owned', `owned entry ${JSON.stringify(entry)} covers the project's ${DEFAULT_CONFIG_FILENAME}; no block may own it while review.external.required is true`);
+    if (guarded.paths.some((file) => ownsFile([entry], file, kinds))) {
+      throw new StateError('config-owned', `owned entry ${JSON.stringify(entry)} covers the project's ${DEFAULT_CONFIG_FILENAME}; no block may own it while ${guarded.why}`);
     }
   }
 }
 
+/**
+ * @typedef {{path: string, branch: string, base_sha: string}} TreeRecord - a block entry's `worktree` (B62a).
+ * @typedef {{worktree: TreeRecord, created: boolean, rollback: (() => Promise<string | null>) | null}} OpenTree - `rollback` resolves to a sentence naming leftovers, or null.
+ */
+
 /**
  * `block open` — refuses a second open of the same id and any owned set that overlaps another
  * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast and the
@@ -304,13 +312,29 @@ function refuseConfigOwner(owned, kinds, guarded) {
  * `dispatch` row — under the same lock, so a refused open writes neither. Its `answer` is the
  * requested lane and must equal `level` (else `bad-decision`, nothing written); the docs floor may
  * still raise the dispatched level, and the dispatch row then names the lane as `requested_level`.
+ * B60: `tests` (`block open --tests <paths…>`, the same path rules as owned entries, else
+ * `bad-tests`) is recorded as the entry's `test_files` and on the dispatch row; a gate argv item
+ * `{test_files}` expands to them (`gates/expand.mjs`). Left out, neither carries the key.
+ * B62a: `worktree` (given by `block open` under `proof.isolation: worktree`, `proof/worktree.mjs`;
+ * this module never imports it) plans the block's own worktree, or the reuse of the one an earlier
+ * entry of the same id recorded (`previous`); its `make()` makes or reuses it. Both are called
+ * under the lock before anything is recorded: the plan before the overlap check (which lets this
+ * block share owned paths with another open block on a different tree, `blocksOverlap`), `make()`
+ * after every other check. A refusal there writes nothing; if the rows or the save fail after
+ * `make()` created a tree, its `rollback()` removes it again, and the original error is thrown
+ * with a sentence added naming anything the rollback could not remove. The entry stores the tree's
+ * `{path, branch, base_sha}` as `worktree`; a tree it made is a signed `worktree.created
+ * {block, path, branch, base}` row just before `dispatch`. On a re-open the block's base is the
+ * tree's `base_sha`, and a `base` that resolves to another commit is refused (`worktree-base`).
  * @param {{
  *   runId: string, id: string, level: string, owned: string[], acceptance: unknown,
  *   attempt?: number, base?: string, lines?: number, brief?: {path: string, content: Buffer | string},
- *   kind?: string, cfg?: Record<string, any>, writeRow: WriteRow, now?: Date,
+ *   kind?: string, cfg?: Record<string, any>, writeRow: WriteRow, now?: Date, tests?: string[],
  *   decision?: {question: 'lane', answer: string, source: 'rules', facts: Record<string, unknown>}, decisionId?: string,
+ *   worktree?: (ctx: {baseSha: string, previous: TreeRecord | null}) => Promise<{path: string, make: () => Promise<OpenTree>}>,
  * }} opts
- * @returns {Promise<{block: Record<string, any>, pointer: string | null}>}
+ * @returns {Promise<{block: Record<string, any>, pointer: string | null, worktreeReused: boolean}>} `worktreeReused`:
+ *   the block took an earlier attempt's worktree as it was.
  */
 export async function openBlock(opts) {
   const { runId, id, level, attempt = 1, lines = null, writeRow, now = new Date() } = opts;
@@ -322,6 +346,7 @@ export async function openBlock(opts) {
   if (opts.decision && opts.decision.answer !== level) throw new StateError('bad-decision', `the decision answer ${opts.decision.answer} is not the requested level ${level}`);
   const owned = assertOwned(opts.owned);
   const acceptance = assertAcceptance(opts.acceptance);
+  const tests = opts.tests === undefined ? null : [...assertOwned(opts.tests, { label: 'test files', code: 'bad-tests' })];
   const kind = blockKind({ owned, declared: opts.kind });
   const dispatched = dispatchLevel({ lane: level, kind, cfg: opts.cfg });
   const pointer = opts.brief ? briefPointer(opts.brief.path, opts.brief.content) : null;
@@ -330,35 +355,70 @@ export async function openBlock(opts) {
   // not wait on it); under the lock the base is resolved again and must be the one stamped against
   const before = await readRun(runId);
   const { workspace } = before;
-  const stampedBase = await resolveCommit(opts.base ?? 'HEAD', workspace);
+  // B62a: a re-open of a block with a worktree keeps the tree's base — the block's base is the
+  // commit its tree started from, and a different --base is refused before anything is touched
+  /** @param {Record<string, any>} record @returns {{path: string, branch: string, base_sha: string} | null} */
+  const previousTree = (record) => (opts.worktree ? record.blocks[id]?.worktree ?? null : null);
+  const previous = previousTree(before);
+  const baseRef = previous ? previous.base_sha : opts.base ?? 'HEAD';
+  const stampedBase = await resolveCommit(baseRef, workspace);
+  if (previous && opts.base !== undefined && (await resolveCommit(opts.base, workspace)) !== previous.base_sha) {
+    throw new StateError('worktree-base', `block ${id}: --base ${opts.base} is not ${previous.base_sha.slice(0, 12)}, the base of the block's worktree ${previous.path}; a re-open keeps the worktree and its base — drop --base; nothing was recorded`);
+  }
   const treeOpen = await treeAtOpen(workspace, stampedBase);
   // B58: `review.external` cannot change mid-run, so the record read here decides
   const guarded = await guardedConfigPaths(before);
 
-  const block = await mutateRun(runId, null, writeRow, async (record) => {
-    if (record.blocks[id]?.status === 'open') throw new StateError('already-open', `block ${id} is already open`);
-    // B57: what each exact owned entry is on disk, under the lock (as `block claim`) — a regular
-    // file owns only itself, here and in every later check
-    const kinds = ownedKinds(record.workspace, owned);
-    refuseConfigOwner(owned, kinds, guarded);
-    for (const [otherId, other] of Object.entries(activeBlocks(record))) {
-      const pair = findOverlap(owned, other.owned_files, { kindsA: kinds, kindsB: other.owned_kinds });
-      if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
+  /** @type {OpenTree | null} */
+  let made = null;
+  try {
+    const { block, reused } = await mutateRun(runId, null, writeRow, async (record) => {
+      if (record.blocks[id]?.status === 'open') throw new StateError('already-open', `block ${id} is already open`);
+      // B57: what each exact owned entry is on disk, under the lock (as `block claim`) — a regular
+      // file owns only itself, here and in every later check
+      const kinds = ownedKinds(record.workspace, owned);
+      refuseConfigOwner(owned, kinds, guarded);
+      const prior = previousTree(record);
+      const baseSha = await resolveCommit(prior ? prior.base_sha : opts.base ?? 'HEAD', record.workspace);
+      if (baseSha !== stampedBase || record.workspace !== workspace) throw new StateError('base-moved', `the base moved while block ${id} was being opened; run block open again`);
+      // B62a: the tree is planned (read-only checks) before the overlap check, which needs its path
+      const planned = opts.worktree ? await opts.worktree({ baseSha, previous: prior }) : null;
+      const self = { owned_files: owned, owned_kinds: kinds, worktree: planned ? { path: planned.path } : null };
+      for (const [otherId, other] of Object.entries(activeBlocks(record))) {
+        const pair = blocksOverlap(self, other);
+        if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
+      }
+      // B62a: the worktree is made (or an earlier attempt's reused) last, once every other check
+      // passed; a tree made here is rolled back below if the rows or the save then fail
+      made = planned ? await planned.make() : null;
+      const tree = made;
+      const entry = { block: id, base_sha: baseSha, owned_files: [...owned], owned_kinds: { ...kinds }, level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open', tree_at_open: treeOpen, ...(tests ? { test_files: tests } : {}), ...(tree ? { worktree: tree.worktree } : {}) };
+      record.blocks[id] = entry;
+      const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
+      const created = tree?.created ? [{ event: 'worktree.created', block: id, path: tree.worktree.path, branch: tree.worktree.branch, base: tree.worktree.base_sha }] : [];
+      return {
+        result: { block: entry, reused: tree !== null && !tree.created },
+        rows: [
+          ...(opts.decision ? [{ ...opts.decision, event: 'decision', decision_id: opts.decisionId ?? randomUUID(), block: id }] : []),
+          ...created,
+          { event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines, ...(tests ? { test_files: tests } : {}) },
+        ],
+      };
+    });
+    return { block, pointer, worktreeReused: reused };
+  } catch (err) {
+    // B62a: nothing was recorded, so a tree this open made must not outlive it
+    if (made?.created && made.rollback) {
+      // the original error is thrown either way; what could not be removed is named in it (the
+      // rollback checks each git result and resolves, it does not throw)
+      const left = await made.rollback();
+      if (left !== null) {
+        if (!(err instanceof Error)) throw new Error(`${String(err).replace(/\.?$/, '.')} ${left}`, { cause: err });
+        err.message = `${err.message.replace(/\.?$/, '.')} ${left}`;
+      }
     }
-    const baseSha = await resolveCommit(opts.base ?? 'HEAD', record.workspace);
-    if (baseSha !== stampedBase || record.workspace !== workspace) throw new StateError('base-moved', `the base moved while block ${id} was being opened; run block open again`);
-    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], owned_kinds: { ...kinds }, level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open', tree_at_open: treeOpen };
-    record.blocks[id] = entry;
-    const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
-    return {
-      result: entry,
-      rows: [
-        ...(opts.decision ? [{ ...opts.decision, event: 'decision', decision_id: opts.decisionId ?? randomUUID(), block: id }] : []),
-        { event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines },
-      ],
-    };
-  });
-  return { block, pointer };
+    throw err;
+  }
 }
 
 /** @param {{runId: string, id: string, writeRow: WriteRow}} opts */
@@ -374,12 +434,15 @@ export async function attemptBlock({ runId, id, writeRow }) {
  * in between touched a file this block owns (that is a conflict ⇒ stop). Rename detection is OFF
  * (`--no-renames`): a rename lists both its old and its new path, so moving an owned file away
  * is a conflict too. Never silent. Owned means `ownsFile` (B57: a directory entry owns the files
- * below it).
+ * below it). B62a: refused for a block with its own worktree (`worktree-rebase`).
  * @param {{runId: string, id: string, head?: string, writeRow: WriteRow}} opts
  * @returns {Promise<{old_base: string, new_base: string}>}
  */
 export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
   return mutateRun(runId, id, writeRow, async (record, block) => {
+    // B62a: a worktree block's base is the commit its tree started from; moving it would leave the
+    // tree on its old base, so the rebase is refused
+    if (block.worktree) throw new StateError('worktree-rebase', `block ${id} has its own worktree ${block.worktree.path} on branch ${block.worktree.branch}; its base is the base of that tree, so block rebase does not apply — work on the branch in the tree instead`);
     const cwd = record.workspace;
     const newBase = await resolveCommit(head, cwd);
     const ancestor = await git(isAncestorArgv(block.base_sha, newBase), cwd, [0, 1]);
@@ -396,10 +459,11 @@ export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
 /**
  * `block claim` — assign one EXACT path (an orphan, or any unowned path) to `id`; refused for a
  * glob, and when another open block owns it — or anything it would own: the claimed path becomes an
- * owned entry, so it is checked with `findOverlap` (B57: an entry owns the paths below it too,
+ * owned entry, so it is checked with `blocksOverlap` (B57: an entry owns the paths below it too,
  * unless it is a regular file now — its kind is recorded in `owned_kinds` as at `block open`).
  * B58: with `review.external.required` set, a path that owns the project's config is refused
- * (`config-owned`), as at `block open`.
+ * (`config-owned`), as at `block open`. B62a: two blocks that each have their own worktree may
+ * own the same path (`blocksOverlap`).
  * @param {{runId: string, id: string, file: string, writeRow: WriteRow}} opts
  */
 export async function claimPath({ runId, id, file, writeRow }) {
@@ -410,7 +474,7 @@ export async function claimPath({ runId, id, file, writeRow }) {
     const kinds = { [file]: pathKind(record.workspace, file) };
     refuseConfigOwner([file], kinds, guarded);
     for (const [otherId, other] of Object.entries(activeBlocks(record))) {
-      const pair = otherId === id ? null : findOverlap([file], other.owned_files, { kindsA: kinds, kindsB: other.owned_kinds });
+      const pair = otherId === id ? null : blocksOverlap({ owned_files: [file], owned_kinds: kinds, worktree: block.worktree ?? null }, other);
       if (pair) throw new StateError('overlap', `${file} overlaps ${pair[1]} owned by open block ${otherId}`);
     }
     if (!block.owned_files.includes(file)) {

package/src/state/brief-status.mjs

@@ -0,0 +1,131 @@
+/**
+ * B64a (issue #13 item 6): the short status of one run — the data `code-forge status` prints, as
+ * text or as one JSON line. A pure function: it reads the run record and the ledger rows it is
+ * handed and nothing else (no file, no lock, no row written); the CLI (`src/cli/status.mjs`) reads
+ * them and renders the result. The object it returns has exactly the keys of the `--json` run
+ * object, in order: run_id, status, mode, spent_usd, unknown_usd_sessions, budget_usd, blocks,
+ * more, closed, stopped.
+ *
+ * Per run: its status (null when the record has none — `run status` then prints no status either;
+ * the text shows `-`), its mode (`brief` for a `run start --mode brief` run, else `plan`), the
+ * spend (`runSpend`, the same numbers `run status` prints as spent_usd and unknown_usd_sessions;
+ * both null when the caller could not read the ledger, `rows: null`) and the budget the caller
+ * read, then one entry per block that is neither closed nor stopped — closed and stopped blocks are
+ * only counted. A block entry holds:
+ *  - `state`: `open` on its first attempt, `attempt-<n>` after `block attempt` raised it to n; a
+ *    block whose record status is anything other than open shows that status as its state;
+ *  - `level`: the level it was dispatched at (the run record);
+ *  - `model`: `<provider>/<model>` (or the model alone) of the block's latest coder `session` /
+ *    `session.background` row of the run that names a model — the rows `src/session/spawn.mjs`
+ *    writes carry `role`, `provider`, `model`; a `ledger add coder` row (`manual`, no model) is
+ *    skipped — null when the ledger names none;
+ *  - `gate`: the block's LAST gate run — `gate.done` says pass (`all_ok: true`) or fail, a
+ *    `gate.red` with no `gate.done` after it is a fail; the name is the failing gate (the last
+ *    `gate.red` of that run), null on a pass; `{result: 'none', name: null}` when no gate ran;
+ *  - `findings`: the open review findings of the block, counted by the caller's `findingsOf`
+ *    (the CLI counts what the block close gate would refuse, `src/review/gate-check.mjs`).
+ * Blocks are in block id order (numeric-aware: B2 before B10).
+ */
+
+import { runSpend } from '../ledger/spend.mjs';
+
+/**
+ * @typedef {{id: string, state: string, level: string | null, model: string | null, gate: {result: 'pass' | 'fail' | 'none', name: string | null}, findings: number}} BlockStatus
+ * @typedef {{run_id: string, status: string | null, mode: 'plan' | 'brief', spent_usd: number | null, unknown_usd_sessions: number | null, budget_usd: number | null, blocks: BlockStatus[], more: number, closed: number, stopped: number}} RunStatus
+ */
+
+/** @param {string} a @param {string} b @returns {number} */
+const byBlockId = (a, b) => a.localeCompare(b, 'en', { numeric: true }) || (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The block's last gate run (see the module doc).
+ * @param {Array<Record<string, any>>} mine - the block's rows of the run, in ledger order.
+ * @returns {{result: 'pass' | 'fail' | 'none', name: string | null}}
+ */
+export function lastGate(mine) {
+  /** @type {string | null} */
+  let red = null;
+  /** @type {{result: 'pass' | 'fail' | 'none', name: string | null}} */
+  let last = { result: 'none', name: null };
+  for (const r of mine) {
+    if (r.event === 'gate.red') {
+      red = typeof r.gate === 'string' ? r.gate : null;
+      last = { result: 'fail', name: red };
+    } else if (r.event === 'gate.done') {
+      last = r.all_ok === true ? { result: 'pass', name: null } : { result: 'fail', name: red };
+      red = null;
+    }
+  }
+  return last;
+}
+
+/**
+ * The engine/model of the block's latest coder session row, or null.
+ * @param {Array<Record<string, any>>} mine @returns {string | null}
+ */
+export function coderModel(mine) {
+  for (let i = mine.length - 1; i >= 0; i -= 1) {
+    const r = mine[i];
+    if ((r.event === 'session' || r.event === 'session.background') && r.role === 'coder' && typeof r.model === 'string' && r.model.length > 0) {
+      return typeof r.provider === 'string' && r.provider.length > 0 ? `${r.provider}/${r.model}` : r.model;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{
+ *   record: Record<string, any>, rows: Array<Record<string, any>> | null, budget: number | null,
+ *   findingsOf: (blockId: string) => number,
+ * }} opts - `rows`: the project's ledger rows (other runs are filtered out here), null when the
+ *   ledger could not be read; `budget`: the workspace's `budget.usd` (null when unset), as
+ *   `run status` reads it.
+ * @returns {RunStatus}
+ */
+export function briefStatus({ record, rows, budget, findingsOf }) {
+  const runId = String(record.run_id);
+  /** @type {Map<string, Array<Record<string, any>>>} the run's rows, grouped by block once */
+  const byBlock = new Map();
+  for (const r of rows ?? []) {
+    if (r?.run !== runId || typeof r.block !== 'string') continue;
+    const list = byBlock.get(r.block);
+    if (list) list.push(r);
+    else byBlock.set(r.block, [r]);
+  }
+  const spend = rows == null ? null : runSpend(rows, runId);
+  const entries = record.blocks && typeof record.blocks === 'object' ? record.blocks : {};
+  const ids = Object.keys(entries).sort(byBlockId);
+  /** @type {BlockStatus[]} */
+  const blocks = [];
+  let closed = 0;
+  let stopped = 0;
+  for (const id of ids) {
+    const entry = entries[id];
+    const status = typeof entry?.status === 'string' ? entry.status : 'open';
+    if (status === 'closed') closed += 1;
+    else if (status === 'stopped') stopped += 1;
+    if (status === 'closed' || status === 'stopped') continue;
+    const mine = byBlock.get(id) ?? [];
+    const attempt = Number.isInteger(entry?.attempt) ? entry.attempt : 1;
+    blocks.push({
+      id,
+      state: status !== 'open' ? status : attempt > 1 ? `attempt-${attempt}` : 'open',
+      level: typeof entry?.level === 'string' ? entry.level : null,
+      model: coderModel(mine),
+      gate: lastGate(mine),
+      findings: findingsOf(id),
+    });
+  }
+  return {
+    run_id: runId,
+    status: typeof record.status === 'string' ? record.status : null,
+    mode: record.mode === 'brief' ? 'brief' : 'plan',
+    spent_usd: spend === null ? null : spend.usd,
+    unknown_usd_sessions: spend === null ? null : spend.unknown,
+    budget_usd: budget,
+    blocks,
+    more: 0,
+    closed,
+    stopped,
+  };
+}

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

@@ -276,8 +276,11 @@ export const FORBIDDEN = Object.freeze(
  * They are NOT part of `FORBIDDEN` (whose rendered count other blocks pin); `mergeForbidden()`
  * 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 block reopen` (B72) — restarting a stopped or lost file's review 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(
@@ -291,6 +294,15 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
       ],
       description: 'Waive a review finding (forge block waive) — human-only, run by the orchestrator after the human said so (§4.9)',
     },
+    {
+      id: 'code-forge-block-reopen-from-coder',
+      kind: 'anyPrefix',
+      prefixes: [
+        ['code-forge', 'block', 'reopen'],
+        ['forge', 'block', 'reopen'],
+      ],
+      description: 'Reopen the review of a stopped or lost file (forge block reopen) — human-only, run by the orchestrator after the human said so (B72)',
+    },
     {
       id: 'code-forge-autopilot-from-coder',
       kind: 'anyPrefix',
@@ -306,6 +318,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 +360,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}';