llm-cli-gateway 1.5.4 → 1.5.14

package/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [1.5.14] - 2026-05-24
+
+### Fixed
+
+- Remove the Redis Lua `eval` lock-release path from production source and replace it with Redis `WATCH`/`MULTI` compare-and-delete semantics.
+- Add exact direct production dependencies for `content-type@1.0.5` and `type-is@2.0.1` so packed consumer installs do not resolve the Socket-flagged `content-type@2.0.0` / `type-is@2.1.0` versions.
+
+### Added
+
+- Add `npm run security:audit` as a CI/release gate covering `npm audit --omit=dev`, production source dynamic-execution scanning, blocked dependency-version checks, and a packed consumer install policy check.
+
+## [1.5.13] - 2026-05-24
+
+### Fixed
+
+- Report missing provider CLI launches as a clear command-not-found error instead of leaking Windows/libuv codes such as `-4058`.
+- Preserve async provider launch errors in job stderr/result output so sync MCP tools can return actionable setup guidance.
+- Replace `irm | iex` Windows install guidance and generated release manifest commands with direct binary download plus SHA256 verification.
+
+## [1.5.12] - 2026-05-24
+
+### Fixed
+
+- Stop detaching provider CLI processes on Windows so `ask_model` and async requests do not flash visible cmd/conhost windows.
+- Use hidden Windows process creation for the bootstrapper's managed Node gateway process and status checks.
+- Keep Windows process cleanup by killing provider process trees with hidden `taskkill.exe` instead of Unix process-group signals.
+
+## [1.5.11] - 2026-05-24
+
+### Fixed
+
+- Install a stable Windows `llm-cli-gateway.exe` command alongside the versioned bootstrapper and add the install directory to the user PATH.
+- Make the Windows one-command installer stop any running gateway before replacing the managed bundle, then start and doctor through the stable command.
+- Fix bootstrapper `status` and `stop` behavior on Windows so they do not depend on Unix-style PID probing.
+
+## [1.5.10] - 2026-05-24
+
+### Fixed
+
+- Hide Windows console windows when the gateway spawns provider CLIs for synchronous and asynchronous requests.
+
+## [1.5.9] - 2026-05-24
+
+### Fixed
+
+- Fix the Node entrypoint direct-run guard on Windows by using `pathToFileURL(realpathSync(...))` instead of constructing a POSIX-style file URL manually.
+- Make the Windows one-command installer stop when bootstrapper commands fail by checking native process exit codes.
+
+## [1.5.8] - 2026-05-24
+
+### Fixed
+
+- Make `start` wait for the local HTTP health endpoint before reporting success.
+- Write gateway stdout/stderr to local log files so startup failures are diagnosable instead of returning a misleading PID.
+
+## [1.5.7] - 2026-05-24
+
+### Fixed
+
+- Add a release-pinned `install-windows.ps1` asset so Windows users can install with one PowerShell command while still verifying the downloaded bootstrapper and platform bundle against `SHA256SUMS`.
+- Add the Windows one-liner to `release-manifest.json` and upload the installer script as part of the desktop release workflow.
+
+## [1.5.6] - 2026-05-24
+
+### Fixed
+
+- Replace the host-Node installer path with platform-specific verified bundles that include the compiled gateway, production dependencies, setup assets, and a managed Node runtime.
+- Make the bootstrapper start the managed runtime from the installed bundle and require `RVWR_ALLOW_HOST_NODE=1` for the developer host-Node fallback.
+- Update release packaging metadata and docs so Windows/macOS/Linux install instructions use `llm-cli-gateway-bundle-<version>-<os>-<arch>.tar.gz`.
+- Update production dependencies (`@modelcontextprotocol/sdk`, `better-sqlite3`, and transitive Hono/AJV packages) so `npm audit --omit=dev` reports zero vulnerabilities while pinning `type-is` and `content-type` away from Socket-flagged latest releases.
+
+## [1.5.5] - 2026-05-24
+
+### Fixed
+
+- Build desktop installer binaries on local self-hosted Linux, Windows, and macOS runners, then publish combined release metadata from the Linux packaging job.
+- Make `installer/build-release.sh` default to the host target for local runs, with `--all-targets` / `RVWR_RELEASE_ALL_TARGETS=1` reserved for local full-matrix testing.
+- Package setup UI/provider assets into the verified gateway bundle and let the setup UI resolve installed bundle assets from the managed gateway directory.
+
 ## [1.5.4] - 2026-05-19
 
 ### Fixed

