mandrel 2.31.0 → 2.33.0

package/.agents/scripts/providers/github/blocked-by-add.js

@@ -22,7 +22,7 @@
 
 import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
-import { parseApiJson } from './request-helpers.js';
+import { paginateRest } from './request-helpers.js';
 
 /**
  * Bounded concurrency for the GitHub dependency-edge round-trips. Kept modest
@@ -32,22 +32,37 @@ import { parseApiJson } from './request-helpers.js';
 const EDGE_CONCURRENCY = 5;
 
 /**
- * Fetch the existing blocked-by issue numbers for a given issue.
+ * Fetch the existing blocked-by database ids for a given issue, **paginated
+ * to exhaustion**.
+ *
+ * This read is the idempotency check: an edge it fails to see is re-POSTed.
+ * Reading only the first page therefore made the writer non-idempotent past
+ * the page boundary — every edge beyond it looked missing on every run
+ * (Story #5046). `paginateRest` walks the pages and carries the shared
+ * transient-retry and page-cap guards.
  *
  * Returns `[]` on any error so the caller falls back to posting the full
  * set of missing edges (worst case: a duplicate POST, which GitHub
- * handles idempotently).
+ * handles idempotently). That non-fatal contract is deliberate and is the
+ * inverse of the READ path in `lib/orchestration/resolve-stories.js`: a lost
+ * write-side edge is cosmetic, a lost read-side edge removes a dispatch gate.
  *
- * @param {{ gh: object, owner: string, repo: string, issueNumber: number }} opts
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number, paginate?: Function }} opts
  * @returns {Promise<number[]>} Database ids of the issues that currently block `issueNumber`.
  */
