mandrel 2.46.0 → 2.48.0

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/merge-baseline.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * merge-baseline.js — git merge driver for `baselines/*.json` (Story #5215).
+ *
+ * ## The failure it replaces
+ *
+ * Every baseline write stamps `generatedAt` on line 4, so two branches that
+ * each refresh a baseline ALWAYS differ there — even when they moved
+ * completely disjoint rows. Git merges JSON as text, so whether it can
+ * separate that hunk from the moved rows is an accident of proximity:
+ *
+ *   - it cannot → a conflict on work that never overlapped (the observed
+ *     `coverage.json` / `maintainability.json` "always conflicts" pattern);
+ *   - it can → it splices both sides' row lines into a row set neither side
+ *     scored, and the ratchet then guards a number no scorer produced (the
+ *     observed `crap.json` "silently auto-merges" pattern).
+ *
+ * The quiet one is the worse one. A baseline is a set of rows keyed by
+ * identity plus a rollup derived from them, so this driver merges it as
+ * that — see `lib/baselines/merge-envelopes.js` for the semantics.
+ *
+ * ## Contract
+ *
+ *   node .agents/scripts/merge-baseline.js %O %A %B %P
+ *
+ * git's merge-driver calling convention: `%O` ancestor, `%A` ours (and the
+ * file the driver MUST leave its result in), `%B` theirs, `%P` the real
+ * pathname being merged. Exit 0 merged clean, non-zero conflicted.
+ *
+ * Registered per clone (registration is per-clone, so `mandrel doctor` is
+ * the guard that it happened, not `mandrel sync`):
+ *
+ *   .gitattributes:  baselines/*.json merge=mandrel-baseline
+ *   git config:      merge.mandrel-baseline.driver
+ *
+ * ## Not every `baselines/*.json` is an envelope
+ *
+ * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger,
+ * context-budget and workflow-citations — files with their own shapes and no
+ * row identity. Anything whose `$schema` is not a known per-kind envelope is
+ * handed straight back to `git merge-file`, so registering the driver cannot
+ * change their behaviour.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertEnvelope } from './lib/baselines/envelope.js';
+import {
+  kindFromEnvelope,
+  mergeEnvelopes,
+} from './lib/baselines/merge-envelopes.js';
+import { writeFile as writeEnvelopeFile } from './lib/baselines/writer.js';
+import { spawnChild } from './lib/child-exec.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+/** Indent one row's canonical JSON to its position inside `rows`. */
+function rowBlock(row) {
+  return JSON.stringify(row, null, 2)
+    .split('\n')
+    .map((line) => `    ${line}`)
+    .join('\n');
+}
+
+/**
+ * Wrap each conflicting row in git conflict markers, leaving every other row
+ * merged. Operates on the canonical text the writer already produced, so the
+ * non-conflicting remainder of the file is byte-identical to what a clean
+ * merge would have written.
+ *
+ * @param {string} text Canonical serialization of the merged envelope.
+ * @param {Array<object>} conflicts Row-scoped conflict records.
+ * @returns {string}
+ */
+export function renderConflictMarkers(text, conflicts) {
+  let out = text;
+  for (const conflict of conflicts) {
+    const placed = conflict.ours ?? conflict.theirs;
+    if (placed === undefined) continue;
+    const block = rowBlock(placed);
+    // The row may or may not be the last element of `rows`; keep whichever
+    // separator follows it on both sides so the markers wrap whole lines.
+    const withComma = `${block},`;
+    const [needle, suffix] = out.includes(withComma)
+      ? [withComma, ',']
+      : [block, ''];
+    if (!out.includes(needle)) continue;
+    const ourSide =
+      conflict.ours === undefined
+        ? ''
+        : `${rowBlock(conflict.ours)}${suffix}\n`;
+    const theirSide =
+      conflict.theirs === undefined
+        ? ''
+        : `${rowBlock(conflict.theirs)}${suffix}\n`;
+    out = out.replace(
+      needle,
+      `<<<<<<< ours\n${ourSide}=======\n${theirSide}>>>>>>> theirs`.replace(
+        /\n$/,
+        '',
+      ),
+    );
+  }
+  return out;
+}
+
+/** Read and parse a merge input; a missing or empty side is `null`. */
+function readSide(file) {
+  if (!file || !fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf8');
+  if (raw.trim() === '') return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined; // present but unparseable — caller falls back to git
+  }
+}
+
+/**
+ * Hand the merge back to git's own text merge. Used for every
+ * `baselines/*.json` that is not a known per-kind envelope, and for one that
+ * is too damaged to parse — in both cases the driver must not invent a
+ * result, and git's behaviour is exactly what the repo had before.
+ *
+ * @returns {number} git merge-file's own exit code.
+ */
+function delegateToGit(basePath, oursPath, theirsPath) {
+  // `stdio: 'inherit'` so git's own conflict reporting reaches the operator
+  // exactly as it would have with no driver registered. `spawnChild` returns
+  // the RAW result deliberately: a `status` of null means the child was
+  // killed, and that must never be read as a clean merge.
+  const result = spawnChild(
+    'git',
+    ['merge-file', oursPath, basePath, theirsPath],
+    { stdio: 'inherit' },
+  );
+  if (result.error) {
+    process.stderr.write(
+      `merge-baseline: could not run git merge-file: ${result.error.message}\n`,
+    );
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+/**
+ * @param {string[]} argv Positional arguments: %O %A %B [%P].
+ * @returns {number} Process exit code.
+ */
+export function runMergeBaseline(argv) {
+  const [baseArg, oursArg, theirsArg, mergedPath] = argv;
+  if (!baseArg || !oursArg || !theirsArg) {
+    process.stderr.write(
+      'merge-baseline: expected the git merge-driver arguments %O %A %B %P\n',
+    );
+    return 2;
+  }
+
+  // Git hands the driver temp filenames RELATIVE to the worktree root it
+  // invokes us from (`.merge_file_xxxxxx`), so every path is resolved before
+  // use — the shared writer refuses a relative path, and that refusal only
+  // shows up under a real `git merge`, never when the driver is called
+  // directly with absolute paths.
+  const [basePath, oursPath, theirsPath] = [baseArg, oursArg, theirsArg].map(
+    (p) => path.resolve(p),
+  );
+
+  const ours = readSide(oursPath);
+  const theirs = readSide(theirsPath);
+  const base = readSide(basePath);
+
+  const kind = kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
+  if (!kind || ours === undefined || theirs === undefined) {
+    return delegateToGit(basePath, oursPath, theirsPath);
+  }
+
+  let merged;
+  try {
+    merged = mergeEnvelopes({ base, ours, theirs, kind });
+  } catch (err) {
+    process.stderr.write(`merge-baseline: ${kind}: ${err.message}\n`);
+    return delegateToGit(basePath, oursPath, theirsPath);
+  }
+
+  const rowConflicts = merged.conflicts.filter((c) => c.scope === 'row');
+  const envelopeConflicts = merged.conflicts.filter(
+    (c) => c.scope === 'envelope',
+  );
+
+  // Write the canonical projection first even when conflicted: the marker
+  // rendering operates on exactly the bytes a clean merge would have left,
+  // so the merged remainder of a conflicted file is identical to it.
+  writeEnvelopeFile(oursPath, merged.envelope);
+
+  if (merged.conflicts.length === 0) {
+    assertEnvelope(merged.envelope);
+    return 0;
+  }
+
+  const label = mergedPath || oursPath;
+  for (const conflict of envelopeConflicts) {
+    process.stderr.write(
+      `merge-baseline: conflict ${kind} envelope key "${conflict.identity}" in ${label} — ours ${JSON.stringify(conflict.ours)}, theirs ${JSON.stringify(conflict.theirs)}\n`,
+    );
+  }
+  for (const conflict of rowConflicts) {
+    process.stderr.write(
+      `merge-baseline: conflict ${kind} row "${conflict.identity}" in ${label}\n`,
+    );
+  }
+
+  if (rowConflicts.length > 0) {
+    const text = fs.readFileSync(oursPath, 'utf8');
+    fs.writeFileSync(oursPath, renderConflictMarkers(text, rowConflicts));
+  }
+  return 1;
+}
+
+function main() {
+  return runMergeBaseline(process.argv.slice(2));
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'merge-baseline',
+  propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/merge-baseline.js %O %A %B %P',
+    summary:
+      'Git merge driver for baselines/*.json. Merges per-kind envelopes by ROW IDENTITY — disjoint refreshes merge clean, the rollup is recomputed from the merged rows, and generatedAt resolves to the later stamp instead of conflicting. A baselines file that is not a known per-kind envelope is handed back to git merge-file unchanged. Exit 0 clean, 1 conflicted.',
+    flags: [
+      ['%O', 'Merge ancestor (git supplies this).'],
+      ['%A', 'Our version — the driver writes its result here.'],
+      ['%B', 'Their version.'],
+      ['%P', 'Real pathname being merged; used in conflict messages.'],
+    ],
+  },
+});

