mandrel 2.25.0 → 2.26.0

package/.agents/scripts/resolve-stories.js

@@ -24,6 +24,7 @@
  *
  * Usage:
  *   node .agents/scripts/resolve-stories.js --ids 101,102
+ *   node .agents/scripts/resolve-stories.js --ids 101-104        # inclusive range
  *   node .agents/scripts/resolve-stories.js --ids 101,102 --pretty
  *   node .agents/scripts/resolve-stories.js --ids 101 --no-native   # skip the dependencies API
  *
@@ -65,7 +66,9 @@ blocked_by edges, with every blocker (in-set or foreign) resolved against its
 real issue state.
 
 Options:
-  --ids <csv>    Comma-separated Story issue numbers. Required.
+  --ids <csv>    Comma-separated Story issue numbers. Required. A token may be
+                 a single id (4922) or an inclusive dash range (4922-4926);
+                 ranges expand in place and dedupe against the rest.
   --pretty       Pretty-print the JSON envelope.
   --no-native    Skip the native blocked_by read (body edges only).
   --help         Show this help.

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

@@ -10,8 +10,16 @@
  * Node script keeps the env injection portable.
  *
  * Pipeline:
+ *   0. Run the full tier's preflight (`runTierPreflight`). Story #4936: this
+ *      used to be a `pretest:coverage` npm script that CI had to name
+ *      explicitly, because `.npmrc`'s `ignore-scripts=true` (CWE-1357
+ *      defence, which stays) suppresses every `pre*` hook. The runner
+ *      invokes it now, so it executes however the coverage run is started.
  *   1. Run the test suite under `NODE_V8_COVERAGE` so each worker writes
- *      raw V8 dumps under `coverage/tmp/`.
+ *      raw V8 dumps under `coverage/tmp/`. The suite targets are the
+ *      shared `FULL_TIER_GLOBS` from `lib/test-tiers.js` — the same set
+ *      `run-tests.js` walks — so the measured surface and `npm test`'s
+ *      surface are the same set by construction.
  *   2. `c8 report` post-processes the dumps into `coverage/coverage-final.json`
  *      plus the printed text table. Include/exclude scope from `.c8rc.cjs`
  *      is passed explicitly because `c8 report` does not auto-load the
@@ -28,13 +36,15 @@
  * while producing an identical `coverage-final.json` artifact for the
  * CRAP gate.
  *
- * Test-runner concurrency: the suite spawn reuses `TEST_RUNNER_FLAGS`
- * from `run-tests.js` — the single source of truth for the
- * `--test-concurrency` value, derived at startup from the host's
- * available parallelism and clamped to `[TEST_CONCURRENCY_MIN,
- * TEST_CONCURRENCY_MAX]`. This keeps the coverage gate (which runs the
- * suite at every story close on both delivery paths) host-aware instead
- * of pinned to the historical literal of 8.
+ * Test-runner flags: the suite spawn reuses `TEST_RUNNER_FLAGS` from
+ * `lib/test-runner-contract.js` — the single source of truth for the
+ * `node --test` flag set, including the host-derived
+ * `--test-concurrency` value clamped to `[TEST_CONCURRENCY_MIN,
+ * TEST_CONCURRENCY_MAX]`. Story #4936: sharing the whole flag set (not
+ * just the concurrency number) is what stops this runner and
+ * `run-tests.js` disagreeing about whether a test can execute at all —
+ * `--experimental-test-module-mocks` decides whether `t.mock.module`
+ * works, and this is the *required* CI job.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -46,56 +56,90 @@ import { fileURLToPath } from 'node:url';
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { C8_CLI } from './lib/c8-cli-path.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
-import { TEST_RUNNER_FLAGS } from './run-tests.js';
+import {
+  runTierPreflight,
+  TEST_RUNNER_FLAGS,
+} from './lib/test-runner-contract.js';
+import { FULL_TIER_GLOBS } from './lib/test-tiers.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
-const COVERAGE_DIR = path.join(ROOT, 'coverage');
 const require = createRequire(import.meta.url);
 const C8_CONFIG = require('../../.c8rc.cjs');
