@elvatis_com/openclaw-cli-bridge-elvatis 2.4.0 → 2.5.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.5.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 (217 tests)
 npm run ci          # lint + typecheck + test
 ```
 
@@ -376,6 +386,17 @@ npm run ci          # lint + typecheck + test
 
 ## Changelog
 
+### 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.5.0

package/index.ts

@@ -98,6 +98,7 @@ interface CliPluginConfig {
   proxyPort?: number;
   proxyApiKey?: string;
   proxyTimeoutMs?: number;
+  modelTimeouts?: Record<string, number>;
   grokSessionPath?: string;
 }
 
@@ -987,7 +988,22 @@ 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 ?? 300_000;
+    // Per-model timeout overrides — fall back to sensible defaults if not configured.
+    // Interactive/fast models get shorter timeouts, heavy models get more time.
+    const defaultModelTimeouts: Record<string, number> = {
+      "cli-claude/claude-opus-4-6":       300_000,  // 5 min — heavy, agentic tasks
+      "cli-claude/claude-sonnet-4-6":     180_000,  // 3 min — standard interactive chat
+      "cli-claude/claude-haiku-4-5":       90_000,  // 90s  — fast responses
+      "cli-gemini/gemini-2.5-pro":        180_000,
+      "cli-gemini/gemini-2.5-flash":       90_000,
+      "cli-gemini/gemini-3-pro-preview":  180_000,
+      "cli-gemini/gemini-3-flash-preview": 90_000,
+      "openai-codex/gpt-5.4":            300_000,
+      "openai-codex/gpt-5.3-codex":      180_000,
+      "openai-codex/gpt-5.1-codex-mini":  90_000,
+    };
+    const modelTimeouts = { ...defaultModelTimeouts, ...cfg.modelTimeouts };
     const codexAuthPath = cfg.codexAuthPath ?? DEFAULT_CODEX_AUTH_PATH;
     const grokSessionPath = cfg.grokSessionPath ?? DEFAULT_SESSION_PATH;
 
@@ -1379,6 +1395,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 +1432,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.5.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.5.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

@@ -278,6 +278,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 +289,25 @@ export interface RunCliOptions {
    */
   cwd?: string;
   timeoutMs?: number;
+  /** Optional logger for timeout events. */
+  log?: (msg: string) => void;
 }
 
+/**
+ * Grace period between SIGTERM and SIGKILL when a timeout fires.
+ * Gives the CLI process 5 seconds to flush output and exit cleanly.
+ */
+const TIMEOUT_GRACE_MS = 5_000;
+
 /**
  * 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.
  */
@@ -303,16 +319,40 @@ export function runCli(
   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 +362,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,6 +376,7 @@ 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,
@@ -342,30 +385,66 @@ export function runCliWithArg(
   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 +470,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 +483,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 +493,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 +513,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 +536,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 +561,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 +591,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 +615,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 +636,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 +662,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 +748,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 +795,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>".`
   );

package/src/proxy-server.ts

@@ -82,6 +82,20 @@ export interface ProxyServerOptions {
    * with the fallback model. Example: "cli-gemini/gemini-2.5-pro" → "cli-gemini/gemini-2.5-flash"
    */
   modelFallbacks?: Record<string, string>;
+  /**
+   * Per-model timeout overrides (ms). Keys are model IDs (without "vllm/" prefix).
+   * Use this to give heavy models more time or limit fast models.
+   *
+   * Example:
+   *   {
+   *     "cli-claude/claude-sonnet-4-6": 180_000,   // 3 min for interactive chat
+   *     "cli-claude/claude-opus-4-6":   300_000,    // 5 min for heavy tasks
+   *     "cli-claude/claude-haiku-4-5":  90_000,     // 90s for fast responses
+   *   }
+   *
+   * When not set for a model, falls back to proxyTimeoutMs (default 300s base).
+   */
+  modelTimeouts?: Record<string, number>;
 }
 
 /** Available CLI bridge models for GET /v1/models */
