mandrel 2.39.0 → 2.40.0

package/.agents/scripts/lib/orchestration/epic-container.js

@@ -0,0 +1,186 @@
+/**
+ * epic-container.js — the one module describing a container Epic.
+ *
+ * An Epic here is a **pure container**: a `type::epic` issue whose body is a
+ * short `## Goal` paragraph and a `- [ ] #N` child checklist, and nothing
+ * else. It carries no `## Spec`, no `acceptance[]` / `verify[]`, and no
+ * `agent::*` label. It is never branched, never implemented and never
+ * delivered — `/mandrel-deliver <epicId>` expands it to its open children and
+ * delivers those.
+ *
+ * **Linkage is parent→child only.** The Epic holds every edge; Story bodies
+ * are never touched. That is the whole reason this can exist without
+ * reversing ADR `20260726-v2-story-collapse`: the `Epic: #N` footer stays
+ * retired and every refusal that reads it still fires, so each Story remains
+ * independently deliverable and the delivery engine stays Story-only.
+ *
+ * Both consumers — `plan-persist` (which writes an Epic) and
+ * `resolve-stories` (which expands one) — import from here so the written
+ * shape and the read shape cannot drift apart.
+ *
+ * @module lib/orchestration/epic-container
+ * @see Story #5139
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+
+/**
+ * The checklist grammar. `getSubTickets` (`providers/github/issues.js`)
+ * already parses this exact form as its strategy-2 child source, so the
+ * checklist is a durable mirror of the native sub-issue edges rather than a
+ * second, competing representation: when the sub-issues API is unavailable
+ * — an older GHES, a revoked scope, a partial write — the children are still
+ * discoverable from the body alone.
+ *
+ * Kept in sync with `_getChecklistChildren` deliberately; a divergence here
+ * would strand children the writer believes it linked.
+ */
+const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+#(\d+)\s*$/gm;
+
+/** Heading the container's one prose section renders under. */
+const GOAL_HEADING = '## Goal';
+
+/** Heading the child checklist renders under. */
+const CHILDREN_HEADING = '## Stories';
+
+/**
+ * Normalize an issue's labels to plain strings. GitHub hands labels back
+ * either as objects (`{ name }`) or, once mapped, as bare strings; callers
+ * should not have to care which shape they hold.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function normalizeLabels(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * Is this issue a container Epic?
+ *
+ * Reads the `type::epic` label and nothing else — the label is the
+ * authoritative marker. Body shape is deliberately NOT part of the test: a
+ * hand-edited Epic whose checklist an operator reordered or annotated is
+ * still an Epic, and treating it otherwise would silently reclassify it as
+ * an ordinary non-Story and hard-error the delivery.
+ *
+ * @param {{ labels?: unknown }} issue
+ * @returns {boolean}
+ */
+export function isEpicTicket(issue) {
+  return normalizeLabels(issue?.labels).includes(TYPE_LABELS.EPIC);
+}
+
+/**
+ * Render a container Epic's body.
+ *
+ * The output is intentionally minimal — a goal paragraph and a checklist.
+ * The Epic must carry **no information a child does not already carry**: it
+ * is a container, so anything unique living here would be a fact with no
+ * home in the tickets that actually get executed, invisible to every agent
+ * delivering them.
+ *
+ * @param {{ goal: string, childIds?: number[] }} opts
+ * @returns {string} Canonical Epic body markdown.
+ */
+export function composeEpicBody({ goal, childIds = [] } = {}) {
+  const text = typeof goal === 'string' ? goal.trim() : '';
+  if (text === '') {
+    throw new Error('[epic-container] composeEpicBody requires a goal.');
+  }
+
+  const ids = normalizeChildIds(childIds);
+  const lines = [GOAL_HEADING, '', text, '', CHILDREN_HEADING, ''];
+  if (ids.length === 0) {
+    lines.push('_No child Stories linked._');
+  } else {
+    for (const id of ids) lines.push(`- [ ] #${id}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Coerce a child-id list to positive integers, deduped, order-preserving.
+ *
+ * @param {unknown} raw
+ * @returns {number[]}
+ */
+export function normalizeChildIds(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of raw) {
+    const id = Number(entry);
+    if (!Number.isInteger(id) || id <= 0) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Read the child issue numbers an Epic body declares.
+ *
+ * Body-only, by design: this is the fallback that works with nothing but the
+ * issue text. Callers that can reach the API should union this with the
+ * native sub-issue edges (`readEpicChildIdsFrom`), because an operator can
+ * link a child in the GitHub UI without touching the checklist.
+ *
+ * @param {string|null|undefined} body
+ * @returns {number[]}
+ */
+export function readEpicChildIds(body) {
+  if (typeof body !== 'string' || body === '') return [];
+  // `matchAll` on a /g regex starts from lastIndex; the literal is
+  // module-scoped, so reset it rather than leaking state across calls.
+  CHECKLIST_ITEM_RE.lastIndex = 0;
+  return normalizeChildIds(
+    [...body.matchAll(CHECKLIST_ITEM_RE)].map((m) => Number.parseInt(m[1], 10)),
+  );
+}
+
+/**
+ * Resolve an Epic's children from **both** sources — the body checklist and
+ * the native sub-issue edges — as one deduped list.
+ *
+ * The two are unioned rather than ranked because each can hold a child the
+ * other misses: the API is authoritative for links made in the GitHub UI,
+ * and the checklist survives an API that is unavailable or was never
+ * written. A child present in either is a child.
+ *
+ * `readNativeChildIds` is injected and may be absent or throw; a failure
+ * degrades to the checklist rather than propagating, since a body-derived
+ * child list is a strictly better answer than an error.
+ *
+ * @param {{
+ *   epic: { number?: number, id?: number, body?: string, nodeId?: string },
+ *   readNativeChildIds?: (epic: object) => Promise<number[]>,
+ *   onWarn?: (message: string) => void,
+ * }} opts
+ * @returns {Promise<number[]>}
+ */
+export async function readEpicChildIdsFrom({
+  epic,
+  readNativeChildIds,
+  onWarn,
+} = {}) {
+  const fromBody = readEpicChildIds(epic?.body);
+  if (typeof readNativeChildIds !== 'function') return fromBody;
+
+  let native = [];
+  try {
+    native = normalizeChildIds(await readNativeChildIds(epic));
+  } catch (err) {
+    const id = epic?.number ?? epic?.id ?? '?';
+    onWarn?.(
+      `[epic-container] native sub-issue read failed for Epic #${id} ` +
+        `(${err?.message ?? String(err)}); using the body checklist alone.`,
+    );
+  }
+
+  return normalizeChildIds([...native, ...fromBody]);
+}

