mandrel 2.59.0 → 2.61.0

package/.agents/scripts/providers/github/projects-v2-graphql.js

@@ -1,10 +1,7 @@
 /**
- * Projects V2 GraphQL shim — single retained surface (Story #1358, Epic #1179).
- * Collapses the projects.js / graphql.js / graphql-builder.js trio into one
- * file; provider delegates the four V2 methods + addItemToProject here. Token:
- * `gh auth token` → GITHUB_TOKEN/GH_TOKEN env. Soft-fails on
- * INSUFFICIENT_SCOPES via `{scopesMissing:true}` / `status:'scopes-missing'` /
- * `unavailable:true` envelopes. Wave 3 deletes the old submodules.
+ * Projects V2 GraphQL shim. Token: `gh auth token` → GITHUB_TOKEN/GH_TOKEN.
+ * Soft-fails on INSUFFICIENT_SCOPES via `{scopesMissing:true}` /
+ * `status:'scopes-missing'` / `unavailable:true` envelopes.
  */
 import { execSync } from 'node:child_process';
 import { withTransientRetry } from './errors.js';

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

@@ -1,23 +1,5 @@
 /**
  * GitHub Provider — shared REST request helpers.
- *
- * Story #2852: dedupes the `parseApiJson` + `paginateRest` copies that
- * previously lived inline in `tickets.js`, `issues.js`, `comments.js`,
- * `branch-protection.js`, and `merge-methods.js`, and folds in two
- * resilience guards:
- *
- *   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.
- *   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
- *      collected so far, so a runaway loop fails fast and visibly instead
- *      of hanging. Pass `pageCap` in the options bag to opt into a larger
- *      ceiling when the call site has a legitimate reason.
- *
- * @see Story #2852 — Harden provider REST read path.
  */
 
 import { Logger } from '../../lib/Logger.js';
@@ -26,20 +8,14 @@ import { withTransientRetry } from './errors.js';
 export const DEFAULT_PAGE_CAP = 50;
 export const DEFAULT_PER_PAGE = 100;
 
-/**
- * Parse a `gh api ...` stdout payload into JSON. Returns `null` for empty
- * bodies (HTTP 204 DELETE responses).
- */
+/** `null` for an empty body (e.g. a 204 DELETE). */
 export function parseApiJson(result) {
   const stdout = result?.stdout ?? '';
   if (!stdout.trim()) return null;
   return JSON.parse(stdout);
 }
 