package/.agents/scripts/providers/github/errors.js

@@ -87,17 +87,67 @@ function matchesAny(haystack, needles) {
   return false;
 }
 
+/** `gh` renders the HTTP status onto stderr as `HTTP 403: <reason>`. */
+const GH_STDERR_STATUS_RE = /\bHTTP (\d{3})\b/i;
+
+/**
+ * The captured `gh` stderr, or `''` when the error carries none.
+ *
+ * Its own function so {@link extractErrorFields} keeps the cyclomatic weight it
+ * had before stderr became a classification input — the field is read twice
+ * there, and inlining the guard twice is what pushed the CRAP ratchet.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function stderrText(err) {
+  return typeof err?.stderr === 'string' ? err.stderr : '';
+}
+
 /**
- * Extract `{ lower, status, code }` from an error in the shape `gh-exec`
- * throws. Pure — exported style for unit-testability without instantiating
- * the provider. Defensive on shape: errors arrive as `Error` objects, plain
- * `{message,status,code}` bags, or non-Errors stringified into `String(err)`.
+ * Recover the HTTP status from a `gh`-CLI failure's stderr.
+ *
+ * The `fetch` transport sets `err.status`; the `gh` transport does not — it
+ * has only an exit code, and puts the status in the text it printed. Without
+ * this, every `gh`-path failure reached the status rules as `undefined` and a
+ * 403 or a 429 was indistinguishable from an unclassifiable error (Story
+ * #5210).
+ *
+ * @param {unknown} stderr
+ * @returns {number|undefined}
+ */
+function statusFromStderr(stderr) {
+  if (typeof stderr !== 'string') return undefined;
+  const m = GH_STDERR_STATUS_RE.exec(stderr);
+  return m ? Number.parseInt(m[1], 10) : undefined;
+}
+
+/**
+ * Extract `{ lower, detail, status, code }` from an error in the shape
+ * `gh-exec` throws. Pure — exported style for unit-testability without
+ * instantiating the provider. Defensive on shape: errors arrive as `Error`
+ * objects, plain `{message,status,code}` bags, or non-Errors stringified into
+ * `String(err)`.
+ *
+ * `lower` is the message alone. `detail` is the message **plus** any captured
+ * `stderr`, and is what the keyword rules read: on the `gh` path the message
+ * is the classified summary (`gh-exec: gh exited with code 1`) and every
+ * actionable word — the status line, `secondary rate limit`, the missing
+ * GraphQL field — lives only on stderr. Matching the keyword lists against the
+ * message alone is what flattened a retryable 403 to `permanent` and let the
+ * Epic rollup treat a rate-limit burst as a settled answer (Story #5210).
  */
 export function extractErrorFields(err) {
   const message = typeof err.message === 'string' ? err.message : String(err);
+  const stderr = stderrText(err);
+  const lower = message.toLowerCase();
   return {
-    lower: message.toLowerCase(),
-    status: typeof err.status === 'number' ? err.status : undefined,
+    lower,
+    // Unconditional concatenation: with no stderr this is the message plus a
+    // trailing space, which every `includes` rule below reads identically.
+    detail: `${lower} ${stderr.toLowerCase()}`,
+    status:
+      typeof err.status === 'number' ? err.status : statusFromStderr(stderr),
     code: typeof err.code === 'string' ? err.code : undefined,
   };
 }
