mandrel 2.66.0 → 2.68.0

package/.agents/scripts/lib/clean-temp.js

@@ -0,0 +1,440 @@
+/**
+ * `/clean-temp` engine: sorts every top-level entry under the project's
+ * tempRoot into one bucket and, on `--execute`, deletes the confirmed
+ * buckets through the temp-retention engine — there is no second walker.
+ *
+ * Buckets: `framework` (a class entry the auto-purge would take),
+ * `closed-issue` (an unrecognized entry naming exactly one closed issue),
+ * `aged` (an unrecognized id-less entry past `staleDays`), and `kept`.
+ */
+
+import { realpathSync } from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { mainCheckoutRoot, tempRootFrom } from './config/temp-paths.js';
+import { removeSparingKept, safeReaddir } from './temp-removal.js';
+import {
+  collectTempEntries,
+  formatBytes,
+  isReservedTopLevel,
+  resolveTempRetention,
+  sweepTempRetention,
+} from './temp-retention.js';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Deletable buckets, in execution order. `aged` is never deleted under `--yes`. */
+const DELETABLE_BUCKETS = Object.freeze(['framework', 'closed-issue', 'aged']);
+const UNATTENDED_BUCKETS = Object.freeze(['framework', 'closed-issue']);
+
+/**
+ * A standalone run of 1–7 digits, no leading zero, not glued to a letter or
+ * digit — so a hash fragment, a timestamp or a version suffix is not an id.
+ */
+const ID_TOKEN = /(?<![A-Za-z0-9])[1-9]\d{0,6}(?![A-Za-z0-9])/g;
+
+const silent = Object.freeze({ info: () => {} });
+
+/**
+ * Distinct issue-id candidates in a basename (extension stripped). More than
+ * one means the entry cannot be attributed to any of them.
+ *
+ * @param {string} name
+ * @returns {number[]}
+ */
+function idCandidates(name) {
+  const stem = name.replace(/\.[^.]*$/, '');
+  return [...new Set(stem.match(ID_TOKEN) ?? [])].map(Number);
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ execute: boolean, yes: boolean, json: boolean, cwd: string|undefined }}
+ */
+function parseCleanTempArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      execute: { type: 'boolean', default: false },
+      yes: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      cwd: { type: 'string' },
+    },
+    strict: true,
+  });
+  return values;
+}
+
+/** `realpath` when the path exists, else a plain resolve. */
+function canonical(target) {
+  try {
+    return realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+/**
+ * The tempRoot a relative `project.paths.tempRoot` names, anchored at the
+ * project root, and whether it lies strictly inside that root.
+ *
+ * @param {string} projectRoot
+ * @param {object} config
+ * @returns {{ tempRoot: string, inside: boolean }}
+ */
+function resolveScopedTempRoot(projectRoot, config) {
+  const raw = tempRootFrom(config);
+  const tempRoot = canonical(
+    path.isAbsolute(raw) ? raw : path.join(projectRoot, raw),
+  );
+  const rel = path.relative(canonical(projectRoot), tempRoot);
+  const inside = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  return { tempRoot, inside };
+}
+
+/**
+ * Issue states, read once per id. A failed read is `error`, which every
+ * caller treats as "not closed" — reads fail safe.
+ *
+ * @param {object|null} provider
+ * @param {Iterable<number>} ids
+ * @returns {Promise<Map<number, 'closed'|'open'|'error'>>}
+ */
+async function readIssueStates(provider, ids) {
+  const states = new Map();
+  for (const id of ids) {
+    try {
+      const ticket = await provider.getTicket(id);
+      const state = String(ticket?.state ?? '').toLowerCase();
+      states.set(id, state === 'closed' ? 'closed' : 'open');
+    } catch {
+      states.set(id, 'error');
+    }
+  }
+  return states;
+}
+
+/** Top-level name of `target` beneath `tempRoot`. */
+function topLevelName(tempRoot, target) {
+  return path.relative(tempRoot, target).split(path.sep)[0];
+}
+
+/** Every id the scan could need a state for. */
+function idsToRead(scan) {
+  const ids = new Set();
+  for (const entry of scan.entries) {
+    if (entry.storyId !== null) ids.add(entry.storyId);
+  }
+  for (const u of scan.unrecognized) {
+    const candidates = idCandidates(path.basename(u.path));
+    if (candidates.length === 1) ids.add(candidates[0]);
+  }
+  return ids;
+}
+
+/** Closed ids among `states`. */
+function closedIds(states) {
+  return [...states].filter(([, s]) => s === 'closed').map(([id]) => id);
+}
+
+/**
+ * Bucket one unrecognized entry.
+ *
+ * @param {{ path: string, bytes: number, mtimeMs: number }} u
+ * @param {Map<number, string>} states
+ * @param {{ now: number, staleMs: number }} ctx
+ * @returns {{ bucket: string, reason: string }}
+ */
+function classifyUnrecognized(u, states, ctx) {
+  const ids = idCandidates(path.basename(u.path));
+  if (ids.length === 1) {
+    const state = states.get(ids[0]);
+    if (state === 'closed') {
+      return { bucket: 'closed-issue', reason: `issue #${ids[0]} closed` };
+    }
+    const why = state === 'open' ? 'open' : 'read failed';
+    return { bucket: 'kept', reason: `issue #${ids[0]} ${why}` };
+  }
+  const label = ids.length === 0 ? 'no id' : `${ids.length} ids`;
+  if (ctx.now - u.mtimeMs >= ctx.staleMs) {
+    return { bucket: 'aged', reason: `${label}, past staleDays` };
+  }
+  return { bucket: 'kept', reason: `${label}, too recent` };
+}
+
+/**
+ * One row per top-level entry under tempRoot.
+ *
+ * @param {object} args
+ * @returns {Promise<object[]>}
+ */
+async function buildRows({ tempRoot, scan, preview, states, ctx, fsp }) {
+  const spent = new Map();
+  for (const p of preview.purged) {
+    const name = topLevelName(tempRoot, p.path);
+    const acc = spent.get(name) ?? { count: 0, bytes: 0 };
+    spent.set(name, { count: acc.count + 1, bytes: acc.bytes + p.bytes });
+  }
+  const unrecognized = new Map(
+    scan.unrecognized.map((u) => [path.basename(u.path), u]),
+  );
+  const rows = [];
+  for (const dirent of await safeReaddir(fsp, tempRoot)) {
+    const { name } = dirent;
+    const row = { entry: name, path: path.join(tempRoot, name), bytes: 0 };
+    const u = unrecognized.get(name);
+    if (isReservedTopLevel(name)) {
+      rows.push({ ...row, bucket: 'kept', reason: 'reserved' });
+    } else if (u) {
+      const ageDays = Math.floor((ctx.now - u.mtimeMs) / MS_PER_DAY);
+      rows.push({
+        ...row,
+        bytes: u.bytes,
+        ageDays,
+        ...classifyUnrecognized(u, states, ctx),
+      });
+    } else if (spent.has(name)) {
+      const { count, bytes } = spent.get(name);
+      rows.push({
+        ...row,
+        bytes,
+        bucket: 'framework',
+        reason: `${count} spent artifact(s)`,
+      });
+    } else {
+      rows.push({ ...row, bucket: 'kept', reason: 'framework: nothing spent' });
+    }
+  }
+  return rows.sort((a, b) => a.entry.localeCompare(b.entry));
+}
+
+/**
+ * @param {object[]} rows
+ * @returns {Record<string, { count: number, bytes: number }>}
+ */
+function bucketTotals(rows) {
+  const totals = {};
+  for (const bucket of [...DELETABLE_BUCKETS, 'kept']) {
+    const inBucket = rows.filter((r) => r.bucket === bucket);
+    totals[bucket] = {
+      count: inBucket.length,
+      bytes: inBucket.reduce((sum, r) => sum + r.bytes, 0),
+    };
+  }
+  return totals;
+}
+
+/**
+ * @param {object[]} rows
+ * @returns {string}
+ */
+function renderTable(rows) {
+  const lines = [
+    'bucket        entry                                    size      age   reason',
+  ];
+  for (const r of rows) {
+    const age = r.ageDays === undefined ? '-' : `${r.ageDays}d`;
+    lines.push(
+      `${r.bucket.padEnd(13)} ${r.entry.padEnd(40)} ${formatBytes(r.bytes).padStart(8)} ${age.padStart(5)}   ${r.reason}`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The operator-confirmed deletion of unrecognized entries: each path is
+ * re-verified as still unrecognized by a fresh scan before it goes.
+ *
+ * @param {{ tempRoot: string, paths: string[], fsp: typeof fsPromises }} args
+ * @returns {Promise<{ bytes: number, errors: string[] }>}
+ */
+async function purgeUnrecognizedEntries({ tempRoot, paths, fsp }) {
+  const { unrecognized } = await collectTempEntries({ tempRoot, fsp });
+  const allowed = new Set(unrecognized.map((u) => u.path));
+  const out = { bytes: 0, errors: [] };
+  for (const target of paths) {
+    if (!allowed.has(target)) {
+      out.errors.push(`${target}: no longer an unrecognized entry — kept`);
+      continue;
+    }
+    try {
+      out.bytes += (await removeSparingKept(fsp, target)).bytes;
+    } catch (err) {
+      out.errors.push(`${target}: ${String(err?.message ?? err)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Delete one bucket through the engine.
+ *
+ * @returns {Promise<{ bytes: number, errors: string[] }>}
+ */
+async function executeBucket(bucket, rows, env) {
+  if (bucket === 'framework') {
+    const result = await sweepTempRetention({
+      config: env.config,
+      tempRoot: env.tempRoot,
+      mergedStoryIds: env.closed,
+      now: env.now,
+      fsp: env.fsp,
+      logger: silent,
+      label: 'clean-temp',
+    });
+    return { bytes: result.bytesReclaimed, errors: result.errors };
+  }
+  return purgeUnrecognizedEntries({
+    tempRoot: env.tempRoot,
+    paths: rows.filter((r) => r.bucket === bucket).map((r) => r.path),
+    fsp: env.fsp,
+  });
+}
+
+/**
+ * Decide whether a bucket may be deleted this run.
+ *
+ * @returns {Promise<{ run: boolean, note?: string }>}
+ */
+async function approveBucket(bucket, total, opts, confirm) {
+  if (total.count === 0) return { run: false };
+  if (opts.yes) {
+    return UNATTENDED_BUCKETS.includes(bucket)
+      ? { run: true }
+      : { run: false, note: 'never deleted unattended — rerun without --yes' };
+  }
+  const ok = await confirm(
+    `[clean-temp] Delete ${total.count} ${bucket} entr${total.count === 1 ? 'y' : 'ies'} (${formatBytes(total.bytes)})?`,
+  );
+  return ok ? { run: true } : { run: false, note: 'declined' };
+}
+
+/**
+ * @returns {Promise<{ executed: object, bytesReclaimed: number, errors: string[] }>}
+ */
+async function executeBuckets(rows, totals, opts, env) {
+  const executed = {};
+  let bytesReclaimed = 0;
+  const errors = [];
+  for (const bucket of DELETABLE_BUCKETS) {
+    const decision = await approveBucket(
+      bucket,
+      totals[bucket],
+      opts,
+      env.confirm,
+    );
+    if (!decision.run) {
+      executed[bucket] = { deleted: false, note: decision.note ?? 'empty' };
+      continue;
+    }
+    const result = await executeBucket(bucket, rows, env);
+    executed[bucket] = { deleted: true, bytes: result.bytes };
+    bytesReclaimed += result.bytes;
+    errors.push(...result.errors);
+  }
+  return { executed, bytesReclaimed, errors };
+}
+
+/**
+ * Run `/clean-temp`. Never calls `process.exit`; the CLI shell applies the
+ * returned exit code.
+ *
+ * @param {object} args
+ * @param {string[]} args.argv
+ * @param {string} args.cwd Invocation dir; `--cwd` overrides it.
+ * @param {(projectRoot: string) => object} args.loadConfig Resolved config bag.
+ * @param {(cwd: string) => string} [args.resolveRoot] The project root the
+ *   run is scoped to — the main checkout root, else `cwd` itself.
+ * @param {(config: object) => object} args.getProvider Lazy; called only when
+ *   an id needs a read.
+ * @param {(question: string) => Promise<boolean>} args.confirm
+ * @param {(text: string) => void} args.write stdout sink.
+ * @param {(text: string) => void} args.writeErr stderr sink.
+ * @param {number} [args.now]
+ * @param {typeof fsPromises} [args.fsp]
+ * @returns {Promise<{ exitCode: number, envelope: object }>}
+ */
+export async function runCleanTemp({
+  argv,
+  cwd,
+  loadConfig,
+  resolveRoot = (dir) => mainCheckoutRoot(dir) ?? dir,
+  getProvider,
+  confirm,
+  write,
+  writeErr,
+  now = Date.now(),
+  fsp = fsPromises,
+}) {
+  const opts = parseCleanTempArgs(argv);
+  const projectRoot = resolveRoot(path.resolve(opts.cwd ?? cwd));
+  const config = loadConfig(projectRoot);
+  const { tempRoot, inside } = resolveScopedTempRoot(projectRoot, config);
+  if (!inside) {
+    writeErr(
+      `[clean-temp] refusing: tempRoot ${tempRoot} is not inside the project root ${projectRoot}.\n`,
+    );
+    return {
+      exitCode: 1,
+      envelope: { kind: 'clean-temp', refused: true, tempRoot, projectRoot },
+    };
+  }
+
+  const policy = resolveTempRetention(config);
+  const ctx = { now, staleMs: policy.staleDays * MS_PER_DAY };
+  const scan = await collectTempEntries({ config, tempRoot, fsp });
+  const ids = idsToRead(scan);
+  const states =
+    ids.size > 0 ? await readIssueStates(getProvider(config), ids) : new Map();
+  const closed = closedIds(states);
+  const preview = await sweepTempRetention({
+    config,
+    tempRoot,
+    mergedStoryIds: closed,
+    now,
+    fsp,
+    dryRun: true,
+    logger: silent,
+  });
+  const rows = await buildRows({ tempRoot, scan, preview, states, ctx, fsp });
+  const totals = bucketTotals(rows);
+  const envelope = {
+    kind: 'clean-temp',
+    tempRoot,
+    dryRun: !opts.execute,
+    staleDays: policy.staleDays,
+    buckets: totals,
+    entries: rows.map(({ path: _p, ...r }) => r),
+    executed: null,
+    bytesReclaimed: 0,
+    errors: [],
+  };
+
+  if (!opts.json) write(renderTable(rows));
+  if (opts.execute) {
+    const env = { config, tempRoot, closed, now, fsp, confirm };
+    Object.assign(envelope, await executeBuckets(rows, totals, opts, env));
+  }
+  if (opts.json) write(`${JSON.stringify(envelope)}\n`);
+  else write(renderSummary(envelope));
+  return { exitCode: envelope.errors.length > 0 ? 1 : 0, envelope };
+}
+
+/**
+ * @param {object} envelope
+ * @returns {string}
+ */
+function renderSummary(envelope) {
+  const parts = Object.entries(envelope.buckets).map(
+    ([bucket, t]) => `${bucket}=${t.count} (${formatBytes(t.bytes)})`,
+  );
+  const head = envelope.dryRun
+    ? '[clean-temp] dry run — nothing deleted; pass --execute to delete.'
+    : `[clean-temp] reclaimed ${formatBytes(envelope.bytesReclaimed)}.`;
+  const errors = envelope.errors
+    .map((e) => `[clean-temp] error: ${e}\n`)
+    .join('');
+  return `${head} ${parts.join(' · ')}\n${errors}`;
+}

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',