package/README.md

@@ -20,7 +20,7 @@ Current personal-appliance artifacts include:
 - Streamable HTTP startup: `LLM_GATEWAY_AUTH_TOKEN=<token> npm run start:http`
 - Machine-readable diagnostics: `npm run doctor`
 - Go bootstrapper scaffold: `installer/` with `setup`, `doctor --json`, `start`, `stop`, `status`, `repair`, `upgrade`, `uninstall`, `print-client-config`, and verified bundle download commands.
-- Release packaging: `npm run release:build` produces cross-platform binaries plus a checksummed Node bundle under `installer/dist/`; see [installer/packaging/README.md](installer/packaging/README.md).
+- Release packaging: the release workflow builds Linux binaries on the local self-hosted runner, builds Windows/macOS binaries on GitHub-hosted runners, then publishes checksummed platform bundles with the gateway, production dependencies, and a managed Node runtime; see [installer/packaging/README.md](installer/packaging/README.md).
 - Docker Compose fallback: [docker-compose.personal.yml](docker-compose.personal.yml) + [Dockerfile.personal](Dockerfile.personal) for users who already manage containers.
 - Local setup UI artifact: [setup/ui/index.html](setup/ui/index.html)
 - Provider setup snippets: [setup/providers/](setup/providers/)
@@ -28,12 +28,35 @@ Current personal-appliance artifacts include:
 
 ### Install / Upgrade / Uninstall (single binary)
 