package/.agents/scripts/lib/orchestration/epic-expansion.js

@@ -0,0 +1,148 @@
+/**
+ * epic-expansion.js — turn a container-Epic id into the open Story ids under it.
+ *
+ * Split out of `resolve-stories.js` (Story #5139): Epic expansion is a
+ * distinct concern from Story resolution — it runs strictly *before* it and
+ * hands it an ordinary id list — and folding it into that already-dense module
+ * cost 4.19 maintainability points for no cohesion gain.
+ *
+ * @module lib/orchestration/epic-expansion
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+import { isEpicTicket, readEpicChildIdsFrom } from './epic-container.js';
+import { isSatisfiedBlocker } from './resolve-stories.js';
+
+/**
+ * Does this issue carry the Story type label?
+ *
+ * @param {{ labels?: unknown }} issue
+ * @returns {boolean}
+ */
+function isStoryTicket(issue) {
+  const raw = issue?.labels;
+  if (!Array.isArray(raw)) return false;
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .includes(TYPE_LABELS.STORY);
+}
+
+/**
+ * Expand any container-Epic id in the requested set to its open child
+ * Stories, leaving every other id untouched.
+ *
+ * `/mandrel-deliver <epicId>` means "deliver everything under this Epic". The
+ * expansion happens **here, before resolution**, so everything downstream —
+ * the DAG, the ready set, the wave tick, the close tail — sees an ordinary
+ * list of Story ids and needs no Epic concept at all. That is the whole
+ * reason the Epic can exist without touching the delivery engine.
+ *
+ * Expansion is **per id**, so Epic and Story ids may be mixed freely in one
+ * invocation and the result is the deduped union in first-seen order.
+ *
+ * Two filters apply to children, and they are deliberately quieter than the
+ * treatment of a *named* id:
+ *
+ *   - **A closed / `agent::done` child is dropped.** Delivering an Epic means
+ *     delivering what is left of it. A dependent's edge onto a landed sibling
+ *     still resolves: the sibling becomes a *foreign* blocker, and foreign
+ *     blockers are checked against live state and enter `done[]`.
+ *   - **A child that is not a `type::story` is dropped with a warning.** A
+ *     named non-Story is an error because the operator asserted it was
+ *     deliverable; a linked one is the Epic's assertion, and someone attaching
+ *     a stray issue in the GitHub UI must not wedge the whole run.
+ *
+ * An Epic that expands to nothing is an **error**, not an empty success: a
+ * silent empty envelope would report a clean no-op for a delivery the
+ * operator asked for and never got.
+ *
+ * @param {{
+ *   ids: number[],
+ *   getTicket: (id: number) => Promise<object|null>,
+ *   readNativeChildIds?: (epic: object) => Promise<number[]>,
+ *   warn?: (msg: string) => void,
+ * }} opts
+ * @returns {Promise<{ ids: number[], expansions: Array<{ epicId: number, childIds: number[] }> }>}
+ */
+export async function expandEpicIds({
+  ids,
+  getTicket,
+  readNativeChildIds,
+  warn,
+}) {
+  const out = [];
+  const seen = new Set();
+  const expansions = [];
+
+  const push = (id) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push(id);
+  };
+
+  for (const id of ids) {
+    const issue = await getTicket(id);
+    if (!issue) {
+      throw new Error(`[resolve-stories] Issue #${id} was not found.`);
+    }
+    if (!isEpicTicket(issue)) {
+      push(id);
+      continue;
+    }
+
+    const childIds = await readEpicChildIdsFrom({
+      epic: issue,
+      readNativeChildIds,
+      onWarn: warn,
+    });
+    if (childIds.length === 0) {
+      throw new Error(
+        `[resolve-stories] Epic #${id} lists no child Stories. An Epic is a container: ` +
+          `link its Stories (a "- [ ] #N" checklist line or a GitHub sub-issue) ` +
+          `or deliver the Story ids directly.`,
+      );
+    }
+
+    const open = [];
+    for (const childId of childIds) {
+      let child;
+      try {
+        child = await getTicket(childId);
+      } catch (err) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: could not read child #${childId} ` +
+            `(${err?.message ?? err}) — skipping it.`,
+        );
+        continue;
+      }
+      if (!child) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: child #${childId} was not found — skipping it.`,
+        );
+        continue;
+      }
+      if (!isStoryTicket(child)) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: child #${childId} is not a ${TYPE_LABELS.STORY} ` +
+            `— skipping it. Only Stories are deliverable.`,
+        );
+        continue;
+      }
+      if (isSatisfiedBlocker(child)) continue;
+      open.push(childId);
+    }
+
+    if (open.length === 0) {
+      throw new Error(
+        `[resolve-stories] Epic #${id} has ${childIds.length} child Story(ies), ` +
+          `but none are still open — every one is closed or agent::done. ` +
+          `There is nothing left to deliver.`,
+      );
+    }
+
+    expansions.push({ epicId: id, childIds: open });
+    for (const childId of open) push(childId);
+  }
+
+  return { ids: out, expansions };
+}

