mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-run-state-store.js

@@ -0,0 +1,295 @@
+/**
+ * epic-run-state-store — stateless functions for reading and writing the
+ * `epic-run-state` structured comment used by `/epic-deliver`.
+ *
+ * This module is the function-based replacement for the legacy
+ * `Checkpointer` class that previously lived at
+ * `./epic-runner/checkpointer.js`. Bodies were lifted verbatim from the
+ * corresponding `Checkpointer` methods so the structured-comment shape is
+ * preserved byte-for-byte. Story #2423 (Epic #2307) deleted the class
+ * file; the class API survives as a tests-only fixture at
+ * `tests/fixtures/epic-run-state-store.js`.
+ *
+ * The comment is identified by a stable HTML marker so it can be overwritten
+ * idempotently across orchestrator restarts. The body is a fenced JSON block
+ * following the schema in tech spec #323.
+ */
+
+import { assertValidDeliverPhase } from './epic-runner/deliver-phases.js';
+import { parseFencedJsonComment } from './structured-comment-parser.js';
+import { findStructuredComment, upsertStructuredComment } from './ticketing.js';
+
+export const EPIC_RUN_STATE_TYPE = 'epic-run-state';
+export const CHECKPOINT_SCHEMA_VERSION = 1;
+
+// Re-export the phase enum + index helper so downstream importers continue
+// to use this module as a single import target.
+export {
+  DELIVER_PHASES,
+  phaseIndex,
+} from './epic-runner/deliver-phases.js';
+
+function assertProvider(provider) {
+  if (!provider)
+    throw new TypeError('epic-run-state-store requires a provider');
+}
+
+function assertEpicId(epicId) {
+  if (!Number.isInteger(epicId)) {
+    throw new TypeError('epic-run-state-store requires a numeric epicId');
+  }
+}
+
+/**
+ * Read and parse the checkpoint. Returns null if the comment is missing or
+ * unparseable (callers treat null as "start fresh").
+ *
+ * @param {{ provider: import('../ITicketingProvider.js').ITicketingProvider, epicId: number }} opts
+ * @returns {Promise<object | null>}
+ */
+export async function read({ provider, epicId } = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  const comment = await findStructuredComment(
+    provider,
+    epicId,
+    EPIC_RUN_STATE_TYPE,
+  );
+  return parseFencedJsonComment(comment);
+}
+
+/**
+ * Overwrite the checkpoint with `state`. Idempotent — callers may invoke
+ * freely per wave; the marker-scoped upsert deletes the prior comment.
+ *
+ * @param {{ provider: import('../ITicketingProvider.js').ITicketingProvider, epicId: number, state: object }} opts
+ */
+export async function write({ provider, epicId, state } = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  const payload = {
+    version: CHECKPOINT_SCHEMA_VERSION,
+    ...state,
+    lastUpdatedAt: new Date().toISOString(),
+  };
+  const body = `\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+  await upsertStructuredComment(provider, epicId, EPIC_RUN_STATE_TYPE, body);
+  return payload;
+}
+
+/**
+ * Initial checkpoint for a brand-new run. Idempotent against re-dispatch
+ * when the wave shape is unchanged. When an existing checkpoint is found
+ * but the incoming `totalWaves` or `concurrencyCap` differs from the
+ * persisted values, refresh those fields in place — preserving
+ * `currentWave`, `waves[]`, `blockerHistory`, `manualInterventions`,
+ * `startedAt`, and any other already-persisted fields (e.g., `plan`,
+ * `phase`). The `plan` field is owned by the prepare caller, which
+ * overwrites it on every prepare run, so it does not need a delta check
+ * here.
+ *
+ * @param {{ provider: import('../ITicketingProvider.js').ITicketingProvider, epicId: number, totalWaves: number, concurrencyCap: number }} opts
+ */
+export async function initialize({
+  provider,
+  epicId,
+  totalWaves,
+  concurrencyCap,
+} = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  const existing = await read({ provider, epicId });
+  if (existing) {
+    if (
+      existing.totalWaves === totalWaves &&
+      existing.concurrencyCap === concurrencyCap
+    ) {
+      return existing;
+    }
+    return write({
+      provider,
+      epicId,
+      state: { ...existing, totalWaves, concurrencyCap },
+    });
+  }
+  return write({
+    provider,
+    epicId,
+    state: {
+      epicId,
+      startedAt: new Date().toISOString(),
+      currentWave: 0,
+      totalWaves,
+      concurrencyCap,
+      phase: 'prepare',
+      waves: [],
+      blockerHistory: [],
+      manualInterventions: [],
+    },
+  });
+}
+
+/**
+ * Reconcile the resume pointer (`currentWave` + `waves[]` history) against
+ * a freshly-recomputed wave plan.
+ *
+ * Story #3358 — when `/epic-deliver` is resumed on a partially-complete
+ * Epic, `epic-deliver-prepare.js` recomputes the wave DAG over only the
+ * **not-done** Stories (`build-wave-dag.js#discoverOpenStories` drops the
+ * closed/merged Stories). The recomputed plan is therefore *shorter* and
+ * **re-indexed from 0** — `plan[0]` is the next ready wave. The preserved
+ * checkpoint, however, still carries the prior `currentWave` (e.g. `2`)
+ * and a `waves[]` history keyed to the *old* index space. `wave-tick.js`
+ * then indexes `plan[currentWave]` into the new plan and dispatches the
+ * wrong wave — silently skipping the Stories that are actually ready.
+ *
+ * Prepare already owns the `plan` field (it overwrites it on every run),
+ * so it must equally own the pointer that indexes into that plan. This
+ * helper is the single point of reconciliation:
+ *
+ *   - When the recomputed `nextPlan` is **structurally identical** to the
+ *     persisted `priorPlan` (an idempotent re-prepare with no Story
+ *     completed since the last run), the pointer is preserved verbatim so
+ *     in-flight wave progress is not lost.
+ *   - When the recomputed `nextPlan` **differs** (a Story merged → the
+ *     plan got shorter / re-indexed), the pointer is reset: `currentWave`
+ *     to `0` (the new plan's index space starts at the first not-done
+ *     wave) and `waves[]` to `[]` (the prior history references the old
+ *     index space and would mis-key `readGateFailures`).
+ *
+ * Plan equality is compared on the Story-id matrix only — `title` /
+ * `worktree` churn on an otherwise-identical plan must not trip a reset.
+ *
+ * Pure function — no I/O, no provider, no side effects.
+ *
+ * @param {{
+ *   currentWave?: number,
+ *   waves?: Array<unknown>,
+ * }} checkpoint The persisted checkpoint fields to reconcile.
+ * @param {Array<Array<{ id?: number, storyId?: number, number?: number }>>} priorPlan
+ *   The plan currently persisted on the checkpoint (may be undefined on a
+ *   first run).
+ * @param {Array<Array<{ id?: number, storyId?: number, number?: number }>>} nextPlan
+ *   The freshly-recomputed plan prepare is about to persist.
+ * @returns {{ currentWave: number, waves: Array<unknown> }} The reconciled
+ *   pointer fields. Always returns concrete values so the caller can spread
+ *   them onto the checkpoint payload unconditionally.
+ */
+export function reconcileResumePointer(checkpoint, priorPlan, nextPlan) {
+  const safeWaves = Array.isArray(checkpoint?.waves) ? checkpoint.waves : [];
+  const currentWave = Number.isInteger(checkpoint?.currentWave)
+    ? checkpoint.currentWave
+    : 0;
+  if (planStoryMatrixEqual(priorPlan, nextPlan)) {
+    return { currentWave, waves: safeWaves };
+  }
+  // Plan was recomputed (resume after a completed wave): the new plan is
+  // 0-indexed over the remaining not-done waves. Reset the pointer and
+  // drop the stale history so `wave-tick.js` reads `plan[0]`.
+  return { currentWave: 0, waves: [] };
+}
+
+/**
+ * Compare two wave plans on their Story-id matrix only. Each plan is
+ * `Array<Array<{ id|storyId|number }>>`; equality requires the same wave
+ * count, the same per-wave Story count, and the same Story ids in the same
+ * positions. `title` / `worktree` fields are ignored so cosmetic churn on
+ * an otherwise-identical plan does not register as a change.
+ *
+ * Pure helper for {@link reconcileResumePointer}.
+ *
+ * @param {Array<Array<object>>|undefined} a
+ * @param {Array<Array<object>>|undefined} b
+ * @returns {boolean}
+ */
+function planStoryMatrixEqual(a, b) {
+  const left = Array.isArray(a) ? a : [];
+  const right = Array.isArray(b) ? b : [];
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i += 1) {
+    const wl = Array.isArray(left[i]) ? left[i] : [];
+    const wr = Array.isArray(right[i]) ? right[i] : [];
+    if (wl.length !== wr.length) return false;
+    for (let j = 0; j < wl.length; j += 1) {
+      if (storyIdOf(wl[j]) !== storyIdOf(wr[j])) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Extract the Story id from a plan entry. Mirrors the resolution order
+ * `wave-runner/tick.js#storyIdOf` uses so the equality check keys on the
+ * same identity the tick dispatches against. Returns `null` for shapeless
+ * entries so two `null`s never compare equal by accident.
+ *
+ * @param {object|number|null|undefined} entry
+ * @returns {number|null}
+ */
+function storyIdOf(entry) {
+  if (typeof entry === 'number') return entry;
+  if (!entry || typeof entry !== 'object') return null;
+  const id = entry.id ?? entry.storyId ?? entry.number;
+  return Number.isInteger(id) ? id : null;
+}
+
+/**
+ * Append a manual-intervention record to the checkpoint. Out-of-band
+ * recovery steps the host LLM performs during a delivery — `AskUserQuestion`
+ * calls, `git restore`/`git reset` against the working tree, manual `--no-ff`
+ * recovery merges, story-close `--skipValidation` overrides — disqualify the
+ * Epic from auto-merge. The auto-merge predicate reads this array and only
+ * fires when it is empty.
+ *
+ * @param {{ provider: import('../ITicketingProvider.js').ITicketingProvider, epicId: number, entry: { reason: string, source?: string, ts?: string } }} opts
+ * @returns {Promise<object>} the persisted state
+ */
+export async function appendIntervention({ provider, epicId, entry } = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  if (!entry || typeof entry.reason !== 'string' || entry.reason.length === 0) {
+    throw new TypeError('appendIntervention: { reason: string } is required.');
+  }
+  const existing = (await read({ provider, epicId })) ?? {};
+  const list = Array.isArray(existing.manualInterventions)
+    ? existing.manualInterventions
+    : [];
+  const record = {
+    reason: entry.reason,
+    source: typeof entry.source === 'string' ? entry.source : 'host-llm',
+    ts: typeof entry.ts === 'string' ? entry.ts : new Date().toISOString(),
+  };
+  return write({
+    provider,
+    epicId,
+    state: {
+      ...existing,
+      manualInterventions: [...list, record],
+    },
+  });
+}
+
+/**
+ * Advance the checkpoint's `phase` field to the next `/epic-deliver`
+ * phase. Reads the current state first so the caller does not need to
+ * keep an in-memory copy. Other state fields are preserved verbatim.
+ *
+ * Story #1155 / Epic #1142 — phase-granular resume. The runner writes
+ * the **next phase to run** here, not the phase that just finished, so
+ * a resume can match `phase === 'code-review'` to mean "Phase D is the
+ * next thing to do."
+ *
+ * @param {{ provider: import('../ITicketingProvider.js').ITicketingProvider, epicId: number, nextPhase: string }} opts
+ *   nextPhase - One of `DELIVER_PHASES` or `'done'`.
+ */
+export async function setPhase({ provider, epicId, nextPhase } = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  assertValidDeliverPhase(nextPhase);
+  const existing = (await read({ provider, epicId })) ?? {};
+  return write({
+    provider,
+    epicId,
+    state: { ...existing, phase: nextPhase },
+  });
+}

package/.agents/scripts/lib/orchestration/epic-runner/concurrency-gate.js

@@ -0,0 +1,186 @@
+/**
+ * Cross-Story conflict-finding gate for `epic-deliver-prepare.js`.
+ *
+ * Story #2297 — when the bounded `/epic-plan` flow emitted concurrency
+ * findings (Story #2296's validator pass), the operator may have shipped
+ * them through to `/epic-deliver` without resolving the underlying
+ * `depends_on` gaps. This gate runs at Phase 1 of `/epic-deliver` and
+ * refuses to flip the Epic to `agent::executing` when the upcoming
+ * waves still contain unresolved conflicts — surfacing the exact
+ * remediation commands the operator should run before retrying.
+ *
+ * The gate is opt-in by default:
+ *   - Advisory findings (severity 'soft') only log a summary.
+ *   - Hard findings (severity 'hard') OR `delivery.failOnConcurrencyHazards: true`
+ *     promote a hard-stop.
+ *
+ * `--ignore-concurrency-hazards` bypasses the gate; the flag use is
+ * recorded on the Epic checkpoint so retro tooling can flag a run that
+ * shipped despite an outstanding hazard.
+ *
+ * The module is pure: it consumes a findings array and a wave plan and
+ * returns either a `{ ok: true }` envelope or throws. No I/O.
+ */
+
+/**
+ * Build the set of "pending" story identifiers from a wave plan. A Story
+ * is pending unless its labels carry `agent::done`. Identifiers are
+ * collected in three shapes — `id` (number), `number`, and `slug` — so
+ * the caller can match findings keyed by any of them.
+ *
+ * @param {Array<Array<{ id?: number|string, number?: number|string, slug?: string, labels?: string[] }>>} wavePlan
+ * @returns {Set<string>}
+ */
+export function collectPendingStoryKeys(wavePlan) {
+  const pending = new Set();
+  if (!Array.isArray(wavePlan)) return pending;
+  for (const wave of wavePlan) {
+    if (!Array.isArray(wave)) continue;
+    for (const story of wave) {
+      if (!story || typeof story !== 'object') continue;
+      const labels = Array.isArray(story.labels) ? story.labels : [];
+      if (labels.includes('agent::done')) continue;
+      if (story.id != null) pending.add(String(story.id));
+      if (story.number != null) pending.add(String(story.number));
+      if (story.slug != null) pending.add(String(story.slug));
+    }
+  }
+  return pending;
+}
+
+/**
+ * Extract every story identifier a finding references. Both finding
+ * kinds in #2296's shape carry slugs; future persisted shapes may carry
+ * numeric IDs — accept both transparently.
+ */
+function findingStoryKeys(finding) {
+  const keys = [];
+  if (Array.isArray(finding?.storySlugs)) {
+    for (const s of finding.storySlugs) keys.push(String(s));
+  }
+  if (finding?.producer?.storySlug != null) {
+    keys.push(String(finding.producer.storySlug));
+  }
+  if (finding?.consumer?.storySlug != null) {
+    keys.push(String(finding.consumer.storySlug));
+  }
+  return keys;
+}
+
+/**
+ * Filter findings to those that touch at least one pending Story. A
+ * finding all of whose referenced Stories are already `agent::done` is
+ * harmless — the conflict has already played out — and is dropped.
+ *
+ * When `pendingKeys` is empty (every wave is done) every finding is
+ * filtered out. When a finding carries no identifiers (shape drift),
+ * conservatively keep it so the operator sees the signal.
+ *
+ * @param {object[]} findings
+ * @param {Set<string>} pendingKeys
+ * @returns {object[]}
+ */
+export function filterFindingsToPending(findings, pendingKeys) {
+  if (!Array.isArray(findings)) return [];
+  if (!(pendingKeys instanceof Set)) return findings;
+  return findings.filter((f) => {
+    const keys = findingStoryKeys(f);
+    if (keys.length === 0) return true;
+    return keys.some((k) => pendingKeys.has(k));
+  });
+}
+
+function isHardFinding(f) {
+  return f && f.severity === 'hard';
+}
+
+/**
+ * Render the operator-facing remediation block for a hard-gate trip.
+ * Produces a single multi-line string suitable for `throw new Error(...)`
+ * — names every offending path, the affected Stories, and the exact
+ * `gh issue edit` commands needed to add the missing `depends_on` links.
+ */
+export function renderGateErrorMessage(findings, ownerRepo) {
+  const lines = [
+    'Refusing to flip Epic to agent::executing — cross-Story concurrency hazards remain unresolved.',
+    '',
+  ];
+  const sharedEditors = findings.filter((f) => f.kind === 'shared-editor');
+  const implicit = findings.filter(
+    (f) => f.kind === 'implicit-cross-story-dep',
+  );
+  if (sharedEditors.length > 0) {
+    lines.push('Shared-editor conflicts:');
+    for (const f of sharedEditors) {
+      const stories = Array.isArray(f.storySlugs) ? f.storySlugs : [];
+      lines.push(
+        `  - "${f.path}" written by ${stories.length} concurrent Stories: ${stories.map((s) => `#${s}`).join(', ')}`,
+      );
+      lines.push(
+        '    Remediation: add a `depends_on` chain or split the edits into a dedicated late-wave wiring Story.',
+      );
+    }
+    lines.push('');
+  }
+  if (implicit.length > 0) {
+    lines.push('Implicit cross-Story dependencies:');
+    for (const f of implicit) {
+      const p = f.producer ?? {};
+      const c = f.consumer ?? {};
+      lines.push(
+        `  - "${f.path}" produced by Story #${p.storySlug ?? '?'} consumed by Story #${c.storySlug ?? '?'} (body.${c.sourceField ?? '?'})`,
+      );
+      const repoFlag = ownerRepo ? ` --repo ${ownerRepo}` : '';
+      lines.push(
+        `    Remediation: gh issue edit ${c.storySlug ?? '?'}${repoFlag} --add-body $'\\n\\nblocked by #${p.storySlug ?? '?'}'`,
+      );
+    }
+    lines.push('');
+  }
+  lines.push(
+    'Resolve the listed conflicts and re-run `/epic-deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Apply the gate to a findings array.
+ *
+ * @param {object}    input
+ * @param {object[]}  input.findings        - Findings filtered to pending waves.
+ * @param {object}    [input.policy]        - Resolved `delivery.failOnConcurrencyHazards` (boolean).
+ * @param {boolean}   [input.ignore]        - `--ignore-concurrency-hazards` flag value.
+ * @param {string}    [input.ownerRepo]     - "owner/repo" string for `gh issue edit` hints.
+ * @returns {{ tripped: boolean, reason: 'hard-severity'|'config-fail-on'|null, findings: object[], bypassed: boolean }}
+ *          When the gate trips and `ignore` is false the caller should
+ *          throw `renderGateErrorMessage(findings, ownerRepo)`. The
+ *          returned `bypassed` is true when `ignore` short-circuits a
+ *          trip; record it on the checkpoint.
+ */
+export function evaluateConcurrencyGate({
+  findings = [],
+  policy = {},
+  ignore = false,
+  ownerRepo,
+} = {}) {
+  void ownerRepo;
+  const hardFindings = findings.filter(isHardFinding);
+  const failOnConcurrencyHazards = policy.failOnConcurrencyHazards === true;
+  if (hardFindings.length > 0) {
+    return {
+      tripped: true,
+      reason: 'hard-severity',
+      findings: hardFindings,
+      bypassed: ignore === true,
+    };
+  }
+  if (failOnConcurrencyHazards && findings.length > 0) {
+    return {
+      tripped: true,
+      reason: 'config-fail-on',
+      findings,
+      bypassed: ignore === true,
+    };
+  }
+  return { tripped: false, reason: null, findings: [], bypassed: false };
+}

package/.agents/scripts/lib/orchestration/epic-runner/deliver-phases.js

@@ -0,0 +1,50 @@
+/**
+ * deliver-phases.js — phase enum and ordering utility for `/epic-deliver`.
+ *
+ * Story #1155 (Epic #1142, 5.40.0). Originally extracted from the
+ * legacy class-based checkpoint module so the phase enum and close-tail
+ * semantics live in a dedicated module that downstream tooling (the
+ * contract test) can import without dragging the provider-coupled
+ * checkpoint surface along. Story #2409 routes the runtime checkpoint
+ * read/write surface through `../epic-run-state-store.js`; this file
+ * remains the canonical home for the phase enum + validator.
+ */
+
+/**
+ * Ordered list of `/epic-deliver` phases. The checkpoint's `phase` field
+ * stores the **next phase to run**, so a mid-flight crash during
+ * `code-review` resumes by reading `phase === 'code-review'` and re-
+ * entering Phase D from the start.
+ */
+export const DELIVER_PHASES = Object.freeze([
+  'prepare',
+  'wave-loop',
+  'close-validation',
+  'code-review',
+  'retro',
+  'finalize',
+]);
+
+/**
+ * Pure: index of `phase` in `DELIVER_PHASES`. Returns `-1` for unknown
+ * values (callers treat that as "start fresh"); `+Infinity` for the
+ * terminal `'done'` sentinel.
+ */
+export function phaseIndex(phase) {
+  if (phase === 'done') return Number.POSITIVE_INFINITY;
+  return DELIVER_PHASES.indexOf(phase);
+}
+
+/**
+ * Pure: validate that `nextPhase` is a known phase tag (or the terminal
+ * `'done'` sentinel). Throws on invalid input — exported so the
+ * `setPhase` store function and downstream callers share one failure mode.
+ */
+export function assertValidDeliverPhase(nextPhase) {
+  if (nextPhase === 'done') return;
+  if (phaseIndex(nextPhase) >= 0) return;
+  throw new Error(
+    `Invalid /epic-deliver phase ${JSON.stringify(nextPhase)}. ` +
+      `Expected one of ${DELIVER_PHASES.join(', ')} or 'done'.`,
+  );
+}

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -0,0 +1,146 @@
+/**
+ * Build the wave DAG from the Epic's open child Stories.
+ *
+ * `getSubTickets` returns the **direct** children of a parent ticket via
+ * native sub-issues + checklist links + body reverse-lookup (despite an
+ * older docstring claiming "every descendant"). The v5 canonical Epic
+ * hierarchy is Epic → Feature → Story → Task, so Stories live as
+ * **grandchildren** of the Epic. We therefore walk one level deeper from
+ * each `type::feature` direct child to collect the real Story set, and
+ * union with any direct-child Stories (some Epics still carry Stories
+ * directly while migrating).
+ *
+ * We additionally filter out closed Stories — `getSubTickets`'s reverse-
+ * reference search can surface closed-as-obsolete tickets whose body
+ * still names the Epic (e.g. a Story replaced during a planning
+ * iteration). Dispatching against those would silently fan a sub-agent
+ * out at pre-replan work.
+ *
+ * Throws if no open Stories are found.
+ */
+
+import { parseBlockedBy } from '../../../dependency-parser.js';
+import { computeWaves } from '../../../Graph.js';
+import { TYPE_LABELS } from '../../../label-constants.js';
+import { WaveScheduler } from '../wave-scheduler.js';
+
+/**
+ * Walk Epic → Feature → Story (one descent past the Epic's direct
+ * children) and return the open `type::story` tickets, deduped by id.
+ *
+ * Exported so `snapshot.js#discoverStoryIds` and `epic-deliver-preflight`
+ * can share the same enumeration contract — the snapshot.end payload,
+ * preflight Story count, and wave DAG input set must never disagree.
+ */
+export async function discoverOpenStories({ epicId, provider }) {
+  const descendants = (await provider.getSubTickets(epicId)) ?? [];
+  const features = descendants.filter((t) =>
+    (t.labels ?? []).includes(TYPE_LABELS.FEATURE),
+  );
+  const grandchildren = (
+    await Promise.all(
+      features.map(async (f) => {
+        const id = f.id ?? f.number;
+        return id == null ? [] : ((await provider.getSubTickets(id)) ?? []);
+      }),
+    )
+  ).flat();
+  const seen = new Set();
+  const stories = [];
+  for (const t of [...descendants, ...grandchildren]) {
+    const labels = t.labels ?? [];
+    if (!labels.includes(TYPE_LABELS.STORY)) continue;
+    const rawState = t.state ?? 'open';
+    const norm = typeof rawState === 'string' ? rawState.toLowerCase() : 'open';
+    if (norm !== 'open') continue;
+    const id = t.id ?? t.number;
+    if (id == null || seen.has(id)) continue;
+    seen.add(id);
+    stories.push(t);
+  }
+  return stories;
+}
+
+export async function runBuildWaveDagPhase(ctx, collaborators, state) {
+  const { epicId, provider } = ctx;
+  const bus = collaborators?.bus ?? null;
+  if (bus) {
+    await bus.emit('epic.plan.start', { epicId });
+  }
+  const stories = await discoverOpenStories({ epicId, provider });
+  if (!stories.length) {
+    throw new Error(`Epic #${epicId} has no child stories to dispatch.`);
+  }
+  const { adjacency, taskMap } = buildStoryDag(stories);
+  const waves = computeWaves(adjacency, taskMap);
+  const scheduler = new WaveScheduler(waves);
+  if (bus) {
+    // epic.plan.end carries the computed waves as the array-of-arrays
+    // shape declared by the schema. Each inner array is the storyIds
+    // dispatched together in that wave. `computeWaves` may return
+    // entries that are objects (when fed `taskMap`); we normalize to a
+    // simple numeric matrix here so the payload validates and replays
+    // off the ledger without coupling readers to internal types.
+    await bus.emit('epic.plan.end', {
+      waves: normalizeWavesForEmit(waves),
+    });
+  }
+  return { ...state, stories, waves, scheduler };
+}
+
+/**
+ * Normalize the runner's wave representation into the
+ * `Array<Array<integer>>` shape declared by
+ * `.agents/schemas/lifecycle/epic.plan.end.schema.json`. `computeWaves`
+ * returns waves of `taskMap` entries (objects with `id`); the ledger
+ * needs only the IDs. Defensive number coercion mirrors the same id
+ * extraction used in `buildStoryDag` above so emit and DAG stay
+ * structurally aligned.
+ */
+function normalizeWavesForEmit(waves) {
+  if (!Array.isArray(waves)) return [];
+  return waves.map((wave) => {
+    if (!Array.isArray(wave)) return [];
+    return wave
+      .map((entry) => {
+        if (entry == null) return null;
+        if (typeof entry === 'number') return entry;
+        const id = entry.id ?? entry.number ?? entry.storyId;
+        return id == null ? null : Number(id);
+      })
+      .filter((n) => Number.isInteger(n) && n > 0);
+  });
+}
+
+/**
+ * Convert an ordered list of story tickets into the adjacency/taskMap shape
+ * that `Graph.computeWaves()` expects.
+ *
+ * Dependency source order (must match manifest-builder.js so dispatch manifest
+ * and runtime wave scheduling never disagree):
+ *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the story
+ *      ticket body via `parseBlockedBy` (same parser the dispatcher uses).
+ *   2. Fallback: explicit `dependencies` array on the provider-returned story
+ *      object (present in fixture / test payloads; optional in live GitHub
+ *      payloads).
+ * Only edges to other stories in this Epic are retained — foreign IDs are
+ * dropped so the DAG stays closed over the scheduled set.
+ */
+function buildStoryDag(stories) {
+  const adjacency = new Map();
+  const taskMap = new Map();
+  const storyIds = new Set(stories.map((s) => Number(s.id ?? s.number)));
+  for (const s of stories) {
+    const id = Number(s.id ?? s.number);
+    const fromBody = parseBlockedBy(s.body ?? '');
+    const fromField = Array.isArray(s.dependencies)
+      ? s.dependencies.map(Number)
+      : [];
+    const merged = [...new Set([...fromBody, ...fromField])]
+      .map(Number)
+      .filter((dep) => dep !== id && storyIds.has(dep));
+    adjacency.set(id, merged);
+    taskMap.set(id, { ...s, id });
+  }
+  return { adjacency, taskMap };
+}