mandrel 2.25.0 → 2.26.0

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/wave-runner/live-probe.js

@@ -2,7 +2,7 @@
  * lib/wave-runner/live-probe.js — the state-probing adapter that feeds the
  * ready-set kernel from live GitHub state.
  *
- * `selectReadySet` (`./ready-set.js`) is deliberately a pure, side-effect-free
+ * `planReadySet` (`./ready-set.js`) is deliberately a pure, side-effect-free
  * kernel: callers hand it the live Story records, the done set, and the
  * in-flight count, and it decides. Until now the only adapter was the
  * flag-driven one (`stories-wave-tick.js --dag/--done/--in-flight`), which
@@ -41,7 +41,7 @@
  *     "waiting" (Story #4601).
  *
  * It is an **adapter, not a kernel change**: it gathers inputs and hands them
- * to `selectReadySet` unchanged. The kernel stays pure and flag-driven, and
+ * to `planReadySet` unchanged. The kernel stays pure and flag-driven, and
  * the legacy flag mode stays byte-compatible.
  *
  * The graph resolution is **not** reimplemented here — it reuses
@@ -217,7 +217,7 @@ export function createProbeContext({
 
 /**
  * Probe live state for a set of Story ids and return the exact inputs
- * `selectReadySet` consumes.
+ * `planReadySet` consumes.
  *
  * Mirrors `resolve-stories.js`'s two-pass envelope build: a provisional pass
  * yields the DAG whose foreign dependency ids are then resolved against live
@@ -239,7 +239,7 @@ export function createProbeContext({
  *   skipped (the probe never fails closed).
  * @param {(msg: string) => void} [args.warn]
  * Each returned node carries its **live labels**. That is load-bearing, not
- * decoration: `selectReadySet` classifies from labels, so a node stripped of
+ * decoration: `planReadySet` classifies from labels, so a node stripped of
  * them reads as `ready` and an `agent::executing` Story gets re-dispatched
  * onto a second branch while its first run is still going. The resolver's DAG
  * projection (`{id, dependsOn, files}`) drops labels because flag mode's
@@ -247,6 +247,7 @@ export function createProbeContext({
  *
  * @returns {Promise<{
  *   nodes: Array<{id: number, dependsOn: number[], files: string[], body: string, labels: string[]}>,
+ *   inFlightRecords: Array<{id: number, dependsOn: number[], files: string[], body: string, labels: string[]}>,
  *   doneIds: Set<number>,
  *   inFlight: number,
  *   blockedIds: number[],
@@ -284,7 +285,7 @@ export async function probeLiveState({
   const labelsById = new Map(stories.map((s) => [s.id, s.labels ?? []]));
   // Bodies ride along with the node so the co-dispatch guard can widen a
   // declared footprint from the paths a Story's own text names (Story #4875).
-  // They are consumed in-process by `selectReadySet` and never serialized into
+  // They are consumed in-process by `planReadySet` and never serialized into
   // the beat envelope, which stays a list of ids.
   const bodyById = new Map(stories.map((s) => [s.id, s.body ?? '']));
   const inFlightIds = deriveInFlightIds(stories, dispatched);
@@ -294,15 +295,24 @@ export async function probeLiveState({
   // never dispatched by this run.
   const foreignHeld = deriveForeignHeld(stories, self, warn);
   for (const id of foreignHeld.keys()) inFlightIds.add(id);
+  const nodes = envelope.dag.map((node) => ({
+    ...node,
+    body: bodyById.get(node.id) ?? '',
+    labels: projectInFlightLabels(
+      labelsById.get(node.id) ?? [],
+      inFlightIds.has(node.id),
+    ),
+  }));
   return {
-    nodes: envelope.dag.map((node) => ({
-      ...node,
-      body: bodyById.get(node.id) ?? '',
-      labels: projectInFlightLabels(
-        labelsById.get(node.id) ?? [],
-        inFlightIds.has(node.id),
-      ),
-    })),
+    nodes,
+    // The same nodes, narrowed to the Stories occupying a slot. `inFlight` is
+    // only a count, so it can shrink capacity but can never stop a Story
+    // admitted now from sharing files with one dispatched on an earlier beat
+    // and still implementing. These records carry the `files[]` and `body` the
+    // co-dispatch guard needs, so the kernel can RESERVE those footprints
+    // rather than merely count them (Story #4950). No extra fetch: this is a
+    // projection of what the probe already read.
+    inFlightRecords: nodes.filter((node) => inFlightIds.has(node.id)),
     doneIds: new Set(envelope.done),
     inFlight: inFlightIds.size,
     blockedIds: deriveBlockedIds(stories),
@@ -316,7 +326,7 @@ export async function probeLiveState({
  *
  * This is the load-bearing half of the dispatch-window fix, and it is why
  * `inFlight` alone is not enough. The two inputs do **different** jobs inside
- * `selectReadySet`:
+ * `planReadySet`:
  *
  *   - `inFlight` is only a **count**. It reserves capacity (`slots = cap −
  *     inFlight`) and nothing more.

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -19,24 +19,36 @@
  * `stories-wave-tick.js` adapter wires this core; this module does not
  * modify that CLI surface.
  *
- * Three exports:
+ * The scheduling surface:
  *   - `classifyStory(story)` — live-label classifier mapping a Story
  *     record's labels + issue state to one of `done | blocked | executing |
  *     ready`. Mirrors the done-predicate this module uses
  *     (`agent::done` OR closed issue) so a Story closed manually through
  *     the GitHub UI is recognised as done.
- *   - `storiesOverlap(a, b)` — the file-overlap co-dispatch guard: true
- *     when two Stories' file footprints intersect. Two Stories that would
- *     touch the same file MUST NOT be dispatched onto parallel
- *     `story-<id>` branches in the same beat (they would race the same
- *     path and produce a merge conflict at close). The comparison runs over
+ *   - `storiesOverlap(a, b)` — the **beat-local** file-overlap co-dispatch
+ *     guard: true when two Stories' file footprints intersect. Two Stories
+ *     that would touch the same file MUST NOT be admitted onto parallel
+ *     `story-<id>` branches on the same beat (they would race the same path
+ *     and produce a merge conflict at close). The comparison runs over
  *     the **widened** footprint (`storyWidenedFootprint`) — a declared
  *     `changes[]` is treated as a lower bound and widened from the paths the
  *     Story's own text names, because a guard that trusts a prediction cannot
  *     prevent the collision nobody predicted (Story #4875).
- *   - `selectReadySet({ stories, doneIds, inFlight, globalCap })` — the
- *     scheduler. Returns the deterministic, overlap-free set of ready
- *     Stories, capped at `globalCap − inFlight`.
+ *   - `planReadySet({ stories, doneIds, inFlight, globalCap,
+ *     inFlightRecords })` — the scheduler. Returns the deterministic,
+ *     overlap-free dispatch set (capped at `globalCap − inFlight`) **and**
+ *     the Stories it withheld because a **concrete** path in their footprint
+ *     is reserved by a Story still in flight from an earlier beat.
+ *
+ * The two guards deliberately draw the glob/UNKNOWN class differently
+ * (Story #4960). Within a beat an unknown-width footprint overlaps
+ * everything, because admitting two Stories whose real widths are unknown is
+ * the collision the guard exists to prevent. Across beats it reserves
+ * nothing: an in-flight Story's window spans its whole implementation, so a
+ * glob that reserved cross-beat would withhold every other Story for
+ * minutes-to-hours — and `resolve-stories.js` substitutes the UNKNOWN
+ * sentinel for any body it cannot parse, so a single malformed Story body
+ * would collapse an N-Story run to fully serial.
  *
  * Adjacency is re-derived from the supplied records via the shared
  * `buildStoryAdjacency` builder (`lib/story-adjacency.js`) — the same
@@ -226,11 +238,29 @@ function storyWidenedFootprint(story) {
 }
 
 /**
- * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
- * file footprints intersect — meaning they would race the same file if
- * dispatched onto parallel `story-<id>` branches in the same beat. Two
- * Stories that overlap MUST NOT both appear in one dispatch set; one is
- * withheld until the other clears.
+ * Both Stories' widened footprints, or `null` when either is empty.
+ *
+ * **An empty footprint means "no known overlap"**, so both guards below
+ * short-circuit to `false` on one. This is permissive by necessity: a Story
+ * with no declared footprint and no path evidence in its text carries no
+ * information, and withholding on absence would serialize every run.
+ *
+ * @param {StoryRecord} a
+ * @param {StoryRecord} b
+ * @returns {[Set<string>, Set<string>]|null}
+ */
+function widenedFootprintPair(a, b) {
+  const fa = storyWidenedFootprint(a);
+  if (fa.size === 0) return null;
+  const fb = storyWidenedFootprint(b);
+  if (fb.size === 0) return null;
+  return [fa, fb];
+}
+
+/**
+ * **Beat-local** file-overlap co-dispatch guard. Returns `true` when two
+ * Stories' file footprints intersect — meaning they would race the same file
+ * if both were admitted onto parallel `story-<id>` branches on this beat.
  *
  * Comparison runs over the **widened** footprint
  * ({@link storyWidenedFootprint}), not the declaration: a declared `changes[]`
@@ -238,32 +268,26 @@ function storyWidenedFootprint(story) {
  * collide were being co-dispatched whenever the collision was not predicted
  * (Story #4875).
  *
- * Two deliberate asymmetries:
+ * **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
+ * Comparison is exact-string, so a Story declaring `.agents/scripts/lib/**`
+ * would not match another declaring `.agents/scripts/lib/story-adjacency.js` —
+ * the guard would silently pass two Stories that genuinely race. Unknown width
+ * is not the same as no width: fail safe by serializing the rest of the beat.
  *
- *   - **An empty footprint means "no known overlap"** → `false`. A Story with
- *     no declared footprint and no path evidence in its text is never
- *     withheld. This is permissive by necessity: a genuinely unknown footprint
- *     carries no information, and withholding on absence would serialize every
- *     run.
- *   - **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
- *     Comparison is exact-string, so a Story declaring
- *     `.agents/scripts/lib/**` would not match another declaring
- *     `.agents/scripts/lib/story-adjacency.js` — the guard would silently
- *     pass two Stories that genuinely race. Unknown width is not the same as
- *     no width: fail safe by serializing.
+ * That fail-safe is **beat-local and stays that way**. The cross-beat
+ * reservation uses {@link reservesConcretePath} instead, because a beat is a
+ * moment and an in-flight window is an implementation (Story #4960).
  *
  * @param {StoryRecord} a
  * @param {StoryRecord} b
  * @returns {boolean}
  */
 export function storiesOverlap(a, b) {
-  const fa = storyWidenedFootprint(a);
-  if (fa.size === 0) return false;
-  const fb = storyWidenedFootprint(b);
-  if (fb.size === 0) return false;
+  const pair = widenedFootprintPair(a, b);
+  if (pair === null) return false;
+  const [fa, fb] = pair;
   for (const path of fa) {
-    if (isGlobPath(path)) return true;
-    if (fb.has(path)) return true;
+    if (isGlobPath(path) || fb.has(path)) return true;
   }
   for (const path of fb) {
     if (isGlobPath(path)) return true;
@@ -271,6 +295,42 @@ export function storiesOverlap(a, b) {
   return false;
 }
 
+/**
+ * **Cross-beat** reservation guard: `true` only when the two widened
+ * footprints share a **concrete** (non-glob) path.
+ *
+ * A Story dispatched on an earlier beat holds its footprint for its entire
+ * implementation window, not for a moment, so the two guards cannot share a
+ * predicate (Story #4960):
+ *
+ *   - A **concrete** shared path is a real, named collision — two branches
+ *     editing `lib/foo.js` conflict at close whether the peer was admitted
+ *     alongside or hours ago. It reserves, exactly as Story #4950 shipped.
+ *   - A **glob** — or the UNKNOWN sentinel `resolve-stories.js` substitutes
+ *     for an unparseable body — names no file. Reserving on it withheld every
+ *     eligible Story against a single unknown-width blocker for that blocker's
+ *     whole window, which is strictly worse than the serial run the
+ *     reservation was meant to speed up. Glob paths are therefore skipped on
+ *     both sides here; the beat-local {@link storiesOverlap} fail-safe is
+ *     unchanged and still serializes them within a beat.
+ *
+ * Set intersection is symmetric, so scanning the reserving side alone finds
+ * every shared concrete path.
+ *
+ * @param {StoryRecord} held      The in-flight Story holding the reservation.
+ * @param {StoryRecord} candidate The Story being considered for admission.
+ * @returns {boolean}
+ */
+function reservesConcretePath(held, candidate) {
+  const pair = widenedFootprintPair(held, candidate);
+  if (pair === null) return false;
+  const [fa, fb] = pair;
+  for (const path of fa) {
+    if (!isGlobPath(path) && fb.has(path)) return true;
+  }
+  return false;
+}
+
 /**
  * Select the set of Stories safe to dispatch on this beat.
  *
@@ -304,10 +364,12 @@ export function storiesOverlap(a, b) {
  *      already occupying a slot (executing / closing / dispatched-not-yet-
  *      labelled). When `slots <= 0`, the result is empty.
  *   5. **Overlap guard.** Greedily admit eligible Stories in ascending-id
- *      order, skipping any whose file footprint overlaps an
- *      already-admitted Story (`storiesOverlap`). A withheld Story stays
- *      eligible and is naturally re-considered on the next beat once its
- *      overlapping peer has cleared.
+ *      order, skipping any whose file footprint overlaps a Story **already
+ *      admitted this beat** ({@link storiesOverlap}) or shares a **concrete**
+ *      path with a Story **still in flight from an earlier beat**
+ *      (`inFlightRecords`, {@link reservesConcretePath}). A withheld Story
+ *      stays eligible and is naturally re-considered on the next beat once
+ *      the Story reserving its files has cleared.
  *
  * The result is deterministic: eligible Stories are considered in
  * ascending-id order, so the same inputs always yield the same set.
@@ -325,22 +387,37 @@ export function storiesOverlap(a, b) {
  *   step 1 above). `false` keeps a foreign dependency as a gate
  *   (standalone / operator-DAG semantics); `true` prunes foreign edges so
  *   the DAG stays closed over the scheduled set (Epic semantics).
- * @returns {StoryRecord[]} The dispatch set: a subset of `stories`,
- *   ascending by id, overlap-free, length ≤ `globalCap − inFlight`.
+ * @param {StoryRecord[]} [args.inFlightRecords=[]] Records for the Stories
+ *   already in flight, whose **concrete** footprint paths this beat must
+ *   **reserve** rather than merely count. `inFlight` is a number and can only
+ *   shrink capacity; without the records a Story admitted now can share files
+ *   with one dispatched on an earlier beat and still implementing — a
+ *   guaranteed merge conflict at close (Story #4950). A glob / UNKNOWN
+ *   footprint reserves nothing (Story #4960). Callers that hold only ids (the
+ *   `--dag`/`--in-flight` flag mode) pass nothing and get the pre-#4950
+ *   same-beat-only behaviour.
+ * @returns {{ selected: StoryRecord[], withheldByInFlight: Array<{id: number, blockedBy: number}> }}
+ *   `selected` is the dispatch set: a subset of `stories`, ascending by id,
+ *   overlap-free, length ≤ `globalCap − inFlight`. `withheldByInFlight`
+ *   names each eligible Story a reservation held back and the in-flight
+ *   Story that holds it.
  */
-export function selectReadySet({
+export function planReadySet({
   stories,
   doneIds = [],
   inFlight = 0,
   globalCap,
   dropForeign = false,
+  inFlightRecords = [],
 } = {}) {
   const records = Array.isArray(stories) ? stories : [];
   const cap = Number.isInteger(globalCap) ? globalCap : 0;
   const inFlightCount =
     Number.isInteger(inFlight) && inFlight > 0 ? inFlight : 0;
   const slots = Math.max(0, cap - inFlightCount);
-  if (slots <= 0 || records.length === 0) return [];
+  if (slots <= 0 || records.length === 0) {
+    return { selected: [], withheldByInFlight: [] };
+  }
 
   // Step 1 — adjacency keyed by id. The `dropForeign` policy decides whether
   // a dependency on an id outside the supplied set gates the dependent
@@ -373,13 +450,83 @@ export function selectReadySet({
   }
 
   // Steps 4 + 5 — greedily admit up to `slots`, skipping file-overlap
-  // collisions against the already-admitted set.
+  // collisions against the already-admitted set AND against the footprints
+  // reserved by Stories still in flight from an earlier beat.
+  return admitStories({
+    eligibleIds,
+    byId,
+    slots,
+    reserved: Array.isArray(inFlightRecords) ? inFlightRecords : [],
+  });
+}
+
+/**
+ * Greedily admit eligible Stories in ascending-id order under two distinct
+ * withholding rules, and report which ones a reservation held back.
+ *
+ * The two rules are distinct predicates, not one applied twice: the
+ * cross-beat reservation matches only a shared **concrete** path
+ * ({@link reservesConcretePath}), while the same-beat guard also serializes
+ * unknown-width footprints ({@link storiesOverlap}). See both for why.
+ *
+ * The reservation check runs **first**, so a Story racing both an in-flight
+ * Story and a same-beat peer is reported against the in-flight one: that is
+ * the longer-lived and more informative blocker (a Story that has been
+ * implementing for beats, not one merely admitted a moment ago), and checking
+ * it first is what makes the report complete — every withheld-by-reservation
+ * Story appears in it. Ordering cannot change `selected`: a candidate either
+ * rule rejects is skipped whichever runs first; only which list it is
+ * reported in depends on the order.
+ *
+ * @param {object} args
+ * @param {number[]} args.eligibleIds        Ascending eligible Story ids.
+ * @param {Map<number, StoryRecord>} args.byId
+ * @param {number} args.slots                Remaining dispatch capacity.
+ * @param {StoryRecord[]} args.reserved      In-flight Story records.
+ * @returns {{ selected: StoryRecord[], withheldByInFlight: Array<{id: number, blockedBy: number}> }}
+ */
+function admitStories({ eligibleIds, byId, slots, reserved }) {
   const selected = [];
+  const withheldByInFlight = [];
   for (const id of eligibleIds) {
     if (selected.length >= slots) break;
     const rec = byId.get(id);
+    const blockedBy = findInFlightBlocker(rec, id, reserved);
+    if (blockedBy !== null) {
+      withheldByInFlight.push({ id, blockedBy });
+      continue;
+    }
     if (selected.some((picked) => storiesOverlap(picked, rec))) continue;
     selected.push(rec);
   }
-  return selected;
+  return { selected, withheldByInFlight };
+}
+
+/**
+ * The id of the in-flight Story whose widened footprint reserves a concrete
+ * path the candidate would race, or `null` when none does.
+ *
+ * Two records are skipped rather than treated as blockers:
+ *
+ *   - **The candidate itself.** Probe mode hands the whole record set to both
+ *     arguments, and an in-flight Story classifies `executing` rather than
+ *     `ready`, so a candidate can never legitimately appear here — but a
+ *     caller that double-lists one Story must not have it withhold itself.
+ *   - **An unidentifiable record.** A withholding this function cannot name
+ *     is one the envelope cannot explain, and an unexplained unfilled slot is
+ *     the exact operator-facing failure this reservation exists to remove.
+ *     Probe-mode records always carry an integer id, so this is defensive.
+ *
+ * @param {StoryRecord} candidate
+ * @param {number} candidateId
+ * @param {StoryRecord[]} reserved
+ * @returns {number|null}
+ */
+function findInFlightBlocker(candidate, candidateId, reserved) {
+  for (const held of reserved) {
+    const heldId = storyIdOf(held);
+    if (heldId === null || heldId === candidateId) continue;
+    if (reservesConcretePath(held, candidate)) return heldId;
+  }
+  return null;
 }

package/.agents/scripts/lib/workers/combined-mi-crap-worker.js

@@ -47,6 +47,7 @@ import { parentPort } from 'node:worker_threads';
 import { finalizeMethodRows } from '../crap-engine.js';
 import { analyzeOnce } from '../crap-utils.js';
 import { prepareSourceForScoring } from '../transpile.js';
+import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit tests
@@ -163,13 +164,6 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   });
 }
 
-if (parentPort) {
-  parentPort.on('message', (msg) => {
-    const out = handleCombinedMiCrapWorkerMessage(msg);
-    if (out.kind === 'exit') {
-      parentPort.close();
-      return;
-    }
-    parentPort.postMessage(out.message);
-  });
-}
+serveWorkerMessages(parentPort, (msg) =>
+  handleCombinedMiCrapWorkerMessage(msg),
+);

package/.agents/scripts/lib/workers/crap-worker.js

@@ -32,6 +32,7 @@
 import { parentPort } from 'node:worker_threads';
 import { calculateCrapForSource, finalizeMethodRows } from '../crap-engine.js';
 import { prepareSourceForScoring } from '../transpile.js';
+import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit
@@ -161,13 +162,4 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
   };
 }
 
-if (parentPort) {
-  parentPort.on('message', (msg) => {
-    const out = handleCrapWorkerMessage(msg, null);
-    if (out.kind === 'exit') {
-      parentPort.close();
-      return;
-    }
-    parentPort.postMessage(out.message);
-  });
-}
+serveWorkerMessages(parentPort, (msg) => handleCrapWorkerMessage(msg, null));

package/.agents/scripts/lib/workers/maintainability-report-worker.js

@@ -40,6 +40,7 @@ import {
   calculateReportForFile,
 } from '../maintainability-engine.js';
 import { transpileIfNeeded } from '../transpile.js';
+import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
  * Score a pre-sourced content string (Story #3696). Mirrors
@@ -125,13 +126,6 @@ export function handleMaintainabilityReportWorkerMessage(msg, deps = {}) {
   }
 }
 
-if (parentPort) {
-  parentPort.on('message', (msg) => {
-    const out = handleMaintainabilityReportWorkerMessage(msg);
-    if (out.kind === 'exit') {
-      parentPort.close();
-      return;
-    }
-    parentPort.postMessage(out.message);
-  });
-}
+serveWorkerMessages(parentPort, (msg) =>
+  handleMaintainabilityReportWorkerMessage(msg),
+);

package/.agents/scripts/lib/workers/maintainability-worker.js

@@ -21,6 +21,7 @@
 
 import { parentPort } from 'node:worker_threads';
 import { scoreFile } from '../maintainability-engine.js';
+import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit
@@ -72,13 +73,6 @@ export function handleMaintainabilityWorkerMessage(msg, deps = {}) {
   }
 }
 
-if (parentPort) {
-  parentPort.on('message', (msg) => {
-    const out = handleMaintainabilityWorkerMessage(msg);
-    if (out.kind === 'exit') {
-      parentPort.close();
-      return;
-    }
-    parentPort.postMessage(out.message);
-  });
-}
+serveWorkerMessages(parentPort, (msg) =>
+  handleMaintainabilityWorkerMessage(msg),
+);

package/.agents/scripts/lib/workers/serve-worker-messages.js

@@ -0,0 +1,35 @@
+/**
+ * lib/workers/serve-worker-messages.js — the shared CPU-pool worker skeleton.
+ *
+ * Every worker under `lib/workers/` is a pure message handler plus the same
+ * eight-line `parentPort` wiring: subscribe, run the handler, close on an
+ * `exit` verdict, post the reply otherwise. That wiring was copied into all
+ * four workers; it lives here once instead (Story #4926).
+ *
+ * The handler contract is unchanged — see `lib/cpu-pool.js`:
+ *   IN  : `{ item: … }` — one unit of work
+ *         `{ exit: true }` — drain & terminate
+ *   OUT : `{ kind: 'exit' }` | `{ kind: 'reply', message: object }`
+ */
+
+/**
+ * Wire a pure worker message handler onto a `worker_threads` port.
+ *
+ * A falsy `port` is a no-op, so a worker module imported directly by a unit
+ * test (where `parentPort` is `null`) installs no listener and stays pure.
+ *
+ * @param {import('node:worker_threads').MessagePort|null|undefined} port
+ * @param {(msg: unknown) => {kind: 'exit'} | {kind: 'reply', message: object}} handle
+ * @returns {void}
+ */
+export function serveWorkerMessages(port, handle) {
+  if (!port) return;
+  port.on('message', (msg) => {
+    const out = handle(msg);
+    if (out.kind === 'exit') {
+      port.close();
+      return;
+    }
+    port.postMessage(out.message);
+  });
+}