llm-cli-gateway 1.17.9 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,146 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.1.0] - 2026-06-07: Grok Build 0.2.32, probe drift acknowledgement, docs currency
+
+### Added
+
+- Grok Build 0.2.32 support: new `leaderSocket` parameter on `grok_request` /
+  `grok_request_async` maps to the new `--leader-socket <PATH>` flag (isolated
+  leader process for local/branch Grok builds; default `~/.grok/leader.sock`).
+  Contract declares the flag with arity-one validation plus conformance
+  fixtures. The release's other changes (plugin slash commands in all
+  conversations, ordered rapid prompt submissions, faster grep on large
+  repos) are CLI-internal and inherited automatically. Probe at 0.2.32:
+  missingFlags/warnings clean.
+
+### Fixed
+
+- Upstream-contract probe drift after the 2026-06 provider CLI upgrades
+  (gemini 0.45.2, grok 0.2.22, vibe 2.14.0): `CliFlagContract.hiddenFromHelp`
+  marks real flags hidden from a binary's `--help` (Claude `--max-turns`), and
+  `CliContract.acknowledgedUpstreamFlags` acknowledges upstream-only flags the
+  gateway never emits (29 Claude, 18 Gemini). Both are probe-only — the argv
+  allowlist is unchanged — with stale-marker warnings in both directions and a
+  new `acknowledgedExtraFlags` probe field. New pure `computeFlagDrift` plus
+  7 unit tests.
+- MCP server version now reports the real package version (was hardcoded
+  `1.0.0`).
+
+### Documentation
+
+- Cross-LLM documentation currency review (Codex + Gemini + Grok + Mistral):
+  README tool reference gains `codex_fork_session`, `llm_request_result`,
+  `llm_process_health`, `upstream_contracts`, and `list_available_models`;
+  `claude_request` parameter list completed (`outputFormat` default is
+  `stream-json`); Codex `fullAuto` documented as deprecated in favour of
+  `sandboxMode`; Gemini approval modes include `plan`; grok/mistral upgrade
+  strategies documented; stale test counts, provider lists, and
+  `BEST_PRACTICES.md` path pointers corrected across README, AGENTS.md,
+  .cursorrules, CLAUDE.md, docs/guides, docs/personal-mcp (Mistral/Vibe row
+  added to the provider support matrix), and docs/upstream.
+
+## [2.0.0] - 2026-06-04: node:sqlite migration — native module out of the prod graph
+
+Major release. Persistence moves from the native `better-sqlite3` binding to
+Node's built-in `node:sqlite` module behind a thin adapter. The entire
+1.17.6-1.17.8 supply-chain incident class — every one of which traced to
+`better-sqlite3`'s install path (`prebuild-install → tar-fs → tar-stream`),
+not its runtime — is now **structurally** gone: the production dependency
+graph contains zero native modules, zero install scripts, and no
+`prebuild-install`/`tar-fs`/`tar-stream` chain. Verified end to end against a
+verdaccio registry reproduction (`scripts/verify-registry-install.sh`):
+consumer tree reified at 94 packages (down from ~124 in 1.17.9), `npm ls`
+exits 0, and no `better-sqlite3`/`tar-stream`/`prebuild-install` appears
+anywhere in the consumer tree.
+
+### BREAKING
+
+- **`engines.node` is now `>=24.4.0`** (was `>=20.0.0`). Node 20 is EOL
+  (April 2026). The 24.4 floor is required because `node:sqlite`'s
+  `allowBareNamedParameters` defaults to `true` only from Node 24.4 — the
+  persistence layer binds bare `{ id: ... }` objects to `@id` placeholders
+  throughout, and on 24.0-24.3 that would need a per-statement
+  `setAllowBareNamedParameters(true)` call. The adapter unit tests assert
+  bare-name binding works, so a regression in either direction is caught.
+
+### Added
+
+- `src/sqlite-driver.ts`: thin adapter over `node:sqlite`'s `DatabaseSync`.
+  Exports `openDatabase`, `openReadOnly`, and a `GatewayDatabase` /
+  `GatewayStatement` surface (`exec`/`prepare`/`run`/`get`/`all`/
+  `withTransaction`/`close`). It is the ONLY production module that touches
+  `node:sqlite`; the release security audit hard-fails if any other
+  production module references it. Preserves the flight recorder's
+  graceful-degradation path (constructor failure → recorder disabled, gateway
+  still runs).
+- Read-only `queryRequests` connection: `openReadOnly` opens the DB with
+  `{ readOnly: true }`, so write-disguised-as-read SQL fails at the SQLite
+  engine level (`SQLITE_READONLY`). This is **stronger** than the old
+  better-sqlite3 `stmt.readonly` JS-property check it replaces — enforcement
+  is at the engine, not in JavaScript — with one belt-and-braces guard: the
+  read-only connection also rejects `VACUUM`/`VACUUM INTO`, the one statement
+  that writes a new file to disk despite `{ readOnly: true }` (and that
+  `stmt.readonly` previously blocked). ATTACH-then-write and
+  `writable_schema` schema edits are already engine-rejected.
+- Cross-engine WAL crash-recovery fixtures in both directions
+  (`src/__tests__/cross-engine-wal.test.ts`): a `better-sqlite3`-written DB
+  (SQLite 3.53.1) with live `-wal`/`-shm` from a simulated unclean stop is
+  opened and exercised under `node:sqlite` (3.51.3), and the reverse for the
+  rollback direction. These gate the "zero data migration" claim across the
+  engine-version skew.
+
+### Changed
+
+- `better-sqlite3` **moved from `dependencies` to `devDependencies`** (same
+  `^12.10.0` range; `@types/better-sqlite3` stays in devDependencies). It is
+  retained at dev time deliberately: two suites seed legacy-schema DB files
+  with it (`src/__tests__/flight-recorder.test.ts`,
+  `src/__tests__/test-veracity-regressions-slice-kappa.test.ts`) to simulate
+  databases written by pre-2.0.0 gateways — that realism is the point, and it
+  makes them standing old-engine-writer → node:sqlite-reader coverage on every
+  CI run — and the cross-engine WAL fixtures need a better-sqlite3 writer.
+  Consumers never see it: devDependencies do not install transitively, and the
+  prod-only shrinkwrap excludes the whole subtree.
+- `flight-recorder.ts` / `job-store.ts` now open SQLite through the adapter
+  (`openDatabase`/`openReadOnly`/`withTransaction`) instead of
+  `require("better-sqlite3")`. SQL, schema, migrations, and pragmas are
+  unchanged.
+- `package.json#overrides`: the `tar-stream` pin is **removed** (the chain
+  that needed it is gone from the prod graph). The `type-is` and `content-type`
+  pins stay — unrelated to this chain.
+- `scripts/release-security-audit.sh`: the `consumerAdvisory` carve-out is
+  **deleted** — blocked `tar-stream` versions are now hard-fail tripwires
+  everywhere (the chain no longer exists in any prod tree). The packed-consumer
+  policy now hard-fails on ANY `tar-stream` in the consumer tree (was an
+  advisory warning). The repo-lockfile tripwire skips dev-only entries so the
+  deliberate devDependency `tar-stream@2.2.0` does not false-fail, while still
+  hard-failing any blocked version that re-enters the prod graph. The
+  better-sqlite3 PRAGMA scan is repointed at the adapter: it now also asserts
+  `node:sqlite` is referenced only by `src/sqlite-driver.ts`.
+- `scripts/pre-release.sh`: the better-sqlite3 native-binding sanity guard is
+  removed (the test suite exercises the binding as a devDep and fails loudly if
+  broken); the `npm ls tar-stream` step is replaced by an absence assertion
+  against the generated prod-only shrinkwrap
+  (`better-sqlite3`/`prebuild-install`/`tar-fs`/`tar-stream` must be absent).
+- `scripts/verify-registry-install.sh`: assertions updated for 2.0.0 —
+  `tar-stream`/`better-sqlite3`/`prebuild-install` must be ABSENT from the
+  consumer tree; consumer `npm ls` must exit 0 (the out-of-range pin that
+  caused ELSPROBLEMS is gone); a `node:sqlite` runtime smoke
+  (`new DatabaseSync(':memory:')`) confirms the engine; and the reified package
+  count is asserted at 94 ±2.
+- README, `socket.yml`, and `docs/personal-mcp/RELEASE_READINESS.md` updated to
+  reflect the node:sqlite reality (no native binding, no install scripts,
+  Node >=24.4.0, adapter-isolation audit replacing the PRAGMA-helper note).
+
+### Rollback
+
+Reverting the 2.0.0 commit re-adds `better-sqlite3` to `dependencies`, the
+`tar-stream` override, and the audit advisory carve-out. DB files are
+compatible in both directions — exactly what the cross-engine WAL fixtures
+prove (the rollback claim inherits that gate; it is not asserted
+independently).
+
 ## [1.17.9] - 2026-06-04: prod-only shrinkwrap + registry-fidelity verification
 
 Patch release shipping a prod-only `npm-shrinkwrap.json` and correcting the

