mandrel 2.54.0 → 2.56.0

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,
     });

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

@@ -129,14 +129,64 @@ export function isEpicTicket(issue) {
  * really had. Callers skip the read on a `null` instead, the same clean
  * no-op `providers/github/board-add.js` makes with `reason: 'no-node-id'`.
  *
+ * Module-private since the reader that consumes it moved here: `nativeChildReader`
+ * below is the only production caller, and exporting a helper nothing outside
+ * imports fails the production dead-export gate. Its behaviour is pinned
+ * through that reader.
+ *
  * @param {{ nodeId?: unknown, node_id?: unknown }} epic
  * @returns {string|null}
  */
-export function resolveEpicNodeId(epic) {
+function resolveEpicNodeId(epic) {
   const nodeId = epic?.nodeId ?? epic?.node_id;
   return typeof nodeId === 'string' && nodeId !== '' ? nodeId : null;
 }
 
+/**
+ * Read an Epic's native sub-issue children as issue numbers.
+ *
+ * The **one** definition, injected into `readEpicChildIdsFrom` by both the
+ * delivery expansion (`resolve-stories.js`) and the rollup
+ * (`epic-rollup.js`). It lived in each of them as a private copy, and the two
+ * copies are exactly the pair that must not drift: if the expansion sees a
+ * child the rollup does not, an Epic becomes expandable but permanently
+ * unclosable — the Story #5210 failure, arrived at from the other direction.
+ * Sharing the reader makes that class of divergence unrepresentable.
+ *
+ * It lives *here*, in the module that already describes what a container Epic
+ * is, rather than in either consumer: `resolve-stories.js` is a CLI entrypoint
+ * and importing one from the lib layer would invert the dependency direction.
+ * The provider is a parameter, so this module stays provider-agnostic.
+ *
+ * `resolveEpicNodeId` is what makes the two callers agree on the *id* as well
+ * as the reader: an Epic reached through a mapped read carries `nodeId`, one
+ * read raw from REST carries `node_id`, and neither caller can tell from the
+ * value it holds. A missing id yields `[]` rather than an `undefined` reaching
+ * GraphQL as a rejected `ID!`.
+ *
+ * @param {object} provider
+ * @returns {(epic: object) => Promise<number[]>}
+ */
+export function nativeChildReader(provider) {
+  return async (epic) => {
+    const nodeId = resolveEpicNodeId(epic);
+    if (nodeId === null) return [];
+    // The declared port first, the legacy private alias second: both forward
+    // to the same gateway on the live provider, and the fallback is what keeps
+    // test doubles written against the older name working.
+    const read =
+      provider?.getNativeSubIssues ?? provider?._getNativeSubIssues ?? null;
+    if (typeof read !== 'function') return [];
+    // Diagnostics-only second argument, and the one place the two shapes are
+    // still read together on purpose: this module is the declared bridge
+    // between them (see `resolveEpicNodeId` above), and the expression is
+    // correct under both — a raw REST issue names the issue number `number`,
+    // a mapped ticket names it `id`. Every *consumer* module now receives one
+    // declared shape and reads the field directly.
+    return (await read.call(provider, nodeId, epic?.number ?? epic?.id)) ?? [];
+  };
+}
+
 /**
  * Render a container Epic's body.
  *
@@ -230,12 +280,22 @@ export function readEpicChildIds(body) {
  * supplied none never asked for authority and is not degraded relative to what
  * it requested.
  *
+ * **`bodyOnlyIds` names the ids the union owes to the checklist alone.** The
+ * two sources are not equally trustworthy about a *single* id: a native edge
+ * is a link the backend holds, so an id it returns names a real issue, while a
+ * checklist row is hand-editable prose and can cite an issue that was deleted,
+ * transferred, or simply mistyped. Callers that must decide what an
+ * unresolvable id means need to know which source vouched for it — a native id
+ * that will not resolve is a failed read, a body-only one is a typo. Empty
+ * when the native read failed or never ran: with no authoritative source to
+ * contrast against, nothing is "body-only" in the sense that matters.
+ *
  * @param {{
  *   epic: { number?: number, id?: number, body?: string, nodeId?: string },
  *   readNativeChildIds?: (epic: object) => Promise<number[]>,
  *   onWarn?: (message: string) => void,
  * }} opts
- * @returns {Promise<{ ids: number[], nativeReadFailed: boolean }>}
+ * @returns {Promise<{ ids: number[], nativeReadFailed: boolean, bodyOnlyIds: number[] }>}
  */
 export async function readEpicChildIdsFrom({
   epic,
@@ -244,14 +304,16 @@ export async function readEpicChildIdsFrom({
 } = {}) {
   const fromBody = readEpicChildIds(epic?.body);
   if (typeof readNativeChildIds !== 'function') {
-    return { ids: fromBody, nativeReadFailed: false };
+    return { ids: fromBody, nativeReadFailed: false, bodyOnlyIds: [] };
   }
 
   try {
     const native = normalizeChildIds(await readNativeChildIds(epic));
+    const nativeSet = new Set(native);
     return {
       ids: normalizeChildIds([...native, ...fromBody]),
       nativeReadFailed: false,
+      bodyOnlyIds: fromBody.filter((id) => !nativeSet.has(id)),
     };
   } catch (err) {
     onWarn?.(
@@ -259,6 +321,6 @@ export async function readEpicChildIdsFrom({
         `#${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 { ids: fromBody, nativeReadFailed: true, bodyOnlyIds: [] };
   }
 }