mandrel 2.60.0 → 2.61.0

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

@@ -2,37 +2,18 @@
 /* node:coverage ignore file */
 
 /**
- * Cross-platform driver for `npm test`.
+ * Cross-platform driver for `npm test`. Cleanup runs in-process so reserved
+ * temp artefacts are removed even when tests fail (`posttest` would not run).
  *
- * npm lifecycle `posttest` scripts only run after a successful `test` script.
- * This wrapper keeps cleanup in the same process path as the Node test runner
- * so reserved test temp artefacts are removed even when tests fail.
+ * The child env unsets `NOTIFICATION_WEBHOOK_URL` so no test POSTs to a live
+ * webhook from `.env` (`MANDREL_ALLOW_TEST_WEBHOOKS=1` opts back in).
  *
- * Webhook scrub: the test child inherits an environment where
- * `NOTIFICATION_WEBHOOK_URL` is unset and `NODE_ENV=test`. Operators keep a
- * real webhook URL in `.env` for development (resolveConfig loads it into
- * process.env); without this scrub, any test that transitively reaches
- * `notify()` POSTs to the live endpoint. Set `MANDREL_ALLOW_TEST_WEBHOOKS=1`
- * to opt back in for the rare case where a contract test deliberately
- * exercises a sandbox endpoint.
+ * Every tier enumerates explicit file targets (`node --test` has no negative
+ * pattern), which overflows the Windows ~32 767-char command line, so targets
+ * are chunked into one spawn per chunk.
  *
- * Windows arg-length safety: every tier enumerates explicit test-file
- * targets. `quick` / `integration` always did (they exclude specific slow
- * suites, so a single glob will not do), and `full` joined them in Story
- * #5111 — `node --test` has no negative pattern, so "everything except
- * `tests/e2e/**`" is only sayable as a file set. With ~700+ targets the
- * joined command line crosses the Windows `CreateProcess` ~32 767-char
- * `lpCommandLine` ceiling, and `spawnSync` throws `ENAMETOOLONG` before a
- * single test runs. To stay safe on every platform the runner partitions the
- * targets into chunks whose joined length stays well under that ceiling
- * (`MAX_TARGET_CHARS`) and spawns one `node --test` process per chunk,
- * aggregating the exit codes. On POSIX the far larger
- * `POSIX_MAX_TARGET_CHARS` budget collapses every tier back into one spawn.
- *
- * Suite credit (Story #5313): a green full-tier run inside a `story-<id>`
- * checkout deposits the `test` gate's evidence record — the one
- * `single-story-close.js` reads — so a bare `npm test` in the worktree is
- * credited at unchanged HEAD. See `lib/test-run-credit.js`.
+ * A green full-tier run in a `story-<id>` checkout deposits close's `test`
+ * gate evidence.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -55,10 +36,6 @@ import { listTestFilesForTier, parseTierArgv } from './lib/test-tiers.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
 
-// 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,
@@ -67,32 +44,15 @@ export {
 };
 
 /**
- * Per-spawn character budget for the joined *targets* portion of the argv.
- *
- * The Windows `CreateProcess` command-line ceiling is 32 767 chars for the
- * whole `lpCommandLine` (node exe path + flags + targets + extra args +
- * quoting). Budgeting the targets to 8 000 chars keeps every spawn's full
- * command line at roughly a quarter of the ceiling — ample headroom for the
- * exe path and any pass-through `--test-name-pattern` args — while keeping
- * the chunk count (and thus the extra `node` start-ups) low.
- *
- * `MAX_TARGET_CHARS` is the **Windows** budget. On POSIX hosts `ARG_MAX` is
- * far higher (~256 KB on macOS, ~1 MB on Linux), so applying the Windows
- * budget there needlessly serializes the quick tier into several sequential
- * `node --test` spawns — each chunk pays a fresh runner start-up, and cores
- * idle at every chunk's tail. `POSIX_MAX_TARGET_CHARS` (100 000) lets the
- * whole quick-tier target list (~33 000 chars today) collapse into a single
- * spawn on POSIX while staying far below `ARG_MAX`.
- * `resolveMaxTargetChars` picks the budget per platform; the Windows
- * semantics of `MAX_TARGET_CHARS` are unchanged.
+ * Per-spawn budget for the joined targets. Windows: ~a quarter of the
+ * 32 767-char ceiling, leaving room for exe path and flags. POSIX `ARG_MAX` is
+ * far larger, so its budget keeps a tier in one spawn (each extra chunk pays a
+ * runner start-up and idles cores at its tail).
  */
 export const MAX_TARGET_CHARS = 8000;
 export const POSIX_MAX_TARGET_CHARS = 100_000;
 
 /**
- * Resolve the per-spawn target-character budget for the host platform.
- * The `platform` parameter is injected in tests.
- *
  * @param {NodeJS.Platform} [platform]
  * @returns {number}
  */
