mandrel 2.67.0 → 2.68.0

package/.agents/agents/story-worker.md

@@ -87,14 +87,16 @@ names. A null digest path means no docs mandate.
 
 `single-story-close.js` runs the canonical close-validation chain
 (**typecheck, lint, test, format, maintainability, coverage, crap**) and is
-the authoritative gate — do not pre-run it. The **one** exception is the
-full suite: after the self-eval loop's last fix commit, run it once in
+the authoritative gate — do not pre-run it. Two exceptions, both run in
 `<workCwd>` exactly as
-[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states it —
-that section is the rule's only home, so read the invocation there rather
-than from a copy here.
-
-If the suite outruns the host's sync Bash ceiling, dispatch it in the
+[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states them:
+the **blocking** lint + quality-preview preflight, then the one credited run
+(the coverage capture or the test depositor, as § 5 picks), once after the
+self-eval loop's last fix commit, then the `--seat-missing` baseline seat
+before push. That section is their only home, so read the invocations there
+rather than from a copy here.
+
+If the run outruns the host's sync Bash ceiling, dispatch it in the
 **background**: its completion re-invokes you. Never spawn a task to poll or
 `sleep`-loop against it; a waiter with a wrong condition outlives the agent.
 An exit code is never evidence a gate did work — its **output** is. Redraft
@@ -142,11 +144,13 @@ the remote ref moved — then return: a turn that ends unpushed reads as
 unfinished work. The orchestrator runs
 `single-story-close.js` in its own session, serialized against your
 siblings. Do not open the PR, flip `agent::done`, or spawn a child to
-close for you. If the push fails, take the blocked path above.
+close for you. If the push fails, take the blocked path above. After
+the push, compute the held review and fix a CRITICAL before returning
+([`deliver-reference.md`](../workflows/helpers/deliver-reference.md) § Held review).
 
 ## Return contract — the hand-off report
 
 A short, literal hand-off your caller can act on: Story id, `workCwd`,
-branch, pushed head SHA, self-eval verdict, `verify[]` evidence. Say the
-branch is pushed and unclosed. Never hand-compose a terminal envelope —
-inventing one makes an unlanded Story look landed.
+branch, pushed head SHA, self-eval verdict, `verify[]` evidence, review
+tally. Say the branch is pushed and unclosed. Never hand-compose a
+terminal envelope — inventing one makes an unlanded Story look landed.

package/.agents/docs/agentrc-reference.json

@@ -125,7 +125,9 @@
               "functions": 90
             }
           },
