codehere 0.5.0-alpha.6 → 0.6.0

package/dist/infrastructure/orchestration/failover-classifier.js

@@ -0,0 +1,151 @@
+/**
+ * Failover classifier — v0.6.x rate-limit fail-over wedge (Slice A).
+ *
+ * Interprets adapter error codes to decide whether fail-over to a different
+ * adapter should be offered to the user. Pure function — no I/O, no adapter
+ * spawning. Adapters already detect rate-limit / quota errors via their
+ * ERROR_PATTERNS arrays and emit `codehere:error` events with codes:
+ *   - 'rate_limit'      — Anthropic / OpenAI / Google 429s
+ *   - 'quota_exceeded'  — credit balance / quota exhausted
+ *   - 'auth_invalid'    — NOT failover-eligible (different fix)
+ *   - other codes       — NOT failover-eligible (specific to provider)
+ *
+ * This module's job: take an emitted error code, return either a FailoverSignal
+ * (caller should ask user "switch to Codex?") or null (don't offer failover).
+ *
+ * Per `feedback_research_sharpens_not_pivots.md` — this sharpens what already
+ * ships (per-adapter error patterns) rather than introducing a new detection
+ * mechanism. Per claim_market_position v4 — the fail-over capability is the
+ * v0.6 outward proof point that demonstrates codehere's vendor-neutral value
+ * (only a vendor-neutral layer can switch you off Claude when Claude refuses).
+ *
+ * Slice A scope (this commit): the pure classifier + retry-after parser +
+ * tests. Slices B-F wire policy resolution, user consent, mid-task hand-off,
+ * UI surfacing, and end-to-end integration.
+ */
+/**
+ * Error codes that should trigger a fail-over offer. Keep tight — false
+ * positives waste user attention with "switch?" prompts they don't want.
+ *
+ * Verified against current adapter ERROR_PATTERNS (May 2026):
+ *   - 'rate_limit'      — emitted by all 5 adapters on 429s
+ *   - 'quota_exceeded'  — emitted by codex-adapter, gemini-adapter
+ *   - 'credit_low'      — emitted by claude-code-adapter, aider-adapter
+ *                         when API credit balance is exhausted
+ *
+ * NOT included (and why):
+ *   - 'auth_invalid' — fixing the wrong adapter doesn't help; switching to
+ *     a different agent that ALSO needs auth doesn't fix anything
+ *   - generic errors — no signal that another adapter would do better
+ *   - timeouts — could be transient on either side
+ */
+const FAILOVER_TRIGGER_CODES = new Set(['rate_limit', 'quota_exceeded', 'credit_low']);
+/**
+ * Returns a FailoverSignal if the error code suggests we should offer
+ * fail-over to a different adapter, null otherwise. Pure function — no
+ * side effects. Caller decides how to surface the offer (CLI prompt,
+ * web UI banner, programmatic auto-failover).
+ *
+ * @param fromAgent  Adapter id of the agent that hit the error
+ * @param errorCode  Code from the adapter's ERROR_PATTERNS classification
+ * @param errorMessage  Original error text (used to extract retry-after)
+ */
+export function classifyFailoverEligibility(fromAgent, errorCode, errorMessage) {
+    if (!FAILOVER_TRIGGER_CODES.has(errorCode))
+        return null;
+    if (!fromAgent)
+        return null;
+    const retryAfterMs = parseRetryAfterMs(errorMessage);
+    const signal = {
+        fromAgent,
+        errorCode,
+        reason: errorMessage || `${fromAgent} hit ${errorCode}`,
+    };
+    if (retryAfterMs !== undefined)
+        signal.retryAfterMs = retryAfterMs;
+    return signal;
+}
+/**
+ * Best-effort extraction of retry-after from common error message shapes.
+ * Returns milliseconds or undefined. Conservative — only matches patterns
+ * we've seen in real provider responses; unknown shapes return undefined
+ * (caller treats as "unknown — show indefinite wait").
+ *
+ * Patterns recognized:
+ *   - "Retry-After: 60"
+ *   - "retry after 60s"
+ *   - "retry after 60 seconds"
+ *   - "try again in 2 minutes"
+ *   - "wait 5 min"
+ *   - "wait 90 seconds"
+ *   - "in 2m 30s" (rare, treat as 2 minutes)
+ *
+ * NOT matched (intentionally — too ambiguous):
+ *   - bare numbers ("60") — could be anything
+ *   - "wait a moment" — no quantity
+ */
+export function parseRetryAfterMs(message) {
+    if (!message)
+        return undefined;
+    // "Retry-After: <N> <unit>" — HTTP header style with EXPLICIT unit.
+    // Per RFC 7231, default unit is seconds; we also accept explicit unit
+    // suffix (some providers add one for clarity, e.g. "Retry-After: 5 minutes").
+    // Must NOT match HTTP-date forms ("Retry-After: Wed, 21 Oct ...").
+    const headerWithUnitMatch = message.match(/retry-?after[:\s]+(\d+)\s*(seconds?|secs?|s\b|minutes?|mins?|m\b|hours?|hrs?|h\b)/i);
+    if (headerWithUnitMatch) {
+        const n = Number(headerWithUnitMatch[1]);
+        const unit = headerWithUnitMatch[2].toLowerCase();
+        if (Number.isFinite(n) && n > 0)
+            return convertToMs(n, unit);
+    }
+    // "Retry-After: 60" — bare header with no unit, defaults to seconds per RFC.
+    // Negative lookahead rejects HTTP-date forms (alphabetic chars after the digits).
+    const headerBareMatch = message.match(/retry-?after[:\s]+(\d+)(?!\s*[A-Za-z])/i);
+    if (headerBareMatch) {
+        const sec = Number(headerBareMatch[1]);
+        if (Number.isFinite(sec) && sec > 0)
+            return sec * 1000;
+    }
+    // Order matters: try LARGER units first so compound durations like
+    // "2m 30s" or "1h 45m" don't get misread as the smaller unit. Without
+    // this, "try again in 2m 30s" would match the seconds pattern on "30s"
+    // and return 30 seconds instead of ~2 minutes.
+    //
+    // Each pattern accepts a fractional value (e.g. OpenAI's "try again in 1.23s")
+    // — bare-int regex would have matched "23s" and missed the "1." prefix,
+    // returning 23 seconds instead of ~1.23 seconds. Capture group is "\d+(?:\.\d+)?".
+    // "in 2 hours" / "try again in 1 hour" — common for daily / weekly limits
+    const naturalHoursMatch = message.match(/(?:retry|try again|in|wait|reset).*?(\d+(?:\.\d+)?)\s*hours?\b/i);
+    if (naturalHoursMatch) {
+        const hr = Number(naturalHoursMatch[1]);
+        if (Number.isFinite(hr) && hr > 0)
+            return Math.round(hr * 60 * 60 * 1000);
+    }
+    // "retry after 2 minutes" / "try again in 5 min" / "wait 5 min" / "in 2m 30s"
+    const naturalMinutesMatch = message.match(/(?:retry|try again|wait).*?(\d+(?:\.\d+)?)\s*(?:minutes?|mins?|m\b)/i);
+    if (naturalMinutesMatch) {
+        const min = Number(naturalMinutesMatch[1]);
+        if (Number.isFinite(min) && min > 0)
+            return Math.round(min * 60 * 1000);
+    }
+    // "retry after 60s" / "try again in 60s" / "wait 60s" / "try again in 1.23s"
+    // (OpenAI returns fractional seconds for sub-2-second rate-limit windows).
+    // Last because compound durations like "2m 30s" should be read as minutes.
+    const naturalSecondsMatch = message.match(/(?:retry|try again|wait).*?(\d+(?:\.\d+)?)\s*(?:seconds?|secs?|s\b)/i);
+    if (naturalSecondsMatch) {
+        const sec = Number(naturalSecondsMatch[1]);
+        if (Number.isFinite(sec) && sec > 0)
+            return Math.round(sec * 1000);
+    }
+    return undefined;
+}
+/** Convert a number + unit string to milliseconds. Unit is one of the regex
+ *  alternatives in the header-with-unit pattern above. */
+function convertToMs(n, unit) {
+    if (/^h/i.test(unit))
+        return n * 60 * 60 * 1000;
+    if (/^m/i.test(unit))
+        return n * 60 * 1000;
+    return n * 1000; // seconds (default)
+}
+//# sourceMappingURL=failover-classifier.js.map

