@link-assistant/hive-mind 2.13.4 → 2.13.5

package/src/codex.lib.mjs

@@ -7,7 +7,11 @@ import { ensureUseM } from './use-m-bootstrap.lib.mjs';
 if (typeof globalThis.use === 'undefined') {
   await ensureUseM();
 }
-const { $ } = await use('command-stream');
+const { $: __rawDollar$ } = await use('command-stream');
+// Issue #2168: retry transient git network failures (push/fetch/pull) the same
+// way `gh` calls are retried, for every command run through this module's `$`.
+const { wrapDollarWithGitRetry } = await import('./git-retry.lib.mjs');
+const $ = wrapDollarWithGitRetry(__rawDollar$);
 const fs = (await use('fs')).promises;
 const path = (await use('path')).default;
 const os = (await use('os')).default;
@@ -44,127 +48,10 @@ import Decimal from 'decimal.js-light';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 import { CODEX_CACHE_READ_USAGE_PATHS, CODEX_CACHE_WRITE_USAGE_PATHS, CODEX_MODEL_DIAGNOSTIC_PATHS, CODEX_REASONING_USAGE_PATHS, CODEX_USAGE_FIELD_NAMES, createCodexTokenFieldAvailability, getFirstObservedNumber, hasAnyObservedPath, hasOwnPath } from './codex.usage-fields.lib.mjs';
 const CODEX_LONG_CONTEXT_PRICE_THRESHOLD = 272000;
-const CODEX_COMPACT_API_ENDPOINT = '/responses/compact';
 const getCodexExecEnv = (verbose = false) => (verbose ? { ...process.env, RUST_LOG: 'debug' } : { ...process.env });
