mandrel 2.46.0 → 2.47.0

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -88,7 +88,8 @@
         "refCleanup",
         "baseFastForward",
         "tempPurge",
-        "leaseRelease"
+        "leaseRelease",
+        "epicRollup"
       ],
       "properties": {
         "followUps": { "type": "boolean" },
@@ -103,6 +104,10 @@
           "type": "boolean",
           "description": "Story #4860 — the operator's assignee-lease on the Story was released now that the merge is confirmed. The close deliberately no longer releases it at PR creation, so the ticket stays assigned for the whole time its PR is open; every non-merged ending (merge.unlanded block, exhausted wait budget, --no-wait-merge, --no-auto-merge) retains the claim and never reaches this step. A no-op release — the operator is no longer the recorded owner, as on a re-run or a belated manual confirm — reports true: an already-unassigned ticket is the desired end state. Only a throw reports false, and like every tail step that degrades the report, never the land."
         },
+        "epicRollup": {
+          "type": "boolean",
+          "description": "Story #5205 — the container Epic listing this Story was rolled up from its children: Status column derived from their composition, the operator recorded as its owner while any child is in flight, and the Epic closed once every child landed. A Story under no container reports true — there was nothing to roll up, which IS the correct outcome. Only a real failure — an unreadable child, a refused board or issue mutation — reports false, and like every tail step that degrades the report, never the land."
+        },
         "details": {
           "type": "object",
           "description": "Per-step diagnostic detail — the reason a false step reported false.",

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -108,8 +108,9 @@ export class ColumnSync {
   }
 
   /**
-   * Sync a single issue to its target column. Returns a result descriptor
-   * (`synced | skipped | failed`) so callers can log without parsing errors.
+   * Sync a single issue to the column its `agent::*` labels imply. Returns a
+   * result descriptor (`synced | skipped | failed`) so callers can log
+   * without parsing errors.
    *
    * @param {number} issueId
    * @param {string[]} labels
@@ -117,6 +118,29 @@ export class ColumnSync {
   async sync(issueId, labels) {
     const column = columnForLabels(labels);
     if (!column) return { status: 'skipped', reason: 'no-matching-label' };
+    return this.setColumn(issueId, column);
+  }
+
+  /**
+   * Push one issue to a column named **directly**, skipping the label
+   * derivation {@link sync} performs.
+   *
+   * Split out for the one caller whose target column cannot come from labels:
+   * a container Epic carries no `agent::*` label by construction, so
+   * {@link columnForLabels} returns `null` for it and `sync` can never move
+   * it. The Epic's column is derived from its children instead
+   * (`epic-rollup.js`) and handed here — which keeps that derivation from
+   * having to fabricate a label on the container just to reach the board, the
+   * one thing the container invariant forbids.
+   *
+   * Every skip path, the metadata cache and the stale-cache self-heal are
+   * shared with `sync` because they live here rather than in it.
+   *
+   * @param {number} issueId
+   * @param {string} column Board column name (`Todo` | `In Progress` | `Done`).
+   */
+  async setColumn(issueId, column) {
+    if (!column) return { status: 'skipped', reason: 'no-column' };
     if (!this.projectNumber) {
       return { status: 'skipped', reason: 'no-project' };
     }

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

@@ -18,6 +18,14 @@
  * `resolve-stories` (which expands one) — import from here so the written
  * shape and the read shape cannot drift apart.
  *
+ * **The container's lifecycle is derived, never labelled.** It still carries
+ * no `agent::*` label — that absence is what keeps it out of the bare
+ * `/mandrel-deliver` ready list and outside `lint-issue-body.js`. What it does
+ * carry is a Projects v2 Status column, an owner while its children run, and
+ * eventually a closed state, all computed from the children by
+ * `epic-rollup.js` and written directly (Story #5205). Deriving rather than
+ * labelling is the whole reason those two facts can coexist.
+ *
  * @module lib/orchestration/epic-container
  * @see Story #5139
  */

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

@@ -0,0 +1,401 @@
+/**
+ * epic-rollup.js — derive a container Epic's board state from its children.
+ *
+ * A container Epic is never delivered, so nothing in the delivery engine
+ * ever writes to it. That left it inert on the board for the whole run it
+ * was the subject of: `columnForLabels` reads `agent::*` labels and the
+ * container carries none by construction, so the Status sync always skipped
+ * it; and the only closure lived in the multi-Story run epilogue, which a
+ * single-Story delivery never reaches.
+ *
+ * This module is the one place that answers "what state is this Epic in?"
+ * — by asking its children — and the one place that writes the answer.
+ * {@link rollUpEpicForStory} is invoked from the two per-Story lifecycle
+ * edges (the `agent::executing` flip in `single-story-init.js` and the
+ * post-land tail), which is what makes the rollup hold at N=1, and the run
+ * epilogue delegates its Epic close here so one closure rule exists.
+ *
+ * Three invariants shape the writes:
+ *
+ *   1. **The Epic never gains an `agent::*` label.** That absence keeps the
+ *      container out of the bare `/mandrel-deliver` ready list and outside
+ *      `lint-issue-body.js`, so the derived column goes to the board
+ *      directly via `ColumnSync.setColumn` rather than through a label.
+ *   2. **Status recomputes in both directions; closure is one-way.** A
+ *      reopened child pulls a closed Epic's Status back to `In Progress`
+ *      and MUST NOT reopen the issue — an operator who closed a container
+ *      deliberately is not overruled by a reopened child.
+ *   3. **Never throws.** Every step degrades with a reason. A stale
+ *      container costs tidiness; a delivery failed on a board mutation
+ *      costs a landed Story its terminal envelope.
+ *
+ * @module lib/orchestration/epic-rollup
+ * @see Story #5205
+ */
+
+import { Logger } from '../Logger.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
+import { ColumnSync, LABEL_TO_COLUMN } from './column-sync.js';
+import { isEpicTicket, readEpicChildIdsFrom } from './epic-container.js';
+import { resolveOperatorFromCandidates } from './lease-guard-shared.js';
+import { deriveParentState } from './ticketing/bulk.js';
+
+/**
+ * Derived states that mean "children are moving" — the window in which the
+ * Epic carries an owner. `agent::blocked` counts: a blocked child is still
+ * this operator's problem, and dropping the assignee at the moment someone
+ * needs to be found would invert the signal.
+ */
+const IN_FLIGHT_STATES = new Set([
+  AGENT_LABELS.EXECUTING,
+  AGENT_LABELS.BLOCKED,
+]);
+
+/**
+ * Read an Epic's native sub-issue children as issue numbers.
+ *
+ * A local adapter rather than an import from `resolve-stories.js`: that
+ * module is a CLI entrypoint, and reaching up into one from the lib layer to
+ * borrow four lines would invert the dependency direction for no gain. What
+ * matters is that the *reader* handed to `readEpicChildIdsFrom` behaves the
+ * same on both paths, which is what keeps an Epic from being expandable but
+ * unclosable.
+ *
+ * @param {object} provider
+ * @returns {(epic: object) => Promise<number[]>}
+ */
+function nativeChildReader(provider) {
+  return async (epic) => {
+    if (typeof provider?._getNativeSubIssues !== 'function') return [];
+    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+  };
+}
+
+/**
+ * Resolve the handle the Epic is assigned to while its children run.
+ *
+ * Deliberately the **non-throwing** resolution (`missingHandleBehavior:
+ * 'null'`), unlike the Story lease's: a container with no owner recorded is
+ * a cosmetic gap, and refusing the whole rollup over it would cost the
+ * Status write and the closure too.
+ *
+ * @param {object} config Resolved `.agentrc.json` config.
+ * @returns {string|null} Bare login, or null when none is configured.
+ */
+function resolveEpicOwner(config) {
+  return resolveOperatorFromCandidates({
+    candidates: [config?.github?.operatorHandle],
+    missingHandleBehavior: 'null',
+  });
+}
+
+/**
+ * Normalize an issue's assignee list to bare logins.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function normalizeAssignees(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((a) => (typeof a === 'string' ? a : a?.login))
+    .filter((login) => typeof login === 'string' && login.length > 0);
+}
+
+/**
+ * Is this issue already closed?
+ *
+ * @param {{ state?: string }} issue
+ * @returns {boolean}
+ */
+function isClosed(issue) {
+  return String(issue?.state ?? '').toLowerCase() === 'closed';
+}
+
+/**
+ * Read every child of one Epic, freshly.
+ *
+ * Returns `null` when any child is unreadable. That is the conservative
+ * answer, not a lazy one: `deriveParentState` reads "all children done" off
+ * the list it is handed, so a silently dropped child could close a container
+ * with work still open under it.
+ *
+ * @param {{ epicId: number, childIds: number[], provider: object }} opts
+ * @returns {Promise<object[]|null>}
+ */
+async function readChildren({ epicId, childIds, provider }) {
+  const children = [];
+  for (const childId of childIds) {
+    let child;
+    try {
+      child = await provider.getTicket(childId);
+    } catch (err) {
+      Logger.warn(
+        `[epic-rollup] Epic #${epicId}: could not read child #${childId} ` +
+          `(${err?.message ?? err}) — leaving the Epic untouched.`,
+      );
+      return null;
+    }
+    if (!child) {
+      Logger.warn(
+        `[epic-rollup] Epic #${epicId}: child #${childId} was not found — ` +
+          'leaving the Epic untouched.',
+      );
+      return null;
+    }
+    children.push(child);
+  }
+  return children;
+}
+
+/**
+ * Push the derived column onto the Epic's board item.
+ *
+ * @param {{ epicId: number, column: string|null, columnSync: object }} opts
+ * @returns {Promise<{ column: string|null, detail: string|null }>}
+ */
+async function applyColumn({ epicId, column, columnSync }) {
+  if (!column || !columnSync) return { column: null, detail: null };
+  try {
+    const result = await columnSync.setColumn(epicId, column);
+    if (result?.status === 'synced') return { column, detail: null };
+    return { column: null, detail: result?.reason ?? 'column-not-synced' };
+  } catch (err) {
+    return { column: null, detail: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Record the operator as the Epic's owner, additively.
+ *
+ * The additive assignees mutation is the only one that cannot evict a login
+ * another run wrote between our read and our write, so it is the only one
+ * used here — and the reason the assignee is never removed when the Epic
+ * closes. A closed container naming who delivered it is useful; a removal
+ * would need the replacing endpoint and would race every concurrent run.
+ *
+ * @param {{ epicId: number, epic: object, owner: string|null, provider: object }} opts
+ * @returns {Promise<{ assigned: boolean, detail: string|null }>}
+ */
+async function applyOwner({ epicId, epic, owner, provider }) {
+  if (!owner) return { assigned: false, detail: 'no-operator-handle' };
+  if (normalizeAssignees(epic?.assignees).includes(owner)) {
+    return { assigned: false, detail: null };
+  }
+  try {
+    await provider.updateTicket(epicId, { addAssignees: [owner] });
+    return { assigned: true, detail: null };
+  } catch (err) {
+    return { assigned: false, detail: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Close a container whose children have all landed.
+ *
+ * @param {{ epicId: number, provider: object }} opts
+ * @returns {Promise<{ closed: boolean, detail: string|null }>}
+ */
+async function applyClosure({ epicId, provider }) {
+  try {
+    await provider.updateTicket(epicId, {
+      state: 'closed',
+      state_reason: 'completed',
+    });
+    Logger.info(
+      `[epic-rollup] Closed container Epic #${epicId} — every child Story landed.`,
+    );
+    return { closed: true, detail: null };
+  } catch (err) {
+    return { closed: false, detail: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Roll one Epic up from the children it lists.
+ *
+ * @param {{ epic: object, childIds: number[], provider: object, columnSync: object, owner: string|null }} opts
+ * @returns {Promise<object>} Per-Epic outcome record.
+ */
+async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
+  const epicId = Number(epic?.number ?? epic?.id);
+  const outcome = {
+    epicId,
+    column: null,
+    assigned: false,
+    closed: false,
+    pending: false,
+    detail: null,
+  };
+
+  const children = await readChildren({ epicId, childIds, provider });
+  if (children === null) {
+    outcome.pending = true;
+    outcome.detail = 'child-read-failed';
+    return outcome;
+  }
+
+  const derived = deriveParentState(children);
+  const applied = await applyColumn({
+    epicId,
+    column: derived ? (LABEL_TO_COLUMN[derived] ?? null) : null,
+    columnSync,
+  });
+  outcome.column = applied.column;
+  if (applied.detail) outcome.detail = applied.detail;
+
+  if (IN_FLIGHT_STATES.has(derived)) {
+    const ownership = await applyOwner({ epicId, epic, owner, provider });
+    outcome.assigned = ownership.assigned;
+    if (ownership.detail) outcome.detail = ownership.detail;
+  }
+
+  if (derived !== AGENT_LABELS.DONE) {
+    // Not every child has landed. Reported pending only when the Epic is
+    // still open — a closed container with an outstanding child is the
+    // reopened-child case, whose Status we just corrected and whose issue
+    // state is deliberately left alone.
+    outcome.pending = !isClosed(epic);
+    return outcome;
+  }
+
+  if (isClosed(epic)) return outcome;
+
+  const closure = await applyClosure({ epicId, provider });
+  outcome.closed = closure.closed;
+  outcome.pending = !closure.closed;
+  if (closure.detail) outcome.detail = closure.detail;
+  return outcome;
+}
+
+/**
+ * Find the open container Epics that list a given Story, with their children.
+ *
+ * The lookup runs child→parent by scanning open Epics because linkage is
+ * parent→child only — a Story body carries no pointer back, and adding one
+ * would reverse ADR `20260726-v2-story-collapse`. It is cheap: open
+ * containers are few, and only one listing this Story is ever read further.
+ *
+ * @param {{ storyId: number, provider: object, skipEpicIds: Set<number> }} opts
+ * @returns {Promise<Array<{ epic: object, childIds: number[] }>>}
+ */
+async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
+  let epics;
+  try {
+    epics = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[epic-rollup] Could not list open Epics (${err?.message ?? err}); ` +
+        'skipping the rollup.',
+    );
+    return [];
+  }
+
+  const matches = [];
+  for (const epic of Array.isArray(epics) ? epics : []) {
+    if (!isEpicTicket(epic)) continue;
+    const epicId = Number(epic?.number ?? epic?.id);
+    if (!Number.isInteger(epicId)) continue;
+    if (skipEpicIds.has(epicId)) continue;
+    // Body checklist UNION native sub-issue edges — the same reader the
+    // delivery expansion uses. Reading the body alone here is what made an
+    // Epic whose children were linked in the GitHub UI expandable but
+    // permanently unclosable.
+    const childIds = await readEpicChildIdsFrom({
+      epic,
+      readNativeChildIds: nativeChildReader(provider),
+      onWarn: (message) => Logger.warn(message),
+    });
+    if (!childIds.includes(storyId)) continue;
+    matches.push({ epic, childIds });
+  }
+  return matches;
+}
+
+/**
+ * Roll every container Epic listing this Story up from its children.
+ *
+ * `skipEpicIds` exists for a caller that walks several Stories of one run:
+ * siblings share a container, so without it the second Story would re-derive
+ * — and re-close — an Epic the first already closed. Live listings filter to
+ * open Epics and would eventually hide it, but a caller must not have to rely
+ * on a remote read racing its own writes.
+ *
+ * @param {{
+ *   storyId: number,
+ *   provider: object,
+ *   config?: object,
+ *   columnSync?: object,
+ *   owner?: string|null,
+ *   skipEpicIds?: Iterable<number>,
+ * }} opts
+ * @returns {Promise<{ epics: object[], closed: number[], pending: number[], reason: string|null }>}
+ */
+export async function rollUpEpicForStory({
+  storyId,
+  provider,
+  config,
+  columnSync,
+  owner,
+  skipEpicIds,
+}) {
+  const empty = { epics: [], closed: [], pending: [], reason: null };
+  const id = Number(storyId);
+  if (!Number.isInteger(id) || id <= 0) {
+    return { ...empty, reason: 'invalid-story-id' };
+  }
+  if (
+    typeof provider?.listIssuesByLabel !== 'function' ||
+    typeof provider?.getTicket !== 'function' ||
+    typeof provider?.updateTicket !== 'function'
+  ) {
+    return { ...empty, reason: 'provider-unsupported' };
+  }
+
+  try {
+    const matches = await findEpicsForStory({
+      storyId: id,
+      provider,
+      skipEpicIds: new Set(skipEpicIds ?? []),
+    });
+    if (matches.length === 0) return { ...empty, reason: 'no-container-epic' };
+
+    // One ColumnSync across every Epic in the run: it caches the board
+    // metadata, so sharing it spends the resolve once instead of per Epic.
+    const sync =
+      columnSync ??
+      (typeof provider.graphql === 'function'
+        ? new ColumnSync({ provider, logger: Logger, config })
+        : null);
+    const resolvedOwner =
+      owner === undefined ? resolveEpicOwner(config) : owner;
+
+    const epics = [];
+    for (const { epic, childIds } of matches) {
+      epics.push(
+        await rollUpOneEpic({
+          epic,
+          childIds,
+          provider,
+          columnSync: sync,
+          owner: resolvedOwner,
+        }),
+      );
+    }
+    return {
+      epics,
+      closed: epics.filter((e) => e.closed).map((e) => e.epicId),
+      pending: epics.filter((e) => e.pending).map((e) => e.epicId),
+      reason: null,
+    };
+  } catch (err) {
+    // The module-level never-throws contract. Both call sites are lifecycle
+    // edges of a Story that is otherwise fine; neither may fail on this.
+    const detail = String(err?.message ?? err);
+    Logger.warn(`[epic-rollup] Rollup for Story #${id} failed: ${detail}`);
+    return { ...empty, reason: detail };
+  }
+}

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -7,8 +7,8 @@
  *   2. Rolls up friction follow-ups across every Story in the run and
  *      files/posts them on the primary Story.
  *   3. Checks sibling Spec/acceptance coherence across Story bodies.
- *   4. Closes any container Epic whose children all landed (Story #5139) —
- *      the only completion cascade v2 reintroduces.
+ *   4. Reports the container Epics whose children all landed (Story #5139),
+ *      delegating the derivation and the close to `epic-rollup.js`.
  *
  * There is no inert planner-only path: `planRunEpilogue` enumerates steps
  * and `runPlanRunEpilogue` executes them. Single-Story runs skip the
@@ -21,8 +21,7 @@ import { selectAudits } from '../audit-suite/index.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
-import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
-import { isEpicTicket, readEpicChildIds } from './epic-container.js';
+import { rollUpEpicForStory } from './epic-rollup.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
   assessRollupOutcome,
@@ -45,118 +44,59 @@ export const RUN_EPILOGUE_STEP_KINDS = Object.freeze([
 ]);
 
 /**
- * Close a container Epic once every child Story has landed.
+ * Close every container Epic whose children all landed in this run.
  *
- * This is the **only** completion cascade v2 reintroduces (Story #5139), and
- * it is deliberately one-directional: closing the container, never touching a
- * child's state, never reopening.
+ * Delegates to `epic-rollup.js` (Story #5205) rather than deriving anything
+ * itself. That module owns the child→parent scan, the body-checklist-union-
+ * native-sub-issue child read, and the one-way closure rule, and it is also
+ * invoked from the per-Story land tail — which is what closes a container
+ * whose last open child was a single Story, a case this epilogue never
+ * reaches because a one-Story run reports `applicable: false`.
  *
- * The lookup runs child→parent by scanning open Epics, because linkage is
- * parent→child only — a Story body carries no pointer back. That is the
- * price of leaving Story bodies untouched, and it is cheap: open Epics are
- * few, and the scan is scoped to Epics that actually contain one of this
- * run's delivered Stories, so an unrelated Epic is never swept.
+ * The step survives for its report: this is the surface an operator reads to
+ * see which containers a multi-Story run closed and which are still pending.
  *
  * Non-fatal throughout: the epilogue is a reporting tail, and a container
  * left open costs tidiness, not correctness.
  *
- * @param {{ stories: string[], provider: object }} opts
+ * @param {{ stories: string[], provider: object, config?: object }} opts
  * @returns {Promise<{ kind: string, closed: number[], pending: number[] }>}
  */
-async function executeEpicClose({ stories, provider }) {
-  const result = { kind: 'epic-close', closed: [], pending: [] };
-  if (
-    typeof provider?.listIssuesByLabel !== 'function' ||
-    typeof provider?.updateTicket !== 'function'
-  ) {
-    return result;
-  }
+async function executeEpicClose({ stories, provider, config }) {
+  const closed = new Set();
+  const pending = new Set();
+  // Siblings share a container, so an Epic resolved by one Story's rollup is
+  // withheld from the next one's — otherwise the second Story would re-derive
+  // and re-close what the first already closed.
+  const seen = new Set();
 
-  const delivered = new Set(stories.map((id) => Number(id)));
-  let epics;
-  try {
-    epics = await provider.listIssuesByLabel({
-      state: 'open',
-      labels: TYPE_LABELS.EPIC,
+  // `rollUpEpicForStory` never throws and always returns the full envelope,
+  // so its three lists are read directly — a `?? []` guard here would be an
+  // unreachable branch asserting a contract the module already keeps.
+  for (const raw of stories) {
+    const storyId = Number(raw);
+    if (!Number.isInteger(storyId) || storyId <= 0) continue;
+    const outcome = await rollUpEpicForStory({
+      storyId,
+      provider,
+      config,
+      skipEpicIds: seen,
     });
-  } catch (err) {
-    Logger.warn(
-      `[run-epilogue] Could not list open Epics (${err?.message ?? err}); skipping the Epic close.`,
-    );
-    return result;
-  }
-
-  for (const epic of Array.isArray(epics) ? epics : []) {
-    if (!isEpicTicket(epic)) continue;
-    const epicId = Number(epic?.number ?? epic?.id);
-    if (!Number.isInteger(epicId)) continue;
-
-    const childIds = readEpicChildIds(epic?.body);
-    if (childIds.length === 0) continue;
-    // Only Epics this run actually advanced. Sweeping every open Epic would
-    // make a delivery close containers it had nothing to do with.
-    if (!childIds.some((c) => delivered.has(c))) continue;
-
-    let allLanded = true;
-    for (const childId of childIds) {
-      try {
-        const child = await provider.getTicket(childId);
-        if (!isSatisfiedChild(child)) {
-          allLanded = false;
-          break;
-        }
-      } catch (err) {
-        Logger.warn(
-          `[run-epilogue] Epic #${epicId}: could not read child #${childId} ` +
-            `(${err?.message ?? err}) — leaving the Epic open.`,
-        );
-        allLanded = false;
-        break;
-      }
-    }
-
-    if (!allLanded) {
-      result.pending.push(epicId);
-      continue;
-    }
-
-    try {
-      await provider.updateTicket(epicId, {
-        state: 'closed',
-        state_reason: 'completed',
-      });
-      Logger.info(
-        `[run-epilogue] Closed container Epic #${epicId} — all ${childIds.length} child Story(ies) landed.`,
-      );
-      result.closed.push(epicId);
-    } catch (err) {
-      Logger.warn(
-        `[run-epilogue] Could not close Epic #${epicId} (${err?.message ?? err}).`,
-      );
-      result.pending.push(epicId);
-    }
+    for (const epic of outcome.epics) seen.add(epic.epicId);
+    for (const epicId of outcome.closed) closed.add(epicId);
+    for (const epicId of outcome.pending) pending.add(epicId);
   }
 
-  return result;
-}
+  // An Epic this run closed can also have been reported pending by an
+  // earlier Story's rollup, when a sibling had not landed yet. The close is
+  // the later, truer answer.
+  for (const epicId of closed) pending.delete(epicId);
 
-/**
- * A child no longer holds its Epic open once it is closed or `agent::done`.
- *
- * Mirrors `isSatisfiedBlocker` in `lib/orchestration/resolve-stories.js`
- * rather than importing it: that module is the delivery-resolution path and
- * pulling it in here would drag the whole story-body parser into the
- * epilogue for a two-line predicate.
- *
- * @param {{ state?: string, labels?: unknown }} issue
- * @returns {boolean}
- */
-function isSatisfiedChild(issue) {
-  if (String(issue?.state ?? '').toLowerCase() === 'closed') return true;
-  const labels = Array.isArray(issue?.labels)
-    ? issue.labels.map((l) => (typeof l === 'string' ? l : l?.name))
-    : [];
-  return labels.includes(AGENT_LABELS.DONE);
+  return {
+    kind: 'epic-close',
+    closed: [...closed],
+    pending: [...pending],
+  };
 }
 
 /**
@@ -952,7 +892,7 @@ export async function runPlanRunEpilogue({
         );
       } else if (step.kind === 'epic-close') {
         results.push(
-          await executeEpicClose({ stories: plan.stories, provider }),
+          await executeEpicClose({ stories: plan.stories, provider, config }),
         );
       }
     } catch (err) {

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -40,6 +40,7 @@ import {
 } from '../../../observability/runtime-friction.js';
 import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import { purgeStoryTempArtifacts as defaultPurgeStoryTempArtifacts } from '../../../temp-retention.js';
+import { rollUpEpicForStory as defaultRollUpEpicForStory } from '../../epic-rollup.js';
 import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
@@ -298,6 +299,45 @@ async function stepLeaseRelease({
  */
 const REAP_SWEEP_REMEDY = 'node .agents/scripts/prune-plan-run-labels.js';
 
+/**
+ * Roll the closing Story's container Epic up from its children (Story #5205).
+ *
+ * Wired here for the same reason the cohort-label reap is: this is the only
+ * seam both a single- and a multi-Story run reach. The run epilogue that used
+ * to own the Epic close runs at N>1 only, so a container whose last open
+ * child was one Story stayed open forever.
+ *
+ * Unlike the reap, the outcome IS reported in the returned `tail`. The
+ * distinction is what an operator can act on: a stale cohort label is read by
+ * nothing, whereas an Epic left open or showing the wrong column is a visible
+ * board state someone will otherwise correct by hand, so a false here earns
+ * its line in the envelope.
+ *
+ * @returns {Promise<{ ok: boolean, detail: string|null }>}
+ */
+async function stepEpicRollup({
+  storyId,
+  provider,
+  config,
+  progress,
+  rollUpEpicForStoryFn,
+}) {
+  const outcome = await rollUpEpicForStoryFn({ storyId, provider, config });
+  for (const epicId of outcome?.closed ?? []) {
+    progress?.(
+      'POST-LAND',
+      `🗃️  Closed container Epic #${epicId} — every child Story landed.`,
+    );
+  }
+  const failures = (outcome?.epics ?? []).filter((e) => e?.detail);
+  return {
+    ok: failures.length === 0,
+    detail: failures.length
+      ? failures.map((e) => `#${e.epicId}: ${e.detail}`).join('; ')
+      : null,
+  };
+}
+
 /**
  * Reap the cohort labels the closing Story carried (Story #5189).
  *
@@ -396,7 +436,8 @@ async function stepPlanRunLabelReap({
  * @param {Function} [args.purgeStoryTempArtifactsFn] Test seam.
  * @param {Function} [args.releaseStoryLeaseFn]     Test seam.
  * @param {Function} [args.reapPlanRunLabelsForStoryFn] Test seam.
- * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, leaseRelease: boolean, details: Record<string, string|null> }>}
+ * @param {Function} [args.rollUpEpicForStoryFn]     Test seam.
+ * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, leaseRelease: boolean, epicRollup: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
   storyId,
@@ -417,6 +458,7 @@ export async function runPostLandTail({
   purgeStoryTempArtifactsFn = defaultPurgeStoryTempArtifacts,
   releaseStoryLeaseFn = defaultReleaseStoryLease,
   reapPlanRunLabelsForStoryFn = defaultReapPlanRunLabelsForStory,
+  rollUpEpicForStoryFn = defaultRollUpEpicForStory,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -483,6 +525,21 @@ export async function runPostLandTail({
     { name: 'plan-run label reap', progress },
   );
 
+  // Story #5205 — the container Epic's state is derived from its children, so
+  // the child reaching `agent::done` is the edge that can close it. Runs with
+  // the other GitHub-touching steps, outside the checkout lock.
+  const epicRollup = await step(
+    () =>
+      stepEpicRollup({
+        storyId,
+        provider,
+        config,
+        progress,
+        rollUpEpicForStoryFn,
+      }),
+    { name: 'epic rollup', progress },
+  );
+
   // Local-checkout mutations: serialized behind a best-effort cross-process
   // lock (Story #4622). Acquire once, run both steps, release in `finally`.
   const lockCfg = config?.delivery?.postLandLock ?? {};
@@ -555,6 +612,7 @@ export async function runPostLandTail({
     baseFastForward: baseFastForward.ok,
     tempPurge: tempPurge.ok,
     leaseRelease: leaseRelease.ok,
+    epicRollup: epicRollup.ok,
     details: {
       followUps: followUps.detail,
       statusResync: statusResync.detail,
@@ -562,6 +620,7 @@ export async function runPostLandTail({
       baseFastForward: baseFastForward.detail,
       tempPurge: tempPurge.detail,
       leaseRelease: leaseRelease.detail,
+      epicRollup: epicRollup.detail,
     },
   };
   const degraded = Object.entries(tail)

package/.agents/scripts/single-story-init.js

@@ -55,6 +55,7 @@ import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
 import { emitTerseResult } from './lib/observability/terse-result.js';
+import { rollUpEpicForStory } from './lib/orchestration/epic-rollup.js';
 import {
   executeFastForward,
   planFastForward,
@@ -223,6 +224,34 @@ async function flipStoryToExecuting(provider, storyId, story) {
   }
 }
 
+/**
+ * Roll any container Epic listing this Story up from its children.
+ *
+ * A container carries no `agent::*` label, so the Status sync that follows
+ * the flip above cannot reach it — its column is derived from its children
+ * instead. This is the edge where the first child of an Epic starts moving,
+ * which is what puts the Epic on the board as In Progress with an owner.
+ *
+ * Best-effort by construction: the rollup never throws, and a container left
+ * at a stale column must never cost the Story its init.
+ *
+ * @param {object} provider
+ * @param {number} storyId
+ * @param {object} config
+ * @returns {Promise<void>}
+ */
+async function rollUpContainerEpic(provider, storyId, config) {
+  const outcome = await rollUpEpicForStory({ storyId, provider, config });
+  for (const epic of outcome.epics) {
+    if (!epic.column) continue;
+    progress(
+      'EPIC',
+      `🗃️  Epic #${epic.epicId} → ${epic.column}` +
+        (epic.assigned ? ' (assigned)' : ''),
+    );
+  }
+}
+
 /**
  * Undo this run's claim when provisioning fails after the early
  * `agent::executing` flip: revert the label to `agent::ready` and release the
@@ -675,6 +704,12 @@ export async function runSingleStoryInit({
     // install window instead of reading agent::ready and double-dispatching.
     await flipStoryToExecuting(provider, storyId, story);
 
+    // Story #5205 — the child is now in flight, so any container Epic listing
+    // it is too. Fired here rather than after provisioning so the board shows
+    // In Progress for the whole install window, and after the flip so the
+    // rollup reads the state it derives from.
+    await rollUpContainerEpic(provider, storyId, config);
+
     // Any failure from here on leaves a claimed, executing-labelled Story with
     // no live run behind it — revert the label and release the lease so the
     // Story is not stranded as phantom-executing.

package/.agents/workflows/helpers/deliver-reference.md

@@ -292,18 +292,40 @@ This executes, in order:
   (files issues when auto-file is on; posts `follow-ups`).
 - `sibling-coherence` — Spec/Acceptance coherence check across sibling bodies
   (`plan-run-sibling-coherence`).
-- `epic-close` — closes a container Epic once **every** child Story is
-  `agent::done`, as `completed`. This is the only completion cascade v2 has:
-  it closes the container and nothing else — no child status roll-up, no label
-  inheritance, no reopening. Because linkage is parent→child only, the parent
-  is found by scanning open `type::epic` issues, and only an Epic containing
-  one of *this run's* Stories is considered, so an unrelated container is
-  never swept. An Epic with an outstanding child is reported `pending` and
-  left open.
+- `epic-close` — **reports** which container Epics this run closed and which
+  are still pending. It derives nothing itself: every step here and the
+  per-Story land tail alike delegate to `epic-rollup.js`, so one rule decides
+  a container's state.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).
 
+## Container-Epic rollup (every N)
+
+A container Epic is never delivered, so nothing used to write to it during
+the run it was the subject of. `epic-rollup.js` derives its state from its
+children at both per-Story lifecycle edges — the `agent::executing` flip in
+`single-story-init.js` and the post-land tail (reported as the tail's
+`epicRollup` step) — which is why it holds at **N=1**, where no epilogue runs.
+
+- **Status** follows the children's composition (`deriveParentState` mapped
+  onto the board's three options): any child executing or blocked → `In
+  Progress`, every child `agent::done` or closed → `Done`. It is written
+  **directly**, never via a label: the container carries no `agent::*` label
+  by construction, which is what keeps it out of the bare `/mandrel-deliver`
+  ready list.
+- **Owner** — `github.operatorHandle` is added to the Epic while any child is
+  in flight, through the additive assignees endpoint, and is never removed.
+- **Closure** is one-way: every child landed closes the container as
+  `completed`; a reopened child moves Status back to `In Progress` and does
+  **not** reopen it.
+- The parent lookup scans open `type::epic` issues, because linkage is
+  parent→child only, and reads children as the body checklist **union** the
+  native sub-issue edges — the same reader `/mandrel-deliver`'s expansion
+  uses, so an Epic can never be expandable but unclosable.
+- Every step is best-effort and never throws: a stale container costs
+  tidiness, not a landed Story's envelope.
+
 ## Ceremony (profiles + two scopes)
 
 Ceremony depth is selected by `delivery.routing.ceremonyProfile`
@@ -323,7 +345,7 @@ sensitive-path classes in `audit-rules.json`
 | **Per-Story (always)** | Gates, branch discipline, close-and-land | `deliver-story` / `single-story-close` |
 | **Per-Story (profile + derived level)** | Acceptance critic mode; review depth | `ceremony-routing.js` + `review-depth.js` + `code-review.js` |
 | **Per-run (N>1)** | Audit roster · follow-up roll-up · sibling coherence | `plan-run-epilogue.js` once at run end |
-| **Per-Story land tail** | Follow-up capture · status resync · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
+| **Per-Story land tail** | Follow-up capture · status resync · Epic rollup · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
 
 ## Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`)
 

package/.agents/workflows/mandrel-deliver.md

@@ -102,9 +102,9 @@ to an attended run.
 
 4. **Close each hand-off** (§ Closing what the workers hand back), then, with
    every Story landed, run the **per-run epilogue (N>1)**:
-   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`, which also
-   closes a container Epic whose children all landed. N=1 skips it
-   ([reference](helpers/deliver-reference.md)).
+   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
+   ([reference](helpers/deliver-reference.md)). Every close rolls its container
+   Epic up from its children.
 
 5. **Correct what the change invalidated.** If a memory you recalled this
    session is now wrong — a trap this landed, a budget it moved — fix that entry

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.47.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.46.0...mandrel-v2.47.0) (2026-09-07)
+
+
+### Added
+
+* roll a container Epic's board status, assignee and closure up from its child Stories ([#5205](https://github.com/dsj1984/mandrel/issues/5205)) ([#5206](https://github.com/dsj1984/mandrel/issues/5206)) ([38aae8b](https://github.com/dsj1984/mandrel/commit/38aae8bb4c273b258b420b463781970df18f58e1))
+
 ## [2.46.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.45.0...mandrel-v2.46.0) (2026-09-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.46.0",
+  "version": "2.47.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",