@codedology/code-forge 0.7.7 → 0.9.0

package/src/cli/block.mjs

@@ -1,15 +1,34 @@
 /**
- * `code-forge block open|attempt|rebase|claim|close|stop` (plan §4.9). The skill calls
+ * `code-forge block open|attempt|rebase|claim|close|stop|waive|reopen` (plan §4.9). The skill calls
  * `block open` before every spawn in every engine; it prints the brief pointer (≤ 200 bytes).
  *
  *   block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file>
  *              [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <forecast>] [--kind code|docs|contract]
+ *              [--tests <paths…>]
  *   block attempt <id> --run <r>
  *   block rebase <id> --run <r> [--head <ref>]
  *   block claim <id> <path> --run <r>
- *   block close <id> --run <r> [--worker-pid <pid>]
+ *   block close <id> --run <r> [--worker-pid <pid>] [--remove-worktree]
  *   block stop <id> --run <r> --reason <text>
  *   block waive <id> <finding-id> --run <r> --file <path> --reason <text>   (human-only, §4.9)
+ *   block reopen <id> --run <r> --file <path> --reason <text>   (human-only, B72)
+ *
+ * B64a `--json` (every subcommand): on success stdout is exactly ONE JSON line instead of the
+ * text — `{"block", "event", …}` with the facts the text prints (open: level, asked, source,
+ * kind, attempt, base_sha, tests, worktree, brief; attempt: attempt; rebase (`rebased`): old_base,
+ * new_base; claim (`claimed`): path; stop (`stopped`); waive (`waived`): finding, file, by;
+ * close (`closed`): status, reason, close_event (the close result's own event word, as the text
+ * prints it in parentheses, else null), and `worktree {removed, path, branch}` with
+ * `--remove-worktree`). On
+ * failure the exit code and stderr are unchanged and stdout stays empty, except a close the gate
+ * refused (`closeBlock` said no), which also prints `{"block", "ok": false, "reason"}`. A usage
+ * error, a thrown refusal, a cancelled `--no-require-reviews` and a failed `--remove-worktree`
+ * print nothing on stdout. Without `--json` every output is byte-identical to before.
+ *
+ * B64b block end: a close that closes or stops the block and `block stop` write
+ * `<runs>/<run>/blocks/<id>.done.json` after the end's rows (`state/block-end.mjs`), then, with
+ * `hooks.on_block_end` in the run's snapshot, run that command outside the lock and add
+ * `done_file` to `close`/`stop --json`. Without the key the output is unchanged.
  *
  * `block close [--transcript <file>] [--report <file>] [--no-require-reviews]` also runs B12b's review rows
  * (`review/gate-check.mjs`): a signed `review.approved` row for the current content hash of every
@@ -59,6 +78,29 @@
  * else still refuses — `unowned_change`, `unproven`, `no_changes`, the transcript grep and
  * `closeBlock`'s own rows. With `--no-require-reviews` the human path runs exactly as without the key.
  *
+ * B70 (issue #9 a): a file with no approval for its current hash whose real review (a signed
+ * `review.round` at that hash) left findings that are all waived — `block waive`, or an autopilot
+ * waiver its grant covered for a non-critical — passes as `reviewed_by_waiver`, never approved
+ * (`checkBlockReviews`). When the block closes, one signed `gate.review_waived_all {file,
+ * content_hash, findings, by}` row per such file is written just before `block.close` (after any
+ * other close row); a refused close writes none. The close prints `block <id>: <file>
+ * reviewed_by_waiver (<ids>; by <who>)` before the closed line, and `--json` adds
+ * `reviewed_by_waiver: [{file, content_hash, status, findings, by}]` (only when there is one).
+ * B71: a finding a signed `review.answered` row clears (another owned file resolved it, judged by
+ * a reviewer) counts like a waived one, listed under `answered` next to `findings` in the close
+ * row and the `--json` entry; the line then reads `(<ids>; by <who>; answered <ids>)`, or
+ * `(answered <ids>)` when nothing was waived (`by` is then null).
+ *
+ * B63b: `context.require_coder_tests: true` in the run's config snapshot (immutable like
+ * `review.external`; the live config is never read for it) adds one check after the report check:
+ * `--report` must be given and readable, its last sentinel for the block must be COMPLETE, and a
+ * `TESTS <command> exit=<n>` line must come before it with `n` 0 — else `coder report FAILED:
+ * context.require_coder_tests needs --report` / `--report cannot be read` / `no ===BLOCK <id>
+ * COMPLETE=== sentinel` / `no TESTS line` / `TESTS exit=<n>`. Waived reviews (the human flag or
+ * `review.external`) do not lift it. On a pass a signed `coder.tests {block, command, exit}` row
+ * (the command redacted) is one of `closeBlock`'s close rows, after any waiver row. Without the key
+ * (or false) nothing is added.
+ *
  * B47: `block open` without `--level` takes the level `autopilot level` chose for the block (the
  * latest `autopilot.level` row of the run for it whose MAC verifies, `autopilotLevel`); with
  * neither it is a usage error (`no --level given and no autopilot level recorded for <id>`). An
@@ -72,6 +114,48 @@
  * `--level` still wins, with no decision row. Outside brief mode `--lines` stays the forecast it
  * always was, and no `--level` without an autopilot level is the usage error above.
  *
+ * B60: `--tests <paths…>` names the block's test files (the same path rules as `--owned`); they are
+ * recorded as the block's `test_files` and on the dispatch row, and a gate argv item that is
+ * exactly `{test_files}` runs them (`gates run --run --block`). Without it the gate takes the owned
+ * entries that look like tests.
+ *
+ * B62a: under `proof.isolation: worktree` (the run's config snapshot, `proof/worktree.mjs`) `block
+ * open` makes the block's own worktree and branch before the block is recorded — or reuses the one
+ * an earlier attempt of the same block made — and prints a `worktree <path> · branch <branch>` line
+ * between the open line and the brief pointer. A refused `git worktree add` refuses the open (exit
+ * 1) with nothing recorded. `block close --remove-worktree` runs `git worktree remove <path>` (no
+ * `--force`; the branch is kept) only after the block closed, and writes a signed
+ * `worktree.removed` or `worktree.remove_failed` row; a failed removal is exit 1 with the block
+ * still closed. The flag on a block without a worktree, or on another subcommand, is a usage error
+ * (exit 2). It is coder-forbidden (`CODER_ONLY_FORBIDDEN`).
+ *
+ * B62b: `block close` of a block with a worktree measures that tree (`blockTree`), not the main
+ * one: the changed files (committed on the block's branch and uncommitted, against
+ * `worktree.base_sha`), the file set and its content hashes, and the unowned changes all come from
+ * the tree, by the same rules as for the main tree. A change in the main tree or in another
+ * block's tree never counts for the block. A fresh tree holds nothing but the block's own work,
+ * so every change in it is the block's: the `tree_at_open` stamps (taken in the main tree) do not
+ * exempt anything there, and a file another block owns is not left to that block (its close
+ * measures only its own tree) — a change in the tree to any file this block does not own is
+ * `unowned_change`. The whole close uses one base, the tree's `base_sha`. A tree that is gone,
+ * not a directory, without the workspace's subdirectory, or recorded malformed refuses the close
+ * before anything is asked or written. The ledger, the signed result files and the high paths stay
+ * in the main tree. Nothing is checked out, pushed or merged.
+ *
+ * B72 (issues #12, #15): `block reopen <id> --run <r> --file <path> --reason <text>` is the
+ * human's restart of a file whose review STOPPED or whose state is LOST (`review/reopen.mjs`):
+ * coder-forbidden like `block waive`. The done marker of the current content's ticket is removed
+ * (the ticket of the block's worktree when it has one), then one signed `review.reopened {block,
+ * file, from, stop_reason, at_seq, from_hash, to_hash, reason, by: human}` row is written, so the
+ * next `review-file` runs a full round 1. Refused (exit 1, no row): `unknown_block` and
+ * `reopen-block-not-open` (checked before anything is read), a `worktree-*` code (the block's tree
+ * cannot be read), `reopen-config` (the run's config snapshot or `tmp.root` cannot be read),
+ * `reopen-not-owned`, `reopen-tampered`, `reopen-not-stopped`, `reopen-same-content`,
+ * `reopen-already-recorded`, `reopen-write-failed`; a missing `--file` or `--reason` is a usage
+ * error (exit 2). It prints `block <id> reopened <file> (from
+ * <from>[ <stop reason>]; by: human)`; `--json`: `{"block", "event": "reopened", "file", "from",
+ * "stop_reason", "at_seq", "from_hash", "to_hash", "ticket_cleared", "by"}`.
+ *
  * `--acceptance` is a YAML/JSON list of `{clause, tests: [test ids…]}`. `block close` runs B8's
  * rows of the gate (worker pin, MACs, orphans); the gate rows owned by later blocks join it
  * through `closeBlock`'s `extraChecks`.
@@ -86,26 +170,90 @@ import { laneFacts } from '../decide/lane-facts.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { attemptBlock, claimPath, closeBlock, openBlock, rebaseBlock, repoTop, stopBlock } from '../state/block.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
-import { configInForce, externalReviewer } from '../state/config-snapshot.mjs';
+import { configInForce, externalReviewer, requireCoderTests } from '../state/config-snapshot.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun, writeSigned } from '../state/run.mjs';
 import { loadKey, verifyRow } from '../state/signer.mjs';
 import { blockFileSet, changedFiles, ownsAt, resultFilesFor, reviewedFiles, reviewGateCheck, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
 import { checkExpiry } from '../autopilot/grant.mjs';
-import { writeSafe } from '../util/redact.mjs';
+import { redact, writeSafe } from '../util/redact.mjs';
+import { blockTree, prepareWorktree, removeWorktree, worktreeSettings } from '../proof/worktree.mjs';
 import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
 import { validateConfig } from '../config/validate.mjs';
 import { migrateConfig } from '../config/migrate.mjs';
 import { exec } from '../util/exec.mjs';
-import { gitChildEnv } from '../worker/ticket.mjs';
-import { missingReviewTickets } from '../engines/sentinel.mjs';
+import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
+import { clearDone } from '../worker/queue.mjs';
+import { loadState } from '../worker/review-state.mjs';
+import { openBlockEntry, reopenFile } from '../review/reopen.mjs';
+import { runRootPath } from '../util/tmp.mjs';
+import { missingReviewTickets, parseSentinel } from '../engines/sentinel.mjs';
+import { blockEndHook, runBlockEndHook, writeDoneFile } from '../state/block-end.mjs';
+import { blockOpenFindings } from '../review/open-findings.mjs';
+import { hookForbidden, scanTranscript } from '../util/forbidden.mjs';
+
+/**
+ * B72: `block reopen` — the file's content is read where the block works (its worktree, else the
+ * main tree), its state is read (never moved) from the code-forge home or the run's old temp root,
+ * the checks, the done marker's removal and then the signed row are `reopenFile`'s.
+ * @param {{runId: string, id: string, file: string, reason: string, record: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean}>}
+ */
+async function reopenBlockFile({ runId, id, file, reason, record, writeRow }) {
+  // the stable block codes come first, before any tree, config, key or ledger read
+  const entry = openBlockEntry(record, runId, id);
+  const real = async (/** @type {string} */ p) => realpath(p).catch(() => path.resolve(p));
+  const mainTop = await real(await repoTop(record.workspace));
+  const wt = await blockTree(record.workspace, entry).catch((thrown) => {
+    if (typeof thrown?.code === 'string' && thrown.code.startsWith('worktree-')) throw new StateError(thrown.code, `block ${id}: ${thrown.message}, so the file's content cannot be read; nothing was recorded`);
+    throw thrown;
+  });
+  const contentRoot = wt === null ? mainTop : wt.top;
+  const wsPrefix = path.relative(mainTop, await real(record.workspace)).split(path.sep).join('/');
+  // the state is read where the worker keeps it: an unreadable snapshot or tmp.root is refused,
+  // never guessed (a wrong root would read as "no state"); only an absent tmp.root (undefined or
+  // null) means the default root, any other non-string is refused (B79)
+  /** @type {string} */
+  let runRootDir;
+  try {
+    const root = configInForce(record)?.tmp?.root;
+    if (root !== undefined && root !== null && typeof root !== 'string') throw new TypeError('tmp.root is not a string');
+    runRootDir = runRootPath(runId, typeof root === 'string' ? { root } : {});
+  } catch {
+    throw new StateError('reopen-config', `reopen-config: the run's config snapshot or its tmp.root cannot be read, so the review state of ${file} cannot be found; nothing was recorded`);
+  }
+  const key = await loadKey(runId);
+  const rows = await readAllRows(record.project);
+  const tree = contentRoot === mainTop ? {} : { tree: contentRoot };
+  const { row, cleared } = await reopenFile({
+    runId,
+    id,
+    file,
+    reason,
+    record,
+    rows,
+    key,
+    writeRow,
+    writeSigned,
+    io: {
+      owns: ownsAt(wsPrefix),
+      loadState: (where) => loadState({ .../** @type {any} */ (where), runRootDir, contentRoot, migrate: false }),
+      contentHash: (f) => contentHash(contentRoot, f),
+      // C11 (synchronous): the cached result of the current content's ticket would repeat the stop
+      clearDone: (f) => clearDone({ repoRoot: mainTop, run: runId, block: id, file: f, ...tree }).removed,
+    },
+  });
+  return { row, cleared };
+}
 
 const USAGE =
-  'usage: code-forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code|docs|contract]\n' +
-  '       code-forge block attempt|rebase <id> --run <r> · block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews] · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
-  '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>\n';
+  'usage: code-forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code|docs|contract] [--tests <paths…>]\n' +
+  '       code-forge block attempt|rebase <id> --run <r> · block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews] [--remove-worktree] · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
+  '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>\n' +
+  '       code-forge block reopen <id> --run <r> --file <path> --reason <text>\n' +
+  '       every block verb takes --json: one JSON line on stdout ({"block","event",…}) instead of the text\n';
 
-const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'];
+const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen'];
 const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
 
 /**
@@ -114,9 +262,11 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  *   stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, probe?: import('../state/run.mjs').StartTimeProbe, now?: () => Date,
  *   isTTY?: boolean, stdinIsTTY?: boolean, stdoutIsTTY?: boolean,
  *   ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean},
+ *   removeBlockTree?: typeof removeBlockTree,
  * }} [deps] - `now` (B48): the clock of the autopilot expiry checks. `stdinIsTTY` / `stdoutIsTTY`
  *   (default `process.stdin.isTTY` / `process.stdout.isTTY`; `isTTY` sets both) and `ui` (default
  *   `@clack/prompts`): B52's confirmation of `--no-require-reviews`, which needs both to be TTYs.
+ *   `removeBlockTree` (B64b, tests only): the `--remove-worktree` step, default the real one.
  * @returns {Promise<number>}
  */
 export async function runBlock(args, deps = {}) {
@@ -129,19 +279,68 @@ export async function runBlock(args, deps = {}) {
     return 2;
   }
   try {
-    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned'], booleans: ['no-require-reviews'] });
+    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned', 'tests'], booleans: ['no-require-reviews', 'remove-worktree', 'json'] });
+    // B64a: --json prints ONE JSON line on success instead of the text lines (`emit`, one object
+    // per verb, built where the text is); without it every output is exactly as before (`say` is `out`)
+    const json = flags.json === true;
+    const say = json ? (/** @type {string} */ _s) => {} : out;
+    const emit = (/** @type {Record<string, unknown>} */ obj) => out(`${JSON.stringify(obj)}\n`);
+    // B60: --tests names exact paths (a file or a directory — PHPUnit and Pest take directories).
+    // `*` and `?` are refused: a glob would reach the gate unexpanded. `[` and `{` are allowed,
+    // since real paths use them (`app/[id]/page.test.tsx`) and argv never reaches a shell. A
+    // leading "-" would be read as an option.
+    for (const t of sub === 'open' && Array.isArray(flags.tests) ? flags.tests : []) {
+      if (/[*?]/.test(t)) throw new StateError('usage', `--tests takes exact paths (a file or a directory); "*" and "?" are refused: ${JSON.stringify(t)}`);
+      if (t.startsWith('-')) throw new StateError('usage', `--tests: a path may not start with "-": ${JSON.stringify(t)}`);
+    }
     const [id, extra] = positionals;
     const runId = typeof flags.run === 'string' ? flags.run : undefined;
     if (!id || !runId) throw new StateError('usage', 'a block id and --run are required');
     if (sub === 'open' && (typeof flags.acceptance !== 'string' || !Array.isArray(flags.owned) || (flags.level !== undefined && typeof flags.level !== 'string'))) {
       throw new StateError('usage', 'block open needs --level, --owned and --acceptance');
     }
+    if (sub !== 'close' && flags['remove-worktree'] === true) throw new StateError('usage', '--remove-worktree is a block close flag');
     if (sub === 'claim' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block claim needs exactly one path');
-    if ((sub === 'stop' || sub === 'waive') && typeof flags.reason !== 'string') throw new StateError('usage', `block ${sub} needs --reason`);
+    if ((sub === 'stop' || sub === 'waive' || sub === 'reopen') && typeof flags.reason !== 'string') throw new StateError('usage', `block ${sub} needs --reason`);
     if (sub === 'waive' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block waive needs exactly one finding id');
+    if (sub === 'reopen' && positionals.length !== 1) throw new StateError('usage', 'block reopen takes one block id (the file goes in --file)');
+    if (sub === 'reopen' && typeof flags.file !== 'string') throw new StateError('usage', 'block reopen needs --file <path>');
     if (sub === 'waive' && typeof flags.file !== 'string') throw new StateError('usage', 'block waive needs --file <path> (a finding id is scoped to one file)');
     const record = await readRun(runId);
     const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+    // B64b: the block-end signal — after an end's rows (and outside the run lock) the done file,
+    // then the owner's `hooks.on_block_end` from the run-start snapshot. Without the hook key the
+    // done file is the only addition: no row, and every output stays exactly as before.
+    const hook = blockEndHook(record);
+    const ended = async (/** @type {'closed' | 'stopped'} */ status, /** @type {string} */ event, /** @type {string | null} */ reason) => {
+      // ruling (e): `ended` never throws — any failure here is the done-file warning and a null
+      // `doneFile`, so the caller's try/finally still reaches the hook
+      /** @type {string | null} */
+      let doneFile = null;
+      try {
+        doneFile = await writeDoneFile({
+          record,
+          id,
+          status,
+          event,
+          reason: typeof reason === 'string' ? redact(reason) : null,
+          openFindings: (rows) => blockOpenFindings(record, rows, id),
+          err,
+        });
+      } catch (thrown) {
+        const code = /** @type {any} */ (thrown)?.code;
+        err(`warning: done file not written: ${typeof code === 'string' && /^[A-Z0-9_]{1,32}$/.test(code) ? code : 'UNKNOWN'}\n`);
+        doneFile = null;
+      }
+      return {
+        json: hook === null ? {} : { done_file: doneFile },
+        runHook: async () => {
+          if (hook === null) return;
+          const top = await repoTop(record.workspace).catch(() => record.workspace);
+          await runBlockEndHook({ hook, runId, id, status, doneFile: doneFile ?? '', repoTop: top, writeRow, err });
+        },
+      };
+    };
     // B48: every block command runs the lazy autopilot checks (grant expiry, expired approvals);
     // a failed check is a warning, never a reason to stop the block command
     try {
@@ -179,7 +378,9 @@ export async function runBlock(args, deps = {}) {
         if (relative.startsWith('..') || path.isAbsolute(relative)) throw new StateError('usage', '--brief must be a file inside the workspace');
         brief = { path: relative, content: await readFile(absolute) };
       }
-      const { block, pointer } = await openBlock({
+      // B62a: the run's isolation, from its config snapshot (fixed for the run)
+      const isolated = worktreeSettings(record);
+      const { block, pointer, worktreeReused } = await openBlock({
         runId,
         id,
         level,
@@ -191,37 +392,76 @@ export async function runBlock(args, deps = {}) {
         brief,
         ...(rules ? { decision: { question: 'lane', answer: rules.lane, source: 'rules', facts: rules.facts } } : {}),
         ...(typeof flags.kind === 'string' ? { kind: flags.kind } : {}),
+        ...(Array.isArray(flags.tests) ? { tests: flags.tests } : {}),
         cfg: await openConfig(record.workspace),
         writeRow,
+        ...(isolated ? { worktree: (/** @type {{baseSha: string, previous: any}} */ ctx) => prepareWorktree({ cwd: record.workspace, settings: isolated, runId, id, ...ctx }) } : {}),
       });
       const raised = block.level !== level ? ` (${block.kind} floor, asked ${level})` : '';
       const chosen = typeof flags.level === 'string' ? '' : rules ? ' (rules lane)' : ' (autopilot level)';
-      out(`block ${id} open · ${block.level}${raised}${chosen} · ${block.kind} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}\n`);
-      out(`${pointer ?? 'brief: none given (--brief <file>)'}\n`);
+      const testCount = Array.isArray(block.test_files) ? block.test_files.length : 0;
+      const tests = testCount > 0 ? ` · ${testCount} test file${testCount === 1 ? '' : 's'}` : '';
+      say(`block ${id} open · ${block.level}${raised}${chosen} · ${block.kind} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}${tests}\n`);
+      if (block.worktree) say(`worktree ${block.worktree.path} · branch ${block.worktree.branch}${worktreeReused ? ' · reused' : ''}\n`);
+      say(`${pointer ?? 'brief: none given (--brief <file>)'}\n`);
+      if (json) {
+        emit({
+          block: id,
+          event: 'open',
+          level: block.level,
+          asked: level ?? null,
+          source: typeof flags.level === 'string' ? 'flag' : rules ? 'rules' : 'autopilot',
+          kind: block.kind,
+          attempt: block.attempt,
+          base_sha: block.base_sha,
+          tests: testCount,
+          worktree: block.worktree ? { path: block.worktree.path, branch: block.worktree.branch, reused: Boolean(worktreeReused) } : null,
+          brief: pointer ?? null,
+        });
+      }
       return 0;
     }
     if (sub === 'attempt') {
-      out(`block ${id} attempt ${await attemptBlock({ runId, id, writeRow })}\n`);
+      const n = await attemptBlock({ runId, id, writeRow });
+      say(`block ${id} attempt ${n}\n`);
+      if (json) emit({ block: id, event: 'attempt', attempt: n });
       return 0;
     }
     if (sub === 'rebase') {
       const moved = await rebaseBlock({ runId, id, head: typeof flags.head === 'string' ? flags.head : undefined, writeRow });
-      out(`block ${id} rebased ${moved.old_base.slice(0, 12)} → ${moved.new_base.slice(0, 12)}\n`);
+      say(`block ${id} rebased ${moved.old_base.slice(0, 12)} → ${moved.new_base.slice(0, 12)}\n`);
+      if (json) emit({ block: id, event: 'rebased', old_base: moved.old_base, new_base: moved.new_base });
       return 0;
     }
     if (sub === 'claim') {
       await claimPath({ runId, id, file: extra, writeRow });
-      out(`block ${id} claimed ${extra}\n`);
+      say(`block ${id} claimed ${extra}\n`);
+      if (json) emit({ block: id, event: 'claimed', path: extra });
       return 0;
     }
     if (sub === 'stop') {
       await stopBlock({ runId, id, reason: /** @type {string} */ (flags.reason), writeRow });
-      out(`block ${id} stopped\n`);
-      return 0;
+      const end = await ended('stopped', 'block.stop', /** @type {string} */ (flags.reason));
+      try {
+        say(`block ${id} stopped\n`);
+        if (json) emit({ block: id, event: 'stopped', ...end.json });
+        return 0;
+      } finally {
+        await end.runHook();
+      }
     }
     if (sub === 'waive') {
       await waiveFinding({ runId, id, finding: extra, reason: /** @type {string} */ (flags.reason), file: /** @type {string} */ (flags.file), writeRow });
-      out(`block ${id} waived ${extra} in ${flags.file} (by: human)\n`);
+      say(`block ${id} waived ${extra} in ${flags.file} (by: human)\n`);
+      if (json) emit({ block: id, event: 'waived', finding: extra, file: flags.file, by: 'human' });
+      return 0;
+    }
+    if (sub === 'reopen') {
+      const file = /** @type {string} */ (flags.file);
+      const { row, cleared } = await reopenBlockFile({ runId, id, file, reason: /** @type {string} */ (flags.reason), record, writeRow });
+      const fromText = row.stop_reason == null ? row.from : `${row.from} ${row.stop_reason}`;
+      say(`block ${id} reopened ${file} (from ${fromText}; by: human)\n`);
+      if (json) emit({ block: id, event: 'reopened', file, from: row.from, stop_reason: row.stop_reason, at_seq: row.at_seq, from_hash: row.from_hash, to_hash: row.to_hash, ticket_cleared: cleared, by: 'human' });
       return 0;
     }
     if (sub === 'close') {
@@ -230,6 +470,21 @@ export async function runBlock(args, deps = {}) {
       // B52: a block that is not open is refused here, with or without --no-require-reviews, by
       // the same check and message as `closeBlock` — and the owner is never asked about it
       if (entry.status !== 'open') throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
+      // B62a: removing a tree the block does not have is a usage error, before anything runs
+      const removeTree = flags['remove-worktree'] === true;
+      if (removeTree && !entry.worktree) throw new StateError('usage', `block ${id} has no worktree (proof.isolation is not worktree); --remove-worktree does not apply`);
+      // B62b: the block's tree is where its work is measured — a tree that is gone refuses the close
+      // before anything is asked or written
+      const wt = await blockTree(record.workspace, entry).catch((thrown) => {
+        if (thrown?.code === 'worktree-missing') {
+          throw new StateError('worktree-missing', `block ${id}: its worktree ${entry.worktree.path} is gone (removed or moved), so its work cannot be measured — restore it on branch ${entry.worktree.branch} (git worktree prune, then git worktree add ${entry.worktree.path} ${entry.worktree.branch}) and close again; nothing was recorded`);
+        }
+        if (typeof thrown?.code === 'string' && thrown.code.startsWith('worktree-')) throw new StateError(thrown.code, `block ${id}: ${thrown.message}, so its work cannot be measured; nothing was recorded`);
+        throw thrown;
+      });
+      // ONE base for the whole close: a worktree block is measured against the commit its tree was
+      // made from (B62a keeps it equal to the block's base_sha: a re-open keeps it, a rebase is refused)
+      const base = wt !== null ? wt.base_sha : entry.base_sha;
       const reviewsWaived = flags['no-require-reviews'] === true;
       // B52: the human's way out is confirmed by the human, at a terminal, before anything is written
       if (reviewsWaived) {
@@ -248,26 +503,46 @@ export async function runBlock(args, deps = {}) {
       // relative `file` and keeps its queue and signed result files under `<top>/.code-forge/`
       // (`repoRootOf`), and `tree_at_open` is stamped there too. An owned entry matches a path
       // as given or, for a workspace in a subdirectory, relative to the workspace (`ownsAt`).
-      // A failure here is the usual `git-failed` refusal.
-      /** @type {Promise<{top: string, wsPrefix: string, owns: (owned: ReadonlyArray<string>, file: string) => boolean, changed: string[], fileSet: Array<{file: string, content_hash: string}>, reviewed: string[]}> | undefined} */
+      // A failure here is the usual `git-failed` refusal. B62b: for a block with a worktree the
+      // listing and the content are the tree's (`top`); `mainTop` keeps the run's state.
+      /** @type {Promise<{top: string, mainTop: string, where: string, inTree: boolean, wsPrefix: string, owns: (owned: ReadonlyArray<string>, file: string) => boolean, changed: string[], fileSet: Array<{file: string, content_hash: string}>, reviewed: string[]}> | undefined} */
       let treeOnce;
       const tree = () =>
         (treeOnce ??= (async () => {
-          const top = await repoTop(record.workspace);
+          const mainTop = await repoTop(record.workspace);
+          const inTree = wt !== null;
+          const top = inTree ? wt.top : mainTop;
+          const where = inTree ? `the worktree ${wt.path}` : 'the workspace';
           // both sides as realpaths: git prints the top resolved (/private/var on macOS) while the
           // run record may keep a symlinked spelling (/var)
           const real = async (/** @type {string} */ p) => realpath(p).catch(() => path.resolve(p));
-          const wsPrefix = path.relative(await real(top), await real(record.workspace)).split(path.sep).join('/');
+          const wsPrefix = path.relative(await real(mainTop), await real(record.workspace)).split(path.sep).join('/');
           const owns = ownsAt(wsPrefix);
           const isMine = (/** @type {string} */ f) => owns(entry.owned_files, f, entry.owned_kinds);
-          const changed = await changedFiles({ repoRoot: top, base: entry.base_sha });
+          const changed = await changedFiles({ repoRoot: top, base });
           // the file set is the diff since base ∪ every owned file with review rows of this block —
           // work the diff cannot see (committed before `block open`, done in another worktree) is
-          // still checked, at its content in the workspace
+          // still checked, at its content in the workspace (in the block's worktree when it has one)
           const reviewed = reviewedFiles(rows, id).filter(isMine);
-          const fileSet = await blockFileSet({ repoRoot: top, base: entry.base_sha, owned: entry.owned_files, matchOwned: isMine, changed: [...new Set([...changed, ...reviewed])].sort() });
-          return { top, wsPrefix, owns, changed, fileSet, reviewed };
+          const fileSet = await blockFileSet({ repoRoot: top, base, owned: entry.owned_files, matchOwned: isMine, changed: [...new Set([...changed, ...reviewed])].sort() });
+          return { top, mainTop, where, inTree, wsPrefix, owns, changed, fileSet, reviewed };
         })());
+      // B58: the config waiver row is written by `closeBlock` under the run lock, just before
+      // `block.close` and only when every other check passed — never by a refused close
+      /** @type {Record<string, any>[]} */
+      const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
+      /** @type {import('../review/gate-check.mjs').WaivedAll[]} */
+      let waivedAll = [];
+      // B70: a file whose review left only waived findings passes as `reviewed_by_waiver`; its signed
+      // `gate.review_waived_all` row joins the close rows (written just before `block.close`, only
+      // when the block closes — a refused close writes none)
+      const onWaivedAll = (/** @type {import('../review/gate-check.mjs').WaivedAll[]} */ files) => {
+        // idempotent: the waived rows are rebuilt from the final list, never appended per call
+        // (closeBlock reads closeRows only after every extra check passed)
+        waivedAll = files;
+        const others = closeRows.filter((r) => r.event !== 'gate.review_waived_all');
+        closeRows.splice(0, closeRows.length, ...others, ...files.map((f) => ({ event: 'gate.review_waived_all', block: id, file: f.file, content_hash: f.content_hash, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })));
+      };
       const reviews = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
         if (transcript === null) {
@@ -277,13 +552,14 @@ export async function runBlock(args, deps = {}) {
         // the human's way out of the per-file review check leaves a signed audit row before the close
         if (reviewsWaived) await writeSigned(runId, writeRow, { event: 'gate.reviews_waived', block: id, by: 'human' });
         // B20: the high paths come first — a base the workspace does not know refuses the close here
-        const highPaths = await highPathsAt(record.workspace, entry.base_sha);
-        const { top, wsPrefix, owns, changed, fileSet, reviewed } = await tree();
+        const highPaths = await highPathsAt(record.workspace, base);
+        const { top, mainTop, where, inTree, wsPrefix, owns, changed, fileSet, reviewed } = await tree();
         const isMine = (/** @type {string} */ f) => owns(entry.owned_files, f, entry.owned_kinds);
         const key = await loadKey(runId);
         // B52: an empty diff with review rows is never silent — name the likely cause
         if (reviewed.length > 0 && !changed.some(isMine)) {
-          err(`WARN block ${id}: no owned file differs from the block base in the workspace, but ${reviewed.length} owned file(s) have review rows — the work was likely committed before block open or done in another worktree; they are checked at their content in the workspace\n`);
+          const likely = inTree ? 'done outside the block\'s worktree (in the main checkout or another tree)' : 'committed before block open or done in another worktree';
+          err(`WARN block ${id}: no owned file differs from the block base in ${where}, but ${reviewed.length} owned file(s) have review rows — the work was likely ${likely}; they are checked at their content in ${where}\n`);
         }
         // B52: only code-forge's own state is exempt — `<top>/.code-forge/`, where the worker keeps
         // its queue and signed results — never a `--transcript` or `--report` path in the source
@@ -293,7 +569,9 @@ export async function runBlock(args, deps = {}) {
         // `.code-forge/runs/<run>/<id>.log`)
         const wsRel = (/** @type {string} */ p) => path.posix.join(wsPrefix, p);
         const ownState = new Set([wsRel(`.code-forge/runs/${runId}.json`), wsRel(`.code-forge/runs/${runId}/${id}.log`)]);
-        const scope = await unownedChanges({ top, changed: changed.filter((f) => !ownState.has(f)), id, blocks: record.blocks, rows, key, isMine, owns, stateDir: '.code-forge' });
+        // B62b: a block's own tree started clean at its base and no other block works in it — no
+        // stamp from the main tree and no other block's ownership exempts a change there
+        const scope = await unownedChanges({ top, changed: changed.filter((f) => !ownState.has(f)), id, blocks: record.blocks, rows, key, isMine, owns, stateDir: '.code-forge', ownTree: inTree });
         if (scope === null) err(`WARN block ${id}: opened before code-forge recorded the tree at block open; unowned changes were not checked\n`);
         for (const { file, block: other } of scope?.siblings ?? []) err(`WARN block ${id}: ${file} changed and is owned by open block ${other}; not checked here (its own gate reviews it)\n`);
         return {
@@ -305,7 +583,7 @@ export async function runBlock(args, deps = {}) {
           // B52: a change no block of the run owns is refused — `--no-require-reviews` does not lift it
           unowned: scope?.unowned ?? [],
           // B52: an old ledger's review.result rows are judged by their signed result files
-          resultFiles: await resultFilesFor({ repoRoot: top, runId, block: id, rows }),
+          resultFiles: await resultFilesFor({ repoRoot: mainTop, runId, block: id, rows }),
           files: reviewsWaived || external !== null ? [] : fileSet,
           // B52: nothing changed and nothing reviewed is never a pass (the owner's way out is
           // --no-require-reviews); B58: `review.external` does not lift it
@@ -314,7 +592,7 @@ export async function runBlock(args, deps = {}) {
           proofFiles: fileSet,
           highPaths,
         };
-      });
+      }, { onWaivedAll });
       // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
       const report = async () => {
         if (typeof flags.report !== 'string' || reviewsWaived || external !== null) return { ok: true };
@@ -328,12 +606,76 @@ export async function runBlock(args, deps = {}) {
         const missing = missingReviewTickets(text, fileSet.map((f) => f.file));
         return missing.length === 0 ? { ok: true } : { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
       };
-      // B58: the config waiver row is written by `closeBlock` under the run lock, just before
-      // `block.close` and only when every other check passed — never by a refused close
-      const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
-      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews, report], closeRows });
-      (result.ok ? out : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
-      return result.ok ? 0 : 1;
+      /** @type {Array<() => Promise<{ok: boolean, reason?: string}>>} */
+      const extraChecks = [reviews, report];
+      // B63b: `context.require_coder_tests` in the run's config snapshot (never the live config)
+      // needs the coder's green test run — waived reviews do not lift it. It runs FIRST: it only
+      // reads the report, so a refusal here leaves no row (not even the human waiver row the review
+      // check writes). Absent or false: nothing is added, the close is exactly as before.
+      if (requireCoderTests(record)) {
+        extraChecks.unshift(async () => {
+          const tests = await coderTests(flags.report, id);
+          if (!tests.ok) return tests;
+          // signed under the run lock by `closeBlock`, after the waiver row, only when the block closes
+          closeRows.push({ event: 'coder.tests', block: id, command: redact(tests.command), exit: tests.exit });
+          return { ok: true };
+        });
+      }
+      // B64b: the hook command is the orchestrator's, never a coder's — a coder transcript that runs
+      // it refuses the close. Only with the hook configured (the list is otherwise unchanged); it
+      // only reads the transcript, so it runs first and a refusal here leaves no row.
+      if (hook !== null) {
+        extraChecks.unshift(async () => {
+          const text = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
+          const [hit] = text === null ? [] : scanTranscript(text, hookForbidden(hook.argv));
+          return hit ? { ok: false, reason: `rule_break transcript line ${hit.line}: ${hit.id}` } : { ok: true };
+        });
+      }
+      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks, closeRows });
+      // B64b: the block ended (closed, or stopped by a worker pin event or ledger.tamper) — its rows
+      // are written and the run lock released; the done file is written before the tree is removed
+      const end = result.status === 'closed' || result.status === 'stopped' ? await ended(result.status, result.event ?? (result.status === 'stopped' ? 'block.stop' : 'block.close'), result.reason ?? null) : null;
+      // B64b ruling (e): the hook runs exactly once for this end, after everything else the verb
+      // does — also when a later step (the output, `--remove-worktree`) throws; it never changes
+      // the exit code or stdout (`runHook` never throws)
+      try {
+        // B70: each file that passed as reviewed_by_waiver is named before the closed line
+        // B71: an answered finding is named as answered; a file with only answered findings has no `by`
+        if (result.ok) {
+          for (const f of waivedAll) {
+            const parts = f.findings.length > 0 ? [`${f.findings.join(', ')}; by ${f.by}`] : [];
+            if (f.answered?.length) parts.push(`answered ${f.answered.join(', ')}`);
+            say(`block ${id}: ${f.file} reviewed_by_waiver (${parts.join('; ')})\n`);
+          }
+        }
+        (result.ok ? say : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
+        // B64a: a refused close also names itself on stdout under --json (its stderr is unchanged)
+        if (json && !result.ok) emit({ block: id, ok: false, reason: result.reason ?? null, ...(end?.json ?? {}) });
+        const closedJson = {
+          block: id,
+          event: result.status,
+          status: result.status,
+          reason: result.reason ?? null,
+          close_event: result.event ?? null,
+          ...(end?.json ?? {}),
+          // B70: only when a file passed as reviewed_by_waiver (otherwise the output is unchanged)
+          ...(result.ok && waivedAll.length > 0 ? { reviewed_by_waiver: waivedAll.map((f) => ({ file: f.file, content_hash: f.content_hash, status: f.status, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })) } : {}),
+        };
+        if (!result.ok || !removeTree) {
+          if (json && result.ok) emit(closedJson);
+          return result.ok ? 0 : 1;
+        }
+        const removed = await (deps.removeBlockTree ?? removeBlockTree)(runId, id, entry.worktree, record.workspace, writeRow, say, err);
+        // a failed removal is exit 1 with its stderr text and nothing on stdout, like every failure
+        if (json && removed === 0) {
+          // built from the block's own tree entry; `removed` is what removeBlockTree reported (0 = removed)
+          const treeJson = entry.worktree ? { removed: removed === 0, path: entry.worktree.path, branch: entry.worktree.branch } : null;
+          emit({ ...closedJson, worktree: treeJson });
+        }
+        return removed;
+      } finally {
+        await end?.runHook();
+      }
     }
   } catch (thrown) {
     err(`block ${sub ?? ''}: ${thrown?.message ?? String(thrown)}\n`);
@@ -343,6 +685,50 @@ export async function runBlock(args, deps = {}) {
   return 2;
 }
 
+/**
+ * B62a: `block close --remove-worktree`, after the block closed: `git worktree remove <path>` (no
+ * `--force`, the branch is kept), then a signed `worktree.removed {block, path, branch}` or
+ * `worktree.remove_failed {block, path, reason}` row. A failed removal (a tree with modified or
+ * untracked files) leaves the tree where it is and the block closed, and is exit 1.
+ * @param {string} runId @param {string} id @param {{path: string, branch: string, base_sha: string}} worktree
+ * @param {string} workspace @param {(row: Record<string, any>) => Promise<unknown>} writeRow
+ * @param {(s: string) => unknown} out @param {(s: string) => unknown} err
+ * @returns {Promise<number>}
+ */
+async function removeBlockTree(runId, id, worktree, workspace, writeRow, out, err) {
+  const failed = await removeWorktree({ cwd: workspace, worktree });
+  if (failed === null) {
+    await writeSigned(runId, writeRow, { event: 'worktree.removed', block: id, path: worktree.path, branch: worktree.branch });
+    out(`block ${id} worktree removed: ${worktree.path} (branch ${worktree.branch} kept)\n`);
+    return 0;
+  }
+  await writeSigned(runId, writeRow, { event: 'worktree.remove_failed', block: id, path: worktree.path, reason: failed });
+  err(`block ${id} worktree NOT removed: ${failed} — the block stays closed; the tree stays at ${worktree.path} (commit or clean it, then git worktree remove it)\n`);
+  return 1;
+}
+
+/**
+ * B63b: the coder's green test run, read from its final report — the block's LAST sentinel must
+ * be COMPLETE, with a `TESTS <command> exit=0` line before it (`parseSentinel`).
+ * @param {unknown} reportFlag - the `--report` value (absent, or `true` for a valueless flag).
+ * @param {string} id
+ * @returns {Promise<{ok: true, command: string, exit: number} | {ok: false, reason: string}>}
+ */
+async function coderTests(reportFlag, id) {
+  if (typeof reportFlag !== 'string') return { ok: false, reason: 'coder report FAILED: context.require_coder_tests needs --report' };
+  let text;
+  try {
+    text = await readFile(reportFlag, 'utf8');
+  } catch {
+    return { ok: false, reason: 'coder report FAILED: --report cannot be read' };
+  }
+  const sentinel = parseSentinel(text, id);
+  if (sentinel?.status !== 'complete') return { ok: false, reason: `coder report FAILED: no ===BLOCK ${id} COMPLETE=== sentinel` };
+  if (!sentinel.tests) return { ok: false, reason: 'coder report FAILED: no TESTS line' };
+  if (sentinel.tests.exit !== 0) return { ok: false, reason: `coder report FAILED: TESTS exit=${sentinel.tests.exit}` };
+  return { ok: true, command: sentinel.tests.command, exit: 0 };
+}
+
 /** B52: the refusal when `--no-require-reviews` has no terminal to ask the human at. */
 export const NO_REVIEWS_NO_TTY = '--no-require-reviews needs the human at a terminal to confirm; the block stays open (there is no --yes)';