mandrel 2.67.0 → 2.68.0

package/.agents/scripts/lib/coverage-capture-incremental.js

@@ -2,6 +2,28 @@
 import path from 'node:path';
 import { resolveChangedFilesRef } from './changed-files.js';
 import { reportCaptureFailure, stampCapturedTree } from './coverage-capture.js';
+import {
+  describeStampFreshness,
+  readHeadCommit,
+} from './coverage-capture-delta.js';
+
+/**
+ * The changed-file set; `null` when incremental mode is off, or (warned)
+ * when the ref cannot be resolved.
+ *
+ * @returns {{ changed: string[] } | null}
+ */
+function readChanged({ crap, getChangedFilesImpl, ref, args, logger }) {
+  if (crap.incrementalCoverage?.skipWhenUnchanged !== true) return null;
+  try {
+    return { changed: getChangedFilesImpl({ ref, cwd: args.cwd }) };
+  } catch (err) {
+    logger.warn(
+      `[coverage-capture] ⚠ incremental mode: ${err?.message ?? err} — falling back to full-scope capture.`,
+    );
+    return null;
+  }
+}
 
 /**
  * Under `skipWhenUnchanged`: the changed-file set decides whether to capture,
@@ -20,6 +42,7 @@ import { reportCaptureFailure, stampCapturedTree } from './coverage-capture.js';
  *   runCaptureImpl: Function,
  *   computeContentDigestImpl: Function,
  *   writeCaptureStampImpl: Function,
+ *   readHeadCommitImpl?: typeof readHeadCommit,
  *   logger: { info: Function, warn: Function, error: Function },
  * }} opts
  * @returns {Promise<number | null>}
@@ -34,22 +57,17 @@ export async function tryIncrementalCapture({
   runCaptureImpl,
   computeContentDigestImpl,
   writeCaptureStampImpl,
+  readHeadCommitImpl = readHeadCommit,
   logger,
 }) {
-  if (crap.incrementalCoverage?.skipWhenUnchanged !== true) return null;
-
   const ref = resolveChangedFilesRef({ crap, ref: args.ref });
-  let changed = null;
-  try {
-    changed = getChangedFilesImpl({ ref, cwd: args.cwd });
-  } catch (err) {
-    logger.warn(
-      `[coverage-capture] ⚠ incremental mode: ${err?.message ?? err} — falling back to full-scope capture.`,
-    );
-    return null;
-  }
+  const read = readChanged({ crap, getChangedFilesImpl, ref, args, logger });
+  if (read === null) return null;
 
-  const scopedFiles = filterFilesUnderTargetsImpl(changed, crap.targetDirs);
+  const scopedFiles = filterFilesUnderTargetsImpl(
+    read.changed,
+    crap.targetDirs,
+  );
   if (scopedFiles.length === 0) {
     logger.info(
       `[coverage-capture] Incremental mode: no changed files under [${crap.targetDirs.join(', ')}] vs ${ref} — skipping capture.`,
@@ -57,35 +75,39 @@ export async function tryIncrementalCapture({
     return 0;
   }
 
-  const freshness = isCoverageFreshImpl({
-    coveragePath: crap.coveragePath,
-    targetDirs: crap.targetDirs,
+  const probe = () =>
+    isCoverageFreshImpl({
+      coveragePath: crap.coveragePath,
+      targetDirs: crap.targetDirs,
+      cwd: args.cwd,
+      requireScope: 'incremental',
+    });
+  const freshness = probe();
+  const detail = describeStampFreshness({
     cwd: args.cwd,
-    requireScope: 'incremental',
+    coveragePath: crap.coveragePath,
+    requiredScope: 'incremental',
+    verdict: freshness.reason,
   });
   if (freshness.fresh) {
     logger.info(
-      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} (incremental) — skipping capture.`,
+      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} (incremental) — skipping capture. ${detail}`,
     );
     return 0;
   }
 
   logger.info(
-    `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing…`,
+    `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing… ${detail}`,
   );
-  // Pre-spawn digest; see `stampCapturedTree`.
+  // Pre-spawn digest and commit; see `stampCapturedTree`.
   const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
+  const commit = readHeadCommitImpl(args.cwd);
   const code = await runCaptureImpl({
     cwd: args.cwd,
+    coveragePath: crap.coveragePath,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
-    recheckFresh: () =>
-      isCoverageFreshImpl({
-        coveragePath: crap.coveragePath,
-        targetDirs: crap.targetDirs,
-        cwd: args.cwd,
-        requireScope: 'incremental',
-      }).fresh === true,
+    recheckFresh: () => probe().fresh === true,
   });
   if (code !== 0) return reportCaptureFailure(code, logger);
 
@@ -97,6 +119,7 @@ export async function tryIncrementalCapture({
     scope: 'incremental',
     files: scopedFiles,
     ref,
+    commit,
     computeContentDigestImpl,
     writeCaptureStampImpl,
     logger,

package/.agents/scripts/lib/coverage-capture-usage.js

@@ -14,7 +14,7 @@ const COVERAGE_CAPTURE_USAGE = {
   invocation:
     'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--require-credited] [--ref <git-ref>] [--cwd <path>]',
   summary:
-    'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale. Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run.',
+    'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale (`npm run test:coverage:affected`, with the base ref in MANDREL_COVERAGE_BASE_REF, under delivery.quality.gates.coverage.captureScope="affected"). Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run.',
   flags: [
     [
       '--skip-when-no-crap-files',

package/.agents/scripts/lib/coverage-capture.js

@@ -3,20 +3,17 @@
  * reads it: the scorer skips uncovered methods, so a stale artifact silently
  * weakens the gate.
  */
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { LOCK_WAIT_EXPIRED_EXIT_CODE } from './full-suite-lock.js';
-import {
-  groupSpawnOptions,
-  superviseGroup,
-  TIMEOUT_EXIT_CODE,
-} from './process-group.js';
+import { TIMEOUT_EXIT_CODE } from './process-group.js';
 import {
   isScorableSourceFile,
   SCORABLE_SOURCE_EXT_RE,
 } from './source-extensions.js';
