mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -71,7 +71,11 @@
  * (`emit-merge-unlanded.js`).
  */
 
-import { requiredCheckFailedBlocksMerge } from './merge-poll.js';
+import {
+  ADVISORY_GATE_INCONCLUSIVE_CLASS,
+  ADVISORY_GATE_RED_CLASS,
+  requiredCheckFailedBlocksMerge,
+} from './merge-poll.js';
 
 /**
  * Every class `classifyMergeBlock` can return. Order is the evaluation
@@ -102,7 +106,14 @@ export const BLOCK_CLASSES = Object.freeze([
  * (`mergeStateStatus: UNSTABLE`), which native auto-merge would land straight
  * past. It is emitted directly by the arm and merge-wait phases — the
  * classifier cannot produce it, because by construction GitHub is NOT blocking
- * the merge, which is the entire problem it names. It is deliberately NOT in
+ * the merge, which is the entire problem it names. Story #5266 added
+ * `advisory-gate-inconclusive` beside it, emitted directly by the same two
+ * phases and under the same discipline: the SAME observation (a red advisory
+ * run on an `UNSTABLE` PR) whose run never FINISHED — a scan or navigation
+ * timeout reporting no violation. It blocks exactly as `advisory-gate-red`
+ * does; it exists because the two authorise different remedies, and reporting
+ * a timed-out scan as a found violation pushes the operator toward a permanent
+ * allowlist exemption for a transient failure. It is deliberately NOT in
  * `BLOCK_CLASSES`, whose reachability invariant covers only what
  * `classifyMergeBlock` returns. (The Epic-era listeners that used to
  * emit it, AutomergePredicate and AutomergeArmer, are gone; the value stays
@@ -114,7 +125,11 @@ export const BLOCK_CLASSES = Object.freeze([
 export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
   ...BLOCK_CLASSES,
   'predicate-refused',
-  'advisory-gate-red',
+  // Sourced from the constants the advisory gate itself decides with
+  // (Story #5266), so the attribution vocabulary cannot drift from the
+  // verdict that emits it.
+  ADVISORY_GATE_RED_CLASS,
+  ADVISORY_GATE_INCONCLUSIVE_CLASS,
 ]);
 
 const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);

package/.agents/scripts/lib/orchestration/merge-poll.js

@@ -113,6 +113,50 @@ export function deriveChecksStatus(statusCheckRollup) {
  * @param {Array<{status?: string, conclusion?: string, state?: string}>} statusCheckRollup
  * @returns {{ requiredRunFailed: boolean, requiredRunInFlight: boolean } | null}
  */
