@codedology/code-forge 0.7.7 → 0.9.0

package/src/doctor/local.mjs

@@ -1,7 +1,8 @@
 /**
  * Doctor rows that need no provider CLI (plan §2.3; block B13b): config, harness links, Jev key
  * resolution (the three `--quick` rows), `code-forge` on PATH, Solo, gate commands, the live Jev
- * call, ledger writability and the `tmp` row. Every check returns rows; none throws.
+ * call, ledger writability, the `tmp` row and (B69) the `review state` row. Every check returns
+ * rows; none throws.
  */
 
 import { constants, readdirSync } from 'node:fs';
@@ -17,10 +18,16 @@ import { missingTools } from '../install/tools.mjs';
 import { OP_MESSAGES } from '../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { ledgerDir } from '../ledger/paths.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { DEFAULT_PROVIDER_CONCURRENCY, providerLimit } from '../session/spawn.mjs';
+import { snapshotFor } from '../state/config-snapshot.mjs';
+import { assertRunId, runsDir } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { loadKey } from '../state/signer.mjs';
 import { listEntries } from '../util/reaper.mjs';
-import { ownerState, tmpBase } from '../util/tmp.mjs';
+import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
+import { missingStateFiles } from '../worker/review-state.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
@@ -104,7 +111,8 @@ export async function checkCommands(cfg, pathEnv) {
   rows.push(row('solo', 'INFO', 'solo', 'UNVERIFIED (no Solo probe in this version)'));
   const gates = cfg?.gates && typeof cfg.gates === 'object' ? cfg.gates : {};
   let any = false;
-  for (const [name, argv] of Object.entries(gates)) {
+  for (const [name, command] of Object.entries(gates)) {
+    const argv = command && !Array.isArray(command) && typeof command === 'object' ? command.argv : command; // B60: {argv, env}
     if (!Array.isArray(argv) || argv.length === 0) continue;
     any = true;
     const found = await commandOnPath(String(argv[0]), { pathEnv });
@@ -191,6 +199,86 @@ export function checkTmp(cfg) {
   return [row('tmp', roots + pids > 0 ? 'WARN' : 'OK', 'tmp', roots + pids > 0 ? `${detail} (the next code-forge run start removes them)` : detail)];
 }
 
+/** B69: the most missing state files the `review state` row names. */
+export const LISTED_MAX = 10;
+
+/**
+ * B69: one WARN row per ACTIVE run (its record's `status` is `active`, as `run end` and the worker
+ * decide it) whose ledger has `review.state` anchors whose latest state file is missing — neither
+ * at `<code-forge home>/runs/<run>/review-state/` nor at the old temp-root path. The row counts the
+ * files the ledger can rebuild (the latest anchor carries `state_body`) and the lost ones (no body:
+ * the next ticket is refused `review-state-lost`; the owner needs `code-forge block reopen`), and
+ * names the first {@link LISTED_MAX} blocks and files (then `… and K more`). No row when nothing
+ * is missing. When the old temp location cannot be named (`tmp.root` not absolute), nothing is
+ * counted and the row says so; when an anchor of the run does not verify, the row says the review
+ * state was not checked. Each project's ledger is read once. Never throws: a run whose record, key
+ * or ledger cannot be read is skipped. No file content is read or printed.
+ * @param {Record<string, any> | null} cfg
+ * @returns {Promise<Row[]>}
+ */
+export async function checkReviewState(cfg) {
+  let names = [];
+  try {
+    names = readdirSync(runsDir()).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  /** @type {Row[]} */
+  const rows = [];
+  /** @type {Map<string, Array<Record<string, any>>>} the ledger rows per project, read once */
+  const ledgers = new Map();
+  for (const name of names.sort()) {
+    const runId = name.slice(0, -'.json'.length);
+    try {
+      assertRunId(runId);
+      const record = await readRun(runId);
+      if (record?.status !== 'active' || typeof record.project !== 'string') continue;
+      const key = await loadKey(runId);
+      let ledger = ledgers.get(record.project);
+      if (ledger === undefined) {
+        ledger = await readAllRows(record.project);
+        ledgers.set(record.project, ledger);
+      }
+      const atNew = missingStateFiles({ runId, key, rows: ledger });
+      if (atNew === null) {
+        rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: review.state anchors do not verify; review state not checked`));
+        continue;
+      }
+      let root;
+      try {
+        root = snapshotFor(record, '')?.config?.tmp?.root;
+      } catch {
+        root = undefined;
+      }
+      if (typeof root !== 'string') root = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
+      let runRootDir;
+      try {
+        runRootDir = runRootPath(runId, root === undefined ? {} : { root });
+      } catch {
+        runRootDir = undefined;
+      }
+      if (runRootDir === undefined) {
+        // the old place cannot be named: nothing is counted as missing, the row says why
+        if (atNew.length > 0) {
+          rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: the old temp location could not be checked (tmp.root is not an absolute path); review state files are not counted`));
+        }
+        continue;
+      }
+      const missing = missingStateFiles({ runId, key, rows: ledger, runRootDir });
+      if (missing === null || missing.length === 0) continue;
+      const rebuildable = missing.filter((m) => m.rebuildable).length;
+      const lost = missing.length - rebuildable;
+      const shown = missing.slice(0, LISTED_MAX).map((m) => `${m.block} ${m.file} (${m.rebuildable ? 'rebuildable' : 'lost'})`).join(', ');
+      const more = missing.length > LISTED_MAX ? ` … and ${missing.length - LISTED_MAX} more` : '';
+      rows.push(row('review-state', 'WARN', 'review state',
+        `run ${runId}: ${missing.length} state file(s) missing — ${rebuildable} rebuildable from the ledger, ${lost} lost (needs code-forge block reopen): ${shown}${more}`));
+    } catch {
+      // an unreadable record, key or ledger: not this row's business
+    }
+  }
+  return rows;
+}
+
 /**
  * B44: the `review concurrency` INFO row — how many review tickets run at once and each provider's
  * session slots, from the effective config (defaults when a key is unset). Never throws.

package/src/engines/sentinel.mjs

@@ -11,6 +11,16 @@
  * trimmed line (`^...$`), so a coder quoting the sentinel text inside ordinary prose ("I will not
  * print ===BLOCK B4 COMPLETE=== yet") never matches — only a line that IS exactly the sentinel does.
  *
+ * **TESTS.** B63b: a coder proves a green test run with a line that IS exactly `TESTS <command>
+ * exit=<n>` (matched after trimming; `<command>` non-empty free text, `<n>` a decimal 0–255 with no
+ * leading zeros — a non-numeric, signed or out-of-range value does not count) printed before its
+ * sentinel. On a returned sentinel, `tests: {command, exit}` is the LAST such line in that
+ * sentinel's own segment: after the previous sentinel line of ANY block (COMPLETE or FAILED) and
+ * before this one. A TESTS line before an earlier attempt's sentinel, or before another block's
+ * sentinel in a shared log, never carries over, and one after the sentinel is ignored; with none
+ * the result has no `tests` key at all. Like the sentinel, the pattern is anchored to the whole
+ * trimmed line, so a TESTS line quoted in prose never matches.
+ *
  * **ACK.** Before any tool call, a coder replies `ACK <sha8> lines=<n>` to the wire receipt it was
  * sent — the sha of the brief file, truncated to 8 hex characters (matched case-insensitively;
  * compared lowercased), and the brief's line count. `parseAck` returns the LAST matching line (fix
@@ -23,17 +33,21 @@
  * look like an ACK (an echoed instruction, a quoted example) being mistaken for the real one.
  */
 
-/** @typedef {{status: "complete", blockId: string} | {status: "failed", blockId: string, reason: string}} SentinelResult */
+/** @typedef {{command: string, exit: number}} TestsLine */
+/** @typedef {({status: "complete", blockId: string} | {status: "failed", blockId: string, reason: string}) & {tests?: TestsLine}} SentinelResult */
 
 const COMPLETE_RE = /^===BLOCK\s+(\S+)\s+COMPLETE===$/;
 const FAILED_RE = /^===BLOCK\s+(\S+)\s+FAILED:\s*(.*?)\s*===$/;
+/** B63b: `TESTS <command> exit=<n>` as a whole trimmed line (no leading zeros); 0–255 is checked after the match. */
+const TESTS_RE = /^TESTS\s+(\S.*?)\s+exit=(0|[1-9]\d{0,2})$/;
 
 /**
  * @param {string} output - the full captured transcript (subprocess stdout, or a Solo
  *   `get_process_output` join).
  * @param {string} [blockId] - when given, only sentinel lines for THIS block id count — a shared
  *   pane/log can interleave another block's lines.
- * @returns {SentinelResult | null} the LAST matching sentinel line, or `null` if none is present.
+ * @returns {SentinelResult | null} the LAST matching sentinel line, or `null` if none is present;
+ *   with `tests` when a `TESTS` line comes before it in its segment (B63b).
  */
 export function parseSentinel(output, blockId) {
   if (typeof output !== 'string') {
@@ -41,17 +55,24 @@ export function parseSentinel(output, blockId) {
   }
   /** @type {SentinelResult | null} */
   let last = null;
+  /** @type {TestsLine | null} */
+  let tests = null;
   for (const rawLine of output.split('\n')) {
     const line = rawLine.trim();
     const complete = COMPLETE_RE.exec(line);
-    if (complete && (!blockId || complete[1] === blockId)) {
-      last = { status: 'complete', blockId: complete[1] };
+    if (complete) {
+      if (!blockId || complete[1] === blockId) last = { status: 'complete', blockId: complete[1], ...(tests ? { tests } : {}) };
+      tests = null; // B63b: any sentinel line, of any block, ends the segment
       continue;
     }
     const failed = FAILED_RE.exec(line);
-    if (failed && (!blockId || failed[1] === blockId)) {
-      last = { status: 'failed', blockId: failed[1], reason: failed[2] };
+    if (failed) {
+      if (!blockId || failed[1] === blockId) last = { status: 'failed', blockId: failed[1], reason: failed[2], ...(tests ? { tests } : {}) };
+      tests = null;
+      continue;
     }
+    const run = TESTS_RE.exec(line);
+    if (run && Number(run[2]) <= 255) tests = { command: run[1], exit: Number(run[2]) };
   }
   return last;
 }

package/src/gates/detect.mjs

@@ -4,7 +4,7 @@
  * arrays, or `null` when the stack has no tool for that gate. Detection is pure filesystem
  * evidence (`fs.existsSync`/`readFileSync`) — no `git`, no child process, no network.
  *
- * Evidence is checked in the table's own order (PHP/Pest, then `package.json` scripts, Cargo,
+ * Evidence is checked in the table's own order (PHP/Pest or PHPUnit, then `package.json` scripts, Cargo,
  * pyproject, go.mod); the first stack whose marker file exists wins. A project with no marker
  * file at all is `unknown`: every gate is `null`, and `code` (a later block) refuses to run a
  * block whose `gates.test` is null — a block without a test gate cannot produce evidence.
@@ -18,10 +18,15 @@ import path from 'node:path';
  * (`gofmt -l`) exit 0 regardless of whether anything is unformatted and instead print the
  * offending file names to stdout — for those, the descriptor carries `failOnStdout: true` so
  * `run.mjs` treats non-empty stdout as red too, since a bare exit-code check can never fail.
- * @typedef {string[] | {argv: string[], failOnStdout: true}} GateCommand
+ * B60: a configured gate may be `{argv, env}` — `env` adds variables to the gate's environment
+ * (the values are never printed, `run.mjs`).
+ * @typedef {string[] | {argv: string[], failOnStdout?: true, env?: Record<string, string>}} GateCommand
  * @typedef {GateCommand | null} Gate
  */
-/** @typedef {{stack: string, test: Gate, lint: Gate, types: Gate, format: Gate}} DetectedGates */
+/**
+ * `stack` is one of `php-pest`, `php-phpunit`, `node`, `rust`, `python`, `go` or `unknown`.
+ * @typedef {{stack: string, test: Gate, lint: Gate, types: Gate, format: Gate}} DetectedGates
+ */
 
 /** @param {string} root @param {string} rel @returns {boolean} */
 function has(root, rel) {
@@ -49,15 +54,23 @@ function readText(root, rel) {
   }
 }
 
-// ── PHP / Pest ───────────────────────────────────────────────────────────────
+// ── PHP (Pest, PHPUnit) ─────────────────────────────────────────────────────
 
-/** @param {string} root @returns {DetectedGates | null} */
+/**
+ * `composer.json` plus an installed runner: `vendor/bin/pest` is `php-pest` (checked first, so a
+ * project with both binaries is Pest), else `vendor/bin/phpunit` is `php-phpunit` (B61). A Laravel
+ * app (`artisan` present) runs either through `php artisan test --compact`; without `artisan` the
+ * runner's own binary runs. `types` and `format` do not depend on the runner.
+ * @param {string} root @returns {DetectedGates | null}
+ */
 function detectPhp(root) {
-  if (!has(root, 'composer.json') || !has(root, 'vendor/bin/pest')) return null;
-  const test = has(root, 'artisan') ? ['php', 'artisan', 'test', '--compact'] : ['vendor/bin/pest'];
+  if (!has(root, 'composer.json')) return null;
+  const runner = has(root, 'vendor/bin/pest') ? 'pest' : has(root, 'vendor/bin/phpunit') ? 'phpunit' : null;
+  if (runner === null) return null;
+  const test = has(root, 'artisan') ? ['php', 'artisan', 'test', '--compact'] : [`vendor/bin/${runner}`];
   const types = has(root, 'phpstan.neon') || has(root, 'phpstan.neon.dist') ? ['vendor/bin/phpstan'] : null;
   const format = has(root, 'pint.json') || has(root, 'vendor/bin/pint') ? ['vendor/bin/pint', '--test'] : null;
-  return { stack: 'php-pest', test, lint: null, types, format };
+  return { stack: `php-${runner}`, test, lint: null, types, format };
 }
 
 // ── Node (package.json scripts) ────────────────────────────────────────────

package/src/gates/expand.mjs

@@ -0,0 +1,202 @@
+/**
+ * B60 (issue #13 item 3): run only the block's related tests, and give a gate its own environment.
+ * Pure — no filesystem, no child process. A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
+ * (one whole item, never a substring, never a shell string) stands for the block's test files:
+ *
+ *  - the block's `test_files` (`block open --tests`), else its owned entries that are concrete
+ *    files (no glob, no trailing `/`) and look like tests ({@link isTestPath});
+ *  - when the block owns more FILES than `gates.full_suite_threshold_files` (default 10; globs and
+ *    directories count the tracked and new (not ignored) files they cover — the caller counts them, gates/owned-count.mjs),
+ *    or no test file is known (also: a gate run with no block), the item is DROPPED and the gate
+ *    runs the full suite.
+ *
+ * {@link testScope} decides which, once per gate run; {@link expandArgv} applies it to one argv.
+ * A gate without the token is never touched.
+ *
+ * A gate given as `{argv, env}` runs with `env` added to the inherited environment. Gate env is
+ * NOT a secret store: code-forge prints and records only the variable NAMES ({@link envKeys},
+ * {@link printableGates}), never a value. The child's own output is masked only for values of
+ * {@link MASK_MIN_LENGTH} or more characters ({@link maskableEnvValues}) — a short value such as
+ * `CI=1` or `MODE=test` would otherwise mask unrelated text (`npm test`).
+ */
+
+import { isExactEntry } from '../state/registry.mjs';
+import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+
+export { TEST_FILES_TOKEN };
+
+/** `gates.full_suite_threshold_files` when the config leaves it out (the schema default). */
+export const DEFAULT_FULL_SUITE_THRESHOLD = 10;
+
+/** The shortest env value masked in a gate's own output. */
+export const MASK_MIN_LENGTH = 8;
+
+/**
+ * The threshold a configured value gives: the value itself when it is an integer >= 0, else the
+ * default.
+ * @param {unknown} value - `gates.full_suite_threshold_files` as the config holds it.
+ * @returns {number}
+ */
+export function thresholdOf(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : DEFAULT_FULL_SUITE_THRESHOLD;
+}
+
+/** Directory names that hold tests. */
+const TEST_DIRS = new Set(['test', 'tests', '__tests__', 'spec']);
+
+/**
+ * The shared test-path predicate: a directory segment named `test`, `tests`, `__tests__` or
+ * `spec`, or a file name ending `.test.<ext>` / `.spec.<ext>` (`a.test.mjs`, `a.spec.ts`),
+ * `Test.php` (`UserTest.php`), `_test.go`, or a Python `test_*.py`.
+ * @param {string} p - a repo-relative POSIX path (an owned entry; a glob is judged by its text).
+ * @returns {boolean}
+ */
+export function isTestPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return false;
+  const segments = p.split('/');
+  const name = segments[segments.length - 1];
+  if (segments.slice(0, -1).some((s) => TEST_DIRS.has(s))) return true;
+  return /\.(test|spec)\.[^/]+$/.test(name) || name.endsWith('Test.php') || name.endsWith('_test.go') || /^test_.*\.py$/.test(name);
+}
+
+/**
+ * An owned entry that names one file: no glob character (`*`, `?`, `{`) and no trailing `/`.
+ * @param {string} p @returns {boolean}
+ */
+const isConcreteFile = (p) => typeof p === 'string' && p.length > 0 && isExactEntry(p) && !p.endsWith('/');
+
+/**
+ * @typedef {{scope: 'related', files: string[]} | {scope: 'full', reason: 'threshold' | 'no_tests'}} TestScope
+ */
+
+/** A gate run with no block: no test file is known. */
+export const NO_BLOCK_SCOPE = Object.freeze(/** @type {TestScope} */ ({ scope: 'full', reason: 'no_tests' }));
+
+/**
+ * Which tests a `{test_files}` gate runs for one block.
+ * @param {{testFiles?: ReadonlyArray<string> | null, owned: ReadonlyArray<string>, ownedFiles?: number, threshold?: number}} opts
+ *   `testFiles` - the block's `test_files` (`block open --tests`), or none; `owned` - its owned
+ *   entries; `ownedFiles` - how many files those entries cover (`ownedFileCount`,
+ *   gates/owned-count.mjs; when not given, one per entry); `threshold` -
+ *   `gates.full_suite_threshold_files`, compared with `ownedFiles`.
+ * @returns {TestScope}
+ */
+export function testScope({ testFiles, owned, ownedFiles = owned.length, threshold = DEFAULT_FULL_SUITE_THRESHOLD }) {
+  if (ownedFiles > threshold) return { scope: 'full', reason: 'threshold' };
+  const files = testFiles && testFiles.length > 0 ? [...testFiles] : owned.filter((p) => isConcreteFile(p) && isTestPath(p));
+  if (files.length === 0) return { scope: 'full', reason: 'no_tests' };
+  return { scope: 'related', files };
+}
+
+/**
+ * The argv of one gate command (an argv array or `{argv, ...}`), or null.
+ * @param {unknown} command @returns {ReadonlyArray<unknown> | null}
+ */
+function argvOf(command) {
+  if (Array.isArray(command)) return command;
+  if (command && typeof command === 'object' && Array.isArray(/** @type {{argv?: unknown}} */ (command).argv)) return /** @type {{argv: unknown[]}} */ (command).argv;
+  return null;
+}
+
+/**
+ * Does any gate in `gates` have an argv item that is exactly {@link TEST_FILES_TOKEN} (a whole
+ * item — the same test {@link expandArgv} applies)? Only then is a block's test scope worked out;
+ * a run of plain gates never reads it.
+ * @param {Record<string, unknown> | null | undefined} gates @returns {boolean}
+ */
+export function hasTestFilesItem(gates) {
+  return Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(TEST_FILES_TOKEN) === true);
+}
+
+/**
+ * One gate argv with every item that is exactly {@link TEST_FILES_TOKEN} replaced by the related
+ * test files, or dropped for a full run. Always a new array; `scoped` is false (and the items
+ * unchanged) when the gate has no such item.
+ * @param {ReadonlyArray<string>} argv @param {TestScope} scope
+ * @returns {{argv: string[], scoped: boolean}}
+ * @throws {TypeError} a test path that starts with `-` (it would be read as an option; `block
+ *   open --tests` refuses one too).
+ */
+export function expandArgv(argv, scope) {
+  if (!argv.includes(TEST_FILES_TOKEN)) return { argv: [...argv], scoped: false };
+  const files = scope.scope === 'related' ? scope.files : [];
+  const dashed = files.find((f) => f.startsWith('-'));
+  if (dashed !== undefined) throw new TypeError(`expandArgv: test path ${JSON.stringify(dashed)} starts with "-"`);
+  return { argv: argv.flatMap((item) => (item === TEST_FILES_TOKEN ? files : [item])), scoped: true };
+}
+
+/**
+ * The fields a scoped gate's result and ledger row carry: `scope`, plus `test_count` when related
+ * or `reason` when full.
+ * @param {TestScope} scope
+ * @returns {{scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold' | 'no_tests'}}
+ */
+export function scopeFields(scope) {
+  return scope.scope === 'related' ? { scope: 'related', test_count: scope.files.length } : { scope: 'full', reason: scope.reason };
+}
+
+/**
+ * A gate command's env as a plain `NAME: value` map, or null when it has none: an argv array, an
+ * object without `env`, or an empty `env: {}` (treated as no env at all).
+ * @param {unknown} command
+ * @returns {Record<string, string> | null}
+ */
+export function envOf(command) {
+  if (!command || typeof command !== 'object' || Array.isArray(command)) return null;
+  const env = /** @type {{env?: unknown}} */ (command).env;
+  if (!env || typeof env !== 'object' || Array.isArray(env) || Object.keys(env).length === 0) return null;
+  return /** @type {Record<string, string>} */ (env);
+}
+
+/**
+ * The sorted variable NAMES of a gate command's env, or null when it has none.
+ * @param {unknown} command @returns {string[] | null}
+ */
+export function envKeys(command) {
+  const env = envOf(command);
+  return env ? Object.keys(env).sort() : null;
+}
+
+/**
+ * Every non-empty string value of every gate's `env`, across every entry of `gates`.
+ * @param {Record<string, unknown> | null | undefined} gates
+ * @returns {string[]}
+ */
+export function envValues(gates) {
+  /** @type {string[]} */
+  const values = [];
+  for (const command of Object.values(gates ?? {})) {
+    for (const value of Object.values(envOf(command) ?? {})) if (typeof value === 'string' && value.length > 0) values.push(value);
+  }
+  return values;
+}
+
+/**
+ * The env values a gate's own output is masked for: those of {@link MASK_MIN_LENGTH} or more
+ * characters. Shorter ones are not masked (they would hide unrelated text).
+ * @param {Record<string, unknown> | null | undefined} gates @returns {string[]}
+ */
+export function maskableEnvValues(gates) {
+  return envValues(gates).filter((value) => value.length >= MASK_MIN_LENGTH);
+}
+
+/**
+ * A copy of `gates` safe to print: each command given with `env` keeps its other fields and shows
+ * `env_keys` (the names) in place of `env`; an empty env is left out. Nothing else changes.
+ * @template {Record<string, any>} T
+ * @param {T} gates @returns {T}
+ */
+export function printableGates(gates) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, command] of Object.entries(gates ?? {})) {
+    if (!command || typeof command !== 'object' || Array.isArray(command) || !Object.hasOwn(command, 'env')) {
+      out[key] = command;
+      continue;
+    }
+    const { env: _env, ...rest } = /** @type {Record<string, unknown>} */ (command);
+    const keys = envKeys(command);
+    out[key] = keys ? { ...rest, env_keys: keys } : rest;
+  }
+  return /** @type {T} */ (out);
+}

