llm-cli-gateway 2.13.2 → 2.14.0

package/CHANGELOG.md

@@ -2,6 +2,145 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [Unreleased]
+
+## [2.14.0] - 2026-07-03
+
+### Fixed
+
+- **Durable instance-lease orphan recovery (#139).** The blanket
+  `markOrphanedOnStartup` sweep in the `AsyncJobManager` constructor rewrote
+  every `running` row to `orphaned`, so on a SHARED store (`backend =
+  "postgres"`) a fresh instance (especially an ephemeral stdio spawn)
+  transiently orphaned other live instances' in-flight jobs (a `running` ->
+  `orphaned` -> `completed` flap a poller can trip on). The sweep is now a
+  per-job fencing lease: each instance registers a lease and advances a
+  `jobs.lease_deadline` on every heartbeat, and the sweep orphans a
+  `queued`/`running` job only when its own `lease_deadline` has expired, never
+  because a different live instance started. Because heartbeat and sweep are
+  both `UPDATE`s on the same `jobs` rows, they serialize on the row lock
+  (Postgres READ COMMITTED) and are trivially serial under single-writer sqlite,
+  so no job whose owner heartbeated within the lease TTL is ever swept. A
+  genuinely stale-then-reviving owner self-heals to the correct terminal state
+  via the guarded `recordComplete` and a flight-recorder reconcile. The fix is
+  transport-aware (an extra `httpJobGrace` for no-pid http jobs, an advisory
+  never-vetoing `kill(pid,0)` for same-host process jobs), durable-admission is
+  fail-closed (a failed `recordStart`/`registerInstance` fails the request and
+  releases the limiter permit), and graceful shutdown drains in-flight terminal
+  writes before deregistering the lease. Additive schema (`jobs.owner_instance`,
+  `jobs.lease_deadline`, a `gateway_instances` table), auto-created on both
+  sqlite and postgres, no data migration.
+
+### Changed
+
+- **`[persistence].ownsOrphanRecovery` is deprecated (#139).** The interim gate
+  (PR #140) that let one designated `postgres` instance own the blanket startup
+  sweep is superseded by the durable lease above, which is safe to run from
+  every instance. The flag is still parsed (so existing configs do not error)
+  and now emits a one-time deprecation warning; it no longer changes behaviour
+  and will be removed in a later release. New `[persistence]` knobs tune the
+  lease: `instanceHeartbeatMs` (15000), `instanceLeaseTtlMs` (90000),
+  `httpJobGraceMs` (300000), `orphanSweepIntervalMs` (30000), `instanceGcMs`
+  (3600000), validated so `instanceLeaseTtlMs >= 2 * instanceHeartbeatMs` and
+  `httpJobGraceMs >= instanceLeaseTtlMs`.
+
+## [2.14.0-rc.1] - 2026-07-03: full-featured provider integration + security-review hardening
+
+Release candidate. Every non-Cursor provider (Claude, Codex, Gemini, Grok,
+Mistral, Devin) becomes a first-class, provider-definition-driven integration,
+and a security review of the change set is folded in. Cursor stays working via
+the shared generation and is maintenance-only.
+
+### Added
+
+- **Provider definitions as the single source of truth** (`src/provider-definitions.ts`):
+  one `ProviderDefinition` per CLI type drives request schemas, resources,
+  discovery, and capabilities, with compile-time exhaustiveness assertions and a
+  `scripts/provider-surfaces-check.mjs` ratchet wired into `npm run check`.
+- **Runtime provider capability discovery with an on-disk cache**: an injectable
+  probe runner (no shell interpolation of caller input), a cache keyed on
+  discovery checksums with a shape-driven secret scrubber and Zod-validated
+  reads, and a TTL that bounds staleness so an upgraded or moved provider CLI is
+  re-discovered instead of served stale.
+- **Registry-generated `models://` and `sessions://` resources** for every
+  provider (Devin and Cursor now first-class), plus **live model discovery**
+  wired into `models://<provider>` and `list_models` via a memoized resolver
+  with a fire-and-forget startup warm (reads never block on a spawn).
+- **Complete CLI request-field coverage** across providers, guarded by
+  upstream-contract and coverage-closure tests; interactive/admin-only flags are
+  represented as typed capability facts rather than silently dropped.
+- **Discovery-driven native ACP surface**: Grok, Mistral, and Devin route
+  natively over ACP when enabled (no masquerade), with capability-gated session
+  methods and state-mutating session ops gated behind
+  `acp.allow_mutating_session_ops`.
+- **Provider admin tools**: `provider_admin_list` / `provider_admin_run`
+  (read-only) and `provider_admin_mutate` (gated). Availability is
+  discovery-driven; mutating ops require `[admin] allow_mutating_cli_admin_ops`
+  and, for remote callers, `LLM_GATEWAY_CLI_ADMIN=1` plus the `cli:admin` OAuth
+  scope, routed through the approval manager with a fail-closed pre-spawn audit.
+- **Postgres job store** (`PostgresJobStore`): a durable async-job and
+  validation-run/receipt backend over the `pg` pool, driven through a dedicated
+  worker thread (`postgres-job-store-worker.ts`). Selectable via
+  `persistence.backend = "postgres"`; the ephemeral memory backend deliberately
+  does not implement the validation-run surface.
+- **Search-engine discoverability for the docs site**: Google Search Console
+  and Bing IndexNow submission (`npm run search:*`), plus `sitemap.xml`,
+  `robots.txt`, and `llms.txt`, alongside a marketing-site refresh.
+
+### Changed
+
+- **Unified provider output/event normalization**: a real Grok JSON parser, and
+  `stopReason`/error signals threaded across the CLI parsers and the ACP event
+  normalizer. The provider-minted session id and terminal stop reason are
+  preserved through the async job and flight recorder so a deferred job resumes
+  with the real provider session id.
+- **`provider_tool_capabilities`** now reports ACP `runtimeEnabled` from the
+  resolved config (previously hardcoded), with entrypoint/version/mediation
+  derived from the registry.
+- Docs: README provider-capability table, per-provider skills refreshed to the
+  installed CLI versions, ACP documented as sync-only for now, and the
+  `provider-acp://` resource registered on the MCP server.
+
+### Fixed
+
+- Codex and Gemini clean exits that actually carried a failed terminal event
+  now surface a warning instead of being reported as a silent empty success;
+  the ACP transport likewise flags a refusal/cancelled/truncated turn.
+- Codex surfaces the real `turn.failed` reason on a non-zero exit instead of a
+  partial agent message.
+- json-mode output parsers tolerate a stray banner line around the JSON object
+  (telemetry is no longer all-or-nothing), and the Gemini stream replaces rather
+  than doubles a consolidated non-delta final message.
+- Implausible `agy models` label lines are filtered instead of surfacing as
+  bogus models in `models://gemini`.
+
+### Security
+
+- **Remote host-path confinement.** Remote HTTP/OAuth callers can no longer hand
+  a provider CLI an arbitrary host path to read, write, or load code from. The
+  advanced path/plugin fields are rejected for remote callers (local stdio is
+  unaffected): `systemPromptFile`/`appendSystemPromptFile`/`settings`/
+  `pluginDir`/`pluginUrl`/`debugFile` (Claude), string `outputSchema`/`images`/
+  `outputLastMessage` (Codex), `promptFile`/`config`/`agentConfig`/string
+  `exportSession` (Devin), and `promptFile`/`leaderSocket`/`rules`/`agent`
+  (Grok). `workingDir`/`addDir`/`includeDirs` remain workspace-confined.
+- **Read-only provider-admin ops** now require the same remote `cli:admin` gate
+  as the mutating path, so a remote caller cannot enumerate or trigger
+  host-global provider-CLI spawns unprivileged.
+- **ACP permission bridge** never turns a single approval into a standing
+  `allow_always` grant (it selects a one-time allow, else denies).
+- **ACP subprocess reaping**: a graceful termination signal escalates to
+  SIGKILL after a grace window so a provider CLI that ignores SIGTERM is not
+  leaked as a zombie.
+- Job results scrub the provider session id from returned streams for remote
+  callers; ACP error redaction covers Google/GitHub/Slack token shapes;
+  `session_info_update` is handled as a forward-compatible unknown ACP variant.
+- CI/release: the Cloudflare Pages token is fetched from Azure Key Vault via
+  GitHub OIDC federation (no stored secret); the release tooling supports
+  prerelease cuts (a prerelease publishes under a side npm dist-tag, never
+  `latest`); typos and gitleaks allowlists cover a deliberate identifier and
+  secret-fixture test files.
+
 ## [2.13.2] - 2026-07-01: remote HTTP + OAuth connector UX and hardening
 
 ### Added

package/README.md

@@ -9,9 +9,11 @@
 > _"Without consultation, plans are frustrated, but with many counselors they succeed."_
 > — Proverbs 15:22 (LSB)
 
-A Model Context Protocol (MCP) gateway for running Claude Code, Codex, Gemini, Grok, Mistral (Vibe), Devin, and Cursor Agent CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
+**Secure local control plane for AI coding agents.**
 
-**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across registered provider CLIs.
+`llm-cli-gateway` lets supported MCP clients operate Claude Code, Codex, Gemini/Antigravity, Grok Build, Mistral Vibe, Cognition Devin, Cursor Agent, and configured HTTP API providers through one user-owned gateway while preserving native CLI sessions, local credentials, durable async jobs, validation receipts, and review workflows.
+
+**Why developers try it:** use the client you are already in to delegate work to local coding agents, scope remote execution to registered workspaces, gate risky actions, survive disconnects, and collect auditable review evidence without turning those agents into a generic chat proxy.
 
 **Current signals:** CI and security workflows pass on `main`, OpenSSF Scorecard is published, OpenSSF Best Practices is passing, releases use Sigstore signing, and the package is MIT licensed.
 
@@ -36,9 +38,9 @@ Or use directly with `npx` from an MCP client:
 
 ## What It Provides Today
 
-`llm-cli-gateway` is a single-user MCP gateway for cross-LLM validation and multi-agent coding workflows. It is more than a thin CLI wrapper:
+`llm-cli-gateway` is a single-user MCP control plane for operating AI coding agents from supported local or remote clients. It is more than a thin CLI wrapper:
 
-- Runs registered provider CLIs through consistent sync and async MCP tools.
+- Runs registered provider CLIs and configured HTTP API providers through consistent sync and async MCP tools.
 - Persists long-running jobs, supports restart-safe result collection, deduplication, cancellation, and sync-to-async deferral.
 - Tracks sessions, real CLI resume paths, structured response metadata, and cache telemetry.
 - Supports cache-aware `promptParts`, including explicit Claude `cache_control` when opted in.
@@ -51,7 +53,7 @@ Or use directly with `npx` from an MCP client:
 
 The repo ships agent-ready workflow skills under [`.agents/skills`](.agents/skills) for async orchestration, session continuity, multi-LLM review, implement-review-fix loops, and secure approval-gated dispatch. Six caller-facing skills are bundled in the published npm package: `async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, and `public-demo-session`. Machine-readable DAG-TOML plans live under [`docs/plans`](docs/plans) and [`setup/install-plan.dag.toml`](setup/install-plan.dag.toml) for workflows that need deterministic sequencing and verification gates.
 
-The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI: Claude, Codex, Gemini, Grok, and Mistral Vibe. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
+The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI and API-provider family: Claude, Codex, Gemini/Antigravity, Grok, Mistral Vibe, Devin, Cursor Agent, OpenAI-compatible endpoints, Anthropic Messages, and xAI Responses. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks or token-env checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
 
 ## Trust & Supply Chain
 
@@ -61,13 +63,13 @@ The next documentation focus is provider-specific skill and DAG-TOML pairs for e
 - CI runs build, lint, format, tests, package checks, and npm audit.
 - Security CI runs actionlint, zizmor, shellcheck, typos, osv-scanner, gitleaks, and lychee.
 - GitHub release installer artifacts are checksummed and signed with Sigstore keyless signing.
-- npm releases use provenance through OIDC trusted publishing.
+- npm releases use a generated prod-only shrinkwrap and release security audit; the publish token is fetched at runtime from Azure Key Vault through GitHub OIDC to Entra.
 - The npm package intentionally ships a generated, prod-only `npm-shrinkwrap.json` so registry installs resolve the audited release tree. Release gates regenerate it from `package-lock.json`, compare for parity, and run a registry-fidelity consumer install before publishing.
 - Socket behavioural alerts are documented in [`socket.yml`](./socket.yml) and under "Security Considerations" below. `shellAccess` and `shrinkwrap` are reviewed package capabilities/configuration for this CLI appliance, not hidden install behaviour.
 
 ## Personal MCP Appliance
 
-The personal-appliance contract keeps that surface intentionally narrow: one trusted user runs the gateway on a machine or volume they own, connects one MCP endpoint, and asks any connected client for cross-LLM validation.
+The personal-appliance contract keeps that surface intentionally narrow: one trusted user runs the gateway on a machine or volume they own, connects one MCP endpoint, and lets supported clients operate local coding agents through workspace-scoped, approval-gated, auditable requests.
 
 The product contract is documented in [docs/personal-mcp/PRODUCT_CONTRACT.md](docs/personal-mcp/PRODUCT_CONTRACT.md). It defines the single-user scope, security posture, target support matrix, and provider-support verification gates. Public setup guides must not claim ChatGPT, Claude web, Claude Desktop, Codex, Gemini CLI, Gemini web, or Grok inbound support until the corresponding provider/client path has been verified.
 
@@ -190,15 +192,15 @@ Every `*_request` and `*_request_async` tool except `devin_request` / `devin_req
 
 Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for all providers except Devin and Cursor, which have no `promptParts` surface; explicit levers are provider-specific):
 
-| CLI     | Prefix discipline | Explicit lever(s) |
-| ------- | ----------------- | ----------------- |
+| CLI     | Prefix discipline | Explicit lever(s)                                                                                                                      |
+| ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | claude  | yes               | `promptParts.cacheControl` + `outputFormat: "stream-json"` (Anthropic `cache_control` breakpoints on stable blocks; `ttl="1h"` forced) |
-| codex   | yes               | none (OpenAI implicit) |
-| gemini  | yes               | none (implicit server-side) |
-| grok    | yes               | `compactionMode` / `compactionDetail` (context compaction: `summary|transcript|segments`; `segments` writes per-segment markdown) |
-| mistral | yes               | none (implicit) |
-| devin   | no                | plain `prompt` only |
-| cursor  | no                | plain `prompt` only |
+| codex   | yes               | none (OpenAI implicit)                                                                                                                 |
+| gemini  | yes               | none (implicit server-side)                                                                                                            |
+| grok    | yes               | `compactionMode` / `compactionDetail` (context compaction: `summary                                                                    | transcript | segments`; `segments` writes per-segment markdown) |
+| mistral | yes               | none (implicit)                                                                                                                        |
+| devin   | no                | plain `prompt` only                                                                                                                    |
+| cursor  | no                | plain `prompt` only                                                                                                                    |
 
 **Claude example (explicit cacheControl)**
 
@@ -208,10 +210,10 @@ claude_request({
     system: "You are a helpful code reviewer.",
     context: "<long stable file dump>",
     task: "Review the diff.",
-    cacheControl: { system: true, context: true }  // task is never marked
+    cacheControl: { system: true, context: true }, // task is never marked
   },
-  outputFormat: "stream-json"
-})
+  outputFormat: "stream-json",
+});
 ```
 
 Gateway emits the `stream-json` stdin path with `cache_control: {type:"ephemeral", ttl:"1h"}` on marked blocks only.
@@ -222,8 +224,8 @@ Gateway emits the `stream-json` stdin path with `cache_control: {type:"ephemeral
 grok_request({
   promptParts: { system: "...", context: "...", task: "..." },
   compactionMode: "segments",
-  compactionDetail: "balanced"
-})
+  compactionDetail: "balanced",
+});
 ```
 
 Emits `--compaction-mode segments --compaction-detail balanced`.
@@ -249,6 +251,26 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 - **Type Safety**: Strict TypeScript with comprehensive error handling
 - **Supply-chain hardening**: a dedicated `.github/workflows/security.yml` runs actionlint, zizmor, shellcheck, typos, osv-scanner, gitleaks, and lychee on every push and PR (see `SECURITY.md` for the threat model)
 
+## Provider capability surface
+
+Every provider is reachable through the same request, session, job, and validation machinery, but the underlying CLIs differ in what they natively expose. The table records what actually shipped per provider; discover the live surface at runtime with `provider_tool_capabilities`, `list_models`, and the `provider-acp://<provider>` / `provider-tools://<provider>` resources.
+
+| Provider | CLI request tools | Native ACP | Live model discovery | Admin surface |
+| --- | --- | --- | --- | --- |
+| Claude Code (`claude`) | `claude_request` / `_async` | None (CLI-first; no ACP entrypoint at claude 2.1.198) | model aliases, reasoning-effort levels, fallback model | read-only via `provider_admin_list` / `provider_admin_run` |
+| OpenAI Codex (`codex`) | `codex_request` / `_async`, `codex_fork_session` | None (codex-cli 0.142.4 advertises mcp-server / app-server transports, not native ACP) | `codex debug models` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Gemini / Antigravity (`gemini`, `agy`) | `gemini_request` / `_async` | None (agy 1.0.14 exposes no ACP entrypoint; legacy Gemini CLI ACP evidence does not transfer) | `agy models` | read-only via `provider_admin_list` / `provider_admin_run` |
+| xAI Grok (`grok`) | `grok_request` (sync `transport: "acp"`) / `_async` | Native via `grok agent stdio` | `grok models` + `~/.grok/config.toml` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Mistral Vibe (`mistral`) | `mistral_request` (sync `transport: "acp"`) / `_async` | Native via `vibe-acp` | Vibe config plus the `VIBE_ACTIVE_MODEL` active model and agent profiles | read-only via `provider_admin_list` / `provider_admin_run` |
+| Cognition Devin (`devin`) | `devin_request` (sync `transport: "acp"`, `agentType: summarizer\|review`) / `_async` | Native via `devin acp` | `--model` / `DEVIN_MODEL` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Cursor Agent (`cursor`) | `cursor_request` (sync `transport: "acp"`) / `_async` | Native via `cursor-agent acp` (companion-owned) | model aliases | read-only via `provider_admin_list` / `provider_admin_run` |
+
+- **Native ACP** is reported honestly. `grok`, `mistral`, `devin`, and `cursor` expose a native ACP entrypoint, so `provider-acp://<provider>` carries the negotiated `initialize` capability set and the derived session-method availability, and the sync `*_request` accepts `transport: "acp"` (fails closed unless `[acp]` and the provider's `runtime_enabled` gate are set). ACP routing is sync-only: the `*_request_async` variants always run the CLI transport and do not accept `transport: "acp"` (nor Devin's `agentType`); async ACP parity is a later phase. `claude`, `codex`, and `gemini` have no native ACP entrypoint at their target CLI versions; their `provider-acp://` records report `native: false` with no methods and no adapter-as-native masquerade, and they expose no `transport: "acp"` selector.
+- **Resources** are generated from the provider registry for every CLI provider: `models://<provider>`, `sessions://<provider>`, `provider-acp://<provider>`, `provider-tools://<provider>`, and `provider-subcommands://<provider>`.
+- **Model discovery** is live and account-aware: the discovery listed above reaches `models://<provider>` and `list_models`, degrading to static registry facts when a live probe is unavailable (a resource read never spawns a CLI).
+- **Admin surfaces** are discovery-driven and output-redacted. `provider_admin_list` and `provider_admin_run` are read-only for every provider. State-mutating admin operations are exposed only through `provider_admin_mutate`, gated behind `[admin] allow_mutating_cli_admin_ops`, the remote `cli:admin` scope, an approval gate, and an audit record. Mutating ACP session operations are likewise gated behind `[acp] allow_mutating_session_ops`.
+- **Validation** commands work across every provider: `validate_with_models`, `second_opinion`, `compare_answers`, `red_team_review`, `consensus_check`, `ask_model`, and `synthesize_validation`, with durable signed receipts via `validation_receipt` and the `validation-receipt://{validationId}` resource.
+
 ## 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.
