@codedology/code-forge 0.7.6 → 0.8.0

package/src/ledger/outside-review.mjs

@@ -0,0 +1,164 @@
+/**
+ * B66 (issue #13 item 8): outside review rounds per PR, next to what code-forge spent on the PR's
+ * blocks. Pure helpers, no I/O:
+ *
+ *  - `parseOutsideReviewArgs` reads `ledger outside-review --run <r> --pr <n> --rounds <n>
+ *    --findings <n> [--link <url>] [--block <id>]…` (the verb in `src/cli/ledger.mjs` does the
+ *    run lookup, the block check, the redaction and the signed write);
+ *  - `buildOutsideReview` builds the `outside_review` report section from the ledger rows and the
+ *    `cost_per_block` entries (`src/ledger/report.mjs` passes them in, so the PR cost is computed
+ *    by the SAME function the `cost_per_block` section uses);
+ *  - `outsideReviewLines` renders the section as terminal text.
+ *
+ * Row: `outside_review {run, pr, rounds, findings, link (or null), blocks: [ids]}`. A later row for
+ * the same PR replaces the earlier one in every reader (the latest row in ledger order wins); the
+ * ledger itself stays append-only.
+ */
+
+import { roundUsd } from './spend.mjs';
+
+export const OUTSIDE_REVIEW_EVENT = 'outside_review';
+
+export const OUTSIDE_REVIEW_USAGE =
+  'usage: code-forge ledger outside-review --run <r> --pr <n> --rounds <n> --findings <n> [--link <url>] [--block <id>]...';
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const POSITIVE_INT = /^[1-9]\d*$/;
+const NON_NEGATIVE_INT = /^(0|[1-9]\d*)$/;
+const LINK = /^https?:\/\/\S+$/;
+const MAX_LINK_CHARS = 2048;
+
+/** @param {unknown} n @returns {boolean} */
+const isCount = (n) => Number.isSafeInteger(n) && /** @type {number} */ (n) >= 0;
+
+const SINGLE_FLAGS = new Set(['--run', '--pr', '--rounds', '--findings', '--link']);
+
+/**
+ * @typedef {{run: string, pr: number, rounds: number, findings: number, link: string | null, blocks: string[]}} OutsideReviewArgs
+ */
+
+/**
+ * @param {string} raw @param {RegExp} shape @returns {number | null}
+ */
+function parseShapedInt(raw, shape) {
+  if (!shape.test(raw)) return null;
+  const n = Number(raw);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/**
+ * Parse the verb's flags (everything after `outside-review`). Every flag but `--block` is given at
+ * most once; `--block` may repeat (duplicates collapsed, first-seen order kept). Any other token,
+ * a flag with no value, a missing required flag or a value of the wrong shape is a usage error.
+ * The link is returned as given — the caller redacts it once the run key is registered.
+ * @param {string[]} args
+ * @returns {{ok: true, value: OutsideReviewArgs} | {ok: false, message: string}}
+ */
+export function parseOutsideReviewArgs(args) {
+  /** @type {Record<string, string>} */
+  const single = {};
+  /** @type {string[]} */
+  const blocks = [];
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    const value = args[i + 1];
+    // the position only, never the token: a stray value (a loose URL) may carry a secret
+    if (flag !== '--block' && !SINGLE_FLAGS.has(flag)) return { ok: false, message: `unknown argument at position ${i + 1}` };
+    if (value === undefined || value.startsWith('--')) return { ok: false, message: `${flag} requires a value` };
+    if (flag === '--block') {
+      if (!blocks.includes(value)) blocks.push(value);
+      continue;
+    }
+    if (Object.hasOwn(single, flag)) return { ok: false, message: `${flag} is given more than once` };
+    single[flag] = value;
+  }
+  for (const flag of ['--run', '--pr', '--rounds', '--findings']) {
+    if (!Object.hasOwn(single, flag)) return { ok: false, message: `${flag} is required` };
+  }
+  const run = single['--run'];
+  if (!RUN_ID.test(run)) return { ok: false, message: '--run must be a run id (letters, digits, ".", "_", "-")' };
+  const pr = parseShapedInt(single['--pr'], POSITIVE_INT);
+  if (pr === null) return { ok: false, message: '--pr must be a positive integer' };
+  const rounds = parseShapedInt(single['--rounds'], NON_NEGATIVE_INT);
+  if (rounds === null) return { ok: false, message: '--rounds must be a non-negative integer' };
+  const findings = parseShapedInt(single['--findings'], NON_NEGATIVE_INT);
+  if (findings === null) return { ok: false, message: '--findings must be a non-negative integer' };
+  let link = null;
+  if (Object.hasOwn(single, '--link')) {
+    link = single['--link'];
+    if (link.length > MAX_LINK_CHARS) return { ok: false, message: `--link is longer than ${MAX_LINK_CHARS} characters` };
+    if (!LINK.test(link)) return { ok: false, message: '--link must be an https:// or http:// URL with no whitespace' };
+  }
+  return { ok: true, value: { run, pr, rounds, findings, link, blocks } };
+}
+
+/** @param {string[]} blocks @returns {string} */
+const blockList = (blocks) => (blocks.length > 0 ? blocks.join(', ') : '-');
+
+/**
+ * The verb's one stdout line.
+ * @param {{pr: number, rounds: number, findings: number, blocks: string[]}} row @returns {string}
+ */
+export function outsideReviewRecordedLine({ pr, rounds, findings, blocks }) {
+  return `outside_review pr ${pr} · rounds ${rounds} · findings ${findings} · blocks ${blockList(blocks)}\n`;
+}
+
+/**
+ * @typedef {{pr: number, rounds: number, findings: number, link: string | null, blocks: string[], code_forge_usd: number, unknown_usd_sessions: number}} OutsideReviewEntry
+ */
+
+/**
+ * The `outside_review` report section: one entry per PR (the latest `outside_review` row for it,
+ * by ledger order), sorted by PR number ascending. `code_forge_usd` sums `totalUsd` of the
+ * `cost_per_block` entries of the row's run whose block the row names; `unknown_usd_sessions` sums
+ * their `unknownUsdSessions` (those sessions count 0 in the dollars). `[]` with no rows.
+ * @param {Array<Record<string, any>>} rows - shadow rows already removed.
+ * @param {Array<{run: string | null, block: string, totalUsd: number, unknownUsdSessions: number}>} costEntries - the `cost_per_block` section.
+ * @returns {OutsideReviewEntry[]}
+ */
+export function buildOutsideReview(rows, costEntries) {
+  /** @type {Map<number, Record<string, any>>} */
+  const latest = new Map();
+  for (const row of rows) {
+    if (row.event !== OUTSIDE_REVIEW_EVENT || !Number.isSafeInteger(row.pr) || row.pr <= 0) continue;
+    // a row whose counts are not 0-or-more safe integers is skipped (the verb never writes one)
+    if (!isCount(row.rounds) || !isCount(row.findings)) continue;
+    latest.set(row.pr, row);
+  }
+  return [...latest.values()]
+    .sort((a, b) => a.pr - b.pr)
+    .map((row) => {
+      const blocks = Array.isArray(row.blocks) ? row.blocks.filter((b) => typeof b === 'string') : [];
+      const run = typeof row.run === 'string' ? row.run : null;
+      // a row with no string run matches no cost entry (never the null-run entries): 0 and 0 unknown
+      const mine = run === null ? [] : costEntries.filter((e) => e.run === run && blocks.includes(e.block));
+      const usd = mine.reduce((sum, e) => sum + e.totalUsd, 0);
+      return {
+        pr: row.pr,
+        rounds: row.rounds,
+        findings: row.findings,
+        link: typeof row.link === 'string' ? row.link : null,
+        blocks,
+        // rounded as `cost_per_block` rounds its dollars (4 decimals)
+        code_forge_usd: roundUsd(usd),
+        unknown_usd_sessions: mine.reduce((sum, e) => sum + e.unknownUsdSessions, 0),
+      };
+    });
+}
+
+/** @param {number} n @param {string} word @returns {string} */
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * Terminal text of the section: `outside review: none` with no entry, else one line per PR.
+ * @param {OutsideReviewEntry[]} section @returns {string}
+ */
+export function outsideReviewLines(section) {
+  if (section.length === 0) return 'outside review: none\n';
+  return section
+    .map((e) => {
+      const unknown = e.unknown_usd_sessions > 0 ? ` (+${e.unknown_usd_sessions} unknown)` : '';
+      return `PR #${e.pr} · ${plural(e.rounds, 'outside round')} · ${plural(e.findings, 'finding')} · code-forge $${e.code_forge_usd.toFixed(2)}${unknown} · ${blockList(e.blocks)}\n`;
+    })
+    .join('');
+}