-          "coveragePath": "coverage/coverage-final.json"
+          "coveragePath": "coverage/coverage-final.json",
+          "captureScope": "full",
+          "timeoutMs": 600000
         },
         "crap": {
           "enabled": true,

package/.agents/docs/configuration.md

@@ -136,7 +136,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `execution` | No | `object` | — | Serialization of the full-suite spawns delivery drives. |
-| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
+| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
 | `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
 | `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
 | `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so unrecognized files under tempRoot are reported with their size and left alone (`/clean-temp` is the operator path for them). signals.ndjson is never purged by any path. |
@@ -169,6 +169,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
 | `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
 | `quality.gates.coverage.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
 | `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. |
+| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
+| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
 | `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
 | `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
 | `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
@@ -365,6 +367,39 @@ A config still carrying the retired key is a hard validation failure; the
   Extend the list-valued gate keys with the deep-merge extender form (see
   [How to extend](#how-to-extend)).
 
+#### `delivery.quality.gates.coverage.captureScope` — delta refresh
+
+Under `captureScope: "affected"`, a capture stamp records the commit it
+measured. When close's base-sync merges `main` into the Story branch, the
+next capture re-measures only the merged commits' tests instead of the
+Story's whole affected scope: it runs `npm run test:coverage:affected` with
+`MANDREL_COVERAGE_BASE_REF` set to the **stamped commit**, drops the prior
+rows of the delta's files, merges the new rows over the prior artifact and
+stamps the merged tree fresh. It holds the full-suite lock like any capture,
+and a red delta refresh fails the capture — it never falls back to a wider
+run.
+
+A delta refresh runs only when **every** condition holds; otherwise the
+capture behaves exactly as before (the Story's affected scope, or the full
+suite when the script is absent):
+
+- the stamp is stale by content digest, and records a `commit` (a stamp
+  written before this field existed never qualifies) that is an ancestor of
+  `HEAD`;
+- `captureScope` is `affected` and the `test:coverage:affected` script
+  exists;
+- the worktree is clean, and the delta (`git diff --name-only <commit> HEAD`)
+  is non-empty and shares no path with the Story's change set;
+- the delta touches no coverage-determining config: `package.json`, a
+  lockfile, `tsconfig*.json`, or a vitest / jest / c8 / nyc config;
+- a prior artifact exists to merge over.
+
+Any git error or unresolvable input fails closed to the ordinary capture.
+Every freshness log line names the stamp's scope, the required scope and the
+verdict (`fresh`, `stale`, `scope-mismatch`, `missing`, or `delta-refresh`
+with the delta's file count), so an unexpected full re-run is explainable
+from the log alone. `captureScope: "full"` is unaffected.
+
 #### `delivery.worktreeIsolation` — node_modules strategies
 
 When `enabled: true`, each Story runs in its own worktree under

package/.agents/schemas/agentrc.schema.json

@@ -359,7 +359,7 @@
           "properties": {
             "fullSuiteLock": {
               "type": "boolean",
-              "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
+              "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
               "default": true
             }
           },
@@ -600,6 +600,19 @@
                       "minLength": 1,
                       "description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads.",
                       "default": "coverage/coverage-final.json"
+                    },
+                    "captureScope": {
+                      "type": "string",
+                      "enum": ["full", "affected"],
+                      "description": "What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite.",
+                      "default": "full"
+                    },
+                    "timeoutMs": {
+                      "type": "integer",
+                      "minimum": 60000,
+                      "maximum": 7200000,
+                      "description": "Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure.",
+                      "default": 600000
                     }
                   },
                   "additionalProperties": false

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -200,7 +200,29 @@
       "required": ["waitedSeconds", "expired"],
       "properties": {
         "waitedSeconds": { "type": "number", "minimum": 0 },
-        "expired": { "type": "boolean" }
+        "expired": { "type": "boolean" },
+        "holder": {
+          "type": "object",
+          "description": "Story #5485 — the live holder an expired wait gave up on, read from the lockfile: its owner id, pid and lock age. Each field is null when the lockfile did not say.",
+          "required": ["ownerId", "pid", "ageSeconds"],
+          "properties": {
+            "ownerId": { "type": ["string", "null"] },
+            "pid": { "type": ["integer", "null"], "minimum": 1 },
+            "ageSeconds": { "type": ["number", "null"], "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "suiteTimings": {
+      "type": ["object", "null"],
+      "description": "Story #5485 — the close's one full-suite run split into three separate figures: lockWaitMs (queued on the host full-suite lock), hostWaitMs (spawn until the suite signalled MANDREL_SUITE_READY_FILE; null when it did not use the handshake) and testRunMs (the test phase the coverage.timeoutMs kill bound applies to). null when no full suite ran in this close.",
+      "required": ["lockWaitMs", "hostWaitMs", "testRunMs"],
+      "properties": {
+        "lockWaitMs": { "type": "number", "minimum": 0 },
+        "hostWaitMs": { "type": ["number", "null"], "minimum": 0 },
+        "testRunMs": { "type": "number", "minimum": 0 }
       },
       "additionalProperties": false
     },

package/.agents/schemas/validation-evidence.schema.json

@@ -41,10 +41,12 @@
               "check-baselines-independent",
               "check-baselines-coverage",
               "quality-preview",
+              "quality-preview-mi",
+              "quality-preview-crap",
               "check-maintainability",
               "check-crap"
             ],
-            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `quality-preview` replays the pre-push CRAP-scope preview at close, registered beside `coverage-capture` (Story #5378); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `quality-preview-mi` / `quality-preview-crap` replay the pre-push quality preview at close as its two halves — the MI half in the parallel partition, the CRAP half serial behind `coverage-capture` (Story #5471) — with `quality-preview` kept as the historical name of the unsplit gate (Story #5378); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
           },
           "commitSha": {
             "type": "string",

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

@@ -2,15 +2,15 @@
 /**
  * Ensures `coverage/coverage-final.json` is fresh before the CRAP gate: skip
  * when the gate is off, no changed file is under `crap.targetDirs`, or the
- * content-digest stamp matches; otherwise run `test:coverage` behind the
- * host-level full-suite lock and stamp on success.
+ * content-digest stamp matches; otherwise run `test:coverage` (or, under
+ * `coverage.captureScope: "affected"`, the consumer's `test:coverage:affected`)
+ * behind the host-level full-suite lock and stamp on success.
  *
  * `--require-credited` must stay an argument, never a config read: as policy
  * it also refused the depositing run, leaving no path that could deposit.
  *
  * Exit codes: 0 fresh/skipped/captured; 1 capture failed or refused (callers
- * MUST surface it); 75 lock wait expired and deferred (only under
- * `MANDREL_FULL_SUITE_LOCK_ON_EXPIRY=defer`); 124 suite timed out.
+ * MUST surface it); 75 lock wait expired, nothing spawned; 124 suite timed out.
  */
 import { getChangedFiles } from './lib/changed-files.js';
 import { isDirectInvocation } from './lib/cli-utils.js';
@@ -23,13 +23,13 @@ import {
   runCapture,
   writeCaptureStamp,
 } from './lib/coverage-capture.js';
+import { tryScopedCapture } from './lib/coverage-capture-affected.js';
 import { runFullScopeCapture } from './lib/coverage-capture-fullscope.js';
-import { tryIncrementalCapture } from './lib/coverage-capture-incremental.js';
 import { handleCoverageCaptureHelp } from './lib/coverage-capture-usage.js';
 import { lockedCapture } from './lib/full-suite-lock.js';
-
 import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
+import { formatSuiteTimings } from './lib/supervised-suite.js';
 
 /**
  * A `null` ref defers the fallback to `resolveChangedFilesRef`.
@@ -67,6 +67,7 @@ export function parseArgs(argv) {
  *   writeCaptureStampImpl?: typeof writeCaptureStamp,
  *   filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
  *   logger?: { info: Function, warn: Function, error: Function },
+ *   lockOptions?: object,
  * }} [deps]
  * @returns {Promise<number>}
  */
@@ -83,6 +84,7 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
     writeCaptureStampImpl = writeCaptureStamp,
     filterFilesUnderTargetsImpl = filterFilesUnderTargets,
     logger = Logger,
+    lockOptions = {},
   } = deps;
   const args = parseArgs(argv);
   const config = resolveConfigImpl({ cwd: args.cwd });
@@ -105,13 +107,65 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
 
   // Outermost first: the credit probe announces or refuses the run, and only
   // a surviving run reaches the host-level full-suite lock.
-  const capture = creditedCapture(lockedCapture(runCaptureImpl, config), {
+  const locked = lockedCapture(runCaptureImpl, config, process.env, {
+    rerunCommand: rerunCommandFor(argv),
+    ...lockOptions,
+  });
+  const credited = creditedCapture(locked, {
     requireCredited: args.requireCredited,
     logger,
   });
+  let timings = null;
+  const capture = (captureOpts) =>
+    credited({
+      ...captureOpts,
+      onTimings: (t) => {
+        timings = t;
+      },
+    });
+  const code = await runCaptureScopes({
+    crap,
+    coverage,
+    args,
+    capture,
+    deps: {
+      getChangedFilesImpl,
+      isCoverageFreshImpl,
+      computeContentDigestImpl,
+      writeCaptureStampImpl,
+      filterFilesUnderTargetsImpl,
+      readPackageScriptsImpl,
+      hasNpmScriptImpl,
+      logger,
+    },
+  });
+  if (timings) logger.info(`[coverage-capture] ${formatSuiteTimings(timings)}`);
+  return code;
+}
+
+/** @param {string[]} argv */
+function rerunCommandFor(argv) {
+  return ['node', ...argv.slice(1)].join(' ');
+}
+
+/**
+ * @param {{ crap: object, coverage: object, args: object, capture: Function, deps: object }} opts
+ * @returns {Promise<number>}
+ */
+async function runCaptureScopes({ crap, coverage, args, capture, deps }) {
+  const {
+    getChangedFilesImpl,
+    isCoverageFreshImpl,
+    computeContentDigestImpl,
+    writeCaptureStampImpl,
+    filterFilesUnderTargetsImpl,
+    readPackageScriptsImpl,
+    hasNpmScriptImpl,
+    logger,
+  } = deps;
 
   // Shared so a new seam cannot reach one capture path and miss the other.
-  // An incremental `null` means not applicable: fall through to full scope.
+  // A scoped `null` means not applicable: fall through to full scope.
   const shared = {
     crap,
     coverage,
@@ -124,9 +178,11 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
     logger,
   };
 
-  const incrementalResult = await tryIncrementalCapture({
+  const incrementalResult = await tryScopedCapture({
     ...shared,
     filterFilesUnderTargetsImpl,
+    readPackageScriptsImpl,
+    hasNpmScriptImpl,
   });
   if (incrementalResult !== null) return incrementalResult;
 

package/.agents/scripts/evidence-gate.js

@@ -5,14 +5,25 @@
  * passed for the current HEAD and tree, and recording a pass for the next
  * caller. `--standalone` is required: it keys evidence by Story id, the same
  * keyspace close consults, so worker-side verify[] runs credit the close.
+ * `--gate test` takes the host full-suite lock.
  */
 
 import { spawnSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+import {
+  fullSuiteLockPolicy,
+  LOCK_WAIT_EXPIRED_EXIT_CODE,
+  withFullSuiteLockAsync,
+} from './lib/full-suite-lock.js';
 import { gitSpawn } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { PROJECT_ROOT } from './lib/project-root.js';
+import {
+  formatSuiteTimings,
+  runSupervisedSuite,
+} from './lib/supervised-suite.js';
 import {
   hashCommandConfig,
   recordPass,
@@ -20,6 +31,8 @@ import {
   treeFingerprint,
 } from './lib/validation-evidence.js';
 
+const FULL_SUITE_GATE = 'test';
+
 export function splitOnDashDash(argv) {
   const idx = argv.indexOf('--');
   if (idx === -1) return { wrapperArgs: argv, runnerArgs: [] };
@@ -90,6 +103,7 @@ function resolveEvidenceKeys({ spawnCwd, gitSpawnFn, useEvidence }) {
  * @param {Function} [deps.shouldSkipFn]
  * @param {Function} [deps.recordPassFn]
  * @param {object}   [deps.logger]
+ * @param {Function} [deps.runSuiteFn]
  * @returns {{ status: number, skipped: boolean }}
  */
 export async function runEvidenceGate(params, deps = {}) {
@@ -99,6 +113,7 @@ export async function runEvidenceGate(params, deps = {}) {
     shouldSkipFn = shouldSkip,
     recordPassFn = recordPass,
     logger = Logger,
+    runSuiteFn = runLockedSuite,
   } = deps;
   const {
     scopeId,
@@ -159,17 +174,18 @@ export async function runEvidenceGate(params, deps = {}) {
   logger.info(
     `[evidence-gate] ▶ ${gate} → ${cmd} ${cmdArgs.join(' ')} (cwd=${spawnCwd})`,
   );
-  const result = spawnFn(cmd, cmdArgs, {
-    cwd: spawnCwd,
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
+  const status = await runGateCommand({
+    gate,
+    cmd,
+    cmdArgs,
+    spawnCwd,
+    logger,
+    spawnFn,
+    runSuiteFn,
   });
-  const status = result.status ?? 1;
   if (status !== 0) {
     process.exitCode = status;
-    logger.error(
-      `[evidence-gate] ✖ ${gate} failed (exit ${status}) in ${spawnCwd}`,
-    );
+    reportGateExit({ gate, status, spawnCwd, logger });
     return { status, skipped: false };
   }
 
@@ -197,6 +213,88 @@ export async function runEvidenceGate(params, deps = {}) {
   return { status: 0, skipped: false };
 }
 
+/**
+ * @param {{ cmd: string, args: string[], cwd: string, log: (m: string) => void }} run
+ * @param {{ config?: object|null, env?: object, lockOptions?: object, runSuiteImpl?: typeof runSupervisedSuite }} [seams]
+ * @returns {Promise<number>} 75 when the lock wait expired.
+ */
+export function runLockedSuite(
+  { cmd, args, cwd, log },
+  {
+    config = loadConfig(cwd),
+    env = process.env,
+    lockOptions = {},
+    runSuiteImpl = runSupervisedSuite,
+  } = {},
+) {
+  const timeoutMs = getQuality(config).coverage?.timeoutMs;
+  return withFullSuiteLockAsync(
+    {
+      ...fullSuiteLockPolicy(config, env),
+      cwd,
+      log,
+      rerunCommand: ['node', ...process.argv.slice(1)].join(' '),
+      ...lockOptions,
+    },
+    ({ lockWaitMs }) =>
+      runSuiteImpl({
+        cmd,
+        args,
+        cwd,
+        timeoutMs,
+        lockWaitMs,
+        onTimings: (t) => log(`[evidence-gate] ${formatSuiteTimings(t)}`),
+        onTimeout: () =>
+          log(
+            `[evidence-gate] ⏱ ${cmd} ${args.join(' ')} exceeded ${timeoutMs}ms — killed its process group.`,
+          ),
+      }),
+  );
+}
+
+/** The `test` gate runs locked and supervised; any other gate plainly. */
+async function runGateCommand({
+  gate,
+  cmd,
+  cmdArgs,
+  spawnCwd,
+  logger,
+  spawnFn,
+  runSuiteFn,
+}) {
+  if (gate === FULL_SUITE_GATE) {
+    const log = (m) => logger.info(m);
+    return await runSuiteFn({ cmd, args: cmdArgs, cwd: spawnCwd, log });
+  }
+  const result = spawnFn(cmd, cmdArgs, {
+    cwd: spawnCwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  return result.status ?? 1;
+}
+
+function reportGateExit({ gate, status, spawnCwd, logger }) {
+  if (status === LOCK_WAIT_EXPIRED_EXIT_CODE) {
+    logger.info(
+      `[evidence-gate] ⏸ ${gate} deferred (exit ${status}) — another full suite still holds the host lock, so nothing ran and no evidence was recorded.`,
+    );
+    return;
+  }
+  logger.error(
+    `[evidence-gate] ✖ ${gate} failed (exit ${status}) in ${spawnCwd}`,
+  );
+}
+
+/** An unloadable config falls back to the defaults. */
+function loadConfig(cwd) {
+  try {
+    return resolveConfig({ cwd });
+  } catch {
+    return null;
+  }
+}
+
 async function main() {
   const { wrapperArgs, runnerArgs } = splitOnDashDash(process.argv.slice(2));
   const args = parseWrapperArgs(wrapperArgs);

package/.agents/scripts/lib/baselines/coverage-refresh-scope.js

@@ -0,0 +1,60 @@
+/** Wires `resolveCoverageRefreshScope` to the on-disk artifact and c8 scope. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildScopePredicate,
+  readArtifactCaptureScope,
+  readCoverageFinal,
+  resolveCoverageRefreshScope,
+  scoreCoverageFinal,
+} from '../coverage-baseline.js';
+import { deriveScopeFromDiff } from './refresh-service.js';
+
+/**
+ * `refreshBaseline` scope options for `update-coverage-baseline.js`.
+ *
+ * @param {string} cwd
+ * @param {{
+ *   fullScope: boolean,
+ *   diffScopeRef: string | null,
+ *   loadScope: (cwd: string) => { include?: string[], exclude?: string[] },
+ *   readCaptureScope?: typeof readArtifactCaptureScope,
+ *   readCoverage?: typeof readCoverageFinal,
+ *   existsSync?: typeof fs.existsSync,
+ *   deriveDiff?: typeof deriveScopeFromDiff,
+ * }} opts
+ */
+export function resolveUpdaterRefreshScope(
+  cwd,
+  {
+    fullScope,
+    diffScopeRef,
+    loadScope,
+    readCaptureScope = readArtifactCaptureScope,
+    readCoverage = readCoverageFinal,
+    existsSync = fs.existsSync,
+    deriveDiff = deriveScopeFromDiff,
+  },
+) {
+  const c8 = () => {
+    const config = loadScope(cwd);
+    return buildScopePredicate({
+      include: config.include ?? [],
+      exclude: config.exclude ?? [],
+    });
+  };
+  return resolveCoverageRefreshScope({
+    cwd,
+    fullScope,
+    diffScopeRef,
+    readCaptureScope,
+    listMeasured: () =>
+      Object.keys(
+        scoreCoverageFinal({ raw: readCoverage(cwd), cwd, scope: c8() }),
+      ),
+    inCoverageScope: (file) =>
+      c8()(file) && existsSync(path.resolve(cwd, file)),
+    deriveDiffFiles: (baseRef) =>
+      deriveDiff({ baseRef, headRef: 'HEAD', predicate: () => true, cwd }),
+  });
+}