@link-assistant/hive-mind 2.13.4 → 2.13.5

package/src/telegram-solve-queue.throttling.lib.mjs

@@ -0,0 +1,323 @@
+/**
+ * Resource and API-limit throttling checks for the Telegram solve queue.
+ *
+ * These are the two decision functions the queue consults before starting a
+ * command: `checkSystemResources` (RAM, CPU, disk) and `checkApiLimits`
+ * (Claude/Codex session + weekly usage, GitHub API). Both return the same
+ * shape — the reasons a command must wait, whether the queue must fall back to
+ * one-at-a-time, and whether the command must be rejected outright.
+ *
+ * Extracted from telegram-solve-queue.lib.mjs (issue #2175) so that file stays
+ * under the 1350-line early-warning threshold of the CI file-headroom check
+ * (long files cause concurrent PR merge conflicts — issue #1593). They take the
+ * queue instance explicitly instead of `this`; SolveQueue keeps thin methods
+ * that delegate here, so every caller and test is unaffected.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2175
+ */
+
+import { getCachedClaudeLimits, getCachedCodexLimits, getCachedGitHubLimits, getCachedMemoryInfo, getCachedCpuInfo, getCachedDiskInfo } from './limits.lib.mjs';
+import { formatWaitingReason } from './telegram-solve-queue.helpers.lib.mjs';
+import { QUEUE_CONFIG } from './queue-config.lib.mjs';
+import { lt } from './limits-i18n.lib.mjs';
+
+/**
+ * Normalize the locale argument, which callers pass either as a bare string or
+ * inside an options object.
+ * @param {string|{locale?: string}} [options]
+ * @returns {string|null}
+ */
+export function getLocale(options = {}) {
+  if (typeof options === 'string') return options;
+  return options?.locale || null;
+}
+
+/**
+ * Suffix a waiting reason with the "waiting for the current command" note.
+ * @param {string} reason
+ * @param {string|null} locale
+ * @returns {string}
+ */
+export function appendWaitingForCurrentCommand(reason, locale) {
+  return `${reason} (${lt('queue_waiting_current_command', {}, { locale })})`;
+}
+
+/**
+ * Check system resources (RAM, CPU, disk) using cached values
+ *
+ * Uses 5-minute load average for CPU instead of instantaneous usage.
+ * This provides a more stable metric that isn't affected by brief spikes
+ * during claude process startup.
+ *
+ * Resource threshold modes are now configurable via HIVE_MIND_QUEUE_CONFIG:
+ * - 'reject': Immediately reject the command, no queueing
+ * - 'enqueue': Block all commands unconditionally until metric drops
+ * - 'dequeue-one-at-a-time': Allow one command when above threshold
+ *
+ * Default strategies:
+ * - RAM: enqueue
+ * - CPU: enqueue
+ * - DISK: enqueue (waits until disk drops below the threshold)
+ *
+ * See: https://github.com/link-assistant/hive-mind/issues/1155
+ * See: https://github.com/link-assistant/hive-mind/issues/1253
+ * See: https://github.com/link-assistant/hive-mind/issues/1981
+ *
+ * @param {number} totalProcessing - Total processing count (queue + external claude processes)
+ * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean, rejected: boolean, rejectReason: string|null}>}
+ */
+export async function checkSystemResources(queue, totalProcessing = 0, options = {}) {
+  const locale = getLocale(options);
+  const reasons = [];
+  let oneAtATime = false;
+  let rejected = false;
+  let rejectReason = null;
+  // Check RAM (using cached value)
+  const memResult = await getCachedMemoryInfo(queue.verbose);
+  if (memResult.success) {
+    const usedRatio = memResult.memory.usedPercentage / 100;
+    if (usedRatio >= QUEUE_CONFIG.thresholds.ram.value) {
+      const reason = formatWaitingReason('ram', memResult.memory.usedPercentage, QUEUE_CONFIG.thresholds.ram.value, { locale });
+      const strategy = QUEUE_CONFIG.thresholds.ram.strategy;
+      queue.recordThrottle(`ram_${strategy}`);
+      if (strategy === 'reject') {
+        rejected = true;
+        rejectReason = reason;
+      } else if (strategy === 'dequeue-one-at-a-time') {
+        oneAtATime = true;
+        if (totalProcessing > 0) {
+          reasons.push(appendWaitingForCurrentCommand(reason, locale));
+        }
+      } else {
+        // 'enqueue' - block unconditionally
+        reasons.push(reason);
+      }
+    }
+  }
+  // Check CPU using 5-minute load average (more stable than 1-minute)
+  const cpuResult = await getCachedCpuInfo(queue.verbose);
+  if (cpuResult.success) {
+    // Use loadAvg5 (5-minute average) instead of usagePercentage (1-minute based)
+    // This provides a more stable metric that isn't affected by transient spikes
+    const loadAvg5 = cpuResult.cpuLoad.loadAvg5;
+    const cpuCount = cpuResult.cpuLoad.cpuCount;
+    // Calculate usage ratio: loadAvg5 / cpuCount
+    // Load average of 1.0 per CPU = 100% utilization
+    const usageRatio = loadAvg5 / cpuCount;
+    const usagePercent = Math.min(100, Math.round(usageRatio * 100));
+    if (queue.verbose) {
+      queue.log(`CPU 5m load avg: ${loadAvg5.toFixed(2)}, cpus: ${cpuCount}, usage: ${usagePercent}%`);
+    }
+    if (usageRatio >= QUEUE_CONFIG.thresholds.cpu.value) {
+      const reason = formatWaitingReason('cpu', usagePercent, QUEUE_CONFIG.thresholds.cpu.value, { locale });
+      const strategy = QUEUE_CONFIG.thresholds.cpu.strategy;
+      queue.recordThrottle(`cpu_${strategy}`);
+      if (strategy === 'reject') {
+        rejected = true;
+        rejectReason = reason;
+      } else if (strategy === 'dequeue-one-at-a-time') {
+        oneAtATime = true;
+        if (totalProcessing > 0) {
+          reasons.push(appendWaitingForCurrentCommand(reason, locale));
+        }
+      } else {
+        // 'enqueue' - block unconditionally
+        reasons.push(reason);
+      }
+    }
+  }
+  // Check disk space (using cached value)
+  // Default strategy changed to 'reject' because queue is lost on restart anyway
+  // See: https://github.com/link-assistant/hive-mind/issues/1253
+  const diskResult = await getCachedDiskInfo(queue.verbose);
+  if (diskResult.success) {
+    // Calculate usage from free percentage
+    const usedPercent = 100 - diskResult.diskSpace.freePercentage;
+    const usedRatio = usedPercent / 100;
+    if (usedRatio >= QUEUE_CONFIG.thresholds.disk.value) {
+      const reason = formatWaitingReason('disk', usedPercent, QUEUE_CONFIG.thresholds.disk.value, { locale });
+      const strategy = QUEUE_CONFIG.thresholds.disk.strategy;
+      queue.recordThrottle(`disk_${strategy}`);
+      if (strategy === 'reject') {
+        rejected = true;
+        rejectReason = reason;
+      } else if (strategy === 'dequeue-one-at-a-time') {
+        oneAtATime = true;
+        if (totalProcessing > 0) {
+          reasons.push(appendWaitingForCurrentCommand(reason, locale));
+        }
+      } else {
+        // 'enqueue' - block unconditionally
+        reasons.push(reason);
+      }
+    }
+  }
+  return { ok: reasons.length === 0 && !rejected, reasons, oneAtATime, rejected, rejectReason };
+}
+
+/**
+ * Check API limits (Claude, GitHub) using cached values
+ *
+ * Logic per issue #1133:
+ * - CLAUDE_5_HOUR_SESSION_THRESHOLD and CLAUDE_WEEKLY_THRESHOLD use one-at-a-time mode:
+ *   when above threshold, allow exactly one command, block if claudeProcessing > 0
+ * - GitHub threshold blocks unconditionally when exceeded (ultimate restriction)
+ *
+ * Logic per issue #1159:
+ * - When tool is 'agent', 'gemini', or 'qwen', skip Claude-specific limits entirely since these tools use
+ *   different rate limiting backends. Only system resources and GitHub limits apply.
+ * - For Claude limits, only count Claude-specific processing items, not agent/codex/gemini/qwen items.
+ *   This allows non-Claude tasks to run in parallel even when Claude limits are reached.
+ *
+ * Logic per issue #1253:
+ * - All thresholds now support configurable strategies (reject, enqueue, dequeue-one-at-a-time)
+ * - Configuration via HIVE_MIND_QUEUE_CONFIG or individual env vars
+ *
+ * @param {boolean} hasRunningToolProcess - Whether matching tool processes are running (from pgrep)
+ * @param {number} toolProcessingCount - Count of matching tool items being processed in queue
+ * @param {string} tool - The tool being used ('claude', 'agent', 'codex', 'gemini', 'qwen', etc.)
+ * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean, rejected: boolean, rejectReason: string|null}>}
+ */
+export async function checkApiLimits(queue, hasRunningToolProcess = false, toolProcessingCount = 0, tool = 'claude', options = {}) {
+  const locale = getLocale(options);
+  const reasons = [];
+  let oneAtATime = false;
+  let rejected = false;
+  let rejectReason = null;
+  // Apply Claude-specific limits only when tool is 'claude'
+  // Other tools (like 'agent', 'gemini', and 'qwen') use different rate limiting backends and are not
+  // affected by Claude API limits (5-hour session, weekly limits)
+  // See: https://github.com/link-assistant/hive-mind/issues/1159
+  const applyClaudeLimits = tool === 'claude';
+  const applyCodexLimits = tool === 'codex';
+  const totalToolProcessing = toolProcessingCount + (hasRunningToolProcess ? 1 : 0);
+  // Check Claude limits (using cached value)
+  // Only applied when tool is 'claude'
+  if (applyClaudeLimits) {
+    const claudeResult = await getCachedClaudeLimits(queue.verbose);
+    if (claudeResult.success) {
+      const sessionPercent = claudeResult.usage.currentSession.percentage;
+      const weeklyPercent = claudeResult.usage.allModels.percentage;
+      // Session limit (5-hour)
+      // Configurable strategy via HIVE_MIND_QUEUE_CONFIG or HIVE_MIND_CLAUDE_5_HOUR_SESSION_STRATEGY
+      // See: https://github.com/link-assistant/hive-mind/issues/1133, #1159, #1253
+      if (sessionPercent !== null) {
+        const sessionRatio = sessionPercent / 100;
+        if (sessionRatio >= QUEUE_CONFIG.thresholds.claude5Hour.value) {
+          const reason = formatWaitingReason('claude_5_hour_session', sessionPercent, QUEUE_CONFIG.thresholds.claude5Hour.value, { locale });
+          const strategy = QUEUE_CONFIG.thresholds.claude5Hour.strategy;
+          queue.recordThrottle(sessionRatio >= 1.0 ? 'claude_5_hour_session_100' : `claude_5_hour_session_${strategy}`);
+          if (strategy === 'reject') {
+            rejected = true;
+            rejectReason = reason;
+          } else if (strategy === 'dequeue-one-at-a-time') {
+            oneAtATime = true;
+            if (totalToolProcessing > 0) {
+              reasons.push(appendWaitingForCurrentCommand(reason, locale));
+            }
+          } else {
+            // 'enqueue' - block unconditionally
+            reasons.push(reason);
+          }
+        }
+      }
+      // Weekly limit
+      // Configurable strategy via HIVE_MIND_QUEUE_CONFIG or HIVE_MIND_CLAUDE_WEEKLY_STRATEGY
+      // See: https://github.com/link-assistant/hive-mind/issues/1133, #1159, #1253
+      if (weeklyPercent !== null) {
+        const weeklyRatio = weeklyPercent / 100;
+        if (weeklyRatio >= QUEUE_CONFIG.thresholds.claudeWeekly.value) {
+          const reason = formatWaitingReason('claude_weekly', weeklyPercent, QUEUE_CONFIG.thresholds.claudeWeekly.value, { locale });
+          const strategy = QUEUE_CONFIG.thresholds.claudeWeekly.strategy;
+          queue.recordThrottle(weeklyRatio >= 1.0 ? 'claude_weekly_100' : `claude_weekly_${strategy}`);
+          if (strategy === 'reject') {
+            rejected = true;
+            rejectReason = reason;
+          } else if (strategy === 'dequeue-one-at-a-time') {
+            oneAtATime = true;
+            if (totalToolProcessing > 0) {
+              reasons.push(appendWaitingForCurrentCommand(reason, locale));
+            }
+          } else {
+            // 'enqueue' - block unconditionally
+            reasons.push(reason);
+          }
+        }
+      }
+    }
+  } else if (applyCodexLimits) {
+    const codexResult = await getCachedCodexLimits(queue.verbose);
+    if (codexResult.success) {
+      const sessionPercent = codexResult.usage.currentSession.percentage;
+      const weeklyPercent = codexResult.usage.allModels.percentage;
+      if (sessionPercent !== null) {
+        const sessionRatio = sessionPercent / 100;
+        if (sessionRatio >= QUEUE_CONFIG.thresholds.codex5Hour.value) {
+          const reason = formatWaitingReason('codex_5_hour_session', sessionPercent, QUEUE_CONFIG.thresholds.codex5Hour.value, { locale });
+          const strategy = QUEUE_CONFIG.thresholds.codex5Hour.strategy;
+          queue.recordThrottle(sessionRatio >= 1.0 ? 'codex_5_hour_session_100' : `codex_5_hour_session_${strategy}`);
+          if (strategy === 'reject') {
+            rejected = true;
+            rejectReason = reason;
+          } else if (strategy === 'dequeue-one-at-a-time') {
+            oneAtATime = true;
+            if (totalToolProcessing > 0) {
+              reasons.push(appendWaitingForCurrentCommand(reason, locale));
+            }
+          } else {
+            reasons.push(reason);
+          }
+        }
+      }
+      if (weeklyPercent !== null) {
+        const weeklyRatio = weeklyPercent / 100;
+        if (weeklyRatio >= QUEUE_CONFIG.thresholds.codexWeekly.value) {
+          const reason = formatWaitingReason('codex_weekly', weeklyPercent, QUEUE_CONFIG.thresholds.codexWeekly.value, { locale });
+          const strategy = QUEUE_CONFIG.thresholds.codexWeekly.strategy;
+          queue.recordThrottle(weeklyRatio >= 1.0 ? 'codex_weekly_100' : `codex_weekly_${strategy}`);
+          if (strategy === 'reject') {
+            rejected = true;
+            rejectReason = reason;
+          } else if (strategy === 'dequeue-one-at-a-time') {
+            oneAtATime = true;
+            if (totalToolProcessing > 0) {
+              reasons.push(appendWaitingForCurrentCommand(reason, locale));
+            }
+          } else {
+            reasons.push(reason);
+          }
+        }
+      }
+    }
+  } else if (queue.verbose) {
+    queue.log(`Claude limits not applied for --tool ${tool}`);
+  }
+  // Check GitHub limits when the active tool already has a running process.
+  // This keeps the queue behavior aligned with the existing one-at-a-time throttling model.
+  // Configurable strategy via HIVE_MIND_QUEUE_CONFIG or HIVE_MIND_GITHUB_API_STRATEGY
+  if (hasRunningToolProcess) {
+    const githubResult = await getCachedGitHubLimits(queue.verbose);
+    if (githubResult.success) {
+      const usedPercent = githubResult.githubRateLimit.usedPercentage;
+      const usedRatio = usedPercent / 100;
+      if (usedRatio >= QUEUE_CONFIG.thresholds.githubApi.value) {
+        const reason = formatWaitingReason('github', usedPercent, QUEUE_CONFIG.thresholds.githubApi.value, { locale });
+        const strategy = QUEUE_CONFIG.thresholds.githubApi.strategy;
+        queue.recordThrottle(usedRatio >= 1.0 ? 'github_100' : `github_${strategy}`);
+        if (strategy === 'reject') {
+          rejected = true;
+          rejectReason = reason;
+        } else if (strategy === 'dequeue-one-at-a-time') {
+          oneAtATime = true;
+          if (totalToolProcessing > 0) {
+            reasons.push(appendWaitingForCurrentCommand(reason, locale));
+          }
+        } else {
+          // 'enqueue' - block unconditionally
+          reasons.push(reason);
+        }
+      }
+    }
+  }
+  return { ok: reasons.length === 0 && !rejected, reasons, oneAtATime, rejected, rejectReason };
+}

