mandrel 2.59.0 → 2.61.0

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

@@ -2,129 +2,38 @@
 
 /**
  * stories-wave-tick.js — continuous ready-set planner for the standalone
- * `/mandrel-deliver` story-list path.
+ * `/mandrel-deliver` story-list path: a thin adapter over
+ * `lib/wave-runner/ready-set.js#planReadySet` (no wave barrier; a Story is
+ * dispatchable the instant its own dependencies are done).
  *
- * Thin **adapter** over the path-agnostic ready-set scheduling core
- * (`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
- * `lib/wave-runner/ready-set.js` applies everywhere. There is no wave barrier: this no longer batches
- * Stories into fully-draining waves; it selects continuously.
+ * Probe mode (`--stories --probe-live`) derives graph, done set and in-flight
+ * count from live state; flag mode (`--dag` + `--done`/`--in-flight`) takes
+ * them from the caller. They are mutually exclusive: a supplied `--done` under
+ * probe mode would reintroduce hand-maintained state. `--dispatched` is
+ * additive and live-state-filtered, never authoritative.
  *
- * 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 `planReadySet`;
- * this file only gathers input, resolves the cap, and renders the envelope.
+ * The cap comes from `delivery.deliverRunner.concurrencyCap`; `--concurrency`
+ * overrides it, except that worktree isolation off clamps it to 1 (a shared
+ * checkout makes concurrent workers contend for HEAD). `capPrecedence` names
+ * the winning source so no override is silent.
  *
- * **Two modes, one kernel.**
- *
- *   - **Probe mode** (`--stories <csv> --probe-live [--dispatched <csv>]`) is
- *     the canonical `/mandrel-deliver` beat: the graph, the done set, and the in-flight
- *     count are resolved from **live state** via `lib/wave-runner/live-probe.js`.
- *     The caller supplies ids, so there is no accounting to hand-maintain
- *     across beats — the seed-the-first-beat's-`--done` footgun the workflow
- *     used to warn about is structurally impossible rather than merely
- *     documented. `--dispatched` is the one fact live state cannot yet report
- *     ("I spawned this id; its label has not appeared"); it is additive and
- *     live-state-filtered, never authoritative (Story #4601).
- *   - **Flag mode** (`--dag`/`--dag-file` + `--done`/`--in-flight`) keeps the
- *     caller-supplied contract byte-compatible for tests and hand-driven
- *     runs. The two are mutually exclusive: honouring a supplied `--done`
- *     under `--probe-live` would silently reintroduce exactly the
- *     hand-maintained state probe mode retires.
- *
- * Usage:
- *   node .agents/scripts/stories-wave-tick.js --stories 101,102 --probe-live
- *   node .agents/scripts/stories-wave-tick.js --dag '<json>'
- *   node .agents/scripts/stories-wave-tick.js --dag-file <path>
- *   node .agents/scripts/stories-wave-tick.js --dag '<json>' --concurrency 5
- *   node .agents/scripts/stories-wave-tick.js --dag '<json>' --done 101,103 --in-flight 1
- *
- * DAG input format (JSON):
- *   Array of { id: number, dependsOn: number[] } objects where id is a Story
- *   ticket number and dependsOn lists Story IDs that must complete first.
- *
- * Output: one JSON object on stdout with shape:
- *   {
- *     kind: 'stories-ready-set',
- *     ready: number[],          // Story IDs safe to dispatch on this beat
- *     totalStories: number,
- *     concurrencyCap: number,
- *     inFlight: number,
- *     cycleError: string | null,
- *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null,
- *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason, source, paths }], note },
- *     footprintGuard: { mode, withheld: [{ id, blockedBy, scope, source, paths }], advisory, note }
- *   }
- *
- * `inFlightReservation` reports the cross-beat half of the co-dispatch guard
- * (Story #4950 made it reserve; Story #5313 narrowed the footprint back to
- * the declared `changes[]`). 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.
- *
- * `footprintGuard` reports the **beat-local** half, which until Story #5044 was
- * reported nowhere: a same-beat overlap skip was a bare `continue` inside
- * `planReadySet`, so the Story vanished from `ready[]` with no field anywhere
- * naming the collision. Every entry in either report now also carries the
- * colliding `paths` and a `source` tag — `declared-overlap`, the one class
- * left since Story #5313: both Stories' `changes[]` named the path (intended
- * serialization: two Stories really do rewrite the same generated baseline)
- * or one declared a glob. `mode` names the `footprintGuard` config value;
- * under `advisory` the collisions are detected and listed in `advisory[]` but
- * dispatch follows the declared `depends_on` edges alone.
- *
- * 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
- * is done — the run-end signal for `plan-run-epilogue.js`), and `blocked:
- * number[]` + `blockedReason: string|null` (Story #4601 — the `agent::blocked`
- * HITL pause, which ends the loop rather than being polled).
- *
- * The standalone loop calls this once per beat and dispatches the returned
- * `ready` set (already capped at `concurrencyCap − inFlight` by the core).
- * Under `--probe-live` each beat re-reads reality, so the run is complete
- * when `epilogueDue` is true; under flag mode the caller re-supplies `--done`
- * and `--in-flight` itself, and the run is complete when every Story is in
- * `--done` and `ready` is empty.
- *
- * The per-beat concurrency cap is resolved from the same config seam
- * `/mandrel-deliver` uses — `resolveConfig` + `getRunners` reading
- * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
- * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
- * overrides the config-resolved value for that run only, and the envelope's
- * `capPrecedence` names which source won so the override is never silent
- * (Story #4875). This shares one
- * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
- * one scheduling kernel with every `/mandrel-deliver` multi-Story invocation.
- *
- * Exit codes: 0 ok · 1 input error · 2 dependency cycle (`cycleError`) ·
- * 3 wedged (`wedged`) — ready is empty, nothing is in flight, and undone
- * Stories are waiting on blockers that are not done · 4 blocked (`blocked`) —
- * a Story carries `agent::blocked`. A cycle is a self-referential DAG the
- * operator must fix; a wedge is a well-formed DAG whose gates cannot be
- * satisfied from the supplied `--done` set (usually a blocker outside the
- * delivered set that has not landed); a block is the protocol's HITL pause,
- * where a human owes a decision no beat can supply. All three are distinct
- * from the ordinary `ready: []` that means "waiting on in-flight work" — and
- * that distinction is the point: each of them previously presented AS that
- * ordinary empty set, so the loop polled a state that could never improve.
+ * Exit codes (see HELP): 0 ok, 1 input error, 2 cycle, 3 wedged, 4 blocked.
+ * Each non-zero case is distinct from the ordinary `ready: []` that means
+ * "waiting on in-flight work", so the loop never polls a state that cannot
+ * improve.
  */
 
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
-import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
+import {
+  getPaths,
+  getRunners,
+  getWorktreeIsolation,
+  resolveConfig,
+  resolveWorktreeEnabled,
+} from './lib/config-resolver.js';
 import { detectCycle } from './lib/Graph.js';
 import { Logger } from './lib/Logger.js';
 import { AGENT_LABELS } from './lib/label-constants.js';
