mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/story-plan.js

@@ -9,16 +9,24 @@
  *   - DEFAULT_REFINE_THRESHOLD     — seed length below which refinement
  *                                    is auto-suggested.
  *   - REQUIRED_SECTIONS            — canonical section headings the body
- *                                    must carry to be accepted by
- *                                    /single-story-deliver.
+ *                                    must carry itself. Story #4874: the
+ *                                    `## Acceptance` / `## Verify` sections
+ *                                    are deliberately NOT among them —
+ *                                    those lists are the ticket's top-level
+ *                                    machine contract and persist
+ *                                    synthesizes their sections, exactly as
+ *                                    the story-author prompt instructs.
  *   - rankDuplicateCandidates({ seed, openStories, maxResults })
  *                                  — Jaccard-overlap ranking of open
  *                                    Stories whose titles fuzzy-match
  *                                    the seed.
- *   - validateStoryBody(body)      — schema-light shape check:
- *                                    required sections present, no
- *                                    `Epic:` reference, AC checklist
- *                                    non-empty.
+ *   - validateStoryBody(body, contract)
+ *                                  — schema-light shape check against the
+ *                                    canonical Story-body contract: `##
+ *                                    Goal` / `## Changes` present, no
+ *                                    `Epic:` reference, and an
+ *                                    acceptance/verify contract resolvable
+ *                                    from the top-level arrays or the body.
  *   - buildContextEnvelope(opts)   — assemble the context envelope the
  *                                    host LLM consumes.
  */
@@ -26,21 +34,25 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { overlapScore, tokenize } from './duplicate-search.js';
+import { parse as parseStoryBody } from './story-body/story-body.js';
 
 export const DEFAULT_REFINE_THRESHOLD = 200;
 export const DEFAULT_DUPLICATE_MAX_RESULTS = 5;
 export const DEFAULT_DUPLICATE_MIN_SCORE = 0.15;
 
-export const REQUIRED_SECTIONS = [
-  'Context',
-  'Acceptance Criteria',
-  'Out of Scope',
-  'Notes',
-];
+/**
+ * The sections the authored body must carry itself. Story #4874 reconciled
+ * this list with the story-author prompt: the prompt tells the author to
+ * write `acceptance[]` / `verify[]` **once** at the ticket's top level and
+ * omit the matching body sections, so demanding those sections here made a
+ * prompt-faithful body unpersistable and cost a re-author round.
+ */
+export const REQUIRED_SECTIONS = ['Goal', 'Changes'];
+
+/** The contract lists persist synthesizes into the body from the top level. */
+const CONTRACT_FIELDS = /** @type {const} */ (['acceptance', 'verify']);
 
 const EPIC_REF_PATTERN = /^\s*Epic:\s*#\d+/m;