package/README.md

@@ -205,7 +205,7 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 ### Security & Quality
 
-- **Comprehensive Testing**: 900+ tests covering unit, integration, and regression scenarios with real CLI execution
+- **Comprehensive Testing**: 1,000+ tests covering unit, integration, and regression scenarios with real CLI execution
 - **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
@@ -214,6 +214,8 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 ## Prerequisites
 
+**Node.js >= 24.4.0** is required (`engines.node` in `package.json`). The gateway uses Node's built-in `node:sqlite` module for persistence — there is no native binding to compile and no install scripts run. The 24.4 floor is where `allowBareNamedParameters` defaults to `true`, which the persistence layer relies on.
+
 Before using this gateway, you need to install the CLI tools you want to use:
 
 ### Claude Code CLI
@@ -342,6 +344,7 @@ The personal-appliance surface exposes simplified validation tools for non-devel
 - `consensus_check`: check whether providers agree with a claim.
 - `ask_model`: ask one provider through the simplified surface.
 - `synthesize_validation`: run an explicit judge model after provider results have been collected.
+- `list_available_models`: list the models each provider CLI exposes through the simplified surface.
 - `job_status` and `job_result`: poll and collect validation job outputs.
 
 The validation report preserves per-provider disagreement. Optional judge synthesis is explicit about which provider produced the judge job.
