@elvatis_com/openclaw-cli-bridge-elvatis 2.4.0 → 2.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 > OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code, OpenCode, Pi) as model providers — with slash commands for instant model switching, restore, health testing, and model listing.
 
-**Current version:** `2.3.0`
+**Current version:** `2.6.0`
 
 ---
 
@@ -282,7 +282,17 @@ In `~/.openclaw/openclaw.json` → `plugins.entries.openclaw-cli-bridge-elvatis.
   "enableProxy": true,         // start local CLI proxy server (default: true)
   "proxyPort": 31337,          // proxy port (default: 31337)
   "proxyApiKey": "cli-bridge", // key between OpenClaw vllm provider and proxy (default: "cli-bridge")
-  "proxyTimeoutMs": 120000     // CLI subprocess timeout in ms (default: 120s)
+  "proxyTimeoutMs": 300000,    // base CLI subprocess timeout in ms (default: 300s, scales dynamically)
+  "modelTimeouts": {           // per-model timeout overrides in ms (optional)
+    "cli-claude/claude-opus-4-6":       300000,   // 5 min — heavy/agentic tasks
+    "cli-claude/claude-sonnet-4-6":     180000,   // 3 min — interactive chat
+    "cli-claude/claude-haiku-4-5":       90000,   // 90s  — fast responses
+    "cli-gemini/gemini-2.5-pro":        180000,
+    "cli-gemini/gemini-2.5-flash":       90000,
+    "openai-codex/gpt-5.4":            300000,
+    "openai-codex/gpt-5.3-codex":      180000,
+    "openai-codex/gpt-5.1-codex-mini":  90000
+  }
 }
 ```
 
@@ -368,7 +378,7 @@ Model fallback (v1.9.0):
 ```bash
 npm run lint        # eslint (TypeScript-aware)
 npm run typecheck   # tsc --noEmit
-npm test            # vitest run (121 tests)
+npm test            # vitest run (252 tests)
 npm run ci          # lint + typecheck + test
 ```
 
@@ -376,6 +386,26 @@ npm run ci          # lint + typecheck + test
 
 ## Changelog
 
+### v2.6.0
+- **feat:** Provider session registry (`src/provider-sessions.ts`) — persistent sessions that survive across runs. When a CLI run times out, the session is preserved (not deleted) so follow-up runs can resume in the same context. Sessions are stored in `~/.openclaw/cli-bridge/sessions.json`.
+- **feat:** Centralized config module (`src/config.ts`) — all magic numbers, timeouts, paths, ports, and model defaults extracted into one file. No more scattered hardcoded values.
+- **feat:** Session-aware proxy — every CLI request gets a `provider_session_id` in the response. Pass it back via `providerSessionId` in subsequent requests to reuse the same session.
+- **feat:** New proxy endpoints: `GET /v1/provider-sessions` (list sessions + stats), `DELETE /v1/provider-sessions/:id` (remove a session)
+- **fix:** Version fallback changed from `"0.0.0"` to `"unknown"` with secondary lookup in `openclaw.plugin.json` — prevents Dashboard showing wrong version
+- **refactor:** `index.ts`, `cli-runner.ts`, `session-manager.ts`, `proxy-server.ts` now import all constants from `config.ts` instead of defining them locally
+- **test:** 35 new tests for provider sessions, config exports (252 total)
+
+### v2.5.0
+- **feat:** Graceful timeout handling — replaces Node's `spawn({ timeout })` with manual SIGTERM→SIGKILL sequence (5s grace period). Exit 143 is now clearly annotated as "timeout by supervisor" in logs, not a cryptic model error.
+- **feat:** Per-model timeout profiles — new `modelTimeouts` config option sets sensible defaults per model: Opus 5 min, Sonnet 3 min, Haiku 90s, Flash models 90s. Scales dynamically with conversation size (+2s/msg beyond 10, +5s/tool).
+- **feat:** Timeout logging — every timeout event logs model, elapsed time, SIGTERM/SIGKILL steps. Fallback messages now show "timeout by supervisor" instead of raw exit codes.
+- **fix:** Base timeout raised from 120s to 300s (was causing frequent Exit 143 on normal Sonnet conversations)
+- **fix:** Session manager `kill()`, `cleanup()`, and `stop()` now use graceful SIGTERM→SIGKILL instead of immediate SIGTERM
+- **test:** 7 new tests for timeout handling and exit code annotation (217 total)
+
+### v2.4.0
+- **feat:** Metrics & health dashboard — request volume, latency, errors, token usage
+
 ### v2.3.0
 - **feat:** OpenAI tool calling protocol support for all CLI models — tool definitions are injected into the prompt, structured `tool_calls` responses are parsed and returned in OpenAI format
 - **feat:** Multimodal content support — images and audio from webchat are extracted to temp files and passed to CLIs (Codex uses native `-i` flag, Claude/Gemini reference file paths in prompt)