-const AC_HEADING_PATTERN = /^##\s+Acceptance Criteria\s*$/m;
-const CHECKLIST_PATTERN = /^\s*-\s*\[\s?\]/m;
 
 /**
  * Rank open Stories by title-overlap with the seed. Reuses the same
@@ -115,54 +127,137 @@ export function shouldRefine({
 }
 
 /**
- * Schema-light validator for a standalone-Story body. Used by the persist
- * path *and* by tests asserting `--dry-run` output stability. The check
- * is deliberately tolerant of authoring whitespace: it asserts the
- * canonical headings are present, that no `Epic: #N` reference leaks
- * (the standalone contract), and that the Acceptance Criteria section
- * carries at least one unchecked checklist item.
+ * Collect the violations for one contract list (`acceptance` / `verify`).
+ *
+ * The list may be authored at the ticket's top level (the shape the
+ * story-author prompt prescribes) or written into the body as a section —
+ * either satisfies the contract, and the top level is preferred because
+ * persist synthesizes the section from it. Only two shapes are violations:
+ * the list is nowhere, or it is in both places and the two disagree (fail
+ * closed rather than guess which is authoritative, mirroring
+ * `plan-persist`'s `syncContractFieldFromTopLevel`).
+ *
+ * @param {'acceptance'|'verify'} field
+ * @param {unknown} bodyList  The parsed body's section entries.
+ * @param {unknown} topLevel  The ticket's top-level array.
+ * @returns {string[]}
+ */
+function collectContractErrors(field, bodyList, topLevel) {
+  const inBody = (Array.isArray(bodyList) ? bodyList : []).map(String);
+  const inTicket = (Array.isArray(topLevel) ? topLevel : []).map(String);
+  if (inBody.length === 0 && inTicket.length === 0) {
+    return [
+      `${field} must list at least one entry — author it as the ticket's top-level ${field}[] array; persist synthesizes the "## ${field[0].toUpperCase()}${field.slice(1)}" section from it`,
+    ];
+  }
+  if (
+    inBody.length > 0 &&
+    inTicket.length > 0 &&
+    (inBody.length !== inTicket.length ||
+      inBody.some((v, i) => v !== inTicket[i]))
+  ) {
+    return [
+      `${field} disagrees between the body section and the top-level ${field}[] array — author it once, at the top level`,
+    ];
+  }
+  return [];
+}
+
+/**
+ * Schema-light validator for a standalone-Story body, stated against the
+ * same authoring shape the story-author prompt prescribes (Story #4874).
+ *
+ * It parses the body with the canonical Story-body parser and asserts:
+ * a non-empty `## Goal`, at least one `## Changes` entry, no leaking
+ * `Epic: #N` reference (the standalone contract), and an acceptance +
+ * verify contract resolvable from the ticket's top-level arrays **or** the
+ * body's own sections. It deliberately does not demand the `## Acceptance`
+ * / `## Verify` sections of the author — persist synthesizes them.
  *
  * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ *   The ticket's top-level contract arrays, when the caller has them.
  * @returns {{ ok:boolean, errors:string[] }}
  */
