mandrel 2.36.0 → 2.38.0

package/.agents/scripts/providers/github/tickets.js

@@ -15,7 +15,7 @@
  * Epic-hierarchy write surface. It composed the exact `Epic: #N` footer that
  * `pr-base-guard.js` hard-refuses at delivery, so the framework retained the
  * ability to generate work it would then reject; it had no production caller
- * (`/plan` persists through the bare `createIssue` below).
+ * (`/mandrel-plan` persists through the bare `createIssue` below).
  *
  * Public surface: `GitHubProvider.createIssue / getTicket /
  * getTickets / updateTicket / getTicketDependencies / primeTicketCache /
@@ -251,8 +251,8 @@ export class TicketGateway {
 
   /**
    * Create a **bare** issue — no footer composition and no sub-issue link.
-   * Since Story #4545 this is the *only* create path: `/plan` persist and the
-   * `/plan` Phase 4 Epic open (`openEpicFromOnePager`'s `createIssue` port)
+   * Since Story #4545 this is the *only* create path: `/mandrel-plan` persist and the
+   * `/mandrel-plan` Phase 4 Epic open (`openEpicFromOnePager`'s `createIssue` port)
    * both route through it.
    *
    * After the POST, the new issue is added to the configured Project V2
@@ -264,38 +264,43 @@ export class TicketGateway {
    * The POST is wrapped in `withTransientRetry` (Story #4541) so it absorbs
    * the same 502/429/ECONNRESET blips the read surfaces already do. It used
    * to post bare, which made a single transient failure at story *k* of *N*
-   * abort `/plan` persist with `1..k-1` already live on the tracker.
+   * abort `/mandrel-plan` persist with `1..k-1` already live on the tracker.
    *
    * Retry alone is not sufficient for that failure mode — a POST whose
-   * response is lost would double-create on the retry — so the caller
-   * (`plan-persist`'s `createStoryIssues`) carries the idempotency half via
-   * a plan fingerprint it looks up before creating. Retry narrows the
-   * window; the fingerprint closes it.
+   * response is lost would double-create on the retry. Story #5112 closed
+   * that: `findExisting` is consulted **before every retry POST**, and a hit
+   * is adopted instead of re-created, so a response-lost first attempt files
+   * exactly one issue. `/mandrel-plan` persist supplies the plan-fingerprint lookup
+   * its resume path already uses (`plan-persist`'s `createStoryIssues`);
+   * callers with no content identity omit it and keep the pre-#5112
+   * retry-only behaviour.
    *
    * @field-manifest POST /repos/{owner}/{repo}/issues: number, id, node_id,
    *                 html_url
    *
-   * @param {{ title: string, body: string, labels?: string[] }} payload
+   * @param {{
+   *   title: string,
+   *   body: string,
+   *   labels?: string[],
+   *   findExisting?: (() => Promise<object|null>)|null,
+   * }} payload
    * @returns {Promise<{
    *   id: number,
    *   number: number,
    *   internalId: number,
    *   nodeId: string,
    *   url: string,
+   *   adopted: boolean,
    *   boardAdd: { added: boolean, reason?: string },
    * }>}
    */
-  async createIssue({ title, body, labels = [] }) {
-    const result = await withTransientRetry(
-      () =>
-        this._gh.api({
-          method: 'POST',
-          endpoint: `/repos/${this.owner}/${this.repo}/issues`,
-          body: { title, body, labels },
-        }),
-      { label: `createIssue "${title}"`, onRetry: defaultRetryWarn },
-    );
-    const issue = parseApiJson(result);
+  async createIssue({ title, body, labels = [], findExisting = null }) {
+    const { issue, adopted } = await this._createIssueOrAdopt({
+      title,
+      body,
+      labels,
+      findExisting,
+    });
     this._listCache.clear();
 
     const boardAdd = await addIssueToBoard({
@@ -311,10 +316,86 @@ export class TicketGateway {
       internalId: issue.id,
       nodeId: issue.node_id,
       url: issue.html_url,
+      adopted,
       boardAdd,
     };
   }
 
+  /**
+   * POST one issue and parse the created resource out of the response.
+   *
+   * @param {{ title: string, body: string, labels: string[] }} payload
+   * @returns {Promise<object>}
+   */
+  async _postIssue(payload) {
+    return parseApiJson(
+      await this._gh.api({
+        method: 'POST',
+        endpoint: `/repos/${this.owner}/${this.repo}/issues`,
+        body: payload,
+      }),
+    );
+  }
+
+  /**
+   * Resolve the ambiguity a lost response leaves behind: did attempt 1 land?
+   * `ECONNRESET` after the server committed the create looks exactly like
+   * `ECONNRESET` before it, so the only authority is the server's own state.
+   *
+   * @param {(() => Promise<object|null>)|null} findExisting
+   * @returns {Promise<object|null>} the already-created issue, or `null`.
+   */
+  async _findAlreadyCreated(findExisting) {
+    return typeof findExisting === 'function' ? await findExisting() : null;
+  }
+
+  /**
+   * The idempotent half of {@link TicketGateway#createIssue}: POST once, and
+   * on every subsequent attempt look for an already-created issue *before*
+   * posting again, so a retry adopts rather than duplicates.
+   *
+   * @param {{ title: string, body: string, labels: string[], findExisting: (() => Promise<object|null>)|null }} args
+   * @returns {Promise<{ issue: object, adopted: boolean }>}
+   */
+  async _createIssueOrAdopt({ title, body, labels, findExisting }) {
+    let posts = 0;
+    return withTransientRetry(
+      async () => {
+        if (posts > 0) {
+          const issue = await this._findAlreadyCreated(findExisting);
+          if (issue) return { issue, adopted: true };
+        }
+        posts += 1;
+        const issue = await this._postIssue({ title, body, labels });
+        return { issue, adopted: false };
+      },
+      { label: `createIssue "${title}"`, onRetry: defaultRetryWarn },
+    );
+  }
+
+  /**
+   * Append logins to an issue's assignee set via GitHub's additive assignees
+   * endpoint. No read-before-write and no replace semantics, so it cannot
+   * evict an assignee another run added between our read and our write. A
+   * non-array or empty list is a no-op.
+   *
+   * @param {number} ticketId
+   * @param {string[]|undefined} logins
+   */
+  async _addAssignees(ticketId, logins) {
+    if (!(logins?.length > 0)) return;
+    await withTransientRetry(
+      () =>
+        this._gh.api({
+          method: 'POST',
+          endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/assignees`,
+          body: { assignees: logins },
+        }),
+      { label: `addAssignees #${ticketId}`, onRetry: defaultRetryWarn },
+    );
+    this.invalidateTicket(ticketId);
+  }
+
   /**
    * Add/remove labels on an issue. When the only mutation is "add", uses the
    * additive labels endpoint (POST /issues/{n}/labels) for atomicity and to
@@ -324,7 +405,7 @@ export class TicketGateway {
    *
    * The additive POST goes through `withTransientRetry` (Story #4961) on the
    * same policy as every other call in this file. Story #4952 raised the
-   * `/plan` write loops that reach this endpoint — the `agent::ready` flips
+   * `/mandrel-plan` write loops that reach this endpoint — the `agent::ready` flips
    * and the checkpoint fan-out — off serial, which is precisely what makes
    * GitHub's secondary rate limit likelier; `gh-exec` already classifies that
    * as transient, so the only thing missing was a backoff behind it.
@@ -370,11 +451,23 @@ export class TicketGateway {
    * {@link TicketGateway#_applyLabelMutations}. Both are the write half of the
    * fan-outs Story #4952 raised; the reads in this file were already wrapped.
    *
+   * `mutations.addAssignees` (Story #5112) is the **additive** assignee
+   * write, on the same shape as the additive label POST above: it appends to
+   * the assignee set instead of replacing it. The lease claim
+   * (`lib/orchestration/ticket-lease.js`) needs that — a replacing PATCH
+   * evicts a simultaneous claimer silently, so both runs read a clean
+   * `[self]` on verify and both believe they hold the lease. Appending makes
+   * the collision *observable* as a co-assignment, which is exactly what the
+   * lease's `lost-race` back-out keys on. `mutations.assignees` (replace) is
+   * unchanged and still used by the steal and release paths.
+   *
+   * @field-manifest POST /repos/{owner}/{repo}/issues/{n}/assignees: assignees
    * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
    *                 body, assignees, state, state_reason, labels
    */
   /* node:coverage ignore next */
   async updateTicket(ticketId, mutations) {
+    await this._addAssignees(ticketId, mutations.addAssignees);
     const patch = {};
     if (mutations.body !== undefined) patch.body = mutations.body;
     if (mutations.assignees) patch.assignees = mutations.assignees;

package/.agents/scripts/quality-preview.js

@@ -292,7 +292,9 @@ export function computeExitCode(merged, miExit, crapExit) {
  *
  * The last header used to hardcode `c=8`, which quietly lied to any consumer
  * that had tuned `codingGuardrails.cyclomaticFlag`. It now names the value the
- * count was actually taken against, read off the merge result.
+ * count was actually taken against, read off the merge result — through the
+ * same `normalizeFlag` the merge itself uses, rather than the second, hand-
+ * inlined copy of that coercion this function used to carry.
  *
  * Pure — accepts pre-computed merge rows and returns a multi-line string. The
  * table renders even on a clean diff so operators see the "no drift" signal.
@@ -300,33 +302,40 @@ export function computeExitCode(merged, miExit, crapExit) {
  * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number }, cyclomaticFlag?: number }} merged
  * @returns {string}
  */