package/.agents/scripts/lib/orchestration/plan-persist/epic-ops.js

@@ -0,0 +1,320 @@
+/**
+ * epic-ops.js — create the optional container Epic for a plan-persist run.
+ *
+ * Story #5139. When `/mandrel-plan` authors more than two Stories it offers to
+ * group them under one container Epic. The Epic is **not** a work item: it
+ * holds a `## Goal` paragraph and a child checklist, carries `type::epic` and
+ * nothing else, and is never branched, implemented or delivered.
+ *
+ * Ordering matters — the Epic is created **after** the Stories, because its
+ * body embeds their issue numbers and its sub-issue edges need their database
+ * ids. A container that exists before its contents would have to be written
+ * twice.
+ *
+ * @module lib/orchestration/plan-persist/epic-ops
+ */
+
+import { createHash } from 'node:crypto';
+import { linkStoriesToEpic } from '../../../providers/github/sub-issue-add.js';
+import { Logger } from '../../Logger.js';
+import { LABEL_COLORS, TYPE_LABELS } from '../../label-constants.js';
+import { composeEpicBody } from '../epic-container.js';
+
+/**
+ * The Story count at or above which `/mandrel-plan` offers a container Epic.
+ *
+ * Three, i.e. "more than two" — at two Stories a pair of ids is as easy to
+ * carry as one, and the container earns nothing.
+ */
+export const EPIC_SUGGESTION_THRESHOLD = 3;
+
+/** Length of the truncated hex digest stamped into the Epic marker. */
+const EPIC_FINGERPRINT_LENGTH = 8;
+
+/** Marker prefix identifying a persist-authored Epic in an issue body. */
+const EPIC_FINGERPRINT_MARKER_PREFIX = 'mandrel-epic-fingerprint';
+
+/**
+ * Derive the Epic's resume identity from its title and the exact child set.
+ *
+ * Keyed on the children, not just the title: two runs that group *different*
+ * Stories are different containers even under the same title, and adopting
+ * one for the other would silently leave a cohort unlinked.
+ *
+ * Fields join on NUL, written as the `\u0000` escape and never as a raw byte
+ * — a literal NUL makes git classify the file binary and drop its diffs.
+ *
+ * @param {{ title: string, childIds: number[] }} opts
+ * @returns {string} Hex digest.
+ */
+function epicFingerprint({ title, childIds }) {
+  const ids = [...childIds].sort((a, b) => a - b).join(',');
+  return createHash('sha256')
+    .update(`${title}\u0000${ids}`)
+    .digest('hex')
+    .slice(0, EPIC_FINGERPRINT_LENGTH);
+}
+
+/**
+ * Render the invisible HTML-comment marker carrying the Epic's fingerprint.
+ *
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+function epicFingerprintMarker(fingerprint) {
+  return `<!-- ${EPIC_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
+}
+
+/**
+ * Ensure the `type::epic` label exists, **failing closed**.
+ *
+ * This is deliberately the opposite posture to the cohort and route labels
+ * (`ensurePersistLabel` in `story-ops.js`), which degrade to "create without
+ * the label" because they are cosmetic. `type::epic` is not cosmetic: it is
+ * the sole marker `isEpicTicket` reads, so an Epic created without it is not
+ * an Epic — it is a stray issue that `/mandrel-deliver` will hard-error on and
+ * no expansion will ever find. Skipping creation leaves the Stories, which
+ * are the part that matters, perfectly deliverable by id.
+ *
+ * @param {{ provider: object }} opts
+ * @returns {Promise<boolean>} Whether creation may proceed.
+ */
+async function ensureEpicLabel({ provider }) {
+  if (typeof provider?.ensureLabels !== 'function') return true;
+  try {
+    const result = await provider.ensureLabels([
+      {
+        name: TYPE_LABELS.EPIC,
+        color: LABEL_COLORS.TYPE,
+        description:
+          'Container-only grouping ticket — holds child Stories, carries no execution payload',
+      },
+    ]);
+    if (
+      Array.isArray(result?.missing) &&
+      result.missing.includes(TYPE_LABELS.EPIC)
+    ) {
+      Logger.warn(
+        `[plan-persist] "${TYPE_LABELS.EPIC}" could not be verified on the remote — ` +
+          'skipping the container Epic. The Stories are unaffected and deliver by id.',
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] "${TYPE_LABELS.EPIC}" label ensure failed (${err.message}) — ` +
+        'skipping the container Epic. The Stories are unaffected and deliver by id.',
+    );
+    return false;
+  }
+}
+
+/**
+ * Find an already-created Epic carrying this fingerprint, so a resumed
+ * persist adopts it instead of opening a second container.
+ *
+ * Non-fatal: a search failure returns `null` and the caller creates. A
+ * duplicate Epic is cosmetic; a crash mid-persist is not.
+ *
+ * @param {{ provider: object, fingerprint: string }} opts
+ * @returns {Promise<{ id: number, url?: string }|null>}
+ */
+async function findExistingEpic({ provider, fingerprint }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  try {
+    const marker = epicFingerprintMarker(fingerprint);
+    const found = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+    const hit = (Array.isArray(found) ? found : []).find((issue) =>
+      String(issue?.body ?? '').includes(marker),
+    );
+    if (!hit) return null;
+    const id = Number(hit.number ?? hit.id);
+    if (!Number.isInteger(id) || id <= 0) return null;
+    return { id, url: hit.html_url ?? hit.url ?? undefined };
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] Epic resume lookup failed (${err.message}); creating a new container.`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Link the created Stories under the Epic as native sub-issue edges.
+ *
+ * Non-fatal by design — the body checklist is the durable mirror, and
+ * `getSubTickets` reads it as a first-class child source. A lost edge costs
+ * the GitHub UI's nesting, not the grouping itself.
+ *
+ * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
+ */
+async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[plan-persist] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native sub-issue edges. The Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await linkStoriesToEpic({
+      epicNumber,
+      childIssueNumbers: childIds,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.failed > 0) {
+      Logger.warn(
+        `[plan-persist] ${summary.failed} sub-issue edge(s) could not be written. ` +
+          'The Epic body checklist still lists every child; add the links by hand ' +
+          'if you want them nested in the GitHub UI.',
+      );
+    } else {
+      Logger.info(
+        `[plan-persist] sub-issue edges: ${summary.added} added, ` +
+          `${summary.skipped} already present.`,
+      );
+    }
+    return summary;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] native sub-issue mirroring failed (${err.message}) — ` +
+        'the Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+}
+
+/**
+ * Create the container Epic for a persisted cohort.
+ *
+ * Returns `null` whenever no Epic was created — not requested, too few
+ * Stories, or the label could not be ensured. Callers treat `null` as the
+ * ordinary no-Epic outcome, never as a failure.
+ *
+ * **The Epic never receives an `agent::*` label.** Its labels are exactly
+ * `[type::epic]`. That absence is load-bearing: it keeps the container out
+ * of the bare `/mandrel-deliver` ready list and outside `lint-issue-body.js`,
+ * which scopes itself to `type::story`.
+ *
+ * @param {{
+ *   provider: object,
+ *   epic: { title: string, goal: string }|null,
+ *   created: Array<{ id: number, title: string }>,
+ *   opts?: { dryRun?: boolean, minStories?: number },
+ * }} args
+ * @returns {Promise<{
+ *   id: number,
+ *   title: string,
+ *   url?: string,
+ *   childIds: number[],
+ *   adopted: boolean,
+ *   edges: { added: number, skipped: number, failed: number }|null,
+ * }|null>}
+ */
+export async function createContainerEpic({
+  provider,
+  epic,
+  created,
+  opts = {},
+}) {
+  const { dryRun = false, minStories = EPIC_SUGGESTION_THRESHOLD } = opts;
+  if (!epic) return null;
+
+  const title = typeof epic.title === 'string' ? epic.title.trim() : '';
+  const goal = typeof epic.goal === 'string' ? epic.goal.trim() : '';
+  if (title === '' || goal === '') {
+    throw new Error(
+      '[plan-persist] A container Epic requires both a title and a goal.',
+    );
+  }
+
+  const childIds = (Array.isArray(created) ? created : [])
+    .map((s) => s.id)
+    .filter((id) => Number.isInteger(id) && id > 0);
+
+  // Dry-run reports the intended container write-free. `created` carries
+  // negative placeholder ids there, so `childIds` is empty by construction —
+  // report the count from `created` itself rather than from the filtered list.
+  if (dryRun) {
+    return {
+      id: -1,
+      title,
+      childIds: (Array.isArray(created) ? created : []).map((s) => s.id),
+      adopted: false,
+      edges: null,
+    };
+  }
+
+  if (childIds.length < minStories) {
+    Logger.info(
+      `[plan-persist] ${childIds.length} Story(ies) is below the ${minStories}-Story ` +
+        'Epic threshold — no container created.',
+    );
+    return null;
+  }
+
+  if (!(await ensureEpicLabel({ provider }))) return null;
+
+  const fingerprint = epicFingerprint({ title, childIds });
+  const existing = await findExistingEpic({ provider, fingerprint });
+  if (existing) {
+    Logger.info(
+      `[plan-persist] resuming: container Epic #${existing.id} already groups ` +
+        'this exact cohort — skipping create.',
+    );
+    const edges = await mirrorSubIssueEdges({
+      provider,
+      epicNumber: existing.id,
+      childIds,
+    });
+    return {
+      id: existing.id,
+      title,
+      url: existing.url,
+      childIds,
+      adopted: true,
+      edges,
+    };
+  }
+
+  const body = `${composeEpicBody({ goal, childIds })}\n${epicFingerprintMarker(fingerprint)}\n`;
+  const result = await provider.createIssue({
+    title,
+    body,
+    labels: [TYPE_LABELS.EPIC],
+  });
+
+  const epicNumber = result.number ?? result.id;
+  const edges = await mirrorSubIssueEdges({
+    provider,
+    epicNumber,
+    childIds,
+  });
+
+  Logger.info(
+    `[plan-persist] container Epic #${epicNumber} groups ${childIds.length} Story(ies): ` +
+      `deliver them all with /mandrel-deliver ${epicNumber}`,
+  );
+
+  return {
+    id: epicNumber,
+    title,
+    url: result.url,
+    childIds,
+    adopted: false,
+    edges,
+  };
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -68,6 +68,7 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import { createContainerEpic } from './epic-ops.js';
 import {
   enforceFanOutGate,
   surfaceSoftConflictFindings,
@@ -711,6 +712,10 @@ export async function runPlanPersist({
     closeSuperseded = true,
     routeDowngradeReason = null,
     injectedRules = undefined,
+    // Story #5139 — the optional container Epic. `null` (the default) is the
+    // ordinary shape: no Epic is created unless `/mandrel-plan` offered one
+    // above the threshold and the operator confirmed it.
+    epic = null,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -840,6 +845,18 @@ export async function runPlanPersist({
     });
   }
 
+  // Story #5139 — the container Epic is created LAST among the writes: its
+  // body embeds the child issue numbers and its sub-issue edges need their
+  // database ids, neither of which exists until the Stories are live. It is
+  // never load-bearing, so a failure here degrades to "no container" and the
+  // Stories still deliver by id.
+  const containerEpic = await createContainerEpic({
+    provider,
+    epic,
+    created,
+    opts: { dryRun },
+  });
+
   const supersede = await runSupersedePhase({
     provider,
     stories,
@@ -866,5 +883,6 @@ export async function runPlanPersist({
     freshness,
     waveTable,
     supersede,
+    epic: containerEpic,
   };
 }