@link-assistant/hive-mind 1.65.1 → 1.66.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 1.66.0
+
+### Minor Changes
+
+- f744d5a: Add internationalisation (i18n) for user-facing terminal output and the Telegram bot. Translations are stored in `links-notation` files under `src/locales/` (`en`, `ru`, `zh`, `hi`) and loaded via `lino-objects-codec`. Adds a `--language <en|ru|zh|hi>` option to `solve`, `hive`, `task`, and `review` (defaults to detected system locale). The Telegram bot picks each user's language from `ctx.from.language_code` with a per-user override settable through a new `/language <code|default>` command (in-memory, resets on bot restart). Built-in commands `/limits`, `/version`, `/solve`, `/hive`, and `/language` now reply in the user's selected language. AI prompts are intentionally untouched - only human-facing strings are translated.
+
+## 1.65.2
+
+### Patch Changes
+
+- 0214c9e: Retry transient 5xx/network errors across all `gh` exec sites. Previously a single 504 from the GitHub GraphQL endpoint could abort `solve` during `gh pr create`. The retry helper now handles HTTP 502/503/504, socket hang up, ECONNRESET, ETIMEDOUT, and TLS handshake timeouts in addition to rate-limit errors, with a separate retry budget and exponential backoff. All direct `execAsync('gh ...')` sites are routed through `execGhWithRetry`.
+
 ## 1.65.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.65.1",
+  "version": "1.66.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -76,6 +76,7 @@
     "dayjs": "^1.11.19",
     "decimal.js-light": "^2.5.1",
     "lino-arguments": "^0.3.0",
+    "lino-objects-codec": "^0.3.6",
     "secretlint": "^11.2.5",
     "semver": "^7.7.3"
   },

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