@@ -127,17 +177,23 @@ export function classifyGithubError(err) {
   // no `.status` / `.code`. Match by `err.name` to avoid a circular import
   // between this module and `lib/gh-exec.js`. Story #2860.
   if (err.name === 'GhExecTimeoutError') return 'transient';
-  const { lower, status, code } = extractErrorFields(err);
-  if (matchesAny(lower, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
+  // Every keyword rule below reads `detail` (message + stderr), never `lower`
+  // alone: the `gh` transport carries its reason exclusively on stderr, so a
+  // message-only match sees nothing but the exit code. Rule ORDER is
+  // load-bearing and unchanged — a secondary rate limit is delivered as HTTP
+  // 403, so the transient rules must stay ahead of the permission rule or it
+  // would bucket as 'permission' and never retry.
+  const { detail, status, code } = extractErrorFields(err);
+  if (matchesAny(detail, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
   if (isTransientStatus(status)) return 'transient';
-  if (isTransientByCodeOrMessage(code, lower)) return 'transient';
+  if (isTransientByCodeOrMessage(code, detail)) return 'transient';
   // Union with the former `transient-retry.js` predicate (Story #4298):
   // retry on network/connectivity blips the status/code checks above miss
   // (e.g. a `dial tcp ... i/o timeout` on `err.stderr` from the gh-CLI path,
   // or `ECONNREFUSED` / `ENETUNREACH`). Checked before the permission rule so
   // a transient network failure never masquerades as a permanent denial.
   if (isTransientNetworkError(err)) return 'transient';
-  if (isPermissionSignal(status, lower)) return 'permission';
+  if (isPermissionSignal(status, detail)) return 'permission';
   return 'permanent';
 }
 

package/.agents/scripts/providers/github/sub-issues.js

@@ -23,6 +23,7 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { describeGhFailure } from '../../lib/gh-exec.js';
 import { Logger } from '../../lib/Logger.js';
 import {
   classifyGithubError as defaultClassifyGithubError,
@@ -104,8 +105,14 @@ export class SubIssueGateway {
         );
         return [];
       }
+      // `describeGhFailure`, not `err.message`: on the gh transport the
+      // message is only the classified summary (`gh exited with code 1`) and
+      // the actionable sentence — the HTTP status, the rate-limit notice — is
+      // on stderr. Three identical opaque lines are what made the Epic-rollup
+      // incident unreadable until the API was queried by hand (Story #5210).
       Logger.error(
-        `[GitHubProvider] sub-issues GraphQL failed (parent #${parentId}, category=${category}): ${err.message}`,
+        `[GitHubProvider] sub-issues GraphQL failed (parent #${parentId}, ` +
+          `category=${category}): ${describeGhFailure(err)}`,
       );
       throw err;
     }