@@ -143,20 +52,12 @@ import {
   WITHHOLD_SCOPES,
 } from './lib/wave-runner/ready-set.js';
 
-/**
- * Exit code for a wedged run — deliberately distinct from the cycle exit (2)
- * so a caller can tell "your DAG is self-referential" from "your DAG is fine
- * but its gates can never be satisfied from this `--done` set".
- */
+/** Wedged run: a well-formed DAG whose gates cannot be satisfied from `--done`. */
 export const WEDGED_EXIT_CODE = 3;
 
 /**
- * Exit code for a run holding an `agent::blocked` Story — distinct from the
- * cycle (2) and wedge (3) exits because the remediation is categorically
- * different: a cycle is a malformed DAG and a wedge is an unlanded blocker,
- * whereas this is the protocol's one runtime HITL pause. A human must decide
- * something before any beat can help. Probe-mode only: flag-mode nodes carry
- * no labels, so nothing there can classify blocked.
+ * A Story carries `agent::blocked` — the HITL pause no beat can clear.
+ * Probe mode only: flag-mode nodes carry no labels.
  */
 export const BLOCKED_EXIT_CODE = 4;
 
@@ -206,6 +107,13 @@ Options:
                      WINS over the configured value, and the envelope's
                      capPrecedence records that it did — including when the
                      request exceeds the configured cap.
+                     ONE EXCEPTION: when worktree isolation resolves off
+                     (CLAUDE_CODE_REMOTE=true, AP_WORKTREE_ENABLED=false, or
+                     delivery.worktreeIsolation.enabled: false), the cap is
+                     clamped to 1 and the clamp outranks this flag — every
+                     Story would otherwise run in the same checkout and two
+                     workers would contend for HEAD. capPrecedence reports
+                     source "worktree-clamp" with the requested value.
   --done <csv>       Comma-separated Story IDs already completed this run.
                      Their dependents become eligible; they are never
                      re-dispatched. Defaults to empty.
