mandrel 2.47.0 → 2.49.0

package/.agents/scripts/lib/baselines/merge-envelopes.js

@@ -0,0 +1,272 @@
+/**
+ * merge-envelopes.js — pure 3-way merge of baseline envelopes by row
+ * identity (Story #5215).
+ *
+ * ## Why this exists
+ *
+ * Every baseline write stamps `generatedAt`, and the stamp sits on line 4 of
+ * every envelope. Two branches that each refresh a baseline therefore always
+ * differ on that line, even when they moved completely disjoint rows — so
+ * git's LINE-based merge has to reconcile it. Whether it can separate that
+ * hunk from the moved rows is an accident of proximity, and both outcomes
+ * are bad:
+ *
+ *   - it cannot → a conflict on work that never actually overlapped;
+ *   - it can → it splices both sides' row lines together into a row set
+ *     NEITHER side ever scored. That silent one is the worse failure: the
+ *     ratchet then guards a number no scorer produced.
+ *
+ * A baseline is not a text file. It is a set of rows keyed by identity plus
+ * a rollup DERIVED from those rows, so merging it as text is a category
+ * error. This module merges it as what it is.
+ *
+ * ## Contract
+ *
+ * Pure: no filesystem, no process, no clock. `assertEnvelope` is deliberately
+ * NOT called here (it compiles schemas off disk on first use) — the driver
+ * validates what this returns.
+ *
+ * Per row identity, the standard 3-way rule: the side that differs from base
+ * wins; when both sides differ from base AND from each other, that identity
+ * is a conflict. Absence is a value, so a row deleted on one side and
+ * untouched on the other merges to deleted.
+ *
+ * Two invariants are load-bearing:
+ *
+ *   1. **The rollup is recomputed, never merged.** Merging two rollups is
+ *      the same splice hazard compressed into a single number, and unlike a
+ *      spliced row set it leaves no evidence. It is always derived from the
+ *      merged rows via the kind's own `rollup()`.
+ *   2. **Identity comes from the kind module** (`rowIdentity`), never from
+ *      `keyField`. CRAP groups by file and identifies by method; keying on
+ *      `keyField` would drop every method in a file but one.
+ *
+ * @module lib/baselines/merge-envelopes
+ */
+
+import { deepEqual } from '../json-utils.js';
+import { KNOWN_KINDS } from './envelope.js';
+import { getKindModule } from './kernel.js';
+
+/**
+ * Envelope keys that are NOT merged side-by-side: `rows` merge by identity,
+ * `rollup` is recomputed from them, and `generatedAt` resolves to the later
+ * of the two stamps rather than conflicting (it is metadata about when a
+ * scorer ran, not a scored value — treating it as content is the whole bug).
+ */
+const DERIVED_KEYS = Object.freeze(['rows', 'rollup', 'generatedAt']);
+
+/**
+ * Identify an envelope's kind from its `$schema` reference.
+ *
+ * Derived from `KNOWN_KINDS` rather than pattern-matched, so a file that is
+ * not a known per-kind envelope answers `null` — which is how the driver
+ * knows to hand it back to git's text merge instead of guessing at a shape
+ * it does not understand. `baselines/*.json` also matches several
+ * non-envelope baselines (arch-cycles, cyclomatic, dead-exports, …).
+ *
+ * @param {unknown} envelope
+ * @returns {string|null}
+ */
+export function kindFromEnvelope(envelope) {
+  const ref = envelope?.$schema;
+  if (typeof ref !== 'string') return null;
+  const base = ref.split('/').pop();
+  for (const kind of KNOWN_KINDS) {
+    if (base === `${kind}.schema.json`) return kind;
+  }
+  return null;
+}
+
+/**
+ * The 3-way choice for one value. `undefined` means "absent on this side",
+ * which makes deletion just another value rather than a special case.
+ *
+ * @param {unknown} base
+ * @param {unknown} ours
+ * @param {unknown} theirs
+ * @returns {{ conflict: boolean, value?: unknown }}
+ */
+function choose(base, ours, theirs) {
+  if (deepEqual(ours, theirs)) return { conflict: false, value: ours };
+  if (deepEqual(ours, base)) return { conflict: false, value: theirs };
+  if (deepEqual(theirs, base)) return { conflict: false, value: ours };
+  return { conflict: true };
+}
+
+/**
+ * Index rows by the kind's `rowIdentity`. A duplicate identity within one
+ * side is fatal rather than last-write-wins: it means the incoming file
+ * already violates the identity contract, and merging it would silently
+ * drop a row.
+ *
+ * @param {Array<object>} rows
+ * @param {(row: object) => string} rowIdentity
+ * @param {string} side
+ * @returns {Map<string, object>}
+ */
+function indexRows(rows, rowIdentity, side) {
+  const out = new Map();
+  for (const [idx, row] of (rows ?? []).entries()) {
+    if (!row || typeof row !== 'object') {
+      throw new TypeError(
+        `mergeEnvelopes: ${side} row at index ${idx} is not an object`,
+      );
+    }
+    const id = rowIdentity(row);
+    if (out.has(id)) {
+      throw new Error(
+        `mergeEnvelopes: ${side} carries two rows with identity "${id}" — the baseline violates the identity contract and cannot be merged safely`,
+      );
+    }
+    out.set(id, row);
+  }
+  return out;
+}
+
+/**
+ * Resolve `generatedAt` to the later of the two sides. A stamp is metadata,
+ * so it never conflicts: the merged file describes a tree scored as recently
+ * as the newer of its inputs.
+ *
+ * @param {string|undefined} ours
+ * @param {string|undefined} theirs
+ * @returns {string|undefined}
+ */
+function laterStamp(ours, theirs) {
+  if (typeof ours !== 'string') return theirs;
+  if (typeof theirs !== 'string') return ours;
+  const a = Date.parse(ours);
+  const b = Date.parse(theirs);
+  if (Number.isNaN(a) || Number.isNaN(b)) return ours > theirs ? ours : theirs;
+  return a >= b ? ours : theirs;
+}
+
+/**
+ * Merge the envelope-level stamps (`$schema`, `kernelVersion`, and per-kind
+ * extras like `scoringSemantics`) by the same 3-way rule as rows. A double
+ * bump to different values is a genuine conflict — two branches disagreeing
+ * about which scorer produced the file.
+ *
+ * @param {object} base
+ * @param {object} ours
+ * @param {object} theirs
+ * @returns {{ merged: object, conflicts: Array<object> }}
+ */
+function mergeStamps(base, ours, theirs) {
+  const keys = new Set(
+    [...Object.keys(ours), ...Object.keys(theirs), ...Object.keys(base)].filter(
+      (k) => !DERIVED_KEYS.includes(k),
+    ),
+  );
+  const merged = {};
+  const conflicts = [];
+  for (const key of keys) {
+    const pick = choose(base[key], ours[key], theirs[key]);
+    if (pick.conflict) {
+      conflicts.push({
+        scope: 'envelope',
+        identity: key,
+        base: base[key],
+        ours: ours[key],
+        theirs: theirs[key],
+      });
+      merged[key] = ours[key];
+      continue;
+    }
+    if (pick.value !== undefined) merged[key] = pick.value;
+  }
+  return { merged, conflicts };
+}
+
+/**
+ * 3-way merge two baseline envelopes against their common ancestor.
+ *
+ * @param {{
+ *   base: object|null,
+ *   ours: object,
+ *   theirs: object,
+ *   kind?: string,
+ *   components?: Array<object>,
+ * }} params
+ *   - `base` — the merge ancestor; `null` (or a rowless object) when the
+ *     file was added on both sides.
+ *   - `components` — passed straight to the kind's `rollup()`. Defaults to
+ *     `[]`, which is what `refreshBaseline` effectively uses, so a merged
+ *     envelope carries the same `{'*': …}` rollup shape a refresh writes.
+ * @returns {{
+ *   kind: string,
+ *   envelope: object,
+ *   conflicts: Array<{scope: string, identity: string, base?: unknown, ours?: unknown, theirs?: unknown}>,
+ * }}
+ */
+export function mergeEnvelopes({
+  base,
+  ours,
+  theirs,
+  kind,
+  components = [],
+} = {}) {
+  const resolvedKind =
+    kind ?? kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
+  if (!resolvedKind) {
+    throw new Error(
+      'mergeEnvelopes: could not resolve a known baseline kind from the envelopes',
+    );
+  }
+  const mod = getKindModule(resolvedKind);
+  const baseEnv = base && typeof base === 'object' ? base : { rows: [] };
+
+  const baseRows = indexRows(baseEnv.rows, mod.rowIdentity, 'base');
+  const ourRows = indexRows(ours?.rows, mod.rowIdentity, 'ours');
+  const theirRows = indexRows(theirs?.rows, mod.rowIdentity, 'theirs');
+
+  const conflicts = [];
+  const rows = [];
+  const identities = new Set([
+    ...ourRows.keys(),
+    ...theirRows.keys(),
+    ...baseRows.keys(),
+  ]);
+  for (const id of identities) {
+    const b = baseRows.get(id);
+    const o = ourRows.get(id);
+    const t = theirRows.get(id);
+    const pick = choose(b, o, t);
+    if (pick.conflict) {
+      conflicts.push({
+        scope: 'row',
+        identity: id,
+        base: b,
+        ours: o,
+        theirs: t,
+      });
+      // Keep the ours-side value so the row set stays well-formed; the
+      // driver renders the conflict markers around it from this record.
+      if (o !== undefined) rows.push(o);
+      else if (t !== undefined) rows.push(t);
+      continue;
+    }
+    if (pick.value !== undefined) rows.push(pick.value);
+  }
+
+  const sortedRows = mod.sortRows(rows);
+  const { merged: stamps, conflicts: stampConflicts } = mergeStamps(
+    baseEnv,
+    ours ?? {},
+    theirs ?? {},
+  );
+
+  const envelope = {
+    ...stamps,
+    generatedAt: laterStamp(ours?.generatedAt, theirs?.generatedAt),
+    rollup: mod.rollup(sortedRows, components),
+    rows: sortedRows,
+  };
+
+  return {
+    kind: resolvedKind,
+    envelope,
+    conflicts: [...stampConflicts, ...conflicts],
+  };
+}