-/**
- * Default retry-warn logger — shared so every retro-relevant call site
- * emits in the same shape and operators can grep for `[gh-api retry]`.
- */
+/** One greppable `[gh-api retry]` shape for every call site. */
 export function defaultRetryWarn({ attempt, maxAttempts, delay, err, label }) {
   const msg =
     typeof err === 'object' && err && typeof err.message === 'string'
@@ -52,10 +28,9 @@ export function defaultRetryWarn({ attempt, maxAttempts, delay, err, label }) {
 }
 
 /**
- * Paginate a REST list endpoint by appending `page=N&per_page=100` until
- * a short page lands or the page cap is exceeded. Mirrors the legacy
- * behaviour for callers (returns a single concatenated array) and adds
- * the Story #2852 transient-retry + page-cap guards.
+ * Concatenate pages until a short page lands. Each page retries transient
+ * errors on its own, so a blip on page N keeps pages 1..N-1. Hitting the page
+ * cap throws (naming endpoint and count) rather than truncating silently.
  *
  * @param {object} ghFacade           bound gh facade (provider._gh)
  * @param {string} endpoint           REST endpoint without `page=` set
@@ -103,7 +78,5 @@ export async function paginateRest(ghFacade, endpoint, opts = {}) {
       );
     }
   }
-  // Unreachable: the loop returns or throws on the last iteration. Kept
-  // for type-narrowing / future-proofing.
   return items;
 }

package/.agents/scripts/providers/github/search-budget.js

@@ -1,26 +1,10 @@
 /**
- * GitHub Provider — `/search/issues` fan-out budget (Story #4678).
- *
- * The 30-requests-per-minute cap is a property of GitHub's `/search/issues`
- * endpoint, not of any one caller. A single audit-to-stories scan issues ~2
- * search calls per finding; a 22-group scan therefore blows well past the cap
- * with no throttle of any kind, and every exhausted call then spends its whole
- * transient-retry budget re-issuing a request against an already-empty window.
- *
- * This module owns the throttle at the endpoint seam: a pure, injectable token
- * bucket that `IssuesGateway#searchIssues` awaits before every call, so every
- * caller (audit-to-stories dedup, `lib/duplicate-search.js`, the tickets
- * gateway's `_searchIssues`) inherits one shared budget for free.
- *
- * `now` and `sleep` are injected so unit tests drive the bucket deterministically
- * without wall-clock time.
+ * GitHub Provider — token-bucket throttle for `/search/issues`, whose
+ * 30/min cap belongs to the endpoint, not any caller. `searchIssues` awaits
+ * it before every call so all callers share one budget.
  */
 
-/**
- * Default budget: 30 tokens per 60s window, matching GitHub's authenticated
- * Search API cap. When a rate limit is reported with no readable reset, the
- * bucket pauses for one full window before the next `take()` resolves.
- */
+/** GitHub's authenticated Search cap; cooldown applies when no reset is readable. */
 const SEARCH_BUDGET_DEFAULTS = Object.freeze({
   capacity: 30,
   windowMs: 60_000,
@@ -28,14 +12,9 @@ const SEARCH_BUDGET_DEFAULTS = Object.freeze({
 });
 
 /**
- * Create a token-bucket search budget.
- *
- * `take()` resolves once a token is available, consuming it; it awaits an
- * accruing token (and any active rate-limit cooldown) rather than failing.
- * `noteRateLimited(resetAtMs)` drains the bucket and blocks every subsequent
- * `take()` until the reported reset (or a fixed cooldown when no reset is
- * readable), so the whole batch pauses **once** instead of each call retrying
- * independently into the empty window.
+ * `take()` waits for (never fails on) a token. `noteRateLimited` drains the
+ * bucket and blocks every `take()` until the reset, so the batch pauses once
+ * instead of each call retrying into the empty window.
  *
  * @param {object} [opts]
  * @param {number} [opts.capacity] — max tokens (and burst size).
@@ -79,7 +58,6 @@ export function createSearchBudget({
         tokens -= 1;
         return;
       }
-      // Sleep just long enough for one token to accrue, then re-check.
       const waitMs = Math.max(1, Math.ceil((1 - tokens) / refillPerMs));
       await sleep(waitMs);
     }
@@ -99,19 +77,11 @@ export function createSearchBudget({
   return { take, noteRateLimited };
 }
 
-/**
- * Process-wide singleton shared by every `searchIssues` caller. Per-process,
- * matching the one-scan-per-checkout model — there is deliberately no
- * cross-process budget.
- */
+/** Per-process by design (one scan per checkout); no cross-process budget. */
 export const searchBudget = createSearchBudget();
 
 /**
- * Best-effort extract of a rate-limit reset time (epoch ms) from a thrown
- * error's stderr. GitHub surfaces the reset as an `x-ratelimit-reset` epoch
- * (seconds) header; `gh` echoes response headers onto stderr on failure.
- * Returns `undefined` when no reset is readable so the bucket falls back to a
- * fixed cooldown. Pure — no I/O.
+ * The `x-ratelimit-reset` header (epoch seconds) `gh` echoes onto stderr.
  *
  * @param {unknown} err
  * @returns {number|undefined} reset time in epoch milliseconds, or undefined.

package/.agents/scripts/providers/github/search-query.js

@@ -1,29 +1,13 @@
 /**
- * GitHub Provider — composed `/search/issues` query bound (Story #4678).
- *
- * `IssuesGateway#searchIssues` is the only place that knows the *composed* `q`
- * — the caller's free text plus the `repo:<owner>/<repo> type:issue` qualifiers
- * it appends. GitHub Search rejects a query over 256 characters with HTTP 422,
- * which is neither transient nor caught, so an over-long title over a deep path
- * would abort the whole scan. This module owns the defensive guard: it truncates
- * the free-text portion on a whole-token boundary until the composed `q` fits.
- *
- * Pure and unit-testable — no I/O.
+ * GitHub Provider — bounds a composed `/search/issues` query. Search answers
+ * a `q` over 256 chars with a non-transient 422 that would abort a scan.
  */
 
-/**
- * GitHub Search's documented maximum query length, in characters. Module-private
- * — `composeBoundedQuery` is the only supported way to apply it, so the bound
- * cannot drift between call sites.
- */
 const GITHUB_SEARCH_MAX_QUERY = 256;
 
 /**
- * Compose a `/search/issues` query from free text plus fixed qualifiers,
- * truncating the free-text portion on a whole-token boundary so the whole
- * composed string is at most `max` characters. Qualifiers are never dropped —
- * they are the load-bearing scope (`repo:` / `type:`) — so when even the
- * qualifiers alone exceed the budget the qualifier string is returned as-is.
+ * Truncate the free text on a whole-token boundary to fit `max`. Qualifiers
+ * are the scope and are never dropped, even if they alone exceed `max`.
  *
  * @param {string} freeText — the caller's free-text search term(s).
  * @param {string[]} qualifiers — fixed qualifier tokens (e.g. `repo:o/r`).
@@ -40,8 +24,6 @@ export function composeBoundedQuery(
   const full = `${free} ${quals}`.trim();
   if (full.length <= max) return full;
 
-  // Reserve space for the qualifiers (and the joining space) and fit as many
-  // leading free-text tokens as the remaining budget allows.
   const reserve = quals.length + (quals.length > 0 ? 1 : 0);
   const budget = max - reserve;
   const bounded = fitTokens(free.split(/\s+/).filter(Boolean), budget);
@@ -49,10 +31,7 @@ export function composeBoundedQuery(
 }
 
 /**
- * Join as many leading `tokens` as fit within `budget` characters, on a
- * whole-token boundary (space-separated). Returns '' when the budget cannot fit
- * even the first token. Module-private — exercised through
- * {@link composeBoundedQuery}, the only caller.
+ * Leading tokens that fit `budget`; '' when even the first doesn't.
  *
  * @param {string[]} tokens
  * @param {number} budget

package/.agents/scripts/providers/github/sub-issue-add.js

@@ -1,54 +1,25 @@
 /**
- * GitHub Provider — shared "link child issue to a parent" helper.
+ * GitHub Provider — link child issues under a parent as native sub-issues
+ * (`POST /repos/{owner}/{repo}/issues/{n}/sub_issues`).
  *
- * Story #5139 — a container Epic holds its children as native GitHub
- * sub-issue edges. The read side has existed since v1
- * (`sub-issues.js` → `getNativeSubIssues`, and the three-strategy
- * aggregator in `issues.js` → `getSubTickets`); this is the missing write.
+ * `sub_issue_id` is the child's database id, not its issue number; both are
+ * plausible integers, so a mix-up silently links the wrong issue.
  *
- * API surface used:
- *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
- *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
- *          body: { "sub_issue_id": <integer db id of the CHILD issue> }
- *
- * **`sub_issue_id` is the child's database id, not its issue number.** They
- * are different integers and both are plausible, so a mix-up does not throw
- * — it silently links the wrong issue, or a nonexistent one. This mirrors
- * `blocked-by-add.js`, whose `issue_id` carries the same trap.
- *
- * Contract (deliberately identical to `blocked-by-add.js`):
- *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
- *   - **Non-fatal** — catches all errors per edge, warns, and continues.
- *     The function never throws; failures are returned in the summary.
- *     The Epic body's checklist is the durable mirror, so a lost edge
- *     degrades discoverability rather than losing the child.
- *   - **No-op on empty input.**
+ * Idempotent (reads existing edges first) and non-fatal (per-edge failures
+ * are warned and counted, never thrown) — the Epic body's checklist is the
+ * durable mirror. Same contract as `blocked-by-add.js`.
  */
 
 import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { paginateRest } from './request-helpers.js';
 
-/**
- * Bounded concurrency for the sub-issue round-trips. Matches the
- * dependency-edge writer's cap: modest enough for GitHub's secondary rate
- * limits while collapsing wall-clock from `sum(round-trips)` toward
- * `sum(round-trips) / concurrency`.
- */
+/** Kept modest for GitHub's secondary rate limits. */
 const EDGE_CONCURRENCY = 5;
 
 /**
- * Fetch the database ids of a parent's existing sub-issues, **paginated to
- * exhaustion**.
- *
- * This read is the idempotency check: an edge it fails to see is re-POSTed.
- * Reading only the first page would therefore make the writer non-idempotent
- * past the page boundary — the same defect Story #5046 fixed in
- * `blocked-by-add.js`.
- *
- * Returns `[]` on any error so the caller falls back to posting the full
- * set. Worst case is a duplicate POST, which GitHub rejects harmlessly and
- * the per-edge catch absorbs.
+ * Paginated to exhaustion: this is the idempotency check, and an unseen edge
+ * is re-POSTed. `[]` on error — a duplicate POST is rejected harmlessly.
  *
  * @param {{ gh: object, owner: string, repo: string, issueNumber: number, paginate?: Function }} opts
  * @returns {Promise<number[]>} Database ids of the parent's current children.
@@ -77,12 +48,6 @@ async function fetchExistingSubIssueIds({
 }
 
 /**
- * Link a set of child issues to one parent as native sub-issues.
- *
- * For each entry in `childInternalIds`, checks whether the edge already
- * exists and POSTs only the missing ones. Every individual POST failure is
- * caught, logged and counted — the function never throws.
- *
  * @param {{
  *   gh: object,
  *   owner: string,
@@ -113,8 +78,7 @@ export async function addSubIssueEdges({
   });
   const existingSet = new Set(existing);
 
-  // Partition up front so the skip count is deterministic regardless of the
-  // concurrent POST dispatch order.
+  // Partition up front so `skipped` is independent of dispatch order.
   const missing = ids.filter((id) => !existingSet.has(id));
   const skipped = ids.length - missing.length;
 
@@ -149,24 +113,10 @@ export async function addSubIssueEdges({
 }
 
 /**
- * Link child Stories to a container Epic, resolving each child's **database
- * id** from its issue number.
- *
- * Callers hold issue numbers (that is what `plan-persist` creates and what
- * an operator types); the API wants database ids. Doing the translation here
- * keeps that trap in one place instead of at every call site.
- *
- * `knownInternalIds` short-circuits the translation for children whose
- * database id the caller already has. `createIssue` returns `internalId` in
- * its response, so a cohort this run just created needs no lookup at all —
- * the `getTicket` fan-out that used to run over every child was re-reading
- * issues the same process had created seconds earlier, one round-trip per
- * Story, to recover a field it had already been handed and thrown away.
- * `getTicket` stays for the children a *resumed* run adopted, whose ids came
- * from a listing rather than a create.
- *
- * Never throws: a child whose id cannot be resolved is counted as failed and
- * the remaining edges still go out.
+ * Link Stories to a container Epic, translating issue numbers to database ids
+ * here so the trap lives in one place. `knownInternalIds` (from
+ * `createIssue`) skips the lookup; `getTicket` covers children a resumed run
+ * adopted. An unresolvable child counts as failed; the rest still go out.
  *
  * @param {{
  *   epicNumber: number,

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

@@ -1,26 +1,7 @@
 /**
- * GitHub Provider — SubIssueGateway.
- *
- * 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. The read path
- * still reaches `GitHubProvider` as `_getNativeSubIssues`, and
- * `IssuesGateway` calls it directly through its `getNativeSubIssues` hook.
- *
- * Constructed with `{ ghGraphql, cache, classifyGithubError }`:
- *   - `ghGraphql(query, variables, opts)`    — bound `_ghGraphql` from the parent.
- *   - `cache.primeIfAbsent(ticket)`          — bound to the shared cache (native-walk priming).
- *
- * The gateway holds **no** transport state of its own — every call goes
- * through the supplied `ghGraphql` hook, which is the parent provider's
- * `gh api graphql` shim.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — SubIssueGateway: the read side of native Sub-Issues (the
+ * GraphQL `subIssues` field, paginated into child numbers). Holds no
+ * transport state; every call goes through the parent's `ghGraphql` hook.
  */
 
 import { describeGhFailure } from '../../lib/gh-exec.js';
@@ -33,10 +14,7 @@ import {
 import { subIssueNodeToTicket } from './mappers.js';
 import { defaultRetryWarn } from './request-helpers.js';
 
-// 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
-// page = 5000 sub-issues, well above any realistic Epic.
+// Fail fast if `hasNextPage` never clears; 50 × 100 = 5000 sub-issues.
 const NATIVE_SUB_ISSUE_PAGE_CAP = 50;
 
 export class SubIssueGateway {
@@ -57,11 +35,7 @@ export class SubIssueGateway {
     this._classify = classifyGithubError;
   }
 
-  /**
-   * Strategy 1 — native GitHub Sub-Issues via GraphQL. Paginates and seeds
-   * the ticket cache via the supplied `cache.primeIfAbsent` hook. Returns
-   * `[]` (not throw) when the feature is disabled on this repo.
-   */
+  /** Primes the ticket cache; `[]` when the feature is disabled. */
   async getNativeSubIssues(parentNodeId, parentId) {
     const childIds = [];
     let cursor = null;
@@ -105,11 +79,8 @@ export class SubIssueGateway {
         );
         return [];
       }
-      // `describeGhFailure`, not `err.message`: on the gh transport the
-      // message is only the classified summary (`gh exited with code 1`) and
-      // the actionable sentence — the HTTP status, the rate-limit notice — is
-      // on stderr. Three identical opaque lines are what made the Epic-rollup
-      // incident unreadable until the API was queried by hand (Story #5210).
+      // Not `err.message`: on the gh transport that is only `gh exited with
+      // code 1`; the HTTP status and rate-limit notice are on stderr.
       Logger.error(
         `[GitHubProvider] sub-issues GraphQL failed (parent #${parentId}, ` +
           `category=${category}): ${describeGhFailure(err)}`,