@codedology/code-forge 0.15.1 → 0.15.3

package/src/gates/run.mjs

@@ -6,6 +6,11 @@
  * stops early.
  */
 
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { customGateMessages } from '../config/validate.mjs';
 import { exec } from '../util/exec.mjs';
 import { registerSecret } from '../util/redact.mjs';
 import { CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
@@ -16,6 +21,9 @@ import { NO_BLOCK_SCOPE, TEST_FILES_TOKEN, changedTestFiles, envOf, expandArgv,
 /** @typedef {import('./detect.mjs').DetectedGates} DetectedGates */
 /** @typedef {import('./expand.mjs').TestScope} TestScope */
 /** @typedef {{n: number, files: string[], failed: boolean}} Repeats */
+/** @typedef {{name: string, argv: string[], env?: Record<string, string>, evidence?: string[]}} CustomGate */
+/** @typedef {{path: string, bytes: number, sha256: string}} Evidence */
+/** @typedef {{kind: string, names: string[]}} KindGates */
 /**
  * Internal block context carried with the gate plan through the proof lock, so repeats run
  * inside the same slot as the initial commands.
@@ -24,17 +32,22 @@ import { NO_BLOCK_SCOPE, TEST_FILES_TOKEN, changedTestFiles, envOf, expandArgv,
 
 /**
  * @typedef {object} GateResult
- * @property {'test'|'lint'|'types'|'format'} gate
+ * @property {string} gate
+ * @property {number} duration_ms - wall time including repeats; zero for skipped gates.
+ * @property {true} [custom]
+ * @property {Evidence[]} [evidence]
+ * @property {string[]} [missing]
  * @property {string[] | null} argv
- * @property {boolean} skipped - true when the gate has no configured command (argv was null).
+ * @property {boolean} skipped - true when unconfigured or excluded by the block's kind set.
  * @property {boolean} ok - true when skipped, or when the command exited with code 0 (and, for a
  *   `failOnStdout` gate, its stdout was empty).
  * @property {number | null} code
  * @property {string} stdout
  * @property {string} stderr
+ * @property {string} [message] - termination diagnostic with the last lines of both streams.
  * @property {'related'|'full'|'changed'} [scope] - only on a gate with a scope token.
  * @property {number} [test_count] - B60: with `scope: related`, how many test files it ran.
- * @property {'threshold'|'no_tests'|'no_baseline'|'unpaired'|'no_changes'|'flaky-test'} [reason] - fallback or repeat failure.
+ * @property {'threshold'|'no_tests'|'no_baseline'|'unpaired'|'no_changes'|'flaky-test'|'timeout'|'prompt'|'spawn-error'|'terminated'|NodeJS.Signals|`not in gates.kinds.${string}`} [reason] - fallback, exclusion or gate failure.
  * @property {Repeats} [repeats]
  * @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).
@@ -43,6 +56,177 @@ import { NO_BLOCK_SCOPE, TEST_FILES_TOKEN, changedTestFiles, envOf, expandArgv,
 /** Fixed run order — always all four, regardless of an earlier one's result. */
 const GATE_ORDER = /** @type {const} */ (['test', 'lint', 'types', 'format']);
 
+/** Leave room below typical ARG_MAX limits for the inherited environment and spawn overhead. */
+const FORMAT_ARGV_BUDGET_BYTES = 100 * 1024;
+
+/** Repeat the executable and flags in every batch; count UTF-8 bytes and NUL terminators.
+ * @param {string[]} prefix @param {string[]} files @param {number} budget
+ * @returns {string[][]}
+ */
+function formatBatches(prefix, files, budget) {
+  if (!Number.isSafeInteger(budget) || budget <= 0) throw new TypeError('format: argv byte budget must be a positive safe integer');
+  const prefixBytes = prefix.reduce((sum, arg) => sum + Buffer.byteLength(arg) + 1, 0);
+  const batches = [];
+  let batch = prefix.slice();
+  let bytes = prefixBytes;
+  for (const file of files) {
+    const size = Buffer.byteLength(file) + 1;
+    if (prefixBytes + size > budget) throw new RangeError(`format: command and file exceed argv byte budget: ${file}`);
+    if (bytes + size > budget) {
+      batches.push(batch);
+      batch = prefix.slice();
+      bytes = prefixBytes;
+    }
+    batch.push(file);
+    bytes += size;
+  }
+  batches.push(batch);
+  return batches;
+}
+
+/** @param {string} stream @returns {string} */
+function outputTail(stream) {
+  const tail = stream.trimEnd().split(/\r?\n/).slice(-10).join('\n');
+  return tail ? `${tail}\n` : '';
+}
+
+/** Existing supported files only, never a directory or glob for the formatter to traverse.
+ * @param {string} cwd @param {'pint'|'prettier'} formatter
+ * @param {TestScope | import('./expand.mjs').ChangedScope} scope
+ * @returns {Promise<string[]>}
+ */
+async function formatFiles(cwd, formatter, scope) {
+  const changed = scope.scope === 'changed';
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const opts = { cwd, env, timeoutMs: 30000 };
+  const listed = await exec(['git', 'ls-files', '-z', '--cached', ...(changed ? ['--others'] : []), '--exclude-standard'], opts);
+  if (listed.result !== 'ok') throw new Error(`format: cannot list Git files: ${listed.stderr || listed.error || listed.signal || 'git failed'}`);
+  const wanted = changed ? new Set(scope.changedFiles) : null;
+  const files = [...new Set(listed.stdout.split('\0').filter((file) => file && (!wanted || wanted.has(file))))].sort();
+  if (files.length === 0) return [];
+  // --no-index also excludes force-added ignored paths. A cached path alone is not proof
+  // that the current ignore rules permit it.
+  const ignored = await exec(['git', 'check-ignore', '--no-index', '-z', '--stdin'], {
+    ...opts, input: `${files.join('\0')}\0`, okExitCodes: [0, 1],
+  });
+  if (ignored.result !== 'ok') throw new Error(`format: cannot check Git ignores: ${ignored.stderr || ignored.error || ignored.signal || 'git failed'}`);
+  const excluded = new Set(ignored.stdout.split('\0'));
+  const root = await realpath(cwd);
+  const selected = [];
+  for (const file of files) {
+    if (excluded.has(file)) continue;
+    const supported = formatter === 'pint' ? /\.php$/i.test(file)
+      : /\.(?:[cm]?[jt]sx?|json5?|jsonc|css|scss|less|html?|vue|md|mdx|markdown|ya?ml|graphql|gql|hbs|handlebars|mustache|mjml)$/i.test(file)
+        || ['.prettierrc', '.babelrc', '.eslintrc', '.stylelintrc'].includes(path.basename(file));
+    if (!supported) continue;
+    try {
+      const absolute = path.resolve(root, file);
+      if (!(await lstat(absolute)).isFile() || await realpath(absolute) !== absolute) continue;
+    } catch (error) {
+      if (['ENOENT', 'ENOTDIR'].includes(error.code)) continue;
+      throw error;
+    }
+    // Leading dashes cannot become options, and existing paths are not treated as globs.
+    selected.push(`./${file}`);
+  }
+  return selected;
+}
+
+/** Unanswered prompt suffixes; inspect only each stream's last non-empty line. */
+export const UNANSWERED_PROMPT_PATTERN = /(?:\?|\(y(?:\/n)?\)|\[y\/n\]|yes\/no)\s*$/i;
+
+/** Simple globs only: * stays in one segment; ** can cross segments.
+ * @param {string} pattern @returns {RegExp}
+ */
+function evidenceMatcher(pattern) {
+  const normalized = pattern.split('/').filter((part) => part !== '.' && part !== '').join('/');
+  let source = '';
+  for (let i = 0; i < normalized.length; i++) {
+    const char = normalized[i];
+    if (char === '*' && normalized[i + 1] === '*') {
+      i++;
+      if (normalized[i + 1] === '/') { source += '(?:.*/)?'; i++; }
+      else source += '.*';
+    } else if (char === '*') source += '[^/]*';
+    else source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** Missing, inaccessible or replaced entries are not evidence.
+ * @param {NodeJS.ErrnoException} error @returns {boolean}
+ */
+function evidenceUnavailable(error) {
+  return ['ENOENT', 'ENOTDIR', 'EACCES', 'ELOOP'].includes(error.code);
+}
+
+/** Never traverse symlinks. Hash at most 200 unique files, without retaining their content.
+ * @param {string} cwd @param {string[]} patterns
+ * @returns {Promise<{evidence: Evidence[], missing?: string[]}>}
+ */
+async function collectEvidence(cwd, patterns) {
+  if (patterns.length === 0) return { evidence: [] };
+  let root;
+  try { root = await realpath(cwd); }
+  catch (error) {
+    if (evidenceUnavailable(error)) return { evidence: [], missing: patterns };
+    throw error;
+  }
+  const matchers = patterns.map(evidenceMatcher);
+  /** @type {Set<string>} */
+  const matched = new Set();
+  /** @param {string} dir @returns {Promise<void>} */
+  async function walk(dir) {
+    let entries;
+    try { entries = await readdir(path.join(root, dir), { withFileTypes: true }); }
+    catch (error) {
+      if (evidenceUnavailable(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const file = dir ? `${dir}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink()) continue;
+      // Also check the resolved path before descending/opening, in case a parent changed.
+      let resolved;
+      try { resolved = await realpath(path.join(root, file)); }
+      catch (error) { if (evidenceUnavailable(error)) continue; throw error; }
+      const relative = path.relative(root, resolved);
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue;
+      if (entry.isDirectory()) await walk(file);
+      else if (entry.isFile()) {
+        if (matchers.some((matcher) => matcher.test(file))) matched.add(file);
+      }
+    }
+  }
+  await walk('');
+  /** @type {Evidence[]} */
+  const evidence = [];
+  for (const file of [...matched].sort().slice(0, 200)) {
+    try {
+      // Recheck parents at the time of hashing, rather than relying on the earlier walk.
+      const resolved = await realpath(path.join(root, file));
+      const relative = path.relative(root, resolved);
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) { matched.delete(file); continue; }
+      const handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        if (!(await handle.stat()).isFile()) { matched.delete(file); continue; }
+        const hash = createHash('sha256');
+        let bytes = 0;
+        for await (const chunk of handle.createReadStream({ autoClose: false })) {
+          bytes += chunk.length;
+          hash.update(chunk);
+        }
+        evidence.push({ path: file, bytes, sha256: hash.digest('hex') });
+      } finally { await handle.close(); }
+    } catch (error) {
+      if (!evidenceUnavailable(error)) throw error;
+      matched.delete(file);
+    }
+  }
+  const missing = patterns.filter((_, i) => ![...matched].some((file) => matchers[i].test(file)));
+  return { evidence, ...(missing.length ? { missing } : {}) };
+}
+
 /**
  * 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).
@@ -55,14 +239,47 @@ function normalizeCommand(command) {
   return { argv: command.argv, failOnStdout: command.failOnStdout === true, env: envOf(command) }; // `env: {}` is no env
 }
 
+/** Interpret timeouts and unanswered prompts for every gate, including repeats.
+ * @param {import('../util/exec.mjs').ExecResult} res
+ * @param {number} timeoutMs
+ * @param {boolean} [failOnStdout]
+ * @returns {Pick<GateResult, 'ok'|'code'|'stdout'|'stderr'|'reason'|'message'>}
+ */
+function gateOutcome(res, timeoutMs, failOnStdout = false) {
+  const prompt = res.result === 'ok' && [res.stdout, res.stderr].some((stream) =>
+    UNANSWERED_PROMPT_PATTERN.test(stream.trimEnd().split(/\r?\n/).at(-1)));
+  const reason = res.timedOut ? 'timeout'
+    : res.code === null ? res.signal ?? (res.error ? 'spawn-error' : 'terminated')
+    : prompt ? 'prompt' : undefined;
+  const diagnostic = res.timedOut
+    ? `gate timeout after ${timeoutMs / 1000} seconds; raise gates.timeout_s (or --timeout-ms)`
+    : res.code === null ? `gate terminated: ${res.signal ?? res.error ?? 'no exit status (no signal reported)'}`
+    : prompt ? 'gate ended on an interactive prompt; install the tool or make the command non-interactive' : '';
+  const tails = ['stdout', 'stderr'].flatMap((stream) => {
+    const tail = res[stream].trimEnd().split(/\r?\n/).slice(-10).join('\n');
+    return tail ? [`${stream} tail:\n${tail}`] : [];
+  });
+  const message = [diagnostic, ...tails].join('\n');
+  return {
+    ok: res.result === 'ok' && !reason && (!failOnStdout || res.stdout.trim().length === 0),
+    code: res.code,
+    stdout: res.stdout,
+    stderr: diagnostic
+      ? `${res.stderr}${res.stderr && !res.stderr.endsWith('\n') ? '\n' : ''}${diagnostic}\n`
+      : res.stderr,
+    ...(reason ? { reason } : {}),
+    ...(diagnostic ? { message } : {}),
+  };
+}
+
 /**
  * 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, repeatNewTests?: RepeatNewTests, lightTestFiles?: string[]}} gates
- * @param {{cwd: string, timeoutMs?: number, scope?: TestScope | import('./expand.mjs').ChangedScope}} opts
- * @returns {Promise<{results: GateResult[], allOk: boolean, repeats?: Repeats}>}
+ * variables added to the inherited environment, overriding the CI=1/npm_config_yes=false defaults.
+ * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate, custom?: CustomGate[], repeatNewTests?: RepeatNewTests, lightTestFiles?: string[], kindGates?: KindGates}} gates
+ * @param {{cwd: string, timeoutMs?: number, scope?: TestScope | import('./expand.mjs').ChangedScope, formatArgvBudgetBytes?: number}} opts - formatArgvBudgetBytes overrides the detected formatter batch budget (default 100 KiB).
+ * @returns {Promise<{results: GateResult[], allOk: boolean, duration_ms: number, repeats?: Repeats}>}
  */
 export async function runGates(gates, opts) {
   if (!gates || typeof gates !== 'object') {
@@ -73,48 +290,80 @@ export async function runGates(gates, opts) {
   if (typeof cwd !== 'string' || cwd.length === 0) {
     throw new TypeError('runGates: opts.cwd must be a non-empty string');
   }
+  const customErrors = customGateMessages(gates.custom);
+  if (customErrors.length > 0) throw new TypeError(customErrors.join('; '));
+  const kindSet = gates.lightTestFiles ? undefined : gates.kindGates;
+  const excluded = (/** @type {string} */ name) => kindSet && !kindSet.names.includes(name);
+  const skipReason = () => /** @type {const} */ (`not in gates.kinds.${kindSet.kind}`);
 
   // 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);
+  for (const gate of gates.custom ?? []) {
+    for (const value of maskableEnvValues({ gate })) 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 planned = [];
+  for (const gate of GATE_ORDER) {
     const command = gates[gate] ?? null;
-    if (command === null) return { gate, command: null };
+    if (command === null || excluded(gate)) { planned.push({ gate, command: null }); continue; }
     const normalized = normalizeCommand(command);
     if (normalized.argv[0] === CHANGED_FILES_TOKEN) throw new TypeError(`gates.${gate}: '{changed_files}' cannot be the command (argv[0])`);
-    const { argv, scoped } = expandArgv(normalized.argv, scope);
+    let { argv, scoped } = expandArgv(normalized.argv, scope);
     if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once ${normalized.argv.map((item) => `'${item}'`).join(' and ')} is dropped for the full suite — put the test command before it`);
-    return { gate, command: { argv, originalArgv: normalized.argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } };
-  });
+    const formatter = gate === 'format' && !Array.isArray(command) ? command.formatter : undefined;
+    let batches;
+    if (formatter) {
+      const files = await formatFiles(cwd, formatter, scope);
+      if (files.length === 0) { planned.push({ gate, command: null, noFiles: true }); continue; }
+      batches = formatBatches(argv, files, opts.formatArgvBudgetBytes ?? FORMAT_ARGV_BUDGET_BYTES);
+      argv = argv.concat(files);
+    }
+    planned.push({ gate, command: { argv, batches, originalArgv: normalized.argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } });
+  }
   /** @type {GateResult[]} */
   const results = [];
-  for (const { gate, command } of planned) {
+  for (const { gate, command, noFiles } of planned) {
     if (command === null) {
-      results.push({ gate, argv: null, skipped: true, ok: true, code: null, stdout: '', stderr: '' });
+      results.push({ gate, duration_ms: 0, argv: null, skipped: true, ok: true, code: null, stdout: '', stderr: '',
+        ...(gates[gate] != null && excluded(gate) ? { reason: skipReason() } : {}),
+        ...(noFiles ? { reason: 'no_changes' } : {}),
+      });
       continue;
     }
-    const { argv, scoped, failOnStdout, env } = command;
+    const { argv, batches = [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, env ? { cwd, timeoutMs, env: { ...process.env, ...env } } : { cwd, timeoutMs });
-    const ok = res.result === 'ok' && (!failOnStdout || res.stdout.trim().length === 0);
+    const execOpts = { cwd, timeoutMs, env: { ...process.env, CI: '1', npm_config_yes: 'false', ...env } };
+    const started = performance.now();
+    const outcomes = [];
+    for (const batch of batches) {
+      const res = await exec(batch, execOpts);
+      const batchOutcome = gateOutcome(res, timeoutMs, failOnStdout);
+      outcomes.push({ ...batchOutcome, ...(batches.length > 1 ? {
+        stdout: outputTail(batchOutcome.stdout), stderr: outputTail(batchOutcome.stderr),
+      } : {}) });
+    }
+    // Retain the first failure's status and diagnostic even if later batches pass.
+    const outcome = {
+      ...(outcomes.find((entry) => !entry.ok) ?? outcomes[0]),
+      stdout: outcomes.map((entry) => entry.stdout).join(''),
+      stderr: outcomes.map((entry) => entry.stderr).join(''),
+    };
     const result = /** @type {GateResult} */ ({
       gate,
+      duration_ms: 0,
       argv,
       skipped: false,
-      ok,
-      code: res.code,
-      stdout: res.stdout,
-      stderr: res.stderr,
       ...(scoped ? scopeFields(scope) : {}),
+      ...outcome,
       ...(env ? { env_keys: Object.keys(env).sort() } : {}),
     });
     const repeat = gates.repeatNewTests;
-    if (gate === 'test' && ok && repeat) {
+    if (gate === 'test' && outcome.ok && repeat) {
       if (!command.originalArgv.includes(TEST_FILES_TOKEN)) {
         repeat.onSkip?.('repeat_new_tests: skipped (gates.test has no {test_files})');
       } else {
@@ -123,19 +372,38 @@ export async function runGates(gates, opts) {
           result.repeats = { n: repeat.n, files, failed: false };
           const repeatArgv = expandArgv(command.originalArgv, { scope: 'related', files }).argv;
           for (let i = 0; i < repeat.n; i++) {
-            const repeated = await exec(repeatArgv, env ? { cwd, timeoutMs, env: { ...process.env, ...env } } : { cwd, timeoutMs });
-            const passed = repeated.result === 'ok' && (!failOnStdout || repeated.stdout.trim().length === 0);
+            const repeated = await exec(repeatArgv, execOpts);
+            const repeatedOutcome = gateOutcome(repeated, timeoutMs, failOnStdout);
             // Keep the first failed run's output, even when a later repeat passes.
-            if (!passed && !result.repeats.failed) {
+            if (!repeatedOutcome.ok && !result.repeats.failed) {
               result.repeats.failed = true;
-              Object.assign(result, { ok: false, reason: 'flaky-test', argv: repeatArgv, code: repeated.code, stdout: repeated.stdout, stderr: repeated.stderr });
+              Object.assign(result, { reason: 'flaky-test', argv: repeatArgv, ...repeatedOutcome });
             }
           }
         }
       }
     }
+    result.duration_ms = Math.round(performance.now() - started);
     results.push(result);
   }
+  for (const gate of gates.custom ?? []) {
+    if (excluded(gate.name)) {
+      results.push({ gate: gate.name, duration_ms: 0, custom: true, argv: null, skipped: true, ok: true, code: null,
+        stdout: '', stderr: '', reason: skipReason(), evidence: [],
+      });
+      continue;
+    }
+    const { argv, env } = normalizeCommand(gate);
+    const started = performance.now();
+    const res = await exec(argv, { cwd, timeoutMs, env: { ...process.env, CI: '1', npm_config_yes: 'false', ...env } });
+    const evidence = await collectEvidence(cwd, gate.evidence ?? []);
+    results.push({ gate: gate.name, custom: true, argv, skipped: false,
+      duration_ms: Math.round(performance.now() - started),
+      ...gateOutcome(res, timeoutMs),
+      ...(env ? { env_keys: Object.keys(env).sort() } : {}),
+      ...evidence,
+    });
+  }
   const repeats = results.find((r) => r.repeats)?.repeats;
-  return { results, allOk: results.every((r) => r.ok), ...(repeats ? { repeats } : {}) };
+  return { results, allOk: results.every((r) => r.ok), duration_ms: results.reduce((sum, r) => sum + r.duration_ms, 0), ...(repeats ? { repeats } : {}) };
 }

package/src/ledger/export.mjs

@@ -1,5 +1,5 @@
 /**
- * `report --export <dir>` — writes one JSON file per report section (plan §6.2; 15 sections since B124b).
+ * `report --export <dir>` — writes one JSON file per report section (plan §6.2; 17 sections since B154).
  */
 
 import { mkdir, writeFile } from 'node:fs/promises';

package/src/ledger/report.mjs

@@ -1,5 +1,5 @@
 /**
- * `code-forge report` (plan §6.2, R4): builds the 15 report sections from a run's ledger rows.
+ * `code-forge report` (plan §6.2, R4): builds the report sections from a project'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
@@ -80,19 +80,42 @@ export function buildRunModes(rows) {
   return runs.map((run) => ({ run, mode: brief.has(run) ? 'brief' : 'plan' }));
 }
 
+/** A full ISO timestamp with a timezone; reject coerced values and impossible calendar dates.
+ * @param {unknown} ts @returns {string | null} */
+function timestamp(ts) {
+  if (typeof ts !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(ts)
+    || !Number.isFinite(Date.parse(ts))) return null;
+  const day = ts.slice(0, 10);
+  const date = Date.parse(`${day}T00:00:00.000Z`);
+  return Number.isFinite(date) && new Date(date).toISOString().slice(0, 10) === day ? ts : null;
+}
+
+/** Missing or reversed endpoints cannot establish elapsed time.
+ * @param {string | null} start @param {string | null} end @returns {number | null} */
+function elapsed(start, end) {
+  if (start === null || end === null) return null;
+  const ms = Date.parse(end) - Date.parse(start);
+  return ms >= 0 ? ms : null;
+}
+
 /**
  * Cost per block — completed AND still open (B33: a running total while the block is open):
- * review $ / coder $ / S1+S2 $ / facts $ / proof ms, `completed` (code close with no pending human check) and
+ * review $ / coder $ / S1+S2 $ / facts $ / proof ms, measured gate/review ms,
+ * `completed` (code close with no pending human check) and
  * `unknownUsdSessions` (spend rows whose price is unknown, counted 0 in the totals). Grouped by
  * run + block, so a block id reused in a second run is its own entry; a row without a run joins
  * the entry of its block when that block id appears in exactly one run (else a `run: null` entry); shadow rows are dropped here too, exactly as `buildSpend` does. An entry is listed
- * once it has a spend row or a `block.close` row.
+ * once it has a spend row, a `block.close` row, or is stopped (`stopped: true`, omitted otherwise).
  */
 function costPerBlock(rows) {
   /** @type {Map<string, any>} */
   const byBlock = new Map();
+  /** @type {Map<string, {firstDispatch: string | null, completion: string | null, stopped: string | null, awaiting: string | null, humanWait: number | null}>} */
+  const times = new Map();
   /** @type {Set<string>} run+block keys with at least one spend row */
   const spent = new Set();
+  const gated = new Set();
+  const reviewed = new Set();
   const closedKeys = new Set();
   // never split one block: a row without a run joins its block's entry when that block id appears
   // in exactly one run; only a block seen in several runs leaves such a row in a `run: null` entry
@@ -126,18 +149,52 @@ function costPerBlock(rows) {
         factsUsd: 0,
         otherUsd: 0,
         proofTimeMs: 0,
+        wallMs: null,
+        humanWaitMs: null,
         totalUsd: 0,
         unknownUsdSessions: 0,
       });
+      times.set(key, { firstDispatch: null, completion: null, stopped: null, awaiting: null, humanWait: null });
     }
     const e = byBlock.get(key);
+    const time = times.get(key);
+    if (['dispatch', 'block.close', 'block.awaiting_human_check', 'block.human_pass'].includes(row.event)) {
+      delete e.stopped;
+      time.stopped = null;
+    }
     if (row.event === 'dispatch') {
       e.level = row.level ?? e.level;
       e.lane = row.lane ?? e.lane;
+      e.completed = false;
     }
     if (row.event === 'block.close') { e.completed = true; closedKeys.add(key); }
     if (row.event === 'block.awaiting_human_check') e.completed = false;
     if (row.event === 'block.human_pass') e.completed = true;
+    if (row.event === 'block.stop') { e.completed = false; e.stopped = true; }
+    // Invalid timestamps have no effect on time; lifecycle and spend still count normally.
+    const ts = timestamp(row.ts);
+    if (ts !== null) {
+      if (row.event === 'dispatch') {
+        time.firstDispatch ??= ts;
+        time.completion = null;
+        time.awaiting = null;
+        time.humanWait = null;
+      }
+      if (row.event === 'block.close') {
+        time.completion = ts;
+        time.humanWait = null;
+      }
+      if (row.event === 'block.awaiting_human_check') {
+        time.awaiting = ts;
+        time.completion = null;
+        time.humanWait = null;
+      }
+      if (row.event === 'block.human_pass') {
+        time.completion = ts;
+        time.humanWait = elapsed(time.awaiting, ts);
+      }
+      if (row.event === 'block.stop') time.stopped = ts;
+    }
     if (isSpendRow(row)) {
       spent.add(key);
       const cost = sessionCostUsd(row);
@@ -153,14 +210,73 @@ function costPerBlock(rows) {
       }
     }
     if (row.event === 'proof' && typeof row.duration_ms === 'number') e.proofTimeMs += row.duration_ms;
+    // gate.red is a diagnostic for a command already included in gate.done's total.
+    // Leave legacy entries without a gateTimeMs field when no measured run is available.
+    if (row.event === 'gate.done' && typeof row.duration_ms === 'number' && Number.isFinite(row.duration_ms) && row.duration_ms >= 0) {
+      e.gateTimeMs = (e.gateTimeMs ?? 0) + row.duration_ms;
+      gated.add(key);
+    }
+    if (row.event === 'review.result' && typeof row.duration_ms === 'number' && Number.isFinite(row.duration_ms) && row.duration_ms >= 0) {
+      e.reviewTimeMs = (e.reviewTimeMs ?? 0) + row.duration_ms;
+      reviewed.add(key);
+    }
   }
-  const out = [...byBlock.entries()].filter(([key, e]) => e.completed || spent.has(key) || closedKeys.has(key)).map(([, e]) => e);
+  const out = [...byBlock.entries()].filter(([key, e]) => e.completed || e.stopped || spent.has(key) || gated.has(key) || reviewed.has(key) || closedKeys.has(key)).map(([key, e]) => {
+    const time = times.get(key);
+    if (e.completed) {
+      e.wallMs = elapsed(time.firstDispatch, time.completion);
+      e.humanWaitMs = time.humanWait;
+    }
+    if (e.stopped) e.wallMs = elapsed(time.firstDispatch, time.stopped);
+    return e;
+  });
   for (const e of out) {
     for (const k of ['reviewUsd', 'coderUsd', 's1s2Usd', 'factsUsd', 'otherUsd', 'totalUsd']) e[k] = Math.round(e[k] * 10000) / 10000;
   }
   return out;
 }
 
+/** Per-run wall time, spend and distinct block counts, plus the ledger/site total.
+ * Rows and costs have already had shadow rows removed. Untimed runs contribute 0 to total wallMs.
+ * Rows without string run ids go to outside_runs; total.usd includes outside_runs.usd.
+ * @param {Array<Record<string, any>>} rows @param {any[]} costs */
+function runTime(rows, costs) {
+  /** @type {Map<string, Array<Record<string, any>>>} */
+  const groups = new Map();
+  const outside = [];
+  for (const row of rows) {
+    if (typeof row.run !== 'string') { outside.push(row); continue; }
+    const run = row.run;
+    if (!groups.has(run)) groups.set(run, []);
+    groups.get(run).push(row);
+  }
+  const spend = new Map(spendByRun(rows).map((r) => [r.run, r.usd]));
+  const runs = [...groups].map(([run, list]) => {
+    const timed = list.filter((r) => timestamp(r.ts) !== null);
+    const started = timed.find((r) => r.event === 'run.start')?.ts ?? timed[0]?.ts ?? null;
+    const ended = timed.filter((r) => r.event === 'run.end').at(-1)?.ts ?? null;
+    const open = ended === null;
+    return {
+      run, started, ended,
+      wallMs: elapsed(started, open ? timed.at(-1)?.ts ?? null : ended),
+      usd: spend.get(run) ?? 0,
+      blocks_closed: costs.filter((b) => b.run === run && b.completed).length,
+      blocks_stopped: new Set(list.filter((r) => r.event === 'block.stop' && r.block).map((r) => r.block)).size,
+      ...(open ? { open: true } : {}),
+    };
+  });
+  return {
+    runs,
+    ...(outside.length ? { outside_runs: { usd: sumSpend(outside).usd, rows: outside.length } } : {}),
+    total: {
+      runs: runs.length,
+      wallMs: runs.reduce((sum, r) => sum + (r.wallMs ?? 0), 0),
+      usd: sumSpend(rows).usd,
+      blocks_closed: runs.reduce((sum, r) => sum + r.blocks_closed, 0),
+    },
+  };
+}
+
 const laneDistribution = (rows) =>
   rows.filter((r) => r.event === 'dispatch').map((r) => ({ block: r.block, lanePicked: r.lane ?? null, levelOpened: r.level ?? null }));
 
@@ -274,8 +390,26 @@ const runStopCounts = (rows) => ({
   noEngineStops: rows.filter((r) => r.event === 'run.stop' && r.reason === 'no_engine').length,
 });
 
+/** Specialist deliverables are separate from calibration's `outcome` events.
+ * @param {import('./write.mjs').LedgerRow[]} rows
+ */
+function specialistOutcomes(rows) {
+  const outcomes = rows.filter((r) => r.event === 'outcome.recorded').map((r) => ({
+    skill: r.skill, step: r.step ?? null, status: r.status,
+    cost_usd: r.cost_usd ?? null, minutes: r.minutes ?? null,
+  }));
+  return {
+    outcomes,
+    total: {
+      count: outcomes.length,
+      cost_usd: outcomes.reduce((sum, r) => sum + (r.cost_usd ?? 0), 0),
+      minutes: outcomes.reduce((sum, r) => sum + (r.minutes ?? 0), 0),
+    },
+  };
+}
+
 /** The exact, ordered set of section keys `buildReport` produces (plan §6.2; B66 appended
- * `outside_review`, then B124b appended `agent_waivers` — append new sections, never reorder) —
+ * `outside_review`, B124b `agent_waivers`, B147 `run_time`, B154 `specialist_outcomes` — 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',
@@ -293,6 +427,8 @@ export const SECTION_NAMES = Object.freeze([
   'run_stop_counts',
   'outside_review',
   'agent_waivers',
+  'run_time',
+  'specialist_outcomes',
 ]);
 
 /**
@@ -325,6 +461,8 @@ export function buildReport(rows) {
         unwaived: r.slice(i + 1).some((undo) => undo.event === 'review.unwaived' && undo.by === 'human'
           && undo.run === row.run && undo.block === row.block && undo.file === row.file && undo.finding === row.finding) }]
       : []),
+    run_time: (/** @type {any[]} */ r) => runTime(r, costs),
+    specialist_outcomes: specialistOutcomes,
   };
   /** @type {Record<string, any>} */
   const sections = {};