+Windows PowerShell:
+
+```powershell
+$Version = '<version>'
+$Base = "https://github.com/verivus-oss/llm-cli-gateway/releases/download/v$Version"
+$InstallDir = Join-Path (Join-Path $env:LOCALAPPDATA 'Programs') 'llm-cli-gateway'
+$Exe = Join-Path $InstallDir 'llm-cli-gateway.exe'
+New-Item -ItemType Directory -Force $InstallDir | Out-Null
+Invoke-WebRequest -UseBasicParsing "$Base/llm-cli-gateway-$Version-windows-amd64.exe" -OutFile $Exe
+$env:RVWR_GATEWAY_BUNDLE_URL = "$Base/llm-cli-gateway-bundle-$Version-windows-amd64.tar.gz"
+$env:RVWR_GATEWAY_BUNDLE_SHA256 = '<bundle-sha256-from-SHA256SUMS>'
+& $Exe setup
+& $Exe stop
+& $Exe install-bundle
+& $Exe start
+& $Exe status
+& $Exe doctor
+```
+
+The Windows installer keeps a stable `llm-cli-gateway.exe` command in
+`%LOCALAPPDATA%\Programs\llm-cli-gateway` and adds that directory to the user
+PATH. Do not script against release-versioned exe names after install.
+
 ```bash
 # After downloading the binary that matches your OS/arch from a release:
 sha256sum --check SHA256SUMS            # verify before run (or `shasum -a 256 --check` on macOS)
 chmod +x llm-cli-gateway-<ver>-<os>-<arch>
 ./llm-cli-gateway-<ver>-<os>-<arch> setup
-./llm-cli-gateway-<ver>-<os>-<arch> install-bundle    # uses RVWR_GATEWAY_BUNDLE_URL/_SHA256
+./llm-cli-gateway-<ver>-<os>-<arch> install-bundle    # uses the platform bundle URL/SHA256
 ./llm-cli-gateway-<ver>-<os>-<arch> start
 ./llm-cli-gateway-<ver>-<os>-<arch> doctor
 
@@ -340,17 +363,233 @@ Execute a Grok CLI (xAI) request with session support.
 
 #### 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:
+Every async job is persisted to a job store 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).
+##### Persistence configuration
+
+The job-store backend is configured by `~/.llm-cli-gateway/config.toml` (override with `LLM_GATEWAY_CONFIG=/path/to/config.toml`). Example:
+
+```toml
+[persistence]
+backend = "sqlite"                          # "sqlite" | "memory" | "postgres" | "none"
+path = "~/.llm-cli-gateway/logs.db"         # for sqlite
+# dsn = "postgresql://user:pw@host/db"      # for postgres (interface only — impl not yet shipped)
+retentionDays = 30
+dedupWindowMs = 3600000
+acknowledgeEphemeral = false                # required to enable async tools with memory backend
+```
+
+Backends:
+- **`sqlite`** (default) — durable, file-backed. Safe for single-instance deployments.
+- **`memory`** — in-process Map. Lost on gateway exit. Requires `acknowledgeEphemeral = true` to be loaded. Suitable for tests and ephemeral CI gateways.
+- **`postgres`** — interface only, implementation not yet shipped. Selecting this backend throws at startup.
+- **`none`** — no store. **`*_request_async`, `llm_job_status`, `llm_job_result`, and `llm_job_cancel` are NOT registered on the gateway.** This is a structural invariant: agents that try to call async tools against a gateway with `backend = "none"` get a clean "tool not found" at connect time instead of silent in-memory loss after the 1-hour TTL. Use `llm_process_health` to inspect the resolved persistence state programmatically.
+
+Legacy environment variables (deprecated; emit a warning at startup):
+- `LLM_GATEWAY_LOGS_DB` / `LLM_GATEWAY_JOBS_DB` — `none` selects `backend = "none"`; any other value selects `backend = "sqlite"` with that path.
+- `LLM_GATEWAY_JOB_RETENTION_DAYS` — overrides `retentionDays`.
+- `LLM_GATEWAY_DEDUP_WINDOW_MS` — overrides `dedupWindowMs`.
+- `LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL` — `1`/`true`/`yes` sets `acknowledgeEphemeral = true`.
+
+##### Per-project isolation
+
+By default, **all gateway data is global per user**, not per project. With no overrides, every Claude Code window — across every repo — spawns its own gateway subprocess but they all read and write the same files:
+
+- `~/.llm-cli-gateway/logs.db` (async jobs + flight recorder)
+- `~/.llm-cli-gateway/sessions.json` (CLI sessions)
+- `~/.llm-cli-gateway/config.toml` (resolved config)
+
+This is usually what you want — `session_list` from repo A shows sessions from repo B, an async job started in window A can be polled from window B, and the 1-hour dedup window catches re-issues across windows. SQLite WAL mode makes concurrent access from multiple gateway subprocesses safe.
+
+If you instead want **per-project isolation** (e.g. unrelated repos shouldn't share session lists or risk false dedup hits), point each project at its own config file. In `.claude/settings.local.json` for the project:
+
+```json
+{
+  "mcpServers": {
+    "llm-gateway": {
+      "env": {
+        "LLM_GATEWAY_CONFIG": "${workspaceFolder}/.gateway/config.toml"
+      }
+    }
+  }
+}
+```
+
+…and put a per-project `config.toml` in the repo:
+
+```toml
+[persistence]
+backend = "sqlite"
+path = "/srv/repos/.../my-repo/.gateway/logs.db"
+```
+
+Now every gateway subprocess spawned for *this* repo's Claude Code window reads its own config and writes to its own SQLite file; sessions, jobs, and dedup state are scoped to the repo. Other repos keep using the global default. `llm_process_health.persistence.sources.configFile` lets an agent confirm which config it's actually running under.
+
+###### Agent-executable spec (DAG-TOML)
+
+If you want an LLM agent to perform this setup deterministically — rather than reading the prose above and guessing — copy the following DAG-TOML into the repo (e.g. `docs/planning/per-project-gateway-isolation.toml`) and point your agent at it. The schema is [`agent-assurance`](https://github.com/verivus-oss/agent-assurance/blob/main/SPEC.md) `template_kind = "implementation-dag"`. The agent MUST execute units in layer order, must not skip the verification unit, and must treat any failed gate as blocking.
+
+```toml
+[meta]
+schema_version    = "1.0.0"
+template_kind     = "implementation-dag"
+docs              = "https://github.com/verivus-oss/agent-assurance/blob/main/SPEC.md"
+confidentiality   = "public"
+title             = "Per-project llm-cli-gateway persistence isolation"
+spec              = "https://github.com/verivusai-labs/llm-cli-gateway#per-project-isolation"
+created           = "YYYY-MM-DD"
+total_units       = 5
+tier1_units       = ["U01","U02","U03","U04","U05"]
+tier2_units       = []
+tier3_units       = []
+
+# ============================================================================
+# [policy.agent] — persona for the agent performing the configuration.
+# ============================================================================
+
+[policy.agent]
+name                 = "Gateway Persistence Isolator"
+role                 = "Configuration Engineer"
+purpose              = "Configure the llm-cli-gateway MCP server so its async job store, sessions, dedup state, and flight recorder are scoped to THIS repository instead of the per-user default at ~/.llm-cli-gateway/."
+validation_type      = "Structural + Runtime Verification"
+workflow_initiator   = false
+description          = "Writes a repo-local config.toml, registers an LLM_GATEWAY_CONFIG override in .claude/settings.local.json, restarts the MCP server, and confirms via llm_process_health that the gateway is now reading the repo-local config and writing to the repo-local SQLite path."
+
+[policy.agent.orchestration]
+consumes_events      = ["PerProjectIsolationRequested"]
+produces_events      = ["PerProjectIsolationComplete"]
+
+[policy.agent.responsibilities]
+items = [
+  "Create the repo-local gateway data directory and add it to .gitignore.",
+  "Write a config.toml that pins backend=sqlite to a repo-local path.",
+  "Register the LLM_GATEWAY_CONFIG env override in .claude/settings.local.json (NOT .mcp.json — that file is committed and shared).",
+  "Trigger an MCP server reconnect.",
+  "Verify via llm_process_health that the resolved configFile and dbPath are the repo-local values.",
+]
+
+# ============================================================================
+# [policy.instance] — concrete paths the agent fills in for THIS repo.
+# Agent MUST replace <REPO_ABS_PATH> with the absolute path to the repo
+# before emitting any artefact. Relative paths in config.toml MUST be
+# expanded to absolute — the gateway does not re-resolve them per cwd.
+# ============================================================================
+
+[policy.instance]
+repo_abs_path                  = "<REPO_ABS_PATH>"           # e.g. /srv/repos/me/my-project
+gateway_data_dir_relative      = ".gateway"                  # repo-relative directory
+config_toml_relative           = ".gateway/config.toml"
+sqlite_db_relative             = ".gateway/logs.db"
+claude_local_settings_relative = ".claude/settings.local.json"
+gitignore_relative             = ".gitignore"
+mcp_server_name                = "llm-gateway"               # must match the entry in .mcp.json
+
+# ============================================================================
+# [policy.gates] — blocking checks. Any failure stops the workflow.
+# ============================================================================
+
+[policy.gates]
+gate_repo_abs_path_resolved    = "policy.instance.repo_abs_path must NOT be the literal string '<REPO_ABS_PATH>' when U01 starts."
+gate_config_is_committed       = "policy.instance.config_toml_relative MAY be committed. policy.instance.claude_local_settings_relative MUST NOT be committed (it is per-developer). Agent MUST verify .gitignore covers .claude/settings.local.json if absent."
+gate_no_legacy_env_leak        = "Agent MUST grep the shell init files for LLM_GATEWAY_LOGS_DB / LLM_GATEWAY_JOBS_DB. If set, the legacy env var will override the new config and the deprecation warning will fire at every gateway boot. The agent reports this as a finding and asks the operator to unset before proceeding."
+gate_health_confirms_isolation = "U05 MUST observe llm_process_health.persistence.sources.configFile == policy.instance.repo_abs_path + '/' + policy.instance.config_toml_relative AND llm_process_health.persistence.path == policy.instance.repo_abs_path + '/' + policy.instance.sqlite_db_relative. Anything else means the override did not take effect."
+
+# ============================================================================
+# [policy.evidence] — what each unit must emit so the work is auditable.
+# ============================================================================
+
+[policy.evidence]
+per_unit_required_fields = [
+  "unit_id",                  # U01..U05
+  "status",                   # "completed" | "failed"
+  "artefact_paths",           # files written / modified
+  "stdout_tail",              # last 20 lines of any command output
+  "verification_quote",       # for U05, the verbatim llm_process_health.persistence block
+]
+findings_required_fields = [
+  "gate_id",                  # which gate failed
+  "observed",
+  "expected",
+  "remediation",
+]
+
+# ============================================================================
+# Units. Execute in layer order. U01..U03 modify the working tree; U04
+# triggers a reconnect; U05 is the verification gate that decides success.
+# ============================================================================
+
+[units.U01]
+name           = "create-repo-local-data-dir"
+summary        = "mkdir -p <repo>/.gateway and append /.gateway/ to .gitignore (creating .gitignore if missing). The gateway will write logs.db, logs.db-wal, logs.db-shm here — none should be committed."
+layer          = 0
+tier           = 1
+status         = "pending"
+depends_on     = []
+blocks         = ["U02"]
+estimated_loc  = 5
+files_modify   = [".gitignore"]
+produces       = ["ART:gateway-data-dir"]
+consumes       = []
+
+[units.U02]
+name           = "write-config-toml"
+summary        = "Write <repo>/.gateway/config.toml with [persistence] backend='sqlite' and path=<absolute-path-to-repo>/.gateway/logs.db. Path MUST be absolute. Do NOT use ~ — the gateway expands ~ but [persistence].path is read literally if not prefixed with ~/, and Claude Code may launch the gateway with a HOME that surprises you."
+layer          = 1
+tier           = 1
+status         = "pending"
+depends_on     = ["U01"]
+blocks         = ["U03"]
+estimated_loc  = 10
+files_modify   = [".gateway/config.toml"]
+produces       = ["ART:gateway-config"]
+consumes       = ["ART:gateway-data-dir"]
+
+[units.U03]
+name           = "register-llm-gateway-config-env-in-claude-local-settings"
+summary        = "Add (or merge) an mcpServers.<mcp_server_name>.env entry in .claude/settings.local.json that sets LLM_GATEWAY_CONFIG to the absolute path of .gateway/config.toml. Do NOT modify .mcp.json — that file is committed and the path would be wrong for every other developer. If .claude/settings.local.json already has an mcpServers.<mcp_server_name> entry, the agent MUST merge into the existing env map (preserving other keys), not overwrite the whole entry."
+layer          = 2
+tier           = 1
+status         = "pending"
+depends_on     = ["U02"]
+blocks         = ["U04"]
+estimated_loc  = 20
+files_modify   = [".claude/settings.local.json"]
+produces       = ["ART:claude-local-settings"]
+consumes       = ["ART:gateway-config"]
+
+[units.U04]
+name           = "trigger-mcp-reconnect"
+summary        = "Ask the operator to run /mcp in Claude Code (or restart Claude Code) so the gateway subprocess is re-spawned under the new env. The agent cannot do this itself — MCP server lifecycle is owned by the host."
+layer          = 3
+tier           = 1
+status         = "pending"
+depends_on     = ["U03"]
+blocks         = ["U05"]
+estimated_loc  = 0
+files_modify   = []
+produces       = ["OUT:mcp-reconnected"]
+consumes       = ["ART:claude-local-settings"]
+
+[units.U05]
+name           = "verify-via-llm-process-health"
+summary        = "Call llm_process_health and assert the returned persistence block satisfies policy.gates.gate_health_confirms_isolation. Quote the verbatim persistence block in evidence. If the assertion fails, the agent MUST NOT mark the workflow complete — it must emit a finding under policy.evidence.findings_required_fields, naming the observed vs. expected configFile/path, and stop."
+layer          = 4
+tier           = 1
+status         = "pending"
+depends_on     = ["U04"]
+blocks         = []
+estimated_loc  = 5
+files_modify   = []
+produces       = ["ART:isolation-verification","OUT:per-project-isolation-complete"]
+consumes       = ["OUT:mcp-reconnected"]
+```
+
+**Why this matters for agents:** the gateway has multiple configuration surfaces (TOML file, env-var overrides, two different MCP settings files) and one easy mistake — editing the committed `.mcp.json` instead of the local-only `.claude/settings.local.json` — will silently break the per-project scope for every other developer on the repo. The DAG above encodes the correct sequence, the verification gate, and the failure modes explicitly so an agent can execute it without inference.
 
 ##### `mistral_request`
 Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but with Vibe's specific surface:
@@ -582,11 +821,12 @@ 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.
+- `LLM_GATEWAY_CONFIG`: Path to the gateway TOML config (default: `~/.llm-cli-gateway/config.toml`). See **Persistence configuration** above for the `[persistence]` schema.
+- `LLM_GATEWAY_LOGS_DB`: **Deprecated** — overrides `[persistence].path` and selects `backend = "sqlite"` (or `backend = "none"` when set to `none`). Emits a deprecation warning at startup; migrate to `config.toml`.
   ```bash
   # Custom path
   LLM_GATEWAY_LOGS_DB=/var/log/gateway/logs.db node dist/index.js