-export function validateStoryBody(body) {
-  const errors = [];
+export function validateStoryBody(body, contract = {}) {
   if (typeof body !== 'string' || body.trim().length === 0) {
     return { ok: false, errors: ['body is empty'] };
   }
 
-  for (const section of REQUIRED_SECTIONS) {
-    const pattern = new RegExp(`^##\\s+${escapeRegex(section)}\\s*$`, 'm');
-    if (!pattern.test(body)) {
-      errors.push(`missing required section: "## ${section}"`);
-    }
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [`body is not a parseable Story body: ${err.message}`],
+    };
   }
 
+  const errors = [];
+  if (typeof parsed.goal !== 'string' || parsed.goal.trim() === '') {
+    errors.push('missing required section: "## Goal"');
+  }
+  if (!Array.isArray(parsed.changes) || parsed.changes.length === 0) {
+    errors.push('missing required section: "## Changes"');
+  }
   if (EPIC_REF_PATTERN.test(body)) {
     errors.push(
       'body contains an "Epic: #N" reference — standalone Stories must not link to an Epic',
     );
   }
-
-  // AC checklist non-empty: extract from "## Acceptance Criteria" to the
-  // next "## " heading (or EOF) and assert at least one checklist item.
-  const acStart = body.search(AC_HEADING_PATTERN);
-  if (acStart !== -1) {
-    const rest = body.slice(acStart);
-    const nextHeading = rest.slice(1).search(/^##\s+/m);
-    const acBlock = nextHeading === -1 ? rest : rest.slice(0, nextHeading + 1);
-    if (!CHECKLIST_PATTERN.test(acBlock)) {
-      errors.push(
-        'Acceptance Criteria section has no unchecked checklist items (`- [ ] ...`)',
-      );
-    }
+  for (const field of CONTRACT_FIELDS) {
+    errors.push(
+      ...collectContractErrors(field, parsed[field], contract?.[field]),
+    );
   }
 
   return { ok: errors.length === 0, errors };
 }
 
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Render the canonical `## Acceptance` / `## Verify` sections into a body
+ * that omits them, from the ticket's top-level arrays (Story #4874).
+ *
+ * This is the synthesis the story-author prompt promises: the author writes
+ * each list once at top level, and the persisted GitHub issue still reads as
+ * a complete executable document. A body that already carries a section is
+ * returned untouched — `validateStoryBody` has already refused the case
+ * where the two disagree.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ * @returns {string}
+ */
+export function synthesizeContractSections(body, contract = {}) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch {
+    return body;
+  }
+  const blocks = [];
+  if (
+    (parsed.acceptance ?? []).length === 0 &&
+    Array.isArray(contract.acceptance) &&
+    contract.acceptance.length > 0
+  ) {
+    const items = contract.acceptance
+      .map((a, i) => `- [ ] AC-${i + 1}: ${a}`)
+      .join('\n');
+    blocks.push(`## Acceptance\n${items}`);
+  }
+  if (
+    (parsed.verify ?? []).length === 0 &&
+    Array.isArray(contract.verify) &&
+    contract.verify.length > 0
+  ) {
+    blocks.push(
+      `## Verify\n${contract.verify.map((v) => `- ${v}`).join('\n')}`,
+    );
+  }
+  if (blocks.length === 0) return body;
+  return `${body.trimEnd()}\n\n${blocks.join('\n\n')}\n`;
 }
 
 /**

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -113,9 +113,9 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
-If you do write those sections into the \`body\` string anyway, they must mirror the top-level arrays **item for item** — persist fails closed on a disagreement rather than guessing which list is authoritative. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
+Never hand-mirror either list into the \`body\` — there is no step that asks you to. Persist fails closed on a body section that disagrees with its top-level array rather than guessing which list is authoritative, so writing one anyway only adds a way to be wrong. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
 
-The serialized \`body\` string renders these markdown sections (in order):
+The **persisted** \`body\` renders these markdown sections (in order) — you author every one of them except \`## Acceptance\` / \`## Verify\`, which persist synthesizes from the top-level arrays:
 
     ## Goal
     <one sentence — why this Story exists>
@@ -130,11 +130,11 @@ The serialized \`body\` string renders these markdown sections (in order):
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
     - ...
 
-    ## Acceptance
+    ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
     - [ ] <testable, observable criterion>
     - ...
 
-    ## Verify
+    ## Verify              <-- synthesized by persist from verify[]; do not author
     - <exact command or test path> (<tier>)
     - ...
 

package/.agents/scripts/lib/test-runner-contract.js

@@ -0,0 +1,134 @@
+/**
+ * The contract every test-running entrypoint shares: the `node --test` flag
+ * set, and the per-tier preflight.
+ *
+ * ## Why this is a module and not two literals (Story #4936)
+ *
+ * The repository has two full-tier runners — `run-tests.js` (`npm test`) and
+ * `run-coverage.js` (`npm run test:coverage`, the *required* CI job). When
+ * they disagree about a `node --test` flag, they disagree about whether a
+ * test can execute at all: `--experimental-test-module-mocks` decides whether
+ * `t.mock.module` works, so a divergence makes a suite pass under one runner
+ * and fail under the other with no source defect. `FULL_TIER_GLOBS` in
+ * [`test-tiers.js`](test-tiers.js) already solved the sibling problem for
+ * *which files* run; this module is the same fix for *how they are run*.
+ * Both runners import from here; neither restates a literal.
+ *
+ * ## The preflight is invoked, never hooked
+ *
+ * `.npmrc` sets `ignore-scripts=true` as deliberate defence against malicious
+ * postinstall hooks (CWE-1357). That setting is correct and stays — but it
+ * suppresses every `pre*` / `post*` lifecycle script for `npm run` as well as
+ * for installs, so a `pretest` entry in `package.json` never fires. The
+ * repository carried `pretest`, `pretest:quick` and `pretest:integration`
+ * entries that therefore ran for no tier at all, and Story #4922 worked
+ * around it for the coverage tier alone by having CI name `pretest:coverage`
+ * explicitly. `runTierPreflight` closes the gap for every tier by moving the
+ * invocation into the runners, where it executes under `npm test`,
+ * `npm run test:coverage`, and a bare `node .agents/scripts/run-tests.js`
+ * alike — no lifecycle hook involved.
+ */
+
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+/** 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 of every runner.
+ *
+ * `--test-concurrency` is derived at startup from the host's available
+ * parallelism so the value suits the machine running the suite rather than
+ * being pinned to the historical constant of 8.
+ *
+ * This is the **single** declaration. A flag added here reaches both runners;
+ * a flag added to one runner's argv builder instead is caught by the
+ * flag-set equality assertion in `tests/scripts/run-coverage.test.js`.
+ */
+export const TEST_RUNNER_FLAGS = Object.freeze([
+  '--experimental-test-module-mocks',
+  '--test',
+  `--test-concurrency=${resolveTestConcurrency()}`,
+]);
+
+/**
+ * Preflight scripts per tier, repo-relative. These are the definitions that
+ * used to live in `package.json` as inert `pretest*` entries.
+ *
+ * `full` carries the skills validator on top of the state-probe wrapper
+ * because the full tier is the release-shaped run (and the surface the
+ * coverage tier measures); `quick` and `integration` run the state probe
+ * only, matching the tiers' historical `pretest:quick` / `pretest:integration`
+ * definitions. The coverage runner runs the full tier, so it shares `full`.
+ *
+ * Deliberately not exported: a second importer would be a second place to
+ * read the tier→preflight mapping from, and tests assert the mapping through
+ * the spawns `runTierPreflight` actually issues — which is the thing that
+ * has to be true.
+ */
+const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
+  full: Object.freeze([
+    '.agents/scripts/test-wrapper.js',
+    '.agents/scripts/validate-skills.js',
+  ]),
+  quick: Object.freeze(['.agents/scripts/test-wrapper.js']),
+  integration: Object.freeze(['.agents/scripts/test-wrapper.js']),
+});
+
+/**
+ * Run the preflight for a tier, in order, stopping at the first failure.
+ *
+ * Mirrors npm's own `pre<script>` semantics — a failed preflight aborts
+ * before the test runner is spawned and propagates its exit code (the
+ * wrapper reserves 2 for "preflight refused") — except that it actually
+ * executes, which the npm hook does not under `ignore-scripts=true`.
+ *
+ * @param {object} [opts]
+ * @param {'full' | 'quick' | 'integration'} [opts.tier]
+ * @param {string} [opts.repoRoot] Absolute repository root.
+ * @param {typeof spawnSync} [opts.spawn] Injected in tests.
+ * @param {string} [opts.execPath] Node binary to spawn; injected in tests.
+ * @returns {number} 0 when every preflight script passed, else the first
+ *   non-zero exit code.
+ */
+export function runTierPreflight({
+  tier = 'full',
+  repoRoot = process.cwd(),
+  spawn = spawnSync,
+  execPath = process.execPath,
+} = {}) {
+  for (const script of TIER_PREFLIGHT_SCRIPTS[tier] ?? []) {
+    const run = spawn(execPath, [path.join(repoRoot, script)], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+    if (run.error) throw run.error;
+    const status = run.status ?? 1;
+    if (status !== 0) return status;
+  }
+  return 0;
+}

package/.agents/scripts/lib/test-tiers.js

@@ -35,7 +35,9 @@ const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
  * same way (Story #4195). Without each root here, both the quick /
  * integration walk and the full-tier glob set miss the colocated tests,
  * leaving that coverage dark in `npm test`. The matching full-tier globs
- * live in `FULL_TIER_GLOBS`.
+ * live in the exported `FULL_TIER_GLOBS` — every full-tier runner
+ * (`run-tests.js`, `run-coverage.js`) MUST consume that constant rather than
+ * restate a glob literal, or a runner silently walks a narrower surface.
  */
 const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
 
@@ -44,8 +46,15 @@ const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
  * The `tests` glob is a flat recursive sweep; the `lib` and `.agents/scripts`
  * globs are scoped to `__tests__` subtrees so they only match colocated
  * tests, never the shipped source modules themselves.
+ *
+ * Exported because the full tier has two runners, not one: `run-tests.js`
+ * (via `listTestFilesForTier`) and `run-coverage.js`. Story #4922 — the
+ * coverage runner used to restate `tests/**` on its own, so the 47 colocated
+ * `__tests__` files ran under `npm test` but were absent from the measured
+ * surface, leaving the coverage and CRAP numbers computed over code the
+ * measuring run never executed. Consume this constant; never restate a glob.
  */
-const FULL_TIER_GLOBS = [
+export const FULL_TIER_GLOBS = [
   'tests/**/*.test.js',
   'lib/**/__tests__/**/*.test.js',
   '.agents/scripts/**/__tests__/**/*.test.js',

package/.agents/scripts/lib/ticket-body-sections.js

@@ -235,7 +235,7 @@ export function sliceTicketBodyForDelivery(body) {
   //    survive verbatim.
   const techLoc = locate(working, 'techSpec');
   let techRegion = null;
-  const PLACEHOLDER = 'MANDREL_TECH_SPEC_PLACEHOLDER';
+  const PLACEHOLDER = '\u0000MANDREL_TECH_SPEC_PLACEHOLDER\u0000';
   if (techLoc) {
     const { end } = descriptor('techSpec');
     techRegion = working.slice(techLoc.startIdx, techLoc.endIdx + end.length);

package/.agents/scripts/lib/util/concurrent-map.js

@@ -13,6 +13,23 @@
  *     and would leak otherwise.
  */
 
+/**
+ * The one bound every independent-write fan-out over the GitHub API uses
+ * (Story #4952 raised those loops off serial; Story #4961 made this the single
+ * owner of the number they share). Imported by the `/plan` context gathers,
+ * the persist checkpoint fan-out, the `agent::ready` flips and the supersede
+ * close loop, so re-tuning the policy is one edit rather than six.
+ *
+ * **Why bounded and not unbounded.** Every unit in those fan-outs is its own
+ * API round-trip, so an unbounded map over an N-Story plan dispatches N writes
+ * at once — and GitHub answers a burst with a secondary rate limit rather than
+ * with throughput. The goal is overlapping unrelated waits, not saturating the
+ * API, and four is enough to collapse the latency the serial loops paid while
+ * staying well under the burst threshold. Callers whose ordering is
+ * load-bearing (`createStoryIssues`) stay serial instead of importing this.
+ */
+export const FANOUT_CONCURRENCY = 4;
+
 /**
  * @template T, R
  * @param {ReadonlyArray<T>} items

package/.agents/scripts/lib/util/parse-id-list.js

@@ -0,0 +1,103 @@
+/**
+ * parse-id-list — expand a Story-id list that may contain dash ranges.
+ *
+ * Operators name a contiguous span of Stories the way they read one — as a
+ * range: `/deliver 4922 - 4926`. Enumerating it by hand is the kind of
+ * transcription step that silently drops or invents an id, so the range is a
+ * first-class shape of every delivery id list rather than something the host
+ * expands from prose.
+ *
+ * Accepted tokens, comma-separated:
+ *   - a single id, with an optional `#` — `4922`, `#4922`
+ *   - an inclusive range — `4922-4926`, `4922 - 4926`, `#4922-#4926`
+ *     (hyphen-minus, en dash, or em dash; whitespace around it is fine)
+ *
+ * Everything else is a hard error, never a silent drop: a wrong id list
+ * co-dispatches against the wrong graph, so it must fail where it is typed.
+ * Two range-specific guards exist for the same reason — a backwards range is
+ * refused rather than expanded to nothing, and a span above `MAX_RANGE_SPAN`
+ * is refused rather than resolving thousands of issues off a typo.
+ */
+
+/**
+ * Inclusive-span ceiling for a single range token. Generous against any real
+ * plan run (a handful of Stories) and tight enough that `1-4926` is caught as
+ * the typo it is rather than fanning out into a live resolution sweep.
+ *
+ * Deliberately module-private: the cap is a published contract
+ * (`helpers/deliver-reference.md` § Ranges), so a test that imported it could
+ * not notice the number silently moving out from under the doc.
+ */
+const MAX_RANGE_SPAN = 50;
+
+/** Hyphen-minus, en dash, em dash — whichever the operator's keyboard emits. */
+const DASH = '[-–—]';
+const SINGLE_RE = /^#?(\d+)$/;
+const RANGE_RE = new RegExp(`^#?(\\d+)\\s*${DASH}\\s*#?(\\d+)$`);
+
+/**
+ * Parse a comma-separated Story-id list, expanding any `A-B` range token.
+ *
+ * Absent or empty input is not an error here — it yields an empty list, and
+ * the caller decides whether that is a usage error (`--ids`) or a legitimate
+ * empty set (`--done`).
+ *
+ * @param {string|undefined|null} raw
+ * @param {object} [options]
+ * @param {string} [options.flag] Flag name, for the error message.
+ * @param {string} [options.prefix] Message prefix, for the caller's log tag.
+ * @param {number} [options.maxSpan] Inclusive-span ceiling per range token.
+ * @returns {{ ids: number[]|null, error: string|null }}
+ */
+export function expandIdList(raw, options = {}) {
+  const { flag = '--ids', prefix = '', maxSpan = MAX_RANGE_SPAN } = options;
+  const fail = (message) => ({ ids: null, error: `${prefix}${message}` });
+
+  const ids = [];
+  const seen = new Set();
+  const push = (n) => {
+    if (seen.has(n)) return;
+    seen.add(n);
+    ids.push(n);
+  };
+
+  for (const token of String(raw ?? '').split(',')) {
+    const trimmed = token.trim();
+    if (trimmed === '') continue;
+
+    const range = RANGE_RE.exec(trimmed);
+    if (range) {
+      const start = Number(range[1]);
+      const end = Number(range[2]);
+      if (start <= 0 || end <= 0) {
+        return fail(
+          `${flag} range "${trimmed}" must use positive issue numbers.`,
+        );
+      }
+      if (end < start) {
+        return fail(
+          `${flag} range "${trimmed}" runs backwards — write it low-to-high (e.g. 4922-4926).`,
+        );
+      }
+      const span = end - start + 1;
+      if (span > maxSpan) {
+        return fail(
+          `${flag} range "${trimmed}" spans ${span} ids, above the ${maxSpan}-id cap. Narrow it, or list the ids.`,
+        );
+      }
+      for (let n = start; n <= end; n++) push(n);
+      continue;
+    }
+
+    const single = SINGLE_RE.exec(trimmed);
+    const n = single ? Number(single[1]) : Number.NaN;
+    if (!Number.isInteger(n) || n <= 0) {
+      return fail(
+        `${flag} must be a comma-separated list of positive issue numbers or A-B ranges (got "${trimmed}").`,
+      );
+    }
+    push(n);
+  }
+
+  return { ids, error: null };
+}

package/.agents/scripts/lib/util/poll-loop.js

@@ -13,6 +13,13 @@
  * `sleep` is exported as the cancellable delay primitive used internally;
  * callers that already have their own cadence (e.g. a continuous ticker)
  * can import it directly.
+ *
+ * `sleepFn` is the inter-tick delay seam (Story #4873). A caller that already
+ * owns a delay seam of its own — the close-and-land merge wait, whose suite
+ * must never actually sleep out a 30s poll interval — passes it here so
+ * adopting this primitive does not cost it that seam. It is called as
+ * `sleepFn(intervalMs, signal)`; a one-argument stub simply ignores the
+ * signal, and the default is the cancellable {@link sleep} below.
  */
 
 /**
@@ -23,11 +30,20 @@
  *   timeoutMs?: number,
  *   signal?: AbortSignal,
  *   logger?: { warn?: Function },
+ *   sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>,
  * }} opts
  * @returns {Promise<any | undefined>}
  */
 export async function pollUntil(opts) {
-  const { fn, predicate, intervalMs, timeoutMs, signal, logger } = opts;
+  const {
+    fn,
+    predicate,
+    intervalMs,
+    timeoutMs,
+    signal,
+    logger,
+    sleepFn = sleep,
+  } = opts;
   if (typeof fn !== 'function') throw new TypeError('pollUntil: fn required');
   if (typeof predicate !== 'function') {
     throw new TypeError('pollUntil: predicate required');
@@ -52,7 +68,7 @@ export async function pollUntil(opts) {
     if (deadline !== null && Date.now() >= deadline) {
       throw new Error(`pollUntil: timed out after ${timeoutMs}ms`);
     }
-    await sleep(intervalMs, signal);
+    await sleepFn(intervalMs, signal);
   }
   return undefined;
 }