@@ -354,15 +357,29 @@ Execute a Claude Code request with optional session management.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`)
-- `outputFormat` (string, optional): Output format ("text" or "json"), default: "text"
+- `outputFormat` (string, optional): Output format (`text|json|stream-json`), default: `stream-json` — the gateway parses NDJSON usage events for token/cost observability; override to `text` only when you want unparsed stdout
 - `sessionId` (string, optional): Specific session ID to use
 - `continueSession` (boolean, optional): Continue the active session
 - `createNewSession` (boolean, optional): Always create a new session
+- `forkSession` (boolean, optional): Fork the resumed session instead of appending to it
 - `allowedTools` (string[], optional): Restrict Claude tools to this allow-list
 - `disallowedTools` (string[], optional): Explicitly deny listed Claude tools
-- `dangerouslySkipPermissions` (boolean, optional): Request CLI-side permission bypass (legacy mode only)
+- `permissionMode` (string, optional): Claude permission mode (`default|acceptEdits|plan|auto|dontAsk|bypassPermissions`); preferred over `dangerouslySkipPermissions`
+- `dangerouslySkipPermissions` (boolean, optional): Deprecated — maps to `permissionMode: "bypassPermissions"`; `permissionMode` wins when both are set
+- `agent` (string, optional): Named sub-agent to run as
+- `agents` (string, optional): Inline agent definitions JSON
+- `systemPrompt` / `appendSystemPrompt` (string, optional): Replace or extend the system prompt
+- `maxBudgetUsd` (number, optional): Budget cap in USD for the request
+- `maxTurns` (integer, optional): Agent-loop turn cap
+- `effort` (string, optional): Reasoning effort (`low|medium|high|xhigh|max`)
+- `fallbackModel` (string, optional): Auto-fallback model when the default is overloaded
+- `jsonSchema` (string, optional): JSON Schema literal constraining structured output
+- `addDir` (string[], optional): Additional workspace directories
+- `noSessionPersistence` (boolean, optional): Ephemeral session (not persisted to disk)
+- `settingSources` / `settings` / `tools` (optional): Setting sources to load, settings JSON path/literal, built-in tool restriction
+- `excludeDynamicSystemPromptSections` (boolean, optional): Trim dynamic system prompt sections
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): Claude MCP servers to expose (default: `["sqry","exa","ref_tools"]`; `"trstr"` available as opt-in)
@@ -370,6 +387,10 @@ Execute a Claude Code request with optional session management.
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency (44% reduction), default: false
 - `optimizeResponse` (boolean, optional): Optimize response for token efficiency (37% reduction), default: false
 - `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Response extras:**
 