package/SKILL.md

@@ -68,4 +68,4 @@ On gateway restart, if any session has expired, a **WhatsApp alert** is sent aut
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 2.1.3
+**Version:** 2.6.0

package/index.ts

@@ -41,7 +41,13 @@ const PACKAGE_VERSION: string = (() => {
     const pkg = JSON.parse(readFileSync(join(__dirname_local, "package.json"), "utf-8")) as { version: string };
     return pkg.version;
   } catch {
-    return "0.0.0"; // fallback — should never happen in normal operation
+    // Second attempt: try openclaw.plugin.json (always co-located)
+    try {
+      const manifest = JSON.parse(readFileSync(join(__dirname_local, "openclaw.plugin.json"), "utf-8")) as { version: string };
+      return manifest.version;
+    } catch {
+      return "unknown"; // should never happen — both files are always present
+    }
   }
 })();
 import type {
@@ -62,6 +68,18 @@ import {
 import { importCodexAuth } from "./src/codex-auth-import.js";
 import { startProxyServer } from "./src/proxy-server.js";
 import { patchOpencllawConfig } from "./src/config-patcher.js";
+import {
+  DEFAULT_PROXY_PORT,
+  DEFAULT_PROXY_API_KEY,
+  DEFAULT_PROXY_TIMEOUT_MS,
+  DEFAULT_MODEL_TIMEOUTS,
+  DEFAULT_MODEL_FALLBACKS,
+  STATE_FILE as CONFIG_STATE_FILE,
+  PENDING_FILE as CONFIG_PENDING_FILE,
+  OPENCLAW_DIR,
+  CLI_TEST_DEFAULT_MODEL as CONFIG_CLI_TEST_DEFAULT_MODEL,
+  PROFILE_DIRS,
+} from "./src/config.js";
 import {
   loadSession,
   deleteSession,
@@ -98,6 +116,7 @@ interface CliPluginConfig {
   proxyPort?: number;
   proxyApiKey?: string;
   proxyTimeoutMs?: number;
+  modelTimeouts?: Record<string, number>;
   grokSessionPath?: string;
 }
 
@@ -108,11 +127,11 @@ interface CliPluginConfig {
 let grokBrowser: Browser | null = null;
 let grokContext: BrowserContext | null = null;
 
-// Persistent profile dirs — survive gateway restarts, keep cookies intact
-const GROK_PROFILE_DIR = join(homedir(), ".openclaw", "grok-profile");
-const GEMINI_PROFILE_DIR = join(homedir(), ".openclaw", "gemini-profile");
-const CLAUDE_PROFILE_DIR = join(homedir(), ".openclaw", "claude-profile");
-const CHATGPT_PROFILE_DIR = join(homedir(), ".openclaw", "chatgpt-profile");
+// Persistent profile dirs — imported from config.ts
+const GROK_PROFILE_DIR = PROFILE_DIRS.grok;
+const GEMINI_PROFILE_DIR = PROFILE_DIRS.gemini;
+const CLAUDE_PROFILE_DIR = PROFILE_DIRS.claude;
+const CHATGPT_PROFILE_DIR = PROFILE_DIRS.chatgpt;
 
 // Stealth launch options — prevent Cloudflare/bot detection from flagging the browser
 const STEALTH_ARGS = [
@@ -684,14 +703,13 @@ async function tryRestoreGrokSession(
   }
 }
 
-const DEFAULT_PROXY_PORT = 31337;
-const DEFAULT_PROXY_API_KEY = "cli-bridge";
+// DEFAULT_PROXY_PORT, DEFAULT_PROXY_API_KEY imported from config.ts
 
 // ──────────────────────────────────────────────────────────────────────────────
 // State file — persists the model that was active before the last /cli-* switch
 // Located at ~/.openclaw/cli-bridge-state.json (survives gateway restarts)
 // ──────────────────────────────────────────────────────────────────────────────
-const STATE_FILE = join(homedir(), ".openclaw", "cli-bridge-state.json");
+const STATE_FILE = CONFIG_STATE_FILE;
 
 interface CliBridgeState {
   previousModel: string;
@@ -707,7 +725,7 @@ function readState(): CliBridgeState | null {
 
 function writeState(state: CliBridgeState): void {
   try {
-    mkdirSync(join(homedir(), ".openclaw"), { recursive: true });
+    mkdirSync(OPENCLAW_DIR, { recursive: true });
     writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + "\n", "utf8");
   } catch {
     // non-fatal — /cli-back will just report no previous model
@@ -779,7 +797,7 @@ const CLI_MODEL_COMMANDS = [
 ] as const;
 
 /** Default model used by /cli-test when no arg is given */
-const CLI_TEST_DEFAULT_MODEL = "cli-claude/claude-sonnet-4-6";
+const CLI_TEST_DEFAULT_MODEL = CONFIG_CLI_TEST_DEFAULT_MODEL;
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Staged-switch state file
@@ -787,7 +805,7 @@ const CLI_TEST_DEFAULT_MODEL = "cli-claude/claude-sonnet-4-6";
 // Written by /cli-* (default), applied by /cli-apply or /cli-* --now.
 // Located at ~/.openclaw/cli-bridge-pending.json
 // ──────────────────────────────────────────────────────────────────────────────
-const PENDING_FILE = join(homedir(), ".openclaw", "cli-bridge-pending.json");
+const PENDING_FILE = CONFIG_PENDING_FILE;
 
 interface CliBridgePending {
   model: string;
@@ -805,7 +823,7 @@ function readPending(): CliBridgePending | null {
 
 function writePending(pending: CliBridgePending): void {
   try {
-    mkdirSync(join(homedir(), ".openclaw"), { recursive: true });
+    mkdirSync(OPENCLAW_DIR, { recursive: true });
     writeFileSync(PENDING_FILE, JSON.stringify(pending, null, 2) + "\n", "utf8");
   } catch {
     // non-fatal
@@ -987,7 +1005,9 @@ const plugin = {
     const enableProxy = cfg.enableProxy ?? true;
     const port = cfg.proxyPort ?? DEFAULT_PROXY_PORT;
     const apiKey = cfg.proxyApiKey ?? DEFAULT_PROXY_API_KEY;
-    const timeoutMs = cfg.proxyTimeoutMs ?? 120_000;
+    const timeoutMs = cfg.proxyTimeoutMs ?? DEFAULT_PROXY_TIMEOUT_MS;
+    // Per-model timeout overrides — defaults from config.ts, can be extended via plugin config.
+    const modelTimeouts = { ...DEFAULT_MODEL_TIMEOUTS, ...cfg.modelTimeouts };
     const codexAuthPath = cfg.codexAuthPath ?? DEFAULT_CODEX_AUTH_PATH;
     const grokSessionPath = cfg.grokSessionPath ?? DEFAULT_SESSION_PATH;
 
@@ -999,14 +1019,8 @@ const plugin = {
       modelCommands[modelId] = `/${entry.name}`;
     }
 
-    // ── Default model fallback chain ──────────────────────────────────────────
-    // When a primary model fails (timeout, error), retry once with a lighter variant.
-    const modelFallbacks: Record<string, string> = {
-      "cli-gemini/gemini-2.5-pro":       "cli-gemini/gemini-2.5-flash",
-      "cli-gemini/gemini-3-pro-preview":  "cli-gemini/gemini-3-flash-preview",
-      "cli-claude/claude-opus-4-6":       "cli-claude/claude-sonnet-4-6",
-      "cli-claude/claude-sonnet-4-6":     "cli-claude/claude-haiku-4-5",
-    };
+    // ── Default model fallback chain (from config.ts) ──────────────────────────
+    const modelFallbacks = { ...DEFAULT_MODEL_FALLBACKS };
 
     // ── Migrate legacy per-provider cookie expiry files to consolidated store ─
     const migration = migrateLegacyFiles();
@@ -1379,6 +1393,7 @@ const plugin = {
             version: plugin.version,
             modelCommands,
             modelFallbacks,
+            modelTimeouts,
             getExpiryInfo: () => ({
               grok:    (() => { const e = loadGrokExpiry();    return e ? formatExpiryInfo(e)    : null; })(),
               gemini:  (() => { const e = loadGeminiExpiry();  return e ? formatGeminiExpiry(e)  : null; })(),
@@ -1415,7 +1430,7 @@ const plugin = {
             // One final attempt
             try {
               const server = await startProxyServer({
-                port, apiKey, timeoutMs, modelCommands, modelFallbacks,
+                port, apiKey, timeoutMs, modelCommands, modelFallbacks, modelTimeouts,
                 log: (msg) => api.logger.info(msg),
                 warn: (msg) => api.logger.warn(msg),
                 getGrokContext: () => grokContext,

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-cli-bridge-elvatis",
   "slug": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "license": "MIT",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [
@@ -34,7 +34,26 @@
       },
       "proxyTimeoutMs": {
         "type": "number",
-        "description": "Max time to wait for a CLI response in ms (default: 120000)"
+        "description": "Base timeout for CLI responses in ms (default: 300000). Scales dynamically with conversation size."
+      },
+      "modelTimeouts": {
+        "type": "object",
+        "description": "Per-model timeout overrides in ms. Keys are model IDs (e.g. 'cli-claude/claude-sonnet-4-6'). Use this to give heavy models more time or limit fast models. When not set, falls back to proxyTimeoutMs.",
+        "additionalProperties": {
+          "type": "number"
+        },
+        "default": {
+          "cli-claude/claude-opus-4-6": 300000,
+          "cli-claude/claude-sonnet-4-6": 180000,
+          "cli-claude/claude-haiku-4-5": 90000,
+          "cli-gemini/gemini-2.5-pro": 180000,
+          "cli-gemini/gemini-2.5-flash": 90000,
+          "cli-gemini/gemini-3-pro-preview": 180000,
+          "cli-gemini/gemini-3-flash-preview": 90000,
+          "openai-codex/gpt-5.4": 300000,
+          "openai-codex/gpt-5.3-codex": 180000,
+          "openai-codex/gpt-5.1-codex-mini": 90000
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {

package/src/cli-runner.ts

@@ -28,11 +28,13 @@ import {
   buildToolPromptBlock,
   parseToolCallResponse,
 } from "./tool-protocol.js";
-
-/** Max messages to include in the prompt sent to the CLI. */
-const MAX_MESSAGES = 20;
-/** Max characters per message content before truncation. */
-const MAX_MSG_CHARS = 4000;
+import {
+  MAX_MESSAGES,
+  MAX_MSG_CHARS,
+  DEFAULT_CLI_TIMEOUT_MS,
+  TIMEOUT_GRACE_MS,
+  MEDIA_TMP_DIR,
+} from "./config.js";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Message formatting
@@ -152,7 +154,7 @@ export interface MediaFile {
   mimeType: string;
 }
 
-const MEDIA_TMP_DIR = join(tmpdir(), "cli-bridge-media");
+// MEDIA_TMP_DIR imported from config.ts
 
 /**
  * Extract non-text content parts (images, audio) from messages.
@@ -278,6 +280,8 @@ export interface CliRunResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /** True when the process was killed due to a timeout (exit 143 = SIGTERM). */
+  timedOut: boolean;
 }
 
 export interface RunCliOptions {
@@ -287,11 +291,21 @@ export interface RunCliOptions {
    */
   cwd?: string;
   timeoutMs?: number;
+  /** Optional logger for timeout events. */
+  log?: (msg: string) => void;
 }
 
+// TIMEOUT_GRACE_MS imported from config.ts
+
 /**
  * Spawn a CLI and deliver the prompt via stdin.
  *
+ * Timeout handling (replaces Node's spawn({ timeout }) for better control):
+ *   1. After `timeoutMs`, send SIGTERM and log a clear message.
+ *   2. If the process doesn't exit within TIMEOUT_GRACE_MS (5s), send SIGKILL.
+ *   3. The result's `timedOut` flag is set so callers can distinguish
+ *      supervisor timeouts from real CLI errors.
+ *
  * cwd defaults to homedir() so CLIs that scan the working directory for
  * project context (like Gemini) don't accidentally enter agentic mode.
  */
@@ -299,20 +313,44 @@ export function runCli(
   cmd: string,
   args: string[],
   prompt: string,
-  timeoutMs = 120_000,
+  timeoutMs = DEFAULT_CLI_TIMEOUT_MS,
   opts: RunCliOptions = {}
 ): Promise<CliRunResult> {
   const cwd = opts.cwd ?? homedir();
+  const log = opts.log ?? (() => {});
 
   return new Promise((resolve, reject) => {
+    // Do NOT pass timeout to spawn() — we manage it ourselves for graceful shutdown.
     const proc = spawn(cmd, args, {
-      timeout: timeoutMs,
       env: buildMinimalEnv(),
       cwd,
     });
 
     let stdout = "";
     let stderr = "";
+    let timedOut = false;
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const clearTimers = () => {
+      if (timeoutTimer) { clearTimeout(timeoutTimer); timeoutTimer = null; }
+      if (killTimer) { clearTimeout(killTimer); killTimer = null; }
+    };
+
+    // ── Timeout sequence: SIGTERM → grace → SIGKILL ──────────────────────
+    timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      const elapsed = Math.round(timeoutMs / 1000);
+      log(`[cli-bridge] timeout after ${elapsed}s for ${cmd}, sending SIGTERM`);
+      proc.kill("SIGTERM");
+
+      killTimer = setTimeout(() => {
+        if (!proc.killed) {
+          log(`[cli-bridge] ${cmd} still running after ${TIMEOUT_GRACE_MS / 1000}s grace, sending SIGKILL`);
+          proc.kill("SIGKILL");
+        }
+      }, TIMEOUT_GRACE_MS);
+    }, timeoutMs);
 
     proc.stdin.write(prompt, "utf8", () => {
       proc.stdin.end();
@@ -322,10 +360,12 @@ export function runCli(
     proc.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
 
     proc.on("close", (code) => {
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0 });
+      clearTimers();
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0, timedOut });
     });
 
     proc.on("error", (err) => {
+      clearTimers();
       reject(new Error(`Failed to spawn '${cmd}': ${err.message}`));
     });
   });
@@ -334,38 +374,75 @@ export function runCli(
 /**
  * Spawn a CLI with the prompt delivered as a CLI argument (not stdin).
  * Used by OpenCode which expects `opencode run "prompt"`.
+ * Uses the same graceful SIGTERM→SIGKILL timeout sequence as runCli.
  */
 export function runCliWithArg(
   cmd: string,
   args: string[],
-  timeoutMs = 120_000,
+  timeoutMs = DEFAULT_CLI_TIMEOUT_MS,
   opts: RunCliOptions = {}
 ): Promise<CliRunResult> {
   const cwd = opts.cwd ?? homedir();
+  const log = opts.log ?? (() => {});
 
   return new Promise((resolve, reject) => {
     const proc = spawn(cmd, args, {
-      timeout: timeoutMs,
       env: buildMinimalEnv(),
       cwd,
     });
 
     let stdout = "";
     let stderr = "";
+    let timedOut = false;
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const clearTimers = () => {
+      if (timeoutTimer) { clearTimeout(timeoutTimer); timeoutTimer = null; }
+      if (killTimer) { clearTimeout(killTimer); killTimer = null; }
+    };
+
+    timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      const elapsed = Math.round(timeoutMs / 1000);
+      log(`[cli-bridge] timeout after ${elapsed}s for ${cmd}, sending SIGTERM`);
+      proc.kill("SIGTERM");
+
+      killTimer = setTimeout(() => {
+        if (!proc.killed) {
+          log(`[cli-bridge] ${cmd} still running after ${TIMEOUT_GRACE_MS / 1000}s grace, sending SIGKILL`);
+          proc.kill("SIGKILL");
+        }
+      }, TIMEOUT_GRACE_MS);
+    }, timeoutMs);
 
     proc.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
     proc.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
 
     proc.on("close", (code) => {
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0 });
+      clearTimers();
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0, timedOut });
     });
 
     proc.on("error", (err) => {
+      clearTimers();
       reject(new Error(`Failed to spawn '${cmd}': ${err.message}`));
     });
   });
 }
 
+/**
+ * Annotate an error message when exit code 143 (SIGTERM) is detected.
+ * Makes it clear in logs that this was a supervisor timeout, not a model error.
+ */
+export function annotateExitError(exitCode: number, stderr: string, timedOut: boolean, model: string): string {
+  const base = stderr || "(no output)";
+  if (timedOut || exitCode === 143) {
+    return `timeout: ${model} killed by supervisor (exit ${exitCode}, likely timeout) — ${base}`;
+  }
+  return base;
+}
+
 // ──────────────────────────────────────────────────────────────────────────────
 // Gemini CLI
 // ──────────────────────────────────────────────────────────────────────────────
@@ -391,7 +468,7 @@ export async function runGemini(
   modelId: string,
   timeoutMs: number,
   workdir?: string,
-  opts?: { tools?: ToolDefinition[] }
+  opts?: { tools?: ToolDefinition[]; log?: (msg: string) => void }
 ): Promise<string> {
   const model = stripPrefix(modelId);
   // -p "" = headless mode trigger; actual prompt arrives via stdin
@@ -404,7 +481,7 @@ export async function runGemini(
     ? buildToolPromptBlock(opts.tools) + "\n\n" + prompt
     : prompt;
 
-  const result = await runCli("gemini", args, effectivePrompt, timeoutMs, { cwd });
+  const result = await runCli("gemini", args, effectivePrompt, timeoutMs, { cwd, log: opts?.log });
 
   // Filter out [WARN] lines from stderr (Gemini emits noisy permission warnings)
   const cleanStderr = result.stderr
@@ -414,7 +491,7 @@ export async function runGemini(
     .trim();
 
   if (result.exitCode !== 0 && result.stdout.length === 0) {
-    throw new Error(`gemini exited ${result.exitCode}: ${cleanStderr || "(no output)"}`);
+    throw new Error(`gemini exited ${result.exitCode}: ${annotateExitError(result.exitCode, cleanStderr, result.timedOut, modelId)}`);
   }
 
   return result.stdout || cleanStderr;
@@ -434,7 +511,7 @@ export async function runClaude(
   modelId: string,
   timeoutMs: number,
   workdir?: string,
-  opts?: { tools?: ToolDefinition[] }
+  opts?: { tools?: ToolDefinition[]; log?: (msg: string) => void }
 ): Promise<string> {
   // Proactively refresh OAuth token if it's about to expire (< 5 min remaining).
   // No-op for API-key users.
@@ -457,15 +534,19 @@ export async function runClaude(
     : prompt;
 
   const cwd = workdir ?? homedir();
-  const result = await runCli("claude", args, effectivePrompt, timeoutMs, { cwd });
+  const result = await runCli("claude", args, effectivePrompt, timeoutMs, { cwd, log: opts?.log });
 
   // On 401: attempt one token refresh + retry before giving up.
   if (result.exitCode !== 0 && result.stdout.length === 0) {
+    // If this was a timeout, don't bother with auth retry — it's a supervisor kill, not a 401.
+    if (result.timedOut) {
+      throw new Error(`claude exited ${result.exitCode}: ${annotateExitError(result.exitCode, result.stderr, true, modelId)}`);
+    }
     const stderr = result.stderr || "(no output)";
     if (stderr.includes("401") || stderr.includes("Invalid authentication credentials") || stderr.includes("authentication_error")) {
       // Refresh and retry once
       await refreshClaudeToken();
-      const retry = await runCli("claude", args, effectivePrompt, timeoutMs, { cwd });
+      const retry = await runCli("claude", args, effectivePrompt, timeoutMs, { cwd, log: opts?.log });
       if (retry.exitCode !== 0 && retry.stdout.length === 0) {
         const retryStderr = retry.stderr || "(no output)";
         if (retryStderr.includes("401") || retryStderr.includes("authentication_error") || retryStderr.includes("Invalid authentication credentials")) {
@@ -478,7 +559,7 @@ export async function runClaude(
       }
       return retry.stdout;
     }
-    throw new Error(`claude exited ${result.exitCode}: ${stderr}`);
+    throw new Error(`claude exited ${result.exitCode}: ${annotateExitError(result.exitCode, stderr, false, modelId)}`);
   }
 
   return result.stdout;
@@ -508,7 +589,7 @@ export async function runCodex(
   modelId: string,
   timeoutMs: number,
   workdir?: string,
-  opts?: { tools?: ToolDefinition[]; mediaFiles?: MediaFile[] }
+  opts?: { tools?: ToolDefinition[]; mediaFiles?: MediaFile[]; log?: (msg: string) => void }
 ): Promise<string> {
   const model = stripPrefix(modelId);
   const args = ["--model", model, "--quiet", "--full-auto"];
@@ -532,10 +613,10 @@ export async function runCodex(
     ? buildToolPromptBlock(opts.tools) + "\n\n" + prompt
     : prompt;
 
-  const result = await runCli("codex", args, effectivePrompt, timeoutMs, { cwd });
+  const result = await runCli("codex", args, effectivePrompt, timeoutMs, { cwd, log: opts?.log });
 
   if (result.exitCode !== 0 && result.stdout.length === 0) {
-    throw new Error(`codex exited ${result.exitCode}: ${result.stderr || "(no output)"}`);
+    throw new Error(`codex exited ${result.exitCode}: ${annotateExitError(result.exitCode, result.stderr, result.timedOut, modelId)}`);
   }
 
   return result.stdout || result.stderr;
@@ -553,14 +634,15 @@ export async function runOpenCode(
   prompt: string,
   _modelId: string,
   timeoutMs: number,
-  workdir?: string
+  workdir?: string,
+  opts?: { log?: (msg: string) => void }
 ): Promise<string> {
   const args = ["run", prompt];
   const cwd = workdir ?? homedir();
-  const result = await runCliWithArg("opencode", args, timeoutMs, { cwd });
+  const result = await runCliWithArg("opencode", args, timeoutMs, { cwd, log: opts?.log });
 
   if (result.exitCode !== 0 && result.stdout.length === 0) {
-    throw new Error(`opencode exited ${result.exitCode}: ${result.stderr || "(no output)"}`);
+    throw new Error(`opencode exited ${result.exitCode}: ${annotateExitError(result.exitCode, result.stderr, result.timedOut, "opencode")}`);
   }
 
   return result.stdout || result.stderr;
@@ -578,14 +660,15 @@ export async function runPi(
   prompt: string,
   _modelId: string,
   timeoutMs: number,
-  workdir?: string
+  workdir?: string,
+  opts?: { log?: (msg: string) => void }
 ): Promise<string> {
   const args = ["-p", prompt];
   const cwd = workdir ?? homedir();
-  const result = await runCliWithArg("pi", args, timeoutMs, { cwd });
+  const result = await runCliWithArg("pi", args, timeoutMs, { cwd, log: opts?.log });
 
   if (result.exitCode !== 0 && result.stdout.length === 0) {
-    throw new Error(`pi exited ${result.exitCode}: ${result.stderr || "(no output)"}`);
+    throw new Error(`pi exited ${result.exitCode}: ${annotateExitError(result.exitCode, result.stderr, result.timedOut, "pi")}`);
   }
 
   return result.stdout || result.stderr;
@@ -663,6 +746,8 @@ export interface RouteOptions {
    * Passed to CLIs that support native media input (e.g. codex -i).
    */
   mediaFiles?: MediaFile[];
+  /** Logger for timeout and lifecycle events. */
+  log?: (msg: string) => void;
 }
 
 /**
@@ -708,12 +793,13 @@ export async function routeToCliRunner(
   // Resolve aliases (e.g. gemini-3-pro → gemini-3-pro-preview) after allowlist check
   const resolved = normalizeModelAlias(normalized);
 
+  const log = opts.log;
   let rawText: string;
-  if (resolved.startsWith("cli-gemini/"))        rawText = await runGemini(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools });
-  else if (resolved.startsWith("cli-claude/"))   rawText = await runClaude(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools });
-  else if (resolved.startsWith("openai-codex/")) rawText = await runCodex(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools, mediaFiles: opts.mediaFiles });
-  else if (resolved.startsWith("opencode/"))     rawText = await runOpenCode(prompt, resolved, timeoutMs, opts.workdir);
-  else if (resolved.startsWith("pi/"))           rawText = await runPi(prompt, resolved, timeoutMs, opts.workdir);
+  if (resolved.startsWith("cli-gemini/"))        rawText = await runGemini(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools, log });
+  else if (resolved.startsWith("cli-claude/"))   rawText = await runClaude(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools, log });
+  else if (resolved.startsWith("openai-codex/")) rawText = await runCodex(prompt, resolved, timeoutMs, opts.workdir, { tools: opts.tools, mediaFiles: opts.mediaFiles, log });
+  else if (resolved.startsWith("opencode/"))     rawText = await runOpenCode(prompt, resolved, timeoutMs, opts.workdir, { log });
+  else if (resolved.startsWith("pi/"))           rawText = await runPi(prompt, resolved, timeoutMs, opts.workdir, { log });
   else throw new Error(
     `Unknown CLI bridge model: "${model}". Use "vllm/cli-gemini/<model>", "vllm/cli-claude/<model>", "openai-codex/<model>", "opencode/<model>", or "pi/<model>".`
   );