llm-cli-gateway 1.0.1 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## Unreleased
+
+## [1.4.0] - 2026-05-16
+
+### Added
+
+- **Codex `exec resume` wired through the gateway** — `codex_request` and `codex_request_async` now accept `sessionId` (real Codex session UUID from `~/.codex/sessions/` or the `codex resume` picker) and `resumeLatest:true`, emitting `codex exec resume <UUID>` and `codex exec resume --last` respectively. Codex sessions are no longer bookkeeping-only at the gateway layer; multi-turn workflows carry real CLI continuity, matching Claude/Gemini/Grok. Gateway-generated `gw-*` IDs are rejected for Codex (as for Gemini/Grok). `--full-auto` is silently dropped on resume because `codex exec resume` does not accept it — the original session's approval policy is inherited.
+- **Durable job results + automatic dedup** — Async jobs are now persisted to a `jobs` table in `~/.llm-cli-gateway/logs.db` on every state transition (start, output flush, completion). `llm_job_status` and `llm_job_result` fall back to the database when the job is no longer in memory, so callers can collect a result regardless of how long ago the work completed (default retention: **30 days**, configurable via `LLM_GATEWAY_JOB_RETENTION_DAYS`). Identical `*_request` / `*_request_async` calls within a dedup window (default **1 hour**, configurable via `LLM_GATEWAY_DEDUP_WINDOW_MS`) short-circuit onto the existing running or completed job instead of spawning a duplicate run — directly fixing the "agent re-issues and the whole job starts over" loop. Each tool now accepts `forceRefresh: true` to bypass dedup. Jobs that were running when the gateway last stopped are flipped to `orphaned` on startup so callers can still read their partial output.
+- **Grok CLI provider (xAI Grok Build TUI)** — New `grok_request` and `grok_request_async` MCP tools mirror the existing Claude/Codex/Gemini surface (sync + async, session management via `--resume`/`--continue`, idle-timeout, approval policy, review-integrity, flight recorder, metrics). Auth assumes a prior `grok login` (OAuth) or `GROK_CODE_XAI_API_KEY`. Default model: `grok-build`. `GROK_DEFAULT_MODEL`, `GROK_MODELS`, and `GROK_MODEL_ALIASES` env vars are honored by the model registry. `cli_upgrade` treats Grok as self-updating (`grok update` / `grok update --version <target>`).
+- **Source-aware model registry** — `list_models` now reports model source/confidence metadata, aliases, default model source, and non-fatal discovery warnings
+- **Deterministic model configuration overrides** — Added `*_SETTINGS_PATH`, `GEMINI_HISTORY_ROOT`, `*_MODEL_ALIASES`, and `LLM_GATEWAY_MODEL_ALIASES` support for stable deployments and tests
+- **CLI lifecycle tools** — Added `cli_versions` and `cli_upgrade` tools for inspecting and upgrading individual Claude, Codex, Gemini, and Grok CLI installations
+- **`resolveCodexSessionArgs` helper** in `src/request-helpers.ts` with 7 new tests covering mode resolution and `gw-*` rejection (Codex uses an `exec resume` subcommand rather than a flag pair, so the helper returns a `mode` discriminant: `new` | `resume-by-id` | `resume-latest`)
+
+### Changed
+
+- **`better-sqlite3` bumped to `^12.9.0`** (from `^11.0.0`) — required engines now `node 20.x || 22.x || 23.x || 24.x || 25.x`
+- **Gemini history discovery is no longer authoritative** — Models observed in local Gemini session files are merged as low-confidence entries and no longer replace the registry or set the default model
+- **Codex default handling remains explicit** — If Codex has no configured default, `default`/`latest` resolve to no model flag so the Codex CLI can use its own built-in default
+- **Gateway skills refreshed** — The `.agents/skills/` (async-job-orchestration, implement-review-fix, multi-llm-review, secure-orchestration, session-workflow) and `skills/` (multi-llm-orchestration, multi-llm-consensus, model-routing, design-review-cycle, agent-codex-gate, codex-review-gate, red-team-assessment) skill docs now cover Grok, durable job results, auto-dedup, and the new Codex resume capability. `.agents/skills/` entries bumped to metadata version 1.5.
+
+## [1.1.0] - 2026-04-04
+
+### Added
+
+- **SQLite flight recorder** — New `src/flight-recorder.ts` module logs all LLM requests/responses to `~/.llm-cli-gateway/logs.db` with two-phase logging (logStart/logComplete), WAL mode for concurrent Datasette reads, and graceful degradation when better-sqlite3 is unavailable
+- **`LLM_GATEWAY_LOGS_DB` env var** — Configure flight recorder database path; set to empty string or `"none"` to disable logging entirely
+- **`structuredContent` in MCP tool responses** — All tool handlers now return machine-readable metadata (model, cli, correlationId, sessionId, durationMs, token usage, exitCode) alongside the text response
+- **`better-sqlite3` dependency** — Native SQLite addon for flight recorder (synchronous writes, WAL support)
+
+### Changed
+
+- **review-integrity.ts simplified** — Reduced from 323 lines to 83 lines. Retains 3 violation types: empty_allowed_tools, critical_tools_disallowed, tool_suppression. Removed inlined_code detection and multi-pattern matching
+- **`buildCliResponse` signature** — Now requires `cli` and `durationMs` parameters for structuredContent population
+- **`createErrorResponse`** — Returns sanitized `errorCategory` enum in structuredContent instead of raw error messages (prevents path/secret leakage)
+- **Flight recorder writes are idempotent** — logComplete only updates rows with status='started', preventing double-completion
+
+### Tests
+
+- 284 tests passing (15 test files)
+- Rewritten review-integrity tests to match simplified API
+
 ## [1.3.0] - 2026-02-15
 
 ### Fixed