package/dist/infrastructure/orchestration/failover-config.js

@@ -0,0 +1,77 @@
+/**
+ * Failover config loader — v0.6.x rate-limit fail-over wedge (Slice C).
+ *
+ * Reads `failoverChain` from `~/.codehere/config.json` and validates it
+ * against the known agent ids. Returns the validated chain or undefined
+ * if the user has not configured one (caller falls back to the default).
+ *
+ * Config shape (~/.codehere/config.json):
+ *   {
+ *     "version": "0.6.0",
+ *     "failover": {
+ *       "chain": ["codex", "claude-code", "aider"]
+ *     }
+ *   }
+ *
+ * If `failover.chain` is missing, empty, or invalid, returns undefined
+ * so the caller uses DEFAULT_FAILOVER_CHAIN from failover-policy.ts.
+ *
+ * Slice C scope: config read + validation. Slice D wires it into
+ * SessionManager so the resolved chain flows into the resolver.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { validateFailoverChain } from './failover-policy.js';
+const GLOBAL_CONFIG_PATH = join(homedir(), '.codehere', 'config.json');
+/**
+ * Load failover configuration from ~/.codehere/config.json.
+ * Returns undefined if the config file does not exist or has no failover section.
+ *
+ * Safe to call at any time — no side effects, no caching, no I/O errors
+ * propagated (returns undefined on any read failure).
+ */
+export function loadFailoverConfig() {
+    if (!existsSync(GLOBAL_CONFIG_PATH))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(GLOBAL_CONFIG_PATH, 'utf-8'));
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const failover = raw.failover;
+        if (!failover || typeof failover !== 'object')
+            return undefined;
+        const config = {};
+        // Validate chain if present
+        if (Array.isArray(failover.chain)) {
+            try {
+                config.chain = validateFailoverChain(failover.chain);
+            }
+            catch {
+                // Invalid chain — skip it, caller uses default
+                config.chain = undefined;
+            }
+        }
+        // autoFailover — boolean, defaults to false
+        if (typeof failover.autoFailover === 'boolean') {
+            config.autoFailover = failover.autoFailover;
+        }
+        return config;
+    }
+    catch {
+        // Config file exists but is malformed — return undefined so caller
+        // falls back to defaults without crashing.
+        return undefined;
+    }
+}
+/**
+ * Get the resolved failover chain: user-configured if present, else default.
+ * Pure function — no I/O. Caller loads config and passes it in.
+ */
+export function resolveChain(userChain) {
+    if (userChain && userChain.length > 0)
+        return userChain;
+    // Re-export the default from failover-policy
+    return ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+}
+//# sourceMappingURL=failover-config.js.map