+/**
+ * Pure: the uppercase conclusion of a check that GENUINELY concluded red, or
+ * `null` when it did not.
+ *
+ * Red means `FAILURE` / `ERROR` only — never `CANCELLED` / `TIMED_OUT` /
+ * `SKIPPED`, which are the superseded-push and sibling-invalidated runs a bare
+ * rollup read miscounts (the #4695 / #4710 trap). A CheckRun carries the
+ * verdict on `conclusion`; a legacy StatusContext carries it on `state`, so
+ * both are read and the one that is red is the one returned.
+ *
+ * Extracted (Story #5266) because {@link deriveRequiredRunEvidence} and
+ * {@link deriveRedHeadRuns} were carrying byte-identical copies of this test:
+ * two places that must agree about what "red" means, and nothing making them.
+ *
+ * @param {{ conclusion?: string, state?: string }} [check]
+ * @returns {string|null}
+ */
+function redConclusionOf(check) {
+  const conclusion = String(check?.conclusion ?? '').toUpperCase();
+  if (conclusion === 'FAILURE' || conclusion === 'ERROR') return conclusion;
+  const state = String(check?.state ?? '').toUpperCase();
+  if (state === 'FAILURE' || state === 'ERROR') return state;
+  return null;
+}
+
+/**
+ * Pure: a check's display name — the CheckRun's `name`, falling back to a
+ * legacy StatusContext's `context`, and `null` when the projection carries
+ * neither.
+ *
+ * A run with no readable name can never match an allowlist entry, so it always
+ * blocks. That is the conservative direction for a gate whose whole purpose is
+ * to stop a silent landing.
+ *
+ * @param {{ name?: string, context?: string }} [check]
+ * @returns {string|null}
+ */
+function readRunName(check) {
+  for (const value of [check?.name, check?.context]) {
+    if (typeof value === 'string' && value) return value;
+  }
+  return null;
+}
+
 export function deriveRequiredRunEvidence(statusCheckRollup) {
   if (!Array.isArray(statusCheckRollup) || statusCheckRollup.length === 0) {
     return null;
@@ -120,7 +164,6 @@ export function deriveRequiredRunEvidence(statusCheckRollup) {
   let requiredRunFailed = false;
   let requiredRunInFlight = false;
   for (const check of statusCheckRollup) {
-    const conclusion = String(check?.conclusion ?? '').toUpperCase();
     const status = String(check?.status ?? '').toUpperCase();
     const state = String(check?.state ?? '').toUpperCase();
     // In flight: a CheckRun not yet COMPLETED, or a legacy StatusContext still
@@ -131,14 +174,7 @@ export function deriveRequiredRunEvidence(statusCheckRollup) {
     } else if (state === 'PENDING' || state === 'EXPECTED') {
       requiredRunInFlight = true;
     }
-    // Genuinely red: FAILURE / ERROR only. CANCELLED / TIMED_OUT / SKIPPED are
-    // the superseded / sibling-invalidated noise a bare rollup miscounts.
-    if (
-      conclusion === 'FAILURE' ||
-      conclusion === 'ERROR' ||
-      state === 'FAILURE' ||
-      state === 'ERROR'
-    ) {
+    if (redConclusionOf(check)) {
       requiredRunFailed = true;
     }
   }
@@ -256,6 +292,47 @@ export function requiredCheckFailedBlocksMerge(prProbe) {
  */
 const MERGE_ADVISORY_STATE = 'UNSTABLE';
 
+/**
+ * The fields a check projection can use to say, in its own words, WHY it went
+ * red. A legacy StatusContext carries `description`; a GitHub Actions CheckRun
+ * carries none of them in `gh pr view`'s fixed `statusCheckRollup` projection,
+ * so the merge wait enriches the run with the check-run API's
+ * `output.title` / `output.summary` before classifying (Story #5266). Both
+ * shapes are read here so the projection has ONE text extractor.
+ *
+ * @param {object} [check] A rollup entry, or an enriched check-run record.
+ * @returns {string|undefined} The joined text, or `undefined` when the record
+ *   carries none — which is itself the signal that the run cannot be
+ *   classified beyond "red".
+ */
+export function readRunSummary(check) {
+  const parts = [];
+  for (const field of ['description', 'title', 'summary', 'text']) {
+    for (const value of [check?.[field], check?.output?.[field]]) {
+      if (typeof value === 'string' && value.trim()) parts.push(value.trim());
+    }
+  }
+  return parts.length > 0 ? parts.join(' — ') : undefined;
+}
+
+/**
+ * Pure: the workflow run id behind a check run's `detailsUrl`
+ * (`.../actions/runs/<runId>/job/<jobId>`), or `null` when the URL is absent
+ * or shaped otherwise (a legacy StatusContext's `targetUrl`, a third-party
+ * app's own page). A run with no id can never be re-run, which is why the
+ * rerun path treats `null` as "nothing to re-run" rather than an error.
+ *
+ * @param {string} [detailsUrl]
+ * @returns {number|null}
+ */
+export function parseWorkflowRunId(detailsUrl) {
+  if (typeof detailsUrl !== 'string') return null;
+  const match = /\/actions\/runs\/(\d+)/.exec(detailsUrl);
+  if (!match) return null;
+  const id = Number.parseInt(match[1], 10);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
 /**
  * Pure: project the HEAD-ANCHORED runs that genuinely concluded red, naming
  * each one (Story #5096).
@@ -273,28 +350,36 @@ const MERGE_ADVISORY_STATE = 'UNSTABLE';
  * conservative direction for a gate whose whole purpose is to stop a silent
  * landing.
  *
- * @param {Array<{name?: string, context?: string, status?: string, conclusion?: string, state?: string}>} statusCheckRollup
- * @returns {Array<{ name: string|null, conclusion: string }>}
+ * **Widened by Story #5266** from `{name, conclusion}` to carry what a red run
+ * is classified and acted on by: `summary` (the run's own account of why it
+ * failed — see {@link readRunSummary}), `runId` (the workflow run behind it,
+ * so a rerun can be requested), and `completedAt` (the observation stamp that
+ * tells a re-run's verdict apart from the stale pre-rerun one). Every added
+ * field is OMITTED when the projection carries no value for it, so a run the
+ * rollup describes as thinly as before still projects to exactly the old two
+ * keys — and a thin run classifies as a violation, i.e. the pre-#5266 verdict.
+ *
+ * @param {Array<{name?: string, context?: string, status?: string, conclusion?: string, state?: string, detailsUrl?: string, completedAt?: string, description?: string, output?: object}>} statusCheckRollup
+ * @returns {Array<{ name: string|null, conclusion: string, summary?: string, runId?: number, completedAt?: string }>}
  */
 export function deriveRedHeadRuns(statusCheckRollup) {
   if (!Array.isArray(statusCheckRollup)) return [];
   const red = [];
   for (const check of statusCheckRollup) {
-    const conclusion = String(check?.conclusion ?? '').toUpperCase();
-    const state = String(check?.state ?? '').toUpperCase();
-    const isRed =
-      conclusion === 'FAILURE' ||
-      conclusion === 'ERROR' ||
-      state === 'FAILURE' ||
-      state === 'ERROR';
-    if (!isRed) continue;
-    const name =
-      typeof check?.name === 'string' && check.name
-        ? check.name
-        : typeof check?.context === 'string' && check.context
-          ? check.context
-          : null;
-    red.push({ name, conclusion: conclusion || state });
+    const conclusion = redConclusionOf(check);
+    if (!conclusion) continue;
+    const summary = readRunSummary(check);
+    const runId = parseWorkflowRunId(check?.detailsUrl);
+    const completedAt = check?.completedAt;
+    red.push({
+      name: readRunName(check),
+      conclusion,
+      ...(summary ? { summary } : {}),
+      ...(runId ? { runId } : {}),
+      ...(typeof completedAt === 'string' && completedAt
+        ? { completedAt }
+        : {}),
+    });
   }
   return red;
 }
@@ -353,6 +438,130 @@ export function advisoryCheckFailedBlocksArm(prProbe, allowlist = []) {
   return selectBlockingRedRuns(prProbe?.redHeadRuns, allowlist).length > 0;
 }
 
+/**
+ * The two advisory-gate block classes (Story #5266). Both BLOCK — the gate's
+ * verdict on whether to land is unchanged — but they authorise different acts,
+ * which is the whole reason they are two:
+ *
+ *   - `advisory-gate-red`          A red advisory run that REPORTED a
+ *                                   violation. The change is implicated;
+ *                                   landing over it is a deliberate override.
+ *   - `advisory-gate-inconclusive` A red advisory run that never finished — a
+ *                                   scan or navigation timeout that reported
+ *                                   no violation at all. Nothing here says the
+ *                                   change is bad, so the proportionate remedy
+ *                                   is to re-run the job, not to grant the
+ *                                   permanent global exemption
+ *                                   `advisoryAllowlist` is.
+ */
+export const ADVISORY_GATE_RED_CLASS = 'advisory-gate-red';
+export const ADVISORY_GATE_INCONCLUSIVE_CLASS = 'advisory-gate-inconclusive';
+
+/**
+ * Text signatures of a run that FAILED WITHOUT FINISHING. Deliberately narrow:
+ * the observed shape (Story #5266) is a `Navigation timeout of NNNN ms
+ * exceeded` line with an empty violation set, and anything this list does not
+ * recognise keeps the pre-#5266 `advisory-gate-red` verdict — the conservative
+ * direction, since misreading a real violation as a timeout would offer the
+ * operator a rerun for a finding that will come back every time.
+ */
+const INCONCLUSIVE_MARKERS = Object.freeze([
+  /navigation timeout/i,
+  /timeout of \d+\s*m?s exceeded/i,
+  /\btimed out\b/i,
+  /\betimedout\b/i,
+  /\bdid not (?:finish|complete)\b/i,
+  /\b(?:scan|crawl|audit) (?:incomplete|aborted|interrupted)\b/i,
+]);
+
+/** A counted finding — `0 violations` is explicitly NOT one. */
+const VIOLATION_COUNT =
+  /\b(\d+)\s+(?:violation|error|issue|failure|problem|finding)s?\b/i;
+/** An uncounted finding — enough on its own, because it names a verdict. */
+const VIOLATION_WORD = /\bviolations?\b|\bfailed assertion/i;
+
+/**
+ * Pure: does this red run's own text report a VIOLATION (as opposed to saying
+ * nothing, or saying it never got that far)?
+ *
+ * A counted phrase wins over the bare word so `0 violations found` — a scan
+ * that completed cleanly and then died — is not read as a finding.
+ *
+ * Takes the text, not the run: its one caller has already established the
+ * run says something, so a second empty-text guard here would be a branch no
+ * input can reach.
+ *
+ * @param {string} text A non-empty run summary.
+ * @returns {boolean}
+ */
+function reportsViolations(text) {
+  const counted = VIOLATION_COUNT.exec(text);
+  if (counted) return Number.parseInt(counted[1], 10) > 0;
+  return VIOLATION_WORD.test(text);
+}
+
+/**
+ * Pure: classify ONE red advisory run as a genuine violation or an
+ * unfinished job (Story #5266).
+ *
+ * A run whose projection carries no text at all classifies as `violation`:
+ * absence of evidence is not evidence the job timed out, and `violation` is
+ * the verdict every red advisory run already got before this Story.
+ *
+ * @param {{ summary?: string }} [run]
+ * @returns {'violation'|'inconclusive'}
+ */
+function classifyAdvisoryRedRun(run) {
+  const text = typeof run?.summary === 'string' ? run.summary : '';
+  if (!text || reportsViolations(text)) return 'violation';
+  return INCONCLUSIVE_MARKERS.some((marker) => marker.test(text))
+    ? 'inconclusive'
+    : 'violation';
+}
+
+/**
+ * Pure: the block class for a whole set of blocking runs.
+ *
+ * `advisory-gate-inconclusive` requires EVERY blocking run to be inconclusive.
+ * One genuine violation beside a timeout is still a genuine violation, and the
+ * operator must not be offered a rerun as the remedy for it.
+ *
+ * Module-private: {@link resolveAdvisoryGateVerdict} is the one door, so a
+ * caller cannot take the class without the reason that matches it — and, being
+ * the one door, it is also what normalises `blockingRuns` to an array, so
+ * neither this nor {@link formatAdvisoryGateReason} re-guards the shape.
+ *
+ * @param {Array<{ summary?: string }>} runs
+ * @returns {string} one of the two advisory classes above
+ */
+function deriveAdvisoryGateClass(runs) {
+  if (runs.length === 0) return ADVISORY_GATE_RED_CLASS;
+  return runs.every((run) => classifyAdvisoryRedRun(run) === 'inconclusive')
+    ? ADVISORY_GATE_INCONCLUSIVE_CLASS
+    : ADVISORY_GATE_RED_CLASS;
+}
+
+/**
+ * Pure: the advisory gate's whole verdict — class AND the reason text that
+ * matches it (Story #5266). One function so a caller can never pair an
+ * inconclusive class with the violation wording.
+ *
+ * @param {{ blockingRuns?: Array<object>, rerunAllowance?: number }} [args]
+ * @returns {{ blockClass: string, blockingRuns: Array<object>, reason: string }}
+ */
+export function resolveAdvisoryGateVerdict({
+  blockingRuns,
+  rerunAllowance = 0,
+} = {}) {
+  const runs = Array.isArray(blockingRuns) ? blockingRuns : [];
+  const blockClass = deriveAdvisoryGateClass(runs);
+  return {
+    blockClass,
+    blockingRuns: runs,
+    reason: formatAdvisoryGateReason(runs, { blockClass, rerunAllowance }),
+  };
+}
+
 /**
  * Pure: the merge wait's advisory-gate decision, the sibling of
  * {@link decideMergeWaitFailFast} (Story #5096).
@@ -366,13 +575,19 @@ export function advisoryCheckFailedBlocksArm(prProbe, allowlist = []) {
  * Returns `null` when the wait should keep polling — the knob is off, the PR
  * is not in the advisory-red state, or every red run is allowlisted.
  *
+ * The verdict it returns is provisional on the text the ROLLUP carried
+ * (Story #5266): the caller may enrich the blocking runs with the check-run
+ * API's output and re-resolve via {@link resolveAdvisoryGateVerdict} before
+ * recording the block.
+ *
  * @param {object} args
- * @returns {{ blockingRuns: Array<object>, reason: string } | null}
+ * @returns {{ blockingRuns: Array<object>, reason: string, blockClass: string } | null}
  */
 export function decideAdvisoryGateBlock({
   probe,
   blockOnAdvisoryFailure,
   advisoryAllowlist,
+  rerunAllowance = 0,
 }) {
   if (!blockOnAdvisoryFailure) return null;
   if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) return null;
@@ -380,30 +595,59 @@ export function decideAdvisoryGateBlock({
     probe?.redHeadRuns,
     advisoryAllowlist,
   );
-  return { blockingRuns, reason: formatAdvisoryGateReason(blockingRuns) };
+  return resolveAdvisoryGateVerdict({ blockingRuns, rerunAllowance });
 }
 
 /**
  * Format the one-line reason a `merge.unlanded` record and the operator-facing
- * block carry for an `advisory-gate-red` verdict, naming each offending job
- * and its conclusion.
+ * block carry for an advisory-gate verdict, naming each offending job and its
+ * conclusion.
+ *
+ * Story #5266 splits the wording by class: an unfinished job is reported as
+ * one, because telling an operator a timed-out scan "concluded red" invites
+ * them to grant a permanent `advisoryAllowlist` exemption for a transient
+ * failure. Both wordings name the same three remedies — rerun, hand-merge,
+ * allowlist — in the order proportionate to the class.
  *
- * @param {Array<{ name: string|null, conclusion: string }>} blockingRuns
+ * Module-private for the same reason {@link deriveAdvisoryGateClass} is: the
+ * class and the wording must travel together.
+ *
+ * @param {Array<{ name: string|null, conclusion: string }>} runs
+ * @param {{ blockClass: string, rerunAllowance: number }} options
  * @returns {string}
  */
-export function formatAdvisoryGateReason(blockingRuns) {
-  const named = (Array.isArray(blockingRuns) ? blockingRuns : [])
-    .map(
-      (run) =>
-        `${run?.name ?? '(unnamed run)'} → ${run?.conclusion ?? 'FAILURE'}`,
-    )
-    .join(', ');
+function formatAdvisoryGateReason(runs, { blockClass, rerunAllowance }) {
+  const named =
+    runs
+      .map(
+        (run) =>
+          `${run?.name ?? '(unnamed run)'} → ${run?.conclusion ?? 'FAILURE'}`,
+      )
+      .join(', ') || '(none named)';
+  const spent =
+    rerunAllowance > 0
+      ? `The rerun allowance (${rerunAllowance}) is already spent on this head. `
+      : '';
+  if (blockClass === ADVISORY_GATE_INCONCLUSIVE_CLASS) {
+    return (
+      'A non-required (advisory) check FAILED WITHOUT FINISHING on the PR ' +
+      'head — it reported no violation, so nothing here says the change is ' +
+      'bad — and GitHub reports the PR mergeable anyway ' +
+      '(mergeStateStatus=UNSTABLE), so native auto-merge would land it over ' +
+      `the failure. Unfinished advisory job(s): ${named}. ` +
+      `${spent}Re-run the job (--rerun-advisory <n>, or ` +
+      'delivery.ci.rerunAdvisory), merge by hand to land over it ' +
+      'deliberately, or exempt the job via delivery.ci.advisoryAllowlist.'
+    );
+  }
   return (
     'A non-required (advisory) check concluded red on the PR head, and GitHub ' +
     'reports the PR mergeable anyway (mergeStateStatus=UNSTABLE) — native ' +
     'auto-merge would land it over the failure. Red advisory job(s): ' +
-    `${named || '(none named)'}. Merge by hand to land over it deliberately, ` +
-    'or exempt the job via delivery.ci.advisoryAllowlist.'
+    `${named}. ${spent}Merge by hand to land over it ` +
+    'deliberately, re-run the job (--rerun-advisory <n>, or ' +
+    'delivery.ci.rerunAdvisory), or exempt the job via ' +
+    'delivery.ci.advisoryAllowlist.'
   );
 }
 

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

@@ -145,6 +145,7 @@ export async function adoptContainerEpic({
     provider,
     epicNumber: target.id,
     childIds,
+    created: all,
   });
 
   Logger.info(
@@ -164,6 +165,24 @@ export async function adoptContainerEpic({
 /**
  * Write the appended checklist back to the Epic body.
  *
+ * **The body is re-read `fresh` immediately before the append.** `target.body`
+ * was captured by `resolveAdoptionTarget` before the first Story was created,
+ * which on a cohort of any size is many seconds and several writes ago. An
+ * append computed against that snapshot and PATCHed wholesale silently drops
+ * every checklist row another writer added in between — a concurrent persist
+ * run adopting the same Epic, or an operator ticking a child off by hand. The
+ * body is a full-document write, so a stale base is not a merge conflict; it
+ * is a silent revert.
+ *
+ * This **narrows** the read-then-PATCH window; it does not close it. Nothing
+ * here is atomic, and GitHub's issue API offers no compare-and-swap, so a
+ * write landing between this read and this PATCH is still lost. Narrowing it
+ * from "the whole create phase" to "one round-trip" is the available fix; a
+ * real one needs an API that does not exist.
+ *
+ * The PATCH is skipped when the append changes nothing, so re-running an
+ * adoption that already landed writes nothing at all.
+ *
  * Non-fatal: the Stories are already live, and the native sub-issue edges
  * written next are the other half of the linkage. Losing the checklist costs
  * the body-only fallback path, not the grouping.
@@ -179,8 +198,9 @@ async function appendChecklist({ provider, target, childIds }) {
     );
     return;
   }
-  const next = appendEpicChildIds(target.body, childIds);
-  if (next === target.body) return;
+  const base = await readFreshEpicBody({ provider, target });
+  const next = appendEpicChildIds(base, childIds);
+  if (next === base) return;
   try {
     await provider.updateTicket(target.id, { body: next });
   } catch (err) {
@@ -190,3 +210,30 @@ async function appendChecklist({ provider, target, childIds }) {
     );
   }
 }
+
+/**
+ * Re-read the Epic's body, bypassing any provider cache.
+ *
+ * `{ fresh: true }` is the whole point: the adoption path already read this
+ * issue once, so a cached read would hand back the very snapshot this function
+ * exists to replace. Falls back to the snapshot when the re-read fails or the
+ * provider has no `getTicket` — a stale base still appends the run's own
+ * children, which beats not linking them.
+ *
+ * @param {{ provider: object, target: { id: number, body: string } }} opts
+ * @returns {Promise<string>}
+ */
+async function readFreshEpicBody({ provider, target }) {
+  if (typeof provider?.getTicket !== 'function') return target.body;
+  try {
+    const fresh = await provider.getTicket(target.id, { fresh: true });
+    if (typeof fresh?.body === 'string') return fresh.body;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] could not re-read Epic #${target.id} before appending its ` +
+        `checklist (${err?.message ?? err}); appending to the body read earlier. ` +
+        'A child linked by another writer since then may be dropped.',
+    );
+  }
+  return target.body;
+}

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

@@ -123,10 +123,10 @@ async function ensureEpicLabel({ provider }) {
  * @returns {Promise<{ id: number, url?: string }|null>}
  */
 async function findExistingEpic({ provider, fingerprint }) {
-  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  if (typeof provider?.listTicketsByLabel !== 'function') return null;
   try {
     const marker = epicFingerprintMarker(fingerprint);
-    const found = await provider.listIssuesByLabel({
+    const found = await provider.listTicketsByLabel({
       state: 'open',
       labels: TYPE_LABELS.EPIC,
     });
@@ -134,9 +134,12 @@ async function findExistingEpic({ provider, fingerprint }) {
       String(issue?.body ?? '').includes(marker),
     );
     if (!hit) return null;
-    const id = Number(hit.number ?? hit.id);
+    // The declared ticket shape: `id` is the issue number. The `number`-then-
+    // `id` fallback this replaced would have adopted the resumed container by
+    // database id — a number that exists, resolves to nothing, fails no guard.
+    const id = Number(hit.id);
     if (!Number.isInteger(id) || id <= 0) return null;
-    return { id, url: hit.html_url ?? hit.url ?? undefined };
+    return { id, url: hit.url ?? undefined };
   } catch (err) {
     Logger.warn(
       `[plan-persist] Epic resume lookup failed (${err.message}); creating a new container.`,
@@ -145,6 +148,26 @@ async function findExistingEpic({ provider, fingerprint }) {
   }
 }
 
+/**
+ * Index a cohort's already-known database ids by issue number.
+ *
+ * A resumed run's adopted Stories carry no `internalId` — they were found by
+ * listing, not created — so they are simply absent from the map and fall
+ * through to the lookup. Absence means "not known here", never "has none".
+ *
+ * @param {Array<{ id?: number, internalId?: number }>|undefined} created
+ * @returns {Map<number, number>}
+ */
+function internalIdsFrom(created) {
+  const map = new Map();
+  for (const story of Array.isArray(created) ? created : []) {
+    if (Number.isInteger(story?.id) && typeof story?.internalId === 'number') {
+      map.set(story.id, story.internalId);
+    }
+  }
+  return map;
+}
+
 /**
  * Link the created Stories under the Epic as native sub-issue edges.
  *
@@ -156,10 +179,18 @@ async function findExistingEpic({ provider, fingerprint }) {
  * children exactly the way creation does — one mirroring rule, not two that
  * drift.
  *
- * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
+ * `created` is optional and carries the cohort's `createIssue` responses, so
+ * the linker can skip the id lookup for every child this run made itself.
+ *
+ * @param {{ provider: object, epicNumber: number, childIds: number[], created?: Array<{ id: number, internalId?: number }> }} opts
  * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
  */
-export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+export async function mirrorSubIssueEdges({
+  provider,
+  epicNumber,
+  childIds,
+  created = [],
+}) {
   if (
     typeof provider?.getDependencyWriteContext !== 'function' ||
     typeof provider?.getTicket !== 'function'
@@ -176,6 +207,7 @@ export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
     const summary = await linkStoriesToEpic({
       epicNumber,
       childIssueNumbers: childIds,
+      knownInternalIds: internalIdsFrom(created),
       getTicket: (issueNumber) => provider.getTicket(issueNumber),
       owner,
       repo,
@@ -285,6 +317,7 @@ export async function createContainerEpic({
       provider,
       epicNumber: existing.id,
       childIds,
+      created,
     });
     return {
       id: existing.id,
@@ -303,11 +336,14 @@ export async function createContainerEpic({
     labels: [TYPE_LABELS.EPIC],
   });
 
-  const epicNumber = result.number ?? result.id;
+  // `createIssue` declares both `id` and `number` and sets them to the same
+  // issue number; reading one of them is the whole contract.
+  const epicNumber = result.id;
   const edges = await mirrorSubIssueEdges({
     provider,
     epicNumber,
     childIds,
+    created,
   });
 
   Logger.info(