+/**
+ * The table's body: one row per regressed file, or the single placeholder
+ * line that keeps the "no drift" signal visible on a clean diff.
+ *
+ * Split out of `renderTable` so that function keeps a flat shape — the
+ * empty-vs-populated branch and the row loop together carried it above the
+ * per-method CRAP contract the pre-push preview enforces.
+ *
+ * @param {Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>} rows
+ * @returns {string[]}
+ */
+function tableBodyLines(rows) {
+  if (rows.length === 0) return ['| _(no per-file regressions)_ | — | — | — |'];
+  return rows.map(
+    (row) =>
+      `| ${row.file} | -${row.miDrop.toFixed(2)} | +${row.worstCrapDelta.toFixed(2)} | ${row.newOverCeilingMethods} |`,
+  );
+}
+
 export function renderTable(merged) {
-  const flag = Number.isFinite(Number(merged?.cyclomaticFlag))
-    ? Number(merged.cyclomaticFlag)
-    : DEFAULT_CYCLOMATIC_FLAG;
+  const flag = normalizeFlag(merged?.cyclomaticFlag);
   const header = [
     'file',
     'MI delta',
     'worst CRAP delta',
     `new-method count over c=${flag}`,
   ];
-  const lines = [];
-  lines.push(`| ${header.join(' | ')} |`);
-  lines.push(`| ${header.map(() => '---').join(' | ')} |`);
-  if (merged.rows.length === 0) {
-    lines.push('| _(no per-file regressions)_ | — | — | — |');
-  } else {
-    for (const row of merged.rows) {
-      lines.push(
-        `| ${row.file} | -${row.miDrop.toFixed(2)} | +${row.worstCrapDelta.toFixed(2)} | ${row.newOverCeilingMethods} |`,
-      );
-    }
-  }
-  lines.push('');
-  lines.push(
+  return [
+    `| ${header.join(' | ')} |`,
+    `| ${header.map(() => '---').join(' | ')} |`,
+    ...tableBodyLines(merged.rows),
+    '',
     `Totals: MI regressions=${merged.totals.miRegressions} · CRAP violations=${merged.totals.crapViolations}`,
-  );
-  return lines.join('\n');
+  ].join('\n');
 }
 
 /**
@@ -354,6 +363,96 @@ function resolveCyclomaticFlag({ cwd, stderr }) {
   }
 }
 
+/**
+ * Invoke one preview runner, degrading a thrown failure into the same
+ * `{ exitCode: 1, envelope: null }` shape a real gate failure produces.
+ *
+ * Both runners degraded identically before, in two hand-copied `catch`
+ * arms; folding them into one helper removes the copy and keeps `runCli` a
+ * pipeline rather than a pair of inlined error handlers. The emitted message
+ * is byte-identical to the arm it replaces — `label` supplies the `MI` /
+ * `CRAP` prefix.
+ *
+ * @param {(args: object) => Promise<{exitCode: number, envelope: object|null}>} runner
+ * @param {{cwd: string, staged: boolean, changedSinceRef: string|null}} args
+ * @param {'MI'|'CRAP'} label
+ * @param {{ write: (s: string) => void }} stderr
+ * @returns {Promise<{exitCode: number, envelope: object|null}>}
+ */
+function runGateSafely(runner, args, label, stderr) {
+  return runner(args).catch((err) => {
+    stderr.write(
+      `[quality:preview] ${label} runner failed: ${err?.message ?? err}\n`,
+    );
+    return { exitCode: 1, envelope: null };
+  });
+}
+
+/**
+ * Write the run's report — the `--json` envelope, or the human-readable
+ * table plus any gate diagnostics and the non-zero-exit summary.
+ *
+ * Split out of `runCli` (Story #5109): the rendering half carried five of
+ * that function's decision points, which put it over the per-method CRAP
+ * contract the pre-push preview enforces. Output bytes are unchanged in both
+ * modes. The exit code stays with the caller — this function only reports.
+ *
+ * @param {{
+ *   json: boolean,
+ *   staged: boolean,
+ *   ref: string|null,
+ *   miResult: {exitCode: number, envelope: object|null},
+ *   crapResult: {exitCode: number, envelope: object|null},
+ *   merged: ReturnType<typeof mergeEnvelopes>,
+ *   stdout: { write: (s: string) => void },
+ *   stderr: { write: (s: string) => void },
+ * }} args
+ * @returns {void}
+ */
+function emitReport({
+  json,
+  staged,
+  ref,
+  miResult,
+  crapResult,
+  merged,
+  stdout,
+  stderr,
+}) {
+  const miExit = miResult.exitCode;
+  const crapExit = crapResult.exitCode;
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          ref: staged ? null : ref,
+          staged,
+          mi: { exit: miExit, envelope: miResult.envelope },
+          crap: { exit: crapExit, envelope: crapResult.envelope },
+          merged,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+  stdout.write('\n--- quality:preview ---\n');
+  stdout.write(
+    staged
+      ? 'scope=staged (git diff --cached)\n\n'
+      : `scope=diff ref=${ref}\n\n`,
+  );
+  stdout.write(`${renderTable(merged)}\n`);
+  const diagnostics = renderDiagnostics([miResult, crapResult]);
+  if (diagnostics) stdout.write(`\n${diagnostics}\n`);
+  if (miExit !== 0 || crapExit !== 0) {
+    stderr.write(
+      `\n[quality:preview] gate exits: mi=${miExit} crap=${crapExit}\n`,
+    );
+  }
+}
+
 /**
  * Top-level CLI entry: invoke both per-kind preview runners, merge, render,
  * and exit with the right code. Exposed as `runCli` so tests can drive the
@@ -381,62 +480,55 @@ export async function runCli({
   const staged = parseStagedFlag(argv);
   const ref = staged ? null : (parseChangedSinceArg(argv) ?? 'HEAD');
 
-  const [miResult, crapResult] = await Promise.all([
-    runMi({ cwd, staged, changedSinceRef: ref }).catch((err) => {
-      stderr.write(
-        `[quality:preview] MI runner failed: ${err?.message ?? err}\n`,
-      );
-      return { exitCode: 1, envelope: null };
-    }),
-    runCrap({ cwd, staged, changedSinceRef: ref }).catch((err) => {
-      stderr.write(
-        `[quality:preview] CRAP runner failed: ${err?.message ?? err}\n`,
-      );
-      return { exitCode: 1, envelope: null };
-    }),
-  ]);
-  const miExit = miResult.exitCode;
-  const crapExit = crapResult.exitCode;
-  const miEnvelope = miResult.envelope;
-  const crapEnvelope = crapResult.envelope;
+  // Story #5109 — the two gates run **one after the other**, not under a
+  // `Promise.all`. Each scores its batch with its own `runOnPool` budget
+  // sized to `os.availableParallelism()`, so overlapping them oversubscribed
+  // the host by 2x and stacked two escomplex heaps: a 58-file preview peaked
+  // at 1.0-1.2 GB RSS for 3.9 s of CPU. Serialising them bounds the preview
+  // to one `availableParallelism` of workers and one heap at a time. The two
+  // runners share no state and neither reads the other's envelope, so the
+  // emitted envelopes — and therefore the merged table and the exit code —
+  // are identical either way; only the peak cost differs.
+  //
+  // Each runner gets its own options literal rather than one shared object,
+  // so serialising them cannot introduce a coupling the concurrent form
+  // did not have.
+  const miResult = await runGateSafely(
+    runMi,
+    { cwd, staged, changedSinceRef: ref },
+    'MI',
+    stderr,
+  );
+  const crapResult = await runGateSafely(
+    runCrap,
+    { cwd, staged, changedSinceRef: ref },
+    'CRAP',
+    stderr,
+  );
+
   // Story #4923 — the over-ceiling column counts against the *resolved*
   // `codingGuardrails.cyclomaticFlag`, not the literal that used to be written
   // into `mergeEnvelopes` and the column header.
   const cyclomaticFlag = resolveCyclomaticFlag({ cwd, stderr });
-  const merged = mergeEnvelopes(miEnvelope, crapEnvelope, { cyclomaticFlag });
+  const merged = mergeEnvelopes(miResult.envelope, crapResult.envelope, {
+    cyclomaticFlag,
+  });
 
-  if (json) {
-    stdout.write(
-      `${JSON.stringify(
-        {
-          ref: staged ? null : ref,
-          staged,
-          mi: { exit: miExit, envelope: miEnvelope },
-          crap: { exit: crapExit, envelope: crapEnvelope },
-          merged,
-        },
-        null,
-        2,
-      )}\n`,
-    );
-  } else {
-    stdout.write('\n--- quality:preview ---\n');
-    stdout.write(
-      staged
-        ? 'scope=staged (git diff --cached)\n\n'
-        : `scope=diff ref=${ref}\n\n`,
-    );
-    stdout.write(`${renderTable(merged)}\n`);
-    const diagnostics = renderDiagnostics([miResult, crapResult]);
-    if (diagnostics) stdout.write(`\n${diagnostics}\n`);
-    if (miExit !== 0 || crapExit !== 0) {
-      stderr.write(
-        `\n[quality:preview] gate exits: mi=${miExit} crap=${crapExit}\n`,
-      );
-    }
-  }
+  emitReport({
+    json,
+    staged,
+    ref,
+    miResult,
+    crapResult,
+    merged,
+    stdout,
+    stderr,
+  });
 
-  return { exitCode: computeExitCode(merged, miExit, crapExit), merged };
+  return {
+    exitCode: computeExitCode(merged, miResult.exitCode, crapResult.exitCode),
+    merged,
+  };
 }
 
 // cli-opt-out: Windows-aware main-guard with leading-slash drive-letter normalisation; mirrors quality-watch.js so the diagnostic surface stays consistent across the gate suite.

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

@@ -2,9 +2,9 @@
 
 /**
  * resolve-stories.js — resolve a list of Story ids into the
- * `{ stories, dag, done }` envelope `/deliver` sequences from.
+ * `{ stories, dag, done }` envelope `/mandrel-deliver` sequences from.
  *
- * This is the ONE resolution step for multi-Story delivery. `/deliver` takes
+ * This is the ONE resolution step for multi-Story delivery. `/mandrel-deliver` takes
  * only Story ids; the graph is discovered here, from live state, rather than
  * hand-transcribed by the host or implied by a batch label.
  *
@@ -63,7 +63,7 @@ const HELP = `\
 Usage:
   resolve-stories.js --ids <n,n,...> [--pretty] [--no-native]
 
-Resolve Story ids into the { stories, dag, done } envelope /deliver sequences
+Resolve Story ids into the { stories, dag, done } envelope /mandrel-deliver sequences
 from. Dependencies are discovered from live state: body edges union native
 blocked_by edges, with every blocker (in-set or foreign) resolved against its
 real issue state.

package/.agents/scripts/resync-status-column.js

@@ -5,7 +5,7 @@
  * resync-status-column.js — re-assert the GitHub Projects v2 Status
  * column for a ticket after auto-merge has fired (Story #2845).
  *
- * The `/single-story-deliver` and `/deliver` workflow docs call
+ * The `/single-story-deliver` and `/mandrel-deliver` workflow docs call
  * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
  * wins the race against the GitHub built-in `Pull request merged`
  * workflow, which would otherwise overwrite Status to whatever value

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

@@ -84,7 +84,7 @@ const tasks = [
   nodeGate('lifecycle-lint', '.agents/scripts/check-lifecycle-lint.js'),
   // Workflow prose surface (Epic #4474 PR5). No workflow may instruct calling
   // an exported library function that has no CLI entrypoint — the measured
-  // shim-writing failure mode the /plan collapse killed. See
+  // shim-writing failure mode the /mandrel-plan collapse killed. See
   // check-workflow-cli-lint.js for the paragraph-level heuristic.
   nodeGate('workflow-cli-lint', '.agents/scripts/check-workflow-cli-lint.js'),
   // Label-vocabulary citations in `.agents/docs/SDLC.md` and

package/.agents/scripts/run-test-profile.js

@@ -69,11 +69,14 @@ export function runTestProfile({
   const { outDir, topN, testArgv } = parseProfileArgv(argv);
   fsLike.mkdirSync(outDir, { recursive: true });
 
-  const nodeArgs = [
-    ...buildNodeTestArgs({ extraArgs: testArgv }),
-    '--test-reporter',
-    'tap',
-  ];
+  // The reporter is a *builder option*, not a suffix. Appended after the
+  // file targets it was two more positionals to Node, the default reporter
+  // ran, and every profile parsed `Timed entries parsed: 0` off a full
+  // suite run. `buildNodeTestArgs` places it in flag position.
+  const nodeArgs = buildNodeTestArgs({
+    extraArgs: testArgv,
+    reporter: 'tap',
+  });
 
   const started = Date.now();
   const result = spawnChild(process.execPath, nodeArgs, {

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

@@ -16,16 +16,18 @@
  * to opt back in for the rare case where a contract test deliberately
  * exercises a sandbox endpoint.
  *
- * Windows arg-length safety: the `quick` / `integration` tiers enumerate
- * explicit test-file targets (they exclude specific slow suites, so a single
- * glob will not do). 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. The
- * `full` tier (a single recursive `tests` glob) yields exactly one chunk, so
- * its behaviour is unchanged.
+ * 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.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -126,18 +128,38 @@ 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.
+ *
  * @param {object} [opts]
- * @param {string[]} [opts.extraArgs]
+ * @param {string[]} [opts.extraArgs] Extra runner arguments (flag position).
  * @param {'full' | 'quick' | 'integration'} [opts.tier]
  * @param {string} [opts.repoRoot]
+ * @param {string} [opts.reporter] `--test-reporter` value, e.g. `'tap'`.
+ * @returns {string[]}
  */
 export function buildNodeTestArgs({
   extraArgs = [],
   tier = 'full',
   repoRoot = ROOT,
+  reporter,
 } = {}) {
-  const targets = listTestFilesForTier(tier, repoRoot);
-  return [...TEST_RUNNER_FLAGS, ...targets, ...extraArgs];
+  return [
+    ...(reporter
+      ? [...TEST_RUNNER_FLAGS, '--test-reporter', reporter]
+      : TEST_RUNNER_FLAGS),
+    ...extraArgs,
+    ...listTestFilesForTier(tier, repoRoot),
+  ];
 }
 
 export function runTestSuite({
@@ -169,7 +191,13 @@ export function runTestSuite({
   for (const chunk of chunks) {
     const testRun = spawn(
       process.execPath,
-      [...TEST_RUNNER_FLAGS, ...chunk, ...rest],
+      // `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.
+      [...TEST_RUNNER_FLAGS, ...rest, ...chunk],
       { cwd, stdio: 'inherit', env },
     );
     if (testRun.error) {
@@ -199,7 +227,44 @@ export function runTestSuite({
   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.
+ */
+export const USAGE = `Usage: node .agents/scripts/run-tests.js [--tier <full|quick|integration|e2e>] [runner args...]
+
+Run the test suite: tier preflight, \`node --test\` over the tier's targets,
+then reserved-temp cleanup — which runs even when the suite fails.
+
+Flags:
+  --tier <full|quick|integration|e2e>
+                        Tier to run. Default: full — every test file except
+                        \`tests/e2e/**\`, which only \`--tier e2e\` runs.
+  --test-name-pattern <re>, --test-only
+                        The documented \`node --test\` pass-throughs, forwarded
+                        verbatim in flag position, ahead of the file targets.
+                        Any other \`--flag\` is rejected rather than forwarded:
+                        \`node --test\` reads an unrecognized flag as another
+                        file pattern, so forwarding one ran nothing and
+                        still exited 0.
+  --help                Show this message.
+
+Exits with the first non-zero \`node --test\` chunk status, or 2 when the tier
+preflight refuses to start the suite.
+`;
+
 runAsCli(import.meta.url, async () => runTestSuite(), {
   source: 'run-tests',
   propagateExitCode: true,
+  usage: USAGE,
 });