package/dist/infrastructure/orchestration/failover-policy.js

@@ -0,0 +1,106 @@
+/**
+ * Failover policy — v0.6.x rate-limit fail-over wedge (Slice B).
+ *
+ * Given: an adapter that hit a fail-over-eligible error (per Slice A's
+ * `classifyFailoverEligibility`), a user-configured preference chain, and
+ * the set of currently-available adapters on this machine.
+ * Returns: the next adapter to try, or null if no fail-over target is
+ * available.
+ *
+ * Pure function — no I/O, no spawning. Caller (session-manager, Slice D)
+ * uses the resolver output to drive the user-consent flow (Slice C) and
+ * the mid-task hand-off.
+ *
+ * Default chain rationale:
+ *   claude-code → codex → aider → opencode → gemini
+ *
+ * The default is ordered by capability+reliability for general coding work
+ * as of May 2026:
+ *   - claude-code: strongest at multi-file reasoning + tool use
+ *   - codex: strongest at independent review + adversarial mode
+ *   - aider: most reliable for surgical single-file edits
+ *   - opencode: cross-vendor flexibility within itself
+ *   - gemini: longest context window, but free-tier rate limits hit fast
+ *
+ * Users can override via `~/.codehere/config.json` `failoverChain` array.
+ * Per-task override also supported via SpawnOptions.failoverChain (Slice D
+ * wires this).
+ *
+ * Slice B scope (this commit): pure resolver + config schema + tests.
+ * Slices C-F wire user consent, mid-task hand-off, UI surfacing, e2e.
+ */
+/** Adapter ids in the order codehere supports. Keep in sync with adapter
+ *  registry. Used as the strict ordering for chain validation. */
+export const KNOWN_AGENT_IDS = ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+/** Default fail-over chain. See module docblock for ordering rationale.
+ *  Each entry is the agent codehere will TRY in order when the previous
+ *  one is unavailable or has already been tried this hand-off. */
+export const DEFAULT_FAILOVER_CHAIN = ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+/**
+ * Resolve the next fail-over target. Returns the adapter id to try, or
+ * null if no eligible target exists.
+ *
+ * Selection rules (in order):
+ *   1. Use preferredChain if provided, else DEFAULT_FAILOVER_CHAIN
+ *   2. Skip the failed agent itself
+ *   3. Skip any adapter in alreadyTried
+ *   4. Skip adapters not present in available[] OR with ready=false
+ *   5. Return the FIRST remaining adapter in chain order
+ *   6. If nothing remains, return null
+ *
+ * Pure — no spawn, no config read. Caller assembles the inputs.
+ */
+export function resolveFailoverTarget(opts) {
+    const chain = opts.preferredChain && opts.preferredChain.length > 0 ? opts.preferredChain : DEFAULT_FAILOVER_CHAIN;
+    const tried = new Set([opts.failedAgent, ...(opts.alreadyTried ?? [])]);
+    const readyById = new Map();
+    for (const a of opts.available)
+        readyById.set(a.id, a.ready);
+    for (const candidate of chain) {
+        if (tried.has(candidate))
+            continue;
+        if (readyById.get(candidate) !== true)
+            continue;
+        return candidate;
+    }
+    return null;
+}
+/**
+ * Validate a user-supplied chain (e.g. read from config.json). Returns the
+ * chain if every entry is a known agent id; throws otherwise. Caller
+ * (config-loader, Slice C) uses this to give a helpful error if the user
+ * mistypes an adapter name.
+ */
+export function validateFailoverChain(chain) {
+    if (!Array.isArray(chain)) {
+        throw new Error('failoverChain must be an array of agent ids');
+    }
+    const validated = [];
+    for (const item of chain) {
+        if (typeof item !== 'string') {
+            throw new Error(`failoverChain entries must be strings, got ${typeof item}`);
+        }
+        if (!isKnownAgentId(item)) {
+            throw new Error(`Unknown agent id in failoverChain: "${item}". Valid ids: ${KNOWN_AGENT_IDS.join(', ')}`);
+        }
+        if (validated.includes(item)) {
+            throw new Error(`Duplicate agent id in failoverChain: "${item}"`);
+        }
+        validated.push(item);
+    }
+    return validated;
+}
+function isKnownAgentId(id) {
+    return KNOWN_AGENT_IDS.includes(id);
+}
+/**
+ * Helper: convert an array of AgentAdapter (typically from an adapter
+ * registry) to the AdapterAvailability shape this module expects, given
+ * a readiness probe function. Used by callers who already have the
+ * adapter instances handy. Caller passes a probe like
+ * `adapter.checkReadiness().state === 'ready'`.
+ */
+export function toAvailability(adapters, isReady) {
+    return adapters.map((a) => ({ id: a.id, ready: isReady(a) }));
+}
+//# sourceMappingURL=failover-policy.js.map