package/src/gates/owned-count.mjs

@@ -0,0 +1,66 @@
+/**
+ * B60: how many FILES a block owns, for `gates.full_suite_threshold_files`.
+ *
+ * The owned entries are resolved against the workspace's tracked and new (not ignored) files
+ * (`git ls-files -z --cached --others --exclude-standard`, argv only) with the B57
+ * ownership rule (`ownsFile`, state/registry.mjs): a directory entry counts every such file below it, a glob counts its matches, a file counts once. Each file is counted
+ * once however many entries cover it. An entry that covers none of them (a path the block will
+ * create) counts as 1. Outside a git repository every entry counts as 1; any other git failure
+ * (a timeout, a spawn error, git failing inside a repository) gives `Infinity`, so the full suite
+ * runs (`reason: threshold`) rather than a guess.
+ *
+ * {@link countOwnedFiles} is the pure rule; {@link ownedFileCount} reads the files from git.
+ */
+import os from 'node:os';
+import { ownsFile } from '../state/registry.mjs';
+import { exec } from '../util/exec.mjs';
+
+const GIT_TIMEOUT_MS = 30000;
+
+/**
+ * The number of files `owned` covers among `files`, each counted once, plus 1 for every entry
+ * that covers none of them.
+ * @param {ReadonlyArray<string>} owned
+ * @param {ReadonlyArray<string>} tracked - the workspace's files
+ * @param {Record<string, string>} [kinds] - the block's `owned_kinds`
+ * @returns {number}
+ */
+export function countOwnedFiles(owned, tracked, kinds) {
+  const covered = new Set();
+  let notThere = 0;
+  for (const entry of owned) {
+    const hits = tracked.filter((file) => ownsFile([entry], file, kinds));
+    if (hits.length === 0) notThere += 1;
+    for (const file of hits) covered.add(file);
+  }
+  return covered.size + notThere;
+}
+
+/** `process.env` minus every inherited `GIT_*`, with no system/global config, messages in English. */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) env[key] = value;
+  }
+  env.LC_ALL = 'C'; // the "not a git repository" message is matched below
+  return env;
+}
+
+/** The files `git ls-files` lists: tracked (`--cached`) and new, not ignored (`--others --exclude-standard`). */
+const LS_FILES_ARGV = Object.freeze(['git', 'ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+
+/**
+ * {@link countOwnedFiles} over the tracked and new (not ignored) files of the workspace at `cwd`.
+ * Not a git repository: every entry counts 1. Any other failure: `Infinity` (the full suite runs).
+ * @param {string} cwd
+ * @param {ReadonlyArray<string>} owned
+ * @param {Record<string, string>} [kinds]
+ * @returns {Promise<number>}
+ */
+export async function ownedFileCount(cwd, owned, kinds) {
+  const res = await exec([...LS_FILES_ARGV], { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result === 'ok') return countOwnedFiles(owned, res.stdout.split('\0').filter((f) => f.length > 0), kinds);
+  if (!res.timedOut && res.code === 128 && /not a git repository/i.test(res.stderr)) return countOwnedFiles(owned, [], kinds);
+  return Number.POSITIVE_INFINITY;
+}

package/src/gates/run.mjs

@@ -7,10 +7,13 @@
  */
 
 import { exec } from '../util/exec.mjs';
+import { registerSecret } from '../util/redact.mjs';
+import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } from './expand.mjs';
 
 /** @typedef {import('./detect.mjs').Gate} Gate */
 /** @typedef {import('./detect.mjs').GateCommand} GateCommand */
 /** @typedef {import('./detect.mjs').DetectedGates} DetectedGates */
+/** @typedef {import('./expand.mjs').TestScope} TestScope */
 
 /**
  * @typedef {object} GateResult
@@ -22,26 +25,35 @@ import { exec } from '../util/exec.mjs';
  * @property {number | null} code
  * @property {string} stdout
  * @property {string} stderr
+ * @property {'related'|'full'} [scope] - B60: only on a gate whose argv has the `{test_files}` item.
+ * @property {number} [test_count] - B60: with `scope: related`, how many test files it ran.
+ * @property {'threshold'|'no_tests'} [reason] - B60: with `scope: full`, why the item was dropped.
+ * @property {string[]} [env_keys] - B60: only on a gate given with a non-empty `env`: the variable
+ *   NAMES, sorted (the values are never in a result).
  */
 
 /** Fixed run order — always all four, regardless of an earlier one's result. */
 const GATE_ORDER = /** @type {const} */ (['test', 'lint', 'types', 'format']);
 
 /**
- * A gate command is either a plain argv array or `{argv, failOnStdout: true}` (detect.mjs's
- * `GateCommand`, e.g. `gofmt -l` which always exits 0). Normalized here so the run loop below has
- * one shape to deal with.
+ * A gate command is either a plain argv array or `{argv, failOnStdout?, env?}` (detect.mjs's
+ * `GateCommand`: `failOnStdout` for `gofmt -l`, which always exits 0; B60 `env` from the config).
+ * Normalized here so the run loop below has one shape to deal with.
  * @param {GateCommand} command
- * @returns {{argv: string[], failOnStdout: boolean}}
+ * @returns {{argv: string[], failOnStdout: boolean, env: Record<string, string> | null}}
  */
 function normalizeCommand(command) {
-  if (Array.isArray(command)) return { argv: command, failOnStdout: false };
-  return { argv: command.argv, failOnStdout: command.failOnStdout === true };
+  if (Array.isArray(command)) return { argv: command, failOnStdout: false, env: null };
+  return { argv: command.argv, failOnStdout: command.failOnStdout === true, env: envOf(command) }; // `env: {}` is no env
 }
 
 /**
+ * B60: `opts.scope` is the block's {@link TestScope} (`testScope`, gates/expand.mjs); a gate argv
+ * item that is exactly `{test_files}` expands to its files, or is dropped for a full run. Left out,
+ * no test file is known (`scope: full, reason: no_tests`). A gate with `env` runs with those
+ * variables added to the inherited environment; a gate with neither runs exactly as before B60.
  * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate}} gates
- * @param {{cwd: string, timeoutMs?: number}} opts
+ * @param {{cwd: string, timeoutMs?: number, scope?: TestScope}} opts
  * @returns {Promise<{results: GateResult[], allOk: boolean}>}
  */
 export async function runGates(gates, opts) {
@@ -49,24 +61,49 @@ export async function runGates(gates, opts) {
     throw new TypeError('runGates: gates must be an object with test/lint/types/format');
   }
   const { cwd, timeoutMs = 300000 } = opts ?? {};
+  const scope = opts?.scope ?? NO_BLOCK_SCOPE; // null falls back too
   if (typeof cwd !== 'string' || cwd.length === 0) {
     throw new TypeError('runGates: opts.cwd must be a non-empty string');
   }
 
+  // B60: gate env is not a secret store. Its values are never put in a result (only `env_keys`);
+  // a value of 8+ characters is also masked in the child's own output (a shorter one would mask
+  // unrelated text — `MODE=test` vs `npm test`)
+  for (const value of maskableEnvValues(gates)) registerSecret(value);
+  // Every gate is normalized and expanded BEFORE any runs, so a bad gate throws with nothing run.
+  // B60: config validation refuses a gate whose only item is {test_files}; the empty-argv check
+  // is the guard for one that reaches here anyway: it names the gate, not an opaque spawn error.
+  const planned = GATE_ORDER.map((gate) => {
+    const command = gates[gate] ?? null;
+    if (command === null) return { gate, command: null };
+    const normalized = normalizeCommand(command);
+    const { argv, scoped } = expandArgv(normalized.argv, scope);
+    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once '{test_files}' is dropped for the full suite — put the test command before it`);
+    return { gate, command: { argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } };
+  });
   /** @type {GateResult[]} */
   const results = [];
-  for (const gate of GATE_ORDER) {
-    const command = gates[gate] ?? null;
+  for (const { gate, command } of planned) {
     if (command === null) {
       results.push({ gate, argv: null, skipped: true, ok: true, code: null, stdout: '', stderr: '' });
       continue;
     }
-    const { argv, failOnStdout } = normalizeCommand(command);
+    const { argv, scoped, failOnStdout, env } = command;
     // Each command is run and its exit status read on its own — never `&&`-chained with the
     // next, so a red gate is reported red without swallowing the gates that follow it.
-    const res = await exec(argv, { cwd, timeoutMs });
+    const res = await exec(argv, env ? { cwd, timeoutMs, env: { ...process.env, ...env } } : { cwd, timeoutMs });
     const ok = res.result === 'ok' && (!failOnStdout || res.stdout.trim().length === 0);
-    results.push({ gate, argv, skipped: false, ok, code: res.code, stdout: res.stdout, stderr: res.stderr });
+    results.push({
+      gate,
+      argv,
+      skipped: false,
+      ok,
+      code: res.code,
+      stdout: res.stdout,
+      stderr: res.stderr,
+      ...(scoped ? scopeFields(scope) : {}),
+      ...(env ? { env_keys: Object.keys(env).sort() } : {}),
+    });
   }
   return { results, allOk: results.every((r) => r.ok) };
 }