mandrel 2.67.0 → 2.69.0

package/.agents/scripts/lib/baselines/crap-updater-cli.js

@@ -6,9 +6,17 @@
  */
 
 import path from 'node:path';
+import { getBaselines, getQuality, resolveConfig } from '../config-resolver.js';
+import { isCoverageFresh } from '../coverage-capture.js';
+import { loadCoverage as loadCoverageDefault } from '../coverage-utils.js';
 import { checkResolutionFloor, scanAndScore } from '../crap-utils.js';
 import { Logger } from '../Logger.js';
 import { parseDiffScopeFlag } from './diff-scope-cli.js';
+import {
+  checkSeatResolution,
+  runSeatMissing,
+  SeatRefusal,
+} from './seat-missing.js';
 
 const DEFAULT_COVERAGE_PATH = 'coverage/coverage-final.json';
 
@@ -20,7 +28,7 @@ const DEFAULT_MIN_RESOLUTION_RATE = 0.75;
  *
  * @param {string[]} [argv]
  * @returns {{baselinePath: string|undefined, coveragePath: string|undefined,
- *   fullScope: boolean, diffScopeRef: string|null}}
+ *   fullScope: boolean, diffScopeRef: string|null, seatMissing: boolean}}
  */
 export function parseCrapUpdaterArgs(argv = []) {
   const out = {
@@ -28,6 +36,7 @@ export function parseCrapUpdaterArgs(argv = []) {
     coveragePath: undefined,
     fullScope: false,
     diffScopeRef: parseDiffScopeFlag(argv),
+    seatMissing: argv.includes('--seat-missing'),
   };
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--baseline' && argv[i + 1]) {
@@ -45,16 +54,17 @@ export function parseCrapUpdaterArgs(argv = []) {
 
 /**
  * Flag → config → default. Throws on `--full-scope` with `--diff-scope`:
- * silently preferring one would write a baseline nobody asked for.
+ * silently preferring one would write a baseline nobody asked for
+ * (`runSeatMissing` refuses the `--seat-missing` pairing).
  *
  * @param {{baselinePath?: string, coveragePath?: string, fullScope?: boolean,
- *   diffScopeRef?: string|null}} args
+ *   diffScopeRef?: string|null, seatMissing?: boolean}} args
  * @param {{crap?: object, baselines?: object}} sources
  * @param {string} [cwd]
  * @returns {{targetDirs: string[], ignoreGlobs: string[],
  *   requireCoverage: boolean, minMethodResolutionRate: number,
  *   coveragePath: string, baselinePath: string, absBaselinePath: string,
- *   fullScope: boolean, diffScopeRef: string|null}}
+ *   fullScope: boolean, diffScopeRef: string|null, seatMissing: boolean}}
  */
 export function resolveCrapUpdaterOptions(
   args = {},
@@ -82,6 +92,7 @@ export function resolveCrapUpdaterOptions(
       : path.resolve(cwd, baselinePath),
     fullScope: Boolean(args.fullScope),
     diffScopeRef: args.diffScopeRef ?? null,
+    seatMissing: Boolean(args.seatMissing),
   };
 }
 
@@ -172,3 +183,89 @@ export function buildCrapUpdaterScorer(
     );
   };
 }
+
+/** Stamp scopes a capture may have written; any one fresh stamp suffices. */
+const CAPTURE_SCOPES = ['full', 'incremental', 'affected'];
+
+/**
+ * The `--seat-missing` scorer: refuses (throws {@link SeatRefusal}) unless
+ * the coverage artifact is fresh for the current tree and every in-scope
+ * method resolved a coverage entry — a wrong-coordinate row stays wrong even
+ * when it is only inserted.
+ *
+ * @param {ReturnType<typeof resolveCrapUpdaterOptions>} options
+ * @param {{loadCoverage: Function, scan?: Function, isFresh?: Function,
+ *   cwd?: string, logger?: object}} deps
+ * @returns {(files: string[]) => Promise<object[]>}
+ */
+export function buildCrapSeatScorer(
+  options,
+  {
+    loadCoverage,
+    scan = scanAndScore,
+    isFresh = isCoverageFresh,
+    cwd = process.cwd(),
+    logger = Logger,
+  } = {},
+) {
+  const fixCommand = `node .agents/scripts/coverage-capture.js --cwd ${cwd}`;
+  return async (files) => {
+    const fresh = CAPTURE_SCOPES.some(
+      (requireScope) =>
+        isFresh({
+          coveragePath: options.coveragePath,
+          targetDirs: options.targetDirs,
+          cwd,
+          requireScope,
+        }).fresh,
+    );
+    const coverage = fresh
+      ? loadCoverage(path.resolve(cwd, options.coveragePath))
+      : null;
+    if (!coverage) {
+      throw new SeatRefusal(
+        `[CRAP] --seat-missing refused: no coverage artifact at ${options.coveragePath} is fresh for the current tree ` +
+          `(method resolution unmeasured; unresolved files: ${files.join(', ')}).\n` +
+          `Fix: re-capture coverage for the current tree — ${fixCommand}`,
+      );
+    }
+    const summary = await scan({
+      targetDirs: options.targetDirs,
+      coverage,
+      requireCoverage: options.requireCoverage,
+      cwd,
+      ignoreGlobs: options.ignoreGlobs,
+      scopeFiles: files,
+    });
+    reportScanSummary(summary, logger);
+    const refusal = checkSeatResolution(summary.resolution, fixCommand);
+    if (refusal) throw new SeatRefusal(refusal);
+    return (summary.rows ?? []).filter(
+      (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
+    );
+  };
+}
+
+/**
+ * `update-crap-baseline.js --seat-missing`: seat the diff's new methods
+ * through {@link buildCrapSeatScorer}. Resolves to the exit code.
+ *
+ * @param {string[]} argv
+ * @param {{config?: object}} [deps]
+ * @returns {Promise<number>}
+ */
+export function seatCrapBaseline(argv, { config = resolveConfig() } = {}) {
+  const options = resolveCrapUpdaterOptions(parseCrapUpdaterArgs(argv), {
+    crap: getQuality(config).crap,
+    baselines: getBaselines(config),
+  });
+  return runSeatMissing({
+    kind: 'crap',
+    label: 'CRAP',
+    writePath: options.absBaselinePath,
+    diffScopeRef: options.diffScopeRef,
+    fullScope: options.fullScope,
+    baseBranch: config.project.baseBranch,
+    score: buildCrapSeatScorer(options, { loadCoverage: loadCoverageDefault }),
+  });
+}

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -507,7 +507,7 @@ async function resolveScope({
  * @param {typeof nodeFs} fs
  * @returns {object | null}
  */
-function readPriorEnvelope(writePath, fs) {
+export function readPriorEnvelope(writePath, fs) {
   let raw;
   try {
     raw = fs.readFileSync(writePath, 'utf8');

package/.agents/scripts/lib/baselines/seat-missing.js

@@ -0,0 +1,228 @@
+/**
+ * Insert-only baseline seating (`--seat-missing`): write ONLY rows whose seat
+ * key is absent from the committed baseline; prior rows keep their parsed
+ * objects, so they serialise byte-identically. The CRAP key is
+ * `path::method` — the gate matches a moved method by name, so it is not
+ * missing.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { execFileCaptureAsync } from '../child-exec.js';
+import { getBaselines, resolveConfig } from '../config-resolver.js';
+import { Logger } from '../Logger.js';
+import { parseDiffScopeFlag } from './diff-scope-cli.js';
+import { assertEnvelope } from './envelope.js';
+import { getKindModule } from './kernel.js';
+import { canonicalizeBaselinePath } from './path-canon.js';
+import {
+  deriveScopeFromDiff,
+  fileFilterFor,
+  readPriorEnvelope,
+  resolveDefaultScorer,
+} from './refresh-service.js';
+import {
+  write as writeEnvelope,
+  writeFile as writeEnvelopeFile,
+} from './writer.js';
+
+/** Thrown when a seat must not write; the CLI prints `message` and exits 1. */
+export class SeatRefusal extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SeatRefusal';
+  }
+}
+
+const SEAT_KEYS = Object.freeze({
+  crap: (row) => `${row.path}::${row.method}`,
+  maintainability: (row) => row.path,
+});
+
+/**
+ * @param {string} kind
+ * @returns {(row: object) => string}
+ */
+export function seatKeyFor(kind) {
+  const key = SEAT_KEYS[kind];
+  if (!key) throw new Error(`seat-missing: unsupported kind "${kind}"`);
+  return key;
+}
+
+/**
+ * Candidate rows whose seat key no prior row carries. Pure.
+ *
+ * @param {{kind: string, priorRows: object[], candidateRows: object[]}} args
+ * @returns {object[]}
+ */
+export function selectMissingRows({ kind, priorRows, candidateRows }) {
+  const key = seatKeyFor(kind);
+  const present = new Set((priorRows ?? []).map(key));
+  return (candidateRows ?? []).filter((row) => !present.has(key(row)));
+}
+
+/**
+ * The CRAP seat's fail-closed precondition: every joinable method in scope
+ * resolved a coverage entry. Returns the refusal text, or `null` to proceed.
+ * Anything below 100% means the artifact's coordinates predate the tree.
+ *
+ * @param {{resolvedMethods?: number, joinableMethods?: number, rate?: number,
+ *   worstFiles?: Array<{file: string, unresolved: number, total: number}>}
+ *   | undefined} resolution
+ * @param {string} fixCommand
+ * @returns {string|null}
+ */
+export function checkSeatResolution(resolution, fixCommand) {
+  const { joinableMethods = 0, resolvedMethods = 0 } = resolution ?? {};
+  if (resolvedMethods >= joinableMethods) return null;
+  const rate = ((resolvedMethods / joinableMethods) * 100).toFixed(1);
+  const files = (resolution.worstFiles ?? [])
+    .map((w) => `  - ${w.file} (${w.unresolved}/${w.total} unresolved)`)
+    .join('\n');
+  return (
+    `[CRAP] --seat-missing refused: method resolution ${resolvedMethods}/${joinableMethods} ` +
+    `(${rate}%) over the in-scope files; seating requires 100%.\n` +
+    (files ? `Unresolved files:\n${files}\n` : '') +
+    `Fix: re-capture coverage for the current tree — ${fixCommand}`
+  );
+}
+
+/**
+ * Three-dot range (from the merge-base): the files this branch changed.
+ *
+ * @param {{baseRef: string, headRef: string, cwd: string}} args
+ * @returns {Promise<string[]>}
+ */
+async function mergeBaseGitDiff({ baseRef, headRef, cwd }) {
+  const { stdout } = await execFileCaptureAsync(
+    'git',
+    ['diff', '--name-only', `${baseRef}...${headRef}`],
+    { cwd },
+  );
+  return stdout.split(/\r?\n/).filter((line) => line.trim().length > 0);
+}
+
+/**
+ * Prior rows are kept as parsed; only the seated rows are projected. With no
+ * prior baseline the writer builds a fresh envelope.
+ */
+function buildSeatedEnvelope({ kind, priorEnvelope, seated }) {
+  if (!priorEnvelope) return writeEnvelope({ kind, rows: seated });
+  const mod = getKindModule(kind);
+  const envelope = {
+    ...priorEnvelope,
+    rows: mod.sortRows([...priorEnvelope.rows, ...seated.map(mod.projectRow)]),
+  };
+  assertEnvelope(envelope);
+  return envelope;
+}
+
+/**
+ * Seat the missing rows of `kind` for the files changed in `baseRef...HEAD`.
+ * `score(files)` may throw a {@link SeatRefusal}. No missing row, no write.
+ *
+ * @param {{kind: string, writePath: string, score: Function, baseRef: string,
+ *   headRef?: string, cwd?: string, gitDiff?: Function, fs?: typeof nodeFs}} opts
+ * @returns {Promise<{seated: number, wrote: boolean, files: string[]}>}
+ */
+export async function seatMissingBaseline({
+  kind,
+  writePath,
+  score,
+  baseRef,
+  headRef = 'HEAD',
+  cwd = process.cwd(),
+  gitDiff = mergeBaseGitDiff,
+  fs = nodeFs,
+}) {
+  const files = await deriveScopeFromDiff({
+    baseRef,
+    headRef,
+    predicate: fileFilterFor(kind),
+    gitDiff,
+    cwd,
+  });
+  if (files.length === 0) return { seated: 0, wrote: false, files };
+
+  const candidateRows = (await score(files)).map((row) => ({
+    ...row,
+    path: canonicalizeBaselinePath(row.path ?? row.file),
+  }));
+  const priorEnvelope = readPriorEnvelope(writePath, fs);
+  const seated = selectMissingRows({
+    kind,
+    priorRows: priorEnvelope?.rows,
+    candidateRows,
+  });
+  if (seated.length === 0) return { seated: 0, wrote: false, files };
+
+  const envelope = buildSeatedEnvelope({ kind, priorEnvelope, seated });
+  writeEnvelopeFile(writePath, envelope, { fsImpl: fs });
+  return { seated: seated.length, wrote: true, files };
+}
+
+/**
+ * The updater CLIs' `--seat-missing` entry: prints `seated: N`; a
+ * {@link SeatRefusal} is an expected outcome, so exit 1 with its message.
+ *
+ * @param {{kind: string, label: string, writePath: string,
+ *   diffScopeRef?: string|null, fullScope?: boolean, baseBranch?: string,
+ *   score?: Function, cwd?: string, logger?: object, seat?: Function}} opts
+ * @returns {Promise<number>} The exit code.
+ */
+export async function runSeatMissing({
+  kind,
+  label,
+  writePath,
+  diffScopeRef = null,
+  fullScope = false,
+  baseBranch = 'main',
+  score,
+  cwd = process.cwd(),
+  logger = Logger,
+  seat = seatMissingBaseline,
+}) {
+  if (fullScope) {
+    throw new Error(
+      `[${label}] --full-scope is incompatible with --seat-missing; pick one`,
+    );
+  }
+  try {
+    const { seated } = await seat({
+      kind,
+      writePath,
+      baseRef: diffScopeRef ?? `origin/${baseBranch}`,
+      score: score ?? ((files) => resolveDefaultScorer(kind, { cwd })(files)),
+      cwd,
+    });
+    logger.info(`[${label}] seated: ${seated}`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof SeatRefusal)) throw err;
+    logger.error(err.message);
+    return 1;
+  }
+}
+
+/**
+ * `update-maintainability-baseline.js --seat-missing`. MI is static, so the
+ * default scorer needs no coverage precondition. Resolves to the exit code.
+ *
+ * @param {string[]} argv
+ * @param {{config?: object, cwd?: string}} [deps]
+ * @returns {Promise<number>}
+ */
+export function seatMaintainabilityBaseline(
+  argv,
+  { config = resolveConfig(), cwd = process.cwd() } = {},
+) {
+  return runSeatMissing({
+    kind: 'maintainability',
+    label: 'Maintainability',
+    writePath: path.resolve(cwd, getBaselines(config).maintainability.path),
+    diffScopeRef: parseDiffScopeFlag(argv),
+    fullScope: argv.includes('--full-scope'),
+    baseBranch: config.project.baseBranch,
+    cwd,
+  });
+}

package/.agents/scripts/lib/child-exec.js

@@ -101,7 +101,10 @@ export function spawnChild(file, args, opts = {}) {
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
 export function spawnCapture(file, args, opts = {}) {
-  const result = spawnChild(file, args, opts);
+  return normalizeCapture(spawnChild(file, args, opts));
+}
+
+function normalizeCapture(result) {
   return {
     status: result?.status ?? 1,
     stdout: (result?.stdout ?? '').toString().trim(),
@@ -109,6 +112,41 @@ export function spawnCapture(file, args, opts = {}) {
   };
 }
 
+/**
+ * The async runner behind `spawnCaptureAsync`: `input` rides stdin; a
+ * timeout, overflow or spawn error resolves with a non-numeric status.
+ *
+ * @returns {Promise<{ status: number|null, stdout: string, stderr: string }>}
+ */
+function execCollect(file, args, { input, ...options }) {
+  return new Promise((resolve) => {
+    const child = execFile(file, args, options, (error, stdout, stderr) => {
+      const code = error ? error.code : 0;
+      const status = Number.isInteger(code) ? code : null;
+      const reason = status === null ? error.message : '';
+      resolve({ status, stdout, stderr: stderr || reason });
+    });
+    child.stdin?.on('error', () => {});
+    child.stdin?.end(input ?? '');
+  });
+}
+
+/**
+ * `spawnCapture` without blocking the event loop: concurrent children keep
+ * draining while this one runs. Same normalisation (`null` → 1, trimmed).
+ *
+ * @param {string}   file
+ * @param {string[]} args
+ * @param {object}   [opts]
+ * @param {Function} [opts.run] - async (or sync) `(file, args, options)` seam.
+ * @returns {Promise<{ status: number, stdout: string, stderr: string }>}
+ */
+export async function spawnCaptureAsync(file, args, opts = {}) {
+  return normalizeCapture(
+    await spawnChild(file, args, { run: execCollect, ...opts }),
+  );
+}
+
 /**
  * `status=null` is printed verbatim: it means the child was killed.
  *

package/.agents/scripts/lib/close-validation/gates.js

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 
 import { _internals as baselineReaderInternals } from '../baselines/reader.js';
 import { getChangedFiles } from '../changed-files.js';
-import { getQuality } from '../config/quality.js';
+import { COVERAGE_GATE_DEFAULTS, getQuality } from '../config/quality.js';
 import { filterFilesUnderTargets } from '../coverage-capture.js';
 import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
 import { KNOWN_KINDS } from '../orchestration/check-baselines/phases/parse-args.js';
@@ -290,41 +290,75 @@ function coverageCaptureRunsSuite({
   return coverageCaptureActive && !captureSkipPredicted && !testCredited;
 }
 
+/**
+ * Names every suite the capture can run: under `captureScope: "affected"` a
+ * red may come from a delta refresh the base-sync triggered, not the Story.
+ */
+const COVERAGE_CAPTURE_HINT =
+  'Coverage capture failed — its suite run (`npm run test:coverage`, or `npm run test:coverage:affected` under `captureScope: "affected"`, including a delta refresh keyed on the stamped commit after a base-sync) exited non-zero. The coverage-capture log names which ran; fix the failing tests or coverage-threshold breaches, then re-run close.';
+
 const COVERAGE_CAPTURE_ARGS = Object.freeze([
   '.agents/scripts/coverage-capture.js',
 ]);
 
-/** The close gate that replays the `pre-push` hook's CRAP-scope preview. */
-const QUALITY_PREVIEW_GATE_NAME = 'quality-preview';
+/**
+ * The `pre-push` hook's quality preview, split at close into its two halves.
+ * The MI half needs no coverage artifact, so it fails in the parallel phase;
+ * the CRAP half stays serial behind coverage-capture. Every name MUST be in
+ * the `gateName` enum of `validation-evidence.schema.json`.
+ */
+const QUALITY_PREVIEW_GATE_NAMES = Object.freeze({
+  maintainability: 'quality-preview-mi',
+  crap: 'quality-preview-crap',
+});
 
-const QUALITY_PREVIEW_HINT =
-  "Quality preview failed — the same per-file maintainability / CRAP check the `pre-push` hook runs, scored against the base branch. Reduce the flagged methods' complexity or cover them, then re-run close; a close that skipped this gate would have died at push instead.";
+const QUALITY_PREVIEW_HINTS = Object.freeze({
+  maintainability:
+    'Maintainability preview failed — the per-file MI check the `pre-push` hook runs, scored against the base branch. Simplify the flagged file(s), then re-run close; this gate runs before coverage-capture, so no suite was spent.',
+  crap: "CRAP preview failed — the per-file CRAP check the `pre-push` hook runs, scored against the base branch and the fresh coverage artifact. Reduce the flagged methods' complexity or cover them, then re-run close; a close that skipped this gate would have died at push instead.",
+});
 
 /**
- * Replays the `pre-push` CRAP-scope preview so its breach fails close, not
- * the push. Registered exactly when coverage-capture is, and after it, so it
- * scores a fresh artifact.
+ * Replays the `pre-push` quality preview as two single-half gates, so an MI
+ * breach fails close before the suite runs and a CRAP breach fails it, not
+ * the push. Registered exactly when coverage-capture is.
  *
  * @param {{ coverageCaptureActive: boolean, baseBranch?: string }} opts
- * @returns {Gate[]}
+ * @returns {{ maintainability: Gate[], crap: Gate[] }}
  */
-function buildQualityPreviewGateEntry({ coverageCaptureActive, baseBranch }) {
-  if (!coverageCaptureActive) return [];
+function buildQualityPreviewGateEntries({ coverageCaptureActive, baseBranch }) {
+  if (!coverageCaptureActive) return { maintainability: [], crap: [] };
   const ref = `origin/${baseBranch || 'main'}`;
-  return [
+  const entry = (half, only) => [
     {
-      name: QUALITY_PREVIEW_GATE_NAME,
+      name: QUALITY_PREVIEW_GATE_NAMES[half],
       cmd: 'node',
-      args: ['.agents/scripts/quality-preview.js', '--changed-since', ref],
-      hint: QUALITY_PREVIEW_HINT,
+      args: [
+        '.agents/scripts/quality-preview.js',
+        '--only',
+        only,
+        '--changed-since',
+        ref,
+      ],
+      hint: QUALITY_PREVIEW_HINTS[half],
     },
   ];
+  return {
+    maintainability: entry('maintainability', 'mi'),
+    crap: entry('crap', 'crap'),
+  };
 }
 
+/**
+ * Shown instead of a gate's own hint when it exits `COVERAGE_TIMEOUT_EXIT_CODE`
+ * — a killed suite, not a failing one.
+ */
+export const GATE_TIMEOUT_HINT = `The gate outran the suite timeout (\`delivery.quality.gates.coverage.timeoutMs\`, default ${COVERAGE_GATE_DEFAULTS.timeoutMs} ms — raise it for a slow or shared host) and its process group was killed — no test verdict exists. This is usually host contention (sibling suites or a peer close sharing the machine), not a failing test: re-run close once the host is quieter.`;
+
 /**
  * Build the close-validation gate list, cheapest fast-fail first: typecheck →
- * lint → [test] → format → [coverage-capture → quality-preview] →
- * check-baselines. Coverage-capture registers only when CRAP is enabled AND a
+ * lint → [test] → format → [quality-preview-mi] → [coverage-capture →
+ * quality-preview-crap] → check-baselines. Coverage-capture registers only when CRAP is enabled AND a
  * `test:coverage` script exists; it then carries test-failure signalling and
  * the plain `test` gate is dropped, so there is always exactly one test gate.
  *
@@ -392,6 +426,10 @@ export function buildDefaultGates({
     enabledKinds: baselineKinds,
     presentBaselines,
   });
+  const qualityPreview = buildQualityPreviewGateEntries({
+    coverageCaptureActive,
+    baseBranch,
+  });
   if (!baselinesDecision.register && baselinesDecision.reason) {
     log?.(`[close-validation] ${baselinesDecision.reason}`);
   }
@@ -421,20 +459,21 @@ export function buildDefaultGates({
         ? { changedFileScope: formatChangedFileScope }
         : {}),
     },
+    ...qualityPreview.maintainability,
     ...(coverageCaptureActive
       ? [
           {
             name: 'coverage-capture',
             cmd: 'node',
             args: [...COVERAGE_CAPTURE_ARGS],
-            hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
+            hint: COVERAGE_CAPTURE_HINT,
             ...(captureSkipPredicted
               ? { skip: { reason: 'incremental-no-crap-changes' } }
               : {}),
           },
         ]
       : []),
-    ...buildQualityPreviewGateEntry({ coverageCaptureActive, baseBranch }),
+    ...qualityPreview.crap,
     ...buildBaselinesGateEntries({
       decision: baselinesDecision,
       kinds: baselineKinds,
@@ -459,6 +498,7 @@ const INDEPENDENT_GATE_NAMES = new Set([
   'format',
   'typecheck',
   BASELINES_GATE_NAMES.independent,
+  QUALITY_PREVIEW_GATE_NAMES.maintainability,
 ]);
 
 /**

package/.agents/scripts/lib/close-validation/process.js

@@ -4,13 +4,11 @@ import { spawn } from 'node:child_process';
 
 import {
   LOCK_WAIT_EXPIRED_EXIT_CODE,
+  resolveFullSuiteLockBudget,
   withFullSuiteLockAsync,
 } from '../full-suite-lock.js';
-import {
-  groupSpawnOptions,
-  superviseGroup,
-  TIMEOUT_EXIT_CODE,
-} from '../process-group.js';
+import { groupSpawnOptions, TIMEOUT_EXIT_CODE } from '../process-group.js';
+import { gateSupervision } from '../supervised-suite.js';
 
 /**
  * Emit each line with `prefix`; the unterminated tail flushes on `end`.
@@ -80,31 +78,35 @@ function isBiomeNoFilesProcessed(output) {
  *
  * `fullSuiteLock` serializes the spawn behind the host lock (async, so
  * sibling gates on this event loop are not stalled). An expired wait spawns
- * anyway unless `deferOnLockExpiry`, which returns
- * `LOCK_WAIT_EXPIRED_EXIT_CODE` so close ends `pending`. Each child leads its
- * own process group so a timeout, abort or parent signal kills its workers too.
+ * nothing and returns `LOCK_WAIT_EXPIRED_EXIT_CODE`, so close ends
+ * `pending`. A full-suite gate's timeout is armed at spawn, re-armed on the
+ * suite-ready handshake, and its lock wait, host wait and test run are logged
+ * as three figures. Each child leads its own process group so a timeout,
+ * abort or parent signal kills its workers too.
  *
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, deferOnLockExpiry?: boolean, timeoutMs?: number, lockOptions?: object, skipIfSatisfied?: () => {status: number}|undefined }} opts
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, timeoutMs?: number, lockOptions?: object, skipIfSatisfied?: () => {status: number}|undefined }} opts
  * @returns {Promise<{ status: number }>}
  */
 export function defaultGateRunner(cmd, args, opts = {}) {
   if (!opts.fullSuiteLock) return spawnGate(cmd, args, opts);
   // `skipIfSatisfied` re-probes after the wait: evidence another suite
   // deposited meanwhile is returned instead of spawning.
-  return withFullSuiteLockAsync(gateLockOptions(opts), () =>
-    spawnGate(cmd, args, opts),
+  return withFullSuiteLockAsync(gateLockOptions(opts), (lock) =>
+    spawnGate(cmd, args, opts, lock),
   );
 }
 
+/** The wait is bounded by the same kill bound that bounds the holder. */
 function gateLockOptions(opts) {
   return {
+    ...resolveFullSuiteLockBudget(opts.timeoutMs),
     cwd: opts.cwd,
     log: opts.log,
     skipIfSatisfied: opts.skipIfSatisfied,
-    onWaitExpired: opts.deferOnLockExpiry ? deferredGateStatus : undefined,
-    ...opts.lockOptions, // test seam only
+    onWaitExpired: deferredGateStatus,
+    ...opts.lockOptions, // `rerunCommand`, plus test seams
   };
 }
 
@@ -116,20 +118,16 @@ function deferredGateStatus() {
  * @param {string} cmd
  * @param {string[]} args
  * @param {Parameters<typeof defaultGateRunner>[2]} opts
+ * @param {{ lockWaitMs?: number }} [lock] How long the full-suite lock queued it.
  * @returns {Promise<{ status: number }>}
  */
-function spawnGate(cmd, args, opts) {
-  const child = spawnGateChild(cmd, args, opts);
+function spawnGate(cmd, args, opts, lock) {
+  const supervision = gateSupervision(opts, lock);
+  const child = spawnGateChild(cmd, args, opts.cwd, supervision.env);
   const output = gateOutput(opts);
   pipePrefixed(child.stdout, output.prefix, output.tap);
   pipePrefixed(child.stderr, output.prefix, output.tap);
-  // A bare suite has nothing to clean up, so it gets SIGKILL; other gates
-  // (a capture holding the lock) get SIGTERM to release and kill their suite.
-  const supervisor = superviseGroup(child, {
-    timeoutMs: opts.timeoutMs,
-    abortSignal: opts.signal,
-    signalOnParentSignal: opts.fullSuiteLock ? 'SIGKILL' : 'SIGTERM',
-  });
+  const supervisor = supervision.supervise(child, output);
   return new Promise((resolve) => {
     // 'close', not 'exit': only 'close' waits for both pipes to drain.
     child.on('close', (code, sig) => {
@@ -148,9 +146,10 @@ function spawnGate(cmd, args, opts) {
 /**
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, env?: Record<string, string> }} opts
+ * @param {string} cwd
+ * @param {Record<string, string>} [env]
  */
-function spawnGateChild(cmd, args, { cwd, env }) {
+function spawnGateChild(cmd, args, cwd, env) {
   return spawn(cmd, args, {
     cwd,
     shell: process.platform === 'win32',