-const V8_TMP = path.join(COVERAGE_DIR, 'tmp');
 
 /**
  * Build the `node --test` argv for the coverage suite spawn.
  *
- * Reuses the shared `TEST_RUNNER_FLAGS` (the single source of truth for
- * the host-aware, clamped `--test-concurrency` value) so the coverage
- * path never drifts from `run-tests.js`. The `runnerFlags` parameter is
- * injected in tests so the argv can be asserted without touching the OS.
+ * Reuses two shared constants so the coverage path cannot drift from
+ * `run-tests.js`:
+ *
+ *   - `TEST_RUNNER_FLAGS` — the single source of truth for the host-aware,
+ *     clamped `--test-concurrency` value.
+ *   - `FULL_TIER_GLOBS` — the single source of truth for *which files the
+ *     full tier runs*. Story #4922: this script used to restate
+ *     `tests/**\/*.test.js` on its own, so the 47 colocated `__tests__`
+ *     suites under `lib/` and `.agents/scripts/` executed under `npm test`
+ *     but never under the measuring run — the coverage and CRAP numbers
+ *     were computed over code the coverage run had not executed.
+ *
+ * Both parameters are injected in tests so the argv can be asserted without
+ * touching the OS.
  *
  * @param {object} [opts]
  * @param {readonly string[]} [opts.runnerFlags]
- * @param {string} [opts.testGlob]
+ * @param {readonly string[]} [opts.testGlobs]
  * @returns {string[]}
  */
 export function buildCoverageTestArgs({
   runnerFlags = TEST_RUNNER_FLAGS,
-  testGlob = 'tests/**/*.test.js',
+  testGlobs = FULL_TIER_GLOBS,
 } = {}) {
-  return [...runnerFlags, testGlob];
+  return [...runnerFlags, ...testGlobs];
 }
 
 /**
- * Execute the coverage pipeline: run the suite under `NODE_V8_COVERAGE`,
- * post-process the dumps with `c8 report`, then gate on the coverage
- * baseline. Returns the first non-zero exit code across the three stages
- * (or the baseline check's status when both prior stages pass).
+ * Execute the coverage pipeline: run the full tier's preflight, run the
+ * suite under `NODE_V8_COVERAGE`, post-process the dumps with `c8 report`,
+ * then gate on the coverage baseline. Returns the first non-zero exit code
+ * across the stages (or the baseline check's status when the prior stages
+ * pass); a refused preflight short-circuits before anything is spawned or
+ * removed.
  *
+ * Every collaborator is injected so the pipeline's wiring — above all
+ * *that the preflight actually runs, and runs first* — is assertable
+ * without spawning the real suite.
+ *
+ * @param {object} [opts]
+ * @param {typeof spawnSync} [opts.spawn]
+ * @param {(opts: { tier: string, repoRoot: string }) => number} [opts.preflight]
+ * @param {(opts: { repoRoot: string }) => unknown} [opts.cleanup]
+ * @param {string} [opts.repoRoot]
  * @returns {number}
  */