@@ -101,12 +61,9 @@ export function resolveMaxTargetChars(platform = process.platform) {
 }
 
 /**
- * Partition an ordered list of test-file targets into chunks whose joined
- * length (targets + single-space separators) stays at or below `maxChars`.
- * Order is preserved. A single target longer than the budget still lands in
- * its own chunk rather than being dropped. An empty target list yields a
- * single empty chunk so the caller still issues exactly one spawn (matching
- * the historical single-spawn behaviour, e.g. the `full`-tier glob path).
+ * Order-preserving chunks with joined length ≤ `maxChars`. An oversized
+ * target gets its own chunk; an empty list yields one empty chunk so the
+ * caller still spawns once.
  *
  * @param {string[]} targets
  * @param {number} [maxChars]
@@ -118,7 +75,6 @@ export function chunkTestTargets(targets, maxChars = MAX_TARGET_CHARS) {
   let currentLen = 0;
 
   for (const target of targets) {
-    // +1 for the separator that would join this target to the previous one.
     const addition = target.length + (current.length > 0 ? 1 : 0);
     if (current.length > 0 && currentLen + addition > maxChars) {
       chunks.push(current);
@@ -134,23 +90,15 @@ export function chunkTestTargets(targets, maxChars = MAX_TARGET_CHARS) {
 }
 
 /**
- * Build the argv for one `node --test` invocation.
- *
- * **Flag position is load-bearing.** Node stops treating tokens as options
- * at the first positional, so every runner flag — the fixed
- * `TEST_RUNNER_FLAGS`, the optional `--test-reporter`, and any caller
- * `extraArgs` — has to sit *before* the test-file targets. Appending
- * `--test-reporter tap` after the targets (what `run-test-profile.js` used
- * to do) made Node read the two tokens as two more file patterns: the
- * default reporter ran, no TAP was emitted, and the profiler parsed zero
- * timed entries out of a full suite run. `reporter` is therefore an option
- * of this builder rather than something a caller concatenates on the end.
+ * Every flag must precede the targets: Node stops parsing options at the
+ * first positional and reads a later flag as a file pattern. Hence
+ * `reporter` is an option here, not something a caller appends.
  *
  * @param {object} [opts]
- * @param {string[]} [opts.extraArgs] Extra runner arguments (flag position).
+ * @param {string[]} [opts.extraArgs]
  * @param {'full' | 'quick' | 'integration'} [opts.tier]
  * @param {string} [opts.repoRoot]
- * @param {string} [opts.reporter] `--test-reporter` value, e.g. `'tap'`.
+ * @param {string} [opts.reporter]
  * @returns {string[]}
  */
 export function buildNodeTestArgs({
@@ -181,10 +129,7 @@ export function runTestSuite({
 } = {}) {
   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.
+  // Nothing has been created yet, so a refusal needs no cleanup.
   const preflightStatus = preflight({ tier, repoRoot: cwd });
   if (preflightStatus !== 0) return preflightStatus;
 
@@ -199,12 +144,7 @@ export function runTestSuite({
   for (const chunk of chunks) {
     const testRun = spawn(
       process.execPath,
-      // `rest` carries the documented `node --test` pass-throughs
-      // (`--test-name-pattern`, `--test-only`) — `parseTierArgv` has already
-      // rejected anything else. They precede the targets for the same reason
-      // `buildNodeTestArgs` orders them that way: Node stops parsing options
-      // at the first positional, so a flag after a target is silently read as
-      // another file pattern.
+      // Pass-through flags precede the targets (see `buildNodeTestArgs`).
       [...TEST_RUNNER_FLAGS, ...rest, ...chunk],
       { cwd, stdio: 'inherit', env },
     );
@@ -213,18 +153,14 @@ export function runTestSuite({
       break;
     }
     const chunkStatus = testRun.status ?? 1;
-    // First non-zero exit code wins; later chunks still run so the full
-    // failure surface is reported in one CI pass.
+    // First non-zero wins; later chunks still run to report every failure.
     if (chunkStatus !== 0 && status === 0) status = chunkStatus;
   }
 
   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.
+  // Fail a run whose fixture telemetry leaked into the live signals tree,
+  // where the retro graduator would count it as real evidence.
   const polluted = fixtureStreamGuard({ cwd });
   if (polluted !== 0 && status === 0) status = polluted;
 
@@ -232,26 +168,15 @@ export function runTestSuite({
     throw spawnError;
   }
 
-  // Story #5313 — a green full run earns close's `test` credit; best-effort,
-  // never the exit code.
+  // Best-effort; never affects the exit code.
   depositCredit({ cwd, tier, status, durationMs: Date.now() - startedAt });
 
   return status;
 }
 
 /**
- * `--help` contract for the runner — the pre-rendered shape
- * `lib/cli-usage.js` accepts alongside a spec object, matching how
- * `check-baselines.js` declares its own.
- *
- * Handed to `runAsCli`, which prints it and returns **before** `main` runs.
- * That ordering is the whole point: with no `usage` the flag fell through to
- * `runTestSuite`, which ran the tier preflight, spawned the full ~10 000-test
- * suite, and swept `temp/` — 25+ seconds and a mutated working tree in
- * answer to a question about flags.
- *
- * Exported so the unit test can assert the documented surface without
- * spawning the CLI.
+ * `runAsCli` prints this and returns before `main`, so `--help` never runs
+ * the suite.
  */
 export const USAGE = `Usage: node .agents/scripts/run-tests.js [--tier <full|quick|integration|e2e>] [runner args...]
 

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

@@ -1,42 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * single-story-close.js — Close a Story against `main` (v2 `/mandrel-deliver` path).
- *
- * Thin CLI entry for `/mandrel-deliver` / `helpers/deliver-story`. Opens a PR from
- * `story-<id>` to `project.baseBranch`, runs Story-scope review, and arms
- * auto-merge. There is no Epic parent, epic-merge-lock, or wave merge.
- *
- * Pipeline (each step is a phase under
- * `./lib/orchestration/single-story-close/phases/`):
- *
- *   1. close-validation  — canonical gate chain against `baseBranch`
- *   2. base-sync         — `origin/<baseBranch>` → Story branch (Story #2580)
- *   3. push              — `git push -u` the Story branch
- *   4. pull-request      — `gh pr list` probe + `gh pr create`
- *   5. code-review       — Story-scope review (Epic #2815 / Story #2839)
- *   6. auto-merge        — `gh pr merge --auto --squash --delete-branch`
- *   7. label flip + notify — Story → `agent::closing` (Story #3385; the
- *                          `agent::done` flip + issue-close is deferred to
- *                          the post-merge confirmation step,
- *                          `single-story-confirm-merge.js`)
- *   8. worktree-reap     — drop the per-Story worktree
- *   9. confirm-merge      — close-and-land (Story #4428; the DEFAULT for
- *                          every run since `delivery.routing.closeAndLand`):
- *                          poll the just-armed PR to merge confirmation
- *                          (reusing `confirmStoryMerged`), capture the
- *                          Story follow-ups, or terminate `agent::blocked`
- *                          with a classified `merge.unlanded` event — or
- *                          `merge.flip-failed` when the merge landed and
- *                          only the label write failed. Skipped when the
- *                          operator owns the merge (`--no-wait-merge`,
- *                          `--no-auto-merge`, or `autoMerge: "strict"`),
- *                          which rests at `agent::closing` for the human.
- *
- * Existing tests import the re-exported helpers
- * (`runSingleStoryClose`, `ensurePullRequest`, `parsePrNumber`,
- * `enableAutoMerge`, `handleSyncFailure`, `buildSyncFailureCommentBody`,
- * `runStoryScopeReview`, `buildStoryReviewCrossRefBody`) from this file.
+ * single-story-close.js — close a Story against the base branch: gates,
+ * base-sync, push, PR, Story-scope review, arm auto-merge, flip to
+ * `agent::closing`, reap the worktree, then (by default) wait for the merge.
+ * The wait is skipped when the operator owns the merge (`--no-wait-merge`,
+ * `--no-auto-merge`, `autoMerge: "strict"`); an arm FAILURE still waits and
+ * blocks, keeping the must-land contract.
  *
  * Usage:
  *   node single-story-close.js --story <STORY_ID> [--cwd <main-repo>]
@@ -47,62 +17,15 @@
  *                              [--rerun-advisory <n>]
  *                              [--override-review-block <reason>]
  *
- * `--override-review-block <reason>` is the one sanctioned way
- * past a code-review CRITICAL blocker. A critical finding halts this script
- * before auto-merge, and until this flag existed there was no override at all —
- * so an operator who had read a finding and judged it wrong could only land by
- * running `gh pr merge` themselves, bypassing the gate with nothing written
- * down. The flag does not weaken the gate; it moves that escape hatch into a
- * mandatory-reason audit trail (Story comment + PR comment + a
- * `review-block-overridden` friction signal) and reports
- * `gates.codeReview: "overridden"` on the terminal envelope. A bare or
- * too-short reason fails during option parsing, before any phase runs.
- *
- * `--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
- * the default, and Story #4539 made that knob actually readable). Resolution
- * order, highest first: `--no-wait-merge` (explicit opt-out, always wins);
- * operator-owns-the-merge (`--no-auto-merge` or `delivery.ci.autoMerge:
- * "strict"` — the PR was deliberately left un-armed, so there is nothing to
- * land and the Story rests at `agent::closing`); explicit `--wait-merge`;
- * then the config. A genuine arm FAILURE is not an opt-out — it still waits
- * and therefore still blocks, which is what keeps the must-land contract
- * intact.
+ * `--override-review-block <reason>` is the audited escape past a code-review
+ * CRITICAL blocker (instead of a hand-merge with no record).
+ * `--merge-watch-mode async` is passed per close by the orchestrator, the only
+ * party that knows the run has N Stories and a foreground wait is dead time.
  *
- * Every invocation emits ONE schema-validated terminal envelope
- * (`.agents/schemas/story-deliver-terminal.schema.json`, Story #4543) on
- * stdout between `--- STORY DELIVER TERMINAL ---` markers. Its `status` is
- * the contract; the exit code mirrors it:
- *
- *   0 — `landed`:  the PR merged, the Story is `agent::done`, and the
- *                  post-land tail ran (follow-ups, status resync, local ref
- *                  cleanup, base fast-forward).
- *   3 — `pending`: RESUMABLE, not a failure. Either the per-invocation merge
- *                  wait (`delivery.mergeWatch.maxWaitSeconds`, default 300s
- *                  to fit a single host tool invocation) expired with the PR
- *                  still healthy and in flight, or the operator owns the
- *                  merge (`--no-wait-merge` / `--no-auto-merge` /
- *                  `autoMerge: "strict"`). NO label was mutated and no
- *                  `merge.unlanded` event was emitted. The envelope's
- *                  `nextCommand` names the single command that resumes it,
- *                  and the cumulative budget is anchored at the PR's
- *                  createdAt so the resume does not restart the clock.
- *   1 — `blocked` or `failed`: a classified hard block (the Story carries
- *                  `agent::blocked` and a friction comment) or a phase crash.
- *
- * The distinct `pending` code is the point: before it, a close-and-land whose
- * CI outlived the host's tool-invocation ceiling was killed mid-poll with no
- * terminal path taken at all, and merely shrinking the budget instead would
- * have misfiled every slow-CI run as a hard block.
+ * Every invocation emits ONE terminal envelope; the exit code mirrors its
+ * status: 0 `landed`; 3 `pending` (resumable — the per-invocation wait
+ * expired with the PR healthy, or the operator owns the merge; nothing
+ * mutated, run `nextCommand`); 1 `blocked` or `failed`.
  *
  * @see .agents/workflows/helpers/deliver-story.md
  * @see .agents/schemas/story-deliver-terminal.schema.json
@@ -118,7 +41,6 @@ import {
   failedTerminalFor,
   gatesForFailedPhase,
 } from './lib/orchestration/single-story-close/failed-terminal.js';
-import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import {
   buildSyncFailureCommentBody,
   handleSyncFailure,
@@ -128,29 +50,14 @@ import {
   parsePrNumber,
   runStoryScopeReview,
 } from './lib/orchestration/single-story-close/phases/code-review.js';
-import { ensurePullRequestWith } from './lib/orchestration/single-story-close/phases/pull-request.js';
 import {
   emitTerminalEnvelope,
   exitCodeForTerminal,
 } from './lib/orchestration/story-deliver-terminal.js';
 
-// Story #2990 moved the `gh`-spawn boundary into the `lib/gh-exec.js`
-// facade (the same shim the `providers/github/` gateways use). The
-// re-exports below preserve the SUT's public surface so tests and the
-// orchestration body keep importing `ensurePullRequest` /
-// `enableAutoMerge` from this file unchanged.
-export const ensurePullRequest = ensurePullRequestWith;
-export const enableAutoMerge = enableAutoMergeWith;
-
-// Re-export pure helpers verbatim — they don't touch `execFileSync`
-// or any URL-mocked module, so the phase exports work unmodified.
-// `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.
+// Pure helpers re-exported as this CLI's public surface; the runner is
+// reached only via dynamic import, so this is where they are statically
+// visible.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
@@ -170,22 +77,9 @@ export async function runSingleStoryClose(opts) {
 }
 
 /**
- * CLI entry — resolves the process exit code from the terminal envelope's
- * 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.
+ * Exit code comes from the envelope's status. The catch parses argv with the
+ * non-throwing wrapper: the strict parser may be what just threw, and every
+ * invocation must still emit exactly one envelope.
  */
 async function main() {
   try {
@@ -194,13 +88,9 @@ async function main() {
   } catch (err) {
     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.
+    // Mirrors runAsCli's default error line, which this catch pre-empts.
     Logger.error(`[single-story-close] Fatal error: ${formatCliError(err)}`);
     emitTerminalEnvelope(terminal);
-    // Story #4578 — a close that died before the runner could report its own
-    // terminal is exactly the friction the retro must see, so the crash path
-    // gets the same emit the happy path does. Best-effort; cannot throw.
     await emitTerminalFriction({ envelope: terminal });
     return exitCodeForTerminal(terminal);
   }
@@ -236,10 +126,8 @@ runAsCli(import.meta.url, main, {
       ],
       [
         '--override-review-block <reason>',
-        // Deliberately does not spell the merge CLI invocation: the
-        // merge-lockout rule in `check-lifecycle-lint.js` forbids that literal
-        // in any string outside `phases/auto-merge.js`, and it is right to —
-        // the point of this flag is that arming stays on the one code path.
+        // Must not spell the merge CLI invocation: `check-lifecycle-lint.js`
+        // forbids that literal outside `phases/auto-merge.js`.
         'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no record at all.',
       ],
     ],