-async function fetchExistingBlockedBy({ gh, owner, repo, issueNumber }) {
+async function fetchExistingBlockedBy({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  paginate = paginateRest,
+}) {
   try {
-    const result = await gh.api({
-      method: 'GET',
-      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
-    });
-    const data = parseApiJson(result);
+    const data = await paginate(
+      gh,
+      `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+      { label: `[blocked-by-add] blocked_by #${issueNumber}` },
+    );
     if (!Array.isArray(data)) return [];
     return data.map((item) => item?.id).filter((id) => typeof id === 'number');
   } catch (err) {

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

@@ -5,8 +5,8 @@
  * single `GitHubProvider`, shared by dispatcher, reconciler, and cascade.
  * The outer TTL wrapper is deliberately omitted because `peekFresh` already
  * bounds entries by a caller-supplied `maxAgeMs`, and every other reader
- * trusts the ticket mutators (`updateTicket` / `postComment` /
- * `addSubIssue` / `removeSubIssue`) to call `invalidate` explicitly.
+ * trusts the ticket mutators (`updateTicket` / `postComment`) to call
+ * `invalidate` explicitly.
  *
  * Surface is intentionally narrow: only the methods the provider itself
  * reaches for live here (`has` / `peek` / `peekFresh` / `set` /

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

@@ -7,20 +7,16 @@
  * the upstream `upsertStructuredComment` ticketing helper before the body
  * lands here.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `postComment`,
- * `getRecentComments`, `getTicketComments`, and `deleteComment` all
- * delegate here.
+ * Extracted from `../github.js` in Story #2462 / Task #2480. `postComment`,
+ * `getTicketComments`, and `deleteComment` on `GitHubProvider` all delegate
+ * here. Story #5008 dropped the repo-wide `getRecentComments` feed — the
+ * telemetry dashboard that read it was retired and nothing else polls a
+ * cross-issue comment stream.
  *
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
-import { withTransientRetry } from './errors.js';
-import {
-  defaultRetryWarn,
-  paginateRest,
-  parseApiJson,
-} from './request-helpers.js';
+import { paginateRest, parseApiJson } from './request-helpers.js';
 
 // Structured-comment badge — preserved verbatim from the legacy
 // `./github/comments.js`. The upstream `upsertStructuredComment` ticketing
@@ -51,24 +47,6 @@ export class CommentGateway {
     this._hooks = hooks;
   }
 
-  /**
-   * Recent comments across all issues in the repo (sorted newest first).
-   *
-   * @field-manifest /repos/{owner}/{repo}/issues/comments?sort=created:
-   *                 id, body, created_at, user, issue_url
-   */
-  async getRecentComments(limit = 100) {
-    const result = await withTransientRetry(
-      () =>
-        this._gh.api({
-          method: 'GET',
-          endpoint: `/repos/${this.owner}/${this.repo}/issues/comments?sort=created&direction=desc&per_page=${limit}`,
-        }),
-      { label: 'getRecentComments', onRetry: defaultRetryWarn },
-    );
-    return parseApiJson(result) ?? [];
-  }
-
   /**
    * All comments on a single ticket. Used by the upstream
    * `findStructuredComment` ticketing helper, which greps each comment

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

@@ -23,7 +23,6 @@ import { LabelGateway } from './labels.js';
 import { MergeMethodsGateway } from './merge-methods.js';
 import { ProjectBoardGateway } from './project-board.js';
 import * as projects from './projects-v2-graphql.js';
-import { PullRequestGateway } from './prs.js';
 import { SubIssueGateway } from './sub-issues.js';
 import { TicketGateway } from './tickets.js';
 
@@ -50,12 +49,6 @@ export function composeGateways(provider) {
     ghGraphql: (q, v, o) => p.graphql(q, v, o),
     cache: p._cache,
     classifyGithubError,
-    hooks: {
-      getTicket: (id, o) => p.getTicket(id, o),
-      getTickets: (id) => p.getTickets(id),
-      primeTicketCache: (t) => p.primeTicketCache(t),
-      invalidateTicket: (id) => p.invalidateTicket(id),
-    },
   });
   p.comments = new CommentGateway({
     ...ghDeps,
@@ -64,14 +57,6 @@ export function composeGateways(provider) {
   p.labels = new LabelGateway(ghDeps);
   p.branchProtection = new BranchProtectionGateway(ghDeps);
   p.mergeMethods = new MergeMethodsGateway(ghDeps);
-  p.pullRequests = new PullRequestGateway({
-    gh: p._gh,
-    hooks: {
-      getTicket: (id) => p.getTicket(id),
-      addItemToProject,
-      getProjectNumber,
-    },
-  });
   p.issues = new IssuesGateway({
     ...ghDeps,
     hooks: {

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

@@ -1,16 +1,16 @@
 /**
- * GitHub Provider — error classifier + sub-issues GraphQL shapes.
+ * GitHub Provider — error classifier + sub-issues GraphQL shape.
  *
  * `classifyGithubError` buckets `gh-exec`-thrown errors into 4 categories
  * (`feature-disabled` / `permission` / `transient` / `permanent`) so the
- * sub-issues fallback and the addSubIssue retry loop have a deterministic
+ * sub-issues fallback and the shared retry loop have a deterministic
  * switch. Rate-limit detection wins over the 401/403 → permission rule
  * because GitHub's secondary rate limit is delivered as HTTP 403 with a
  * known message; if we bucketed it as 'permission' it would never be
  * retried.
  *
- * `SUB_ISSUES_QUERY` / `ADD_SUB_ISSUE_MUTATION` / `REMOVE_SUB_ISSUE_MUTATION`
- * are the three GraphQL shapes the sub-issues feature reads/writes.
+ * `SUB_ISSUES_QUERY` is the GraphQL shape the sub-issues read path uses.
+ * Story #5008 removed the add/remove mutations with the write surface.
  *
  * Extracted from `../github.js` in Story #1846 / Task #1857.
  */
@@ -153,11 +153,11 @@ export function classifyGithubError(err) {
 // transient network/connectivity errors — so every former consumer of either
 // module keeps (or gains) its prior retry coverage with no shim.
 //
-// Mirrors the addSubIssue retry contract in `sub-issues.js` so read-path
-// callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
-// jittered exponential backoff on transient GitHub errors instead of
-// bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /deliver Phase E retro). The network consumers repointed here
+// Read-path callers (paginateRest, getTicket, getNativeSubIssues, …) all
+// absorb the same jittered exponential backoff on transient GitHub errors
+// through this one primitive, instead of bubbling a one-shot
+// 502/429/ECONNRESET that kills a longer pipeline (e.g. the /deliver
+// Phase E retro). The network consumers repointed here
 // (branch-protection, labels, projects-v2-graphql) call with no opts, so
 // they adopt these defaults; their retry *classes* (the network blips) are
 // preserved via the unified classifier above.
@@ -174,8 +174,7 @@ export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
  * `classify` (defaults to `classifyGithubError`) decides whether each
  * failure is retry-eligible: only `'transient'` retries; every other
  * bucket (`feature-disabled` / `permission` / `permanent`) bubbles on the
- * first failure. The retry shape matches `addSubIssue` in
- * `sub-issues.js:119-167`.
+ * first failure.
  *
  * `sleep` and `random` are injectable so tests can drive deterministic
  * retry paths without real-world timing.
@@ -256,19 +255,3 @@ export const SUB_ISSUES_QUERY = `query($id: ID!, $cursor: String) {
     }
   }
 }`;
-
-export const ADD_SUB_ISSUE_MUTATION = `
-  mutation($parentId: ID!, $subIssueId: ID!, $replaceParent: Boolean) {
-    addSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId, replaceParent: $replaceParent }) {
-      issue { number }
-      subIssue { number }
-    }
-  }`;
-
-export const REMOVE_SUB_ISSUE_MUTATION = `
-  mutation($parentId: ID!, $subIssueId: ID!) {
-    removeSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId }) {
-      issue { number }
-      subIssue { number }
-    }
-  }`;

package/.agents/scripts/providers/github/request-helpers.js

@@ -9,8 +9,7 @@
  *   1. **Transient retry** — each underlying `gh.api({...})` call inside
  *      `paginateRest` is wrapped in `withTransientRetry` (from `./errors.js`),
  *      so a single 502 / 429 / ECONNRESET on page N of M does not lose
- *      pages 1..N-1 of work. The retry shape matches the existing
- *      `addSubIssue` mutation retry contract in `sub-issues.js`.
+ *      pages 1..N-1 of work.
  *   2. **Page cap** — `paginateRest` enforces a hard ceiling (default
  *      `DEFAULT_PAGE_CAP = 50` → 5000 items at `per_page=100`). Exceeding
  *      the cap throws a clear error naming the endpoint, cap, and items

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

@@ -1,21 +1,19 @@
 /**
  * GitHub Provider — SubIssueGateway.
  *
- * Owns the native GitHub Sub-Issues link surface (the GraphQL `subIssues`
- * field on an Issue, plus the add/remove mutations) along with the
- * `reconcileSubIssueLinks` walker that backfills missing parent/child
- * links across an Epic's child set.
+ * Owns the **read** side of the native GitHub Sub-Issues surface: the
+ * GraphQL `subIssues` field on an Issue, paginated into a child-number
+ * list. Story #5008 removed the write side (`addSubIssue`,
+ * `removeSubIssue`) and the `reconcileSubIssueLinks` walker along with the
+ * rest of the Epic-hierarchy provider surface — v2 delivery is Story-only,
+ * so nothing establishes or repairs parent/child links any more.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `addSubIssue`,
- * `removeSubIssue`, and `reconcileSubIssueLinks` all delegate here.
+ * Extracted from `../github.js` in Story #2462 / Task #2480. The read path
+ * still reaches `GitHubProvider` as `_getNativeSubIssues`, and
+ * `IssuesGateway` calls it directly through its `getNativeSubIssues` hook.
  *
- * Constructed with `{ ghGraphql, hooks, classifyGithubError, cache, queries }`:
+ * Constructed with `{ ghGraphql, cache, classifyGithubError }`:
  *   - `ghGraphql(query, variables, opts)`    — bound `_ghGraphql` from the parent.
- *   - `hooks.getTicket(id, opts)`            — bound to the TicketGateway.
- *   - `hooks.getTickets(parentId)`           — bound to the TicketGateway (for the reconciler).
- *   - `hooks.primeTicketCache(tickets)`      — bound to the TicketGateway (reconciler priming).
- *   - `hooks.invalidateTicket(id)`           — bound to the TicketGateway (post-mutation invalidate).
  *   - `cache.primeIfAbsent(ticket)`          — bound to the shared cache (native-walk priming).
  *
  * The gateway holds **no** transport state of its own — every call goes
@@ -26,25 +24,14 @@
  */
 
 import { Logger } from '../../lib/Logger.js';
-import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import {
-  ADD_SUB_ISSUE_MUTATION,
   classifyGithubError as defaultClassifyGithubError,
-  REMOVE_SUB_ISSUE_MUTATION,
   SUB_ISSUES_QUERY,
   withTransientRetry,
 } from './errors.js';
 import { subIssueNodeToTicket } from './mappers.js';
 import { defaultRetryWarn } from './request-helpers.js';
 
-// Concurrency + retry budgets — preserved from `../github.js` so dispatch
-// fan-out and sub-issue reconciliation keep their established shapes.
-const SUB_ISSUE_RECONCILE_CONCURRENCY = 4;
-const SUB_ISSUE_RETRY_MAX_ATTEMPTS = 6;
-const SUB_ISSUE_RETRY_BASE_DELAY_MS = 1000;
-const SUB_ISSUE_RETRY_MAX_DELAY_MS = 30000;
-const SUB_ISSUE_RETRY_JITTER_MS = 500;
-
 // Story #2852: cap the native sub-issue cursor walk so a runaway pagination
 // (e.g. an upstream API regression that never sets `hasNextPage = false`)
 // fails fast instead of looping forever. 50 cursor pages × 100 nodes per
@@ -55,24 +42,16 @@ export class SubIssueGateway {
   /**
    * @param {{
    *   ghGraphql: (query: string, variables?: object, opts?: object) => Promise<object>,
-   *   hooks?: {
-   *     getTicket?: (id: number, opts?: object) => Promise<object>,
-   *     getTickets?: (parentId: number) => Promise<object[]>,
-   *     primeTicketCache?: (tickets: object[]) => void,
-   *     invalidateTicket?: (id: number) => void,
-   *   },
    *   cache?: { primeIfAbsent: (ticket: object) => void },
    *   classifyGithubError?: (err: unknown) => string,
    * }} deps
    */
   constructor({
     ghGraphql,
-    hooks = {},
     cache,
     classifyGithubError = defaultClassifyGithubError,
   } = {}) {
     this._ghGraphql = ghGraphql;
-    this._hooks = hooks;
     this._cache = cache;
     this._classify = classifyGithubError;
   }
@@ -132,191 +111,4 @@ export class SubIssueGateway {
     }
     return childIds;
   }
-
-  /**
-   * Establish the native sub-issue link between `parentNumber` and the
-   * child identified by `childNodeId`. Retries on transient errors with
-   * jittered exponential backoff before re-throwing.
-   */
-  async addSubIssue(
-    parentNumber,
-    childNodeId,
-    opts = { replaceParent: false },
-  ) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] addSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    let lastErr;
-    for (let attempt = 0; attempt < SUB_ISSUE_RETRY_MAX_ATTEMPTS; attempt++) {
-      try {
-        const result = await this._ghGraphql(
-          ADD_SUB_ISSUE_MUTATION,
-          {
-            parentId: parentTicket.nodeId,
-            subIssueId: childNodeId,
-            replaceParent: opts.replaceParent,
-          },
-          { headers: { 'GraphQL-Features': 'sub_issues' } },
-        );
-        // Sub-issue link mutates the parent's sub-issue list. Invalidate so
-        // the next `getTicket(parentNumber)` re-fetches a coherent view.
-        if (typeof this._hooks.invalidateTicket === 'function') {
-          this._hooks.invalidateTicket(parentNumber);
-        }
-        return result;
-      } catch (err) {
-        lastErr = err;
-        const category = this._classify(err);
-        const isFinalAttempt = attempt === SUB_ISSUE_RETRY_MAX_ATTEMPTS - 1;
-        if (category !== 'transient' || isFinalAttempt) throw err;
-        const base = Math.min(
-          SUB_ISSUE_RETRY_MAX_DELAY_MS,
-          SUB_ISSUE_RETRY_BASE_DELAY_MS * 2 ** attempt,
-        );
-        const delay =
-          base + Math.floor(Math.random() * SUB_ISSUE_RETRY_JITTER_MS);
-        Logger.warn(
-          `[GitHubProvider] sub-issue link transient error for parent #${parentNumber} (attempt ${attempt + 1}/${SUB_ISSUE_RETRY_MAX_ATTEMPTS}); retrying in ${delay}ms: ${err.message}`,
-        );
-        await new Promise((r) => setTimeout(r, delay));
-      }
-    }
-    throw lastErr;
-  }
-
-  async removeSubIssue(parentNumber, subIssueNumber) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] removeSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    const childTicket = await getTicket(subIssueNumber);
-    const result = await this._ghGraphql(
-      REMOVE_SUB_ISSUE_MUTATION,
-      { parentId: parentTicket.nodeId, subIssueId: childTicket.nodeId },
-      { headers: { 'GraphQL-Features': 'sub_issues' } },
-    );
-    if (typeof this._hooks.invalidateTicket === 'function') {
-      this._hooks.invalidateTicket(parentNumber);
-      this._hooks.invalidateTicket(subIssueNumber);
-    }
-    return result;
-  }
-
-  /**
-   * Walk every child of `epicId` whose body footer carries `parent: #N` and
-   * verify the native sub-issue link is present. Re-establish missing links
-   * via `addSubIssue` (which retries internally). Idempotent.
-   */
-  async reconcileSubIssueLinks(epicId) {
-    const PARENT_RE = /(?:^|\n)parent:\s*#(\d+)/;
-    const getTicket = this._hooks.getTicket;
-    const getTickets = this._hooks.getTickets;
-    if (typeof getTicket !== 'function' || typeof getTickets !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] reconcileSubIssueLinks requires getTicket + getTickets hooks',
-      );
-    }
-    const allChildren = await getTickets(epicId);
-    const parentByChild = new Map();
-    for (const child of allChildren) {
-      const match = (child.body ?? '').match(PARENT_RE);
-      if (!match) continue;
-      parentByChild.set(child.id, Number.parseInt(match[1], 10));
-    }
-
-    const childrenByParent = new Map();
-    for (const [childId, parentId] of parentByChild) {
-      if (!childrenByParent.has(parentId)) childrenByParent.set(parentId, []);
-      childrenByParent.get(parentId).push(childId);
-    }
-
-    let alreadyLinked = 0;
-    let reconciled = 0;
-    let failed = 0;
-    const failures = [];
-
-    const parentEntries = Array.from(childrenByParent.entries());
-
-    await concurrentMap(
-      parentEntries,
-      async ([parentId, childIds]) => {
-        let parent;
-        try {
-          parent = await getTicket(parentId);
-        } catch (err) {
-          for (const childId of childIds) {
-            failures.push({ parentId, childId, reason: err.message });
-          }
-          failed += childIds.length;
-          return;
-        }
-        if (!parent?.nodeId) {
-          for (const childId of childIds) {
-            failures.push({
-              parentId,
-              childId,
-              reason: 'parent missing nodeId',
-            });
-          }
-          failed += childIds.length;
-          return;
-        }
-
-        const linked = new Set(
-          await this.getNativeSubIssues(parent.nodeId, parentId),
-        );
-
-        await concurrentMap(
-          childIds,
-          async (childId) => {
-            if (linked.has(childId)) {
-              alreadyLinked++;
-              return;
-            }
-            let childTicket;
-            try {
-              childTicket = await getTicket(childId);
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-              return;
-            }
-            if (!childTicket?.nodeId) {
-              failures.push({
-                parentId,
-                childId,
-                reason: 'child missing nodeId',
-              });
-              failed++;
-              return;
-            }
-            try {
-              await this.addSubIssue(parentId, childTicket.nodeId);
-              reconciled++;
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-            }
-          },
-          { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-        );
-      },
-      { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-    );
-
-    return {
-      totalExpected: parentByChild.size,
-      alreadyLinked,
-      reconciled,
-      failed,
-      failures,
-    };
-  }
 }

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