package/src/ledger/report.mjs

@@ -1,5 +1,5 @@
 /**
- * `code-forge report` (plan §6.2, R4): builds the 13 report sections from a run's ledger rows.
+ * `code-forge report` (plan §6.2, R4): builds the 14 report sections from a run's ledger rows.
  * Pure data, no I/O — terminal rendering + `--export` live in `src/cli/report.mjs`.
  *
  * Shadow rows (`row.source === 'shadow'`) are excluded everywhere here (plan §6.3: shadow-sampled
@@ -12,10 +12,15 @@
  * coder/reviewer/judge/s2/author/facts spend (plus `ledger add coder` manual rows and
  * `session.background` rows, whose price is unknown); its dollars come from `./spend.mjs`
  * (`usd`, else `cost_usd`, else ESTIMATED from its tokens × `./prices.mjs`); `review.done` {block,file,context_mode,findings_by_severity,round}; `decision`
- * {block,question,source}; `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
- * `review.unavailable` {block,reason}; `proof` {block,duration_ms}; `run.stop` {reason}.
+ * {block,question,source}; `run.start` {run}; `run.mode` {run,mode,plan} (B59, `buildRunModes`); `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
+ * `review.unavailable` {block,reason}; `proof` {block,duration_ms}; `run.stop` {reason};
+ * `outside_review` {run,pr,rounds,findings,link,blocks} (B66, `./outside-review.mjs`).
+ *
+ * Signatures are not verified here: like every other section, `outside_review` reads the rows as
+ * the ledger holds them (an unsigned or tampered row is counted, not dropped).
  */
 