-
-const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const getCodexDiagnosticValue = (line, key) => {
-  const match = line.match(new RegExp(`${escapeRegExp(key)}=(?:"([^"]*)"|([^\\s")]+))`));
-  return match?.[1] ?? match?.[2] ?? null;
-};
-const getCodexDiagnosticInteger = (line, key) => {
-  const value = getCodexDiagnosticValue(line, key);
-  if (value === null) return null;
-  const parsed = Number.parseInt(value, 10);
-  return Number.isFinite(parsed) ? parsed : null;
-};
-const getCodexDiagnosticTimestamp = line => {
-  const eventTimestamp = getCodexDiagnosticValue(line, 'event.timestamp');
-  if (eventTimestamp) return eventTimestamp;
-  const logPrefixMatch = line.match(/^\[(\d{4}-\d{2}-\d{2}T[^\]]+Z)\]/u);
-  return logPrefixMatch?.[1] ?? null;
-};
-const isSuccessfulCodexCompactRequestLine = line => {
-  if (!line.includes('codex_otel.log_only:')) return false;
-  if (!line.includes('event.name="codex.api_request"')) return false;
-  if (!line.includes(`endpoint="${CODEX_COMPACT_API_ENDPOINT}"`)) return false;
-  const statusCode = getCodexDiagnosticInteger(line, 'http.response.status_code');
-  return statusCode === null || (statusCode >= 200 && statusCode < 300);
-};
-
-const splitTokenCountEvenly = (total, partCount) => {
-  const safeTotal = Math.max(0, Math.round(total || 0));
-  const safePartCount = Math.max(1, Math.round(partCount || 1));
-  const base = Math.floor(safeTotal / safePartCount);
-  let remainder = safeTotal % safePartCount;
-  return Array.from({ length: safePartCount }, () => {
-    const value = base + (remainder > 0 ? 1 : 0);
-    if (remainder > 0) remainder--;
-    return value;
-  });
-};
-const splitCodexSubSessionInputTokens = (total, partCount, autoCompactTokenLimit = null) => {
-  const safeTotal = Math.max(0, Math.round(total || 0));
-  const safePartCount = Math.max(1, Math.round(partCount || 1));
-  const safeLimit = Number.isFinite(autoCompactTokenLimit) && autoCompactTokenLimit > 0 ? Math.round(autoCompactTokenLimit) : null;
-  if (safePartCount <= 1) return [safeTotal];
-  if (safeLimit && safeTotal > safeLimit * (safePartCount - 1)) {
-    const chunks = [];
-    let remaining = safeTotal;
-    for (let i = 0; i < safePartCount - 1; i++) {
-      const chunk = Math.min(safeLimit, remaining);
-      chunks.push(chunk);
-      remaining -= chunk;
-    }
-    chunks.push(Math.max(0, remaining));
-    return chunks;
-  }
-  return splitTokenCountEvenly(safeTotal, safePartCount);
-};
-const splitTokenCountByWeights = (total, weights) => {
-  const safeTotal = Math.max(0, Math.round(total || 0));
-  const safeWeights = Array.isArray(weights) && weights.length > 0 ? weights.map(weight => Math.max(0, weight || 0)) : [1];
-  const weightTotal = safeWeights.reduce((sum, weight) => sum + weight, 0);
-  if (weightTotal <= 0) return splitTokenCountEvenly(safeTotal, safeWeights.length);
-  let allocated = 0;
-  return safeWeights.map((weight, index) => {
-    if (index === safeWeights.length - 1) return Math.max(0, safeTotal - allocated);
-    const value = Math.floor((safeTotal * weight) / weightTotal);
-    allocated += value;
-    return value;
-  });
-};
-const rebuildCodexSubSessionsFromCompactifications = tokenUsage => {
-  const compactifications = Array.isArray(tokenUsage.compactifications) ? tokenUsage.compactifications : [];
-  if (compactifications.length === 0 || (tokenUsage.stepCount || 0) === 0) {
-    tokenUsage.subSessions = Array.isArray(tokenUsage.subSessions) ? tokenUsage.subSessions : [];
-    return;
-  }
-
-  const subSessionCount = compactifications.length + 1;
-  const inputChunks = splitCodexSubSessionInputTokens(tokenUsage.inputTokens || 0, subSessionCount, tokenUsage.autoCompactTokenLimit);
-  const cacheWriteChunks = splitTokenCountByWeights(tokenUsage.cacheWriteTokens || 0, inputChunks);
-  const cacheReadChunks = splitTokenCountByWeights(tokenUsage.cacheReadTokens || 0, inputChunks);
-  const outputChunks = splitTokenCountByWeights(tokenUsage.outputTokens || 0, inputChunks);
-  tokenUsage.subSessions = inputChunks.map((inputTokens, index) => {
-    const cacheCreationTokens = cacheWriteChunks[index] || 0;
-    const outputTokens = outputChunks[index] || 0;
-    return {
-      inputTokens,
-      cacheCreationTokens,
-      cacheReadTokens: cacheReadChunks[index] || 0,
-      outputTokens,
-      messageCount: null,
-      peakContextUsage: getCumulativeContextInputTokens({ inputTokens, cacheCreationTokens }),
-      peakOutputUsage: outputTokens,
-      estimated: true,
-      source: 'codex.compact-diagnostics',
-      compactBoundaryBefore: index === 0 ? null : compactifications[index - 1] || null,
-    };
-  });
-};
-const recordCodexCompactification = (line, tokenUsage) => {
-  if (!isSuccessfulCodexCompactRequestLine(line)) return;
-  const timestamp = getCodexDiagnosticTimestamp(line);
-  const conversationId = getCodexDiagnosticValue(line, 'conversation.id');
-  const existing = tokenUsage.compactifications.find(compact => compact.timestamp === timestamp && compact.conversationId === conversationId);
-  if (existing) return;
-  tokenUsage.compactifications.push({
-    timestamp,
-    preTokens: null,
-    trigger: 'auto',
-    source: 'codex.responses.compact',
-    conversationId: conversationId || null,
-  });
-};
-const parseCodexDiagnosticLine = (line, tokenUsage) => {
-  const contextLimit = getCodexDiagnosticInteger(line, 'context_window') ?? getCodexDiagnosticInteger(line, 'model_context_window');
-  if (contextLimit !== null) tokenUsage.contextLimit = contextLimit;
-
-  const autoCompactTokenLimit = getCodexDiagnosticInteger(line, 'auto_compact_token_limit') ?? getCodexDiagnosticInteger(line, 'model_auto_compact_token_limit');
-  if (autoCompactTokenLimit !== null) tokenUsage.autoCompactTokenLimit = autoCompactTokenLimit;
-  recordCodexCompactification(line, tokenUsage);
-};
+// Issue #2175: diagnostic-line parsing lives in its own module to keep this file
+// under the 1350-line warning threshold.
+import { parseCodexDiagnosticLine, rebuildCodexSubSessionsFromCompactifications } from './codex.diagnostics.lib.mjs';
 export const createCodexTokenUsage = requestedModelId => ({
   inputTokens: 0,
   outputTokens: 0,

package/src/config.lib.mjs

@@ -115,6 +115,15 @@ export const retryLimits = {
   maxForkRetries: parseIntWithDefault('HIVE_MIND_MAX_FORK_RETRIES', 5),
   maxVerifyRetries: parseIntWithDefault('HIVE_MIND_MAX_VERIFY_RETRIES', 5),
   maxApiRetries: parseIntWithDefault('HIVE_MIND_MAX_API_RETRIES', 3),
+  // Issue #2168: GitHub's own 5xx / GraphQL-internal failures ("Something went
+  // wrong while executing your query") are usually over within seconds, but 3
+  // attempts at 1s+2s was too tight to ride one out. These budgets are used by
+  // `ghWithRateLimitRetry` for the transient (non-rate-limit) branch.
+  maxGitHubTransientRetries: parseIntWithDefault('HIVE_MIND_MAX_GITHUB_TRANSIENT_RETRIES', 6),
+  initialGitHubTransientDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_GITHUB_TRANSIENT_DELAY_MS', 2000),
+  // Issue #2168: network-facing git operations (push/fetch/clone) get the same
+  // treatment via `gitCmdRetry` in src/lib.mjs.
+  maxGitRetries: parseIntWithDefault('HIVE_MIND_MAX_GIT_RETRIES', 5),
   retryBackoffMultiplier: parseFloatWithDefault('HIVE_MIND_RETRY_BACKOFF_MULTIPLIER', 2),
   // Unified retry config for all transient API errors (Overloaded, 503, Internal Server Error)
   // Issue #2169: count backstop only. With the defaults below (3 min → 30 min backoff) the 12-hour

package/src/gemini.lib.mjs

@@ -8,7 +8,11 @@ if (typeof globalThis.use === 'undefined') {
   await ensureUseM();
 }
 
-const { $ } = await use('command-stream');
+const { $: __rawDollar$ } = await use('command-stream');
+// Issue #2168: retry transient git network failures (push/fetch/pull) the same
+// way `gh` calls are retried, for every command run through this module's `$`.
+const { wrapDollarWithGitRetry } = await import('./git-retry.lib.mjs');
+const $ = wrapDollarWithGitRetry(__rawDollar$);
 
 import { log, buildToolErrorMessage } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';

package/src/git-retry.lib.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/**
+ * Retry wrapper for network-facing *git* commands.
+ *
+ * Issue #2168 asked for retry on "any git/github operation". The `gh` half was
+ * already covered by src/github-rate-limit.lib.mjs (`wrapDollarWithGhRetry`),
+ * but the ~36 `git push` / `git fetch` / `git pull` call sites scattered across
+ * src/*.mjs had no retry at all: a single `fatal: unable to access ...` or
+ * `RPC failed; curl 56 ... connection reset` aborted the whole session.
+ *
+ * Wrapping every call site by hand would have to be repeated for every new call
+ * site, so the retry is installed on command-stream's `$` tag instead - exactly
+ * the shape already used for `gh`. Anything that runs through a wrapped `$`
+ * gets the retry for free, and the existing ESLint rules that push code towards
+ * the wrapped `$` keep new call sites covered.
+ *
+ * Only *network* subcommands are retried. Local plumbing (`git commit`,
+ * `git checkout`, ...) is deterministic: re-running it cannot turn a failure
+ * into a success, and a blind second attempt could mask the real error.
+ *
+ * `git clone` is intentionally NOT in the list: a partially-written destination
+ * directory makes the second attempt fail with "already exists and is not an
+ * empty directory", which would replace the real (transient) diagnosis with a
+ * confusing one. Repository cloning in this codebase goes through
+ * `gh repo clone`, which is already covered by the gh retry wrapper.
+ */
+
+// Subcommands that talk to the remote and are safe to re-run verbatim.
+const GIT_NETWORK_SUBCOMMANDS = Object.freeze(['push', 'fetch', 'pull', 'ls-remote']);
+
+/**
+ * Decide whether `command` is a git command that reaches the network.
+ *
+ * Handles the `git -C <dir> push ...` and `git --no-pager fetch ...` forms by
+ * skipping leading option tokens (and their argument, for the options that take
+ * one) before looking at the subcommand.
+ *
+ * @param {string} command - the reconstructed shell command line.
+ * @returns {string|null} the matched subcommand, or null when not a git network command.
+ */
+export const matchGitNetworkCommand = command => {
+  const text = String(command ?? '').trim();
+  if (!/^git(?:\s|$)/.test(text)) return null;
+  const tokens = text.split(/\s+/).slice(1);
+  const optionsWithValue = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path']);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token.startsWith('-')) {
+      // `git clone` is excluded on purpose - see the module header.
+      return GIT_NETWORK_SUBCOMMANDS.includes(token) ? token : null;
+    }
+    if (optionsWithValue.has(token)) i++;
+  }
+  return null;
+};
+
+/**
+ * Wrap command-stream's `$` so that git network commands are retried on
+ * transient failures. Non-git commands (and local git plumbing) are passed
+ * straight through, so the wrapper is safe to install globally.
+ *
+ * @template T
+ * @param {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>} dollar
+ * @param {object} [options] - forwarded to gitCmdRetry per call.
+ * @returns {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>}
+ */
+export const wrapDollarWithGitRetry = (dollar, options = {}) => {
+  if (typeof dollar !== 'function') {
+    throw new TypeError(`Expected command-stream's $ export to be a function, received ${typeof dollar}.`);
+  }
+  const wrapped = (strings, ...values) => {
+    // Options-call form: `$({ cwd })` returns a new tag bound to those options.
+    if (strings && !Array.isArray(strings) && typeof strings === 'object') {
+      return wrapDollarWithGitRetry(dollar(strings), options);
+    }
+    let preview = '';
+    for (let i = 0; i < strings.length; i++) {
+      preview += strings[i];
+      if (i < values.length) preview += String(values[i] ?? '');
+    }
+    const subcommand = matchGitNetworkCommand(preview);
+    if (!subcommand) return dollar(strings, ...values);
+    // Lazy import keeps this module free of a static cycle with lib.mjs.
+    return (async () => {
+      const { gitCmdRetry } = await import('./lib.mjs');
+      return gitCmdRetry(() => dollar(strings, ...values), {
+        label: `git ${subcommand}`,
+        ...options,
+      });
+    })();
+  };
+  wrapped.raw = typeof dollar.raw === 'function' ? dollar.raw : dollar;
+  return wrapped;
+};
+
+export default { matchGitNetworkCommand, wrapDollarWithGitRetry };

package/src/github-pr-idempotency.lib.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Make `gh pr create` safe to retry.
+ *
+ * Issue #2168: `gh pr create` aborted a solve run on GitHub's transient
+ * GraphQL internal error. The fix is to retry — but a mutation that failed
+ * *after* GitHub committed it (a 5xx on the response path, not the request
+ * path) would make the retry fail again with
+ *
+ *   GraphQL: A pull request already exists for konard:issue-4804-203a323f30b1.
+ *
+ * which is not transient and would abort the run just the same, only one step
+ * later. Retrying a write is only correct when the write is idempotent, so
+ * this module turns "already exists" into "here is the pull request you were
+ * trying to create".
+ */
+
+/**
+ * Combined text of an error-ish value, mirroring the collector used by the
+ * transient classifier.
+ */
+const errorText = error => {
+  if (!error) return '';
+  if (typeof error === 'string') return error;
+  const parts = [];
+  if (typeof error.message === 'string') parts.push(error.message);
+  if (error.stderr) parts.push(error.stderr.toString());
+  if (error.stdout) parts.push(error.stdout.toString());
+  if (error.cause) parts.push(errorText(error.cause));
+  return parts.join('\n');
+};
+
+/**
+ * Detect `gh pr create`'s "a pull request already exists" rejection.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isPullRequestAlreadyExistsError = error => {
+  const text = errorText(error).toLowerCase();
+  if (!text) return false;
+  return text.includes('a pull request already exists') || (text.includes('pull request') && text.includes('already exists'));
+};
+
+/**
+ * Look up the pull request that already exists for `headRef`.
+ *
+ * `gh pr list --head` matches on the branch name; for a fork the head is
+ * `owner:branch`, and GitHub still indexes it under the bare branch name, so
+ * the bare name is what we query with.
+ *
+ * @param {object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.headRef - branch name, with or without an `owner:` prefix.
+ * @param {(command: string, options?: object) => Promise<{stdout: string}>} params.execGh - retry-wrapped exec (e.g. `execGhWithRetry`).
+ * @param {(msg: string, options?: object) => Promise<void>|void} [params.log]
+ * @returns {Promise<string|null>} PR URL, or null when none could be resolved.
+ */
+export const findExistingPullRequestUrl = async ({ owner, repo, headRef, execGh, log = null }) => {
+  const branch = String(headRef || '').includes(':') ? String(headRef).split(':').pop() : String(headRef || '');
+  if (!branch) return null;
+  try {
+    const { stdout } = await execGh(`gh pr list --repo ${owner}/${repo} --head ${branch} --state all --limit 1 --json url,number,state`, {
+      label: 'gh pr list (existing PR lookup)',
+    });
+    const parsed = JSON.parse((stdout || '[]').toString().trim() || '[]');
+    const first = Array.isArray(parsed) ? parsed[0] : null;
+    if (first?.url) {
+      if (log) await Promise.resolve(log(`   Recovered existing PR #${first.number} (${first.state}) for head ${branch}: ${first.url}`));
+      return first.url;
+    }
+  } catch (lookupError) {
+    if (log) await Promise.resolve(log(`   Could not look up the existing PR for head ${branch}: ${lookupError.message}`, { level: 'warn' }));
+  }
+  return null;
+};
+
+export default {
+  isPullRequestAlreadyExistsError,
+  findExistingPullRequestUrl,
+};

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

@@ -21,6 +21,8 @@ import { promisify } from 'node:util';
 import { exec as execCb } from 'node:child_process';
 
 import { limitReset, retryLimits } from './config.lib.mjs';
+import { matchGitNetworkCommand } from './git-retry.lib.mjs';
+import { collectErrorText, describeTransientError, formatTransientDiagnostics, isTransientNetworkError, GITHUB_SERVER_TRANSIENT_PATTERNS } from './transient-errors.lib.mjs';
 
 const exec = promisify(execCb);
 
@@ -34,24 +36,6 @@ const githubRateLimitLogging = {
   lastUsageByResource: null,
 };
 
-/**
- * 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.
@@ -288,22 +272,18 @@ const sleepWithCountdown = async (ms, log) => {
 };
 
 /**
- * Patterns matched against an error's combined message/stderr/stdout to decide
- * whether the failure is a transient network/edge fault that deserves a retry.
- * Mirrors `isTransientNetworkError` in `src/lib.mjs` (issue #1536); duplicated
- * here to avoid a circular import — `lib.mjs` already imports from this file.
+ * Transient-fault classification now lives in `src/transient-errors.lib.mjs`
+ * (issue #2168). Both this module and `src/lib.mjs` import from that leaf
+ * module so a pattern added once applies everywhere; previously each file kept
+ * its own copy of the list and `GraphQL: Something went wrong while executing
+ * your query` was missing from both.
  *
  * Issue #1756: `gh pr create` failed with `HTTP 504: 504 Gateway Timeout
  * (https://api.github.com/graphql)`. `execGhWithRetry`/`ghWithRateLimitRetry`
  * only handled rate-limit errors before — a single 504 was fatal.
+ * Issue #2168: the same call failed with GitHub's GraphQL internal error,
+ * which is not an HTTP status at all and so was not covered by #1756.
  */
-const TRANSIENT_NETWORK_PATTERNS = ['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'etimedout', 'enotfound', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'http 502', 'http 503', 'http 504', 'bad gateway', 'service unavailable', 'gateway timeout', 'tls handshake timeout', 'ssl_error', 'socket hang up', 'unexpected eof'];
-
-const isTransientNetworkError = error => {
-  const text = collectErrorText(error).toLowerCase();
-  if (!text) return false;
-  return TRANSIENT_NETWORK_PATTERNS.some(pattern => text.includes(pattern));
-};
 
 /**
  * Patterns that identify a *transient* failure of GitHub's compare/diff
@@ -318,13 +298,15 @@ const isTransientNetworkError = error => {
  * used to treat this as fatal and abort the whole session. These patterns let
  * callers recognise the transient case and degrade gracefully instead.
  *
- * Note: HTTP 500 is deliberately matched here (and NOT in
- * `TRANSIENT_NETWORK_PATTERNS`) because a bare 500 from arbitrary endpoints is
- * too broad to retry blindly; it is only safe to treat as transient for the
- * compare endpoint, alongside the explicit "not_available" / "heavy server
- * load" markers.
+ * Issue #2168: these markers are now the shared
+ * `GITHUB_SERVER_TRANSIENT_PATTERNS` list. HTTP 500 used to be matched only
+ * here, on the theory that a bare 500 is too broad to retry blindly. That
+ * carve-out is what let GitHub's GraphQL internal error abort `gh pr create`,
+ * so 5xx/GraphQL-internal responses are now retryable everywhere; writes that
+ * could double-apply are made idempotent at the call site instead (see
+ * `src/github-pr-idempotency.lib.mjs`).
  */
-const TRANSIENT_COMPARE_API_PATTERNS = ['this diff is temporarily unavailable', 'temporarily unavailable due to heavy server load', 'heavy server load', 'not_available', 'http 500', 'http 502', 'http 503', 'http 504'];
+const TRANSIENT_COMPARE_API_PATTERNS = GITHUB_SERVER_TRANSIENT_PATTERNS;
 
 /**
  * Detect whether `error` represents a transient failure of GitHub's
@@ -364,8 +346,10 @@ const isTransientCompareApiError = error => {
  */
 export const ghWithRateLimitRetry = async (fn, options = {}) => {
   const maxAttempts = options.maxAttempts ?? retryLimits.maxApiRetries;
-  const transientMaxAttempts = options.transientMaxAttempts ?? retryLimits.maxApiRetries;
-  const transientDelay = options.transientDelay ?? 1000;
+  // Issue #2168: the transient budget used to reuse `maxApiRetries` (3 attempts
+  // at 1s + 2s). GitHub's GraphQL internal errors routinely outlast that.
+  const transientMaxAttempts = options.transientMaxAttempts ?? retryLimits.maxGitHubTransientRetries;
+  const transientDelay = options.transientDelay ?? retryLimits.initialGitHubTransientDelayMs;
   const transientBackoff = options.transientBackoff ?? 2;
   const label = options.label || 'gh';
   const log = options.log || (msg => console.warn(msg));
@@ -403,18 +387,24 @@ export const ghWithRateLimitRetry = async (fn, options = {}) => {
         continue;
       }
 
-      if (isTransientNetworkError(error)) {
+      // Issue #2168: classify once, and log the classification on every path —
+      // including the "we are not retrying this" path — so the next unknown
+      // failure mode can be diagnosed from the session log without a rerun.
+      const description = describeTransientError(error);
+
+      if (description.transient) {
         transientAttempts++;
         if (transientAttempts >= transientMaxAttempts) {
-          await Promise.resolve(log(`❌ ${label}: transient network error persisted after ${transientAttempts} attempts; giving up.`));
+          await Promise.resolve(log(`❌ ${label}: transient network error persisted after ${transientAttempts} attempts; giving up. [${formatTransientDiagnostics(description)}]`));
           throw error;
         }
         const waitMs = transientDelay * Math.pow(transientBackoff, transientAttempts - 1);
-        await Promise.resolve(log(`⚠️ ${label}: transient network error (attempt ${transientAttempts}/${transientMaxAttempts}), retrying in ${Math.round(waitMs / 1000)}s...`));
+        await Promise.resolve(log(`⚠️ ${label}: transient network error (attempt ${transientAttempts}/${transientMaxAttempts}), retrying in ${Math.round(waitMs / 1000)}s... [${formatTransientDiagnostics(description)}]`));
         await sleepWithCountdown(waitMs, log);
         continue;
       }
 
+      await Promise.resolve(log(`ℹ️ ${label}: error is not retryable [${formatTransientDiagnostics(description)}]; propagating to caller.`));
       throw error;
     }
   }
@@ -480,7 +470,20 @@ export const wrapDollarWithGhRetry = (dollar, options = {}) => {
       if (i < values.length) preview += String(values[i] ?? '');
     }
     const isGh = /^\s*gh(?:\s|$)/.test(preview);
-    if (!isGh) return dollar(strings, ...values);
+    if (!isGh) {
+      // Issue #2168: "retry for any git/github operation". Network-facing git
+      // commands (`git push`/`fetch`/`pull`/`ls-remote`) get the same treatment
+      // here so every module already using the wrapped `$` is covered without
+      // touching its call sites. Everything else passes straight through.
+      const gitSubcommand = matchGitNetworkCommand(preview);
+      if (gitSubcommand) {
+        return (async () => {
+          const { gitCmdRetry } = await import('./lib.mjs');
+          return gitCmdRetry(() => dollar(strings, ...values), { label: `$git (${gitSubcommand})`, ...options });
+        })();
+      }
+      return dollar(strings, ...values);
+    }
     return ghWithRateLimitRetry(() => dollar(strings, ...values), {
       label: `$gh (${preview.trim().split(/\s+/).slice(0, 3).join(' ')})`,
       ...options,