@codedology/code-forge 0.7.6 → 0.8.0

package/src/state/block-end.mjs

@@ -0,0 +1,290 @@
+/**
+ * B64b (issue #13): the block-end signal — a done file and the owner's `hooks.on_block_end` hook.
+ *
+ * A block ends where `src/state/block.mjs` sets its status to `closed` or `stopped`: `closeBlock`
+ * closing it, `closeBlock` stopping it (a pinned worker event or `ledger.tamper`), and `stopBlock`
+ * (`block stop`). After each end — its ledger rows written and the run lock released — the CLI
+ * (`src/cli/block.mjs`):
+ *
+ * 1. writes `<runs>/<run>/blocks/<id>.done.json` ({@link doneFilePath}) atomically (a temp file in
+ *    the same directory, then a rename; a second end overwrites it) with {@link doneFileContent}:
+ *    the block, the run, its status, the end's event and reason, the HEAD commit of the block's
+ *    tree, the block's own spend and its open findings, and the time. Never transcript text, diff
+ *    text or secrets. A failed write changes nothing but one stderr warning line.
+ * 2. runs `hooks.on_block_end` (`blockEndHook` in `config-snapshot.mjs`, from the run-start
+ *    config snapshot only — the key is immutable) once, outside the run lock: argv only (no
+ *    shell), cwd the repository top, stdin closed, stdout and stderr discarded, the parent env plus
+ *    `CODE_FORGE_RUN`, `CODE_FORGE_BLOCK`, `CODE_FORGE_BLOCK_STATUS` and `CODE_FORGE_DONE_FILE`;
+ *    its process group is killed at `timeout_s`. One signed `hook.ran` row records it (under the run lock). A hook
+ *    that fails, is missing, times out or crashes changes nothing but one stderr warning line.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runSpend } from '../ledger/spend.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+import { exec } from '../util/exec.mjs';
+import { assertRunId, runsDir } from './paths.mjs';
+import { withRunLock, writeSigned } from './run.mjs';
+
+// B64b: the hook's config reader lives next to `externalReviewer` (read by `state/block.mjs` too)
+export { HOOK_TIMEOUT_DEFAULT_S, HOOK_TIMEOUT_MAX_S, HOOK_TIMEOUT_MIN_S, blockEndHook } from './config-snapshot.mjs';
+
+/**
+ * The block's done file: `<runs>/<run>/blocks/<id>.done.json` (the run's own directory under the
+ * runs dir, next to the run record — never in the source tree).
+ * @param {string} runId @param {string} id
+ * @returns {string} an absolute path
+ */
+export function doneFilePath(runId, id) {
+  return path.resolve(runsDir(), assertRunId(runId), 'blocks', `${safeId(id)}.done.json`);
+}
+
+/** @param {string} id @returns {string} the id, refused when it could leave the blocks dir. */
+function safeId(id) {
+  if (typeof id !== 'string' || id.length === 0 || id.includes('/') || id.includes('\\') || id === '.' || id === '..' || id.includes('\0')) {
+    throw new TypeError(`block id ${JSON.stringify(id)} cannot name a done file`);
+  }
+  return id;
+}
+
+/**
+ * The done file's content, keys in this order. Pure.
+ * @param {{
+ *   block: string, runId: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
+ *   commit: string | null, spend: {usd: number, unknown: number} | null, findings: number | null, at: Date,
+ * }} facts
+ * @returns {{block: string, run_id: string, status: string, event: string, reason: string | null, commit: string | null,
+ *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string}}
+ */
+export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at }) {
+  return {
+    block,
+    run_id: runId,
+    status,
+    event,
+    reason: typeof reason === 'string' ? reason : null,
+    commit: typeof commit === 'string' && commit.length > 0 ? commit : null,
+    // a non-finite spend or a non-integer count is unknown (null) — the keys are never dropped
+    spent_usd: spend && Number.isFinite(spend.usd) ? spend.usd : null,
+    unknown_usd_sessions: spend && Number.isInteger(spend.unknown) ? spend.unknown : null,
+    findings: Number.isInteger(findings) ? findings : null,
+    at: at.toISOString(),
+  };
+}
+
+/** @param {string} cwd @returns {Promise<string | null>} HEAD of `cwd`'s repository, or null. */
+async function headCommit(cwd) {
+  try {
+    const env = {};
+    for (const [name, value] of Object.entries(process.env)) if (!name.startsWith('GIT_')) env[name] = value;
+    const res = await exec(['git', 'rev-parse', '--verify', 'HEAD'], {
+      cwd,
+      env: { ...env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null', GIT_TERMINAL_PROMPT: '0' },
+      timeoutMs: 10000,
+    });
+    const sha = res.stdout.trim();
+    return res.result === 'ok' && /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the block's done file after an end (its ledger rows are already written). Never throws: a
+ * failure prints `warning: done file not written: <reason>` on stderr and returns null.
+ * @param {{
+ *   record: Record<string, any>, id: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
+ *   openFindings: (rows: Record<string, any>[]) => Promise<number>, err: (s: string) => unknown, now?: Date,
+ * }} opts - `record` is the run record read before the end (its `workspace` and the block's
+ *   `worktree` do not change at an end); `openFindings` counts the block's open findings exactly
+ *   as `code-forge status` does.
+ * @returns {Promise<string | null>} the done file's absolute path, or null when it was not written.
+ */
+export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date() }) {
+  const runId = String(record?.run_id);
+  try {
+    const file = doneFilePath(runId, id);
+    /** @type {Record<string, any>[] | null} */
+    let rows = null;
+    try {
+      rows = await readAllRows(record.project);
+    } catch {
+      rows = null;
+    }
+    const spend = rows === null ? null : runSpend(rows.filter((r) => r?.block === id), runId);
+    // like the spend: unknown (null) when the rows cannot be read or the count fails — never a 0
+    /** @type {number | null} */
+    let findings = null;
+    if (rows !== null) {
+      try {
+        const n = await openFindings(rows);
+        findings = Number.isInteger(n) && n >= 0 ? n : null;
+      } catch {
+        findings = null;
+      }
+    }
+    const tree = record.blocks?.[id]?.worktree?.path;
+    const commit = await headCommit(typeof tree === 'string' && tree.length > 0 ? tree : record.workspace);
+    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now });
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+      await writeFile(tmp, `${JSON.stringify(content)}\n`, { mode: 0o600 });
+      await rename(tmp, file);
+    } catch (thrown) {
+      await rm(tmp, { force: true }).catch(() => {});
+      throw thrown;
+    }
+    return file;
+  } catch (thrown) {
+    err(`warning: done file not written: ${reasonOf(thrown)}\n`);
+    return null;
+  }
+}
+
+/** @param {unknown} thrown @returns {string} a one-line reason (an error code or message). */
+function reasonOf(thrown) {
+  const any = /** @type {any} */ (thrown);
+  const text = typeof any?.code === 'string' ? any.code : typeof any?.message === 'string' ? any.message : String(thrown);
+  return text.split('\n')[0];
+}
+
+/**
+ * @typedef {{exit: number | null, signal: string | null, timedOut: boolean, notFound: boolean, error: string | null}} SpawnResult
+ */
+
+/** @param {unknown} thrown @returns {string} the error's code (`EACCES`, …), else `UNKNOWN` — never its message. */
+function errorCode(thrown) {
+  const code = /** @type {any} */ (thrown)?.code;
+  return typeof code === 'string' && /^[A-Z0-9_]{1,32}$/.test(code) ? code : 'UNKNOWN';
+}
+
+/**
+ * The warning's tail for a hook that did not exit 0 (ruling round 2 (b)), or null for a clean exit:
+ * `exit N`, `timed out`, `not found`, `signal <NAME>` or `failed to start (<code>)`.
+ * @param {SpawnResult} ran @returns {string | null}
+ */
+export function hookWarning(ran) {
+  if (ran.timedOut) return 'timed out';
+  if (ran.notFound) return 'not found';
+  if (ran.error !== null) return `failed to start (${ran.error})`;
+  if (typeof ran.exit === 'number') return ran.exit === 0 ? null : `exit ${ran.exit}`;
+  if (typeof ran.signal === 'string') return `signal ${ran.signal}`;
+  return 'failed to start (UNKNOWN)';
+}
+
+/**
+ * Spawn the hook: no shell, stdin closed, stdout and stderr discarded, its own process group,
+ * killed (the whole group) at the timeout.
+ * @param {string[]} argv @param {{cwd: string, env: NodeJS.ProcessEnv, timeoutMs: number}} opts
+ * `notFound` is an ENOENT for `argv[0]` itself; every other spawn error (a missing cwd included —
+ * Node names `argv[0]` in that ENOENT too, so the cwd is checked first) is `error`, its code.
+ * @returns {Promise<SpawnResult>}
+ */
+async function spawnHook(argv, { cwd, env, timeoutMs }) {
+  try {
+    if (!(await stat(cwd)).isDirectory()) return { exit: null, signal: null, timedOut: false, notFound: false, error: 'ENOTDIR' };
+  } catch (thrown) {
+    return { exit: null, signal: null, timedOut: false, notFound: false, error: errorCode(thrown) };
+  }
+  return new Promise((resolve) => {
+    let timedOut = false;
+    let settled = false;
+    /** @type {NodeJS.Timeout | undefined} */
+    let timer;
+    const done = (/** @type {SpawnResult} */ r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const failed = (/** @type {unknown} */ thrown) => {
+      const any = /** @type {any} */ (thrown);
+      const notFound = any?.code === 'ENOENT' && (any?.path === undefined || any.path === argv[0]);
+      done({ exit: null, signal: null, timedOut: false, notFound, error: notFound ? null : errorCode(thrown) });
+    };
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), { cwd, env, shell: false, detached: true, stdio: ['ignore', 'ignore', 'ignore'] });
+    } catch (thrown) {
+      failed(thrown);
+      return;
+    }
+    const pid = child.pid;
+    child.on('error', failed);
+    child.on('close', (code, signal) => done({ exit: code, signal: signal ?? null, timedOut, notFound: false, error: null }));
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        if (typeof pid === 'number' && pid > 1) process.kill(-pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // already gone
+        }
+      }
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Run `hooks.on_block_end` once for an end, outside the run lock, then write one signed `hook.ran`
+ * row under it (also when the hook failed, timed out or was not found). Never throws, never prints
+ * on stdout; a hook that did not exit 0 prints one `warning: on_block_end hook <tail>` line on
+ * stderr ({@link hookWarning}). `doneFile` is the empty string when the done file was not written.
+ * @param {{
+ *   hook: {argv: string[], timeoutS: number}, runId: string, id: string, status: string, doneFile: string,
+ *   repoTop: string, writeRow: (row: Record<string, any>) => Promise<unknown>, err: (s: string) => unknown,
+ * }} opts
+ * @returns {Promise<Record<string, any> | null>} the row written (unsigned fields), or null when none was.
+ */
+export async function runBlockEndHook({ hook, runId, id, status, doneFile, repoTop, writeRow, err }) {
+  const env = {
+    ...process.env,
+    CODE_FORGE_RUN: runId,
+    CODE_FORGE_BLOCK: id,
+    CODE_FORGE_BLOCK_STATUS: status,
+    CODE_FORGE_DONE_FILE: doneFile,
+  };
+  const started = process.hrtime.bigint();
+  /** @type {SpawnResult} */
+  let ran;
+  // "failed to start" covers the spawn only; a later failure gets neutral wording below
+  try {
+    ran = await spawnHook(hook.argv, { cwd: repoTop, env, timeoutMs: hook.timeoutS * 1000 });
+  } catch (thrown) {
+    ran = { exit: null, signal: null, timedOut: false, notFound: false, error: errorCode(thrown) };
+  }
+  try {
+    const durationMs = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+    const warning = hookWarning(ran);
+    if (warning !== null) err(`warning: on_block_end hook ${warning}\n`);
+    const row = {
+      event: 'hook.ran',
+      block: id,
+      hook: 'on_block_end',
+      argv0: path.basename(hook.argv[0]),
+      exit: ran.exit,
+      signal: ran.signal,
+      timed_out: ran.timedOut,
+      duration_ms: durationMs,
+    };
+    try {
+      // clause 2: the hook.ran row is appended UNDER the run lock (writeSigned alone takes no lock)
+      await withRunLock(runId, () => writeSigned(runId, writeRow, row));
+    } catch (thrown) {
+      // an error code only, never raw message text
+      err(`warning: on_block_end hook row not written (${errorCode(thrown)})\n`);
+      return null;
+    }
+    return row;
+  } catch (thrown) {
+    err(`warning: on_block_end hook not recorded (${errorCode(thrown)})\n`);
+    return null;
+  }
+}

package/src/state/block.mjs

@@ -11,18 +11,18 @@
  * B12) — this module never imports them (C17).
  */
 
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { createReadStream, existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 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
@@ -299,12 +307,34 @@ function refuseConfigOwner(owned, kinds, guarded) {
  * tree's changes at open, which `block close` reads to tell the coder's changes from earlier ones.
  * B58: with `review.external.required` set, an owned entry that owns the project's config is
  * refused (`config-owned`, {@link refuseConfigOwner}).
+ * B59: `decision` (the rules lane of a brief-mode block) is written as a signed `decision` row
+ * naming the block, with `decisionId` (default a fresh UUID) as its `decision_id`, just before the
+ * `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;
@@ -313,8 +343,10 @@ export async function openBlock(opts) {
   if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
   if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
   if (opts.kind !== undefined && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${BLOCK_KINDS.join(', ')}`);
+  if (opts.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;
@@ -323,32 +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: [{ 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 */
@@ -364,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]);
@@ -386,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 }) {
@@ -400,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)) {