@@ -389,7 +411,7 @@ The personal-appliance surface exposes simplified validation tools for non-devel
 - `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.
-- `validation_receipt`: retrieve the immutable receipt of a terminal cross-LLM validation run by `validationId` (returns `minted | pending | expired_unminted | not_found`, own-or-not-found). `format: "markdown"` renders a human-readable report; `includeRawResponses` inlines provider answer text. Registered only under the durable persistence gate (`backend = "sqlite"` with an attached validation-run store).
+- `validation_receipt`: retrieve the immutable receipt of a terminal cross-LLM validation run by `validationId` (returns `minted | pending | expired_unminted | not_found`, own-or-not-found). `format: "markdown"` renders a human-readable report; `includeRawResponses` inlines provider answer text. Registered only when the attached job store provides the durable validation-run store capability (`sqlite` and `postgres`).
 
 The same receipt is also exposed as the `validation-receipt://{validationId}` MCP resource (same durable gate and own-or-not-found owner scoping).
 
@@ -574,6 +596,7 @@ Execute a Grok CLI (xAI) request with session support.
 
 - `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`)
+- `transport` (string, optional): `"cli"` (default) runs the Grok CLI; `"acp"` routes through Grok's native `grok agent stdio` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `grok_request_async` always runs the CLI transport and does not accept `transport`
 - `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`)
