mandrel 2.24.0 → 2.26.0

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,14 +239,15 @@ 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
  * caller tracked in-flight itself; probe mode must put them back.
  *
  * @returns {Promise<{
- *   nodes: Array<{id: number, dependsOn: number[], files: string[], labels: string[]}>,
+ *   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[],
@@ -282,6 +283,11 @@ 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 `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);
   // A Story another operator's lease holds occupies a (global) dispatch slot
   // just like an in-flight one: fold it into the in-flight set so it is both
@@ -289,14 +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,
-      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),
@@ -310,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,20 +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' declared 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).
- *   - `selectReadySet({ stories, doneIds, inFlight, globalCap })` — the
- *     scheduler. Returns the deterministic, overlap-free set of ready
- *     Stories, capped at `globalCap − inFlight`.
+ *   - `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).
+ *   - `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
@@ -169,37 +185,109 @@ function isGlobPath(path) {
 }
 
 /**
- * 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.
- *
- * Two deliberate asymmetries:
- *
- *   - **An empty footprint means "no known overlap"** → `false`. A Story that
- *     declares no files is never withheld. This is permissive by necessity:
- *     an undeclared 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.
+ * Repo-relative file paths as they appear in Story prose: at least one `/`
+ * separator and a short file extension. Deliberately narrow — a token has to
+ * look like a real path before it can widen a footprint and withhold a Story.
+ */
+const PROSE_PATH_RE = /(?:[\w.@~-]+\/)+[\w.@-]+\.[A-Za-z0-9]{1,6}/g;
+
+/**
+ * Scrape file paths a Story's **text** mentions but its `changes[]` never
+ * declared (Story #4875).
+ *
+ * The declared footprint is a planner's *prediction*, and it is systematically
+ * a lower bound: a Story's `## Spec` names the module it must also touch, its
+ * acceptance criteria name the caller that must be updated, and none of that
+ * reaches `changes[]`. The overlap guard exists to stop two Stories racing the
+ * same file, so trusting the declaration outright means the guard is blind to
+ * precisely the collisions nobody predicted.
+ *
+ * Evidence is only ever **added** — nothing here can shrink a declared
+ * footprint, so widening can withhold a Story for a beat but can never
+ * co-dispatch one the declared comparison would have caught.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyEvidencePaths(story) {
+  const out = new Set();
+  for (const field of [story?.title, story?.body, story?.spec]) {
+    if (typeof field !== 'string' || field === '') continue;
+    for (const match of field.matchAll(PROSE_PATH_RE)) {
+      const trimmed = match[0].trim();
+      if (trimmed) out.add(trimmed);
+    }
+  }
+  return out;
+}
+
+/**
+ * A Story's footprint **widened from observable evidence** — the set the
+ * co-dispatch guard actually compares (Story #4875).
+ *
+ * `declared ∪ scraped-from-prose`. See {@link storyEvidencePaths} for why the
+ * declaration is treated as a lower bound rather than the answer.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyWidenedFootprint(story) {
+  const out = storyFootprint(story);
+  for (const path of storyEvidencePaths(story)) out.add(path);
+  return out;
+}
+
+/**
+ * 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[]`
+ * is a lower bound on what a Story will touch, and two Stories whose real edits
+ * collide were being co-dispatched whenever the collision was not predicted
+ * (Story #4875).
+ *
+ * **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.
+ *
+ * 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 = storyFootprint(a);
-  if (fa.size === 0) return false;
-  const fb = storyFootprint(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;
@@ -207,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.
  *
@@ -240,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.
@@ -261,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
@@ -309,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

@@ -24,7 +24,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -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
@@ -88,7 +89,7 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
   const prepare = deps.prepare ?? prepareSourceForScoring;
   const analyze = deps.analyze ?? analyzeOnce;
 
@@ -150,7 +151,10 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   }
 
   const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
-    finalizeMethodRows(rawCrapRows, { requireCoverage });
+    finalizeMethodRows(rawCrapRows, {
+      requireCoverage,
+      coverageAvailable,
+    });
   return reply({
     miScore,
     crapRows: rows,
@@ -160,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

@@ -11,7 +11,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -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
@@ -80,7 +81,7 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
 
   // Coverage entry is pre-resolved on the host and attached to the item.
   // `item.coverageEntry` may be explicitly `null` when the file has no
@@ -143,7 +144,10 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
     );
   }
 
-  const finalized = finalizeMethodRows(methodRows, { requireCoverage });
+  const finalized = finalizeMethodRows(methodRows, {
+    requireCoverage,
+    coverageAvailable,
+  });
   return {
     kind: 'reply',
     message: {
@@ -158,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);
+  });
+}