@@ -287,10 +195,6 @@ Exit codes:
 `;
 
 /**
- * Build the exit-1 input-error result. Shared by both modes so a malformed
- * `--concurrency` reports identically whether it arrived alongside `--dag` or
- * `--probe-live`.
- *
  * @param {string} message
  * @param {number|null} [concurrencyCap]
  * @param {number} [inFlightValue]
@@ -315,48 +219,18 @@ function inputErrorResult(message, concurrencyCap = null, inFlightValue = 0) {
   };
 }
 
-/**
- * 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).
- */
+/** Machine-readable reason a reservation withheld a Story. */
 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).
- *
- * Each entry also carries the **colliding paths** and an
- * `OVERLAP_SOURCES` tag (Story #5044). A withhold that names no path is one an
- * operator cannot act on, and `declared-overlap` vs `scraped-overlap` is the
- * difference between "these two Stories both declared this generated baseline,
- * serializing them is the point" and "one Story's body happened to mention a
- * path the other declared" — the same unfilled slot for two very different
- * reasons.
+ * Report the cross-beat footprint reservation. It needs the in-flight
+ * Stories' records, which only probe mode has; flag mode reports
+ * `available: false` explicitly, since an absent guard reads like one that
+ * found nothing. Foreign-lease holders get their own reason because no beat
+ * of this run clears them.
  *
  * @param {object[]|null|undefined} inFlightRecords
  * @param {Array<{id: number, blockedBy: number, source?: string, paths?: string[]}>} withheld
@@ -401,21 +275,9 @@ export function buildReservationReport(
 }
 
 /**
- * Report the **beat-local** half of the footprint guard, plus the guard mode
- * itself (Story #5044).
- *
- * Until now a same-beat overlap skip was an anonymous `continue` inside
- * `planReadySet`: the Story simply did not appear in `ready[]` and no field
- * anywhere said why. That is the same unexplained-unfilled-slot failure the
- * cross-beat `inFlightReservation` report was built to remove, left standing on
- * the other half of the guard — and it is how a plan whose siblings collided
- * only on machine-generated footer text ran fully serial without leaving a
- * trace to notice.
- *
- * `withheld` and `advisory` are disjoint by construction: under `enforce` every
- * detection withheld, under `advisory` none did. Reporting them as separate
- * lists rather than one flagged list means a consumer counting withheld
- * dispatches never has to inspect a boolean to get the count right.
+ * Report the beat-local half of the footprint guard and its mode. `withheld`
+ * and `advisory` are disjoint: under `enforce` every detection withheld,
+ * under `advisory` none did.
  *
  * @param {Array<object>} footprintWithholds The kernel's complete ledger.
  * @param {'enforce'|'advisory'} mode
@@ -443,10 +305,6 @@ export function buildFootprintGuardReport(footprintWithholds, mode) {
 }
 
 /**
- * Render the operator-facing note for the beat-local guard, naming the
- * colliding path(s) for every entry. `null` when the guard neither withheld nor
- * waved anything through.
- *
  * @param {object[]} beat
  * @param {object[]} advisory
  * @param {string} mode
@@ -482,9 +340,7 @@ function footprintGuardNote(beat, advisory, mode) {
 }
 
 /**
- * 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.
+ * One sentence per reason class present; they clear by different events.
  *
  * @param {Array<{id: number, blockedBy: number, reason: string}>} withheld
  * @returns {string}
@@ -519,14 +375,8 @@ function reservationNote(withheld) {
 }
 
 /**
- * Parse and validate the raw DAG input array.
- *
- * Each entry must carry `{ id, dependsOn }`. An optional `files` string
- * array (the canonical footprint shape) is preserved and forwarded to the
- * ready-set core so the file-overlap co-dispatch guard the Epic path uses is
- * genuinely active on the standalone path too: two ready Stories that
- * declare an intersecting footprint are never dispatched onto parallel
- * `story-<id>` branches in the same beat.
+ * Validate the raw DAG array. An optional `files` footprint is forwarded so
+ * the overlap guard is active in flag mode too.
  *
  * @param {unknown} raw Parsed JSON value from --dag or --dag-file.
  * @returns {{ nodes: Array<{id: number, dependsOn: number[], files?: string[]}>, error: string|null }}
@@ -589,14 +439,8 @@ export function parseDag(raw) {
 }
 
 /**
- * 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.
+ * Parse a CSV of ids or `A-B` ranges into a deduped set. Rejects any bad
+ * token so a typo never silently drops a gate or a held slot.
  *
  * @param {string|undefined} raw
  * @param {string} flag Flag name, for the error message.
@@ -608,8 +452,6 @@ export function parseIdCsv(raw, flag) {
 }
 
 /**
- * Parse the `--done` CSV of already-completed Story IDs (flag mode).
- *
  * @param {string|undefined} raw
  * @returns {{ ids: Set<number>|null, error: string|null }}
  */
@@ -618,10 +460,7 @@ export function parseDoneIds(raw) {
 }
 
 /**
- * Parse the raw `--in-flight` value into a non-negative integer. Absent
- * input defaults to 0. Rejects negatives and non-integers.
- *
- * @param {unknown} raw
+ * @param {unknown} raw Absent defaults to 0.
  * @returns {{ value: number|null, error: string|null }}
  */
 export function parseInFlight(raw) {
@@ -639,11 +478,12 @@ export function parseInFlight(raw) {
 }
 
 /**
- * Validate a raw `--concurrency` value into a positive integer.
- *
- * Accepts a number or a numeric string (from the CLI). Rejects anything that
- * is not a positive integer (zero, negative, fractional, non-numeric).
- *
+ * Cap when worktree isolation resolves off — a safety floor, so it outranks
+ * even an explicit `--concurrency`.
+ */
+export const WORKTREE_DISABLED_CONCURRENCY_CAP = 1;
+
+/**
  * @param {unknown} raw
  * @returns {{ value: number|null, error: string|null }}
  */
@@ -662,100 +502,110 @@ export function parseConcurrencyOverride(raw) {
 }
 
 /**
- * Resolve the per-beat concurrency cap.
- *
- * Mirrors the `/mandrel-deliver` multi-Story seam (`helpers/deliver-story.md`): resolve the
- * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
- * then read `delivery.deliverRunner.concurrencyCap` via `getRunners` (default
- * 3). An explicit `override` (the `--concurrency <n>` CLI flag) wins over
- * config for that run only.
- *
  * @param {object} [opts]
- * @param {string} [opts.cwd]       Repo root for config resolution.
- * @param {object} [opts.config]    Pre-resolved config (injected by tests so
- *                                   they never depend on a real `.agentrc`).
- * @param {number} [opts.override]  Validated positive integer from
- *                                   `--concurrency`; wins over config.
- * @returns {number} The resolved positive-integer concurrency cap.
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.config] Pre-resolved config (test injection).
+ * @param {number} [opts.override] Validated `--concurrency`.
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @returns {number}
  */
 export function resolveConcurrencyCap(opts = {}) {
   return resolveCapPrecedence(opts).cap;
 }
 
 /**
- * Resolve the per-beat cap **and the precedence that produced it** (Story
- * #4875).
- *
- * `--concurrency` wins over `delivery.deliverRunner.concurrencyCap`, and that
- * is the intended contract — a flag an operator typed for one run should not be
- * outranked by a checked-in default. What was wrong is that it won *silently*:
- * the envelope reported a single `concurrencyCap` number with no record of
- * which source set it, so a run at 8 when the project configured 3 was
- * indistinguishable from a project configured at 8. A reader could not tell an
- * override from a default, and an override that ran the repo above its own
- * configured ceiling left no trace at all.
- *
- * So the flag still wins, but never quietly: the source is named, the
- * configured value is carried alongside the requested one, and a request that
- * exceeds the configured cap is called out as such. Reporting rather than
- * refusing is deliberate — the configured cap is a project default, not a
- * safety limit, and refusing a deliberate operator escalation would trade a
- * silent override for a silent stall.
+ * Resolve the per-beat cap and the precedence that produced it. The flag wins
+ * over config but never silently: a request above the configured cap is
+ * reported, not refused (the configured cap is a default, not a safety
+ * limit). The worktree clamp outranks both.
  *
  * @param {object} [opts]
- * @param {string} [opts.cwd]      Repo root for config resolution.
+ * @param {string} [opts.cwd]
  * @param {object} [opts.config]   Pre-resolved config (test injection).
- * @param {number} [opts.override] Validated positive integer from
- *                                 `--concurrency`.
+ * @param {number} [opts.override] Validated `--concurrency`.
+ * @param {NodeJS.ProcessEnv} [opts.env]
  * @returns {{
  *   cap: number,
- *   source: 'flag'|'config',
+ *   source: 'flag'|'config'|'worktree-clamp',
  *   configuredCap: number,
  *   requestedCap: number|null,
  *   exceedsConfigured: boolean,
  *   note: string,
  * }}
  */
-export function resolveCapPrecedence({ cwd, config, override } = {}) {
+export function resolveCapPrecedence({ cwd, config, override, env } = {}) {
   const resolved = config ?? resolveConfig({ cwd });
   const { deliverRunner } = getRunners(resolved);
   const configuredCap = deliverRunner.concurrencyCap;
-  if (override == null) {
-    return {
-      cap: configuredCap,
-      source: 'config',
-      configuredCap,
-      requestedCap: null,
-      exceedsConfigured: false,
-      note: `cap ${configuredCap} from delivery.deliverRunner.concurrencyCap (no --concurrency given)`,
-    };
-  }
-  const exceedsConfigured = override > configuredCap;
+  const requested =
+    override == null
+      ? {
+          cap: configuredCap,
+          source: 'config',
+          configuredCap,
+          requestedCap: null,
+          exceedsConfigured: false,
+          note: `cap ${configuredCap} from delivery.deliverRunner.concurrencyCap (no --concurrency given)`,
+        }
+      : {
+          cap: override,
+          source: 'flag',
+          configuredCap,
+          requestedCap: override,
+          exceedsConfigured: override > configuredCap,
+          note:
+            override > configuredCap
+              ? `cap ${override} from --concurrency, which OVERRIDES and EXCEEDS the configured delivery.deliverRunner.concurrencyCap ${configuredCap} — this run is deliberately above the project default`
+              : `cap ${override} from --concurrency, which overrides the configured delivery.deliverRunner.concurrencyCap ${configuredCap}`,
+        };
+
+  return resolveWorktreeClamp({ requested, config: resolved, env });
+}
+
+/**
+ * Apply the worktree-isolation floor. Keyed off `resolveWorktreeEnabled` so
+ * every route to isolation-off is covered. The config is normalised through
+ * `getWorktreeIsolation` first: a raw read of an omitted block is `false` and
+ * would clamp as if isolation had been disabled. The clamp record is emitted
+ * even when the requested cap was already 1, so sequentiality is attributable.
+ *
+ * @param {object} args
+ * @param {{cap: number, source: string, configuredCap: number, requestedCap: number|null, exceedsConfigured: boolean, note: string}} args.requested
+ * @param {object|null} [args.config]
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @returns {typeof args.requested}
+ */
+export function resolveWorktreeClamp({ requested, config, env } = {}) {
+  const worktreeEnabled = resolveWorktreeEnabled(
+    {
+      config: { delivery: { worktreeIsolation: getWorktreeIsolation(config) } },
+    },
+    env ?? process.env,
+  );
+  if (worktreeEnabled) return requested;
+
+  const from =
+    requested.source === 'flag'
+      ? '--concurrency'
+      : 'delivery.deliverRunner.concurrencyCap';
   return {
-    cap: override,
-    source: 'flag',
-    configuredCap,
-    requestedCap: override,
-    exceedsConfigured,
-    note: exceedsConfigured
-      ? `cap ${override} from --concurrency, which OVERRIDES and EXCEEDS the configured delivery.deliverRunner.concurrencyCap ${configuredCap} — this run is deliberately above the project default`
-      : `cap ${override} from --concurrency, which overrides the configured delivery.deliverRunner.concurrencyCap ${configuredCap}`,
+    cap: WORKTREE_DISABLED_CONCURRENCY_CAP,
+    source: 'worktree-clamp',
+    configuredCap: requested.configuredCap,
+    requestedCap: requested.cap,
+    // The escalation never took effect.
+    exceedsConfigured: false,
+    note: `cap clamped to ${WORKTREE_DISABLED_CONCURRENCY_CAP} because worktree isolation resolved OFF — requested ${requested.cap} from ${from}. Concurrent dispatch shares one checkout without per-Story worktrees, so two workers would contend for HEAD; this floor outranks an explicit --concurrency.`,
   };
 }
 
 /**
- * Resolve the two footprint-guard inputs from the same config seam the cap
- * comes from (Story #5044).
- *
- * `tempRoot` is threaded rather than hardcoded because the evidence scrape must
- * exclude the project's *configured* scratch root: a consumer that sets
- * `project.paths.tempRoot: '.scratch'` would otherwise have every sibling
- * citing a report under it collide, which is the exact defect this Story
- * removes for the default `temp/`.
+ * `tempRoot` is the configured one, not a hardcoded `temp/`, so the overlap
+ * guard excludes the project's actual scratch root.
  *
  * @param {object} [opts]
- * @param {string} [opts.cwd]     Repo root for config resolution.
- * @param {object} [opts.config]  Pre-resolved config (test injection).
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.config]
  * @returns {{ footprintGuard: 'enforce'|'advisory', tempRoot: string }}
  */
 export function resolveFootprintGuardSettings({ cwd, config } = {}) {
@@ -767,32 +617,18 @@ export function resolveFootprintGuardSettings({ cwd, config } = {}) {
 }
 
 /**
- * Build the per-beat ready-set envelope from a validated DAG.
- *
- * Maps each operator-DAG node onto a Story record the ready-set core
- * 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 `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.
+ * Build the per-beat envelope. A cyclic DAG is rejected up front (exit 2)
+ * because the core would silently never schedule it.
  *
  * @param {Array<{id: number, dependsOn: number[]}>} nodes
  * @param {object} args
