lazyclaw 6.3.1 → 6.5.0

package/providers/cli_login.mjs

@@ -0,0 +1,179 @@
+// providers/cli_login.mjs — connect/login helpers for the keyless CLI
+// providers (codex-cli / gemini-cli) so the picker can offer an inline
+// "log in / connect" action instead of dead-ending on the CLI's own
+// "please log in" message.
+//
+// Two halves:
+//   - cliLoginStatus(): pure, dependency-injectable detection of whether a
+//     provider's CLI is installed and signed in (unit-tested).
+//   - runCliLoginInteractive(): spawns the real login / install subprocess
+//     with the terminal inherited. Driven from the chat post-loop guard
+//     after the Ink UI releases stdin (same mechanism /setup uses), so the
+//     browser-OAuth flow gets a real TTY.
+//
+// codex has a headless login (`codex login`, `codex login status`); gemini
+// does NOT — its Google sign-in only happens by launching `gemini`
+// interactively, or by supplying GEMINI_API_KEY. We model both.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync as _existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const CLI_LOGIN_PROVIDERS = {
+  'codex-cli': {
+    bin: 'codex',
+    pkg: '@openai/codex',
+    // `codex login` opens a browser for ChatGPT OAuth; `codex login status`
+    // exits 0 when signed in. `codex login --with-api-key` reads a key on stdin.
+    loginArgs: ['login'],
+    statusArgs: ['login', 'status'],
+    apiKeyStdinArgs: ['login', '--with-api-key'],
+    browserHint: 'codex login',
+    apiKeyHint: 'OpenAI key (sk-…) — stored by codex via `codex login --with-api-key`',
+  },
+  'gemini-cli': {
+    bin: 'gemini',
+    pkg: '@google/gemini-cli',
+    // No headless login: Google OAuth only runs when `gemini` is launched
+    // interactively. We detect sign-in by the presence of the OAuth creds
+    // file (or a GEMINI_API_KEY in the environment).
+    loginArgs: [],
+    credPath: join(homedir(), '.gemini', 'oauth_creds.json'),
+    apiKeyEnv: 'GEMINI_API_KEY',
+    browserHint: 'gemini (Google sign-in)',
+    apiKeyHint: 'Google AI Studio key — saved in lazyclaw and passed as GEMINI_API_KEY',
+  },
+};
+
+// Locate a binary on PATH without throwing. Returns the path or ''.
+function _whichSync(bin) {
+  try {
+    const r = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+    if (r.status === 0) return String(r.stdout || '').split('\n')[0].trim();
+  } catch (_) { /* ignore */ }
+  return '';
+}
+
+// Run `<bin> <args>` just for its exit code (codex login status). Resolves the
+// numeric code (or 1 on spawn error) — never rejects.
+function _runForCode(bin, args) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(bin, args, { stdio: ['ignore', 'ignore', 'ignore'] });
+    } catch (_) { resolve(1); return; }
+    proc.once('error', () => resolve(1));
+    proc.once('close', (code) => resolve(typeof code === 'number' ? code : 1));
+  });
+}
+
+/**
+ * Detect whether a keyless CLI provider is installed and signed in.
+ * All side-effecting lookups are injectable so this is unit-testable.
+ *
+ * @param {string} provName  'codex-cli' | 'gemini-cli'
+ * @param {{
+ *   which?: (bin:string)=>string,
+ *   runStatus?: (bin:string, args:string[])=>Promise<number>,
+ *   existsSync?: (p:string)=>boolean,
+ *   env?: Record<string,string|undefined>,
+ *   hasStoredKey?: boolean,   // a key already saved in lazyclaw for this provider
+ * }} [deps]
+ * @returns {Promise<{supported:boolean, binMissing?:boolean, loggedIn?:boolean, via?:string, pkg?:string}>}
+ */
+export async function cliLoginStatus(provName, deps = {}) {
+  const spec = CLI_LOGIN_PROVIDERS[provName];
+  if (!spec) return { supported: false };
+  const which = deps.which || _whichSync;
+  if (!which(spec.bin)) {
+    return { supported: true, binMissing: true, loggedIn: false, pkg: spec.pkg };
+  }
+  // An explicit lazyclaw-stored key means we can authenticate regardless of
+  // the CLI's own login state (codex via env, gemini via GEMINI_API_KEY).
+  if (deps.hasStoredKey) return { supported: true, binMissing: false, loggedIn: true, via: 'api-key' };
+  if (spec.statusArgs) {
+    const code = await (deps.runStatus || _runForCode)(spec.bin, spec.statusArgs);
+    return { supported: true, binMissing: false, loggedIn: code === 0, via: `${spec.bin} ${spec.statusArgs.join(' ')}` };
+  }
+  // gemini: no status command — infer from creds file / env key.
+  const existsSync = deps.existsSync || _existsSync;
+  const env = deps.env || process.env;
+  const ok = (!!spec.credPath && existsSync(spec.credPath)) || (!!spec.apiKeyEnv && !!env[spec.apiKeyEnv]);
+  return { supported: true, binMissing: false, loggedIn: ok, via: 'creds/env' };
+}
+
+// Spawn a command with the terminal inherited; resolve on close (never reject).
+function _spawnInherit(bin, args, opts = {}) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(bin, args, { stdio: 'inherit', ...opts });
+    } catch (e) {
+      process.stderr.write(`\n  failed to launch ${bin}: ${e?.message || e}\n`);
+      resolve(1);
+      return;
+    }
+    proc.once('error', (e) => { process.stderr.write(`\n  ${bin} error: ${e?.message || e}\n`); resolve(1); });
+    proc.once('close', (code) => resolve(typeof code === 'number' ? code : 0));
+  });
+}
+
+// Pipe a secret to a command's stdin (codex login --with-api-key), inheriting
+// stdout/stderr so the user sees the result. Resolves the exit code.
+function _spawnKeyStdin(bin, args, key) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(bin, args, { stdio: ['pipe', 'inherit', 'inherit'] });
+    } catch (e) { process.stderr.write(`\n  failed to launch ${bin}: ${e?.message || e}\n`); resolve(1); return; }
+    proc.once('error', (e) => { process.stderr.write(`\n  ${bin} error: ${e?.message || e}\n`); resolve(1); });
+    proc.once('close', (code) => resolve(typeof code === 'number' ? code : 0));
+    try { proc.stdin.write(String(key || '')); proc.stdin.end(); } catch (_) { /* closed already */ }
+  });
+}
+
+/**
+ * Run the chosen connect action in the foreground (terminal inherited). Called
+ * from the chat post-loop guard once Ink has released stdin.
+ *
+ * @param {{ provider:string, mode:'browser'|'install'|'apikey', apiKey?:string }} req
+ */
+export async function runCliLoginInteractive(req = {}) {
+  const { provider, mode, apiKey } = req;
+  const spec = CLI_LOGIN_PROVIDERS[provider];
+  if (!spec) { process.stderr.write(`\n  unknown login provider: ${provider}\n`); return; }
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+  const ok = (s) => `\x1b[32m${s}\x1b[0m`;
+
+  if (mode === 'install') {
+    process.stdout.write(`\n  Installing ${spec.pkg} …  ${dim(`npm i -g ${spec.pkg}`)}\n\n`);
+    const code = await _spawnInherit('npm', ['i', '-g', spec.pkg]);
+    process.stdout.write(code === 0
+      ? `\n  ${ok('✓ installed')} ${spec.pkg}. Re-open ${dim(`/provider ${provider}`)} to sign in.\n\n`
+      : `\n  install exited ${code}. You can run ${dim(`npm i -g ${spec.pkg}`)} yourself.\n\n`);
+    return;
+  }
+
+  if (mode === 'apikey') {
+    if (provider === 'codex-cli') {
+      process.stdout.write(`\n  Storing your OpenAI key via ${dim('codex login --with-api-key')} …\n\n`);
+      const code = await _spawnKeyStdin(spec.bin, spec.apiKeyStdinArgs, apiKey);
+      process.stdout.write(code === 0 ? `\n  ${ok('✓ codex signed in with an API key.')}\n\n` : `\n  codex login exited ${code}.\n\n`);
+    }
+    // gemini's key is persisted in lazyclaw config by the caller and injected
+    // as GEMINI_API_KEY at spawn time — nothing to run here.
+    return;
+  }
+
+  // Browser OAuth.
+  if (provider === 'codex-cli') {
+    process.stdout.write(`\n  Opening ${dim('codex login')} — a sign-in URL will appear. Complete it in your browser, then return here.\n\n`);
+    const code = await _spawnInherit(spec.bin, spec.loginArgs);
+    process.stdout.write(code === 0 ? `\n  ${ok('✓ codex signed in.')}\n\n` : `\n  codex login exited ${code}.\n\n`);
+  } else if (provider === 'gemini-cli') {
+    process.stdout.write(`\n  Launching ${dim('gemini')} for Google sign-in. Authenticate in the browser, then ${dim('/quit')} (or Ctrl-C) inside gemini to return.\n\n`);
+    await _spawnInherit(spec.bin, spec.loginArgs);
+    process.stdout.write(`\n  Back in lazyclaw.\n\n`);
+  }
+}