+import { runSupervisedSuite } from './supervised-suite.js';
 
 /**
  * Newest mtime across the scorable sources the CRAP scanner walks; unreadable
@@ -156,18 +153,40 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
   }
 }
 
+/** @param {string} value */
+const nonEmpty = (value) => typeof value === 'string' && value.length > 0;
+
+/** Scoped-stamp fields, each written only when it carries a value. */
+function optionalStampFields({ scope, files, ref, commit }) {
+  const out = {};
+  if (scope !== undefined) out.scope = scope;
+  if (Array.isArray(files)) out.files = [...files].sort();
+  if (nonEmpty(ref)) out.ref = ref;
+  if (nonEmpty(commit)) out.commit = commit;
+  return out;
+}
+
+/** @param {Record<string, unknown>} fields */
+function definedOnly(fields) {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, value]) => value !== undefined),
+  );
+}
+
 /**
  * Best-effort: a write failure returns `false` (next check falls back to
  * mtime). Full-scope callers omit `scope`, keeping the `{ digest, capturedAt }`
- * shape.
+ * shape. `commit` is the HEAD sha the run measured; a stamp without it reads
+ * exactly as before and is never delta-refresh eligible.
  *
  * @param {{
  *   cwd: string,
  *   coveragePath: string,
  *   digest: string,
- *   scope?: 'full' | 'incremental',
+ *   scope?: 'full' | 'incremental' | 'affected',
  *   files?: string[],
  *   ref?: string,
+ *   commit?: string | null,
  *   writeFileSync?: typeof fs.writeFileSync,
  * }} opts
  * @returns {boolean} True when the stamp was written.
@@ -179,13 +198,15 @@ export function writeCaptureStamp({
   scope,
   files,
   ref,
+  commit,
   writeFileSync = fs.writeFileSync,
 }) {
   if (typeof digest !== 'string' || digest.length === 0) return false;
-  const payload = { digest, capturedAt: new Date().toISOString() };
-  if (scope !== undefined) payload.scope = scope;
-  if (Array.isArray(files)) payload.files = [...files].sort();
-  if (typeof ref === 'string' && ref.length > 0) payload.ref = ref;
+  const payload = {
+    digest,
+    capturedAt: new Date().toISOString(),
+    ...optionalStampFields({ scope, files, ref, commit }),
+  };
   try {
     writeFileSync(
       captureStampPath(cwd, coveragePath),
@@ -197,42 +218,45 @@ export function writeCaptureStamp({
   }
 }
 
+/** Stamp scopes narrower than `full`; each satisfies only its own probe. */
+const PARTIAL_STAMP_SCOPES = new Set(['incremental', 'affected']);
+
 /**
  * @param {{digest?: unknown, scope?: unknown} | null} stamp
- * @param {'full' | 'incremental'} requireScope
+ * @param {'full' | 'incremental' | 'affected'} requireScope
  * @returns {{ digest: string } | { scopeMismatch: true } | null} `null`
- *   falls through to the mtime heuristic.
+ *   means no usable stamp: nothing vouches for the artifact.
  */
 function readStampForScope(stamp, requireScope) {
   if (typeof stamp?.digest !== 'string' || stamp.digest.length === 0) {
     return null;
   }
-  const stampScope = stamp.scope === 'incremental' ? 'incremental' : 'full';
-  if (stampScope === 'incremental' && requireScope !== 'incremental') {
+  if (PARTIAL_STAMP_SCOPES.has(stamp.scope) && stamp.scope !== requireScope) {
     return { scopeMismatch: true };
   }
   return { digest: stamp.digest };
 }
 
 /**
- * Stamp digest vs current digest when a stamp exists; otherwise artifact
- * mtime vs newest source. IO errors resolve stale. Both paths fail closed
- * (`no-sources`) on an empty source set — "found nothing" is not "nothing
- * changed". An incremental stamp never satisfies a full-scope probe; a stamp
- * with no `scope` is full-scope.
+ * Only a matching stamp vouches for the artifact, because only a green run
+ * writes one; artifact mtime says when a run wrote it, never that the run
+ * passed, so a red run's artifact must not read as fresh. Without a verdict,
+ * `no-sources` (empty source set — "found nothing" is not "nothing changed")
+ * outranks `unstamped`. A partial (incremental / affected) stamp satisfies
+ * only a probe of its own scope; a stamp with no `scope` is full-scope.
  *
  * @param {{
  *   coveragePath: string,
  *   targetDirs: string[],
  *   cwd: string,
- *   requireScope?: 'full' | 'incremental',
+ *   requireScope?: 'full' | 'incremental' | 'affected',
  *   statSync?: typeof fs.statSync,
  *   readdirSync?: typeof fs.readdirSync,
  *   existsSync?: typeof fs.existsSync,
  *   readFileSync?: typeof fs.readFileSync,
  *   computeDigest?: typeof computeContentDigest,
  * }} opts
- * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' | 'scope-mismatch' }}
+ * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' | 'scope-mismatch' | 'unstamped' }}
  */
 export function isCoverageFresh({
   coveragePath,
@@ -254,7 +278,7 @@ export function isCoverageFresh({
     try {
       stamp = JSON.parse(readFileSync(stampPath, 'utf8'));
     } catch {
-      // Corrupt/unreadable stamp → fall through to the mtime heuristic.
+      // Corrupt/unreadable stamp vouches for nothing.
     }
     const resolved = readStampForScope(stamp, requireScope);
     if (resolved?.scopeMismatch) {
@@ -270,21 +294,14 @@ export function isCoverageFresh({
     }
   }
 
-  let coverageMtime;
-  try {
-    coverageMtime = statSync(absCoverage).mtimeMs;
-  } catch {
-    return { fresh: false, reason: 'missing' };
-  }
-
   const newestSrc = newestSourceMtime(cwd, targetDirs, {
     statSync,
     readdirSync,
   });
-  if (newestSrc === 0) return { fresh: false, reason: 'no-sources' };
-  return coverageMtime >= newestSrc
-    ? { fresh: true, reason: 'fresh' }
-    : { fresh: false, reason: 'stale' };
+  return {
+    fresh: false,
+    reason: newestSrc === 0 ? 'no-sources' : 'unstamped',
+  };
 }
 
 /**
@@ -358,9 +375,10 @@ export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
  *   cwd: string,
  *   targetDirs: string[],
  *   coveragePath: string,
- *   scope?: 'full' | 'incremental',
+ *   scope?: 'full' | 'incremental' | 'affected',
  *   files?: string[],
  *   ref?: string,
+ *   commit?: string | null,
  *   computeContentDigestImpl: typeof computeContentDigest,
  *   writeCaptureStampImpl: typeof writeCaptureStamp,
  *   logger: { info: Function, warn: Function, error: Function },
@@ -375,6 +393,7 @@ export function stampCapturedTree({
   scope,
   files,
   ref,
+  commit,
   computeContentDigestImpl,
   writeCaptureStampImpl,
   logger,
@@ -393,9 +412,7 @@ export function stampCapturedTree({
     cwd,
     coveragePath,
     digest: preDigest,
-    ...(scope === undefined ? {} : { scope }),
-    ...(files === undefined ? {} : { files }),
-    ...(ref === undefined ? {} : { ref }),
+    ...definedOnly({ scope, files, ref, commit: commit || undefined }),
   });
   if (written) {
     logger.info(
@@ -434,73 +451,96 @@ export function anyChangedUnderTargets(changedFiles, targetDirs) {
   return filterFilesUnderTargets(changedFiles, targetDirs).length > 0;
 }
 
+/**
+ * @param {{ cwd: string, coveragePath?: string }} opts No `coveragePath`,
+ *   no stamp to drop.
+ */
+function dropCaptureStamp({ cwd, coveragePath }) {
+  if (!coveragePath) return;
+  fs.rmSync(captureStampPath(cwd, coveragePath), { force: true });
+}
+
 /** GNU `timeout(1)` code, so callers tell a hang (124) from failing tests. */
 export const COVERAGE_TIMEOUT_EXIT_CODE = TIMEOUT_EXIT_CODE;
 
 /**
- * Spawn `npm run test:coverage` asynchronously as its own process group, so
+ * Spawn `npm run <script>` asynchronously as its own process group, so
  * the lock heartbeat keeps running and a timeout or signal kills every
  * worker. Takes no positional file args: node's runner would execute a
- * forwarded source file as a test instead of filtering the suite.
+ * forwarded source file as a test instead of filtering the suite. Scope a
+ * run through `env` instead. Given `coveragePath`, the capture stamp is
+ * removed before the spawn: the suite is about to overwrite the artifact, so
+ * a red, killed or crashed run must leave no stamp vouching for it — only
+ * `stampCapturedTree` after a green run restores one.
  *
  * @param {{
  *   cwd: string,
+ *   coveragePath?: string,
  *   timeoutMs?: number,
- *   spawnImpl?: typeof spawn,
+ *   script?: string,
+ *   env?: Record<string, string>,
+ *   spawnImpl?: Function,
  *   log?: (m: string) => void,
+ *   lockWaitMs?: number,
+ *   onTimings?: (timings: import('./supervised-suite.js').SuiteTimings) => void,
  * }} opts
  * @returns {Promise<number>}
  */
-export function runCapture({
-  cwd,
-  timeoutMs,
-  spawnImpl = spawn,
-  log = () => {},
-} = {}) {
-  const args = ['run', 'test:coverage'];
+export function runCapture(opts = {}) {
+  const { script = 'test:coverage', log = () => {} } = opts;
+  dropCaptureStamp(opts);
+  const args = ['run', script];
   log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
-  return new Promise((resolve) => {
-    const child = spawnImpl('npm', args, {
-      cwd,
-      stdio: 'inherit',
-      shell: process.platform === 'win32',
-      ...groupSpawnOptions(),
-    });
-    const supervisor = superviseGroup(child, { timeoutMs });
-    child.on('error', () => {
-      supervisor.release();
-      resolve(1);
-    });
-    child.on('exit', (code) => {
-      supervisor.release();
-      if (!supervisor.timedOut) {
-        resolve(code ?? 1);
-        return;
-      }
+  return runSupervisedSuite({
+    ...opts,
+    cmd: 'npm',
+    args,
+    onTimeout: () =>
       log(
-        `[coverage-capture] ⏱ npm run test:coverage exceeded ${timeoutMs}ms — killed its process group. Returning exit ${COVERAGE_TIMEOUT_EXIT_CODE}.`,
-      );
-      resolve(COVERAGE_TIMEOUT_EXIT_CODE);
-    });
+        `[coverage-capture] ⏱ npm run ${script} exceeded ${opts.timeoutMs}ms — killed its process group. Returning exit ${COVERAGE_TIMEOUT_EXIT_CODE}.`,
+      ),
   });
 }
 
+/** @param {number} code */
+function lockWaitExpiredMessage(code) {
+  return `[coverage-capture] ⏸ the full-suite lock wait expired with another suite still running, so this capture was deferred — no suite ran. Exiting ${code}; re-run it once that suite finishes.`;
+}
+
+/** @param {number} code */
+function timeoutMessage(code) {
+  return `[coverage-capture] ⏱ npm run test:coverage timed out and was killed (exit ${code}) — no test verdict exists. This is usually host contention, not a failing test; re-run once the host is quieter.`;
+}
+
+/** @param {number} code */
+function failingSuiteMessage(code) {
+  return `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`;
+}
+
+/**
+ * Exits that are not a failing suite, each with its own report: an expired
+ * lock wait ran nothing, and a timeout killed the suite before any verdict.
+ * Named functions: V8 coverage omitted an inline arrow here, so CRAP could
+ * not resolve it.
+ */
+const NON_FAILURE_CAPTURE_EXITS = Object.freeze({
+  [LOCK_WAIT_EXPIRED_EXIT_CODE]: ['info', lockWaitExpiredMessage],
+  [COVERAGE_TIMEOUT_EXIT_CODE]: ['error', timeoutMessage],
+});
+
+const FAILING_SUITE_REPORT = Object.freeze(['error', failingSuiteMessage]);
+
 /**
- * Report a non-zero capture; an expired lock wait is not a failing suite.
+ * Report a non-zero capture; an expired lock wait or a timeout is not a
+ * failing suite, so neither prints the failing-tests line.
  *
  * @param {number} code
  * @param {{ info: Function, error: Function }} logger
  * @returns {number}
  */
 export function reportCaptureFailure(code, logger) {
-  if (code === LOCK_WAIT_EXPIRED_EXIT_CODE) {
-    logger.info(
-      `[coverage-capture] ⏸ the full-suite lock wait expired and this capture was deferred — no suite ran. Exiting ${code}.`,
-    );
-    return code;
-  }
-  logger.error(
-    `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
-  );
+  const [level, message] =
+    NON_FAILURE_CAPTURE_EXITS[code] ?? FAILING_SUITE_REPORT;
+  logger[level](message(code));
   return code;
 }

package/.agents/scripts/lib/full-suite-lock.js

@@ -3,16 +3,16 @@
  * worktrees (they contend for cores and a shared coverage artifact), over
  * the `sweep-lock.js` primitive.
  *
- * Best-effort: any failure to acquire spawns anyway — a stale lockfile must
- * never fail a delivery. Only close opts in to defer on an expired wait
- * ({@link LOCK_WAIT_EXPIRED_EXIT_CODE}). Waits are async so the holder's
- * heartbeat and signal release keep working, and FIFO via
- * `full-suite-queue.js`. The lock covers only the spawn, never the
- * freshness checks before it.
+ * It queues, never overlaps: an expired wait behind a live holder spawns
+ * nothing ({@link LOCK_WAIT_EXPIRED_EXIT_CODE}). A dead holder is taken over
+ * and a lockfile I/O error proceeds unserialized. Waits are async (the
+ * holder's heartbeat keeps working) and FIFO via `full-suite-queue.js`; the
+ * lock covers only the spawn.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { getQuality } from './config/quality.js';
 import { mainCheckoutRoot } from './config/temp-paths.js';
 import { isFirstInLine, waitInLine } from './full-suite-queue.js';
 import { acquireSweepLock } from './single-story-sweep/sweep-lock.js';
@@ -20,20 +20,14 @@ import { acquireSweepLock } from './single-story-sweep/sweep-lock.js';
 /** Environment escape hatch: set to `0`/`false`/`off`/`no` to disable. */
 export const FULL_SUITE_LOCK_ENV = 'MANDREL_FULL_SUITE_LOCK';
 
-/** Close sets it to `defer` on its gate children; nothing else does. */
-export const FULL_SUITE_LOCK_EXPIRY_ENV = 'MANDREL_FULL_SUITE_LOCK_ON_EXPIRY';
-
 /** `EX_TEMPFAIL`. */
 export const LOCK_WAIT_EXPIRED_EXIT_CODE = 75;
 
 /** Under the main checkout's `.git`, so every worktree shares one file. */
 const FULL_SUITE_LOCK_FILENAME = 'mandrel-full-suite.lock';
 
-/** Well under close's ten-minute foreground ceiling. */
-const DEFAULT_WAIT_MS = 300_000;
-
-/** Never above the wait budget. */
-const DEFAULT_STALE_MS = 240_000;
+/** The wait floor, and the budget when no kill bound is known. */
+const MIN_WAIT_MS = 300_000;
 
 const DEFAULT_POLL_MS = 2_000;
 
@@ -47,16 +41,32 @@ const LOCK_TAG = '[full-suite-lock]';
 const LOCK_DEFAULTS = Object.freeze({
   enabled: true,
   log: () => {},
-  waitMs: DEFAULT_WAIT_MS,
+  ...resolveFullSuiteLockBudget(),
   pollMs: DEFAULT_POLL_MS,
-  staleMs: DEFAULT_STALE_MS,
   reportMs: DEFAULT_REPORT_MS,
   fsImpl: fs,
   nowFn: Date.now,
   sleepFn: (ms) => defaultSleep(ms),
   acquireOnceFn: (opts) => acquireSweepLock(opts),
+  onWaitExpired: () => LOCK_WAIT_EXPIRED_EXIT_CODE,
+  rerunCommand: 'the same command',
 });
 
+/**
+ * The one wait budget every full-suite lock taker uses. A holder's suite is
+ * killed at its supervisor's `killBoundMs` (the coverage gate's `timeoutMs`),
+ * so waiting that long always observes a release or a death. The stale
+ * threshold is four fifths of the wait: never above the budget, and a live
+ * holder (heartbeating at a third of its own threshold) is never read stale.
+ *
+ * @param {number} [killBoundMs]
+ * @returns {{ waitMs: number, staleMs: number }}
+ */
+export function resolveFullSuiteLockBudget(killBoundMs) {
+  const waitMs = Math.max(MIN_WAIT_MS, Number(killBoundMs) || 0);
+  return { waitMs, staleMs: waitMs - waitMs / 5 };
+}
+
 /**
  * Both hatches (env, then config) can only turn the lock off.
  *
@@ -157,9 +167,10 @@ function consult(probe, applies) {
  *   acquireOnceFn?: typeof acquireSweepLock,
  *   lockPath?: string,
  *   skipIfSatisfied?: () => T|undefined,
- *   onWaitExpired?: () => T|undefined,
- * }} opts A non-`undefined` return from either hook stands in for the spawn.
- * @param {() => Promise<T>} spawn
+ *   onWaitExpired?: (holder: import('./full-suite-queue.js').LockHolder) => T,
+ *   rerunCommand?: string,
+ * }} opts A non-`undefined` `skipIfSatisfied` return stands in for the spawn.
+ * @param {(timing: { lockWaitMs: number }) => Promise<T>} spawn
  * @returns {Promise<T>}
  */
 export async function withFullSuiteLockAsync(options, spawn) {
@@ -167,8 +178,8 @@ export async function withFullSuiteLockAsync(options, spawn) {
   const { lock, lockPath } = beginLock(opts);
   const wait =
     lock === null && lockPath !== null
-      ? await waitInLine({ ...opts, lockPath, expiryNote: expiryNote(opts) })
-      : { held: lock, expired: false, waited: false };
+      ? await waitInLine({ ...opts, lockPath })
+      : { held: lock, expired: false, waited: false, waitedMs: 0 };
   try {
     return await spawnOrStandIn(opts, wait, spawn);
   } finally {
@@ -184,12 +195,6 @@ function withDefaults(options) {
   return opts;
 }
 
-function expiryNote({ onWaitExpired }) {
-  return typeof onWaitExpired === 'function'
-    ? 'not spawning; the caller reports the wait instead'
-    : 'spawning anyway';
-}
-
 async function spawnOrStandIn(opts, wait, spawn) {
   const probe = consult(opts.skipIfSatisfied, wait.waited);
   if (probe.satisfied) {
@@ -198,8 +203,8 @@ async function spawnOrStandIn(opts, wait, spawn) {
     );
     return probe.value;
   }
-  const deferred = consult(opts.onWaitExpired, wait.expired);
-  return deferred.satisfied ? deferred.value : await spawn();
+  if (wait.expired) return opts.onWaitExpired(wait.holder);
+  return await spawn({ lockWaitMs: wait.waitedMs ?? 0 });
 }
 
 /**
@@ -212,6 +217,18 @@ function defaultSleep(ms) {
   });
 }
 
+/**
+ * @param {object} [config]
+ * @param {Record<string, string|undefined>} [env]
+ */
+export function fullSuiteLockPolicy(config, env = process.env) {
+  return {
+    ...resolveFullSuiteLockBudget(getQuality(config).coverage?.timeoutMs),
+    enabled: isFullSuiteLockEnabled({ config, env }),
+    onWaitExpired: () => LOCK_WAIT_EXPIRED_EXIT_CODE,
+  };
+}
+
 /**
  * Serialize a capture runner's spawn. Wrapped at the one call site below
  * every skip/freshness decision, so a credited capture never waits.
@@ -219,7 +236,7 @@ function defaultSleep(ms) {
  * @param {Function} runCaptureFn
  * @param {object} [config]
  * @param {Record<string, string|undefined>} [env]
- * @param {object} [lockOptions] Test seam only.
+ * @param {object} [lockOptions]
  * @returns {(opts?: object) => Promise<number>}
  */
 export function lockedCapture(
@@ -228,11 +245,7 @@ export function lockedCapture(
   env = process.env,
   lockOptions = {},
 ) {
-  const policy = {
-    enabled: isFullSuiteLockEnabled({ config, env }),
-    onWaitExpired: deferredCaptureExit(env),
-    ...lockOptions,
-  };
+  const policy = { ...fullSuiteLockPolicy(config, env), ...lockOptions };
   return (captureOpts = {}) =>
     withFullSuiteLockAsync(
       {
@@ -241,20 +254,10 @@ export function lockedCapture(
         log: captureOpts.log,
         skipIfSatisfied: freshnessProbe(captureOpts),
       },
-      () => runCaptureFn(captureOpts),
+      ({ lockWaitMs }) => runCaptureFn({ ...captureOpts, lockWaitMs }),
     );
 }
 
-/**
- * @param {Record<string, string|undefined>} env
- * @returns {(() => number)|undefined}
- */
-function deferredCaptureExit(env) {
-  return env[FULL_SUITE_LOCK_EXPIRY_ENV] === 'defer'
-    ? () => LOCK_WAIT_EXPIRED_EXIT_CODE
-    : undefined;
-}
-
 /**
  * A fresh recheck means exit 0 without spawning.
  *