@@ -394,19 +415,33 @@ Execute a Codex request with optional session tracking.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
-- `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, recommended: `gpt-5.4`)
-- `fullAuto` (boolean, optional): Enable full-auto mode, default: false
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
+- `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, recommended: `gpt-5.5`)
+- `fullAuto` (boolean, optional): Deprecated — expands to `--sandbox workspace-write` only (current Codex no longer accepts approval-policy flags); prefer `sandboxMode`
+- `sandboxMode` (string, optional): Codex sandbox (`read-only|workspace-write|danger-full-access`)
 - `dangerouslyBypassApprovalsAndSandbox` (boolean, optional): Request Codex bypass flags
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): MCP servers expected for Codex execution context
 - `sessionId` (string, optional): Session identifier for tracking
+- `resumeLatest` (boolean, optional): Resume the most recent Codex session in the current cwd (`codex exec resume --last`); ignored if `sessionId` is set
 - `createNewSession` (boolean, optional): Always create a new session
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
+- `outputFormat` (string, optional): `text` (default) or `json` (`--json` JSONL events for token usage extraction)
+- `outputSchema` (string|object, optional): Codex `--output-schema` — path or inline JSON Schema
+- `workingDir` (string, optional): Working root for this session (`-C`/`--cd`; new sessions only)
+- `addDir` (string[], optional): Additional writable workspace directories (one `--add-dir` per entry; new sessions only)
+- `ephemeral` (boolean, optional): Codex `--ephemeral` (no session persistence)
+- `images` (string[], optional): Image attachments (one `-i <path>` per entry)
+- `profile` (string, optional): Codex `--profile <name>` (new sessions only; ignored with a logged warning on resume)
+- `configOverrides` (object, optional): Codex `-c key=value` overrides
+- `ignoreRules` / `ignoreUserConfig` (boolean, optional): Codex `--ignore-rules` / `--ignore-user-config`
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `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)
-- `idleTimeoutMs` (number, optional): Kill a stuck Codex process after output inactivity; 30,000 to 3,600,000 ms
+- `idleTimeoutMs` (integer, optional): Kill a stuck Codex process after output inactivity; 30,000 to 3,600,000 ms
 
 **Response extras:**
 
@@ -418,32 +453,56 @@ Execute a Codex request with optional session tracking.
 ```json
 {
   "prompt": "Create a REST API endpoint",
-  "model": "gpt-5.4",
-  "fullAuto": true,
+  "model": "gpt-5.5",
+  "sandboxMode": "workspace-write",
   "optimizePrompt": true
 }
 ```
 
+##### `codex_fork_session`
+
+Fork an existing Codex session into a new branch (`codex fork <SESSION_ID|--last> <prompt>`), preserving the original session's history while the fork diverges.
+
+**Parameters:**
+
+- `prompt` (string, required): Prompt text for the forked session (1-100,000 chars)
+- `sessionId` (string, optional): Codex session UUID to fork from (mutually exclusive with `forkLast`)
+- `forkLast` (boolean, optional): Fork the most recent Codex session instead of naming one
+- `model` (string, optional): Model name or alias (e.g. `gpt-5.5`, `latest`)
+- `sandboxMode` (string, optional): Codex sandbox (`read-only|workspace-write|danger-full-access`)
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (number, optional): Idle timeout in ms (30s-1h, omit for CLI default)
+
 ##### `gemini_request`
 
 Execute a Gemini CLI request with session support.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, `pro`, `flash`)
 - `sessionId` (string, optional): Session ID to resume
 - `resumeLatest` (boolean, optional): Resume the latest session automatically
 - `createNewSession` (boolean, optional): Always create a new session
-- `approvalMode` (string, optional): Gemini approval mode (`default|auto_edit|yolo`) in legacy mode
+- `approvalMode` (string, optional): Gemini approval mode (`default|auto_edit|yolo|plan`) in legacy mode
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): Allowed Gemini MCP server names
 - `allowedTools` (string[], optional): Restrict Gemini tools to this allow-list
 - `includeDirs` (string[], optional): Additional workspace directories for Gemini
+- `outputFormat` (string, optional): `text` (default), `json` (`-o json`), or `stream-json` (`-o stream-json`, NDJSON with usage extraction)
+- `sandbox` (boolean, optional): Run Gemini in sandbox mode (`-s`)
+- `policyFiles` / `adminPolicyFiles` (string[], optional): Policy / admin-policy file paths (one `--policy`/`--admin-policy` per file; paths must exist)
+- `attachments` (string[], optional): Absolute file paths prepended as `@<path>` tokens to the prompt
+- `skipTrust` (boolean, optional): Emit `--skip-trust` to trust the workspace for this session (required for headless runs in fresh workspaces)
+- `yolo` (boolean, optional): Auto-approve all; equivalent to `approvalMode: "yolo"`. Emits `--yolo` only when `--approval-mode yolo` is not already being emitted (never both)
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `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)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Response extras:**
 