package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js

@@ -0,0 +1,175 @@
+/**
+ * bootstrap/baseline-merge-driver — register the `baselines/*.json` merge
+ * driver on a consumer clone (Story #5215).
+ *
+ * Registration has two halves that live in different places, and conflating
+ * them is why this needs a doctor check rather than just an installer:
+ *
+ *   1. **`.gitattributes`** says which files use the driver. It is a tracked
+ *      file, so installing the line once ships it to everyone.
+ *   2. **`git config merge.mandrel-baseline.driver`** says what the driver
+ *      actually is. Git deliberately keeps this out of tracked config —
+ *      otherwise a clone would execute a command chosen by whoever wrote the
+ *      repo — so it is **per clone**, and a fresh clone silently falls back
+ *      to git's text merge with no error at all.
+ *
+ * That silence is the whole reason `mandrel doctor` carries a check: an
+ * unregistered clone is not broken in any way it can report on its own, it
+ * just quietly goes back to conflicting (or worse, splicing) baselines.
+ *
+ * This module owns both halves plus the strings they share, so the installer
+ * and the doctor check cannot drift apart on the exact command.
+ *
+ * @module lib/bootstrap/baseline-merge-driver
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnCapture } from '../child-exec.js';
+
+/** Driver name, as it appears on both sides of the registration. */
+const BASELINE_MERGE_DRIVER_NAME = 'mandrel-baseline';
+
+/** The `.gitattributes` line that routes baselines through the driver. */
+const BASELINE_MERGE_ATTRIBUTE = `baselines/*.json merge=${BASELINE_MERGE_DRIVER_NAME}`;
+
+/** Git config key holding the driver command. */
+export const BASELINE_MERGE_DRIVER_CONFIG_KEY = `merge.${BASELINE_MERGE_DRIVER_NAME}.driver`;
+
+/**
+ * The driver command. Relative to the worktree root, which is where git runs
+ * a merge driver from, and where `mandrel sync` materializes `.agents/`.
+ */
+const BASELINE_MERGE_DRIVER_COMMAND =
+  'node .agents/scripts/merge-baseline.js %O %A %B %P';
+
+/** The exact command an operator runs to complete registration. */
+export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_CONFIG_KEY} "${BASELINE_MERGE_DRIVER_COMMAND}"`;
+
+/**
+ * Does this `.gitattributes` content route baselines through the driver?
+ * Comment lines do not count — a commented-out registration is not one.
+ *
+ * @param {string|null|undefined} gitattributes
+ * @returns {boolean}
+ */
+export function declaresBaselineMergeDriver(gitattributes) {
+  return String(gitattributes ?? '')
+    .split('\n')
+    .some((line) => {
+      const trimmed = line.trim();
+      if (trimmed === '' || trimmed.startsWith('#')) return false;
+      return trimmed.includes(`merge=${BASELINE_MERGE_DRIVER_NAME}`);
+    });
+}
+
+/**
+ * Add the attribute line, preserving every existing line verbatim.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} [fsImpl]
+ * @returns {{ action: 'created'|'appended'|'already-present', path: string }}
+ */
+function ensureGitattributesLine(projectRoot, fsImpl = fs) {
+  const target = path.join(projectRoot, '.gitattributes');
+  if (!fsImpl.existsSync(target)) {
+    fsImpl.writeFileSync(target, `${BASELINE_MERGE_ATTRIBUTE}\n`, 'utf8');
+    return { action: 'created', path: target };
+  }
+  const existing = fsImpl.readFileSync(target, 'utf8');
+  if (declaresBaselineMergeDriver(existing)) {
+    return { action: 'already-present', path: target };
+  }
+  // A file not ending in a newline would otherwise glue our line onto the
+  // last existing one, silently rewriting it.
+  const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
+  fsImpl.writeFileSync(
+    target,
+    `${existing}${separator}${BASELINE_MERGE_ATTRIBUTE}\n`,
+    'utf8',
+  );
+  return { action: 'appended', path: target };
+}
+
+/**
+ * Point `merge.mandrel-baseline.driver` at the driver in THIS clone.
+ *
+ * @param {string} projectRoot
+ * @param {typeof spawnCapture} [spawnImpl]
+ * @returns {{ action: 'set'|'already-present'|'not-a-repo'|'failed' }}
+ */
+function ensureDriverGitConfig(projectRoot, spawnImpl = spawnCapture) {
+  const opts = {
+    cwd: projectRoot,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: false,
+  };
+  const inRepo = spawnImpl('git', ['rev-parse', '--git-dir'], opts);
+  if ((inRepo?.status ?? 1) !== 0) return { action: 'not-a-repo' };
+
+  const current = spawnImpl(
+    'git',
+    ['config', '--local', '--get', BASELINE_MERGE_DRIVER_CONFIG_KEY],
+    opts,
+  );
+  if (
+    (current?.status ?? 1) === 0 &&
+    String(current.stdout ?? '').trim() === BASELINE_MERGE_DRIVER_COMMAND
+  ) {
+    return { action: 'already-present' };
+  }
+
+  const set = spawnImpl(
+    'git',
+    [
+      'config',
+      '--local',
+      BASELINE_MERGE_DRIVER_CONFIG_KEY,
+      BASELINE_MERGE_DRIVER_COMMAND,
+    ],
+    opts,
+  );
+  spawnImpl(
+    'git',
+    [
+      'config',
+      '--local',
+      `merge.${BASELINE_MERGE_DRIVER_NAME}.name`,
+      'mandrel baseline merge by row identity',
+    ],
+    opts,
+  );
+  return { action: (set?.status ?? 1) === 0 ? 'set' : 'failed' };
+}
+
+/**
+ * Install both halves. Idempotent: a second run reports `already-present`
+ * and changes no bytes.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {typeof spawnCapture} [ctx.spawnImpl]
+ * @param {typeof fs} [ctx.fsImpl]
+ * @returns {{
+ *   action: 'already-present'|'updated',
+ *   attributes: string,
+ *   config: string,
+ *   path: string,
+ *   line: string,
+ * }}
+ */
+export function ensureBaselineMergeDriver(ctx) {
+  const attributes = ensureGitattributesLine(ctx.projectRoot, ctx.fsImpl ?? fs);
+  const config = ensureDriverGitConfig(ctx.projectRoot, ctx.spawnImpl);
+  const settled =
+    attributes.action === 'already-present' &&
+    (config.action === 'already-present' || config.action === 'not-a-repo');
+  return {
+    action: settled ? 'already-present' : 'updated',
+    attributes: attributes.action,
+    config: config.action,
+    path: attributes.path,
+    line: BASELINE_MERGE_ATTRIBUTE,
+  };
+}

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -15,7 +15,11 @@
  *   4. Seeds `delivery.quality.codingGuardrails` and
  *      `delivery.quality.autoRefresh` defaults in `.agentrc.json` when
  *      the keys are absent. Existing values are preserved.
- *   5. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
+ *   5. Registers the `baselines/*.json` merge driver (Story #5215) — the
+ *      `.gitattributes` line plus this clone's `merge.mandrel-baseline.driver`
+ *      config, so concurrent baseline refreshes merge by row identity instead
+ *      of conflicting on the `generatedAt` stamp.
+ *   6. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
  *      v2 model is Story-only — nothing writes, reads, or reaps per-Epic
  *      ratchet snapshots — so an upgrading consumer is left carrying a
  *      committed directory no gate consults. Absent on every repo that never
@@ -35,6 +39,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getAgentrcDefaults, lookupPath } from '../config/defaults.js';
 import { deepEqual } from '../json-utils.js';
+import { ensureBaselineMergeDriver } from './baseline-merge-driver.js';
 
 /**
  * The exact pre-commit body the framework ships. Kept as a single string so
@@ -407,7 +412,7 @@ export function pruneLegacyEpicBaselines(ctx) {
 }
 
 /**
- * Run all five steps in order. Composable wrapper used by the bootstrap
+ * Run all six steps in order. Composable wrapper used by the bootstrap
  * and update workflows. Each step's outcome is returned under its own key
  * so callers can render a per-action summary.
  *
@@ -423,6 +428,7 @@ export function applyQualityBootstrap(ctx) {
     hook: ensurePreCommitHook(ctx),
     scripts: ensureQualityNpmScripts(ctx),
     config: ensureQualityConfigDefaults(ctx),
+    mergeDriver: ensureBaselineMergeDriver(ctx),
     legacyBaselines: pruneLegacyEpicBaselines(ctx),
   };
 }

package/.agents/scripts/lib/observability/source-classifier.js

@@ -121,6 +121,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'lint-issue-body.js',
   'lint-label-vocabulary.js',
   'mandrel-update-preflight.js',
+  'merge-baseline.js',
   'nav-registry-diff.js',
   'notify.js',
   'plan-context.js',

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

@@ -33,23 +33,35 @@
 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.
+ * The checklist grammar: a checklist row, and the **first** issue reference
+ * anywhere on it. 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 rate-limit burst) the
+ * children are still discoverable from the body alone.
+ *
+ * Deliberately the **loosest** of the three grammars that read this shape, and
+ * looser than it was: it used to require the id to be the whole row
+ * (`- [ ] #123`), which matched none of the annotated rows a hand-maintained
+ * rollout tracker actually carries — `- [ ] Design sign-off (#1897): pending`,
+ * `- [ ] 1.4 #1909 (Part B blocked)`. An Epic with 58 children presented three
+ * to the rollup, which closed it with 23 still open (Story #5210).
+ *
+ * It is NOT in sync with `_getChecklistChildren` (`providers/github/issues.js`)
+ * and no longer claims to be: that one is a general parent→child strategy for
+ * any issue and still requires `#N` immediately after the checkbox. Reading a
+ * superset here is safe in the direction that matters — a spurious id costs a
+ * skipped non-Story child, while a missed id costs a container closed over open
+ * work. The union with the native edges keeps both honest, and after #5210
+ * nothing irreversible is decided on this grammar alone.
  */