@@ -623,13 +637,16 @@ async function handleRequest(
     // ── CLI runner routing (Gemini / Claude Code / Codex) ──────────────────────
     let result: CliToolResult;
     let usedModel = model;
-    const routeOpts = { workdir, tools: hasTools ? tools : undefined, mediaFiles: mediaFiles.length ? mediaFiles : undefined };
+    const routeOpts = { workdir, tools: hasTools ? tools : undefined, mediaFiles: mediaFiles.length ? mediaFiles : undefined, log: opts.log };
 
     // ── Dynamic timeout: scale with conversation size ────────────────────────
-    const baseTimeout = opts.timeoutMs ?? 300_000; // 5 min default (was 120s)
+    // Per-model timeout takes precedence, then global proxyTimeoutMs, then 300s default.
+    const perModelTimeout = opts.modelTimeouts?.[model];
+    const baseTimeout = perModelTimeout ?? opts.timeoutMs ?? 300_000;
     const msgExtra = Math.max(0, cleanMessages.length - 10) * 2_000;
     const toolExtra = (tools?.length ?? 0) * 5_000;
     const effectiveTimeout = Math.min(baseTimeout + msgExtra + toolExtra, 600_000);
+    opts.log(`[cli-bridge] ${model} timeout: ${Math.round(effectiveTimeout / 1000)}s (base=${Math.round(baseTimeout / 1000)}s${perModelTimeout ? " per-model" : ""}, +${Math.round(msgExtra / 1000)}s msgs, +${Math.round(toolExtra / 1000)}s tools)`);
 
     // ── SSE keepalive: send headers early so OpenClaw doesn't read-timeout ──
     let sseHeadersSent = false;
@@ -654,10 +671,12 @@ async function handleRequest(
       const primaryDuration = Date.now() - cliStart;
       const msg = (err as Error).message;
       // ── Model fallback: retry once with a lighter model if configured ────
+      const isTimeout = msg.includes("timeout:") || msg.includes("exit 143") || msg.includes("exited 143");
       const fallbackModel = opts.modelFallbacks?.[model];
       if (fallbackModel) {
         metrics.recordRequest(model, primaryDuration, false);
-        opts.warn(`[cli-bridge] ${model} failed (${msg}), falling back to ${fallbackModel}`);
+        const reason = isTimeout ? "timeout by supervisor" : msg;
+        opts.warn(`[cli-bridge] ${model} failed (${reason}), falling back to ${fallbackModel}`);
         const fallbackStart = Date.now();
         try {
           result = await routeToCliRunner(fallbackModel, cleanMessages, effectiveTimeout, routeOpts);

package/src/session-manager.ts

@@ -95,6 +95,8 @@ function buildMinimalEnv(): Record<string, string> {
 /** Auto-cleanup interval: 30 minutes. */
 const SESSION_TTL_MS = 30 * 60 * 1000;
 const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+/** Grace period between SIGTERM and SIGKILL for session termination. */
+const KILL_GRACE_MS = 5_000;
 
 export class SessionManager {
   private sessions = new Map<string, SessionEntry>();
@@ -213,12 +215,19 @@ export class SessionManager {
     }
   }
 
-  /** Send SIGTERM to the session process. */
+  /**
+   * Gracefully terminate a session: SIGTERM first, then SIGKILL after grace period.
+   * This prevents the ambiguous "exit 143 (no output)" pattern.
+   */
   kill(sessionId: string): boolean {
     const entry = this.sessions.get(sessionId);
     if (!entry || entry.status !== "running") return false;
     entry.status = "killed";
     entry.proc.kill("SIGTERM");
+    // If the process doesn't exit within the grace period, force-kill it
+    setTimeout(() => {
+      try { if (!entry.proc.killed) entry.proc.kill("SIGKILL"); } catch { /* already dead */ }
+    }, KILL_GRACE_MS);
     return true;
   }
 
@@ -238,7 +247,7 @@ export class SessionManager {
     return result;
   }
 
-  /** Remove sessions older than SESSION_TTL_MS. Kill running ones first. Clean up isolated workdirs. */
+  /** Remove sessions older than SESSION_TTL_MS. Kill running ones with graceful SIGTERM→SIGKILL. */
   cleanup(): void {
     const now = Date.now();
     for (const [sessionId, entry] of this.sessions) {
@@ -246,6 +255,10 @@ export class SessionManager {
         if (entry.status === "running") {
           entry.proc.kill("SIGTERM");
           entry.status = "killed";
+          // Escalate to SIGKILL after grace period
+          setTimeout(() => {
+            try { if (!entry.proc.killed) entry.proc.kill("SIGKILL"); } catch { /* already dead */ }
+          }, KILL_GRACE_MS);
         }
         // Clean up isolated workdir if it wasn't cleaned on exit
         if (entry.isolatedWorkdir) {
@@ -258,17 +271,20 @@ export class SessionManager {
     sweepOrphanedWorkdirs();
   }
 
-  /** Stop the cleanup timer (for graceful shutdown). */
+  /** Stop the cleanup timer (for graceful shutdown). SIGTERM all sessions, SIGKILL after grace. */
   stop(): void {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = null;
     }
-    // Kill all running sessions and clean up their workdirs
+    // Kill all running sessions with graceful SIGTERM → SIGKILL escalation
     for (const [, entry] of this.sessions) {
       if (entry.status === "running") {
         entry.proc.kill("SIGTERM");
         entry.status = "killed";
+        setTimeout(() => {
+          try { if (!entry.proc.killed) entry.proc.kill("SIGKILL"); } catch { /* already dead */ }
+        }, KILL_GRACE_MS);
       }
       if (entry.isolatedWorkdir) {
         cleanupWorkdir(entry.isolatedWorkdir);

package/test/cli-runner-extended.test.ts

@@ -265,3 +265,75 @@ describe("Codex auto-git-init via routeToCliRunner", () => {
     expect(mockExecSync).toHaveBeenCalledWith("git init", expect.objectContaining({ cwd: "/no-git-dir" }));
   });
 });
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Timeout handling: graceful SIGTERM → SIGKILL and exit 143 annotation
+// ──────────────────────────────────────────────────────────────────────────────
+
+import { runCli, annotateExitError } from "../src/cli-runner.js";
+
+describe("runCli() timeout handling", () => {
+  it("does NOT pass timeout to spawn options (manual timer instead)", async () => {
+    mockSpawn.mockImplementation(() => makeFakeProc("ok", 0));
+    await runCli("echo", [], "hello", 60_000);
+    const spawnOpts = mockSpawn.mock.calls[0][2];
+    expect(spawnOpts.timeout).toBeUndefined();
+  });
+
+  it("sends SIGTERM after timeout fires", async () => {
+    vi.useFakeTimers();
+    const proc = new EventEmitter() as any;
+    proc.stdout = new EventEmitter();
+    proc.stderr = new EventEmitter();
+    proc.stdin = { write: vi.fn((_d: string, _e: string, cb?: () => void) => { cb?.(); }), end: vi.fn() };
+    proc.kill = vi.fn(() => { proc.emit("close", 143); });
+    proc.killed = false;
+    mockSpawn.mockImplementation(() => proc);
+
+    const logMessages: string[] = [];
+    const promise = runCli("claude", [], "prompt", 100, { log: (m) => logMessages.push(m) });
+
+    // Advance past the timeout
+    vi.advanceTimersByTime(101);
+
+    const result = await promise;
+    expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
+    expect(result.timedOut).toBe(true);
+    expect(result.exitCode).toBe(143);
+    expect(logMessages.some(m => m.includes("timeout") && m.includes("SIGTERM"))).toBe(true);
+    vi.useRealTimers();
+  });
+
+  it("sets timedOut=false for normal exits", async () => {
+    mockSpawn.mockImplementation(() => makeFakeProc("output", 0));
+    const result = await runCli("echo", [], "hello", 60_000);
+    expect(result.timedOut).toBe(false);
+    expect(result.exitCode).toBe(0);
+  });
+});
+
+describe("annotateExitError()", () => {
+  it("annotates exit 143 as timeout", () => {
+    const msg = annotateExitError(143, "(no output)", false, "cli-claude/claude-sonnet-4-6");
+    expect(msg).toContain("timeout");
+    expect(msg).toContain("supervisor");
+    expect(msg).toContain("cli-claude/claude-sonnet-4-6");
+  });
+
+  it("annotates when timedOut is true regardless of exit code", () => {
+    const msg = annotateExitError(1, "some error", true, "cli-claude/claude-sonnet-4-6");
+    expect(msg).toContain("timeout");
+    expect(msg).toContain("supervisor");
+  });
+
+  it("returns plain error when not a timeout", () => {
+    const msg = annotateExitError(1, "auth error", false, "cli-claude/claude-sonnet-4-6");
+    expect(msg).toBe("auth error");
+    expect(msg).not.toContain("timeout");
+  });
+
+  it("returns (no output) placeholder when stderr is empty and not a timeout", () => {
+    const msg = annotateExitError(1, "", false, "cli-claude/claude-sonnet-4-6");
+    expect(msg).toBe("(no output)");
+  });
+});