-  # Disable flight recorder
+  # Disable durable persistence (also disables *_request_async tools)
   LLM_GATEWAY_LOGS_DB=none node dist/index.js
   ```
 

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

@@ -61,6 +61,14 @@ export declare class AsyncJobManager {
     private processMonitor;
     private store;
     constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null);
+    /**
+     * True iff a durable (or memory) job store is attached. The MCP-tool
+     * registration layer ANDs this with persistence.asyncJobsEnabled when
+     * deciding whether to register the *_request_async / llm_job_* tools.
+     * Without a store, async tools must not be registered, otherwise we
+     * re-open the silent in-memory loss path the structural invariant closes.
+     */
+    hasStore(): boolean;
     private emitMetrics;
     private evictCompletedJobs;
     /**

package/dist/async-job-manager.js

@@ -1,6 +1,5 @@
-import { spawn } from "child_process";
 import { randomUUID } from "crypto";
-import { getExtendedPath, killProcessGroup, registerProcessGroup, unregisterProcessGroup, } from "./executor.js";
+import { getExtendedPath, killProcessGroup, spawnCliProcess, unregisterProcessGroup, } from "./executor.js";
 import { noopLogger } from "./logger.js";
 import { ProcessMonitor } from "./process-monitor.js";
 import { computeRequestKey } from "./job-store.js";
@@ -8,6 +7,19 @@ const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
 const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour in-memory retention; durable store has its own (longer) retention
 const EVICTION_INTERVAL_MS = 5 * 60 * 1000; // Check every 5 minutes
 const OUTPUT_FLUSH_INTERVAL_MS = 1000; // Throttle DB writes for streaming stdout/stderr
+function describeProcessLaunchError(cli, error) {
+    const code = error.code;
+    if (code === "ENOENT") {
+        return {
+            exitCode: 127,
+            message: `The '${cli}' command was not found. Install the ${cli} CLI and make sure it is on PATH. (${error.message})`,
+        };
+    }
+    return {
+        exitCode: 126,
+        message: `Failed to launch ${cli} CLI: ${error.message}`,
+    };
+}
 /**
  * U22 fix: deterministic canonicalisation of an env-var map for the dedup key.
  * Returns "" when env is undefined or empty (preserves dedup key continuity for
@@ -62,6 +74,16 @@ export class AsyncJobManager {
             this.evictionTimer.unref();
         }
     }
+    /**
+     * True iff a durable (or memory) job store is attached. The MCP-tool
+     * registration layer ANDs this with persistence.asyncJobsEnabled when
+     * deciding whether to register the *_request_async / llm_job_* tools.
+     * Without a store, async tools must not be registered, otherwise we
+     * re-open the silent in-memory loss path the structural invariant closes.
+     */
+    hasStore() {
+        return this.store !== null;
+    }
     emitMetrics(job) {
         if (job.metricsRecorded)
             return;
@@ -335,15 +357,11 @@ export class AsyncJobManager {
         // Mistral Vibe ships as the `vibe` binary; the gateway uses `mistral` as the
         // provider key but spawns `vibe` on the shell.
         const command = cli === "mistral" ? "vibe" : cli;
-        const child = spawn(command, args, {
+        const child = spawnCliProcess(command, args, {
             cwd,
-            detached: true,
             stdio: ["ignore", "pipe", "pipe"],
             env: { ...process.env, PATH: getExtendedPath(), ...(extraEnv ?? {}) },
         });
-        if (child.pid)
-            registerProcessGroup(child.pid);
-        child.unref();
         // Single cleanup flag to prevent double-unregister
         let groupCleaned = false;
         const cleanupGroup = () => {
@@ -436,10 +454,13 @@ export class AsyncJobManager {
             job.clearIdleTimer?.();
             job.cleanupGroup?.();
             if (job.status === "running") {
+                const launchError = describeProcessLaunchError(cli, error);
                 job.status = job.canceled ? "canceled" : "failed";
-                job.error = error.message;
+                job.exitCode = launchError.exitCode;
+                job.error = launchError.message;
+                job.stderr = job.stderr ? `${job.stderr}\n${launchError.message}` : launchError.message;
                 job.finishedAt = new Date().toISOString();
-                this.logger.error(`Job ${id} error: ${error.message}`, { correlationId });
+                this.logger.error(`Job ${id} error: ${launchError.message}`, { correlationId });
                 this.emitMetrics(job);
                 this.persistComplete(job);
                 this.fireOnComplete(job);
@@ -453,7 +474,7 @@ export class AsyncJobManager {
                 job.cleanupGroup?.();
             }
             if (job.status !== "running") {
-                job.exitCode = code ?? job.exitCode;
+                job.exitCode = job.exitCode ?? code ?? null;
                 if (!job.finishedAt) {
                     job.finishedAt = new Date().toISOString();
                 }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "./logger.js";
 export interface CacheTtl {
     session: number;
     activeSession: number;
@@ -33,3 +34,32 @@ export interface Config {
  * Database and Redis fields are populated only when both env vars are set.
  */
 export declare function loadConfig(): Config;
+export declare const PERSISTENCE_BACKENDS: readonly ["sqlite", "postgres", "memory", "none"];
+export type PersistenceBackend = (typeof PERSISTENCE_BACKENDS)[number];
+export declare const DEFAULT_JOB_RETENTION_DAYS = 30;
+export declare const DEFAULT_DEDUP_WINDOW_MS: number;
+export interface PersistenceConfig {
+    backend: PersistenceBackend;
+    path: string | null;
+    dsn: string | null;
+    retentionDays: number;
+    dedupWindowMs: number;
+    acknowledgeEphemeral: boolean;
+    /** True iff async-job tools should be registered on the MCP server. */
+    asyncJobsEnabled: boolean;
+    /** Audit trail: which inputs (file, env vars) contributed to the resolved config. */
+    sources: PersistenceConfigSources;
+}
+export interface PersistenceConfigSources {
+    configFile: string | null;
+    envOverrides: string[];
+}
+/**
+ * Load and validate the persistence config from (in order, last-write-wins):
+ *   1. Built-in defaults (backend=sqlite, default retention/dedup).
+ *   2. ~/.llm-cli-gateway/config.toml (or $LLM_GATEWAY_CONFIG).
+ *   3. Legacy env vars (with deprecation warning).
+ *
+ * Throws on incoherent configs (memory/none + asyncJobsEnabled without ack).
+ */
+export declare function loadPersistenceConfig(logger?: Logger): PersistenceConfig;