@@ -19,8 +19,10 @@
  * module.
  *
  * Gateway map: tickets, sub-issues, comments, labels, branch-protection,
- * merge-methods, prs, project-board, issues (epics + sub-tickets +
- * branch probe + raw GraphQL).
+ * merge-methods, project-board, issues (epics + sub-tickets + branch probe
+ * + raw GraphQL). Story #5008 retired the `prs` gateway — `single-story-close`
+ * drives `gh pr create` directly — along with the sub-issue write surface and
+ * the repo-wide recent-comments feed.
  */
 
 import { createGh, gh as defaultGh } from '../lib/gh-exec.js';
@@ -125,16 +127,11 @@ const DELEGATIONS = [
   ['updateTicket', 'tickets.updateTicket'],
   ['_applyLabelMutations', 'tickets._applyLabelMutations'],
   ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
-  ['addSubIssue', 'subIssues.addSubIssue'],
-  ['removeSubIssue', 'subIssues.removeSubIssue'],
-  ['reconcileSubIssueLinks', 'subIssues.reconcileSubIssueLinks'],
-  ['getRecentComments', 'comments.getRecentComments'],
   ['getTicketComments', 'comments.getTicketComments'],
   ['deleteComment', 'comments.deleteComment'],
   ['postComment', 'comments.postComment'],
   ['getBranchProtection', 'branchProtection.getBranchProtection'],
   ['setBranchProtection', 'branchProtection.setBranchProtection'],
-  ['createPullRequest', 'pullRequests.createPullRequest'],
   ['ensureLabels', 'labels.ensureLabels'],
   ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
   ['getMergeMethods', 'mergeMethods.getMergeMethods'],