-const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+#(\d+)\s*$/gm;
+const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+.*?#(\d+)\b/gm;
 
 /**
  * The same grammar, unanchored to a global cursor — for callers testing one
- * line at a time. Kept beside its `/g` twin so the two cannot drift.
+ * line at a time. Kept beside its `/g` twin so the two cannot drift; the pair
+ * MUST accept the same line set, which `epic-container.test.js` pins.
  */
-export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+#\d+\s*$/;
+export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+.*?#\d+\b/;
 
 /** Heading the container's one prose section renders under. */
 const GOAL_HEADING = '## Goal';
@@ -180,12 +192,23 @@ export function readEpicChildIds(body) {
  * degrades to the checklist rather than propagating, since a body-derived
  * child list is a strictly better answer than an error.
  *
+ * **The degrade is reported, not hidden.** The result carries
+ * `nativeReadFailed`, because a truncated list and a genuinely small Epic are
+ * otherwise indistinguishable downstream — and one caller
+ * (`epic-rollup.js`) decides an irreversible close on the difference. A caller
+ * that only needs "who are the children" reads `ids` and ignores the flag;
+ * a caller about to do something it cannot undo MUST NOT.
+ *
+ * `nativeReadFailed` is false when no reader was injected: a caller that
+ * supplied none never asked for authority and is not degraded relative to what
+ * it requested.
+ *
  * @param {{
  *   epic: { number?: number, id?: number, body?: string, nodeId?: string },
  *   readNativeChildIds?: (epic: object) => Promise<number[]>,
  *   onWarn?: (message: string) => void,
  * }} opts
- * @returns {Promise<number[]>}
+ * @returns {Promise<{ ids: number[], nativeReadFailed: boolean }>}
  */
 export async function readEpicChildIdsFrom({
   epic,
@@ -193,18 +216,22 @@ export async function readEpicChildIdsFrom({
   onWarn,
 } = {}) {
   const fromBody = readEpicChildIds(epic?.body);
-  if (typeof readNativeChildIds !== 'function') return fromBody;
+  if (typeof readNativeChildIds !== 'function') {
+    return { ids: fromBody, nativeReadFailed: false };
+  }
 
-  let native = [];
   try {
-    native = normalizeChildIds(await readNativeChildIds(epic));
+    const native = normalizeChildIds(await readNativeChildIds(epic));
+    return {
+      ids: normalizeChildIds([...native, ...fromBody]),
+      nativeReadFailed: false,
+    };
   } 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.`,
+      `[epic-container] native sub-issue read failed for Epic ` +
+        `#${epic?.number ?? epic?.id ?? '?'} (${err?.message ?? String(err)}); ` +
+        'using the body checklist alone — the child list may be incomplete.',
     );
+    return { ids: fromBody, nativeReadFailed: true };
   }
-
-  return normalizeChildIds([...native, ...fromBody]);
 }

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

@@ -27,6 +27,32 @@ function isStoryTicket(issue) {
     .includes(TYPE_LABELS.STORY);
 }
 
+/**
+ * The error for an Epic that yielded no children.
+ *
+ * The two empty cases have different remedies, so they get different messages:
+ * an operator told to go link Stories that are already linked will do the wrong
+ * thing for what was really a transient API failure (Story #5210).
+ *
+ * @param {number} id
+ * @param {boolean} nativeReadFailed
+ * @returns {Error}
+ */
+function noChildrenError(id, nativeReadFailed) {
+  if (nativeReadFailed) {
+    return new Error(
+      `[resolve-stories] Epic #${id} expanded to no child Stories, but the ` +
+        `native sub-issue read failed — the list is incomplete, not empty. ` +
+        `Re-run once the GitHub API read succeeds.`,
+    );
+  }
+  return 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.`,
+  );
+}
+
 /**
  * Expand any container-Epic id in the requested set to its open child
  * Stories, leaving every other id untouched.
@@ -90,17 +116,13 @@ export async function expandEpicIds({
       continue;
     }
 
-    const childIds = await readEpicChildIdsFrom({
+    const { ids: childIds, nativeReadFailed } = 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.`,
-      );
+      throw noChildrenError(id, nativeReadFailed);
     }
 
     const open = [];