mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/git/sync-from-base.js

@@ -12,18 +12,38 @@
  * merge and reduces (does not eliminate) the residual race-with-merge
  * window. The merge queue is the proper fix for the residual race.
  *
- * Why merge (not rebase): Story branches are pushed and reviewed across
- * iterations of the watch + fix loop; a rebase would force-push and risk
- * losing in-flight reviewer context. The merge commit is squashed away
- * when the PR lands, so the cosmetic cost is zero.
+ * Why merge, not rebase (Story #5267 — settled, do not re-open):
+ *
+ *   1. Mandrel states no rebase rule anywhere. `git-conventions.md`
+ *      mandates branch shapes and commit subjects and is silent on how a
+ *      branch takes on base commits, so there is no convention to honour
+ *      here — only a trade-off to pick.
+ *   2. Story branches are pushed and reviewed across iterations of the
+ *      watch + fix loop. A rebase force-pushes, discarding in-flight
+ *      reviewer context and any review state pinned to the old SHAs.
+ *   3. A rebase would NOT save the pre-push capture stamp people reach
+ *      for it to save. The stamp is keyed on the tree, and rebasing onto
+ *      a moved base changes the tree exactly as merging it does — both
+ *      invalidate the stamp, so the credit argument is a wash. The real
+ *      remedy is the `changedPaths` reporting below: say out loud when
+ *      the sync spent the stamp, rather than change how it is spent.
+ *
+ * The merge commit is squashed away when the PR lands, so the cosmetic
+ * cost is zero.
  *
  * Outcomes (`{ synced, kind, ... }`):
  *
- *   - `{ synced: true, kind: 'noop-already-current' }` — `origin/<base>`
- *     is already an ancestor of HEAD; nothing to do.
- *   - `{ synced: true, kind: 'fast-forward' }` — merge fast-forwarded.
- *   - `{ synced: true, kind: 'merge-commit' }` — non-trivial merge
- *     succeeded; a merge commit landed on the active branch.
+ *   - `{ synced: true, kind: 'noop-already-current', changedPaths: [] }`
+ *     — `origin/<base>` is already an ancestor of HEAD; nothing to do.
+ *   - `{ synced: true, kind: 'fast-forward', changedPaths }` — merge
+ *     fast-forwarded.
+ *   - `{ synced: true, kind: 'merge-commit', changedPaths }` — non-trivial
+ *     merge succeeded; a merge commit landed on the active branch.
+ *
+ * `changedPaths` is the tracked paths the sync brought into the branch —
+ * `git diff --name-only <pre-merge HEAD> HEAD` — and is what lets a caller
+ * tell a sync that spent a pre-push capture stamp from one that did not.
+ * It is `[]` for every non-mutating and every failing outcome.
  *   - `{ synced: false, kind: 'fetch-failed', stderr }` — `git fetch`
  *     could not retrieve `origin/<base>`. No mutation occurred.
  *   - `{ synced: false, kind: 'conflict', conflictFiles }` — merge
@@ -32,17 +52,102 @@
  *   - `{ synced: false, kind: 'merge-failed', stderr }` — merge exited
  *     non-zero for a reason other than a parseable conflict (rare; treat
  *     as a hard blocker on the caller's side).
+ *   - `{ synced: false, kind: 'merge-driver-missing', stderr }` — the
+ *     worktree's `.gitattributes` routes `baselines/*.json` through the
+ *     `mandrel-baseline` merge driver and this clone has no
+ *     `merge.mandrel-baseline.driver` config, so git would text-merge
+ *     generated baselines. Nothing was fetched or merged (Story #5277).
  *
  * The helper does not mutate any ticket state, post comments, or write
  * to anything other than the worktree's git refs / index. Callers own
  * the recovery surface.
  */
 
+import {
+  BASELINE_MERGE_DRIVER_CONFIG_KEY,
+  BASELINE_MERGE_DRIVER_REMEDY,
+  probeBaselineMergeDriver,
+} from '../bootstrap/baseline-merge-driver.js';
 import {
   gitFetchWithRetry as defaultGitFetchWithRetry,
   gitSpawn as defaultGitSpawn,
 } from '../git-utils.js';
 
+/**
+ * Refuse the sync when the baseline merge driver is declared but unregistered
+ * (Story #5277). `probeBaselineMergeDriver` owns the two-part question and why
+ * each half matters; this is where the answer becomes a refusal.
+ *
+ * Base-sync is the one place the failure is catchable before it happens: it is
+ * the merge that runs unattended, immediately before the push, on exactly the
+ * files a concurrent sibling Story most often also refreshed. Refusing costs
+ * one operator command; proceeding costs a silently wrong baseline on `main`
+ * that nothing downstream re-derives.
+ *
+ * @param {string} cwd
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @returns {{ synced: false, kind: 'merge-driver-missing', stderr: string, remedy: string }|null}
+ */
+function refuseWithoutMergeDriver(cwd, gitSpawn) {
+  const { declared, command } = probeBaselineMergeDriver({
+    projectRoot: cwd,
+    runGit: (args) => gitSpawn(cwd, ...args),
+  });
+  if (!declared || command.length > 0) return null;
+  return {
+    synced: false,
+    kind: 'merge-driver-missing',
+    stderr:
+      `.gitattributes routes baselines/*.json through the mandrel-baseline merge ` +
+      `driver, but ${BASELINE_MERGE_DRIVER_CONFIG_KEY} is unset in this clone. ` +
+      'Merging origin now would text-merge generated baselines, which conflicts on ' +
+      'the generatedAt stamp and can splice rows neither branch scored. Register the ' +
+      `driver, then re-run:\n  ${BASELINE_MERGE_DRIVER_REMEDY}\n` +
+      '  (or: npm run baselines:merge-driver)',
+    remedy: BASELINE_MERGE_DRIVER_REMEDY,
+  };
+}
+
+/**
+ * Resolve the current HEAD SHA, or `null` when git cannot answer.
+ *
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function readHead(gitSpawn, cwd) {
+  const head = gitSpawn(cwd, 'rev-parse', 'HEAD');
+  if (head.status !== 0) return null;
+  const sha = (head.stdout ?? '').toString().trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * The tracked paths that differ between `fromSha` and the current HEAD.
+ *
+ * Returns `[]` when the pre-merge SHA could not be read or the diff itself
+ * failed. That is deliberately the quiet answer: the only consumer is the
+ * caller's "your capture stamp may be dead" warning, and manufacturing that
+ * warning out of a failed probe would cry wolf on every sync in a repo where
+ * `rev-parse` is broken — a condition the merge one line earlier would
+ * already have failed on.
+ *
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @param {string} cwd
+ * @param {string|null} fromSha
+ * @returns {string[]}
+ */
+function diffPaths(gitSpawn, cwd, fromSha) {
+  if (!fromSha) return [];
+  const diff = gitSpawn(cwd, 'diff', '--name-only', fromSha, 'HEAD');
+  if (diff.status !== 0) return [];
+  return (diff.stdout ?? '')
+    .toString()
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 /**
  * Sync the active branch in `cwd` against `origin/<baseBranch>`. See
  * the module docstring for the full outcome envelope.
@@ -64,9 +169,9 @@ import {
  *   tests.
  *
  * @returns {Promise<
- *   | { synced: true, kind: 'noop-already-current' }
- *   | { synced: true, kind: 'fast-forward' }
- *   | { synced: true, kind: 'merge-commit' }
+ *   | { synced: true, kind: 'noop-already-current', changedPaths: string[] }
+ *   | { synced: true, kind: 'fast-forward', changedPaths: string[] }
+ *   | { synced: true, kind: 'merge-commit', changedPaths: string[] }
  *   | { synced: false, kind: 'fetch-failed', stderr: string }
  *   | { synced: false, kind: 'conflict', conflictFiles: string[] }
  *   | { synced: false, kind: 'merge-failed', stderr: string }
@@ -88,6 +193,12 @@ export async function syncBranchFromBase({
     );
   }
 
+  const driverGap = refuseWithoutMergeDriver(cwd, gitSpawn);
+  if (driverGap) {
+    log('SYNC', driverGap.stderr);
+    return driverGap;
+  }
+
   log('SYNC', `Fetching origin/${baseBranch}...`);
   const fetch = await gitFetchWithRetry(cwd, 'origin', baseBranch);
   if (fetch.status !== 0) {
@@ -111,9 +222,14 @@ export async function syncBranchFromBase({
   );
   if (originAlreadyMerged.status === 0) {
     log('SYNC', `origin/${baseBranch} already merged into HEAD — no-op.`);
-    return { synced: true, kind: 'noop-already-current' };
+    return { synced: true, kind: 'noop-already-current', changedPaths: [] };
   }
 
+  // Pin the pre-merge HEAD so a successful sync can name what it brought
+  // in. Read BEFORE the merge, because afterwards the only handle on the
+  // old tree is this SHA.
+  const preMergeHead = readHead(gitSpawn, cwd);
+
   const headBehindOrigin = gitSpawn(
     cwd,
     'merge-base',
@@ -134,6 +250,7 @@ export async function syncBranchFromBase({
     return {
       synced: true,
       kind: willFastForward ? 'fast-forward' : 'merge-commit',
+      changedPaths: diffPaths(gitSpawn, cwd, preMergeHead),
     };
   }
 

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

@@ -101,6 +101,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-lifecycle-lint.js',
   'check-pinned-override-notes.js',
   'check-schema-references.js',
+  'check-test-portability.js',
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
   'check-workflow-citations.js',

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -82,8 +82,16 @@ function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
   if (raw === null) return null;
   try {
     return JSON.parse(raw);
-  } catch {
-    return null;
+  } catch (cause) {
+    // Story #5277 — the same distinction one line above, applied to the
+    // second way a base read fails. `null` here means "no baseline at the base
+    // ref", which empties the head-vs-base arm on purpose; an UNPARSEABLE base
+    // blob is a read that failed, and reporting it as "no base" made a
+    // corrupted or half-merged `baselines/*.json` on the base branch report
+    // zero regressions at exit 0. Text-merged baselines are exactly how such a
+    // blob gets onto the base branch, which is the failure this Story removes
+    // upstream — this arm is what stops it being silent when it happens anyway.
+    throw buildBaseReadError({ kind, ref: scope.ref, file: rel, cause });
   }
 }
 

package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js

@@ -96,23 +96,69 @@ function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
 }
 
 /**
- * Read the baseline rows as of one refresh commit. Returns `null` — never
- * throws and never a partial row set — when the blob is absent, unreadable or
- * unparseable at that SHA. The caller treats `null` as "this commit
- * acknowledges nothing", which keeps the ratchet at full strength rather than
- * acknowledging on a guess.
+ * Read the baseline rows as of one git ref.
+ *
+ * Returns `null` — never throws and never a partial row set — when the blob is
+ * unreadable or unparseable at that ref. The caller treats `null` as "this
+ * commit acknowledges nothing", which keeps the ratchet at full strength rather
+ * than acknowledging on a guess.
+ *
+ * A blob that is genuinely ABSENT at the ref reads as `{ rows: [] }`, not
+ * `null`. The distinction only matters for the `sha^` read below: the commit
+ * that CREATES a baseline has no blob at its parent, and treating that as
+ * unreadable would make the first refresh of any kind acknowledge nothing.
+ * `readBaseFromGit` already draws exactly this line — `null` for git's exit
+ * 128 "path does not exist in this revision", a throw for everything else — so
+ * the two cases are distinguishable rather than guessed at.
+ *
+ * @returns {{ rows: Array<object> }|null}
  */
-function readRowsAtCommit(sha, baselinePath, cwd) {
+function readRowsAtRef(ref, baselinePath, cwd) {
   let raw;
   try {
-    raw = readBaseFromGit(sha, baselinePath, { cwd });
+    raw = readBaseFromGit(ref, baselinePath, { cwd });
   } catch {
     return null;
   }
-  if (raw === null) return null;
+  if (raw === null) return { rows: [] };
   try {
     const payload = JSON.parse(raw);
-    return Array.isArray(payload?.rows) ? payload.rows : null;
+    return Array.isArray(payload?.rows) ? { rows: payload.rows } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which row identities did the tagged commit itself REWRITE (Story #5277)?
+ *
+ * This is the half Story #5179 left open. It scoped the acknowledgment to the
+ * rows present in the baseline blob *at* the tagged commit — but a blob is a
+ * whole-file snapshot, so it also contains every row an EARLIER, untagged
+ * commit on the same branch lowered. Such a row is present at the refresh
+ * commit and unchanged at head, so it classified as `ok` and was acknowledged
+ * by a commit that never touched it. The observed shape: a branch lowers a
+ * maintainability row while refactoring, later refreshes an unrelated CRAP row
+ * with a `baseline-refresh:` commit, and the first regression is waved through.
+ *
+ * Diffing `sha^ → sha` is what makes the acknowledgment a statement about the
+ * COMMIT rather than about the branch's accumulated state. No tolerance is
+ * applied: any movement at all means the commit re-scored that identity, which
+ * is the only question being asked here.
+ *
+ * @returns {Set<string>|null} null when the diff is unusable, which
+ *   acknowledges nothing from this commit.
+ */
+function keysTouchedByCommit({ mod, rowsAtSha, rowsAtParent }) {
+  try {
+    const result = mod.compare({ rows: rowsAtSha }, { rows: rowsAtParent });
+    return new Set(
+      [
+        ...(result?.regressions ?? []),
+        ...(result?.improvements ?? []),
+        ...(result?.additions ?? []),
+      ].map((entry) => entry.key),
+    );
   } catch {
     return null;
   }
@@ -179,6 +225,11 @@ function classifyAgainstRefresh({ mod, headRows, refreshRows, tolerance }) {
  *      lands in `drifted`. Drift from commits landing AFTER the refresh is what
  *      "the baseline commit must be the branch's last score-moving commit" asks
  *      for by convention and nothing enforced.
+ *   3. **The commit actually rewrote it** (Story #5277) — `keysTouchedByCommit`
+ *      diffs `sha^ → sha`. Tests 1 and 2 both read the blob AT the commit,
+ *      which is a whole-file snapshot and therefore also carries rows an
+ *      earlier untagged commit lowered; those rows passed both tests without
+ *      the tagged commit having touched them.
  *
  * Fails closed at every step: an unreadable blob, a missing `compare`, or a
  * classifier that throws contributes nothing, so those regressions stand.
@@ -212,17 +263,24 @@ function acknowledgeableKeys({
   // state the branch is asking to be held to.
   const decided = new Set();
   for (const { sha } of refreshCommits) {
-    const refreshRows = readRowsAtCommit(sha, baselinePath, cwd);
-    if (refreshRows === null) continue;
+    const atSha = readRowsAtRef(sha, baselinePath, cwd);
+    const atParent = readRowsAtRef(`${sha}^`, baselinePath, cwd);
+    if (atSha === null || atParent === null) continue;
+    const touched = keysTouchedByCommit({
+      mod,
+      rowsAtSha: atSha.rows,
+      rowsAtParent: atParent.rows,
+    });
+    if (touched === null) continue;
     const verdict = classifyAgainstRefresh({
       mod,
       headRows,
-      refreshRows,
+      refreshRows: atSha.rows,
       tolerance,
     });
     if (verdict === null) continue;
     for (const key of verdict.ok) {
-      if (decided.has(key)) continue;
+      if (decided.has(key) || !touched.has(key)) continue;
       decided.add(key);
       acknowledgeable.add(key);
     }
@@ -264,10 +322,12 @@ function logAcknowledgment({ kind, reasons, acknowledged, kept }) {
  *
  * The two trigger arms are scoped differently, deliberately:
  *
- * - **Commit tag** — scoped to the rows the tagged commits actually refreshed,
+ * - **Commit tag** — scoped to the rows the tagged commits actually rewrote,
  *   per `acknowledgeableKeys`. Before Story #5179 this cleared every regression
  *   in the range, so a branch merged carrying a stale row and the ratchet ran
- *   loose on that file; the failure recurred six times.
+ *   loose on that file; the failure recurred six times. Story #5277 closed the
+ *   remainder: the scoping read the blob at the tagged commit, which still
+ *   carried rows an earlier untagged commit had lowered.
  * - **Env parity** (`<KIND>_REFRESH=1`) — stays whole-run. There is no commit to
  *   anchor row-scoping to, and setting the variable is an explicit, deliberate
  *   operator act rather than a signal inferred from history.

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -13,8 +13,12 @@
  *
  * The strand shapes the table resolves, and why each is real:
  *
- *   - `executing` with no PR → resume implementation. The work never reached
- *     close.
+ *   - `executing`, branch UNPUSHED, no PR → resume implementation. The work
+ *     never reached close. Since Story #5267 the worker pushes before its
+ *     creditable capture, so an unpushed branch means this and nothing else.
+ *   - `executing`, branch PUSHED, no PR → run close. The worker's hand-off
+ *     landed; only the close-and-land tail is owed, and re-initializing here
+ *     would re-open finished work.
  *   - `closing` with a pending PR → resume the land. The overwhelmingly
  *     common shape now that the merge wait is bounded: the wait returned
  *     `pending` and something has to pick it back up.
@@ -315,6 +319,80 @@ function closeInFlightVerdict({ storyId, artifacts, evidence }) {
   };
 }
 
+/**
+ * The `agent::executing` rows of the table (Story #4543; split on push state
+ * by Story #5267).
+ *
+ * Lifted out of {@link decideRecovery} because this label alone fans out into
+ * five distinct strands, and because the push-state split below only reads
+ * correctly next to the artifact probes it is ordered after.
+ *
+ * @param {{ storyId: number, branch: object, pr: object|null, closeArtifacts?: object, evidence: string[] }} args
+ * @returns {{ shape: string, nextCommand: string|null, detail: string, evidence: string[] }}
+ */
+function decideExecuting({ storyId, branch, pr, closeArtifacts, evidence }) {
+  if (pr?.number) {
+    return {
+      shape: 'executing-with-pr',
+      nextCommand: NEXT_COMMANDS.close(storyId),
+      detail:
+        `PR #${pr.number} exists but the Story is still \`agent::executing\` — the close ` +
+        `opened the PR and then died before the label flip. Re-run close; it reuses the ` +
+        `open PR rather than opening a duplicate.`,
+      evidence,
+    };
+  }
+  // Story #4816 — the close artifacts get the first word here, and ONLY
+  // here. Every other row of this table describes a state whose evidence is
+  // already unambiguous; `executing` + no PR is the one row that reads
+  // identically for a dead implementation and for a close that is halfway
+  // through its gate chain, and answering it from labels alone is what sent
+  // operators to re-init on top of a live close.
+  if (closeLooksLive(closeArtifacts)) {
+    return closeInFlightVerdict({
+      storyId,
+      artifacts: closeArtifacts,
+      evidence,
+    });
+  }
+  if (closeArtifacts?.envelope) {
+    return envelopeOnDiskVerdict({
+      storyId,
+      artifacts: closeArtifacts,
+      evidence,
+    });
+  }
+  // Story #5267 — push state is what separates the two remaining strands, and
+  // it separates them cleanly now that the worker pushes BEFORE its creditable
+  // capture. Before that ordering, a worker whose turn ended on the
+  // backgrounded capture left an unpushed branch that was indistinguishable
+  // from work that never got started; now an unpushed branch means exactly one
+  // thing, and a pushed one means the hand-off happened and only close is
+  // owed.
+  if (branch?.remote) {
+    return {
+      shape: 'executing-pushed-no-pr',
+      nextCommand: NEXT_COMMANDS.close(storyId),
+      detail:
+        `\`story-${storyId}\` is PUSHED to origin but no PR exists and no close left an ` +
+        `artifact behind — the worker finished and handed off, and the close never ran (or ` +
+        `died before its first gate). Nothing needs re-implementing: run close, which is ` +
+        `idempotent. Do NOT re-init — the branch already carries the finished work.`,
+      evidence,
+    };
+  }
+  return {
+    shape: 'executing-no-pr',
+    nextCommand: NEXT_COMMANDS.implement(storyId),
+    detail:
+      `Story is \`agent::executing\`, \`story-${storyId}\` is UNPUSHED, there is no PR, and ` +
+      `no close left an artifact behind (no persisted terminal envelope, no recent gate ` +
+      `log) — implementation never finished. Re-init (idempotent — it reuses the existing ` +
+      `branch and worktree) and resume in the worktree it prints.`,
+    evidence,
+  };
+}
+
 /**
  * The decision table. Pure: every input is an already-observed probe, so the
  * mapping is testable without git, GitHub, or a clock.
@@ -434,47 +512,7 @@ export function decideRecovery({
   }
 
   if (label === STATE_LABELS.EXECUTING) {
-    if (pr?.number) {
-      return {
-        shape: 'executing-with-pr',
-        nextCommand: NEXT_COMMANDS.close(storyId),
-        detail:
-          `PR #${pr.number} exists but the Story is still \`agent::executing\` — the close ` +
-          `opened the PR and then died before the label flip. Re-run close; it reuses the ` +
-          `open PR rather than opening a duplicate.`,
-        evidence,
-      };
-    }
-    // Story #4816 — the close artifacts get the first word here, and ONLY
-    // here. Every other row of this table describes a state whose evidence is
-    // already unambiguous; `executing` + no PR is the one row that reads
-    // identically for a dead implementation and for a close that is halfway
-    // through its gate chain, and answering it from labels alone is what sent
-    // operators to re-init on top of a live close.
-    if (closeLooksLive(closeArtifacts)) {
-      return closeInFlightVerdict({
-        storyId,
-        artifacts: closeArtifacts,
-        evidence,
-      });
-    }
-    if (closeArtifacts?.envelope) {
-      return envelopeOnDiskVerdict({
-        storyId,
-        artifacts: closeArtifacts,
-        evidence,
-      });
-    }
-    return {
-      shape: 'executing-no-pr',
-      nextCommand: NEXT_COMMANDS.implement(storyId),
-      detail:
-        `Story is \`agent::executing\` with no PR, and no close left an artifact behind (no ` +
-        `persisted terminal envelope, no recent gate log) — implementation never finished. ` +
-        `Re-init (idempotent — it reuses the existing branch and worktree) and resume in the ` +
-        `worktree it prints.`,
-      evidence,
-    };
+    return decideExecuting({ storyId, branch, pr, closeArtifacts, evidence });
   }
 
   return {
@@ -500,6 +538,7 @@ export function decideRecovery({
  */
 const TRANSIENT_SHAPES = new Set([
   'executing-no-pr',
+  'executing-pushed-no-pr',
   'executing-with-pr',
   'closing-no-pr',
   'closing-pr-pending',

package/.agents/scripts/lib/orchestration/dependency-candidates.js

@@ -92,7 +92,7 @@ export async function findDependencyCandidates({
     (p) => typeof p === 'string' && p.trim() !== '',
   );
   if (wanted.length === 0) return [];
-  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+  if (typeof provider?.listTicketsByLabel !== 'function') return [];
 
   const excluded = new Set(
     [...excludeIds].map((id) => Number(id)).filter((n) => Number.isFinite(n)),
@@ -100,7 +100,7 @@ export async function findDependencyCandidates({
 
   let issues;
   try {
-    issues = await provider.listIssuesByLabel({
+    issues = await provider.listTicketsByLabel({
       state: 'open',
       labels: TYPE_LABELS.STORY,
     });
@@ -113,7 +113,11 @@ export async function findDependencyCandidates({
 
   const out = [];
   for (const issue of Array.isArray(issues) ? issues : []) {
-    const id = Number(issue?.number ?? issue?.id);
+    // The declared ticket shape: `id` is the issue number. Reading it through
+    // the old `number`-then-`id` fallback was the bug in waiting — on this
+    // shape the fallback never fires, and on a raw REST payload it silently
+    // produced database ids for every candidate the planner offered.
+    const id = Number(issue?.id);
     if (!Number.isInteger(id) || id <= 0 || excluded.has(id)) continue;
 
     const footprint = footprintOf(issue);
@@ -125,7 +129,7 @@ export async function findDependencyCandidates({
     out.push({
       id,
       title: typeof issue?.title === 'string' ? issue.title : '',
-      url: issue?.html_url ?? issue?.url ?? buildStoryUrl(id, { owner, repo }),
+      url: issue?.url ?? buildStoryUrl(id, { owner, repo }),
       state: typeof issue?.state === 'string' ? issue.state : 'open',
       overlappingPaths,
     });

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

@@ -81,7 +81,12 @@ async function readChildTitles({ childIds, provider }) {
  * @returns {Promise<{ id: number, title: string, url: string, score: number, childIds: number[] }|null>}
  */
 async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
-  const id = Number(epic?.number ?? epic?.id);
+  // `listTicketsByLabel` hands back the declared ticket shape, in which `id`
+  // is the issue number. The `number`-then-`id` fallback this replaced read as
+  // defensive and was not: on that shape it never fired, and on a raw REST
+  // payload it was the only thing standing between this and scoring an Epic
+  // under its database id.
+  const id = Number(epic?.id);
   if (!Number.isInteger(id) || id <= 0) return null;
 
   const title = typeof epic?.title === 'string' ? epic.title : '';
@@ -98,7 +103,7 @@ async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
   return {
     id,
     title,
-    url: epic?.html_url ?? epic?.url ?? buildEpicUrl(id, { owner, repo }),
+    url: epic?.url ?? buildEpicUrl(id, { owner, repo }),
     score: Number(score.toFixed(4)),
     childIds,
   };
@@ -126,14 +131,14 @@ async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
  */
 export async function findOpenEpicCandidates({ seed, provider, owner, repo }) {
   if (typeof seed !== 'string' || seed.trim() === '') return [];
-  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+  if (typeof provider?.listTicketsByLabel !== 'function') return [];
 
   const seedTokens = tokenize(seed);
   if (seedTokens.size === 0) return [];
 
   let issues;
   try {
-    issues = await provider.listIssuesByLabel({
+    issues = await provider.listTicketsByLabel({
       state: 'open',
       labels: TYPE_LABELS.EPIC,
     });