+import { buildOutsideReview } from './outside-review.mjs';
 import { isSpendRow, rowUsd, spendByRun, sumSpend } from './spend.mjs';
 
 const ROLE_BUCKET = Object.freeze({
@@ -51,7 +56,7 @@ export function sessionCostUsd(row) {
 
 /**
  * B33: spend per run (running totals, open blocks included) and over the whole ledger — kept
- * beside the 13 sections, not as a 14th (`SECTION_NAMES` stays pinned at 13).
+ * beside the sections, never one of them (text only, not in `SECTION_NAMES`).
  * @param {Array<Record<string, any>>} rows
  * @returns {{runs: Array<{run: string | null, usd: number, unknown: number, sessions: number}>, total: {usd: number, unknown: number, sessions: number}}}
  */
@@ -60,6 +65,20 @@ export function buildSpend(rows) {
   return { runs: spendByRun(acted), total: sumSpend(acted) };
 }
 
+/**
+ * B59: the mode of every run with a `run.start` row, in ledger order — `brief` when the run has a
+ * `run.mode {mode: brief}` row, else `plan` (a run with no `run.mode` row is a plan run). Like the
+ * spend, it is terminal text only (`src/cli/report.mjs`): it is not in `--json` or `--export`, so
+ * the pinned `SECTION_NAMES` sections stay exactly as they are.
+ * @param {Array<Record<string, any>>} rows
+ * @returns {Array<{run: string, mode: 'brief' | 'plan'}>}
+ */
+export function buildRunModes(rows) {
+  const brief = new Set(rows.filter((r) => r.event === 'run.mode' && r.mode === 'brief' && typeof r.run === 'string').map((r) => r.run));
+  const runs = [...new Set(rows.filter((r) => r.event === 'run.start' && typeof r.run === 'string').map((r) => r.run))];
+  return runs.map((run) => ({ run, mode: brief.has(run) ? 'brief' : 'plan' }));
+}
+
 /**
  * Cost per block — completed AND still open (B33: a running total while the block is open):
  * review $ / coder $ / S1+S2 $ / facts $ / proof ms, `completed` (any `block.close` row) and
@@ -243,7 +262,8 @@ const runStopCounts = (rows) => ({
   noEngineStops: rows.filter((r) => r.event === 'run.stop' && r.reason === 'no_engine').length,
 });
 
-/** The exact, ordered set of section keys `buildReport` produces (plan §6.2: "13 sections") —
+/** The exact, ordered set of section keys `buildReport` produces (plan §6.2; B66 appended the
+ * 14th, `outside_review` — append new sections, never reorder) —
  * exported so tests (and `--export`) can assert against ONE source of truth instead of a copy. */
 export const SECTION_NAMES = Object.freeze([
   'cost_per_block',
@@ -259,6 +279,7 @@ export const SECTION_NAMES = Object.freeze([
   'forecast_vs_actual_lines',
   'blocks_stopped_at_l3',
   'run_stop_counts',
+  'outside_review',
 ]);
 
 /**
@@ -267,8 +288,10 @@ export const SECTION_NAMES = Object.freeze([
  */
 export function buildReport(rows) {
   const acted = rows.filter((r) => r.source !== 'shadow');
+  // computed once: `cost_per_block` and `outside_review` share the same entries
+  const costs = costPerBlock(acted);
   const builders = {
-    cost_per_block: costPerBlock,
+    cost_per_block: () => costs,
     lane_distribution: laneDistribution,
     escalations: escalationsPerBlock,
     s1_calls_per_block: s1CallsPerBlock,
@@ -281,6 +304,9 @@ export function buildReport(rows) {
     forecast_vs_actual_lines: forecastVsActualLines,
     blocks_stopped_at_l3: blocksStoppedAtL3,
     run_stop_counts: runStopCounts,
+    // B66: per PR, the outside review rounds next to the cost of its blocks — the SAME
+    // `costPerBlock` entries the `cost_per_block` section shows
+    outside_review: (/** @type {any[]} */ r) => buildOutsideReview(r, costs),
   };
   /** @type {Record<string, any>} */
   const sections = {};

package/src/proof/export.mjs

@@ -10,7 +10,12 @@
  *   (c) `proof.export.copy_untracked` paths that exist in the main tree ride along through
  *       `git archive --add-file` (never anything under `.code-forge/`);
  *   (d) the block's owned files at their CURRENT content (new files included, deleted ones removed);
- *   (e) `proof.export.link_dirs` symlinked from the main tree.
+ *   (e) `proof.export.link_dirs` symlinked from the main tree — except a Composer vendor directory
+ *       (B61: it holds `composer/autoload_real.php`), which is COPIED. PHP resolves `__DIR__`
+ *       through symlinks, so a linked vendor makes Composer's autoloader load the app's own classes
+ *       (`App\…`, `Tests\…`) from the MAIN tree, not the export: another block's half-written file
+ *       would leak into the measurement. Composer's generated paths are relative to the vendor
+ *       directory, so the copy points at the export's own `app/`, `tests/` and `database/`.
  *
  * A gate that fails inside the export on a file the export lacks but the main tree has is
  * `export.incomplete: <path>`, never a red test (`classifyExportFailure`).
@@ -24,7 +29,8 @@
  * `checkout-index`).
  */
 
-import { copyFile, lstat, mkdir, mkdtemp, readlink, realpath, rm, stat, symlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { copyFile, cp, lstat, mkdir, mkdtemp, readdir, readlink, realpath, rm, stat, symlink } from 'node:fs/promises';
 import path from 'node:path';
 import { runGates } from '../gates/run.mjs';
 import { StateError } from '../state/paths.mjs';
@@ -44,6 +50,8 @@ export const ISOLATIONS = Object.freeze(/** @type {const} */ (['export', 'lock']
 const BLOCK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
 const GIT_TIMEOUT_MS = 120000;
 const STATE_DIR = '.code-forge';
+/** B61: the file that makes a `link_dirs` entry a Composer vendor directory (copied, not linked). */
+const COMPOSER_AUTOLOADER = path.join('composer', 'autoload_real.php');
 
 /**
  * `process.env` minus every `GIT_*`, plus `extra`.
@@ -85,6 +93,58 @@ function assertRelPath(p, key) {
   return p;
 }
 
+/**
+ * B61: a Composer vendor directory (it holds `composer/autoload_real.php`) — copied into the export,
+ * never linked: PHP resolves `__DIR__` through a symlink, so a linked vendor would autoload the
+ * app's classes from the main tree.
+ * @param {string} dir @returns {Promise<boolean>}
+ */
+async function isComposerVendor(dir) {
+  return (await stat(path.join(dir, COMPOSER_AUTOLOADER)).catch(() => null))?.isFile() ?? false;
+}
+
+/**
+ * B61: inside a copied dependency dir, every absolute symlink whose target is in the main tree
+ * (a Composer path repository: `vendor/acme/pkg -> <main>/packages/pkg`) is pointed at the same
+ * place in the export; a link to the main-tree root points at the export root. Relative links,
+ * links outside the main tree and links into the main tree's `.code-forge/` (the export has none)
+ * stay as they are.
+ *
+ * `copy` must be a real directory (refused otherwise, before anything changes), and the walk never
+ * goes through a symlink: a `Dirent` from `readdir` describes the entry itself (lstat semantics), so
+ * only real directories are entered — a link is only ever rewritten, never followed, and nothing
+ * outside the copy is touched.
+ * @param {string} copy - the copied dir in the export @param {string[]} mainRoots - the main tree, as given and real
+ * @param {string} dir - the export root
+ */
+async function retargetMainTreeLinks(copy, mainRoots, dir) {
+  const at = await lstatOrNull(copy);
+  if (!at?.isDirectory()) throw new StateError('export-not-copied', `buildExport: ${copy} is not a real directory; its links are left unchanged`);
+  /** @type {string[]} */
+  const pending = [copy];
+  while (pending.length > 0) {
+    const current = /** @type {string} */ (pending.pop());
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(entryPath);
+        continue;
+      }
+      if (!entry.isSymbolicLink()) continue;
+      const target = await readlink(entryPath);
+      if (!path.isAbsolute(target)) continue;
+      for (const root of mainRoots) {
+        const rel = path.relative(root, target);
+        if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) continue;
+        if (rel === STATE_DIR || rel.startsWith(`${STATE_DIR}${path.sep}`)) break;
+        await rm(entryPath, { force: true });
+        await symlink(rel === '' ? dir : path.join(dir, rel), entryPath);
+        break;
+      }
+    }
+  }
+}
+
 /** @param {string} p @returns {Promise<import('node:fs').Stats | null>} */
 async function lstatOrNull(p) {
   try {
@@ -160,8 +220,8 @@ async function exportIgnoredBlobs(entries, base, cwd) {
  *   cwd: string, blockId: string, baseSha: string, owned: ReadonlyArray<string>, ownedKinds?: Readonly<Record<string, string>>,
  *   linkDirs?: ReadonlyArray<string>, copyUntracked?: ReadonlyArray<string>, exportRoot?: string,
  * }} opts
- * @returns {Promise<{dir: string, base: string, restored: string[], untracked: string[], owned: string[], removed: string[], linked: string[]}>}
- *   repo-relative lists, sorted.
+ * @returns {Promise<{dir: string, base: string, restored: string[], untracked: string[], owned: string[], removed: string[], linked: string[], copied: string[]}>}
+ *   repo-relative lists, sorted; `copied` is the `linkDirs` entries copied as Composer vendor dirs.
  */
 export async function buildExport(opts) {
   const { blockId, baseSha, owned, linkDirs = DEFAULT_LINK_DIRS, copyUntracked = DEFAULT_COPY_UNTRACKED } = opts;
@@ -268,8 +328,9 @@ export async function buildExport(opts) {
       ownedCopied.push(rel);
     }
 
-    // (e) dependency dirs, linked from the main tree.
+    // (e) dependency dirs, linked from the main tree; a Composer vendor dir is copied (B61).
     const linked = [];
+    const copied = [];
     for (const rel of linkDirs) {
       const src = path.join(cwd, rel);
       const st = await stat(src).catch(() => null);
@@ -277,11 +338,31 @@ export async function buildExport(opts) {
       const dest = path.join(dir, rel);
       await rm(dest, { recursive: true, force: true });
       await mkdir(path.dirname(dest), { recursive: true });
+      const real = await realpath(src);
+      if (await isComposerVendor(real)) {
+        // Copied from its real directory, so the copy is a real directory even when the main tree's
+        // entry is a symlink. Relative symlinks inside (vendor/bin entries) resolve in the copy;
+        // absolute ones into the main tree are pointed at the export. A copy-on-write clone where
+        // the file system has one.
+        await cp(real, dest, { recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE });
+        await retargetMainTreeLinks(dest, [...new Set([path.resolve(opts.cwd), cwd])], dir);
+        copied.push(rel);
+        continue;
+      }
       await symlink(src, dest, 'dir');
       linked.push(rel);
     }
 
-    return { dir, base, restored: [...restored].sort(), untracked: untracked.sort(), owned: ownedCopied, removed: [...removedSet].sort(), linked: linked.sort() };
+    return {
+      dir,
+      base,
+      restored: [...restored].sort(),
+      untracked: untracked.sort(),
+      owned: ownedCopied,
+      removed: [...removedSet].sort(),
+      linked: linked.sort(),
+      copied: copied.sort(),
+    };
   } finally {
     await rm(scratch, { recursive: true, force: true });
   }
@@ -358,11 +439,13 @@ export function incompleteMessage(missing) {
 
 /**
  * Run the block's gates (B5 `runGates`) inside the export; a red gate whose output is a
- * missing-file error for a main-tree path is re-labelled `export.incomplete`.
- * @param {{gates: Parameters<typeof runGates>[0], exportDir: string, mainTree: string, timeoutMs?: number}} opts
+ * missing-file error for a main-tree path is re-labelled `export.incomplete`. B60: `scope` (the
+ * block's `testScope`) is handed to `runGates` for a `{test_files}` gate; the test paths are
+ * repo-relative, so they name the same files inside the export.
+ * @param {{gates: Parameters<typeof runGates>[0], exportDir: string, mainTree: string, timeoutMs?: number, scope?: import('../gates/expand.mjs').TestScope}} opts
  */
-export async function runGatesInExport({ gates, exportDir, mainTree, timeoutMs }) {
-  const { results } = await runGates(gates, { cwd: exportDir, ...(timeoutMs ? { timeoutMs } : {}) });
+export async function runGatesInExport({ gates, exportDir, mainTree, timeoutMs, scope }) {
+  const { results } = await runGates(gates, { cwd: exportDir, ...(timeoutMs ? { timeoutMs } : {}), ...(scope ? { scope } : {}) });
   /** @type {{gate: string, path: string, message: string}[]} */
   const incomplete = [];
   const labelled = [];

package/src/proof/lock.mjs

@@ -16,6 +16,8 @@
  * with `isolation: lock` through the B6 writer.
  */
 
+import { hasTestFilesItem, testScope } from '../gates/expand.mjs';
+import { ownedFileCount } from '../gates/owned-count.mjs';
 import { runGates } from '../gates/run.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun, saveRun, withRunLock } from '../state/run.mjs';
@@ -129,10 +131,31 @@ export async function withGateSlot({ runId, blockId, fn, pid = process.pid }) {
 }
 
 /**
- * B5's gate runner behind the lock — the entry point a gate caller (`gates run --run --block`,
- * the B12 block gate) uses.
- * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number}} opts
+ * B5's gate runner behind the lock. A gate caller (`gates run --run --block`, the B12 block gate)
+ * uses it.
+ *
+ * B60: a `{test_files}` gate runs the block's related tests. These are its `test_files` (from
+ * `block open --tests`), else its owned entries that look like tests (`testScope`, read from the
+ * run record once the slot is taken). The full suite runs instead when the block owns more than
+ * `threshold` (`gates.full_suite_threshold_files`) files, or when no test file is known. The
+ * owned files are counted by `ownedFileCount` over the tracked and new (not ignored) files at
+ * `cwd`. Gates with no `{test_files}` item run exactly as before B60: the run record is not read
+ * and nothing is counted.
+ * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number, threshold?: number}} opts
  */
-export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs }) {
-  return withGateSlot({ runId, blockId, fn: () => runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) }) });
+export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, threshold }) {
+  return withGateSlot({
+    runId,
+    blockId,
+    fn: async () => {
+      // plain gates (no `{test_files}` item) run exactly as before B60: no scope is worked out
+      if (!hasTestFilesItem(gates)) return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+      // the slot checked the block is open; it may still be gone by the time it is read again
+      const block = (await readRun(runId)).blocks?.[blockId];
+      if (!block) throw new StateError('no-block', `block ${blockId} is not in run ${runId}`);
+      const ownedFiles = await ownedFileCount(cwd, block.owned_files, block.owned_kinds);
+      const scope = testScope({ testFiles: block.test_files, owned: block.owned_files, ownedFiles, ...(threshold === undefined ? {} : { threshold }) });
+      return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}), scope });
+    },
+  });
 }