package/src/transient-errors.lib.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * Single source of truth for "is this failure worth retrying?" classification
+ * of git and GitHub (`gh`) operations.
+ *
+ * Issue #2168: `gh pr create` aborted a whole solve run with
+ *
+ *   GraphQL: Something went wrong while executing your query on
+ *   2026-08-21T19:28:14Z. Please include `811E:19A5B0:3A5AA9:37C97F:6A88A6CC`
+ *   when reporting this issue.
+ *
+ * That is GitHub's generic *server-side* GraphQL failure (the GraphQL analogue
+ * of an HTTP 500 — GitHub's own docs tell you to retry it and, if it persists,
+ * report the reference id). The call site already went through
+ * `execGhWithRetry` (added for issue #1756), but the retry wrapper only
+ * recognised TCP/TLS faults and `HTTP 502/503/504`, so this error fell through
+ * the `isTransientNetworkError` check and was rethrown on the first attempt.
+ *
+ * Before this module the pattern list lived in two places — `src/lib.mjs`
+ * (`isTransientNetworkError`, superset with git-transport patterns) and
+ * `src/github-rate-limit.lib.mjs` (a deliberate copy, to avoid a circular
+ * import). Two lists meant a pattern added to one silently did not apply to
+ * the other. This module is a leaf (it imports nothing from the project) so
+ * both files can depend on it without a cycle.
+ *
+ * @see docs/case-studies/issue-2168/README.md
+ */
+
+/**
+ * Transport-level faults: the request never reached GitHub, or the connection
+ * died mid-flight. Safe to retry for both git and gh.
+ */
+export const NETWORK_TRANSIENT_PATTERNS = Object.freeze(['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'econnaborted', 'epipe', 'etimedout', 'enotfound', 'eai_again', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'tls handshake timeout', 'ssl_error', 'socket hang up', 'unexpected eof', 'client.timeout exceeded', 'context deadline exceeded', 'request timed out', 'timeout awaiting response headers']);
+
+/**
+ * GitHub-side faults: the request reached GitHub and GitHub failed to serve
+ * it. These are 5xx-class conditions — retrying is the documented remedy.
+ *
+ * Issue #2168 added the GraphQL variants. GitHub's GraphQL API answers with
+ * HTTP 200 and an `errors[]` payload for internal failures, so no HTTP status
+ * pattern can catch them; the message text is the only signal `gh` surfaces.
+ */
+export const GITHUB_SERVER_TRANSIENT_PATTERNS = Object.freeze([
+  'http 500',
+  'http 502',
+  'http 503',
+  'http 504',
+  'bad gateway',
+  'service unavailable',
+  'gateway timeout',
+  'internal server error',
+  // GraphQL internal errors (HTTP 200 + errors[]), issue #2168.
+  'something went wrong while executing your query',
+  'this may be the result of a timeout',
+  'or it could be a github bug',
+  'graphql: server error',
+  'graphql: timedout',
+  'graphql: internal error',
+  // REST/GraphQL "try again later" phrasings.
+  'please try again later',
+  'try again in a few',
+  'this diff is temporarily unavailable',
+  'temporarily unavailable due to heavy server load',
+  'heavy server load',
+  'not_available',
+]);
+
+/**
+ * git transport faults specific to the pack protocol. `git push`/`git fetch`
+ * report a broken transfer through these strings rather than an HTTP status.
+ *
+ * Issue #1957 introduced them for clone recovery; issue #2168 makes them part
+ * of the shared vocabulary so `git push` retries recognise them too.
+ */
+export const GIT_TRANSIENT_PATTERNS = Object.freeze(['unexpected disconnect', 'sideband', 'early eof', 'the remote end hung up', 'remote end hung up unexpectedly', 'rpc failed', 'fetch-pack', 'index-pack failed', 'transfer closed', 'unable to access', 'could not read from remote repository', 'failed to connect to github.com', 'operation timed out after', 'gnutls_handshake() failed', 'the requested url returned error: 5']);
+
+/**
+ * Union used by the general-purpose `isTransientNetworkError` helpers. Kept as
+ * a single flat list so a caller cannot accidentally miss a category.
+ */
+export const ALL_TRANSIENT_PATTERNS = Object.freeze([...NETWORK_TRANSIENT_PATTERNS, ...GITHUB_SERVER_TRANSIENT_PATTERNS, ...GIT_TRANSIENT_PATTERNS]);
+
+/**
+ * Pull every plausible string out of an error-ish value so pattern matches
+ * survive whatever shape the caller produced: `Error`, a plain string, a
+ * `child_process.exec` rejection (`stdout`/`stderr`), a command-stream result
+ * object (`code`/`stdout`/`stderr`), or a wrapper carrying `cause`.
+ *
+ * @param {unknown} error
+ * @param {number} [depth] - internal recursion guard for `cause` chains.
+ * @returns {string}
+ */
+export const collectErrorText = (error, depth = 0) => {
+  if (!error || depth > 5) return '';
+  if (typeof error === 'string') return error;
+  const parts = [];
+  const push = value => {
+    if (typeof value === 'string') parts.push(value);
+    else if (value && typeof value.toString === 'function') parts.push(value.toString());
+  };
+  if (typeof error.message === 'string') parts.push(error.message);
+  push(error.stderr);
+  push(error.stdout);
+  if (error.cause) parts.push(collectErrorText(error.cause, depth + 1));
+  // Last resort: an error-ish object whose text only lives in a custom
+  // `toString`. Raw byte payloads are deliberately excluded — issue #1829 pins
+  // that a bare Buffer carries no classifiable text (its bytes may be an
+  // arbitrary command payload rather than a failure description).
+  if (parts.length === 0 && !ArrayBuffer.isView(error) && typeof error.toString === 'function') push(error);
+  return parts.join('\n');
+};
+
+const matchPattern = (error, patterns) => {
+  const text = collectErrorText(error).toLowerCase();
+  if (!text) return null;
+  return patterns.find(pattern => text.includes(pattern)) || null;
+};
+
+/**
+ * True when `error` is a transient transport/server fault that a retry can fix.
+ * Superset covering network, GitHub 5xx/GraphQL-internal, and git-pack faults.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isTransientNetworkError = error => matchPattern(error, ALL_TRANSIENT_PATTERNS) !== null;
+
+/**
+ * True when `error` is a GitHub server-side fault (5xx or GraphQL internal).
+ * Narrower than `isTransientNetworkError` — used for logging/classification.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isGitHubServerError = error => matchPattern(error, GITHUB_SERVER_TRANSIENT_PATTERNS) !== null;
+
+/**
+ * Return the first transient pattern that matched, or `null` when the error is
+ * not classified as transient. Exposed so retry wrappers can log *why* they
+ * retried (or, in verbose mode, why they refused to).
+ *
+ * @param {unknown} error
+ * @returns {string|null}
+ */
+export const matchTransientPattern = error => matchPattern(error, ALL_TRANSIENT_PATTERNS);
+
+/**
+ * Extract GitHub's support reference id from an error.
+ *
+ * Two shapes are recognised:
+ *   - the `X-GitHub-Request-Id: AAAA:BBBB:...` response header, and
+ *   - the GraphQL prose form: ``Please include `811E:19A5B0:...` when
+ *     reporting this issue.``
+ *
+ * Issue #2168: without this id a GitHub support report (or an upstream bug
+ * report) is unactionable, and the id was previously only visible by reading
+ * the raw failure text by hand.
+ *
+ * @param {unknown} error
+ * @returns {string|null}
+ */
+export const parseGitHubRequestId = error => {
+  const text = collectErrorText(error);
+  if (!text) return null;
+  const headerMatch = text.match(/x-github-request-id:\s*([0-9A-Fa-f]{4,}(?::[0-9A-Fa-f]{4,})+)/i);
+  if (headerMatch) return headerMatch[1];
+  const proseMatch = text.match(/please include\s+`?([0-9A-Fa-f]{4,}(?::[0-9A-Fa-f]{4,})+)`?/i);
+  if (proseMatch) return proseMatch[1];
+  return null;
+};
+
+/**
+ * Full classification of a failure, for retry decisions *and* for diagnostics.
+ *
+ * @param {unknown} error
+ * @returns {{transient: boolean, category: 'network'|'github-server'|'git-transport'|null, matchedPattern: string|null, requestId: string|null, text: string}}
+ */
+export const describeTransientError = error => {
+  const text = collectErrorText(error);
+  const lowered = text.toLowerCase();
+  const find = patterns => patterns.find(pattern => lowered.includes(pattern)) || null;
+
+  const networkPattern = find(NETWORK_TRANSIENT_PATTERNS);
+  const serverPattern = find(GITHUB_SERVER_TRANSIENT_PATTERNS);
+  const gitPattern = find(GIT_TRANSIENT_PATTERNS);
+
+  let category = null;
+  let matchedPattern = null;
+  if (networkPattern) {
+    category = 'network';
+    matchedPattern = networkPattern;
+  } else if (serverPattern) {
+    category = 'github-server';
+    matchedPattern = serverPattern;
+  } else if (gitPattern) {
+    category = 'git-transport';
+    matchedPattern = gitPattern;
+  }
+
+  return {
+    transient: category !== null,
+    category,
+    matchedPattern,
+    requestId: parseGitHubRequestId(error),
+    text,
+  };
+};
+
+/**
+ * One-line, log-friendly summary of a classification. Used by the retry
+ * wrappers so every retry decision (and every give-up) is traceable in the
+ * solve log without turning on verbose mode.
+ *
+ * @param {ReturnType<typeof describeTransientError>} description
+ * @returns {string}
+ */
+export const formatTransientDiagnostics = description => {
+  if (!description) return '';
+  const bits = [];
+  bits.push(description.transient ? `transient=yes category=${description.category} pattern="${description.matchedPattern}"` : 'transient=no');
+  if (description.requestId) bits.push(`github-request-id=${description.requestId}`);
+  return bits.join(' ');
+};
+
+export default {
+  NETWORK_TRANSIENT_PATTERNS,
+  GITHUB_SERVER_TRANSIENT_PATTERNS,
+  GIT_TRANSIENT_PATTERNS,
+  ALL_TRANSIENT_PATTERNS,
+  collectErrorText,
+  isTransientNetworkError,
+  isGitHubServerError,
+  matchTransientPattern,
+  parseGitHubRequestId,
+  describeTransientError,
+  formatTransientDiagnostics,
+};