mandrel 2.25.0 → 2.26.0

package/.agents/scripts/stories-wave-tick.js

@@ -5,7 +5,7 @@
  * `/deliver` story-list path.
  *
  * Thin **adapter** over the path-agnostic ready-set scheduling core
- * (`lib/wave-runner/ready-set.js#selectReadySet`). It emits the set of
+ * (`lib/wave-runner/ready-set.js#planReadySet`). It emits the set of
  * Stories safe to dispatch **on this beat** — a Story becomes dispatchable
  * the instant its own dependencies are done, under the same global
  * concurrency cap and the same file-overlap co-dispatch guard
@@ -15,7 +15,7 @@
  * The previous static wave-batch plan (group N must fully drain before
  * group N+1 opens, via `Graph.js#assignLayers`) is gone. The scheduling
  * kernel — adjacency derivation, the done-predicate classifier, the
- * eligibility rule, and the overlap guard — lives once in `selectReadySet`;
+ * eligibility rule, and the overlap guard — lives once in `planReadySet`;
  * this file only gathers input, resolves the cap, and renders the envelope.
  *
  * **Two modes, one kernel.**
@@ -54,9 +54,22 @@
  *     concurrencyCap: number,
  *     inFlight: number,
  *     cycleError: string | null,
- *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null
+ *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null,
+ *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason }], note }
  *   }
  *