@@ -169,46 +169,98 @@ 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.
+ *
+ * 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.
+ */
+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));
+};
+
 /**
  * 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.
+ * (resetTime + bufferMs + jitterMs) followed by a retry. Transient network
+ * errors (504/502/503, socket hang up, TLS timeouts) get exponential backoff
+ * and a separate retry budget. Other errors are rethrown immediately so we
+ * don't mask programming bugs or 404s.
+ *
+ * Issue #1726 — rate-limit retry. Issue #1756 — transient network retry.
  *
  * @template T
  * @param {() => Promise<T>} fn
  * @param {object} [options]
  * @param {number} [options.maxAttempts] - hard cap on rate-limit retries (default `retryLimits.maxApiRetries`).
+ * @param {number} [options.transientMaxAttempts] - hard cap on transient network retries (default `retryLimits.maxApiRetries`).
+ * @param {number} [options.transientDelay] - initial transient retry delay in ms (default 1000).
+ * @param {number} [options.transientBackoff] - backoff multiplier for transient retries (default 2).
  * @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 transientMaxAttempts = options.transientMaxAttempts ?? retryLimits.maxApiRetries;
+  const transientDelay = options.transientDelay ?? 1000;
+  const transientBackoff = options.transientBackoff ?? 2;
   const label = options.label || 'gh';
   const log = options.log || (msg => console.warn(msg));
 
+  // Two independent retry budgets — a long string of rate-limit responses
+  // shouldn't burn the transient-error retries, and vice versa.
+  let rateLimitAttempts = 0;
+  let transientAttempts = 0;
   let lastError;
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+  // Hard cap so a permanently broken endpoint can't loop forever — sum of
+  // both budgets plus a safety margin.
+  const hardCap = maxAttempts + transientMaxAttempts + 1;
+
+  for (let i = 0; i < hardCap; i++) {
     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;
+      if (isRateLimitError(error)) {
+        rateLimitAttempts++;
+        if (rateLimitAttempts >= maxAttempts) {
+          await Promise.resolve(log(`❌ ${label}: rate limit still active after ${rateLimitAttempts} 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 ${rateLimitAttempts}/${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);
+        continue;
       }
 
-      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);
+      if (isTransientNetworkError(error)) {
+        transientAttempts++;
+        if (transientAttempts >= transientMaxAttempts) {
+          await Promise.resolve(log(`❌ ${label}: transient network error persisted after ${transientAttempts} attempts; giving up.`));
+          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 sleepWithCountdown(waitMs, log);
+        continue;
+      }
+
+      throw error;
     }
   }
-  // Unreachable — loop either returns or throws.
+  // Unreachable — loop either returns or throws via the budgets above.
   throw lastError;
 };
 
@@ -265,8 +317,11 @@ export const wrapDollarWithGhRetry = (dollar, options = {}) => {
   return wrapped;
 };
 
+export { isTransientNetworkError };
+
 export default {
   isRateLimitError,
+  isTransientNetworkError,
   parseRateLimitReset,
   fetchNextRateLimitReset,
   computeRateLimitWait,

package/src/github.batch.lib.mjs

@@ -11,7 +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
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. execGhWithRetry adds transient-network retry (#1756).
 /**
  * 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"
@@ -124,14 +124,14 @@ export async function batchCheckPullRequestsForIssues(owner, repo, issueNumbers)
           await new Promise(resolve => setTimeout(resolve, timeouts.githubRepoDelay));
         }
 
-        // Execute GraphQL query
-        const { exec } = await import('child_process');
-        const { promisify } = await import('util');
-        const execAsync = promisify(exec);
-        const { stdout } = await execAsync(`gh api graphql -f query='${query}'`, {
-          encoding: 'utf8',
-          maxBuffer: githubLimits.bufferMaxSize,
-          env: process.env,
+        // Execute GraphQL query (#1756: route through execGhWithRetry for transient 5xx + rate-limit)
+        const { stdout } = await execGhWithRetry(`gh api graphql -f query='${query}'`, {
+          execOptions: {
+            encoding: 'utf8',
+            maxBuffer: githubLimits.bufferMaxSize,
+            env: process.env,
+          },
+          label: 'gh api graphql (batch PR check)',
         });
 
         const data = JSON.parse(stdout);
@@ -191,12 +191,13 @@ export async function batchCheckPullRequestsForIssues(owner, repo, issueNumbers)
 
         for (const issueNum of batch) {
           try {
-            const { exec } = await import('child_process');
-            const { promisify } = await import('util');
-            const execAsync = promisify(exec);
             const cmd = `gh api repos/${owner}/${repo}/issues/${issueNum}/timeline --paginate --jq '[.[] | select(.event == "cross-referenced" and .source.issue.pull_request != null and .source.issue.state == "open")] | length'`;
 
-            const { stdout } = await execAsync(cmd, { encoding: 'utf8', env: process.env });
+            // #1756: route REST fallback through execGhWithRetry for transient 5xx + rate-limit
+            const { stdout } = await execGhWithRetry(cmd, {
+              execOptions: { encoding: 'utf8', env: process.env },
+              label: `gh api timeline (issue #${issueNum})`,
+            });
             const openPrCount = parseInt(stdout.trim()) || 0;
 
             results[issueNum] = {
@@ -271,14 +272,14 @@ export async function batchCheckArchivedRepositories(repositories) {
           await new Promise(resolve => setTimeout(resolve, timeouts.githubRepoDelay));
         }
 
-        // Execute GraphQL query
-        const { exec } = await import('child_process');
-        const { promisify } = await import('util');
-        const execAsync = promisify(exec);
-        const { stdout } = await execAsync(`gh api graphql -f query='${query}'`, {
-          encoding: 'utf8',
-          maxBuffer: githubLimits.bufferMaxSize,
-          env: process.env,
+        // Execute GraphQL query (#1756: route through execGhWithRetry for transient 5xx + rate-limit)
+        const { stdout } = await execGhWithRetry(`gh api graphql -f query='${query}'`, {
+          execOptions: {
+            encoding: 'utf8',
+            maxBuffer: githubLimits.bufferMaxSize,
+            env: process.env,
+          },
+          label: 'gh api graphql (batch archived check)',
         });
 
         const data = JSON.parse(stdout);
@@ -301,12 +302,13 @@ export async function batchCheckArchivedRepositories(repositories) {
 
         for (const repo of batch) {
           try {
-            const { exec } = await import('child_process');
-            const { promisify } = await import('util');
-            const execAsync = promisify(exec);
             const cmd = `gh api repos/${repo.owner}/${repo.name} --jq .archived`;
 
-            const { stdout } = await execAsync(cmd, { encoding: 'utf8', env: process.env });
+            // #1756: route REST fallback through execGhWithRetry for transient 5xx + rate-limit
+            const { stdout } = await execGhWithRetry(cmd, {
+              execOptions: { encoding: 'utf8', env: process.env },
+              label: `gh api repos (${repo.owner}/${repo.name})`,
+            });
             const isArchived = stdout.trim() === 'true';
 
             const repoKey = `${repo.owner}/${repo.name}`;

package/src/github.graphql.lib.mjs

@@ -3,6 +3,8 @@
  * This module provides functions to fetch issues using GitHub's GraphQL API
  */
 