package/providers/codex_cli.mjs

@@ -30,6 +30,7 @@
 // shell input.
 
 import { spawnSandboxed } from '../sandbox.mjs';
+import { classifyCliExit } from './cli_error.mjs';
 
 class AbortError extends Error {
   constructor(message = 'aborted') {
@@ -51,19 +52,23 @@ class CliExitError extends Error {
   constructor(code, signal, stderr) {
     super(`codex CLI exited ${code ?? signal}: ${String(stderr).slice(0, 400)}`);
     this.name = 'CodexCliExitError';
-    this.code = 'CLI_EXIT';
+    // Transient upstream throttle → retriable RATE_LIMIT; genuine cap → CLI_EXIT.
+    const cls = classifyCliExit(stderr);
+    this.code = cls.code;
+    if (cls.retryAfterMs !== undefined) this.retryAfterMs = cls.retryAfterMs;
     this.exitCode = code;
     this.signal = signal;
     this.stderr = stderr;
   }
 }
 
-// Map a few friendly aliases. Codex CLI accepts the literal model id
-// (e.g. gpt-5-codex) directly, so unknown inputs pass through.
-const _ALIASES = {
-  codex: 'gpt-5-codex',
-  'gpt-codex': 'gpt-5-codex',
-};
+// No alias map. The previous aliases mapped "codex"/"gpt-codex" to
+// "gpt-5-codex", but that model is rejected by a ChatGPT-account codex
+// login ("not supported when using Codex with a ChatGPT account"), so the
+// alias actively produced a broken `-m`. An empty/unknown model now means
+// "no -m" → codex falls back to the account default in ~/.codex/config.toml,
+// which is the only model set guaranteed to be allowed for that login.
+const _ALIASES = {};
 
 // Drop cross-vendor model ids (claude-*, gemini-*) silently so the
 // CLI falls back to its own default. The orchestrator workflow forwards
@@ -107,13 +112,48 @@ function extractEventText(obj) {
   return '';
 }
 
+// Pull a human-readable error out of a codex failure event. Codex reports
+// API/turn failures on STDOUT (not stderr) as either:
+//   {"type":"error","message":"<json-string>"}
+//   {"type":"turn.failed","error":{"message":"<json-string>"}}
+// where the message is usually itself a JSON document
+//   {"type":"error","status":400,"error":{"message":"<the real reason>"}}.
+// We unwrap one level of nesting so callers surface "The 'x' model is not
+// supported …" instead of the misleading "Reading additional input from
+// stdin…" the CLI happens to print on stderr. Returns '' for non-error events.
+function extractEventError(obj) {
+  if (!obj || typeof obj !== 'object') return '';
+  if (obj.type !== 'error' && obj.type !== 'turn.failed') return '';
+  let raw = obj.type === 'turn.failed' ? (obj.error?.message ?? obj.message) : obj.message;
+  if (typeof raw === 'string') {
+    try {
+      const inner = JSON.parse(raw);
+      raw = inner?.error?.message || inner?.message || raw;
+    } catch (_) { /* not nested JSON — use the string as-is */ }
+  }
+  return typeof raw === 'string' ? raw : JSON.stringify(raw ?? obj);
+}
+
 function extractUsage(obj) {
   if (!obj || typeof obj !== 'object' || obj.type !== 'turn.completed') return null;
   const u = obj.usage || {};
-  const input = (u.input_tokens ?? 0) + (u.cached_input_tokens ?? 0);
-  const output = (u.output_tokens ?? 0) + (u.reasoning_output_tokens ?? 0);
-  if (!input && !output) return null;
-  return { inputTokens: input, outputTokens: output, totalCostUsd: 0 };
+  // OpenAI Responses-API convention (codex follows it): input_tokens already
+  // INCLUDES cached_input_tokens, and output_tokens already INCLUDES
+  // reasoning_output_tokens — they are subset breakdowns, not additive. Summing
+  // them double-counts and trips the cost cap early. Report NET (non-cached)
+  // input — total minus the cached subset — to match Anthropic's convention so
+  // rates.mjs's single cost formula doesn't bill the cached tokens at BOTH the
+  // input rate and the cache-read rate. Surface the cached subset separately.
+  const cacheRead = u.cached_input_tokens ?? 0;
+  const input = (u.input_tokens ?? 0) - cacheRead;
+  const output = u.output_tokens ?? 0;
+  if (!input && !output && !cacheRead) return null;
+  return {
+    inputTokens: input,
+    outputTokens: output,
+    cacheReadInputTokens: cacheRead,
+    totalCostUsd: 0,
+  };
 }
 
 export const codexCliProvider = {
@@ -160,6 +200,7 @@ export const codexCliProvider = {
 
     proc.stdout.setEncoding('utf8');
     let buffer = '';
+    let apiError = null;
     let exitInfo = null;
     const exitPromise = new Promise((resolve) => {
       proc.on('close', (code, signal) => {
@@ -181,6 +222,8 @@ export const codexCliProvider = {
           try { obj = JSON.parse(line); } catch { continue; }
           const text = extractEventText(obj);
           if (text) yield text;
+          const errMsg = extractEventError(obj);
+          if (errMsg) apiError = errMsg;
           const usage = extractUsage(obj);
           if (usage && typeof opts.onUsage === 'function') {
             try { opts.onUsage(usage); } catch (_) { /* never break stream on usage */ }
@@ -192,6 +235,14 @@ export const codexCliProvider = {
           const obj = JSON.parse(buffer.trim());
           const text = extractEventText(obj);
           if (text) yield text;
+          // Drain usage + error too, so a final turn.completed/turn.failed that
+          // isn't newline-terminated still reports tokens and surfaces the error.
+          const errMsg = extractEventError(obj);
+          if (errMsg) apiError = errMsg;
+          const usage = extractUsage(obj);
+          if (usage && typeof opts.onUsage === 'function') {
+            try { opts.onUsage(usage); } catch (_) { /* never break stream on usage */ }
+          }
         } catch (_) { /* incomplete tail — drop */ }
       }
       // Wait for either a clean exit or an async spawn error. On ENOENT the
@@ -201,6 +252,13 @@ export const codexCliProvider = {
       if (spawnError) {
         throw spawnError.code === 'ENOENT' ? new CliMissingError() : spawnError;
       }
+      // Prefer the real API/turn error (carried on stdout) over the CLI's
+      // unhelpful stderr ("Reading additional input from stdin…"). codex
+      // exits non-zero on turn.failed, so this runs before the generic
+      // exit-code branch and gives the actionable message.
+      if (apiError && !opts.signal?.aborted) {
+        throw new CliExitError(exitInfo?.code ?? 1, exitInfo?.signal ?? null, apiError);
+      }
       if (exitInfo && exitInfo.code !== 0 && !opts.signal?.aborted) {
         throw new CliExitError(exitInfo.code, exitInfo.signal, stderr);
       }
@@ -213,4 +271,4 @@ export const codexCliProvider = {
   },
 };
 
-export { CliMissingError, CliExitError, AbortError, resolveModel, buildPrompt, extractEventText, extractUsage };
+export { CliMissingError, CliExitError, AbortError, resolveModel, buildPrompt, extractEventText, extractEventError, extractUsage };

package/providers/gemini.mjs

@@ -50,6 +50,60 @@ class ApiError extends Error {
     this.body = body;
   }
 }
+class TimeoutError extends Error {
+  constructor(idleMs) {
+    super(`gemini: idle timeout — no stream activity for ${idleMs}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'TIMEOUT';
+    this.idleMs = idleMs;
+  }
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+
+// Resolve the IDLE (inter-chunk) timeout once per request: opts override
+// wins, then env LAZYCLAW_REQUEST_TIMEOUT_MS (positive int), else 120s.
+function resolveIdleTimeoutMs(opts) {
+  if (Number.isFinite(opts?.idleTimeoutMs) && opts.idleTimeoutMs > 0) return opts.idleTimeoutMs;
+  const raw = parseInt(process.env.LAZYCLAW_REQUEST_TIMEOUT_MS ?? '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return DEFAULT_IDLE_TIMEOUT_MS;
+}
+
+// Wrap a chunk iterator with an IDLE timeout: abort only when NO chunk has
+// arrived for idleMs (the timer resets on every received chunk, and also
+// guards the connect/first-byte phase). This is NOT a total-duration cap,
+// so a long but healthy generation that streams steadily is never aborted.
+// `controller` is aborted on idle expiry so the real connection tears down.
+async function* iterateWithIdleTimeout(body, idleMs, controller) {
+  const iterator = iterateBody(body)[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new TimeoutError(idleMs));
+        }, idleMs);
+      });
+      let step;
+      try {
+        step = await Promise.race([iterator.next(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // Best-effort, NON-awaited cleanup: on idle abort the underlying reader
+    // may be suspended on a read that never settles, so awaiting return()
+    // would re-hang us. The controller abort already tears down the socket.
+    if (typeof iterator.return === 'function') {
+      try { Promise.resolve(iterator.return()).catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+}
 
 function parseRetryAfterMs(headers) {
   let raw = null;
@@ -117,6 +171,7 @@ function toGeminiBody(messages, opts) {
   }
   const body = { contents };
   if (systemText) body.systemInstruction = { parts: [{ text: systemText }] };
+  if (Number.isFinite(opts.maxTokens)) body.generationConfig = { maxOutputTokens: opts.maxTokens };
   return body;
 }
 
@@ -131,16 +186,31 @@ export const geminiProvider = {
     const fetchFn = opts.fetch || globalThis.fetch;
     if (!fetchFn) throw new Error('gemini: no fetch implementation available');
     const baseUrl = (opts.baseUrl || DEFAULT_BASE).replace(/\/$/, '');
-    const model = opts.model || 'gemini-1.5-pro';
+    const model = opts.model || 'gemini-2.5-pro';
 
     if (opts.signal?.aborted) throw new AbortError('aborted before request');
 
+    // Compose the caller's signal with an internal controller that the idle
+    // timeout aborts. The composed signal goes to fetch so a stalled
+    // connection (or a user cancel) tears down the real socket.
+    const idleMs = resolveIdleTimeoutMs(opts);
+    const idleController = new AbortController();
+    const fetchSignal = opts.signal
+      ? (typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([opts.signal, idleController.signal])
+          : idleController.signal)
+      : idleController.signal;
+    const forwardCallerAbort = () => idleController.abort();
+    if (opts.signal && typeof AbortSignal.any !== 'function') {
+      opts.signal.addEventListener('abort', forwardCallerAbort, { once: true });
+    }
+
     const url = `${baseUrl}/models/${encodeURIComponent(model)}:streamGenerateContent?alt=sse&key=${encodeURIComponent(opts.apiKey)}`;
     const res = await fetchFn(url, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(toGeminiBody(messages, opts)),
-      signal: opts.signal,
+      signal: fetchSignal,
     });
 
     if (!res.ok) {
@@ -152,7 +222,12 @@ export const geminiProvider = {
 
     const decoder = new TextDecoder('utf-8', { fatal: false });
     let buffer = '';
-    for await (const chunk of iterateBody(res.body)) {
+    let lastUsage = null;   // Gemini sends a cumulative usageMetadata; keep the last
+    let lastFinish = null;
+    try {
+    for await (const chunk of iterateWithIdleTimeout(res.body, idleMs, idleController)) {
+      // A user cancel surfaces as an idle-controller abort too; map it back
+      // to ABORT so it stays distinguishable from a TIMEOUT.
       if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
       buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
       let consumed = 0;
@@ -169,6 +244,9 @@ export const geminiProvider = {
               if (typeof p?.text === 'string' && p.text) yield p.text;
             }
           }
+          if (obj?.usageMetadata) lastUsage = obj.usageMetadata;
+          const fr = obj?.candidates?.[0]?.finishReason;
+          if (fr) lastFinish = fr;
           // Some error responses surface mid-stream as {error: {...}}.
           if (obj?.error) {
             const message = obj.error.message || JSON.stringify(obj.error);
@@ -181,6 +259,29 @@ export const geminiProvider = {
       }
       if (consumed > 0) buffer = buffer.slice(consumed);
     }
+    } finally {
+      if (opts.signal && typeof AbortSignal.any !== 'function') {
+        opts.signal.removeEventListener('abort', forwardCallerAbort);
+      }
+    }
+    // Stream completed cleanly — surface the final usage + any truncation.
+    if (lastUsage && typeof opts.onUsage === 'function') {
+      try {
+        opts.onUsage({
+          // promptTokenCount is cache-INCLUSIVE; report NET (minus cached) to
+          // match Anthropic's convention so rates.mjs doesn't bill the cached
+          // tokens at BOTH the input rate and the cache-read rate.
+          inputTokens: (lastUsage.promptTokenCount ?? 0) - (lastUsage.cachedContentTokenCount ?? 0),
+          outputTokens: lastUsage.candidatesTokenCount ?? null,
+          cacheReadInputTokens: lastUsage.cachedContentTokenCount ?? 0,
+          totalCostUsd: 0,
+        });
+      } catch { /* never fail the stream on a usage callback */ }
+    }
+    if (typeof opts.onTruncated === 'function'
+        && (lastFinish === 'MAX_TOKENS' || lastFinish === 'SAFETY' || lastFinish === 'RECITATION')) {
+      try { opts.onTruncated(lastFinish); } catch { /* ditto */ }
+    }
   },
 };
 

package/providers/gemini_cli.mjs

@@ -19,12 +19,14 @@
 // REPL both treat AsyncIterable<string> as their only contract, so
 // non-streaming is transparent to callers.
 //
-// Why `--skip-trust` is hard-coded: lazyclaw orchestrator / workflow
-// subprocesses commonly run from /tmp or scratch dirs which gemini's
-// trusted-folder policy rejects. We are spawning gemini ourselves with
-// our own prompt, so the policy adds friction without security value.
+// The trusted-folder bypass (`--skip-trust` + GEMINI_CLI_TRUST_WORKSPACE) is
+// enabled by default because lazyclaw orchestrator / workflow subprocesses
+// commonly run from /tmp or scratch dirs that gemini's trusted-folder policy
+// rejects in headless -p mode. It is a genuine trust bypass, now consolidated
+// behind one switch (opts.trustWorkspace, default true) — see geminiArgs/geminiEnv.
 
 import { spawnSandboxed } from '../sandbox.mjs';
+import { classifyCliExit } from './cli_error.mjs';
 
 class AbortError extends Error {
   constructor(message = 'aborted') {
@@ -46,7 +48,10 @@ class CliExitError extends Error {
   constructor(code, signal, stderr) {
     super(`gemini CLI exited ${code ?? signal}: ${String(stderr).slice(0, 400)}`);
     this.name = 'GeminiCliExitError';
-    this.code = 'CLI_EXIT';
+    // Transient upstream throttle → retriable RATE_LIMIT; genuine cap → CLI_EXIT.
+    const cls = classifyCliExit(stderr);
+    this.code = cls.code;
+    if (cls.retryAfterMs !== undefined) this.retryAfterMs = cls.retryAfterMs;
     this.exitCode = code;
     this.signal = signal;
     this.stderr = stderr;
@@ -95,14 +100,49 @@ function buildPrompt(messages, system) {
 function extractUsage(stats) {
   if (!stats || typeof stats !== 'object') return null;
   const models = stats.models || {};
-  let input = 0, output = 0;
+  let input = 0, output = 0, cached = 0;
   for (const m of Object.values(models)) {
     const t = m?.tokens || {};
-    input  += (t.prompt ?? t.input ?? 0);
-    output += (t.candidates ?? t.output ?? 0);
+    // cached is a subset of prompt → report NET (prompt minus cached) so it
+    // matches Anthropic's convention and rates.mjs doesn't bill the cached
+    // tokens at BOTH the input rate and the cache-read rate. Surface cached
+    // separately so it can still bill at the cache-read rate.
+    input  += (t.prompt ?? t.input ?? 0) - (t.cached ?? 0);
+    // thoughts = reasoning tokens, billed as output and reported separately from
+    // candidates (additive).
+    output += (t.candidates ?? t.output ?? 0) + (t.thoughts ?? 0);
+    cached += (t.cached ?? 0);
   }
-  if (!input && !output) return null;
-  return { inputTokens: input, outputTokens: output, totalCostUsd: 0 };
+  if (!input && !output && !cached) return null;
+  return { inputTokens: input, outputTokens: output, cacheReadInputTokens: cached, totalCostUsd: 0 };
+}
+
+// The gemini trusted-folder bypass — needed because lazyclaw runs gemini from
+// scratch dirs (/tmp, worker cwds) that gemini's trusted-folder policy would
+// otherwise reject in headless -p mode. It is a GENUINE trust bypass, so it
+// lives behind ONE switch: opts.trustWorkspace (default true) gates BOTH the
+// --skip-trust flag AND the GEMINI_CLI_TRUST_WORKSPACE env that previously
+// duplicated it (so dropping one no longer silently left the other). Pass
+// trustWorkspace:false to enforce the policy — safest when the subprocess also
+// runs under confinement.
+export function geminiArgs(prompt, opts = {}) {
+  const args = [];
+  if (opts.trustWorkspace !== false) args.push('--skip-trust');
+  args.push('-p', prompt, '-o', 'json');
+  const model = resolveModel(opts.model);
+  if (model) args.push('-m', model);
+  return args;
+}
+
+export function geminiEnv(opts = {}) {
+  return {
+    ...process.env,
+    ...(opts.trustWorkspace !== false ? { GEMINI_CLI_TRUST_WORKSPACE: 'true' } : {}),
+    // Forward a lazyclaw-stored key as GEMINI_API_KEY so the "paste an API key"
+    // connect path authenticates the subprocess (the gemini CLI reads this env
+    // var). Omitted when blank so a Google-OAuth login is unaffected.
+    ...(opts.apiKey ? { GEMINI_API_KEY: String(opts.apiKey) } : {}),
+  };
 }
 
 export const geminiCliProvider = {
@@ -112,9 +152,7 @@ export const geminiCliProvider = {
     const prompt = buildPrompt(messages, opts.system || messages.find(m => m.role === 'system')?.content);
     if (!prompt) return;
 
-    const args = ['--skip-trust', '-p', prompt, '-o', 'json'];
-    const model = resolveModel(opts.model);
-    if (model) args.push('-m', model);
+    const args = geminiArgs(prompt, opts);
 
     if (opts.signal?.aborted) throw new AbortError('aborted before spawn');
 
@@ -123,7 +161,7 @@ export const geminiCliProvider = {
       proc = spawnSandboxed(opts.sandbox || null, bin, args, {
         cwd: opts.cwd || process.cwd(),
         stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env, GEMINI_CLI_TRUST_WORKSPACE: 'true' },
+        env: geminiEnv(opts),
       });
     } catch (err) {
       if (err && err.code === 'ENOENT') throw new CliMissingError();
@@ -177,7 +215,26 @@ export const geminiCliProvider = {
       } catch (err) {
         throw new Error(`gemini CLI returned non-JSON stdout: ${err.message} :: ${payload.slice(0, 200)}`);
       }
+      // The JSON payload carries an optional `error` object on failure
+      // (gemini-cli --output-format json: "response, stats, and errors").
+      // A failed turn can still exit 0 with an empty response + an error,
+      // so surface it instead of silently yielding nothing.
       const text = typeof parsed.response === 'string' ? parsed.response : '';
+      if (!text && parsed.error) {
+        // A failed turn is still METERED: gemini-cli puts the partial token
+        // usage in the SAME JSON's `stats` even when the turn errored out. Bill
+        // it BEFORE throwing so a failed-but-metered turn still reaches the cost
+        // cap (the error path used to throw before extractUsage ever ran, so a
+        // failed turn leaked its tokens past accounting). Guarded so a usage
+        // callback can never mask the real error.
+        const failedUsage = extractUsage(parsed.stats);
+        if (failedUsage && typeof opts.onUsage === 'function') {
+          try { opts.onUsage(failedUsage); } catch (_) { /* never let usage hide the error */ }
+        }
+        const em = parsed.error?.message
+          || (typeof parsed.error === 'string' ? parsed.error : JSON.stringify(parsed.error));
+        throw new CliExitError(exitInfo.code, exitInfo.signal, em);
+      }
       if (text) yield text;
       const usage = extractUsage(parsed.stats);
       if (usage && typeof opts.onUsage === 'function') {
@@ -185,11 +242,15 @@ export const geminiCliProvider = {
       }
     } finally {
       if (opts.signal) opts.signal.removeEventListener('abort', onAbort);
-      if (!proc.killed && exitInfo === null) {
-        try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
-      }
+      // Unlike the streaming claude-cli/codex-cli providers (which yield chunks
+      // while the child still runs and so need a mid-stream-bail kill), gemini
+      // buffers the whole turn and `await`s the close/spawn-error race BEFORE the
+      // single yield above. By the time this finally runs the child has already
+      // exited (or we threw on spawnError before reaching here), so there is no
+      // live subprocess to reap — the old `exitInfo === null` guard was dead.
     }
   },
 };
 
 export { CliMissingError, CliExitError, AbortError, resolveModel, buildPrompt, extractUsage };
+// geminiArgs/geminiEnv are also exported at their definitions (trust-switch seam).