fix(wiki): Remove the hidden 60s default timeout, validate gitnexus wiki timeout/retry flags, and surface timeout errors

README.md

@@ -725,7 +725,7 @@ gitnexus wiki --force
 
 
 # Increase the timeout or retries for large codebase or slow LLM providers
-gitnexus wiki --timeout <seconds> # Per-attempt LLM request timeout in seconds (default: 60) 
+gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
 gitnexus wiki --retries <n>      # Max LLM retry attempts per request (default: 3)
 
 ```

gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md

@@ -62,7 +62,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 | `--api-key <key>` | LLM API key |
 | `--concurrency <n>` | Parallel LLM calls (default: 3) |
 | `--gist` | Publish wiki as a public GitHub Gist |
-| `--timeout <seconds>` | Per-attempt LLM request timeout in seconds (default: 60) |
+| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
 | `--retries <n>` | Max LLM retry attempts per request (default: 3) |
 
 ### list — Show all indexed repos

gitnexus/src/cli/index.ts

@@ -161,7 +161,7 @@ program
   )
   .option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)')
   .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
-  .option('--timeout <seconds>', 'Per-attempt LLM request timeout in seconds (default: 60)')
+  .option('--timeout <seconds>', 'LLM request timeout in seconds (default: disabled)')
   .option('--retries <n>', 'Max LLM retry attempts per request (default: 3)')
   .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
   .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')

gitnexus/src/cli/wiki.ts

@@ -37,6 +37,23 @@ export interface WikiCommandOptions {
   retries?: string;
 }
 
+function parsePositiveIntegerOption(
+  value: string | undefined,
+  flag: string,
+  multiplier = 1,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (!/^[1-9]\d*$/.test(trimmed)) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  const parsed = parseInt(trimmed, 10);
+  if (parsed > Math.floor(Number.MAX_SAFE_INTEGER / multiplier)) {
+    throw new Error(`${flag} is too large`);
+  }
+  return parsed;
+}
+
 /**
  * Prompt the user for input via stdin.
  */
@@ -127,6 +144,17 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
     return;
   }
 
+  let timeoutSeconds: number | undefined;
+  let retries: number | undefined;
+  try {
+    timeoutSeconds = parsePositiveIntegerOption(options?.timeout, '--timeout', 1000);
+    retries = parsePositiveIntegerOption(options?.retries, '--retries');
+  } catch (error) {
+    console.log(`  Error: ${(error as Error).message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   // ── Resolve LLM config (with interactive fallback) ─────────────────
   // Save any CLI overrides immediately
   if (
@@ -350,13 +378,11 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
   }
 
   // ── Apply per-run overrides not saved to config ────────────────────
-  if (options?.timeout) {
-    const secs = parseInt(options.timeout, 10);
-    if (!isNaN(secs) && secs > 0) llmConfig.requestTimeoutMs = secs * 1000;
+  if (timeoutSeconds !== undefined) {
+    llmConfig.requestTimeoutMs = timeoutSeconds * 1000;
   }
-  if (options?.retries) {
-    const n = parseInt(options.retries, 10);
-    if (!isNaN(n) && n > 0) llmConfig.maxAttempts = n;
+  if (retries !== undefined) {
+    llmConfig.maxAttempts = retries;
   }
 
   // ── Setup progress bar with elapsed timer ──────────────────────────
@@ -563,6 +589,8 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
 
     if (err.message?.includes('No source files')) {
       console.log(`\n  ${err.message}\n`);
+    } else if (err.message?.includes('LLM request timed out after')) {
+      console.log(`\n  Timeout: ${err.message}\n`);
     } else if (err.message?.includes('content filter')) {
       // Content filter block — actionable message
       console.log(`\n  Content Filter: ${err.message}\n`);

gitnexus/src/core/wiki/llm-client.ts

@@ -23,7 +23,7 @@ export interface LLMConfig {
   apiVersion?: string;
   /** When true, strips sampling params and uses max_completion_tokens instead of max_tokens */
   isReasoningModel?: boolean;
-  /** Per-attempt fetch timeout in ms (default: 60_000). */
+  /** Per-attempt fetch timeout in ms. Omit to disable request timeouts. */
   requestTimeoutMs?: number;
   /** Max fetch attempts before giving up (default: 3). */
   maxAttempts?: number;
@@ -81,6 +81,19 @@ export function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
+function formatTimeoutDuration(timeoutMs: number): string {
+  if (timeoutMs >= 1000 && timeoutMs % 1000 === 0) {
+    return `${timeoutMs / 1000}s`;
+  }
+  return `${timeoutMs}ms`;
+}
+
+function isTimeoutLikeError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  if (err.name === 'TimeoutError' || err.name === 'AbortError') return true;
+  return /time(d)?\s*out|timeout/i.test(err.message);
+}
+
 /**
  * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
  * endpoint (CWE-918 / CodeQL js/http-to-file-access).
@@ -237,12 +250,13 @@ export async function callLLM(
           ...authHeaders,
         },
         body: JSON.stringify(body),
-        // Per-attempt timeout. Without this each retry can hang
-        // indefinitely on a frozen TCP connection — the per-call
-        // signal is the only timeout `resilientFetch` honors;
-        // `capDelayMs` only bounds the *backoff* between attempts.
-        // Default 60s; raise via --timeout for slow models or large pages.
-        signal: AbortSignal.timeout(config.requestTimeoutMs ?? 60_000),
+        // Request timeout is opt-in for wiki generation. Large local
+        // model runs can legitimately take well over a minute, so the
+        // default runtime path must not impose a hidden 60s ceiling.
+        signal:
+          config.requestTimeoutMs !== undefined
+            ? AbortSignal.timeout(config.requestTimeoutMs)
+            : undefined,
       },
       {
         breakerKey: `wiki-llm-${new URL(url).host}`,
@@ -261,6 +275,12 @@ export async function callLLM(
         `LLM API error (${err.response.status} after retries): ${errorText.slice(0, 500)}`,
       );
     }
+    if (config.requestTimeoutMs !== undefined && isTimeoutLikeError(err)) {
+      throw new Error(
+        `LLM request timed out after ${formatTimeoutDuration(config.requestTimeoutMs)}. ` +
+          'Increase --timeout or omit it to disable the request timeout.',
+      );
+    }
     throw err;
   }