@@ -467,7 +526,7 @@ Execute a Grok CLI (xAI) request with session support.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `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>`)
@@ -482,9 +541,35 @@ Execute a Grok CLI (xAI) request with session support.
 - `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)
+- `maxTurns` (integer, optional): Agent-loop iteration cap (`--max-turns`)
+- `workingDir` (string, optional): Working directory for this invocation (`--cwd`)
+- `sandbox` (string, optional): Sandbox profile for filesystem/network access (`--sandbox`, freeform; also via `GROK_SANDBOX`)
+- `rules` (string, optional): Extra rules appended to the system prompt (`--rules`; supports `@file` prefix)
+- `systemPromptOverride` (string, optional): Replace the agent's system prompt entirely
+- `allow` / `deny` (string[], optional): Permission allow/deny rules (one `--allow`/`--deny` per entry)
+- `compactionMode` (string, optional): `summary` (default) `|transcript|segments`
+- `compactionDetail` (string, optional): `none|minimal|balanced|verbose` (segments mode only)
+- `agent` (string, optional): Agent name or definition file path
+- `agents` (string|object, optional): Inline subagent definitions JSON
+- `bestOfN` (integer, optional): Run the task N ways in parallel and pick the best (headless only)
+- `check` (boolean, optional): Append a self-verification loop (headless only)
+- `disableWebSearch` (boolean, optional): Disable web search and remote retrieval tools
+- `todoGate` (boolean, optional): Enable runtime turn-end TodoGate (session-scoped)
+- `verbatim` (boolean, optional): Send the prompt exactly as given (also skips gateway prompt optimisation)
+- `promptFile` / `promptJson` / `single` (optional): Single-turn prompt from a file / JSON blocks / literal
+- `experimentalMemory` / `noMemory` (boolean, optional): Enable/disable cross-session memory
+- `noAltScreen` / `noPlan` / `noSubagents` (boolean, optional): Disable alt screen / plan mode / subagent spawning
+- `oauth` (boolean, optional): Use OAuth during authentication
+- `restoreCode` (boolean, optional): Check out the original session commit when resuming
+- `leaderSocket` (string, optional): Custom leader socket path (`--leader-socket`, Grok 0.2.32+; default `~/.grok/leader.sock`) — targets an isolated leader process, e.g. a local/branch Grok build
+- `nativeWorktree` (boolean|string, optional): Grok's own `--worktree` flag (`true` → bare, string → named); distinct from the gateway `worktree` option
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `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)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Example:**
 
