mandrel 2.1.0 → 2.2.0

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

@@ -5,12 +5,10 @@
  * `/deliver` story-list path.
  *
  * Thin **adapter** over the path-agnostic ready-set scheduling core
- * (`lib/wave-runner/ready-set.js#selectReadySet`). It consumes an
- * operator-supplied dependency DAG of standalone Story IDs plus the live
- * progress of the run (which Stories are done, how many are in flight) and
- * 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#selectReadySet`). 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.
  *
@@ -18,9 +16,27 @@
  * 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`;
- * this file only parses input, resolves the cap, and renders the envelope.
+ * this file only gathers input, resolves the cap, and renders the envelope.
+ *
+ * **Two modes, one kernel.**
+ *
+ *   - **Probe mode** (`--stories <csv> --probe-live [--dispatched <csv>]`) is
+ *     the canonical `/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
@@ -41,11 +57,19 @@
  *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null
  *   }
  *
- * The standalone loop calls this once per beat: after each Story closes it
- * re-runs with the closed Story added to `--done` and the live in-flight
- * count in `--in-flight`, dispatching the returned `ready` set (already
- * capped at `concurrencyCap − inFlight` by the core). The run is complete
- * when every Story is in `--done` and `ready` is empty.
+ * 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
  * `/deliver` uses — `resolveConfig` + `getRunners` reading
@@ -57,11 +81,15 @@
  *
  * 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. 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). Both are distinct
- * from the ordinary `ready: []` that means "waiting on in-flight work".
+ * 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.
  */
 
 import { readFileSync } from 'node:fs';
@@ -72,7 +100,13 @@ import { getRunners, resolveConfig } 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';
+import { parseIds } from './lib/orchestration/resolve-stories.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
+import {
+  createProbeContext,
+  probeLiveState,
+  validateProbeFlags,
+} from './lib/wave-runner/live-probe.js';
 import { selectReadySet } from './lib/wave-runner/ready-set.js';
 
 /**
@@ -82,13 +116,32 @@ import { selectReadySet } from './lib/wave-runner/ready-set.js';
  */
 export const WEDGED_EXIT_CODE = 3;
 
-const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>] [--done <csv>] [--in-flight <n>]
+/**
+ * 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.
+ */
+export const BLOCKED_EXIT_CODE = 4;
+
+const HELP = `Usage:
+  node .agents/scripts/stories-wave-tick.js --stories <csv> --probe-live [--dispatched <csv>] [--concurrency <n>]
+  node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>] [--done <csv>] [--in-flight <n>]
 
-Continuous ready-set planner for standalone Story delivery. Consumes a
-dependency graph of Story IDs plus the live run progress and 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.
+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.
+
+Two modes:
+  --probe-live  Resolve the graph and derive done / in-flight from LIVE state
+                (the canonical /deliver beat). Nothing is hand-maintained
+                across beats. Mutually exclusive with --dag/--dag-file/--done/
+                --in-flight. Adds "done" and "epilogueDue" to the envelope.
+  --dag         Legacy flag mode: the caller supplies the graph and the run
+                progress. Kept for tests and hand-driven runs.
 
 Input DAG format (JSON array):
   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
@@ -98,6 +151,19 @@ 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.
+  --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
+                     live state, so it closes the init window: a Story reads
+                     agent::ready for the 3-6 minutes single-story-init.js
+                     takes to flip agent::executing, and without this it is
+                     dispatched a second time onto the same branch. Append
+                     every id you dispatch and never remove one — a stale id
+                     that has since gone done is dropped automatically, so
+                     over-supplying is free and forgetting is the only error.
   --concurrency <n>  Override the per-beat concurrency cap for this run only.
                      Must be a positive integer. When omitted, the cap is
                      resolved from delivery.deliverRunner.concurrencyCap in
@@ -127,8 +193,36 @@ Exit codes:
   3 - Wedged: ready is empty, nothing is in flight, and undone Stories are
       waiting on blockers that are not done. Distinct from an ordinary empty
       ready set (which means "waiting on in-flight work") and from a cycle.
+  4 - Blocked: a Story carries agent::blocked (probe mode only). The HITL
+      pause — no beat can clear it. STOP the loop; do not poll.
 `;
 
