mandrel 2.24.0 → 2.26.0

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

@@ -29,52 +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.
@@ -165,8 +147,18 @@ export function runTestSuite({
   cleanup = cleanupRepoTestTempArtifacts,
   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);
 
@@ -192,6 +184,14 @@ export function runTestSuite({
 
   cleanup({ repoRoot: cwd });
 
+  // A test that spawns a real CLI at the repository root inherits the real
+  // state directory, so its fixture telemetry can land in the operator's live
+  // signals tree — where the retro graduator counts it as recurrence evidence
+  // and files a ticket citing a fixture Story id. Fail the run that caused it
+  // rather than discovering it from that ticket.
+  const polluted = fixtureStreamGuard({ cwd });
+  if (polluted !== 0 && status === 0) status = polluted;
+
   if (spawnError) {
     throw spawnError;
   }

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,11 +95,12 @@
  * @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';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { resolveRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
 import {
   failedTerminalFor,
   gatesForFailedPhase,
@@ -123,12 +134,17 @@ export const enableAutoMerge = enableAutoMergeWith;
 // `gatesForFailedPhase` now lives beside the envelope it feeds
 // (`single-story-close/failed-terminal.js`); it is re-exported here so the
 // CLI's public surface is unchanged by that move.
+// `resolveRunScopedConfig` (Story #4891) is the run-scoped config pin the
+// pipeline reads before its first phase; it is part of this CLI's surface for
+// the same reason the sync helpers are — the runner reaches it only through a
+// dynamic import, so this file is where it is statically visible.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
   gatesForFailedPhase,
   handleSyncFailure,
   parsePrNumber,
+  resolveRunScopedConfig,
   runStoryScopeReview,
 };
 
@@ -145,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.
@@ -185,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:

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

@@ -61,6 +61,7 @@ import {
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
 import { verifyRemote } from './lib/orchestration/remote-verifier.js';
+import { pinRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
 import {
   acquireStoryLease,
   releaseStoryLease,
@@ -735,6 +736,11 @@ export async function runSingleStoryInit({
     standalone: true,
     storyBranch,
     baseBranch,
+    // The write half of the run-scoped config pin. `baseBranch` above is the
+    // legacy field close still reads as a fallback; this block is the
+    // registry-driven form a second run-scoped key joins without a second
+    // mechanism (`lib/orchestration/run-scoped-config.js`).
+    runScopedConfig: pinRunScopedConfig(config),
     storyTitle: story.title,
     worktreeEnabled: runtime.worktreeEnabled,
     workCwd,
@@ -805,6 +811,7 @@ export function renderSingleStoryInitComment(result) {
     standalone: true,
     storyBranch: result.storyBranch,
     baseBranch: result.baseBranch,
+    runScopedConfig: result.runScopedConfig,
     worktreeEnabled: result.worktreeEnabled,
     workCwd: result.workCwd,
     worktreeCreated: result.worktreeCreated,