package/README.md

@@ -3,17 +3,21 @@
 > *"Without consultation, plans are frustrated, but with many counselors they succeed."*
 > — Proverbs 15:22 (LSB)
 
-A Model Context Protocol (MCP) server providing unified access to Claude Code, Codex, and Gemini CLIs with session management, retry logic, and async job orchestration.
+A Model Context Protocol (MCP) server providing unified access to Claude Code, Codex, Gemini, and Grok CLIs with session management, retry logic, and async job orchestration.
 
 ## Features
 
 ### Core Capabilities
-- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, and Gemini CLIs
+- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, Gemini, and Grok CLIs
 - **Session Management**: Track and resume conversations across all CLIs with persistent storage
 - **Token Optimization**: Automatic 44% reduction on prompts, 37% on responses (opt-in)
 - **Correlation ID Tracking**: Full request tracing across all LLM interactions
 - **Cross-Tool Collaboration**: LLMs can use each other via MCP (validated through dogfooding)
 
+### Observability
+- **SQLite Flight Recorder**: Every request/response logged to `~/.llm-cli-gateway/logs.db` with correlation IDs, token usage, duration, retry counts, and circuit breaker state. Browse with [Datasette](https://datasette.io/): `datasette ~/.llm-cli-gateway/logs.db`
+- **Structured Metadata**: Tool responses include machine-readable `structuredContent` (model, cli, correlationId, sessionId, durationMs, token counts)
+
 ### Reliability & Performance
 - **Retry Logic**: Exponential backoff with circuit breaker for transient failures
 - **Atomic File Writes**: Process-specific temp files with fsync for data integrity
@@ -22,7 +26,7 @@ A Model Context Protocol (MCP) server providing unified access to Claude Code, C
 - **Long-Running Jobs**: Non-time-bound async execution via `*_request_async` + polling tools
 
 ### Security & Quality
-- **Comprehensive Testing**: 221 tests covering unit, integration, and regression scenarios
+- **Comprehensive Testing**: 284 tests covering unit, integration, and regression scenarios
 - **Input Validation**: Zod schemas prevent injection attacks
 - **No Secret Leakage**: Generic session descriptions only (file permissions 0o600)
 - **No ReDoS**: Bounded regex patterns prevent catastrophic backtracking
@@ -52,6 +56,13 @@ npm install -g @google/gemini-cli
 # Or: https://github.com/google-gemini/gemini-cli
 ```
 
+### Grok CLI (xAI)
+```bash
+npm install -g grok-build
+grok login   # OAuth flow, or set GROK_CODE_XAI_API_KEY
+# Docs: https://docs.x.ai/build/cli
+```
+
 ## Installation
 
 ### As an MCP server (npm)
@@ -201,8 +212,54 @@ Execute a Gemini CLI request with session support.
 }
 ```
 
-##### `claude_request_async` / `codex_request_async`
-Start a long-running Claude or Codex request without waiting for completion in the same MCP call.
+##### `grok_request`
+Execute a Grok CLI (xAI) request with session support.
+
+**Parameters:**
+- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `model` (string, optional): Model name or alias (e.g. `grok-build`, `latest`)
+- `outputFormat` (string, optional): `"plain"` (default), `"json"`, or `"streaming-json"`
+- `sessionId` (string, optional): Session ID to resume (`--resume <id>`)
+- `resumeLatest` (boolean, optional): Resume the most recent session in the current cwd (`--continue`)
+- `createNewSession` (boolean, optional): Always create a new session
+- `alwaysApprove` (boolean, optional): Auto-approve all tool executions (`--always-approve`) in legacy mode
+- `permissionMode` (string, optional): `default|acceptEdits|auto|dontAsk|bypassPermissions|plan`
+- `effort` (string, optional): `low|medium|high|xhigh|max`
+- `reasoningEffort` (string, optional): Reasoning effort for reasoning models
+- `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
+- `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
+- `mcpServers` (string[], optional): MCP server names tracked for approvals (Grok manages its own MCP config via `grok mcp`)
+- `allowedTools` (string[], optional): Allowed built-in tools (passed as `--tools` comma list)
+- `disallowedTools` (string[], optional): Disallowed built-in tools (passed as `--disallowed-tools` comma list)
+- `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
+- `optimizeResponse` (boolean, optional): Optimize response for token efficiency, default: false
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+
+**Example:**
+```json
+{
+  "prompt": "Summarize the latest commit message in 1 sentence",
+  "model": "grok-build",
+  "effort": "low"
+}
+```
+
+#### Durable job results & automatic dedup
+
+Every async job is persisted to a `jobs` table in `~/.llm-cli-gateway/logs.db` as it transitions through running → completed/failed/canceled. This makes the gateway a durable collection layer:
+
+- **Re-issuing a request is safe.** Identical `*_request` / `*_request_async` calls within the dedup window (default 1 hour) short-circuit onto the existing running or completed job — the caller gets back the same job ID instead of starting a duplicate run. This directly fixes the "agent times out polling, re-issues, and the whole job starts over" failure mode.
+- **`llm_job_status` and `llm_job_result` work across gateway restarts.** Job rows live for 30 days by default; callers can fetch results long after the in-memory cache has evicted them.
+- **Jobs running at shutdown are marked `orphaned`** on the next gateway boot (the detached child can't be reattached to). Their captured partial output remains readable.
+- **Pass `forceRefresh: true`** on any request tool to bypass dedup and force a fresh CLI run.
+
+Environment variables:
+- `LLM_GATEWAY_JOB_RETENTION_DAYS` — how long completed jobs stay queryable. Default `30`.
+- `LLM_GATEWAY_DEDUP_WINDOW_MS` — how recent an existing job must be to dedup against. Default `3600000` (1 hour). Set `0` to disable dedup.
+- `LLM_GATEWAY_JOBS_DB` — override the sqlite path. Defaults to the value of `LLM_GATEWAY_LOGS_DB`, then `~/.llm-cli-gateway/logs.db`. Set to `none` to disable durability entirely (in-memory only).
+
+##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async`
+Start a long-running Claude, Codex, Gemini, or Grok request without waiting for completion in the same MCP call.
 
 Use this flow when analysis/runtime can exceed client tool-call limits:
 1. Start job with `*_request_async`
@@ -240,7 +297,7 @@ Approval records are persisted to `~/.llm-cli-gateway/approvals.jsonl`.
 Create a new session for a specific CLI.
 
 **Parameters:**
-- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini")
+- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok")
 - `description` (string, optional): Description for the session
 - `setAsActive` (boolean, optional): Set as active session, default: true
 
@@ -257,7 +314,7 @@ Create a new session for a specific CLI.
 List all sessions, optionally filtered by CLI.
 
 **Parameters:**
-- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini")
+- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok")
 
 **Response includes:**
 - Total session count
@@ -295,12 +352,74 @@ Clear all sessions, optionally for a specific CLI.
 List available models for each CLI.
 
 **Parameters:**
-- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini")
+- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok")
 
 **Response includes:**
 - Model names and descriptions
 - Best use cases for each model
 - CLI-specific information
+- `defaultModel` and `defaultModelSource` when a default is explicitly configured
+- `modelMetadata` with source/confidence (`fallback`, `config`, `env`, `observed`)
+- `aliases` and `warnings` when configured or when discovery degrades gracefully
+
+The registry treats explicit configuration as authoritative. Bundled fallback models are low-confidence hints, and Gemini models observed in local session history are merged as low-confidence entries only; they do not become the default model.
+
+Model registry environment overrides:
+
+```bash
+# Explicit defaults
+CLAUDE_DEFAULT_MODEL=haiku
+CODEX_DEFAULT_MODEL=<codex-model-id>
+GEMINI_DEFAULT_MODEL=gemini-2.5-flash
+
+# Additional models: comma/newline list, JSON array, or JSON object of model->description
+GEMINI_MODELS='{"gemini-team-default":"Team-approved Gemini model"}'
+
+# Aliases
+GEMINI_MODEL_ALIASES='team=gemini-team-default'
+LLM_GATEWAY_MODEL_ALIASES='codex.fast=gpt-5.3-codex-spark,gemini.fast=gemini-team-default'
+
+# Deterministic config/discovery paths
+CODEX_CONFIG_PATH=/path/to/config.toml
+CLAUDE_SETTINGS_PATH=/path/to/settings.json
+CLAUDE_SETTINGS_LOCAL_PATH=/path/to/settings.local.json
+GEMINI_SETTINGS_PATH=/path/to/settings.json
+GEMINI_HISTORY_ROOT=/path/to/.gemini/tmp
+
+# Disable local model-history discovery
+LLM_GATEWAY_DISABLE_MODEL_DISCOVERY=1
+```
+
+##### `cli_versions`
+Report installed CLI versions.
+
+**Parameters:**
+- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok")
+
+##### `cli_upgrade`
+Plan or run an upgrade for one CLI.
+
+**Parameters:**
+- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok")
+- `target` (string, optional): Package tag/version/target, default: `latest`
+- `dryRun` (boolean, optional): Return the upgrade plan without running it, default: `true`
+- `timeoutMs` (number, optional): Upgrade timeout when `dryRun=false`
+
+**Upgrade strategies:**
+- Claude latest: `claude update`
+- Claude explicit target: `claude install <target>`
+- Codex latest: `codex update`
+- Codex explicit target: `npm install -g @openai/codex@<target>`
+- Gemini: `npm install -g @google/gemini-cli@<target>`
+
+**Example dry run:**
+```json
+{
+  "cli": "gemini",
+  "target": "latest",
+  "dryRun": true
+}
+```
 
 ## Session Management
 
@@ -360,6 +479,13 @@ await callTool("session_delete", {
   ```bash
   LLM_GATEWAY_APPROVAL_POLICY=strict node dist/index.js
   ```
+- `LLM_GATEWAY_LOGS_DB`: Path to SQLite flight recorder database. Default: `~/.llm-cli-gateway/logs.db`. Set to empty string or `none` to disable logging.
+  ```bash
+  # Custom path
+  LLM_GATEWAY_LOGS_DB=/var/log/gateway/logs.db node dist/index.js
+  # Disable flight recorder
+  LLM_GATEWAY_LOGS_DB=none node dist/index.js
+  ```
 
 ### CLI-Specific Settings
 
@@ -368,6 +494,25 @@ Each CLI can be configured through its own configuration files:
 - Codex: `~/.codex/config.toml`
 - Gemini: `~/.gemini/config.json`
 
+## For Fans of Simon Willison
+
+Simon's `llm` tool made it trivially easy to talk to any LLM from the command line. But as AI-assisted development matures, the challenge shifts from "how do I call a model" to "how do I orchestrate multiple models reliably, and what did they actually do?"
+
+**Multiple models increase the confidence factor.** When Claude writes code, Codex reviews it, and Gemini checks for bugs -- each bringing different training data and reasoning patterns -- the result is more robust than any single model alone. And often this isn't even enough. Having the models do iterative reviews is where you start getting real confidence.
+
+**Every interaction should be queryable data.** Inspired by `llm`'s SQLite logging philosophy, the gateway records every request and response to a local SQLite database. Not just prompts and responses -- retry counts, circuit breaker states, approval decisions, thinking blocks, cost estimates. Open it with Datasette and you have a complete operational picture of your AI usage:
+
+    datasette ~/.llm-cli-gateway/logs.db
+
+**The `llm-gateway` plugin bridges both worlds.** Install it, and your existing `llm` workflows gain orchestration features without changing how you work:
+
+    llm install llm-gateway
+    llm -m gateway-claude "explain this function"
+
+Your gateway interactions appear in both `llm logs` (for your personal history) and the gateway's flight recorder (for operational observability). Two audiences, one workflow.
+
+**Composability over monoliths.** The gateway doesn't replace `llm` -- it complements it. Use `llm` directly when you want simplicity. Route through the gateway when you want resilience, multi-model coordination, or detailed operational telemetry. The plugin is the bridge, not the destination.
+
 ## Development
 
 ### Project Structure
@@ -542,4 +687,3 @@ For issues and questions:
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for detailed release history.
-

package/dist/approval-manager.d.ts

@@ -2,7 +2,7 @@ import type { Logger } from "./logger.js";
 import type { ReviewIntegrityResult } from "./review-integrity.js";
 export type ApprovalPolicy = "strict" | "balanced" | "permissive";
 export type ApprovalStrategy = "legacy" | "mcp_managed";
-export type ApprovalCli = "claude" | "codex" | "gemini";
+export type ApprovalCli = "claude" | "codex" | "gemini" | "grok";
 export type ApprovalStatus = "approved" | "denied";
 export interface ApprovalRequest {
     cli: ApprovalCli;

package/dist/approval-manager.js

@@ -83,7 +83,9 @@ export class ApprovalManager {
             // Canonicalize to handle scoped forms like "Read(*)", "Bash(git:*)"
             const canonicalized = request.disallowedTools.map(s => {
                 const trimmed = s.trim();
-                const cut = Math.min(...[trimmed.indexOf("("), trimmed.indexOf(":")].filter(i => i >= 0).concat([trimmed.length]));
+                const cut = Math.min(...[trimmed.indexOf("("), trimmed.indexOf(":")]
+                    .filter(i => i >= 0)
+                    .concat([trimmed.length]));
                 return trimmed.slice(0, cut).trim();
             });
             const blockedCritical = criticalTools.filter(t => canonicalized.includes(t));
@@ -103,7 +105,8 @@ export class ApprovalManager {
         if (request.reviewIntegrity && request.reviewIntegrity.violations.length > 0) {
             for (const violation of request.reviewIntegrity.violations) {
                 // Skip empty_allowed_tools and critical_tools_disallowed — already handled in context-dependent scoring above
-                if (violation.type === "empty_allowed_tools" || violation.type === "critical_tools_disallowed")
+                if (violation.type === "empty_allowed_tools" ||
+                    violation.type === "critical_tools_disallowed")
                     continue;
                 score += violation.score;
                 reasons.push(`Review integrity: ${violation.detail}`);
@@ -128,12 +131,12 @@ export class ApprovalManager {
             bypassRequested: request.bypassRequested,
             fullAuto: request.fullAuto,
             metadata: request.metadata,
-            reviewIntegrity: request.reviewIntegrity
+            reviewIntegrity: request.reviewIntegrity,
         };
         appendFileSync(this.logPath, `${JSON.stringify(record)}\n`, { encoding: "utf-8", mode: 0o600 });
         this.logger.info(`Approval decision: ${status} (score=${score}, policy=${policy})`, {
             cli: request.cli,
-            operation: request.operation
+            operation: request.operation,
         });
         return record;
     }

package/dist/async-job-manager.d.ts

@@ -1,7 +1,8 @@
 import type { Logger } from "./logger.js";
 import { type JobHealth } from "./process-monitor.js";
-export type LlmCli = "claude" | "codex" | "gemini";
-export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled";
+import { JobStore } from "./job-store.js";
+export type LlmCli = "claude" | "codex" | "gemini" | "grok";
+export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
 export interface AsyncJobSnapshot {
     id: string;
     cli: LlmCli;
@@ -22,16 +23,64 @@ export interface AsyncJobResult extends AsyncJobSnapshot {
     stdoutTruncated: boolean;
     stderrTruncated: boolean;
 }
+export interface StartJobOptions {
+    cwd?: string;
+    idleTimeoutMs?: number;
+    outputFormat?: string;
+    /** Bypass dedup and force a fresh CLI run even if a recent matching job exists. */
+    forceRefresh?: boolean;
+}
+export interface StartJobOutcome {
+    snapshot: AsyncJobSnapshot;
+    /** Set to the existing job's id when the request was de-duplicated. */
+    deduped: boolean;
+    /** Set when deduped — the original job's correlation id, useful for logging. */
+    originalCorrelationId?: string;
+}
 export declare class AsyncJobManager {
     private logger;
     private onJobComplete?;
     private jobs;
     private evictionTimer;
     private processMonitor;
-    constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined);
+    private store;
+    constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null);
     private emitMetrics;
     private evictCompletedJobs;
-    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string): AsyncJobSnapshot;
+    /**
+     * Compute the dedup key for a job. Stable across re-issues of the same request,
+     * which is exactly what allows agents to safely retry without restarting the run.
+     */
+    private buildRequestKey;
+    private safeStoreCall;
+    /**
+     * Flush in-memory stdout/stderr to the durable store if anything changed
+     * since the last flush. Throttled by OUTPUT_FLUSH_INTERVAL_MS to avoid
+     * pounding sqlite on every chunk of streaming output.
+     */
+    private maybeFlushOutput;
+    private persistComplete;
+    /**
+     * Reconstitute an in-memory AsyncJobRecord from a durable row, so subsequent
+     * getJobSnapshot/getJobResult calls hit the in-memory cache.
+     * The reconstituted record has process=null — it represents historical data only.
+     */
+    private hydrateFromStore;
+    /**
+     * Backwards-compatible entry point. Equivalent to startJobWithDedup({...}).snapshot.
+     * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
+     * optional param for the dedup-aware path.
+     */
+    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean): AsyncJobSnapshot;
+    /**
+     * Start a job, with optional dedup against recent identical requests.
+     * Returns `{ snapshot, deduped }` so callers can log/report the short-circuit.
+     *
+     * Dedup is keyed on (cli, args). If a job with the same key was started within
+     * the dedup window (default 1h) and is still running or completed, its snapshot
+     * is returned without spawning a new process. forceRefresh skips dedup entirely.
+     */
+    startJobWithDedup(cli: LlmCli, args: string[], correlationId: string, opts?: StartJobOptions): StartJobOutcome;
     getJobSnapshot(jobId: string): AsyncJobSnapshot | null;
     getJobResult(jobId: string, maxChars?: number): AsyncJobResult | null;
     cancelJob(jobId: string): {