@@ -636,7 +659,7 @@ Every async job is persisted to a job store as it transitions through running
 
 - **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 collect 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.
+- **A job is marked `orphaned` only when its owning gateway instance is provably gone**, never because another instance restarted. Each instance holds a periodic heartbeat lease and stamps every job it owns; the recovery sweep orphans a `queued`/`running` job only when that job's own lease has expired. On a shared store (`backend = "postgres"`) this means a fresh instance never orphans another live instance's in-flight jobs. The captured partial output of a genuinely orphaned job remains readable, and a stale-then-reviving owner that later finishes self-heals to the correct terminal state (issue #139).
 - **Pass `forceRefresh: true`** on any request tool to bypass dedup and force a fresh CLI run.
 
 ##### Persistence configuration
@@ -647,17 +670,29 @@ The job-store backend is configured by `~/.llm-cli-gateway/config.toml` (overrid
 [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)
+# dsn = "postgresql://user:pw@host/db"      # for postgres
 retentionDays = 30
 dedupWindowMs = 3600000
 acknowledgeEphemeral = false                # required to enable async tools with memory backend
+
+# Issue #139 durable orphan-recovery lease (defaults shown). Each instance
+# advances a per-job lease on every heartbeat; the sweep orphans a job only
+# after its own lease expires, so a fresh instance never orphans another live
+# instance's jobs on a shared store. Validated: leaseTtl >= 2*heartbeat and
+# httpJobGrace >= leaseTtl.
+instanceHeartbeatMs = 15000                 # heartbeat cadence
+instanceLeaseTtlMs = 90000                  # per-job lease TTL (6x heartbeat)
+httpJobGraceMs = 300000                     # extra grace for no-pid http jobs (5 min)
+orphanSweepIntervalMs = 30000               # reaper cadence
+instanceGcMs = 3600000                      # gateway_instances GC horizon
+# ownsOrphanRecovery = false                # DEPRECATED (#139): superseded by the lease; parsed + warned, no longer used
 ```
 
 Backends:
 
 - **`sqlite`** (default) — durable, file-backed. Safe for single-instance deployments.
+- **`postgres`** — durable PostgreSQL-backed async job, dedup, orphan recovery, HTTP job, and validation receipt storage. Use this for multi-instance or service deployments. Requires the optional peer dependency `pg` to be installed alongside the gateway.
 - **`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):
@@ -922,6 +957,7 @@ consumes       = ["OUT:mcp-reconnected"]
 Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but with Vibe's specific surface:
 
 - `model` (string, optional): Vibe model alias (for example `mistral-medium-3.5` or `latest`). The resolved value is injected via the `VIBE_ACTIVE_MODEL` environment variable; omit it to let the gateway discover Vibe config and avoid stale hardcoded defaults.
+- `transport` (string, optional): `"cli"` (default) runs the Vibe CLI; `"acp"` routes through Vibe's native `vibe-acp` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `mistral_request_async` always runs the CLI transport and does not accept `transport`
 - `permissionMode`: the Vibe `--agent` name — builtins `default | plan | accept-edits | auto-approve`, or any install-gated/custom agent. Emitted as `--agent <name>`. Defaults to `auto-approve` in programmatic mode.
 - `allowedTools` (string[], optional): One `--enabled-tools <tool>` flag per entry (allow-list only).
 - `disallowedTools` (string[], optional): Accepted for parity with the other providers; ignored at the CLI boundary with a logged warning.
@@ -951,7 +987,8 @@ Run a Cognition Devin CLI request synchronously (headless print mode, `devin -p`
 
 - `prompt` (string, optional*): Prompt text for Devin CLI (1-100,000 chars). Required in practice; `promptFile` is additive
 - `model` (string, optional): Model name or alias (e.g. `opus`, `latest`)
-- `transport` (string, optional): `"cli"` (default) runs the Devin CLI; `"acp"` routes through `devin acp` when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise)
+- `transport` (string, optional): `"cli"` (default) runs the Devin CLI; `"acp"` routes through Devin's native `devin acp` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `devin_request_async` always runs the CLI transport and accepts neither `transport` nor `agentType`
+- `agentType` (string, optional): ACP agent variant for `transport: "acp"` (`devin acp --agent-type`): `"summarizer"` (no tools, text summary) or `"review"` (read-only plus shell code-review); ignored for the CLI transport
 - `permissionMode` (string, optional): Devin CLI permission mode (`--permission-mode`): `auto` (auto-approves read-only tools), `smart` (also auto-runs actions a fast model judges safe), `dangerous` (auto-approves all). Omit to use Devin's headless default
 - `promptFile` (string, optional): Load the initial prompt from a file (`--prompt-file`)
 - `sessionId` (string, optional): Devin session ID to resume (`--resume <id>`). The `gw-*` id minted for a brand-new session is not resumable via `sessionId`; continue with `resumeLatest: true`
@@ -972,7 +1009,7 @@ Run a Cursor Agent CLI request synchronously. Defaults to headless print mode (`
 - `model` (string, optional): Model name or alias (for example `gpt-5`, `sonnet-4-thinking`, or `latest`)
 - `mode` (string, optional): Cursor mode, `"plan"` or `"ask"` (`--mode`)
 - `outputFormat` (string, optional): `"text"` (default), `"json"`, or `"stream-json"`
-- `transport` (string, optional): `"cli"` (default) or `"acp"`; ACP fails closed unless enabled in gateway config and rejects unsupported Cursor CLI-only controls instead of dropping them
+- `transport` (string, optional): `"cli"` (default) or `"acp"`; ACP fails closed unless enabled in gateway config and rejects unsupported Cursor CLI-only controls instead of dropping them. Sync-only: `cursor_request_async` always runs the CLI transport and does not accept `transport`
 - `force` (boolean, optional): Emit `--force` for non-interactive operation
 - `autoReview` (boolean, optional): Emit `--auto-review`
 - `sandbox` (string, optional): `"enabled"` or `"disabled"` (`--sandbox`)
@@ -1317,7 +1354,7 @@ The API key value is never emitted on any of these surfaces (only the env var na
 
 ### Security note
 
-The resolved API key is excluded from `payloadJson`, the dedup key, logs, and the flight recorder. However, the **request prompt is persisted in plaintext** in the async job store (the SQLite file at `[persistence].path`, default `~/.llm-cli-gateway/logs.db`) and is not covered by secret redaction. This mirrors the CLI tools, whose prompt is persisted in `argsJson` whenever it is passed as a command argument (a few CLI paths instead stream the prompt over stdin and so do not persist it). Treat the job store as sensitive at rest. See [Security Considerations](#security-considerations).
+The resolved API key is excluded from `payloadJson`, the dedup key, logs, and the flight recorder. However, the **request prompt is persisted in plaintext** in the async job store (SQLite at `[persistence].path`, default `~/.llm-cli-gateway/logs.db`, or Postgres rows under `backend = "postgres"`) and is not covered by secret redaction. This mirrors the CLI tools, whose prompt is persisted in `argsJson` whenever it is passed as a command argument (a few CLI paths instead stream the prompt over stdin and so do not persist it). Treat the job store as sensitive at rest. See [Security Considerations](#security-considerations).
 
 ## Session Management
 
@@ -1384,9 +1421,11 @@ await callTool("session_delete", {
   - **Gemini (Antigravity)** → `default` / prompted, i.e. **no** `--dangerously-skip-permissions` (the `agy` CLI has no accept-edits middle rung, so the safe default is prompted execution; without the opt-in, Gemini cannot auto-approve mutating tools under `mcp_managed`)
 
   Set to `1`/`true` to let the operator opt back in: this permits bypass requests through the approval gate **and** restores each provider's full auto-approve mode under `mcp_managed` (Claude `bypassPermissions`, Grok `--always-approve`, Mistral `--agent auto-approve`, Gemini `--dangerously-skip-permissions`). Sandboxed auto modes (e.g. codex `--sandbox workspace-write`) are unaffected.
+
   ```bash
   LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1 node dist/index.js
   ```
+
 - `LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER`: Name of an HTTP header carrying the authenticated user identity asserted by a **trusted front door** (any identity-aware reverse proxy / IdP). When set, the gateway adopts that header value as the request's ownership principal — but **only** for requests authenticated with the gateway's own static bearer token (i.e. the trusted upstream proxy), never from an arbitrary remote client. Off by default; IdP-agnostic. Lets a proxy-fronted multi-user deployment carry per-user identity into the gateway.
   ```bash
   LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER=x-gateway-principal node dist/index.js
@@ -1575,11 +1614,11 @@ The gateway supports concurrent requests across different CLIs. Each request spa
 
 - **Input Validation**: All prompts are validated (min 1 char, max 100k chars)
 - **API-provider keys**: For `[providers.<name>]` HTTP providers, the gateway reads the key from the named environment variable at request time only. The resolved key is excluded from the persisted `payloadJson`, the dedup key, logs, and the flight recorder, and is never surfaced on the discovery/diagnostic surfaces (which report only the env var name and a presence boolean). `base_url` userinfo is redacted on the diagnostic surfaces. See [API providers (HTTP)](#api-providers-http).
-- **Prompt persistence at rest**: Async job rows store the request **prompt in plaintext** (HTTP `payloadJson`, and CLI `argsJson` whenever the prompt is passed as a command argument rather than streamed over stdin); this is not covered by secret redaction. The SQLite job-store file (default `~/.llm-cli-gateway/logs.db`, configurable via `[persistence].path`) is `chmod`ed to `0o600` on non-Windows hosts; treat it as sensitive and scope/rotate it like any prompt log. Set `[persistence].backend = "none"` to disable the async job store entirely (the `*_request_async` / `llm_job_*` tools are then not registered).
+- **Prompt persistence at rest**: Async job rows store the request **prompt in plaintext** (HTTP `payloadJson`, and CLI `argsJson` whenever the prompt is passed as a command argument rather than streamed over stdin); this is not covered by secret redaction. The SQLite job-store file (default `~/.llm-cli-gateway/logs.db`, configurable via `[persistence].path`) is `chmod`ed to `0o600` on non-Windows hosts; the Postgres backend stores the same fields in database rows. Treat either backend as sensitive and scope/rotate it like any prompt log. Set `[persistence].backend = "none"` to disable the async job store entirely (the `*_request_async` / `llm_job_*` tools are then not registered).
 - **Command Execution**: Uses `spawn` with separate arguments (not shell execution)
 - **No Eval**: No dynamic code evaluation in our source (see "Socket alerts" below for the transitive `ajv` codegen case)
 - **Sandboxing**: Consider running in containers for production use
-- **Provenance**: Releases are published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via OIDC trusted publishing from GitHub Actions
+- **npm publish control**: npm releases are gated by the generated prod-only shrinkwrap, release security audit, packed-consumer checks, and a publish token fetched at runtime from Azure Key Vault through GitHub OIDC to Entra
 - **Release signing**: GitHub release installer artifacts are signed with Sigstore keyless signing; verify `SHA256SUMS.sigstore.json` before trusting the checksum file
 
 ### Socket alerts — context for reviewers

package/dist/acp/client.d.ts

@@ -1,6 +1,6 @@
 import { AcpError } from "./errors.js";
 import type { JsonRpcStdioTransport, JsonRpcId } from "./json-rpc-stdio.js";
-import { type ContentBlock, type InitializeResponse, type ReadTextFileRequest, type ReadTextFileResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionLoadResponse, type SessionNewResponse, type SessionPromptResponse, type SessionUpdateNotification, type WriteTextFileRequest, type WriteTextFileResponse } from "./types.js";
+import { type CloseSessionResponse, type ContentBlock, type DeleteSessionResponse, type InitializeResponse, type ListSessionsResponse, type ReadTextFileRequest, type ReadTextFileResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionLoadResponse, type SessionNewResponse, type SessionPromptResponse, type SessionResumeResponse, type SessionUpdateNotification, type SetSessionConfigOptionResponse, type SetSessionModeResponse, type WriteTextFileRequest, type WriteTextFileResponse } from "./types.js";
 import type { Logger } from "../logger.js";
 import type { CliType } from "../session-manager.js";
 export declare const DEFAULT_ACP_PROTOCOL_VERSION = 1;
@@ -25,6 +25,7 @@ export interface AcpClientOptions {
     readonly logger?: Logger;
     readonly protocolVersion?: number;
     readonly timeouts?: AcpClientTimeouts;
+    readonly allowMutatingSessionOps?: boolean;
 }
 export interface AcpClientTimeouts {
     readonly initializeMs?: number;
@@ -48,6 +49,18 @@ export interface PromptParams {
     readonly sessionId: string;
     readonly prompt: ReadonlyArray<ContentBlock>;
 }
+export interface ResumeSessionParams extends NewSessionParams {
+    readonly sessionId: string;
+}
+export interface SetSessionModeParams {
+    readonly sessionId: string;
+    readonly modeId: string;
+}
+export interface SetSessionConfigOptionParams {
+    readonly sessionId: string;
+    readonly configId: string;
+    readonly value: string;
+}
 export declare class AcpClient {
     private readonly transport;
     private readonly provider;
@@ -56,16 +69,31 @@ export declare class AcpClient {
     private readonly logger;
     private readonly protocolVersion;
     private readonly timeouts;
+    private readonly allowMutatingSessionOps;
     private initialized;
     private initializeResult;
+    private methodAvailability;
+    private static readonly MUTATING_METHODS;
     constructor(options: AcpClientOptions);
     get isInitialized(): boolean;
     get agentInfo(): InitializeResponse | null;
+    get availableMethods(): ReadonlySet<string>;
+    supportsMethod(method: string): boolean;
     initialize(options?: InitializeOptions): Promise<InitializeResponse>;
     newSession(params: NewSessionParams): Promise<SessionNewResponse>;
     loadSession(params: LoadSessionParams): Promise<SessionLoadResponse>;
     prompt(params: PromptParams): Promise<SessionPromptResponse>;
     cancel(sessionId: string): void;
+    resumeSession(params: ResumeSessionParams): Promise<SessionResumeResponse>;
+    listSessions(params?: {
+        cursor?: string;
+    }): Promise<ListSessionsResponse>;
+    closeSession(sessionId: string): Promise<CloseSessionResponse>;
+    deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
+    setSessionMode(params: SetSessionModeParams): Promise<SetSessionModeResponse>;
+    setSessionConfigOption(params: SetSessionConfigOptionParams): Promise<SetSessionConfigOptionResponse>;
+    private augmentSessionMethods;
+    private assertMethodAvailable;
     private send;
     private normalizeError;
     private assertInitialized;

package/dist/acp/client.js

@@ -1,5 +1,5 @@
-import { AcpProtocolError, isAcpError } from "./errors.js";
-import { parseInitializeResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionUpdateNotification, parseWriteTextFileRequest, } from "./types.js";
+import { AcpMethodUnsupportedError, AcpMutatingDisabledError, AcpProtocolError, isAcpError, } from "./errors.js";
+import { deriveAcpMethodAvailability, parseCloseSessionResponse, parseDeleteSessionResponse, parseInitializeResponse, parseListSessionsResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionResumeResponse, parseSessionUpdateNotification, parseSetSessionConfigOptionResponse, parseSetSessionModeResponse, parseWriteTextFileRequest, sessionResponseMethods, } from "./types.js";
 import { noopLogger } from "../logger.js";
 export const DEFAULT_ACP_PROTOCOL_VERSION = 1;
 export class AcpClient {
@@ -10,8 +10,15 @@ export class AcpClient {
     logger;
     protocolVersion;
     timeouts;
+    allowMutatingSessionOps;
     initialized = false;
     initializeResult = null;
+    methodAvailability = new Set();
+    static MUTATING_METHODS = new Set([
+        "session/delete",
+        "session/set_mode",
+        "session/set_config_option",
+    ]);
     constructor(options) {
         this.transport = options.transport;
         this.provider = options.provider;
@@ -20,6 +27,7 @@ export class AcpClient {
         this.logger = options.logger ?? noopLogger;
         this.protocolVersion = options.protocolVersion ?? DEFAULT_ACP_PROTOCOL_VERSION;
         this.timeouts = options.timeouts ?? {};
+        this.allowMutatingSessionOps = options.allowMutatingSessionOps ?? false;
     }
     get isInitialized() {
         return this.initialized;
@@ -27,6 +35,12 @@ export class AcpClient {
     get agentInfo() {
         return this.initializeResult;
     }
+    get availableMethods() {
+        return new Set(this.methodAvailability);
+    }
+    supportsMethod(method) {
+        return this.methodAvailability.has(method);
+    }
     async initialize(options = {}) {
         if (this.initialized && this.initializeResult) {
             return this.initializeResult;
@@ -45,12 +59,15 @@ export class AcpClient {
         const result = parseInitializeResponse(raw, this.provider);
         this.initialized = true;
         this.initializeResult = result;
+        this.methodAvailability = new Set(deriveAcpMethodAvailability(result));
         return result;
     }
     async newSession(params) {
         this.assertInitialized("session/new");
         const raw = await this.send("session/new", { cwd: params.cwd, mcpServers: params.mcpServers ?? [] }, this.timeouts.sessionNewMs);
-        return parseSessionNewResponse(raw, this.provider);
+        const response = parseSessionNewResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
     }
     async loadSession(params) {
         this.assertInitialized("session/load");
@@ -59,7 +76,9 @@ export class AcpClient {
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
         }, this.timeouts.sessionLoadMs);
-        return parseSessionLoadResponse(raw, this.provider);
+        const response = parseSessionLoadResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
     }
     async prompt(params) {
         this.assertInitialized("session/prompt");
@@ -69,6 +88,61 @@ export class AcpClient {
     cancel(sessionId) {
         this.transport.notify("session/cancel", { sessionId });
     }
+    async resumeSession(params) {
+        this.assertMethodAvailable("session/resume");
+        const raw = await this.send("session/resume", { sessionId: params.sessionId, cwd: params.cwd, mcpServers: params.mcpServers ?? [] }, this.timeouts.sessionLoadMs);
+        const response = parseSessionResumeResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
+    }
+    async listSessions(params = {}) {
+        this.assertMethodAvailable("session/list");
+        const raw = await this.send("session/list", { cursor: params.cursor });
+        return parseListSessionsResponse(raw, this.provider);
+    }
+    async closeSession(sessionId) {
+        this.assertMethodAvailable("session/close");
+        const raw = await this.send("session/close", { sessionId });
+        return parseCloseSessionResponse(raw, this.provider);
+    }
+    async deleteSession(sessionId) {
+        this.assertMethodAvailable("session/delete");
+        const raw = await this.send("session/delete", { sessionId });
+        return parseDeleteSessionResponse(raw, this.provider);
+    }
+    async setSessionMode(params) {
+        this.assertMethodAvailable("session/set_mode");
+        const raw = await this.send("session/set_mode", {
+            sessionId: params.sessionId,
+            modeId: params.modeId,
+        });
+        return parseSetSessionModeResponse(raw, this.provider);
+    }
+    async setSessionConfigOption(params) {
+        this.assertMethodAvailable("session/set_config_option");
+        const raw = await this.send("session/set_config_option", {
+            sessionId: params.sessionId,
+            configId: params.configId,
+            value: params.value,
+        });
+        return parseSetSessionConfigOptionResponse(raw, this.provider);
+    }
+    augmentSessionMethods(response) {
+        for (const method of sessionResponseMethods(response)) {
+            this.methodAvailability.add(method);
+        }
+    }
+    assertMethodAvailable(method) {
+        this.assertInitialized(method);
+        if (!this.methodAvailability.has(method)) {
+            throw new AcpMethodUnsupportedError(this.provider, method, {
+                reason: "capability_not_advertised",
+            });
+        }
+        if (AcpClient.MUTATING_METHODS.has(method) && !this.allowMutatingSessionOps) {
+            throw new AcpMutatingDisabledError(this.provider, method, { reason: "config_gate_off" });
+        }
+    }
     async send(method, params, timeoutMs) {
         try {
             return await this.transport.request(method, params, timeoutMs);

package/dist/acp/errors.d.ts

@@ -1,5 +1,5 @@
 import type { CliType } from "../session-manager.js";
-export type AcpErrorKind = "acp_disabled" | "provider_acp_disabled" | "provider_acp_unsupported" | "provider_runtime_disabled" | "provider_unavailable" | "protocol" | "timeout" | "permission_denied" | "process_exit";
+export type AcpErrorKind = "acp_disabled" | "provider_acp_disabled" | "provider_acp_unsupported" | "provider_runtime_disabled" | "provider_unavailable" | "method_unsupported" | "mutating_disabled" | "protocol" | "timeout" | "permission_denied" | "process_exit";
 export declare function redactAcpMessage(input: string): string;
 export declare function redactAcpDebug(value: unknown): unknown;
 export declare function redactAcpCause(cause: unknown): unknown;
@@ -32,6 +32,14 @@ export declare class ProviderRuntimeDisabledError extends AcpError {
 export declare class ProviderUnavailableError extends AcpError {
     constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
 }
+export declare class AcpMethodUnsupportedError extends AcpError {
+    readonly method: string;
+    constructor(provider: CliType, method: string, debug?: AcpErrorDebug);
+}
+export declare class AcpMutatingDisabledError extends AcpError {
+    readonly method: string;
+    constructor(provider: CliType, method: string, debug?: AcpErrorDebug);
+}
 export declare class AcpProtocolError extends AcpError {
     readonly code?: number;
     constructor(userMessage: string, options?: {