+/**
+ * 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]
+ * @returns {{ envelope: object, exitCode: 1 }}
+ */
+function inputErrorResult(message, concurrencyCap = null, inFlightValue = 0) {
+  return {
+    envelope: {
+      kind: 'stories-ready-set',
+      ready: [],
+      totalStories: 0,
+      concurrencyCap,
+      inFlight: inFlightValue,
+      cycleError: null,
+      wedged: null,
+      inputError: message,
+    },
+    exitCode: 1,
+  };
+}
+
 /**
  * Parse and validate the raw DAG input array.
  *
@@ -200,15 +294,16 @@ export function parseDag(raw) {
 }
 
 /**
- * Parse a comma-separated `--done` 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.
+ * 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`).
  *
  * @param {string|undefined} raw
+ * @param {string} flag Flag name, for the error message.
  * @returns {{ ids: Set<number>|null, error: string|null }}
  */
-export function parseDoneIds(raw) {
+export function parseIdCsv(raw, flag) {
   if (raw == null || raw === '') {
     return { ids: new Set(), error: null };
   }
@@ -220,7 +315,7 @@ export function parseDoneIds(raw) {
     if (!Number.isInteger(num) || num <= 0) {
       return {
         ids: null,
-        error: `--done must be a comma-separated list of positive integers, got "${trimmed}"`,
+        error: `${flag} must be a comma-separated list of positive integers, got "${trimmed}"`,
       };
     }
     ids.add(num);
@@ -228,6 +323,16 @@ export function parseDoneIds(raw) {
   return { ids, error: null };
 }
 
+/**
+ * Parse the `--done` CSV of already-completed Story IDs (flag mode).
+ *
+ * @param {string|undefined} raw
+ * @returns {{ ids: Set<number>|null, error: string|null }}
+ */
+export function parseDoneIds(raw) {
+  return parseIdCsv(raw, '--done');
+}
+
 /**
  * Parse the raw `--in-flight` value into a non-negative integer. Absent
  * input defaults to 0. Rejects negatives and non-integers.
@@ -371,7 +476,12 @@ export function buildReadySetEnvelope(
     const rec = {
       id: node.id,
       dependsOn: node.dependsOn,
-      labels: doneIds.has(node.id) ? [AGENT_LABELS.DONE] : [],
+      // 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;
     return rec;
@@ -471,37 +581,23 @@ export function runStoriesWaveTick({
   cwd,
   config,
 } = {}) {
-  const inputError = (message, concurrencyCap = null, inFlightValue = 0) => ({
-    envelope: {
-      kind: 'stories-ready-set',
-      ready: [],
-      totalStories: 0,
-      concurrencyCap,
-      inFlight: inFlightValue,
-      cycleError: null,
-      wedged: null,
-      inputError: message,
-    },
-    exitCode: 1,
-  });
-
   // 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) {
-    return inputError(concurrencyError);
+    return inputErrorResult(concurrencyError);
   }
 
   const { value: inFlightValue, error: inFlightError } =
     parseInFlight(inFlight);
   if (inFlightError) {
-    return inputError(inFlightError);
+    return inputErrorResult(inFlightError);
   }
 
   const { ids: doneIds, error: doneError } = parseDoneIds(done);
   if (doneError) {
-    return inputError(doneError, null, inFlightValue);
+    return inputErrorResult(doneError, null, inFlightValue);
   }
 
   const concurrencyCap = resolveConcurrencyCap({ cwd, config, override });
@@ -512,7 +608,7 @@ export function runStoriesWaveTick({
     try {
       rawJson = readFileSync(dagFile, 'utf8');
     } catch (err) {
-      return inputError(
+      return inputErrorResult(
         `Could not read DAG file "${dagFile}": ${err.message}`,
         concurrencyCap,
         inFlightValue,
@@ -521,7 +617,7 @@ export function runStoriesWaveTick({
   } else if (dagJson) {
     rawJson = dagJson;
   } else {
-    return inputError(
+    return inputErrorResult(
       'Either --dag <json> or --dag-file <path> is required',
       concurrencyCap,
       inFlightValue,
@@ -532,7 +628,7 @@ export function runStoriesWaveTick({
   try {
     parsed = JSON.parse(rawJson);
   } catch (err) {
-    return inputError(
+    return inputErrorResult(
       `Invalid JSON: ${err.message}`,
       concurrencyCap,
       inFlightValue,
@@ -541,7 +637,7 @@ export function runStoriesWaveTick({
 
   const { nodes, error: parseError } = parseDag(parsed);
   if (parseError) {
-    return inputError(parseError, concurrencyCap, inFlightValue);
+    return inputErrorResult(parseError, concurrencyCap, inFlightValue);
   }
 
   return buildReadySetEnvelope(nodes, {
@@ -551,12 +647,144 @@ 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 `/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`.
+ *
+ * @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 }>}
+ */
+export async function runProbedStoriesWaveTick({
+  stories,
+  concurrency,
+  dispatched,
+  cwd,
+  config,
+  probe = probeLiveState,
+  context = createProbeContext,
+} = {}) {
+  const { value: override, error: concurrencyError } =
+    parseConcurrencyOverride(concurrency);
+  if (concurrencyError) {
+    return inputErrorResult(concurrencyError);
+  }
+
+  let ids;
+  try {
+    ids = parseIds(stories);
+  } catch (err) {
+    return inputErrorResult(err.message);
+  }
+
+  const { ids: dispatchedIds, error: dispatchedError } = parseIdCsv(
+    dispatched,
+    '--dispatched',
+  );
+  if (dispatchedError) {
+    return inputErrorResult(dispatchedError);
+  }
+
+  const concurrencyCap = resolveConcurrencyCap({ cwd, config, override });
+
+  let probed;
+  try {
+    const { provider, owner, repo } = context();
+    probed = await probe({
+      ids,
+      provider,
+      owner,
+      repo,
+      dispatched: [...dispatchedIds],
+      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.
+    return inputErrorResult(
+      `Could not probe live state: ${err?.message ?? err}`,
+      concurrencyCap,
+    );
+  }
+
+  const { nodes, doneIds, inFlight, blockedIds = [] } = probed;
+  const { envelope, exitCode } = buildReadySetEnvelope(nodes, {
+    concurrencyCap,
+    doneIds,
+    inFlight,
+  });
+
+  const done = [...doneIds].sort((a, b) => a - b);
+  const epilogueDue =
+    nodes.length > 0 && nodes.every((node) => doneIds.has(node.id));
+  return {
+    envelope: {
+      ...envelope,
+      done,
+      epilogueDue,
+      blocked: blockedIds,
+      blockedReason: blockedReasonFor(blockedIds),
+    },
+    // 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.
+    exitCode:
+      blockedIds.length > 0 && !envelope.cycleError
+        ? BLOCKED_EXIT_CODE
+        : exitCode,
+  };
+}
+
+/**
+ * Render the operator-facing reason for a blocked run, or `null` when nothing
+ * is blocked.
+ *
+ * @param {number[]} blockedIds
+ * @returns {string|null}
+ */
+function blockedReasonFor(blockedIds) {
+  if (blockedIds.length === 0) return null;
+  const list = blockedIds.map((id) => `#${id}`).join(', ');
+  return (
+    `${blockedIds.length} Story(ies) carry agent::blocked — ${list}. ` +
+    `agent::blocked is the protocol's HITL pause: no beat can clear it and ` +
+    `the loop must stop rather than poll. Read each Story's friction comment ` +
+    `(gh issue view <id> --comments), resolve the blocker, then flip it back ` +
+    `with: node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready`
+  );
+}
+
 async function main(argv) {
   const { values } = parseArgs({
     args: argv,
     options: {
       dag: { type: 'string' },
       'dag-file': { type: 'string' },
+      stories: { type: 'string' },
+      'probe-live': { type: 'boolean' },
+      dispatched: { type: 'string' },
       concurrency: { type: 'string' },
       done: { type: 'string' },
       'in-flight': { type: 'string' },
@@ -571,19 +799,43 @@ async function main(argv) {
     return;
   }
 
-  const { envelope, exitCode } = runStoriesWaveTick({
-    dagJson: values.dag,
+  const flagError = validateProbeFlags({
+    probeLive: values['probe-live'],
+    stories: values.stories,
+    dag: values.dag,
     dagFile: values['dag-file'],
-    concurrency: values.concurrency,
     done: values.done,
     inFlight: values['in-flight'],
+    dispatched: values.dispatched,
   });
 
+  const { envelope, exitCode } = flagError
+    ? inputErrorResult(flagError)
+    : values['probe-live']
+      ? await runProbedStoriesWaveTick({
+          stories: values.stories,
+          concurrency: values.concurrency,
+          dispatched: values.dispatched,
+        })
+      : runStoriesWaveTick({
+          dagJson: values.dag,
+          dagFile: values['dag-file'],
+          concurrency: values.concurrency,
+          done: values.done,
+          inFlight: values['in-flight'],
+        });
+
   process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
 
   if (exitCode !== 0) {
     Logger.error(
-      `stories-wave-tick: ${envelope.inputError ?? envelope.cycleError ?? 'error'}`,
+      `stories-wave-tick: ${
+        envelope.inputError ??
+        envelope.cycleError ??
+        envelope.blockedReason ??
+        envelope.wedged?.reason ??
+        'error'
+      }`,
     );
     process.exitCode = exitCode;
   }

package/.agents/workflows/deliver.md

@@ -67,9 +67,12 @@ to respect.
    node .agents/scripts/resolve-stories.js --ids <id,id,...>
    ```
 
-   Capture `stories[]`, `dag[]`, and `done[]` from the envelope. Do **not**
-   rebuild the graph by hand — it is discovered from live state, including
-   edges a body does not spell out and blockers outside the delivered set.
+   This validates the set and shows the operator what will run: read
+   `stories[]`, `dag[]`, and `done[]` to present the order in step 2. You do
+   **not** thread them into step 3 — the tick re-resolves the graph itself
+   from the same machinery, every beat. Do **not** rebuild the graph by hand;
+   it is discovered from live state, including edges a body does not spell
+   out and blockers outside the delivered set.
 
    Resolution hard-errors (exit 1) on a named id that is not a Story, still
    carries an `Epic: #N` footer, or whose native dependency edges cannot be
@@ -78,23 +81,41 @@ to respect.
 
 2. **Confirm (N>1).** Present the order and wait unless `--yes`.
 
-3. **Sequence.** Loop until every Story is done:
+3. **Sequence.** Loop until the tick reports `epilogueDue: true`:
 
    ```bash
    node .agents/scripts/stories-wave-tick.js \
-     --dag '<dag from step 1>' --done <csv> --in-flight <n> --concurrency <n>
+     --stories <id,id,...> --probe-live --concurrency <n> \
+     --dispatched <every id you have dispatched so far>
    ```
 
-   **Seed the first beat's `--done` from the resolver's `done[]`** — not from
-   an empty string. That array carries the blockers that have already landed,
-   including foreign ones outside the delivered set. Seeding it empty
-   discards exactly the cross-run resolution this step exists for, and the
-   run wedges on a blocker that finished weeks ago. On later beats, `--done`
-   is `done[]` plus every Story that has since closed.
+   Each beat re-probes live state: it re-resolves the graph, classifies done
+   (`agent::done` or a closed issue — including foreign blockers that landed
+   in another run), and derives in-flight from live `agent::executing` /
+   `agent::closing` labels. You never compute `done` or `in-flight` — that
+   accounting is read from reality every beat (Story #4594).
+
+   **`--dispatched` is the one thing you must tell it (Story #4601).** List
+   every Story id you have spawned this run. Live state cannot report a Story
+   you dispatched ninety seconds ago: `single-story-init.js` flips
+   `agent::executing` at step 6 of 6, *after* a 3–6 minute worktree install,
+   so until then the Story still reads `agent::ready` and the next beat hands
+   it back — a second sub-agent then joins the first on the same branch and
+   worktree, interleaving commits.
+
+   The rule is **append-only: add each id as you dispatch it and never remove
+   one.** The flag is additive, not authoritative — the probe unions it into
+   the label-derived set and then filters it against live state, so an id that
+   has since gone `agent::done` is dropped for you. Re-listing an id costs
+   nothing and cannot double-count a slot; *omitting* one is the only way to
+   get this wrong. This is why `--dispatched` is not the `--done` bookkeeping
+   #4594 retired, and why `--in-flight` remains rejected under `--probe-live`.
 
    Branch on the exit code:
-   - **0** — dispatch each `ready` id. An empty `ready` with work in flight
-     means "waiting"; keep looping.
+   - **0** — dispatch each `ready` id (the set is already capped and
+     overlap-free). An empty `ready` with work in flight means "waiting";
+     keep looping. `epilogueDue: true` means every Story is done — leave the
+     loop and go to step 4.
    - **2** — `cycleError`: the graph is self-referential. Fix the
      `depends_on` declarations; do not retry.
    - **3** — `wedged`: nothing is dispatchable, nothing is in flight, and
@@ -102,6 +123,20 @@ to respect.
      names the stuck ids and their unmet blockers. Either land the blocker
      first or include it in `--ids`. Do not retry unchanged — the state
      cannot improve on its own.
+   - **4** — `blocked`: one or more Stories carry `agent::blocked`, named in
+     `blocked[]` with `blockedReason`. This is the protocol's HITL pause
+     ([`instructions.md` § 1.J](../instructions.md)) — **stop the loop and
+     surface it to the operator; do not poll.** No beat can clear it, because
+     a human owes a decision. Read the Story's friction comment, and resume
+     only once the operator has unblocked it:
+
+     ```bash
+     gh issue view <id> --comments
+     node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready
+     ```
+
+     A blocked Story outranks a wedge (its blockers are moot while a human
+     owes a decision) but not a cycle (exit 2 — fix the graph first).
 
    For each `ready` Story id, read
    [`helpers/deliver-story.md`](helpers/deliver-story.md) **in full** and
@@ -109,8 +144,8 @@ to respect.
    `--yes` / injected helper content, execute directly without a re-read
    turn.
 
-4. **Per-run epilogue (N>1).** After the last Story lands, keyed on the
-   delivered id set:
+4. **Per-run epilogue (N>1).** Once step 3 reports `epilogueDue: true`
+   (every Story done), keyed on the delivered id set:
 
    ```bash
    node .agents/scripts/plan-run-epilogue.js --stories 101,102

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -13,8 +13,10 @@ description: >-
 > only its wrapper (Story label transitions).
 
 After the implementation commits land and **before** the Story proceeds to
-close, run an explicit, **independent** eval pass that scores the working diff
-against **each** `acceptance[]` item individually. This is the acceptance gate
+close, run an explicit, **independent** eval pass that scores the change set
+computed once for this Story and injected into the critic — never one the
+critic re-derives (Story #4593) — against **each** `acceptance[]` item
+individually. This is the acceptance gate
 the close-validation chain does not provide: that chain (lint / test / format /
 maintainability / coverage / crap) proves the code is *healthy*, not that it
 satisfies *this Story's* acceptance criteria.
@@ -46,7 +48,10 @@ mid-delivery, and evaluates the actual work product.
    > — the same signal `review-depth.js` resolves depth from, so the two
    > decisions cannot disagree. Derive it with `deriveChangeLevel` from
    > [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) over
-   > the Story's changed files (`git diff --name-only main...story-<id>`), then
+   > the **change set your caller computed once** for this Story (Story #4593 —
+   > `computeChangeSet` from
+   > [`change-set.js`](../../scripts/lib/orchestration/change-set.js); see
+   > [`deliver-story.md`](deliver-story.md) Step 2), then
    > resolve the ceremony per cluster with `resolveCeremonyForRisk` from
    > [`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)
    > using that `derivedLevel` and `delivery.routing.freshCriticSampleRate`:
@@ -87,8 +92,12 @@ mid-delivery, and evaluates the actual work product.
    > comment (if you block) that the inline fallback was used.
 
    The critic:
-   - Inspects the working diff (`git diff origin/<baseBranch>...HEAD`) and the
-     Story's inline `acceptance[]` / `verify[]` arrays.
+   - Inspects the **change set handed to it in its spawn context** — the one
+     list computed above — and the Story's inline `acceptance[]` / `verify[]`
+     arrays. Pass the file list explicitly when you dispatch the critic; it
+     does not re-enumerate the diff for itself (Story #4593), so a commit
+     landing mid-ceremony cannot leave the critic scoring a different change
+     than the one that routed it.
    - **Runs the `verify[]` commands** and consumes their output as **required
      evidence** when scoring the relevant acceptance items. `verify[]` is not
      optional advisory pre-flight — a criterion cannot be scored `met` without