mandrel 2.66.0 → 2.68.0

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

@@ -4,7 +4,8 @@
  */
 
 import { getQuality } from '../config/quality.js';
-import { FULL_SUITE_LOCK_EXPIRY_ENV } from '../full-suite-lock.js';
+import { COVERAGE_TIMEOUT_EXIT_CODE } from '../coverage-capture.js';
+import { LOCK_WAIT_EXPIRED_EXIT_CODE } from '../full-suite-lock.js';
 import { gitSpawn } from '../git-utils.js';
 import {
   recordPass as defaultRecordPass,
@@ -16,13 +17,49 @@ import {
   isFormatterEligible,
   listChangedFilesForFormatGate,
 } from './commands.js';
-import { DEFAULT_GATES, partitionGates } from './gates.js';
+import { DEFAULT_GATES, GATE_TIMEOUT_HINT, partitionGates } from './gates.js';
 import { defaultGateRunner } from './process.js';
 import { runProjectionAdvisories as defaultRunProjections } from './projections/advisories.js';
 import { defaultGetHeadSha } from './projections/head-sha.js';
 
 /** @typedef {import('./gates.js').Gate} Gate */
 
+/**
+ * Classify a non-zero gate exit and log it as what it is: `75` is an expired
+ * full-suite lock wait (nothing ran), `124` a killed suite (no verdict), and
+ * anything else a real failure with the gate's own hint. Returns the
+ * `failed[]` entry, carrying `outcome` so callers never re-derive it; its
+ * `gate.hint` is the one that fits the outcome (none when deferred), so a
+ * caller replaying it never prints the failing-tests hint for a non-failure.
+ *
+ * @param {{ gate: Gate, status: number, cwd: string, log: (m: string) => void }} args
+ * @returns {{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'failed' }}
+ */
+function reportGateExit({ gate, status, cwd, log }) {
+  if (status === LOCK_WAIT_EXPIRED_EXIT_CODE) {
+    log(
+      `[close-validation] ⏸ ${gate.name} deferred (exit ${status}) — the full-suite lock wait expired, so nothing ran in ${cwd}`,
+    );
+    const { hint: _failureHint, ...deferredGate } = gate;
+    return { gate: deferredGate, status, cwd, outcome: 'deferred' };
+  }
+  if (status === COVERAGE_TIMEOUT_EXIT_CODE) {
+    log(
+      `[close-validation] ⏱ ${gate.name} timed out (exit ${status}) in ${cwd}`,
+    );
+    log(`[close-validation]   hint: ${GATE_TIMEOUT_HINT}`);
+    return {
+      gate: { ...gate, hint: GATE_TIMEOUT_HINT },
+      status,
+      cwd,
+      outcome: 'timeout',
+    };
+  }
+  log(`[close-validation] ✖ ${gate.name} failed (exit ${status}) in ${cwd}`);
+  if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+  return { gate, status, cwd, outcome: 'failed' };
+}
+
 function applyChangedFileScope({ gate, spawnCwd, log }) {
   // A skip decided when the gate list was built wins over everything.
   if (gate.skip) {
@@ -95,10 +132,10 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  *   getTreeFingerprint?: (cwd: string) => string|null,
  *   recordPass?: typeof defaultRecordPass,
  *   shouldSkip?: typeof defaultShouldSkip,
- *   deferOnLockExpiry?: boolean,
- * }} opts `deferOnLockExpiry`: an expired full-suite lock wait spawns
- *   nothing (here or in any gate child) and reports `LOCK_WAIT_EXPIRED_EXIT_CODE`.
- * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string }>, skipped: Array<{ gate: Gate, reason: string }> }}
+ * }} opts An expired full-suite lock wait spawns nothing (here or in any gate
+ *   child) and reports `LOCK_WAIT_EXPIRED_EXIT_CODE`.
+ * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'failed' }>, skipped: Array<{ gate: Gate, reason: string }> }}
+ *   `outcome` classifies the exit: `deferred` (75), `timeout` (124), else `failed`.
  */
 export async function runCloseValidation({
   cwd,
@@ -120,10 +157,9 @@ export async function runCloseValidation({
     defaultTreeFingerprint(resolvedCwd, gitSpawn),
   recordPass = defaultRecordPass,
   shouldSkip = defaultShouldSkip,
-  deferOnLockExpiry = false,
 } = {}) {
   const failed = [];
-  const lockOpts = fullSuiteLockOptions({ config, deferOnLockExpiry });
+  const lockOpts = fullSuiteLockOptions({ config });
   const skipped = [];
   const evidenceActive = useEvidence && storyId != null && standalone;
   const evidenceStoreOpts = { cwd, standalone };
@@ -228,7 +264,7 @@ export async function runCloseValidation({
       execution = applyChangedFileScope({ gate, spawnCwd, log });
     } catch (err) {
       if (!firstIndepFailure) {
-        firstIndepFailure = { gate, status: 1, cwd: spawnCwd };
+        firstIndepFailure = { gate, status: 1 };
         log(
           `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
         );
@@ -271,7 +307,7 @@ export async function runCloseValidation({
     }
     if (result.status !== 0) {
       if (!firstIndepFailure) {
-        firstIndepFailure = { gate, status: result.status, cwd: spawnCwd };
+        firstIndepFailure = { gate, status: result.status };
         ac.abort();
       }
       return;
@@ -287,13 +323,8 @@ export async function runCloseValidation({
   await Promise.all(indepTasks);
 
   if (firstIndepFailure) {
-    failed.push(firstIndepFailure);
-    log(
-      `[close-validation] ✖ ${firstIndepFailure.gate.name} failed (exit ${firstIndepFailure.status}) in ${spawnCwd}`,
-    );
-    if (firstIndepFailure.gate.hint) {
-      log(`[close-validation]   hint: ${firstIndepFailure.gate.hint}`);
-    }
+    const { gate, status } = firstIndepFailure;
+    failed.push(reportGateExit({ gate, status, cwd: spawnCwd, log }));
     return { ok: false, failed, skipped };
   }
 
@@ -324,29 +355,36 @@ export async function runCloseValidation({
 }
 
 /**
- * The `fullSuiteLock` gate shares coverage capture's timeout so a hung suite
- * fails instead of holding the host lock. Under `deferOnLockExpiry` every
- * gate child inherits the defer opt-in via env.
+ * The `fullSuiteLock` gate shares coverage capture's timeout
+ * (`coverage.timeoutMs`) so a hung suite fails instead of holding the host
+ * lock; the same figure bounds its lock wait (`resolveFullSuiteLockBudget`).
  *
- * @param {{ config: object|null, deferOnLockExpiry: boolean }} args
+ * @param {{ config: object|null }} args
  * @returns {{ forGate: (gate: object) => object }}
  */
-function fullSuiteLockOptions({ config, deferOnLockExpiry }) {
+function fullSuiteLockOptions({ config }) {
   const timeoutMs = getQuality(config).coverage?.timeoutMs;
-  const deferEnv = deferOnLockExpiry
-    ? { [FULL_SUITE_LOCK_EXPIRY_ENV]: 'defer' }
-    : null;
   return {
     forGate(gate) {
-      const env = deferEnv ? { ...gate.env, ...deferEnv } : gate.env;
       return {
-        ...(env ? { env } : {}),
-        ...(gate.fullSuiteLock ? { timeoutMs, deferOnLockExpiry } : {}),
+        ...(gate.env ? { env: gate.env } : {}),
+        ...(gate.fullSuiteLock ? fullSuiteGateOptions(gate, timeoutMs) : {}),
       };
     },
   };
 }
 
+/**
+ * A full-suite gate's kill bound, and the command its lock-expiry line names.
+ *
+ * @param {{ cmd: string, args?: string[] }} gate
+ * @param {number} timeoutMs
+ */
+function fullSuiteGateOptions(gate, timeoutMs) {
+  const rerunCommand = [gate.cmd, ...(gate.args ?? [])].join(' ');
+  return { timeoutMs, lockOptions: { rerunCommand } };
+}
+
 /**
  * Mutates the caller's `failed` / `skipped` accumulators.
  *
@@ -368,21 +406,18 @@ async function runSerialGates(
     dispatchGate,
   },
 ) {
-  const failGate = (gate, status, message) => {
-    failed.push({ gate, status, cwd: spawnCwd });
-    log(message);
-    if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+  const failGate = (gate, status) => {
+    failed.push(reportGateExit({ gate, status, cwd: spawnCwd, log }));
   };
   for (const gate of serial) {
     let execution;
     try {
       execution = applyChangedFileScope({ gate, spawnCwd, log });
     } catch (err) {
-      failGate(
-        gate,
-        1,
+      log(
         `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
       );
+      failGate(gate, 1);
       return;
     }
     if (execution.skip) {
@@ -414,11 +449,7 @@ async function runSerialGates(
       configHash,
     );
     if (result.status !== 0) {
-      failGate(
-        gate,
-        result.status,
-        `[close-validation] ✖ ${gate.name} failed (exit ${result.status}) in ${spawnCwd}`,
-      );
+      failGate(gate, result.status);
       return;
     }
     log(`[close-validation] ✓ ${gate.name}`);

package/.agents/scripts/lib/config/gates/coverage.schema.js

@@ -3,6 +3,12 @@
 import { COVERAGE_GATE_DEFAULTS } from '../quality.js';
 import { gateBase, SAFE_STRING } from './shared.js';
 
+/** Schema bounds on `coverage.timeoutMs`: one minute to two hours. */
+export const COVERAGE_TIMEOUT_BOUNDS = Object.freeze({
+  min: 60_000,
+  max: 7_200_000,
+});
+
 export const COVERAGE_GATE = {
   type: 'object',
   description:
@@ -21,6 +27,21 @@ export const COVERAGE_GATE = {
         'Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads.',
       default: COVERAGE_GATE_DEFAULTS.coveragePath,
     },
+    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: COVERAGE_GATE_DEFAULTS.captureScope,
+    },
+    timeoutMs: {
+      type: 'integer',
+      minimum: COVERAGE_TIMEOUT_BOUNDS.min,
+      maximum: COVERAGE_TIMEOUT_BOUNDS.max,
+      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: COVERAGE_GATE_DEFAULTS.timeoutMs,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/quality.js

@@ -66,6 +66,8 @@ export const COVERAGE_GATE_DEFAULTS = Object.freeze({
   tolerance: Object.freeze({ kind: 'absolute', value: 0 }),
   floors: DEFAULT_COVERAGE_FLOORS,
   coveragePath: 'coverage/coverage-final.json',
+  // `affected` runs the consumer's `test:coverage:affected` instead.
+  captureScope: 'full',
   // On expiry `runCapture` exits 124 so callers can tell a hang from a failure.
   timeoutMs: 600_000,
 });
@@ -101,6 +103,8 @@ const COVERAGE_GATE_KEYS = new Set([
   'tolerance',
   'floors',
   'coveragePath',
+  'captureScope',
+  'timeoutMs',
 ]);
 
 const MI_GATE_KEYS = new Set([
@@ -265,6 +269,7 @@ function resolveCoverageGate(userBlock) {
       enabled: defaults.enabled,
       baselinePath: defaults.baselinePath,
       coveragePath: defaults.coveragePath,
+      captureScope: defaults.captureScope,
       tolerance: toleranceScalar(defaults.tolerance, 0),
       timeoutMs: defaults.timeoutMs,
     };
@@ -274,11 +279,12 @@ function resolveCoverageGate(userBlock) {
     enabled: userBlock.enabled ?? defaults.enabled,
     baselinePath: userBlock.baselinePath ?? defaults.baselinePath,
     coveragePath: userBlock.coveragePath ?? defaults.coveragePath,
+    captureScope: userBlock.captureScope ?? defaults.captureScope,
     tolerance: toleranceScalar(
       userBlock.tolerance,
       toleranceScalar(defaults.tolerance, 0),
     ),
-    timeoutMs: defaults.timeoutMs,
+    timeoutMs: userBlock.timeoutMs ?? defaults.timeoutMs,
   };
 }
 

package/.agents/scripts/lib/config/temp-paths.js

@@ -214,6 +214,21 @@ export function storyTerminalEnvelopePath(sid, config) {
   return path.join(orchestrationLogDir(config), storyTerminalEnvelopeName(sid));
 }
 
+/**
+ * The worker's held Story-scope review, beside the terminal envelope so the
+ * close that adopts it reads it from the same anchored directory.
+ *
+ * @param {number} sid
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function storyReviewDepositPath(sid, config) {
+  return path.join(
+    orchestrationLogDir(config),
+    `story-review-${storyId(sid)}.json`,
+  );
+}
+
 const runId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -25,7 +25,7 @@ const EXECUTION_SCHEMA = {
     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.',
+        '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,
     },
   },
@@ -283,8 +283,9 @@ const TEMP_RETENTION_SCHEMA = {
   description:
     '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 operator scratch files under tempRoot are reported with their ' +
-    'size and left alone. signals.ndjson is never purged by any path.',
+    '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.',
   properties: {
     enabled: {
       type: 'boolean',
@@ -326,6 +327,14 @@ const TEMP_RETENTION_SCHEMA = {
             'Age-floored only; the current run is always excluded.',
           default: true,
         },
+        scratch: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/scratch/ — agent-authored scratch. ' +
+            '`scratch/story-<id>/` is purged when that Story lands; any ' +
+            'other `scratch/` entry is age-floored.',
+          default: true,
+        },
       },
       additionalProperties: false,
     },

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

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import picomatch from 'picomatch';
 import { write, writeFile } from './baselines/writer.js';
+import { captureStampPath } from './coverage-capture.js';
 
 const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
 export const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
@@ -202,20 +203,64 @@ export function axisToleranceFor(
   return Math.max(baseTolerance, eventResolution * NOISE_EVENT_HEADROOM);
 }
 
+/** The capture stamp's scope; `full` when absent, unreadable or unscoped. */
+export function readArtifactCaptureScope(
+  cwd,
+  coveragePath = COVERAGE_FINAL_PATH,
+  fsImpl = fs,
+) {
+  try {
+    const stamp = JSON.parse(
+      fsImpl.readFileSync(captureStampPath(cwd, coveragePath), 'utf8'),
+    );
+    return typeof stamp?.scope === 'string' ? stamp.scope : 'full';
+  } catch {
+    return 'full';
+  }
+}
+
+/**
+ * Narrow a refresh scope (`null` = full) to measured files, keeping any file
+ * `mustMeasure` names so its missing row fails the refresh.
+ */
+function narrowScopeToMeasured(scopeFiles, measuredFiles, mustMeasure) {
+  if (scopeFiles === null) return [...measuredFiles];
+  const measured = new Set(measuredFiles);
+  return scopeFiles.filter((file) => measured.has(file) || mustMeasure(file));
+}
+
+/**
+ * Baseline rows absent from `current`. From a full artifact they are removed
+ * files. From an `affected` artifact they are unmeasured and not reported,
+ * except a changed file: that one fails closed as new, as does a changed
+ * file with no baseline row the scoped run skipped.
+ */
+function classifyAbsent(current, baseline, { artifactScope, changedFiles }) {
+  const absent = Object.keys(baseline).filter((f) => current[f] === undefined);
+  if (artifactScope !== 'affected') {
+    return { removedFiles: absent.map((file) => ({ file })), unmeasured: [] };
+  }
+  const unmeasured = (changedFiles ?? [])
+    .filter((file) => current[file] === undefined)
+    .map((file) => ({ file, current: null, reason: 'unmeasured' }));
+  return { removedFiles: [], unmeasured };
+}
+
 /**
  * Classify files: `regressions` (an axis dropped beyond tolerance) and
  * `newFiles` (else untested code lands at 0%) fail the CLI; `removedFiles`
- * and `improvements` are reported only.
+ * and `improvements` are reported only. `opts.artifactScope: 'affected'`
+ * with the in-scope `opts.changedFiles` reads absent rows as unmeasured.
  */
 export function compareScores(
   current,
   baseline,
   tolerance = COVERAGE_TOLERANCE,
+  opts = {},
 ) {
   const regressions = [];
   const newFiles = [];
   const improvements = [];
-  const removedFiles = [];
 
   for (const [file, scores] of Object.entries(current)) {
     const base = baseline[file];
@@ -252,9 +297,37 @@ export function compareScores(
       improvements.push({ file });
     }
   }
-  for (const file of Object.keys(baseline)) {
-    if (current[file] === undefined) removedFiles.push({ file });
-  }
+  const { removedFiles, unmeasured } = classifyAbsent(current, baseline, opts);
+  newFiles.push(...unmeasured);
 
   return { regressions, newFiles, improvements, removedFiles };
 }
+
+/**
+ * `refreshBaseline` scope options. Under an `affected` artifact the scope is
+ * narrowed to measured files, so the scope merge preserves a row the scoped
+ * run skipped instead of deleting it. A changed file `inCoverageScope` names
+ * stays in scope and must produce a row: skipping it fails closed.
+ */
+export async function resolveCoverageRefreshScope({
+  cwd,
+  fullScope,
+  diffScopeRef,
+  readCaptureScope,
+  listMeasured,
+  inCoverageScope,
+  deriveDiffFiles,
+}) {
+  if (readCaptureScope(cwd) !== 'affected') {
+    if (fullScope) return { fullScope: true };
+    return diffScopeRef ? { baseRef: diffScopeRef } : {};
+  }
+  const diff = fullScope
+    ? null
+    : await deriveDiffFiles(diffScopeRef ?? 'origin/main');
+  return {
+    scopeFiles: narrowScopeToMeasured(diff, listMeasured(cwd), inCoverageScope),
+    requireRowsForScopeFiles: true,
+    requiredScopeFilePredicate: inCoverageScope,
+  };
+}