+import { execGhWithRetry } from './github-rate-limit.lib.mjs'; // #1756: route gh exec through transient + rate-limit retry wrapper
+
 /**
  * Fetch issues from a single repository with pagination support for >100 issues
  * @param {string} owner - Repository owner
@@ -13,9 +15,6 @@
  * @returns {Promise<Array>} Array of issues
  */
 async function fetchRepositoryIssuesWithPagination(owner, repoName, log, cleanErrorMessage, issueLimit = 100) {
-  const { exec } = await import('child_process');
-  const { promisify } = await import('util');
-  const execAsync = promisify(exec);
   const allIssues = [];
   let hasNextPage = true;
   let cursor = null;
@@ -59,7 +58,10 @@ async function fetchRepositoryIssuesWithPagination(owner, repoName, log, cleanEr
       // Add delay for rate limiting
       await new Promise(resolve => setTimeout(resolve, 1000));
 
-      const { stdout } = await execAsync(graphqlCmd, { encoding: 'utf8', env: process.env });
+      const { stdout } = await execGhWithRetry(graphqlCmd, {
+        execOptions: { encoding: 'utf8', env: process.env },
+        label: `gh api graphql (issues page ${pageNum} of ${owner}/${repoName})`,
+      });
       const data = JSON.parse(stdout);
       const issuesData = data.data.repository.issues;
 
@@ -95,10 +97,6 @@ async function fetchRepositoryIssuesWithPagination(owner, repoName, log, cleanEr
  * @returns {Promise<{success: boolean, issues: Array, repoCount: number}>}
  */
 export async function tryFetchIssuesWithGraphQL(owner, scope, log, cleanErrorMessage, repoLimit = 100, issueLimit = 100) {
-  const { exec } = await import('child_process');
-  const { promisify } = await import('util');
-  const execAsync = promisify(exec);
-
   try {
     await log('   🧪 Attempting GraphQL approach with pagination support...', { verbose: true });
 
@@ -174,7 +172,10 @@ export async function tryFetchIssuesWithGraphQL(owner, scope, log, cleanErrorMes
       // Add delay for rate limiting
       await new Promise(resolve => setTimeout(resolve, 2000));
 
-      const { stdout } = await execAsync(graphqlCmd, { encoding: 'utf8', env: process.env });
+      const { stdout } = await execGhWithRetry(graphqlCmd, {
+        execOptions: { encoding: 'utf8', env: process.env },
+        label: `gh api graphql (repos page ${repoPageNum} of ${owner})`,
+      });
       const data = JSON.parse(stdout);
       const repos = isOrg ? data.data.organization.repositories : data.data.user.repositories;
 

package/src/github.lib.mjs

@@ -16,6 +16,8 @@ export { getToolDisplayName }; // Re-export for use by other modules
 import { buildBudgetStatsString } from './claude.budget-stats.lib.mjs';
 import { buildCostInfoString } from './github-cost-info.lib.mjs';
 export { buildCostInfoString };
+// #1756: route gh exec calls through transient + rate-limit retry wrapper
+import { execGhWithRetry } from './github-rate-limit.lib.mjs';
 // Issue #1625: Named marker constants (single source of truth) + in-memory
 // tracking for tool-posted comments. See tool-comments.lib.mjs for design.
 import { SOLUTION_DRAFT_LOG_MARKER, SOLUTION_DRAFT_FAILED_MARKER, SOLUTION_DRAFT_FINISHED_WITH_ERRORS_MARKER, USAGE_LIMIT_REACHED_MARKER, NOW_WORKING_SESSION_IS_ENDED_MARKER, postTrackedComment, postTrackedCommentFromFile } from './tool-comments.lib.mjs';
@@ -858,9 +860,6 @@ export function isRateLimitError(error) {
  * @returns {Promise<Array>} Array of issues
  */
 export async function fetchAllIssuesWithPagination(baseCommand) {
-  const { exec } = await import('child_process');
-  const { promisify } = await import('util');
-  const execAsync = promisify(exec);
   // Import log and cleanErrorMessage from lib.mjs
   const { log, cleanErrorMessage } = await import('./lib.mjs');
   try {
@@ -876,7 +875,11 @@ export async function fetchAllIssuesWithPagination(baseCommand) {
     const maxPageSize = isSearchCommand ? 100 : 1000;
     const improvedCommand = `${commandWithoutLimit} --limit ${maxPageSize}`;
     await log(`   🔎 Executing: ${improvedCommand}`, { verbose: true });
-    const { stdout } = await execAsync(improvedCommand, { encoding: 'utf8', env: process.env });
+    // #1756: use execGhWithRetry so transient 5xx (e.g., 504) auto-retry
+    const { stdout } = await execGhWithRetry(improvedCommand, {
+      execOptions: { encoding: 'utf8', env: process.env },
+      label: 'gh search/list issues (paginated)',
+    });
     const endTime = Date.now();
     const issues = JSON.parse(stdout || '[]');
     await log(`   ✅ Fetched ${issues.length} issues in ${Math.round((endTime - startTime) / 1000)}s`);
@@ -913,7 +916,11 @@ export async function fetchAllIssuesWithPagination(baseCommand) {
       await log('   🔄 Falling back to default behavior...', { verbose: true });
       const fallbackCommand = baseCommand.includes('--limit') ? baseCommand : `${baseCommand} --limit 100`;
       await new Promise(resolve => setTimeout(resolve, timeouts.githubRepoDelay)); // Shorter delay for fallback
-      const { stdout } = await execAsync(fallbackCommand, { encoding: 'utf8', env: process.env });
+      // #1756: use execGhWithRetry on fallback too
+      const { stdout } = await execGhWithRetry(fallbackCommand, {
+        execOptions: { encoding: 'utf8', env: process.env },
+        label: 'gh search/list issues (fallback)',
+      });
       const issues = JSON.parse(stdout || '[]');
       await log(`   ⚠️  Fallback: fetched ${issues.length} issues (limited to 100)`, { level: 'warning' });
       return issues;

package/src/hive.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Import Sentry instrumentation first (must be before other imports)
 import './instrument.mjs';
-import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. execGhWithRetry adds transient-network retry (#1756).
 const earlyArgs = process.argv.slice(2);
 if (earlyArgs.includes('--version')) {
   const { getVersion } = await import('./version.lib.mjs');
@@ -112,9 +112,6 @@ if (isRunningDirectly) {
      * @returns {Promise<Array>} Array of issues
      */
     async function fetchIssuesFromRepositories(owner, scope, monitorTag, fetchAllIssues = false) {
-      const { exec } = await import('child_process');
-      const { promisify } = await import('util');
-      const execAsync = promisify(exec);
       try {
         await log(`   🔄 Using repository-by-repository fallback for ${scope}: ${owner}`);
         // Strategy 1: Try GraphQL approach first (faster but has limitations)
@@ -141,7 +138,11 @@ if (isRunningDirectly) {
 
         // Add delay for rate limiting
         await new Promise(resolve => setTimeout(resolve, 2000));
-        const { stdout: repoOutput } = await execAsync(repoListCmd, { encoding: 'utf8', env: process.env });
+        // #1756: route through execGhWithRetry for transient 5xx + rate-limit
+        const { stdout: repoOutput } = await execGhWithRetry(repoListCmd, {
+          execOptions: { encoding: 'utf8', env: process.env },
+          label: `gh api ${scope} repos (paginated)`,
+        });
         // Parse the output line by line, as gh api with --jq outputs one JSON object per line
         const repoLines = repoOutput
           .trim()
@@ -291,6 +292,10 @@ if (isRunningDirectly) {
     // Set global verbose mode
     global.verboseMode = argv.verbose;
 
+    // Initialize i18n based on --language (or detected system locale)
+    const { initI18n } = await import('./i18n.lib.mjs');
+    await initI18n(argv.language);
+
     setupVerboseLogInterceptor(); // Issue #1466: capture [VERBOSE] output in log files
     setupStdioLogInterceptor(); // Issue #1549: capture ALL terminal output in log file
 

package/src/i18n.lib.mjs

@@ -0,0 +1,174 @@
+// i18n module for hive-mind.
+// - Translation files live in src/locales/<locale>.lino and are stored
+//   in Links Notation, parsed via lino-objects-codec.
+// - Supported locales: en (default fallback), ru, zh, hi.
+// - Public API: initI18n, t, getCurrentLocale, setLocale, getSupportedLocales,
+//   normalizeLocale, getUserLocale, setUserLocale, clearUserLocale,
+//   resolveLocaleFromTelegramCtx.
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { parseIndented } from 'lino-objects-codec';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DEFAULT_LOCALE = 'en';
+const SUPPORTED_LOCALES = ['en', 'ru', 'zh', 'hi'];
+
+const localeCache = new Map(); // locale -> { key: string }
+const userLocales = new Map(); // userId/chatId -> locale (in-memory)
+
+let currentLocale = DEFAULT_LOCALE;
+let fallbackLoaded = false;
+
+export function getSupportedLocales() {
+  return [...SUPPORTED_LOCALES];
+}
+
+export function normalizeLocale(input) {
+  if (!input || typeof input !== 'string') return null;
+  const lower = input.toLowerCase();
+  // Take only the language part (before "_" or "-")
+  const lang = lower.split(/[_\-.]/)[0];
+  if (SUPPORTED_LOCALES.includes(lang)) return lang;
+  return null;
+}
+
+export function detectLocale() {
+  const envLocale = process.env.LANG || process.env.LANGUAGE || process.env.LC_ALL || process.env.LC_MESSAGES || '';
+  return normalizeLocale(envLocale) || DEFAULT_LOCALE;
+}
+
+async function readLocaleFile(locale) {
+  const localesDir = path.join(__dirname, 'locales');
+  const linoFile = path.join(localesDir, `${locale}.lino`);
+  const data = await fs.readFile(linoFile, 'utf-8');
+  return parseIndentedToFlatMap(data);
+}
+
+// parseIndented returns { id, obj } where obj is the key->value map.
+// Some keys contain dots (e.g., error.invalid_github_url). The parser
+// supports them when the key is a plain reference (no spaces/quotes).
+function unescapeString(s) {
+  // Convert literal escape sequences (e.g., "\n" inside a quoted string in
+  // Links Notation) into the corresponding JS characters. This keeps the
+  // .lino files single-line and human-friendly.
+  return s.replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\r/g, '\r').replace(/\\\\/g, '\\');
+}
+
+function parseIndentedToFlatMap(text) {
+  const parsed = parseIndented({ text });
+  // parsed: { id: <localeName>, obj: { key: value, ... } }
+  if (!parsed || !parsed.obj) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(parsed.obj)) {
+    out[k] = typeof v === 'string' ? unescapeString(v) : String(v);
+  }
+  return out;
+}
+
+export async function loadTranslations(locale) {
+  if (localeCache.has(locale)) return localeCache.get(locale);
+
+  let translations = {};
+  try {
+    translations = await readLocaleFile(locale);
+  } catch {
+    translations = {};
+  }
+  localeCache.set(locale, translations);
+
+  // Always have the fallback (English) ready
+  if (!fallbackLoaded && locale !== DEFAULT_LOCALE) {
+    try {
+      const fb = await readLocaleFile(DEFAULT_LOCALE);
+      localeCache.set(DEFAULT_LOCALE, fb);
+    } catch {
+      localeCache.set(DEFAULT_LOCALE, {});
+    }
+    fallbackLoaded = true;
+  } else if (locale === DEFAULT_LOCALE) {
+    fallbackLoaded = true;
+  }
+
+  return translations;
+}
+
+export async function initI18n(localeInput = null) {
+  const requested = localeInput ? normalizeLocale(localeInput) : null;
+  const detectedLocale = requested || detectLocale();
+  currentLocale = detectedLocale;
+  await loadTranslations(detectedLocale);
+  if (detectedLocale !== DEFAULT_LOCALE) {
+    await loadTranslations(DEFAULT_LOCALE);
+  }
+  return detectedLocale;
+}
+
+function applyParams(text, params) {
+  if (!params) return text;
+  let out = text;
+  for (const [k, v] of Object.entries(params)) {
+    out = out.replace(new RegExp(`{{${k}}}`, 'g'), String(v));
+  }
+  return out;
+}
+
+export function t(key, params = {}, options = {}) {
+  const locale = options.locale ? normalizeLocale(options.locale) || currentLocale : currentLocale;
+  const main = localeCache.get(locale) || {};
+  const fallback = localeCache.get(DEFAULT_LOCALE) || {};
+  const value = main[key] ?? fallback[key] ?? key;
+  return applyParams(value, params);
+}
+
+export function getCurrentLocale() {
+  return currentLocale;
+}
+
+export function setLocale(locale) {
+  const normalized = normalizeLocale(locale);
+  if (normalized) currentLocale = normalized;
+}
+
+// In-memory per-user locale store (used by the Telegram bot).
+export function getUserLocale(userId) {
+  if (userId === undefined || userId === null) return null;
+  return userLocales.get(String(userId)) || null;
+}
+
+export function setUserLocale(userId, locale) {
+  const normalized = normalizeLocale(locale);
+  if (!normalized || userId === undefined || userId === null) return false;
+  userLocales.set(String(userId), normalized);
+  return true;
+}
+
+export function clearUserLocale(userId) {
+  if (userId === undefined || userId === null) return false;
+  return userLocales.delete(String(userId));
+}
+
+// Resolve the best locale for a Telegram update context.
+// Priority: per-user override -> ctx.from.language_code -> current default.
+export function resolveLocaleFromTelegramCtx(ctx) {
+  const userId = ctx?.from?.id;
+  const userOverride = getUserLocale(userId);
+  if (userOverride) return userOverride;
+  const fromTelegram = normalizeLocale(ctx?.from?.language_code);
+  if (fromTelegram) return fromTelegram;
+  return currentLocale;
+}
+
+// Pre-load every supported locale (handy for the Telegram bot at startup).
+export async function preloadAllLocales() {
+  for (const loc of SUPPORTED_LOCALES) {
+    try {
+      await loadTranslations(loc);
+    } catch {
+      // ignore - missing files fall back to English
+    }
+  }
+}

package/src/limits.lib.mjs

@@ -12,7 +12,7 @@ import { promisify } from 'node:util';
 import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc.js';
 
-import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. execGhWithRetry adds transient-network retry (#1756).
 // Initialize dayjs plugins
 dayjs.extend(utc);
 
@@ -316,7 +316,8 @@ function getDisplayCpuCoresUsed(loadAvg5, cpuCount) {
  */
 export async function getGitHubRateLimits(verbose = false) {
   try {
-    const { stdout } = await execAsync('gh api rate_limit 2>/dev/null');
+    // #1756: route through execGhWithRetry for transient 5xx; skip rate-limit retry budget (this is the endpoint we'd consult to know about rate limits).
+    const { stdout } = await execGhWithRetry('gh api rate_limit 2>/dev/null', { label: 'gh api rate_limit', maxAttempts: 1 });
     const data = JSON.parse(stdout);
 
     if (verbose) {