mandrel 2.66.0 → 2.68.0

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/drain-pending-cleanup.js

@@ -8,10 +8,11 @@
  * any still-stuck entries by enumerating the processes holding handles
  * inside the worktree path and terminating them.
  *
- * Invoked by `/mandrel-deliver` and `/mandrel-plan`
- * (via `drainPendingCleanupAtBoot` → `worktree-sweep.js`), and
- * `story-close` so the pending-cleanup ledger drains automatically
- * across the sprint lifecycle. Operators can also run it standalone:
+ * The same drain runs automatically at workflow boot: `runBootSweep`
+ * (`boot-sweep.js`) calls `sweepStaleStoryWorktrees`
+ * (`lib/orchestration/plan-runner/worktree-sweep.js`), which force-drains
+ * the ledger before reaping closed-Story worktrees. Operators can also run
+ * it standalone:
  *
  *   node .agents/scripts/drain-pending-cleanup.js              # full drain + escalate
  *   node .agents/scripts/drain-pending-cleanup.js --no-escalate  # passive drain only

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 }),
+  });
+}

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

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

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

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