- * @param {number} args.concurrencyCap Resolved per-beat concurrency cap.
- * @param {object|null} [args.capPrecedence] The {@link resolveCapPrecedence}
- *   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.
+ * @param {number} args.concurrencyCap
+ * @param {object|null} [args.capPrecedence]
+ * @param {Set<number>} [args.doneIds]
+ * @param {number} [args.inFlight]
+ * @param {object[]|null} [args.inFlightRecords] `null` (flag mode) means
+ *   reservation is unavailable, not empty.
+ * @param {number[]} [args.foreignHeldIds] Ids held by a foreign lease.
  * @returns {{
  *   envelope: {
  *     kind: 'stories-ready-set',
@@ -825,21 +661,13 @@ export function buildReadySetEnvelope(
     ready: [],
     totalStories,
     concurrencyCap,
-    // Which source set `concurrencyCap`, and whether it outranks the project's
-    // configured value (Story #4875). Never omitted on a resolved beat: a
-    // missing precedence record is what made a silent override possible.
+    // The reports below are never omitted: an absent report reads like an
+    // empty one.
     capPrecedence,
     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, []),
-    // The beat-local half of the same guard, plus the mode it ran in (Story
-    // #5044). Also never omitted: a same-beat skip used to be reported nowhere
-    // at all, which is precisely how an evidence-widening artifact could
-    // serialize a whole run unnoticed.
     footprintGuard: buildFootprintGuardReport([], footprintGuard),
   };
 
@@ -847,10 +675,7 @@ export function buildReadySetEnvelope(
     return { envelope: base, exitCode: 0 };
   }
 
-  // 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 planReadySet uses internally.
+  // dropForeign:false: a dependency outside the supplied set is honored.
   const adjacency = buildStoryAdjacency(nodes, { dropForeign: false });
   const cycle = detectCycle(adjacency);
   if (cycle) {
@@ -863,26 +688,16 @@ export function buildReadySetEnvelope(
     };
   }
 
-  // Map DAG nodes → Story records. Tag done nodes as agent::done so the
-  // core's classifier (a) excludes them from the dispatch set and (b) folds
-  // them into the satisfied-dependency set, making their dependents eligible.
-  // Forward any declared file footprint so the core's overlap guard fires.
+  // Done nodes are tagged agent::done so the core both excludes them and
+  // counts them as satisfied dependencies. Probe-mode live labels are kept so
+  // an in-flight Story is never re-dispatched onto a second branch.
   const records = nodes.map((node) => {
     const rec = {
       id: node.id,
       dependsOn: node.dependsOn,
-      // A node's own live labels (probe mode) are preserved so the core's
-      // classifier withholds an in-flight `agent::executing` / `agent::closing`
-      // Story rather than re-dispatching it onto a second branch. Flag-mode
-      // nodes carry none — `parseDag` accepts no labels — so this is inert
-      // there and the legacy contract is unchanged.
       labels: doneIds.has(node.id) ? [AGENT_LABELS.DONE] : (node.labels ?? []),
     };
     if (node.files !== undefined) rec.files = node.files;
-    // Probe-mode nodes carry the Story body so the overlap guard can widen a
-    // declared footprint from the paths the Story's own text names (Story
-    // #4875). Flag-mode nodes carry none — `parseDag` accepts no body — so
-    // this is inert there and the legacy contract is unchanged.
     if (typeof node.body === 'string') rec.body = node.body;
     return rec;
   });
@@ -892,17 +707,11 @@ export function buildReadySetEnvelope(
     doneIds,
     inFlight,
     globalCap: concurrencyCap,
-    // 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 ?? [],
     footprintGuard,
     tempRoot,
   });
   const ready = selected.map((rec) => rec.id);
-  // The cross-beat report reads the enforced in-flight slice of the kernel's
-  // ledger rather than the legacy `withheldByInFlight` list, so it carries the
-  // colliding paths and the overlap source through to the operator.
   const reservation = buildReservationReport(
     inFlightRecords,
     footprintWithholds.filter(
@@ -912,17 +721,6 @@ export function buildReadySetEnvelope(
   );
   const guardReport = buildFootprintGuardReport(footprintWithholds, guardMode);
 
-  // Wedge detection (Story #4540). `ready: []` is normal while work is in
-  // flight — the loop is simply waiting. But ready-empty AND nothing in
-  // flight AND undone Stories remaining means no beat can ever make
-  // progress: the run is stuck, and the previous behaviour was to return
-  // exit 0 with an empty ready set forever, indistinguishable from
-  // "waiting". Name the stuck ids and their unmet blockers.
-  //
-  // Distinct from `cycleError`/exit 2: a cycle is a self-referential DAG,
-  // whereas this is a DAG whose gates are real but unsatisfiable from the
-  // supplied `done` set (typically a blocker outside the delivered set that
-  // has not landed).
   const wedge = detectWedge({ nodes, doneIds, ready, inFlight });
   if (wedge) {
     return {
@@ -968,9 +766,7 @@ export function detectWedge({ nodes, doneIds, ready, inFlight }) {
     }))
     .filter((s) => s.unmetBlockers.length > 0);
 
-  // Undone work with no unmet blockers would have been dispatched; if that
-  // is the whole set, the cap or in-flight accounting explains the empty
-  // ready set rather than a wedge.
+  // Undone work with no unmet blockers is capacity-limited, not wedged.
   if (stories.length === 0) return null;
 
   const detail = stories
@@ -986,20 +782,17 @@ export function detectWedge({ nodes, doneIds, ready, inFlight }) {
 }
 
 /**
- * Core logic: parse DAG input, resolve the concurrency cap, validate, and
- * compute the per-beat ready set via the shared scheduling core.
- *
- * Exported for unit tests; the CLI `main` function is a thin wrapper. Tests
- * inject `config` so they never depend on a real `.agentrc`.
+ * Flag-mode beat.
  *
  * @param {object} args
- * @param {string} [args.dagJson]      Raw JSON string from --dag.
- * @param {string} [args.dagFile]      Path to a JSON file from --dag-file.
- * @param {string|number} [args.concurrency] Raw --concurrency override.
- * @param {string} [args.done]         Raw --done CSV of completed Story IDs.
- * @param {string|number} [args.inFlight] Raw --in-flight count.
- * @param {string} [args.cwd]          Repo root for config resolution.
- * @param {object} [args.config]       Pre-resolved config (test injection).
+ * @param {string} [args.dagJson]
+ * @param {string} [args.dagFile]
+ * @param {string|number} [args.concurrency]
+ * @param {string} [args.done]
+ * @param {string|number} [args.inFlight]
+ * @param {string} [args.cwd]
+ * @param {object} [args.config] Pre-resolved config (test injection).
+ * @param {NodeJS.ProcessEnv} [args.env]
  * @returns {{
  *   envelope: {kind: string, ready: number[], totalStories: number, concurrencyCap: number, inFlight: number, cycleError: string|null},
  *   exitCode: number
@@ -1013,9 +806,8 @@ export function runStoriesWaveTick({
   inFlight,
   cwd,
   config,
+  env,
 } = {}) {
-  // Validate the --concurrency override before resolving config so an invalid
-  // value fails fast with exit code 1 regardless of DAG validity.
   const { value: override, error: concurrencyError } =
     parseConcurrencyOverride(concurrency);
   if (concurrencyError) {
@@ -1033,7 +825,7 @@ export function runStoriesWaveTick({
     return inputErrorResult(doneError, null, inFlightValue);
   }
 
-  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override, env });
   const concurrencyCap = capPrecedence.cap;
 
   let rawJson;
@@ -1084,32 +876,22 @@ export function runStoriesWaveTick({
 }
 
 /**
- * Probe mode: resolve the graph and the run's progress from **live state**,
- * then run the same scheduling kernel the flag mode does.
- *
- * This is the flag-free beat. The caller supplies only the Story ids it was
- * asked to deliver; `done` and `inFlight` are probed rather than transcribed,
- * which is what makes the `/mandrel-deliver` loop's old seed-the-first-beat footgun
- * structurally impossible instead of merely documented.
- *
- * The envelope is the flag mode's, plus three probe-only fields the caller can
- * no longer compute for itself:
- *   - `done` — the resolved done set (in-set ∪ satisfied foreign blockers).
- *   - `epilogueDue` — true exactly when every listed Story is done, which is
- *     the run-end signal for `plan-run-epilogue.js`.
- *   - `blocked` — ids carrying `agent::blocked` (Story #4601). Non-empty means
- *     the loop must END, not poll: see `BLOCKED_EXIT_CODE`.
+ * Probe-mode beat: graph and progress from live state. Adds `done`,
+ * `epilogueDue` (every listed Story done — the run-end signal), `blocked`
+ * (non-empty ends the loop) and `stalledDispatch` (`--dispatched` ids still
+ * `agent::ready`, which only the caller can tell from a dead spawn).
  *
  * @param {object} args
- * @param {string} args.stories        Raw `--stories` CSV of Story ids.
- * @param {string|number} [args.concurrency] Raw `--concurrency` override.
- * @param {string} [args.dispatched]   Raw `--dispatched` CSV of ids the host
- *   has spawned but may not yet have observed labelled.
- * @param {string} [args.cwd]          Repo root for config resolution.
- * @param {object} [args.config]       Pre-resolved config (test injection).
- * @param {Function} [args.probe]      Probe seam (test injection).
- * @param {Function} [args.context]    Provider-context seam (test injection).
- * @returns {Promise<{ envelope: object, exitCode: number }>}
+ * @param {string} args.stories
+ * @param {string|number} [args.concurrency]
+ * @param {string} [args.dispatched]
+ * @param {string} [args.cwd]
+ * @param {object} [args.config]
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @param {Function} [args.probe]   Test seam.
+ * @param {Function} [args.context] Test seam.
+ * @returns {Promise<{ envelope: object, exitCode: number, records: object[] }>}
+ *   `records` are the probed nodes, kept off stdout.
  */
 export async function runProbedStoriesWaveTick({
   stories,
@@ -1117,6 +899,7 @@ export async function runProbedStoriesWaveTick({
   dispatched,
   cwd,
   config,
+  env,
   probe = probeLiveState,
   context = createProbeContext,
 } = {}) {
@@ -1141,7 +924,7 @@ export async function runProbedStoriesWaveTick({
     return inputErrorResult(dispatchedError);
   }
 
-  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override, env });
   const concurrencyCap = capPrecedence.cap;
 
   let probed;
@@ -1157,9 +940,7 @@ export async function runProbedStoriesWaveTick({
       warn: (m) => Logger.warn(m),
     });
   } catch (err) {
-    // A failed probe must never degrade into "nothing is ready" — that is
-    // indistinguishable from a healthy waiting beat and would silently stall
-    // the run. Fail loud with the input-error contract instead.
+    // Never degrade into "nothing is ready": that reads as a healthy wait.
     return inputErrorResult(
       `Could not probe live state: ${err?.message ?? err}`,
       concurrencyCap,
@@ -1171,6 +952,7 @@ export async function runProbedStoriesWaveTick({
     doneIds,
     inFlight,
     blockedIds = [],
+    stalledDispatch = [],
     foreignHeld = [],
     inFlightRecords = [],
   } = probed;
@@ -1179,11 +961,7 @@ export async function runProbedStoriesWaveTick({
     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),
     ...resolveFootprintGuardSettings({ cwd, config }),
   });
@@ -1198,16 +976,13 @@ export async function runProbedStoriesWaveTick({
       epilogueDue,
       blocked: blockedIds,
       blockedReason: blockedReasonFor(blockedIds),
-      // Stories another operator's lease holds — withheld from dispatch this
-      // beat (folded into in-flight) and surfaced so the run can report
-      // "#<id> held by @<holder>" instead of dispatching into an init refusal.
+      stalledDispatch,
       foreignHeld,
       foreignHeldReason: foreignHeldReasonFor(foreignHeld),
     },
-    // A blocked Story outranks the scheduler's own verdict — including a
-    // wedge, whose named blockers are moot while a human owes a decision.
-    // A cycle (2) does not yield: a self-referential DAG is a planning error
-    // that must be fixed before any of this run's state means anything.
+    records: nodes,
+    // Blocked outranks a wedge (its blockers are moot while a human owes a
+    // decision) but not a cycle, which invalidates the run's state.
     exitCode:
       blockedIds.length > 0 && !envelope.cycleError
         ? BLOCKED_EXIT_CODE
@@ -1216,9 +991,6 @@ export async function runProbedStoriesWaveTick({
 }
 
 /**
- * Render the operator-facing reason for a blocked run, or `null` when nothing
- * is blocked.
- *
  * @param {number[]} blockedIds
  * @returns {string|null}
  */
@@ -1235,14 +1007,6 @@ function blockedReasonFor(blockedIds) {
 }
 
 /**
- * Render the operator-facing note for Stories held by another operator's
- * lease, or `null` when none are held.
- *
- * These are not errors and not a wedge: the holder's run is progressing
- * normally, this run simply must not join it on the same branch. The Story
- * stays withheld and re-probes each beat, so it dispatches on its own the
- * moment the holder's lease clears (their run lands or is stolen).
- *
  * @param {Array<{id: number, holder: string}>} foreignHeld
  * @returns {string|null}
  */