@@ -738,6 +823,21 @@ Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but wit
 - `disallowedTools` (string[], optional): Accepted for parity with the other providers; ignored at the CLI boundary with a logged warning.
 - `outputFormat` (string, optional): Vibe 2.x values are `"text"`, `"json"`, or `"streaming"`; legacy aliases `"plain"` and `"stream-json"` are accepted and normalized before spawn.
 - `sessionId` / `resumeLatest` / `createNewSession`: standard session controls. Current Vibe defaults session logging to enabled; if an older config has `[session_logging] enabled = false`, `doctor --json` surfaces an actionable next-action.
+- `trust` (boolean, optional): Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted; skips the interactive trust prompt)
+- `maxTurns` (integer, optional): Agent-loop iteration cap (`--max-turns`, programmatic mode only)
+- `maxPrice` (number, optional): Interrupt when cumulative cost crosses this USD cap (`--max-price`, programmatic mode only)
+- `maxTokens` (integer, optional): Cap cumulative prompt + completion tokens (`--max-tokens`, programmatic mode only)
+- `workingDir` (string, optional): Change to this directory before running (`--workdir`)
+- `addDir` (string[], optional): Additional writable workspace directories (one `--add-dir` per entry)
+- `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
+- `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
+- `mcpServers` (string[], optional): MCP server names tracked for approvals (Vibe manages its own MCP config via `vibe mcp`)
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
+- `optimizePrompt` / `optimizeResponse` (boolean, optional): Token-efficiency optimisation, default: false
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 ##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async`
 
@@ -776,10 +876,33 @@ List recent MCP-managed approval decisions recorded by the gateway.
 **Parameters:**
 
 - `limit` (number, optional): Max records (1-500), default: 50
-- `cli` (string, optional): Filter by `"claude"`, `"codex"`, or `"gemini"`
+- `cli` (string, optional): Filter by `"claude"`, `"codex"`, `"gemini"`, `"grok"`, or `"mistral"`
 
 Approval records are persisted to `~/.llm-cli-gateway/approvals.jsonl`.
 
