@link-assistant/hive-mind 1.59.5 → 1.59.7

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # @link-assistant/hive-mind
 
+## 1.59.7
+
+### Patch Changes
+
+- 4f03aea: fix(solve): post a Working session summary at the end of every working session — issue #1728.
+
+  `--auto-attach-solution-summary` previously only ran in `solve.mjs`'s top-level flow.
+  Iterations inside `--auto-restart-until-mergeable` (`src/solve.auto-merge.lib.mjs`) and
+  `--watch` / temporary auto-restart (`src/solve.watch.lib.mjs`) called
+  `executeToolIteration()`, uploaded a log comment, and discarded the AI's
+  `toolResult.resultSummary` — so when the AI finished an iteration without posting
+  a comment, the user saw only the start (`Auto-restart triggered`) and end
+  (`Auto-restart-until-mergeable Log`) brackets with no AI conclusions in between.
+  Reproduced live on link-foundation/box PR #83 between comment ids
+  [`4345164478`](https://github.com/link-foundation/box/pull/83#issuecomment-4345164478)
+  and [`4345439482`](https://github.com/link-foundation/box/pull/83#issuecomment-4345439482).
+
+  Fix: extracted the attach-decision into a single helper
+  `maybeAttachWorkingSessionSummary` in `src/solve.results.lib.mjs` that all three
+  working-session call sites (`solve.mjs`, `solve.auto-merge.lib.mjs`,
+  `solve.watch.lib.mjs`) invoke with their own `iterationStartTime`. Each successful
+  iteration now ends with either an AI-authored comment OR an automated
+  "Working session summary" comment.
+
+  Also renamed the comment header from "Solution summary" to "Working session
+  summary" because not every working session is a solution draft — many are
+  continuation/restart iterations. CLI flag names (`--attach-solution-summary`,
+  `--auto-attach-solution-summary`, `--no-auto-attach-solution-summary`) and
+  function names are preserved for backwards compatibility. The new header is
+  registered in `TOOL_GENERATED_COMMENT_MARKERS` so a previous iteration's summary
+  is excluded from the next iteration's "did the AI post anything?" check.
+
+  Tests: extended `tests/test-solution-summary.mjs` to cover the new helper, the
+  header rename, the marker registration, and the per-iteration wiring in
+  `solve.auto-merge.lib.mjs` / `solve.watch.lib.mjs`.
+
+  Case study: `docs/case-studies/issue-1728/`.
+
+## 1.59.6
+
+### Patch Changes
+
+- d6d05a0: Fully safeguard from GitHub API rate-limit errors — issue #1726.
+
+  `/merge` merged a draft PR even though every `gh api` call had been failing
+  with `HTTP 403: API rate limit exceeded`. The merge subsystem caught those
+  errors silently in `getActiveRepoWorkflows()` and reported _"no CI checks
+  and repo has no active workflows — no CI/CD configured"_, which `/merge`
+  interpreted as _"all clear"_. Verbose log
+  ([`docs/case-studies/issue-1726/data/a4dccea2-a941-4a0c-a50e-60b1ed454e1e.log`](./docs/case-studies/issue-1726/data/a4dccea2-a941-4a0c-a50e-60b1ed454e1e.log),
+  lines 40251–40269):
+
+  ```
+  [VERBOSE] /merge: Error fetching workflows for link-foundation/relative-meta-logic:
+    Command failed: gh api "repos/link-foundation/relative-meta-logic/actions/workflows" --paginate --slurp
+  gh: API rate limit exceeded for user ID 1431904 ... (HTTP 403)
+
+  [VERBOSE] /merge: PR #100 has no CI checks and repo has no active workflows - no CI/CD configured
+  ```
+
+  Two combining root causes:
+  1. **`getActiveRepoWorkflows()` swallowed exceptions** in
+     [`src/github-merge.lib.mjs`](./src/github-merge.lib.mjs) and returned
+     `[]`. Rate-limit responses became "this repo has no workflows", which the
+     merge gate treated as "no CI configured, safe to merge".
+  2. **No gh API call site had rate-limit retry**. The existing
+     `ghCmdRetry`/`ghRetry` helpers only recognised transient TCP/TLS faults,
+     so a 403 fell straight through. ~135 raw `$gh ...` and
+     ``exec(`gh ...`)`` call sites scattered across `src/solve.*`,
+     `src/github-merge.*`, scripts, and reviewers.
+
+  Fix:
+  - **New rate-limit module**
+    [`src/github-rate-limit.lib.mjs`](./src/github-rate-limit.lib.mjs) with
+    `isRateLimitError`, `parseRateLimitReset`, `fetchNextRateLimitReset`,
+    `computeRateLimitWait`, `ghWithRateLimitRetry`, `execGhWithRetry`,
+    `wrapDollarWithGhRetry`. Applies the issue's policy:
+    `wait = (resetTime − now) + bufferMs (10 min) + random(0..jitterMs) (0..5 min)`,
+    reusing `limitReset.bufferMs` / `limitReset.jitterMs` from
+    [`src/config.lib.mjs`](./src/config.lib.mjs) (introduced in #1236).
+  - **Propagate errors instead of swallowing**. `getActiveRepoWorkflows()`
+    no longer wraps the gh call in try/catch that returns `[]`. Errors bubble
+    up; the merge gate sees the failure and stops.
+  - **Layered retry in legacy helpers**. `ghRetry` and `ghCmdRetry` in
+    [`src/lib.mjs`](./src/lib.mjs) check `isRateLimitError` first and delegate
+    to `ghWithRateLimitRetry` before applying transient-network retry.
+  - **Local `exec` shim** in 7 merge files rebound through
+    `ghWithRateLimitRetry` — converts every existing ``exec(`gh ...`)`` site
+    without per-call edits.
+  - **Wrapped `$` at every entry point** (15 files). `wrapDollarWithGhRetry`
+    routes every `$gh ...` through the retry helper while passing non-gh
+    commands unchanged.
+  - **Marker imports** in 17 callee files that receive `$` as a parameter,
+    declaring rate-limit awareness for the ESLint rule.
+  - **Queue threshold lowered** from 75% to 50% in
+    [`src/queue-config.lib.mjs`](./src/queue-config.lib.mjs).
+  - **Custom ESLint rule**
+    [`eslint-rules/no-direct-gh-exec.mjs`](./eslint-rules/no-direct-gh-exec.mjs)
+    flags any unsafe `gh` exec call site; files that import a known-safe
+    wrapper are exempted at file scope.
+
+  Tests:
+  - [`tests/github-rate-limit.test.mjs`](./tests/github-rate-limit.test.mjs)
+    — 22 unit tests covering `isRateLimitError` (primary, secondary,
+    abuse-detection, stderr, cause-chain), `parseRateLimitReset` (header
+    variants), `computeRateLimitWait` (future / null / past reset, jitter
+    bounds), `ghWithRateLimitRetry` (success, propagation, retry-then-succeed,
+    exhausted retries), `wrapDollarWithGhRetry` (passthrough, retry,
+    propagation).
+  - [`tests/test-no-direct-gh-exec-rule.mjs`](./tests/test-no-direct-gh-exec-rule.mjs)
+    — RuleTester valid/invalid cases.
+  - Updated `tests/queue-config.test.mjs` and `tests/limits-display.test.mjs`
+    for the 50% threshold.
+
+  Documentation:
+  [`docs/case-studies/issue-1726/`](./docs/case-studies/issue-1726/README.md)
+  contains the failing run logs, root-cause analysis, fix breakdown, and
+  verification commands.
+
+- bb0af8c: Fix `check-file-line-limits` CI failure on `main` after issue #1726 merge.
+
+  After PR #1726 (rate-limit safeguards) merged into `main`, the
+  `check-file-line-limits` job failed because three `.mjs` files crossed the
+  1500-line hard limit:
+  - `src/hive.mjs` — 1500 → 1504 lines
+  - `src/limits.lib.mjs` — 1497 → 1501 lines
+  - `src/solve.repository.lib.mjs` — 1500 → 1501 lines
+
+  Two root causes combined: (1) the per-file marker block PR #1726 added was 4
+  lines (2 comment lines + import + `void`), with no headroom check; (2) ESLint's
+  `max-lines` rule was configured with `skipBlankLines: true, skipComments: true`
+  while the CI script counts raw `wc -l`, so `npm run lint` passed locally even
+  though the CI script would fail. Local lint and CI line-limit had silently
+  drifted apart. See
+  [`docs/case-studies/issue-1730`](./docs/case-studies/issue-1730/README.md)
+  for the timeline, log excerpts, and template comparison.
+
+  Fix:
+  - **Synchronize ESLint `max-lines` with the CI script** in
+    [`eslint.config.mjs`](./eslint.config.mjs) by setting `skipBlankLines: false,
+skipComments: false`. Now `npm run lint` catches the failure locally before
+    push, restoring the invariant the rule's comment claimed.
+  - **Compact the rate-limit marker** introduced by #1726 from 4 lines to 1 line
+    in all 17 files. ESLint's existing `varsIgnorePattern: '^_'` means the
+    `void _wrapDollarWithGhRetry;` line was redundant; the trailing-comment form
+    preserves rate-limit awareness for `no-direct-gh-exec` while saving 3 lines
+    per file. Files: `src/hive.mjs`, `src/limits.lib.mjs`,
+    `src/{solve.session,solve.preparation,solve.progress-monitoring,solve.error-handlers,solve.feedback,solve.auto-pr,solve.branch-errors,hive.recheck,github.batch,bidirectional-interactive,token-sanitization}.lib.mjs`,
+    `src/youtrack/youtrack-sync.mjs`,
+    `scripts/{create-github-release,format-github-release,format-release-notes}.mjs`.
+  - **Compact `solve.repository.lib.mjs`** wrap pattern from 4 lines to 3 while
+    keeping the destructure form so `eslint-rules/no-direct-gh-exec.mjs` still
+    recognizes `wrapDollarWithGhRetry` in scope.
+
+  After the fix, all three previously-failing files are at or below 1500 raw
+  lines (1500 / 1498 / 1500) and `npm run lint` would now reject any
+  re-introduction of the regression.
+
 ## 1.59.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.59.5",
+  "version": "1.59.7",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/bidirectional-interactive.lib.mjs

@@ -22,6 +22,7 @@
  * @experimental
  */
 
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller
 // Configuration constants
 const CONFIG = {
   // Minimum time between comment checks to avoid rate limiting (in ms)

package/src/contributing-guidelines.lib.mjs

@@ -9,8 +9,9 @@ if (typeof globalThis.use === 'undefined') {
   globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
 }
 
-const { $ } = await use('command-stream');
-
+const { $: __rawDollar$ } = await use('command-stream');
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry(__rawDollar$);
 /**
  * Common paths where contributing guidelines might be found
  */

package/src/github-error-reporter.lib.mjs

@@ -13,8 +13,9 @@ if (typeof globalThis.use === 'undefined') {
 }
 
 const fs = (await use('fs')).promises;
-const { $ } = await use('command-stream');
-
+const { $: __rawDollar$ } = await use('command-stream');
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry(__rawDollar$);
 const GITHUB_ISSUE_BODY_MAX_SIZE = 60000;
 const GITHUB_FILE_MAX_SIZE = 10 * 1024 * 1024;
 

package/src/github-merge-ci-signals.lib.mjs

@@ -13,8 +13,14 @@
 
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
-
-const exec = promisify(execCallback);
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
+
+const execRaw = promisify(execCallback);
+// Issue #1726: rate-limit safe gh wrapper.
+const exec = (cmd, opts) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, opts), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
 
 /**
  * Get the committed date of a specific commit from GitHub API

package/src/github-merge-ci.lib.mjs

@@ -11,8 +11,14 @@
 import { getWorkflowRunsForSha } from './github-merge.lib.mjs';
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
-
-const exec = promisify(execCallback);
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
+
+const execRaw = promisify(execCallback);
+// Issue #1726: every gh call must be rate-limit safe.
+const exec = (cmd, opts) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, opts), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
 
 /**
  * Wait for all workflow runs triggered by a specific commit to complete

package/src/github-merge-ready-sync.lib.mjs

@@ -11,8 +11,14 @@
 
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
 
-const exec = promisify(execCallback);
+const execRaw = promisify(execCallback);
+// Issue #1726: rate-limit safe gh wrapper.
+const exec = (cmd, opts) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, opts), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
 
 import { extractLinkedIssueNumber } from './github-linking.lib.mjs';
 

package/src/github-merge-repo-actions.lib.mjs

@@ -12,10 +12,16 @@
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
 import { githubLimits } from './config.lib.mjs';
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
 const execRaw = promisify(execCallback);
 // Issue #1722: raise exec maxBuffer above Node's 1 MB default for paginated gh
 // API responses (workflow runs can easily exceed that on busy repos).
-const exec = (cmd, opts = {}) => execRaw(cmd, { maxBuffer: githubLimits.bufferMaxSize, ...opts });
+// Issue #1726: wrap with rate-limit retry so a 5,000/hr quota hit waits for
+// reset instead of bubbling up as a generic fetch failure.
+const exec = (cmd, opts = {}) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, { maxBuffer: githubLimits.bufferMaxSize, ...opts }), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
 
 // Statuses we treat as "not yet finished".
 const ACTIVE_RUN_STATUSES = ['in_progress', 'queued', 'waiting', 'requested', 'pending'];

package/src/github-merge.lib.mjs

@@ -18,13 +18,24 @@ const execRaw = promisify(execCallback);
 
 import { parseGitHubUrl } from './github.lib.mjs';
 import { githubLimits } from './config.lib.mjs';
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
 
 // Issue #1722: gh api `--paginate --slurp` responses for repos with many
 // historical workflow runs can easily exceed Node's default 1 MB exec buffer
 // (observed 12.7 MB on this repo's main branch). Default to the configured
 // githubLimits.bufferMaxSize (10 MB; HIVE_MIND_GITHUB_BUFFER_MAX_SIZE) for all
 // gh calls in this file.
-const exec = (cmd, opts = {}) => execRaw(cmd, { maxBuffer: githubLimits.bufferMaxSize, ...opts });
+//
+// Issue #1726: every gh call in the merge subsystem must be rate-limit safe.
+// Wrapping the local `exec` shim ensures all 25+ call sites pick up retry
+// behaviour without per-call changes. Non-rate-limit errors continue to throw
+// so genuine failures (404, auth, malformed JSON downstream) surface to the
+// caller — they MUST NOT be swallowed as in the original /merge bug where a
+// rate-limit error was silently treated as "no workflows".
+const exec = (cmd, opts = {}) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, { maxBuffer: githubLimits.bufferMaxSize, ...opts }), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
 
 // Issue #1413: Import ready tag sync, timeline, and label constant from separate module
 // to keep this file under the 1500 line limit
@@ -1340,40 +1351,37 @@ export async function getWorkflowRunJobsCount(owner, repo, runId, verbose = fals
  * @returns {Promise<{count: number, hasWorkflows: boolean, workflows: Array<{id: number, name: string, state: string, path: string}>}>}
  */
 export async function getActiveRepoWorkflows(owner, repo, verbose = false) {
-  try {
-    const { stdout } = await exec(`gh api "repos/${owner}/${repo}/actions/workflows" --paginate --slurp`);
-    const allWorkflows = JSON.parse(stdout.trim() || '[]')
-      .flatMap(page => page.workflows || [])
-      .filter(workflow => workflow.state === 'active')
-      .map(workflow => ({ id: workflow.id, name: workflow.name, state: workflow.state, path: workflow.path }));
-
-    // GitHub Pages workflows only run after merge and never produce PR check-runs.
-    const workflows = allWorkflows.filter(wf => !wf.path.startsWith('dynamic/pages/'));
-
-    if (verbose) {
-      console.log(`[VERBOSE] /merge: Found ${allWorkflows.length} active workflows in ${owner}/${repo} (${workflows.length} PR-relevant after filtering out GitHub Pages deployment workflows)`);
-      for (const wf of allWorkflows) {
-        const filtered = wf.path.startsWith('dynamic/pages/');
-        console.log(`[VERBOSE] /merge:   - ${wf.name} (${wf.id}): ${wf.state}, path=${wf.path}${filtered ? ' [excluded: GitHub Pages deployment]' : ''}`);
-      }
-    }
+  // Issue #1726: this function previously swallowed every error as "no workflows",
+  // including GitHub API rate-limit responses. The /merge command then thought CI
+  // was unconfigured and proceeded as if checks had passed — a hard failure mode
+  // visible in the original case-study log where errors were thrown but the
+  // process exited 0.
+  //
+  // Rate-limit errors are now retried inside the local exec() wrapper. After
+  // retries are exhausted, the error MUST propagate so callers can decide
+  // whether to abort or continue — never default to "no workflows".
+  const { stdout } = await exec(`gh api "repos/${owner}/${repo}/actions/workflows" --paginate --slurp`);
+  const allWorkflows = JSON.parse(stdout.trim() || '[]')
+    .flatMap(page => page.workflows || [])
+    .filter(workflow => workflow.state === 'active')
+    .map(workflow => ({ id: workflow.id, name: workflow.name, state: workflow.state, path: workflow.path }));
+
+  // GitHub Pages workflows only run after merge and never produce PR check-runs.
+  const workflows = allWorkflows.filter(wf => !wf.path.startsWith('dynamic/pages/'));
 
-    return {
-      count: workflows.length,
-      hasWorkflows: workflows.length > 0,
-      workflows,
-    };
-  } catch (error) {
-    if (verbose) {
-      console.log(`[VERBOSE] /merge: Error fetching workflows for ${owner}/${repo}: ${error.message}`);
+  if (verbose) {
+    console.log(`[VERBOSE] /merge: Found ${allWorkflows.length} active workflows in ${owner}/${repo} (${workflows.length} PR-relevant after filtering out GitHub Pages deployment workflows)`);
+    for (const wf of allWorkflows) {
+      const filtered = wf.path.startsWith('dynamic/pages/');
+      console.log(`[VERBOSE] /merge:   - ${wf.name} (${wf.id}): ${wf.state}, path=${wf.path}${filtered ? ' [excluded: GitHub Pages deployment]' : ''}`);
     }
-    // On error, assume no workflows (safer: avoids false positives in the no-CI case)
-    return {
-      count: 0,
-      hasWorkflows: false,
-      workflows: [],
-    };
   }
+
+  return {
+    count: workflows.length,
+    hasWorkflows: workflows.length > 0,
+    workflows,
+  };
 }
 
 // Issue #1690: Re-export CI signal helpers from separate module to keep this file under 1500 lines

package/src/github-rate-limit.lib.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+/**
+ * GitHub API rate-limit detection and retry utilities.
+ *
+ * Issue #1726: Hosted runners hit GitHub's 5,000/hr core API quota and bubble
+ * the failure up as a generic 403/HTTP error. The wrappers in lib.mjs only
+ * recognise transient TCP/TLS faults; rate-limit responses fell through and
+ * crashed callers (or worse, were silently swallowed in the merge subsystem
+ * making it look like "no workflows / no checks" — see
+ * src/github-merge.lib.mjs:getActiveRepoWorkflows in the original log).
+ *
+ * The retry policy required by the issue:
+ *   wait = (resetTimestamp - now) + bufferMs (10 min) + random(jitterMs) (0-5 min)
+ *
+ * `bufferMs` and `jitterMs` already exist in src/config.lib.mjs#limitReset
+ * (added in #1236 for Claude limit waits) so we re-use them rather than
+ * duplicate constants.
+ */
+import { promisify } from 'node:util';
+import { exec as execCb } from 'node:child_process';
+
+import { limitReset, retryLimits } from './config.lib.mjs';
+
+const exec = promisify(execCb);
+
+const RATE_LIMIT_PATTERNS = ['api rate limit exceeded', 'rate limit exceeded', 'you have exceeded a secondary rate limit', 'secondary rate limit', 'abuse detection', 'was submitted too quickly'];
+
+/**
+ * Pull every plausible string out of a thrown error/result so pattern matches
+ * survive whatever shape the upstream caller gave us (Error, exec result with
+ * stdout/stderr, command-stream result, plain string, etc.).
+ */
+const collectErrorText = error => {
+  if (!error) return '';
+  if (typeof error === 'string') return error;
+  const parts = [];
+  if (typeof error.message === 'string') parts.push(error.message);
+  if (typeof error.stderr === 'string') parts.push(error.stderr);
+  else if (error.stderr && typeof error.stderr.toString === 'function') parts.push(error.stderr.toString());
+  if (typeof error.stdout === 'string') parts.push(error.stdout);
+  else if (error.stdout && typeof error.stdout.toString === 'function') parts.push(error.stdout.toString());
+  if (error.cause) parts.push(collectErrorText(error.cause));
+  return parts.join('\n');
+};
+
+/**
+ * Detect whether `error` represents a GitHub rate-limit response.
+ * Recognises both primary (5,000/hr) and secondary (abuse-detection) forms.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isRateLimitError = error => {
+  const text = collectErrorText(error).toLowerCase();
+  if (!text) return false;
+  return RATE_LIMIT_PATTERNS.some(pattern => text.includes(pattern));
+};
+
+/**
+ * Extract a `Date` for when the rate-limit window resets, in priority order:
+ *   1. `X-RateLimit-Reset` header value (Unix epoch seconds) embedded in the
+ *      error text — `gh` prints headers when --include is used and graphql
+ *      surfaces them in the error body.
+ *   2. `Retry-After` header (seconds from now).
+ *   3. None — caller falls back to a polled `gh api rate_limit` lookup.
+ *
+ * @param {unknown} error
+ * @returns {Date|null}
+ */
+export const parseRateLimitReset = error => {
+  const text = collectErrorText(error);
+  if (!text) return null;
+
+  const resetMatch = text.match(/x-ratelimit-reset:\s*(\d+)/i);
+  if (resetMatch) {
+    const epochSeconds = Number(resetMatch[1]);
+    if (Number.isFinite(epochSeconds) && epochSeconds > 0) {
+      return new Date(epochSeconds * 1000);
+    }
+  }
+
+  const retryAfterMatch = text.match(/retry-after:\s*(\d+)/i);
+  if (retryAfterMatch) {
+    const seconds = Number(retryAfterMatch[1]);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return new Date(Date.now() + seconds * 1000);
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Ask `gh api rate_limit` directly when the error didn't carry a reset header.
+ * Returns the most-restrictive (soonest) reset time across the resources we
+ * touch (core, search, graphql) so we don't resume into a still-throttled
+ * bucket.
+ *
+ * @returns {Promise<Date|null>}
+ */
+export const fetchNextRateLimitReset = async () => {
+  try {
+    // eslint-disable-next-line gh-rate-limit/no-direct-gh-exec -- this IS the rate-limit helper; calling itself recursively would loop.
+    const { stdout } = await exec('gh api rate_limit');
+    const data = JSON.parse(stdout);
+    const resources = data?.resources || {};
+    const candidates = [];
+    for (const key of ['core', 'graphql', 'search']) {
+      const r = resources[key];
+      if (r && Number.isFinite(r.reset) && r.remaining === 0) {
+        candidates.push(r.reset);
+      }
+    }
+    if (candidates.length === 0) return null;
+    const soonestEpoch = Math.min(...candidates);
+    return new Date(soonestEpoch * 1000);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Compute the absolute wait deadline that satisfies issue #1726:
+ *   reset + bufferMs (default 10 min) + random(0..jitterMs) (default 0-5 min)
+ *
+ * @param {Date|null} reset
+ * @returns {{ waitMs: number, deadline: Date, reset: Date|null, bufferMs: number, jitterMs: number }}
+ */
+export const computeRateLimitWait = (reset, now = Date.now()) => {
+  const bufferMs = limitReset.bufferMs;
+  const jitterMs = Math.floor(Math.random() * (limitReset.jitterMs + 1));
+  const resetTime = reset instanceof Date ? reset.getTime() : null;
+  const baselineWait = resetTime && resetTime > now ? resetTime - now : 0;
+  const waitMs = baselineWait + bufferMs + jitterMs;
+  return {
+    waitMs,
+    deadline: new Date(now + waitMs),
+    reset: reset || null,
+    bufferMs,
+    jitterMs,
+  };
+};
+
+/**
+ * Sleep with optional periodic countdown notifications.
+ *
+ * @param {number} ms
+ * @param {(msg: string) => Promise<void>|void} [log]
+ */
+const sleepWithCountdown = async (ms, log) => {
+  if (ms <= 0) return;
+  if (!log || ms <= 60_000) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+    return;
+  }
+  let remaining = ms;
+  const timer = setInterval(() => {
+    remaining -= 60_000;
+    if (remaining > 0) {
+      const minutes = Math.round(remaining / 60_000);
+      Promise.resolve(log(`⏳ Rate-limit wait: ${minutes} min remaining...`)).catch(() => {});
+    }
+  }, 60_000);
+  try {
+    await new Promise(resolve => setTimeout(resolve, ms));
+  } finally {
+    clearInterval(timer);
+  }
+};
+
+/**
+ * Wrap `fn` so that GitHub rate-limit errors are converted into a sleep until
+ * (resetTime + bufferMs + jitterMs) followed by a retry. Non-rate-limit errors
+ * are rethrown immediately so we don't mask programming bugs or 404s.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {object} [options]
+ * @param {number} [options.maxAttempts] - hard cap on rate-limit retries (default `retryLimits.maxApiRetries`).
+ * @param {string} [options.label] - prefix for log messages.
+ * @param {(msg: string) => Promise<void>|void} [options.log] - logger. Defaults to console.warn.
+ * @returns {Promise<T>}
+ */
+export const ghWithRateLimitRetry = async (fn, options = {}) => {
+  const maxAttempts = options.maxAttempts ?? retryLimits.maxApiRetries;
+  const label = options.label || 'gh';
+  const log = options.log || (msg => console.warn(msg));
+
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (!isRateLimitError(error)) throw error;
+
+      if (attempt === maxAttempts) {
+        await Promise.resolve(log(`❌ ${label}: rate limit still active after ${attempt} attempts; giving up.`));
+        throw error;
+      }
+
+      const reset = parseRateLimitReset(error) || (await fetchNextRateLimitReset());
+      const { waitMs, deadline, bufferMs, jitterMs } = computeRateLimitWait(reset);
+      const waitMinutes = Math.round(waitMs / 60_000);
+      const resetSummary = reset ? `reset at ${reset.toISOString()}` : 'reset time unknown (using buffer + jitter only)';
+      await Promise.resolve(log(`⏳ ${label}: GitHub API rate limit hit (attempt ${attempt}/${maxAttempts}). Waiting ${waitMinutes} min (${resetSummary}; buffer ${Math.round(bufferMs / 60_000)} min + jitter ${Math.round(jitterMs / 1000)}s) until ${deadline.toISOString()}.`));
+      await sleepWithCountdown(waitMs, log);
+    }
+  }
+  // Unreachable — loop either returns or throws.
+  throw lastError;
+};
+
+/**
+ * Convenience wrapper around child_process.exec that retries on rate-limit
+ * errors. Use it for callers that build a `gh` command string and want the
+ * existing exec-based ergonomics.
+ *
+ * @param {string} command
+ * @param {object} [options] - forwarded to ghWithRateLimitRetry, plus `execOptions`.
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+export const execGhWithRetry = async (command, options = {}) => {
+  const { execOptions, ...retryOptions } = options;
+  return ghWithRateLimitRetry(() => exec(command, execOptions), {
+    label: retryOptions.label || `gh exec (${command.split(/\s+/).slice(0, 3).join(' ')})`,
+    ...retryOptions,
+  });
+};
+
+/**
+ * Wrap a command-stream `$` tagged-template so every `$gh ...` it issues is
+ * retried on rate-limit errors. Returns a callable that delegates to the
+ * underlying `$` for non-`gh` commands and through `ghWithRateLimitRetry` for
+ * `gh ...` commands.
+ *
+ * Usage at the top of a file:
+ *   const { $: rawDollar } = await use('command-stream');
+ *   const $ = wrapDollarWithGhRetry(rawDollar);
+ *
+ * @template T
+ * @param {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>} dollar
+ * @param {object} [options] - forwarded to ghWithRateLimitRetry per call.
+ * @returns {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>}
+ */
+export const wrapDollarWithGhRetry = (dollar, options = {}) => {
+  const wrapped = (strings, ...values) => {
+    // Reconstruct the literal command for inspection (sufficient — leading
+    // `gh ` is what we care about).
+    let preview = '';
+    for (let i = 0; i < strings.length; i++) {
+      preview += strings[i];
+      if (i < values.length) preview += String(values[i] ?? '');
+    }
+    const isGh = /^\s*gh(?:\s|$)/.test(preview);
+    if (!isGh) return dollar(strings, ...values);
+    return ghWithRateLimitRetry(() => dollar(strings, ...values), {
+      label: `$gh (${preview.trim().split(/\s+/).slice(0, 3).join(' ')})`,
+      ...options,
+    });
+  };
+  // Preserve a reference to the underlying $ for consumers that need it.
+  wrapped.raw = dollar;
+  return wrapped;
+};
+
+export default {
+  isRateLimitError,
+  parseRateLimitReset,
+  fetchNextRateLimitReset,
+  computeRateLimitWait,
+  ghWithRateLimitRetry,
+  execGhWithRetry,
+  wrapDollarWithGhRetry,
+};

package/src/github.batch.lib.mjs

@@ -11,6 +11,7 @@ if (typeof globalThis.use === 'undefined') {
 import { log, cleanErrorMessage } from './lib.mjs';
 import { githubLimits, timeouts } from './config.lib.mjs';
 
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller
 /**
  * Check if a PR body/title indicates it fixes/closes/resolves a specific issue number
  * GitHub auto-closes issues when PR body contains keywords like "fixes #123", "closes #123", "resolves #123"