+ * `inFlightReservation` reports the cross-beat half of the co-dispatch guard
+ * (Story #4875 widened the footprint; Story #4950 made it reserve). Under
+ * `--probe-live` the in-flight Stories' own records are handed to the kernel,
+ * so a candidate sharing a CONCRETE path with a Story dispatched on an EARLIER
+ * beat is withheld and named here with its blocker and a `reason`
+ * (`in-flight-earlier-beat` or `foreign-lease`). A glob / UNKNOWN footprint
+ * reserves nothing across beats — it would withhold the whole run for one
+ * blocker's entire implementation window — while still serializing its own
+ * beat (Story #4960). Flag mode carries a count and no records, so it reports
+ * `available: false` rather than an empty — and therefore indistinguishable —
+ * result.
+ *
  * Probe mode adds fields the caller can no longer compute for itself:
  * `done: number[]` (the resolved done set, in-set ∪ satisfied foreign
  * blockers), `epilogueDue: boolean` (true exactly when every listed Story
@@ -104,12 +117,13 @@ import { Logger } from './lib/Logger.js';
 import { AGENT_LABELS } from './lib/label-constants.js';
 import { parseIds } from './lib/orchestration/resolve-stories.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
+import { expandIdList } from './lib/util/parse-id-list.js';
 import {
   createProbeContext,
   probeLiveState,
   validateProbeFlags,
 } from './lib/wave-runner/live-probe.js';
-import { selectReadySet } from './lib/wave-runner/ready-set.js';
+import { planReadySet } from './lib/wave-runner/ready-set.js';
 
 /**
  * Exit code for a wedged run — deliberately distinct from the cycle exit (2)
@@ -135,7 +149,7 @@ const HELP = `Usage:
 Continuous ready-set planner for standalone Story delivery. Emits the set of
 Stories safe to dispatch on this beat — a Story is dispatchable the instant
 its own dependencies are done — plus the resolved per-beat concurrency cap
-and the same file-overlap guard as selectReadySet.
+and the same file-overlap guard as planReadySet.
 
 Two modes:
   --probe-live  Resolve the graph and derive done / in-flight from LIVE state
@@ -153,9 +167,10 @@ Each entry must include:
   dependsOn  - Array of Story IDs that must complete before this Story runs
 
 Options:
-  --stories <csv>    Story ids to deliver (probe mode). The graph, the done
-                     set, and the in-flight count are resolved from live
-                     state — no --done / --in-flight bookkeeping.
+  --stories <csv>    Story ids to deliver (probe mode). Singles or inclusive
+                     A-B ranges (101,104-107). The graph, the done set, and
+                     the in-flight count are resolved from live state — no
+                     --done / --in-flight bookkeeping.
   --probe-live       Enable probe mode. Requires --stories.
   --dispatched <csv> Probe mode only. Ids you have SPAWNED this run. Unioned
                      into the live-derived in-flight set, then filtered by
@@ -196,9 +211,20 @@ Output envelope:
     },
     "inFlight": 0,
     "cycleError": null,
-    "wedged": null
+    "wedged": null,
+    "inFlightReservation": {
+      "available": true,
+      "withheld": [{ "id": 4951, "blockedBy": 4949 }],
+      "note": "..."
+    }
   }
 
+inFlightReservation names each Story withheld this beat because its file
+footprint overlaps one still IN FLIGHT from an earlier beat, together with the
+blocking id — so an unfilled slot is explained rather than mysterious. It needs
+the in-flight Stories' footprints, which only --probe-live has: under --dag the
+report is { available: false } and selection de-conflicts within the beat only.
+
 Exit codes:
   0 - Success, ready set emitted
   1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
@@ -231,12 +257,124 @@ function inputErrorResult(message, concurrencyCap = null, inFlightValue = 0) {
       inFlight: inFlightValue,
       cycleError: null,
       wedged: null,
+      inFlightReservation: null,
       inputError: message,
     },
     exitCode: 1,
   };
 }
 
+/**
+ * Why a reservation withheld a Story. Machine-readable companion to the
+ * operator-facing `note`, so a consumer never has to parse prose to tell an
+ * earlier-beat blocker from a foreign-lease one (Story #4960).
+ */
+const RESERVATION_REASONS = Object.freeze({
+  EARLIER_BEAT: 'in-flight-earlier-beat',
+  FOREIGN_LEASE: 'foreign-lease',
+});
+
+/**
+ * Describe this beat's in-flight footprint reservation for the envelope
+ * (Story #4950).
+ *
+ * The reservation needs the in-flight Stories' **records** — their footprints
+ * — not just how many there are, so its availability is a property of the
+ * mode rather than of the run:
+ *
+ *   - **Probe mode** hands over the records `live-probe.js` already fetched,
+ *     so `inFlightRecords` is an array (possibly empty) and reservation is
+ *     `available: true`.
+ *   - **Flag mode** (`--dag` + `--in-flight <n>`) supplies a graph and a
+ *     count; no node carries a label, so nothing there can even classify as
+ *     in-flight. There is no footprint to reserve against, and selection is
+ *     unchanged from before #4950. Saying so explicitly is the point: a
+ *     silently-absent guard reads exactly like a guard that found nothing.
+ *
+ * A reservation is held either by a Story **this run** dispatched on an
+ * earlier beat or by one **another operator's lease** holds — `live-probe.js`
+ * folds both into the in-flight set, and they reserve identically but read
+ * very differently to an operator. Reporting a foreign-held peer as "still in
+ * flight from an earlier beat" is simply false: this run never dispatched it
+ * and no later beat of this run will clear it. `foreignHeldIds` splits the two
+ * so each carries its own reason (Story #4960).
+ *
+ * @param {object[]|null|undefined} inFlightRecords
+ * @param {Array<{id: number, blockedBy: number}>} withheld
+ * @param {Iterable<number>} [foreignHeldIds] Ids held by a foreign lease.
+ * @returns {{ available: boolean, withheld: Array<{id: number, blockedBy: number, reason: string}>, note: string|null }}
+ */
+export function buildReservationReport(
+  inFlightRecords,
+  withheld,
+  foreignHeldIds = [],
+) {
+  if (!Array.isArray(inFlightRecords)) {
+    return {
+      available: false,
+      withheld: [],
+      note:
+        'In-flight footprint reservation is UNAVAILABLE this beat: flag mode ' +
+        'supplies a dependency graph and an --in-flight count, never the ' +
+        'in-flight Stories themselves, so there are no footprints to reserve ' +
+        'against. Selection is unchanged (same-beat de-confliction only). ' +
+        'Use --probe-live to reserve in-flight footprints.',
+    };
+  }
+  if (withheld.length === 0) {
+    return { available: true, withheld: [], note: null };
+  }
+  const foreign = new Set(foreignHeldIds);
+  const classified = withheld.map((w) => ({
+    ...w,
+    reason: foreign.has(w.blockedBy)
+      ? RESERVATION_REASONS.FOREIGN_LEASE
+      : RESERVATION_REASONS.EARLIER_BEAT,
+  }));
+  return {
+    available: true,
+    withheld: classified,
+    note: reservationNote(classified),
+  };
+}
+
+/**
+ * Render the operator-facing reservation note, one sentence per reason class
+ * present. Neither class is a failure or a wedge, but they clear by different
+ * events, so each names its own.
+ *
+ * @param {Array<{id: number, blockedBy: number, reason: string}>} withheld
+ * @returns {string}
+ */
+function reservationNote(withheld) {
+  const detail = (entries) =>
+    entries.map((w) => `#${w.id} ← #${w.blockedBy}`).join('; ');
+  const byBeat = withheld.filter(
+    (w) => w.reason === RESERVATION_REASONS.EARLIER_BEAT,
+  );
+  const byLease = withheld.filter(
+    (w) => w.reason === RESERVATION_REASONS.FOREIGN_LEASE,
+  );
+  const parts = [];
+  if (byBeat.length > 0) {
+    parts.push(
+      `${byBeat.length} Story(ies) withheld because their file footprint ` +
+        `overlaps a Story still in flight from an earlier beat — ${detail(byBeat)}. ` +
+        `Each re-admits automatically on a later beat, once the Story ` +
+        `reserving its files leaves the in-flight set.`,
+    );
+  }
+  if (byLease.length > 0) {
+    parts.push(
+      `${byLease.length} Story(ies) withheld because their file footprint ` +
+        `overlaps a Story another operator's lease holds — ${detail(byLease)}. ` +
+        `No beat of THIS run clears that: the peer is the holder's work, and ` +
+        `each re-admits once their lease clears (see foreignHeldReason).`,
+    );
+  }
+  return `${parts.join(' ')} Neither is a wedge and neither is a failure.`;
+}
+
 /**
  * Parse and validate the raw DAG input array.
  *
@@ -308,33 +446,22 @@ export function parseDag(raw) {
 }
 
 /**
- * Parse a comma-separated list of Story IDs into a deduped set of positive
- * integers. Empty / absent input yields an empty set. Rejects any token that
- * is not a positive integer so a typo never silently drops a dependency gate
- * (`--done`) or a held dispatch slot (`--dispatched`).
+ * Parse a comma-separated list of Story IDs — singles or `A-B` dash ranges —
+ * into a deduped set of positive integers. Empty / absent input yields an
+ * empty set. Rejects any token that is not a positive integer or a valid
+ * range, so a typo never silently drops a dependency gate (`--done`) or a
+ * held dispatch slot (`--dispatched`).
+ *
+ * Ranges are accepted here for the same reason `--stories` accepts them: an
+ * operator delivering `4922-4926` writes the dispatched set back the same way.
  *
  * @param {string|undefined} raw
  * @param {string} flag Flag name, for the error message.
  * @returns {{ ids: Set<number>|null, error: string|null }}
  */
 export function parseIdCsv(raw, flag) {
-  if (raw == null || raw === '') {
-    return { ids: new Set(), error: null };
-  }
-  const ids = new Set();
-  for (const token of String(raw).split(',')) {
-    const trimmed = token.trim();
-    if (trimmed === '') continue;
-    const num = Number(trimmed);
-    if (!Number.isInteger(num) || num <= 0) {
-      return {
-        ids: null,
-        error: `${flag} must be a comma-separated list of positive integers, got "${trimmed}"`,
-      };
-    }
-    ids.add(num);
-  }
-  return { ids, error: null };
+  const { ids, error } = expandIdList(raw, { flag });
+  return error ? { ids: null, error } : { ids: new Set(ids), error: null };
 }
 
 /**
@@ -480,7 +607,7 @@ export function resolveCapPrecedence({ cwd, config, override } = {}) {
  * understands (`{ id, dependsOn }`), tags any node already in the done set
  * as `agent::done` so the core's classifier excludes it from the dispatch
  * set **and** counts it as a satisfied dependency, then delegates the
- * scheduling decision to `selectReadySet`. A cyclic operator DAG is a
+ * scheduling decision to `planReadySet`. A cyclic operator DAG is a
  * planning error (the core would silently never schedule the cycle), so we
  * detect it up front via the shared `detectCycle` kernel and short-circuit
  * with a `cycleError` and exit code 2.
@@ -492,6 +619,14 @@ export function resolveCapPrecedence({ cwd, config, override } = {}) {
  *   record explaining which source set the cap.
  * @param {Set<number>} [args.doneIds] Story IDs already completed this run.
  * @param {number} [args.inFlight]     Stories already occupying a slot.
+ * @param {object[]|null} [args.inFlightRecords] Records for the Stories
+ *   already in flight, so the kernel reserves their footprints instead of
+ *   merely counting them (Story #4950). `null` (flag mode) means reservation
+ *   is structurally unavailable — see {@link buildReservationReport}.
+ * @param {number[]} [args.foreignHeldIds] Ids among `inFlightRecords` that a
+ *   **foreign operator's lease** holds rather than this run's own earlier
+ *   beat, so a withholding against one is reported for what it is
+ *   (Story #4960). Flag mode has no lease view and passes none.
  * @returns {{
  *   envelope: {
  *     kind: 'stories-ready-set',
@@ -506,7 +641,14 @@ export function resolveCapPrecedence({ cwd, config, override } = {}) {
  */
 export function buildReadySetEnvelope(
   nodes,
-  { concurrencyCap, capPrecedence = null, doneIds = new Set(), inFlight = 0 },
+  {
+    concurrencyCap,
+    capPrecedence = null,
+    doneIds = new Set(),
+    inFlight = 0,
+    inFlightRecords = null,
+    foreignHeldIds = [],
+  },
 ) {
   const totalStories = nodes.length;
 
@@ -522,6 +664,10 @@ export function buildReadySetEnvelope(
     inFlight,
     cycleError: null,
     wedged: null,
+    // Whether this beat could reserve the in-flight Stories' footprints, and
+    // which Stories a reservation withheld (Story #4950). Never omitted on a
+    // resolved beat: an absent report reads exactly like an empty one.
+    inFlightReservation: buildReservationReport(inFlightRecords, []),
   };
 
   if (totalStories === 0) {
@@ -531,7 +677,7 @@ export function buildReadySetEnvelope(
   // Cycle detection before scheduling — a cycle is a planning error the
   // operator must fix. dropForeign:false preserves the operator-DAG contract
   // (a dependency on an id outside the supplied set is honored, not pruned),
-  // matching the same builder seam selectReadySet uses internally.
+  // matching the same builder seam planReadySet uses internally.
   const adjacency = buildStoryAdjacency(nodes, { dropForeign: false });
   const cycle = detectCycle(adjacency);
   if (cycle) {
@@ -568,12 +714,22 @@ export function buildReadySetEnvelope(
     return rec;
   });
 
-  const ready = selectReadySet({
+  const { selected, withheldByInFlight } = planReadySet({
     stories: records,
     doneIds,
     inFlight,
     globalCap: concurrencyCap,
-  }).map((rec) => rec.id);
+    // Flag mode has no in-flight records at all; `?? []` keeps the kernel's
+    // contract (an array) while `base.inFlightReservation` reports that the
+    // reservation itself was unavailable rather than merely empty.
+    inFlightRecords: inFlightRecords ?? [],
+  });
+  const ready = selected.map((rec) => rec.id);
+  const reservation = buildReservationReport(
+    inFlightRecords,
+    withheldByInFlight,
+    foreignHeldIds,
+  );
 
   // Wedge detection (Story #4540). `ready: []` is normal while work is in
   // flight — the loop is simply waiting. But ready-empty AND nothing in
@@ -589,12 +745,25 @@ export function buildReadySetEnvelope(
   const wedge = detectWedge({ nodes, doneIds, ready, inFlight });
   if (wedge) {
     return {
-      envelope: { ...base, ready, wedged: wedge },
+      envelope: {
+        ...base,
+        ready,
+        wedged: wedge,
+        inFlightReservation: reservation,
+      },
       exitCode: WEDGED_EXIT_CODE,
     };
   }
 
-  return { envelope: { ...base, ready, wedged: null }, exitCode: 0 };
+  return {
+    envelope: {
+      ...base,
+      ready,
+      wedged: null,
+      inFlightReservation: reservation,
+    },
+    exitCode: 0,
+  };
 }
 
 /**
@@ -775,7 +944,7 @@ export async function runProbedStoriesWaveTick({
 
   let ids;
   try {
-    ids = parseIds(stories);
+    ids = parseIds(stories, '--stories');
   } catch (err) {
     return inputErrorResult(err.message);
   }
@@ -819,12 +988,19 @@ export async function runProbedStoriesWaveTick({
     inFlight,
     blockedIds = [],
     foreignHeld = [],
+    inFlightRecords = [],
   } = probed;
   const { envelope, exitCode } = buildReadySetEnvelope(nodes, {
     concurrencyCap,
     capPrecedence,
     doneIds,
     inFlight,
+    // Probe mode is the only mode that HAS the in-flight Stories' records, so
+    // it is the only mode that can reserve their footprints (Story #4950).
+    inFlightRecords,
+    // ...and the only mode that can tell a foreign lease-holder apart from
+    // this run's own earlier-beat dispatch (Story #4960).
+    foreignHeldIds: foreignHeld.map((h) => h.id),
   });
 
   const done = [...doneIds].sort((a, b) => a - b);

package/.agents/scripts/update-coverage-baseline.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// cli-opt-out: top-level main()-driven CLI invoked via npm run coverage:update; no runAsCli() wrapper required.
 /**
  * Refresh `baselines/coverage.json` from the most recent
  * `coverage/coverage-final.json`. Run this when you intentionally add,
@@ -22,6 +21,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import {
   buildScopePredicate,
@@ -31,6 +31,32 @@ import {
 } from './lib/coverage-baseline.js';
 import { Logger } from './lib/Logger.js';
 
+/**
+ * Usage block for `--help`. This CLI *writes* on invocation, so the help
+ * branch must short-circuit before `main` runs rather than inside it —
+ * `runAsCli` answers help first, which makes "a usage probe never mutates a
+ * baseline" structural instead of a check `main` has to remember.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-coverage-baseline.js [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Score → write the coverage baseline from the coverage-final.json already on disk. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+  notes: [
+    'Run `npm run test:coverage` first — this script never runs the suite itself.',
+  ],
+};
+
 const require = createRequire(import.meta.url);
 
 function loadC8Scope(cwd) {
@@ -123,7 +149,11 @@ function main() {
   });
 }
 
-main().catch((err) => {
-  Logger.error(`[Coverage] ❌ Fatal error: ${err?.message ?? err}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'coverage-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[Coverage] ❌ Fatal error: ${err?.message ?? err}`);
+    process.exitCode = 1;
+  },
 });