+##### `llm_request_result`
+
+Read back any persisted request — sync or async — by its correlation ID. Every response echoes its ID in `structuredContent.correlationId`; pass it here to recover the persisted prompt/response after the inline result is gone. Reads the flight recorder, so it works independently of async-job persistence (returns "not found" when flight recording is disabled).
+
+**Parameters:**
+
+- `correlationId` (string, required): Correlation ID from a prior request
+- `maxChars` (number, optional): Max chars of the persisted response to return (1,000-2,000,000)
+- `includePrompt` (boolean, optional): Include the full persisted prompt text, default: false
+
+##### `llm_process_health`
+
+Report gateway process health: async-job manager state plus the resolved persistence block (`backend`, `dbPath`, config sources). Use it to confirm which config file and SQLite paths the gateway is actually running under.
+
+##### `upstream_contracts`
+
+Return the gateway's declared provider CLI contracts, optionally probing the installed binaries for drift.
+
+**Parameters:**
+
+- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral`)
+- `probeInstalled` (boolean, optional, default `false`): Run local `--help` probes and compare advertised flags against the declared contract — strongly recommended after any provider CLI upgrade. The probe reports `missingFlags`, `extraFlags`, `acknowledgedExtraFlags` (known upstream-only flags filtered from `extraFlags`), `discoveredFlags`, and stale-marker `warnings`.
+
 #### Session Management Tools
 
 ##### `session_create`
@@ -922,6 +1045,9 @@ Plan or run an upgrade for one CLI.
 - Codex latest: `codex update`
 - Codex explicit target: `npm install -g @openai/codex@<target>`
 - Gemini: `npm install -g @google/gemini-cli@<target>`
+- Grok latest: `grok update`
+- Grok explicit target: `grok update --version <target>`
+- Mistral (Vibe): dispatches to the detected installer (`pip`/`uv`/`brew`); errors with guidance when none is detected (Vibe ships no self-update command)
 
 **Example dry run:**
 
@@ -1180,8 +1306,8 @@ If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/pack
 | **Network access**               | `src/http-transport.ts` opens an HTTP MCP transport when started via `npm run start:http`. `src/endpoint-exposure.ts` issues a HEAD probe to verify configured public/tunnel URLs. Socket also flagged `dist/upstream-contracts.js` in v1.17.2 from descriptive text, not a network call. | The transport binds to `127.0.0.1` by default and requires `LLM_GATEWAY_AUTH_TOKEN` to be set. The default stdio MCP entry point (`npm start`) opens no sockets. `src/upstream-contracts.ts` stores provider CLI metadata and imports no HTTP client APIs.                                                                                                  |
 | **Shell access**                 | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                    | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `gemini`, `grok`, `vibe`).                                                                                                         |
 | **Uses eval**                    | None in our source. Transitive: `@modelcontextprotocol/sdk` → `ajv@8` uses `new Function(...)` in `ajv/dist/compile/index.js` to compile JSON Schema validators.                                 | This is ajv's standard codegen path. Only known schemas (defined in our source and the MCP SDK) flow into it; no caller-supplied data ever reaches the compiled function body.                                                                                                                                                                               |
-| **better-sqlite3 PRAGMA helper** | Transitive: `better-sqlite3/lib/methods/pragma.js` interpolates its caller-provided `source` into a `PRAGMA ${source}` statement.                                                                | We do not call `db.pragma()` from production source. Internal SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements, and `npm run security:audit` fails the release if production code reintroduces `.pragma()` calls.                                                                                                                          |
-| **Dependency ownership**         | A handful of small transitive packages (e.g. `bindings` via `better-sqlite3`, `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics. | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. Our previous direct dependency on `toml@3.0.0` (also single-maintainer, last released 2020) was replaced with the actively-maintained `smol-toml` to reduce inherited risk. |
+| **SQLite adapter isolation**     | Persistence uses Node's built-in `node:sqlite` module (no native binding, no install scripts) through a single adapter, `src/sqlite-driver.ts`.                                                  | `node:sqlite` is touched by exactly one production module (the adapter); every other module talks to SQLite through its typed surface. We never call any `db.pragma()` helper (it does not exist on `node:sqlite`); SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements. `npm run security:audit` fails the release if production code references `node:sqlite` outside the adapter or reintroduces a `.pragma()` call.                                                            |
+| **Dependency ownership**         | A handful of small transitive packages (e.g. `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics.                                  | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. As of 2.0.0 the prod graph carries no native module (`better-sqlite3` moved to devDependencies; `node:sqlite` is built into Node), eliminating the entire `prebuild-install`/`tar-fs`/`tar-stream` install-time chain. Our earlier direct dependency on `toml@3.0.0` was replaced with `smol-toml`.        |
 
 See [`socket.yml`](./socket.yml) for the same context in machine-readable form.
 

package/dist/flight-recorder.d.ts

@@ -34,6 +34,9 @@ interface LoggerLike {
 export declare function resolveFlightRecorderDbPath(): string | null;
 export declare class FlightRecorder {
     private db;
+    private readOnlyDb;
+    private closed;
+    private readonly dbPath;
     private insertStartTxn;
     private updateCompleteTxn;
     constructor(dbPath: string);

package/dist/flight-recorder.js

@@ -1,10 +1,10 @@
-import { chmodSync, existsSync, mkdirSync } from "fs";
+import { chmodSync } from "fs";
 import os from "os";
 import path from "path";
-import { createRequire } from "module";
+import { openDatabase, openReadOnly } from "./sqlite-driver.js";
 const MAX_THINKING_BYTES = 1_000_000;
 function ensureRequestsCacheColumns(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("cache_read_tokens")) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_read_tokens INTEGER");
@@ -14,7 +14,7 @@ function ensureRequestsCacheColumns(db) {
     }
 }
 function ensureStablePrefixColumns(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("stable_prefix_hash")) {
         db.exec("ALTER TABLE requests ADD COLUMN stable_prefix_hash TEXT");
@@ -25,7 +25,7 @@ function ensureStablePrefixColumns(db) {
     db.exec("CREATE INDEX IF NOT EXISTS idx_requests_stable_hash ON requests(stable_prefix_hash)");
 }
 function ensureCacheControlBlocksColumn(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("cache_control_blocks")) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_control_blocks INTEGER");
@@ -77,16 +77,14 @@ function truncateThinkingBlocks(blocks) {
 }
 export class FlightRecorder {
     db;
+    readOnlyDb = null;
+    closed = false;
+    dbPath;
     insertStartTxn;
     updateCompleteTxn;
     constructor(dbPath) {
-        const require = createRequire(import.meta.url);
-        const BetterSqlite3 = require("better-sqlite3");
-        const directory = path.dirname(dbPath);
-        if (!existsSync(directory)) {
-            mkdirSync(directory, { recursive: true });
-        }
-        this.db = new BetterSqlite3(dbPath);
+        this.dbPath = dbPath;
+        this.db = openDatabase(dbPath);
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA foreign_keys = ON");
         this.db.exec(`
@@ -165,7 +163,7 @@ export class FlightRecorder {
       INSERT INTO gateway_metadata (request_id, async_job_id, status)
       VALUES (@request_id, @async_job_id, 'started')
     `);
-        this.insertStartTxn = this.db.transaction((entry) => {
+        this.insertStartTxn = this.db.withTransaction((entry) => {
             insertRequest.run({
                 id: entry.correlationId,
                 cli: entry.cli,
@@ -206,7 +204,7 @@ export class FlightRecorder {
           status = @status
       WHERE request_id = @id AND status = 'started'
     `);
-        this.updateCompleteTxn = this.db.transaction((correlationId, result) => {
+        this.updateCompleteTxn = this.db.withTransaction((correlationId, result) => {
             const thinkingBlocks = result.thinkingBlocks && result.thinkingBlocks.length > 0
                 ? JSON.stringify(truncateThinkingBlocks(result.thinkingBlocks))
                 : null;
@@ -240,18 +238,22 @@ export class FlightRecorder {
         this.updateCompleteTxn(correlationId, result);
     }
     queryRequests(sql, ...params) {
-        const stmt = this.db.prepare(sql);
-        if (stmt.readonly === false) {
-            throw new Error("FlightRecorder.queryRequests refuses non-readonly SQL — use a transaction or a separate write surface for INSERT/UPDATE/DELETE.");
+        if (this.closed) {
+            throw new Error("flight recorder is closed");
         }
-        if (!stmt.all) {
-            return [];
+        if (!this.readOnlyDb) {
+            this.readOnlyDb = openReadOnly(this.dbPath);
         }
-        return stmt.all(...params);
+        return this.readOnlyDb.prepare(sql).all(...params);
     }
     flush() {
     }
     close() {
+        this.closed = true;
+        if (this.readOnlyDb) {
+            this.readOnlyDb.close();
+            this.readOnlyDb = null;
+        }
         this.db.close();
     }
 }

package/dist/index.d.ts

@@ -251,6 +251,7 @@ export declare function prepareGrokRequest(params: {
     noSubagents?: boolean;
     oauth?: boolean;
     restoreCode?: boolean;
+    leaderSocket?: string;
     nativeWorktree?: boolean | string;
 }, runtime?: GatewayServerRuntime): CliRequestPrep | ExtendedToolResponse;
 export declare function prepareMistralRequest(params: {
@@ -376,6 +377,7 @@ export interface GrokRequestParams {
     noSubagents?: boolean;
     oauth?: boolean;
     restoreCode?: boolean;
+    leaderSocket?: string;
     nativeWorktree?: boolean | string;
     worktree?: boolean | {
         name?: string;