-function runCoveragePipeline() {
-  rmSync(COVERAGE_DIR, { recursive: true, force: true });
-  mkdirSync(V8_TMP, { recursive: true });
+export function runCoveragePipeline({
+  spawn = spawnSync,
+  preflight = runTierPreflight,
+  cleanup = cleanupRepoTestTempArtifacts,
+  repoRoot = ROOT,
+} = {}) {
+  const coverageDir = path.join(repoRoot, 'coverage');
+  const v8Tmp = path.join(coverageDir, 'tmp');
+
+  const preflightStatus = preflight({ tier: 'full', repoRoot });
+  if (preflightStatus !== 0) return preflightStatus;
 
-  const testRun = spawnSync(process.execPath, buildCoverageTestArgs(), {
-    cwd: ROOT,
+  rmSync(coverageDir, { recursive: true, force: true });
+  mkdirSync(v8Tmp, { recursive: true });
+
+  const testRun = spawn(process.execPath, buildCoverageTestArgs(), {
+    cwd: repoRoot,
     stdio: 'inherit',
     // GIT_*-scrubbed: under a husky pre-push from a linked worktree the
     // inherited GIT_DIR poisons fixture `git init` runs (#4580).
-    env: { ...buildWebhookSafeTestEnv(process.env), NODE_V8_COVERAGE: V8_TMP },
+    env: { ...buildWebhookSafeTestEnv(process.env), NODE_V8_COVERAGE: v8Tmp },
   });
 
-  cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
+  cleanup({ repoRoot });
 
   const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => [
     '--include',
@@ -106,29 +150,36 @@ function runCoveragePipeline() {
     p,
   ]);
 
-  const reportRun = spawnSync(
+  // `c8 report` does not auto-load `.c8rc.cjs`, so every scope knob it needs
+  // is forwarded explicitly from the config object — including `all`, which
+  // is what puts a 0 % row on a source file no test ever loaded (Story
+  // #4922). Reading it off the config keeps `.c8rc.cjs` the one declaration.
+  const allArgs = C8_CONFIG.all ? ['--all'] : [];
+
+  const reportRun = spawn(
     process.execPath,
     [
       C8_CLI,
       'report',
       '--reporter=json',
       '--reporter=text',
+      ...allArgs,
       '--temp-directory',
-      V8_TMP,
+      v8Tmp,
       ...includeArgs,
       ...excludeArgs,
     ],
-    { cwd: ROOT, stdio: 'inherit', shell: false },
+    { cwd: repoRoot, stdio: 'inherit', shell: false },
   );
 
-  const checkRun = spawnSync(
+  const checkRun = spawn(
     process.execPath,
     [
-      path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
+      path.join(repoRoot, '.agents', 'scripts', 'check-baselines.js'),
       '--gate',
       'coverage',
     ],
-    { cwd: ROOT, stdio: 'inherit' },
+    { cwd: repoRoot, stdio: 'inherit' },
   );
 
   return testRun.status !== 0

package/.agents/scripts/run-lint.js

@@ -28,11 +28,20 @@ const tasks = [
     args: ['biome', 'ci', '.'],
   },
   {
+    // `docs/**/*.md` sat outside these globs until PR #4970's follow-up,
+    // so `npm run lint` reported "0 error(s)" while the close-time
+    // code-review lens — which lints the whole changed surface, not just
+    // what this driver globs — raised pre-existing `docs/` violations
+    // against whichever Story happened to touch the file. Keep `docs/`
+    // here so the two surfaces agree. `docs/CHANGELOG.md` is linted too;
+    // the generator-owned rules it can never satisfy are exempted by a
+    // `markdownlint-disable-file` directive in its own header.
     name: 'markdownlint',
     cmd: 'npx',
     args: [
       'markdownlint-cli2',
       '.agents/**/*.md',
+      'docs/**/*.md',
       '*.md',
       '!node_modules/**',
       '!.worktrees/**',
@@ -79,6 +88,17 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],
   },
+  {
+    // GitHub Actions job-timeout gate (Story #4936). Enumerates every
+    // `jobs.<id>` key across `.github/workflows/*.yml` and fails when one
+    // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or
+    // sets one above the ceiling. A deadlocked Windows job burned 44 minutes
+    // of a runner and withheld the failing required check's logs for the
+    // whole time; nothing but this check would have caught the gap.
+    name: 'workflow-timeouts',
+    cmd: 'node',
+    args: ['.agents/scripts/check-workflow-timeouts.js'],
+  },
   {
     // Architecture cycle ratchet (Story #3991). Detects directed import
     // cycles under `.agents/scripts/` and fails on any cycle not in the

package/.agents/scripts/run-tests.js

@@ -29,53 +29,34 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
+import {
+  resolveTestConcurrency,
+  runTierPreflight,
+  TEST_CONCURRENCY_MAX,
+  TEST_CONCURRENCY_MIN,
+  TEST_RUNNER_FLAGS,
+} from './lib/test-runner-contract.js';
 import { listTestFilesForTier, parseTierArgv } from './lib/test-tiers.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
 
-/** Minimum and maximum bounds for `--test-concurrency`. */
-export const TEST_CONCURRENCY_MIN = 1;
-export const TEST_CONCURRENCY_MAX = 16;
-
-/**
- * Resolve the `--test-concurrency` value for the current host.
- *
- * Uses `os.availableParallelism()` (Node ≥18.14 / ≥20.0) clamped to the
- * range `[TEST_CONCURRENCY_MIN, TEST_CONCURRENCY_MAX]`.  The `parallelism`
- * parameter is injected in tests so the clamping logic is verifiable
- * without touching the OS.
- *
- * @param {number} [parallelism] - defaults to `os.availableParallelism()`
- * @returns {number}
- */
-export function resolveTestConcurrency(
-  parallelism = os.availableParallelism(),
-) {
-  return Math.min(
-    TEST_CONCURRENCY_MAX,
-    Math.max(TEST_CONCURRENCY_MIN, parallelism),
-  );
-}
-
-/**
- * Fixed `node --test` flags applied to every spawn (every chunk).
- * `--test-concurrency` is derived at startup from the host's available
- * parallelism so the value is appropriate for the machine running the suite
- * rather than being pinned to the historical constant of 8.
- */
-export const TEST_RUNNER_FLAGS = Object.freeze([
-  '--experimental-test-module-mocks',
-  '--test',
-  `--test-concurrency=${resolveTestConcurrency()}`,
-]);
+// The runner contract (flag set, concurrency clamp, tier preflight) is
+// declared once in `lib/test-runner-contract.js` so `run-coverage.js` shares
+// it by construction. Re-exported here because this module is the runner's
+// public face for its own unit tests.
+export {
+  resolveTestConcurrency,
+  TEST_CONCURRENCY_MAX,
+  TEST_CONCURRENCY_MIN,
+  TEST_RUNNER_FLAGS,
+};
 
 /**
  * Per-spawn character budget for the joined *targets* portion of the argv.
@@ -167,8 +148,17 @@ export function runTestSuite({
   listTargets = listTestFilesForTier,
   maxTargetChars = resolveMaxTargetChars(),
   fixtureStreamGuard = assertNoReservedIdStreams,
+  preflight = runTierPreflight,
 } = {}) {
   const { tier, rest } = parseTierArgv(argv);
+
+  // Preflight first, and abort on refusal — the tier's checks exist to stop
+  // the suite starting from a known-bad state, so running them after the
+  // spawn would be pointless. Nothing has been created yet, so there is
+  // nothing to clean up on this path.
+  const preflightStatus = preflight({ tier, repoRoot: cwd });
+  if (preflightStatus !== 0) return preflightStatus;
+
   const targets = listTargets(tier, cwd);
   const chunks = chunkTestTargets(targets, maxTargetChars);
 

package/.agents/scripts/single-story-close.js

@@ -43,6 +43,16 @@
  *                              [--skip-validation] [--skip-sync]
  *                              [--no-auto-merge]
  *                              [--wait-merge | --no-wait-merge]
+ *                              [--merge-watch-mode <sync|async>]
+ *
+ * `--merge-watch-mode` (Story #4949) overrides `delivery.mergeWatch.mode` for
+ * one invocation, on the same explicit-wins-over-config precedence
+ * `--max-wait-seconds` uses, and the two compose. It exists because run
+ * topology is invisible from inside close: a solo delivery is cheapest waiting
+ * in the foreground, while the Nth close of a wave pays that wait as
+ * serialized dead time. The config default therefore stays `sync` and the
+ * orchestrator — the only party that knows N — passes `async` per close. An
+ * unrecognized value fails during option parsing, before any phase runs.
  *
  * Close-and-land is the DEFAULT for every run (Story #4428 introduced it as
  * `--wait-merge`; `delivery.routing.closeAndLand` — default `true` — made it
@@ -85,7 +95,7 @@
  * @see .agents/schemas/story-deliver-terminal.schema.json
  */
 
-import { parseSprintArgs } from './lib/cli-args.js';
+import { parseSprintArgsTolerant } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
@@ -151,13 +161,25 @@ export async function runSingleStoryClose(opts) {
  * status rather than from a thrown/not-thrown distinction, so `pending`
  * (resumable) is distinguishable from `blocked` (come look) without parsing
  * stdout.
+ *
+ * The catch parses argv through the **non-throwing** wrapper (Story #4959).
+ * It used to call `parseSprintArgs()` — re-invoking the very parser that had
+ * just thrown, since `parseMergeWatchMode` made argv parsing fallible. The
+ * second throw escaped the handler, so an unparseable argv produced a bare
+ * stack trace with no envelope and no friction signal, on the surface whose
+ * whole contract is that every invocation emits exactly one envelope. An
+ * error handler may not depend on an operation already known to fail.
+ *
+ * A parse rejection carries no `closePhase`, so the envelope reports `init` —
+ * accurate: the runner rejected the flag before any phase ran, and nothing
+ * was mutated.
  */
 async function main() {
   try {
     const outcome = await runSingleStoryClose();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    const terminal = failedTerminalFor(err, parseSprintArgs());
+    const terminal = failedTerminalFor(err, parseSprintArgsTolerant().args);
     if (!terminal) throw err;
     // Mirror runAsCli's default error line (which this catch pre-empts) so the
     // human-facing failure text is unchanged, then emit the envelope.
@@ -191,6 +213,10 @@ runAsCli(import.meta.url, main, {
       ['--wait-merge', 'Force the in-close merge wait.'],
       ['--no-wait-merge', 'Return as soon as the PR is open; do not wait.'],
       ['--max-wait-seconds <n>', 'Per-invocation merge-wait bound.'],
+      [
+        '--merge-watch-mode <sync|async>',
+        'Override delivery.mergeWatch.mode for this invocation only. `async` caps the merge wait to a short probe window and returns the resumable `pending` terminal instead of holding the foreground slot — pass it on every close of a multi-Story run. An invalid value exits non-zero before any phase runs.',
+      ],
       ['--no-evidence', 'Do not reuse or write gate evidence stamps.'],
       ['--dry-run', 'Report the plan; mutate nothing.'],
     ],

package/.agents/scripts/single-story-confirm-merge.js

@@ -37,7 +37,7 @@
  */
 
 import { parseArgs } from 'node:util';
-import { parseSprintArgs } from './lib/cli-args.js';
+import { parseSprintArgsTolerant } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { formatCliError } from './lib/error-redactor.js';
@@ -66,6 +66,15 @@ const progress = Logger.createProgress('single-story-confirm-merge', {
   stderr: true,
 });
 
+/**
+ * This CLI's own surface name — the `runAsCli` source, and the `emitter.tool`
+ * every friction record it emits carries. Single-homed so the two cannot
+ * drift: `emitTerminalFriction` defaults to the CLOSE CLI's name, so a record
+ * emitted from here without it is attributed to a CLI that never ran, and the
+ * retro roll-up sends the follow-up to the wrong surface.
+ */
+const CLI_SOURCE = 'single-story-confirm-merge';
+
 /**
  * Default `gh` facade for this CLI, bound to the merge wait's spawn-level
  * timeout (Story #4710). This CLI is the resume surface async mode hands the
@@ -204,7 +213,7 @@ async function logConfirmResult(result, terminal, config) {
     },
   });
   emitTerminalEnvelope(terminal, { config });
-  await emitTerminalFriction({ envelope: terminal, config });
+  await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE, config });
   return { success: terminal.status !== 'failed', result, terminal };
 }
 
@@ -512,14 +521,21 @@ async function main() {
     const outcome = await runConfirmMerge();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    const storyId = Number(parseSprintArgs().storyId);
+    // Non-throwing by construction (Story #4959): this used to call
+    // `parseSprintArgs()`, so a rejected `--merge-watch-mode` threw a second
+    // time here and escaped the handler — no envelope, no friction. Close
+    // carries the identical shape; both landing surfaces behave the same.
+    const { args, error: argvError } = parseSprintArgsTolerant();
+    const storyId = Number(args.storyId);
     // No story id → a usage error; there is nothing to report an envelope
     // about, so let runAsCli surface it as a plain fatal.
     if (!Number.isInteger(storyId) || storyId <= 0) throw err;
     const terminal = buildTerminalEnvelope({
       storyId,
       status: 'failed',
-      phase: 'confirm-merge',
+      // An argv rejection happens before any phase runs, so it reports at
+      // `init` rather than claiming a confirm-merge attempt that never began.
+      phase: argvError ? 'init' : 'confirm-merge',
       failure: { reason: String(err?.message ?? err) },
       nextCommand: NEXT_COMMANDS.recover(storyId),
       elapsedSeconds: 0,
@@ -528,13 +544,13 @@ async function main() {
       `[single-story-confirm-merge] Fatal error: ${formatCliError(err)}`,
     );
     emitTerminalEnvelope(terminal);
-    await emitTerminalFriction({ envelope: terminal });
+    await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE });
     return exitCodeForTerminal(terminal);
   }
 }
 
 runAsCli(import.meta.url, main, {
-  source: 'single-story-confirm-merge',
+  source: CLI_SOURCE,
   propagateExitCode: true,
   usage: {
     invocation: