@codedology/code-forge 0.7.6 → 0.8.0

package/src/cli/block.mjs

@@ -4,13 +4,31 @@
  *
  *   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)
  *
+ * 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
  * changed owned file (deletions included) that no later review of the same content made stale
@@ -59,11 +77,57 @@
  * 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.
  *
+ * 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
  * explicit `--level` always wins; a repeated or valueless `--level` is a usage error as before.
  *
+ * B59: in a brief-mode run (`run start --mode brief`), `block open` without `--level` takes the
+ * lane from the §3.5 rules (`fallbackLane`) over facts built from the owned entries, `--lines`
+ * (estimated changed lines) and `proof.tiers.high.paths` of the run's config snapshot
+ * (`laneFacts`), and writes one signed `decision {question: lane, source: rules}` row naming the
+ * block, then the `dispatch` row (`openBlock`; neither when the open is refused). An explicit
+ * `--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.
+ *
  * `--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`.
@@ -73,27 +137,34 @@ import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYAML } from 'yaml';
 import { approvalCheckText, expiryChecks } from '../autopilot/limits.mjs';
+import { fallbackLane } from '../decide/fallback-rules.mjs';
+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 { 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 { 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';
 
 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' +
+  '       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 FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
@@ -104,9 +175,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 = {}) {
@@ -119,19 +192,66 @@ 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 === 'waive' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block waive needs exactly one finding id');
     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 {
@@ -141,8 +261,25 @@ export async function runBlock(args, deps = {}) {
     }
 
     if (sub === 'open') {
-      // B47: no --level ⇒ the level autopilot chose for the block (a signed autopilot.level row)
-      const level = typeof flags.level === 'string' ? flags.level : await autopilotLevel(runId, id, record);
+      // an explicit --level wins; B59: else in a brief-mode run the rules lane; B47: else the level
+      // autopilot chose for the block (a signed autopilot.level row)
+      /** @type {{lane: string, facts: ReturnType<typeof laneFacts>} | null} */
+      let rules = null;
+      /** @type {string | null} */
+      let level;
+      // B59: only the rules lane parses --lines this early; every other open parses it where it
+      // always was (after the level check and --attempt), so its errors keep their pre-B59 order
+      /** @type {number | null | undefined} */
+      let lines;
+      if (typeof flags.level === 'string') {
+        level = flags.level;
+      } else if (record.mode === 'brief') {
+        lines = intFlag(flags.lines, 'lines') ?? null;
+        rules = rulesLane(record, /** @type {string[]} */ (flags.owned), lines);
+        level = rules.lane;
+      } else {
+        level = await autopilotLevel(runId, id, record);
+      }
       if (level === null) throw new StateError('usage', `no --level given and no autopilot level recorded for ${id}`);
       const acceptance = parseYAML(await readFile(/** @type {string} */ (flags.acceptance), 'utf8'), { prettyErrors: false });
       let brief;
@@ -152,7 +289,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,
@@ -160,40 +299,72 @@ export async function runBlock(args, deps = {}) {
         acceptance,
         attempt: intFlag(flags.attempt, 'attempt'),
         base: typeof flags.base === 'string' ? flags.base : undefined,
-        lines: intFlag(flags.lines, 'lines') ?? null,
+        lines: lines === undefined ? (intFlag(flags.lines, 'lines') ?? null) : lines,
         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' ? '' : ' (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 chosen = typeof flags.level === 'string' ? '' : rules ? ' (rules lane)' : ' (autopilot level)';
+      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 === 'close') {
@@ -202,6 +373,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) {
@@ -220,25 +406,29 @@ 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 };
         })());
       const reviews = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
@@ -249,13 +439,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
@@ -265,7 +456,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 {
@@ -277,7 +470,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
@@ -302,10 +495,60 @@ export async function runBlock(args, deps = {}) {
       };
       // 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 }];
-      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 {
+        (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 ?? {}) };
+        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`);
@@ -315,6 +558,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)';
 
@@ -344,6 +631,19 @@ async function confirmNoReviews(runId, id, deps) {
   return ui.isCancel(go) || go !== true ? 'cancelled' : 'confirmed';
 }
 
+/**
+ * B59: the rules lane for a brief-mode block — `fallbackLane` over the facts of its owned entries,
+ * the `--lines` estimate and the snapshot's `proof.tiers.high.paths` (none for a record from
+ * before snapshots).
+ * @param {Record<string, any>} record @param {string[]} owned @param {number | null} lines
+ * @returns {{lane: string, facts: ReturnType<typeof laneFacts>}}
+ */
+function rulesLane(record, owned, lines) {
+  const high = configInForce(record)?.proof?.tiers?.high?.paths;
+  const facts = laneFacts({ owned, lines, highPaths: high });
+  return { lane: fallbackLane(facts), facts };
+}
+
 /**
  * B47: the level `autopilot level` chose for the block — the latest `autopilot.level` row of this
  * run for it whose MAC verifies — or null when there is none.