package/dist/infrastructure/orchestration/gemini-adapter.js

@@ -28,7 +28,9 @@
  * fingerprints. Finalizes on `close` (not `exit`) so trailing stdout flushes.
  * Kills the process group (negative pid) so subagents under gemini exit too.
  */
-import { spawn, execFileSync } from 'child_process';
+import { spawn, execFile, execFileSync } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
 import { existsSync } from 'fs';
@@ -36,6 +38,7 @@ import { homedir } from 'os';
 import { join } from 'path';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { applyMemoryPrefix } from './memory-injector.js';
+import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 // `--approval-mode=yolo` auto-accepts every tool action without prompting (the
 // older `--yolo` flag is deprecated). codehere's safety hook is the external
@@ -87,6 +90,41 @@ function scanForKnownError(text) {
     }
     return null;
 }
+/**
+ * Parse the plain-text output of `gemini --list-sessions` and return the
+ * 1-based index for a given session UUID, or null if not found.
+ *
+ * Format (verified against gemini-cli source — packages/cli/src/utils/sessions.ts):
+ *   Available sessions for this project (3):
+ *
+ *     1. Some Title (5 minutes ago) [a1b2c3d4-...]
+ *     2. Other Title (1 hour ago, current) [e5f6g7h8-...]
+ *     3. Third One (yesterday) [9i0j1k2l-...]
+ *
+ * Indices are 1-based and stable within one run (sort-by-startTime); the UUID
+ * is the durable handle. We exported as a pure function so tests don't need
+ * the real gemini binary or a real session store.
+ */
+export function parseGeminiSessionIndexForUuid(listOutput, uuid) {
+    if (!uuid)
+        return null;
+    // Match `  N. <title> ... [<uuid>]` — UUID is always the last bracketed
+    // segment on the line. Title can contain anything (including bracketed
+    // text), so we match `[uuid]` at end-of-line, not the first `[...]`.
+    const lineRegex = /^\s*(\d+)\.\s.*\[([0-9a-fA-F-]{8,})\]\s*$/;
+    for (const raw of listOutput.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        const m = line.match(lineRegex);
+        if (!m)
+            continue;
+        const idx = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(idx) || idx <= 0)
+            continue;
+        if (m[2] === uuid)
+            return idx;
+    }
+    return null;
+}
 export function spawnGemini(prompt, options = {}) {
     const sessionId = randomUUID();
     const startedAt = Date.now();
@@ -137,6 +175,27 @@ export function spawnGemini(prompt, options = {}) {
             if (typeof t === 'string')
                 textAccum += t + '\n';
         }
+        // #110 slice 4 — mirror gemini tool calls to the audit log. Same
+        // shape Codex uses (post-hoc, no block). gemini emits tool_use
+        // BEFORE the call lands; mirror at that point so the audit row
+        // appears around when the action happens.
+        if (event.type === 'tool_use') {
+            const data = event.data;
+            const toolName = String(data?.tool_name ?? 'tool');
+            const params = data?.parameters ?? {};
+            const input = (typeof params.command === 'string' && params.command) ||
+                (typeof params.file_path === 'string' && params.file_path) ||
+                (typeof params.path === 'string' && params.path) ||
+                (typeof params.query === 'string' && params.query) ||
+                JSON.stringify(params).slice(0, 500);
+            mirrorToolCallToAudit({
+                sessionId,
+                agent: 'gemini',
+                toolName,
+                toolInput: String(input),
+                cwd,
+            });
+        }
         // Token usage comes ONLY in the final `result` event with status:'success',
         // shape { stats: { input_tokens, output_tokens, total_tokens, cached } }.
         if (event.type === 'result') {
@@ -234,6 +293,11 @@ export function spawnGemini(prompt, options = {}) {
         };
     }
     let stdoutBuf = '';
+    // Captured from the gemini-cli `init` event so appendMessage can resolve
+    // it to a session-list index (gemini's --resume only takes index or
+    // 'latest', NOT the UUID itself). See parseGeminiSessionIndexForUuid +
+    // the appendMessage block below.
+    let geminiSessionUuid = null;
     child.stdout?.on('data', (chunk) => {
         stdoutBuf += chunk.toString('utf-8');
         let idx;
@@ -244,6 +308,9 @@ export function spawnGemini(prompt, options = {}) {
                 continue;
             try {
                 const data = JSON.parse(line);
+                if (data.type === 'init' && typeof data.session_id === 'string') {
+                    geminiSessionUuid = data.session_id;
+                }
                 emit({ type: data.type ?? 'gemini_event', timestamp: Date.now(), data });
             }
             catch {
@@ -356,24 +423,58 @@ export function spawnGemini(prompt, options = {}) {
         },
         canAppendMessage: true,
         /**
-         * v0.6.0 — Slice 2b of REPL persistence. Gemini's --resume flag accepts
-         * either a numeric INDEX (per-cwd ordinal of past sessions) or the literal
-         * string "latest" — NOT the session_id UUID that the init JSONL event
-         * emits. UUID→index mapping requires --list-sessions which has its own
-         * race condition (indices shift as sessions are added/deleted).
+         * v0.6.x — UUID→index resolution (replaces the prior --resume latest
+         * shortcut). Gemini's --resume flag accepts a numeric INDEX (per-cwd
+         * ordinal of past sessions) or the literal 'latest' — NOT the session_id
+         * UUID that the init JSONL event emits.
          *
-         * For the v0.6 cut we use --resume latest. Limitation: if the user spawns
-         * another gemini session in this cwd between the original spawn and this
-         * follow-up, the follow-up routes to the wrong session. Same caveat as
-         * opencode's --continue. Acceptable for the typical reply-within-minutes
-         * flow; the rigorous UUID→index helper is queued for v0.6.x.
+         * Strategy: capture session_id on spawn (see geminiSessionUuid above) →
+         * here, run `gemini --list-sessions` (plain text, no --json flag), parse
+         * each line for `[uuid]` at end of line, find the index that matches our
+         * captured UUID, and use it in --resume <N>. If anything fails (binary
+         * missing, list times out, UUID not found), fall back to --resume latest
+         * — same posture as before for safety, but with a chance to nail the
+         * exact session in the common case.
+         *
+         * Concurrency win: if a sibling session is spawned in the same cwd between
+         * spawn and reply, we no longer route the reply to the wrong one.
          */
-        appendMessage(text) {
+        async appendMessage(text) {
             const startedAt = Date.now();
+            // Resolve UUID→index ASYNCHRONOUSLY before spawning the followup. Must
+            // be async (not execFileSync) because this runs in the daemon's HTTP
+            // request path; a sync call would block the event loop and freeze every
+            // other in-flight session for up to the timeout.
+            let resumeArg = 'latest';
+            if (geminiSessionUuid) {
+                try {
+                    // gemini-cli's --list-sessions runs an internal generateSummary()
+                    // first, which itself has a 5000ms LLM-call abort timeout (see
+                    // sessionSummaryService.ts DEFAULT_TIMEOUT_MS in upstream). Our
+                    // wrapper timeout MUST be comfortably greater than that or we kill
+                    // the child mid-summary, get empty stdout, and silently fall back
+                    // to --resume latest — which would defeat the whole UUID→index fix.
+                    // 15s = 5s upstream LLM cap + parse/flush/spawn overhead + slack.
+                    // Override via CODEHERE_GEMINI_LIST_TIMEOUT_MS for slow boxes.
+                    const timeoutMs = Number(process.env.CODEHERE_GEMINI_LIST_TIMEOUT_MS) || 15000;
+                    const { stdout: listOut } = await execFileAsync('gemini', ['--list-sessions'], {
+                        cwd,
+                        env: spawnEnv,
+                        encoding: 'utf-8',
+                        timeout: timeoutMs,
+                    });
+                    const idx = parseGeminiSessionIndexForUuid(listOut, geminiSessionUuid);
+                    if (idx !== null)
+                        resumeArg = String(idx);
+                }
+                catch {
+                    // Binary missing, slow auth, no sessions yet — fall through to latest.
+                }
+            }
             return new Promise((resolve, reject) => {
                 let stdout = '';
                 let stderr = '';
-                const followup = spawn('gemini', ['-p', text, '--resume', 'latest', ...HEADLESS_FLAGS], {
+                const followup = spawn('gemini', ['-p', text, '--resume', resumeArg, ...HEADLESS_FLAGS], {
                     cwd,
                     env: spawnEnv,
                     stdio: ['ignore', 'pipe', 'pipe'],
@@ -387,7 +488,7 @@ export function spawnGemini(prompt, options = {}) {
                 });
                 followup.on('exit', (code) => {
                     if (code !== 0) {
-                        reject(new Error(`gemini --resume latest exited ${code}: ${stderr.slice(0, 300)}`));
+                        reject(new Error(`gemini --resume ${resumeArg} exited ${code}: ${stderr.slice(0, 300)}`));
                         return;
                     }
                     // Parse stream-json — extract assistant message text from 'message'
@@ -417,6 +518,7 @@ export function spawnGemini(prompt, options = {}) {
 export const GeminiAdapter = {
     id: 'gemini',
     label: 'Gemini',
+    description: 'Google\'s coding agent. Has a free tier and can read very large amounts of code or docs at once. Useful when the paid agents are out of credits.',
     // Match `gemini`, `node /path/.../gemini`, and `./gemini` invocations.
     processPattern: /(?:^|\/)gemini(?:\s|$)|node\s+\S*gemini/,
     isInstalled() {