saros-proxy 0.10.2 → 1.0.0

package/README.md

@@ -44,51 +44,55 @@ Manage multiple API keys behind a single endpoint — OpenCode-Go **and** Comman
 - **Graceful shutdown** — Drains active requests before exiting (no dropped connections).
 - **Security hardening** — API key masking in logs, SSRF prevention (HTTPS-only upstream), configurable CORS, host binding validation.
 - **Config validation** — CLI args, YAML file, or environment variables with sensible defaults.
-- **Health endpoint** — `GET /health` shows key status, active requests, and circuit-breaker state.
+- **Health endpoint** — `GET /health` shows key status per key (enabled, why it is out of rotation, when it retries), active requests, and circuit-breaker state.
+- **Request forensics** — `X-Proxy-Provider` / `X-Proxy-Key-Label` / `X-Proxy-Request-Id` headers on served responses, plus `GET /debug/recent` (last 200 requests in memory, no credentials).
 - **No database** — Stateless proxy, zero external dependencies beyond Node.js.
 
 ---
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     Your App / OpenCode                     │
-│                                                             │
-│   ┌──────────┐   ┌──────────┐   ┌──────────┐                │
-│   │ Request 1│   │ Request 2│   │ Request 3│    ...         │
-│   └────┬─────┘   └────┬─────┘   └────┬─────┘                │
-└────────┼──────────────┼──────────────┼──────────────────────┘
-         │              │              │
-         └──────────────┼──────────────┘
-                        │
-                        ▼
-┌─────────────────────────────────────────────────────────────┐
-│                       Saros (:3000)                         │
-│                                                             │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
-│  │ Key Selector │─▶│   Circuit    │─▶│   Request   │       │
-│  │ Round-Robin  │  │   Breaker    │  │   Forwarder  │       │
-│  │ + Failover   │  │ Threshold +  │  │ + Timeout +  │       │
-│  │              │  │   Cooldown   │  │     SSE      │       │
-│  └──────────────┘  └──────────────┘  └──────┬───────┘       │
-└─────────────────────────────────────────────┼───────────────┘
-                                              │
-                                  ┌───────────┼───────────┐
-                                  ▼           ▼           ▼
-                           ┌──────────┐ ┌──────────┐ ┌──────────┐
-                           │  Key A   │ │  Key B   │ │  Key C   │
-                           │ sk-abc…  │ │ sk-def…  │ │ user_…   │
-                           └────┬─────┘ └────┬─────┘ └────┬─────┘
-                                │            │            │
-                                └────────────┼────────────┘
-                                             │
-                       ┌─────────────────────┴─────────────────────┐
-                       ▼                                           ▼
-              ┌───────────────────────┐                  ┌──────────────────────────┐
-              │      OpenCode-Go API  │                  │      CommandCode API     │
-              │    https://opencode.ai│                  │ https://api.commandcode.ai│
-              └───────────────────────┘                  └──────────────────────────┘
+```mermaid
+flowchart TB
+    subgraph client["Your App / OpenCode"]
+        direction LR
+        r1["Request 1"]
+        r2["Request 2"]
+        r3["Request 3"]
+        rest["..."]
+    end
+
+    subgraph saros["Saros :3000"]
+        direction LR
+        ks["Key Selector<br/>round-robin + failover"]
+        cb["Circuit Breaker<br/>threshold + cooldown"]
+        fw["Request Forwarder<br/>timeout + SSE"]
+        ks --> cb --> fw
+    end
+
+    subgraph keys["API keys"]
+        direction LR
+        ka["Key A<br/>sk-abc…"]
+        kb["Key B<br/>sk-def…"]
+        kc["Key C<br/>user_…"]
+    end
+
+    oc["OpenCode-Go API<br/>opencode.ai"]
+    cc["CommandCode API<br/>api.commandcode.ai"]
+
+    r1 --> ks
+    r2 --> ks
+    r3 --> ks
+    rest --> ks
+    fw --> ka
+    fw --> kb
+    fw --> kc
+    ka --> oc
+    kb --> oc
+    kc --> oc
+    ka --> cc
+    kb --> cc
+    kc --> cc
 ```
 
 ### How Request Distribution Works
@@ -97,13 +101,46 @@ Here's how Saros picks which API key to use:
 
 #### Usage-Weighted Rotation
 
-Saros polls the upstream usage API for each key (5h / weekly / monthly windows)
-and weights rotation by **remaining** quota. If key X is 30% used and key Y is
-70% used, 10 requests are distributed 7 → X and 3 → Y — proportional balancing,
-not hard cutoffs, so neither key absorbs the full load when the other runs low.
+Saros polls each key's quota endpoint and weights rotation by **remaining
+monthly** quota. If key X is 30% into its monthly allowance and key Y is 70%,
+10 requests are distributed 7 → X and 3 → Y — proportional balancing, not hard
+cutoffs, so neither key absorbs the full load when the other runs low.
+
+The number Saros compares is always a percentage of that key's **own provider
+monthly budget**, never absolute capacity:
+
+| provider | endpoint | what it reports |
+| --- | --- | --- |
+| OpenCode Go | `GET /zen/go/v1/usage` | `rolling` (5h) / `weekly` / `monthly` as percents |
+| CommandCode | `GET /alpha/billing/credits` | `fiveHour` and `weekly` as `used`/`cap` in credits, `credits.monthlyCredits` (remaining) and reset timestamps |
+
+CommandCode's payload has no explicit monthly cap. The parser **infers** it
+from the window caps (the 20% / 50% / 100% ladder is OpenCode Go's documented
+plan shape; for CommandCode the 14/35 ratio was measured against its
+dashboard): monthly cap = 2 × `weekly.cap`, falling back to 5 ×
+`fiveHour.cap` when the weekly window is absent. The candidate cap is only
+accepted when the credits agree with it — `credits.monthlyCredits <= cap` and
+`cap − monthlyCredits >= max(weekly.used, fiveHour.used)`; otherwise the
+fallback is tried and, if it also disagrees, the response is treated as
+unusable (the previous usage state is kept rather than branding a broken
+derivation as 0% usage). A payload without `monthlyCredits` reports the
+monthly metric as unavailable (`n/a` in `saros-proxy usage`). Both parsers
+emit the same 0-100 percent scale, so a mixed pool compares like with like.
+Two consequences worth knowing:
+
+- **Monthly is the weight; a spent window still excludes the key.** A key with
+  50% of the month left but a 5-hour or weekly window at 100% weighs 0 and is
+  not selected while another key has room — otherwise it would keep receiving
+  traffic and failing upstream. `/health`'s `usagePercent` is the monthly
+  number.
+- **Percent is all there is.** OpenCode Go publishes percents only — no counts,
+  no caps — so "remaining capacity" in tokens or dollars cannot be derived.
 
 - Refreshed in the background every 60s (stale data keeps working).
-- Without usage data, falls back to even round-robin.
+- Keys without usage data take the **median of the other keys' non-exhausted
+  weights**, not plain round-robin. Round-robin is only the fallback when no
+  key has usage data at all (or when every key is exhausted and a request must
+  share one).
 - A key whose account has no plan for its provider (403 `EntitlementError` /
   `upgrade_required` from the usage endpoint) is dropped from rotation without
   tripping the circuit breaker, and returns as soon as a later refresh sees it
@@ -118,14 +155,16 @@ object for non-streaming bodies — is booked against the key that served the
 request. Totals are persisted to `~/.config/saros/token-usage.json` (debounced
 atomic writes) and shown by `saros-proxy usage`.
 
-This is the only consumption signal available for providers without a
-queryable quota API (CommandCode): their keys report no percentages, but
-`saros-proxy usage` shows absolute token totals and request counts per key.
+This is the fallback signal: when a provider has no quota endpoint, or its usage
+call fails, absolute token totals and request counts per key are what
+`saros-proxy usage` can still show.
 
 #### Circuit Breaker
 
 Keys that return auth/quota errors (`401`, quota `4xx/5xx`) enter a cooldown
-and are lazily re-enabled after it expires. Timeouts and connection errors do
+and are lazily re-enabled after it expires — or immediately by a successful
+response through the same key, which happens when tier 2 shares one key between
+concurrent requests and only one of them fails. Timeouts and connection errors do
 **not** disable keys — they are shared-upstream failures, so Saros keeps
 cycling instead of locking up with "all keys unavailable".
 
@@ -283,6 +322,11 @@ Test that it's alive:
 ```bash
 curl http://127.0.0.1:3000/health
 
+# Why is a key out of rotation? The `keys` block says it (never the key itself):
+#   "keys": [{"label":"work","provider":"commandcode","enabled":false,
+#             "reason":"auth","lastError":{"status":401},
+#             "retryAfterMs":43876}]
+
 # Query models
 curl http://127.0.0.1:3000/zen/go/v1/models
 
@@ -335,10 +379,15 @@ keys:
   - label: cc-console-key
     key: sk-your-console-key-here...    # ambiguous prefix → set provider explicitly
     provider: commandcode
+  - label: old-account
+    key: sk-you...0000
+    enabled: false           # retired: kept in config, never used
 ```
 
 The `provider` field is optional — it wins over prefix inference and is required only when a CommandCode `sk-` console key must be distinguished from an OpenCode-Go key. When keys are encrypted at rest (prefix hidden), the provider from setup time is persisted alongside.
 
+The `enabled` field is optional (default `true`). Setting `enabled: false` retires a key without deleting it: it never enters rotation, is never counted as a failure, and `/health` reports it as `disabledByConfig: true` (the 503 lists it as `disabled_by_config`). A revoked key is usually better retired than deleted — the credential stays for the record and comes back with a one-word edit.
+
 **Per-provider upstream override (optional):**
 
 ```yaml
@@ -357,10 +406,11 @@ OPENCODE_GO_KEYS="account1:sk-xxx,cc:user_yyy"
 - Clients always speak the canonical OpenCode-Go shapes (`/zen/go/v1/...` or the `/v1/...` alias).
 - When a request is served by a CommandCode key, Saros remaps the route to CommandCode's OpenAI-compatible surface (`/provider/v1/...`) and injects the provider's identity headers — transparent to the client.
 - Models uniquely named by a provider (e.g. `claude-*` or vendor-prefixed ids on CommandCode) are routed to a key of that provider first; other providers remain as fallback.
-- Synced harness configs may list provider-specific models as `model@commandcode`; the suffix selects the provider and is stripped before forwarding.
-- The `/health` endpoint reports per-provider key counts under `providers`.
+- Synced harness configs may list provider-specific models as `model@commandcode`; the suffix selects the provider and is stripped before forwarding. The pin is authoritative: key selection is restricted to that provider, so a pin whose provider cannot serve the model still reaches that upstream and surfaces its error instead of a local 503.
+- The `/health` endpoint reports per-provider key counts under `providers`, and a `keys` array with each key's state: `enabled`, `entitled`, `consecutiveFailures`, `disabledAt`, `retryAfterMs`, and `lastError` (`status` + `reason`: `auth`, `quota`, `rate_limit`, `server`). The credential is never part of the response.
+- When no key can serve a request, the `503` body says which keys are out and why — `keys[]` with `reason`/`lastStatus`/`retryAfterMs`, plus a `causes[]` list (revoked key, exhausted quota, rate limit, missing plan, or a `@provider` pin with no usable key). The legacy `error` field (`All API keys are temporarily unavailable`) is still present.
 - OpenCode-Go requires a stable per-conversation session id (`x-opencode-session`, used for routing and prompt caching). Saros forwards a client-supplied value untouched and derives one from the conversation (model + first user turn) when the client sends none — harnesses that only attach the header on some request paths would otherwise get `400 MissingSessionID`.
-- Usage-based weighted rotation applies to providers with a queryable usage API (OpenCode-Go). CommandCode keys participate in rotation without usage data, but their token consumption is tracked per key and shown by `saros-proxy usage` (see [Token Accounting](#token-accounting)).
+- Usage-based weighted rotation uses each provider's queryable usage endpoint (OpenCode-Go `GET /zen/go/v1/usage`, CommandCode `GET /alpha/billing/credits`). Both contribute a monthly percentage of their own budget; token consumption stays tracked per key and shown by `saros-proxy usage` (see [Usage-Weighted Rotation](#usage-weighted-rotation) and [Token Accounting](#token-accounting)).
 
 #### Smoke test (key identification)
 
@@ -372,33 +422,100 @@ CC_KEY=user_your-token npx tsx scripts/live-identify-check.ts
 
 ### API Key Encryption
 
-Keys can be encrypted at rest using AES-256-GCM with scrypt key derivation. Encrypted keys look like `enc:scrypt:...` in `config.yaml` and get decrypted at startup using the `OPENCODE_GO_ENCRYPTION_KEY` environment variable.
+Keys can be stored as `enc:v1:` envelopes instead of plaintext. An envelope is
+`enc:v1:<salt>.<nonce>.<tag>.<ciphertext>`: scrypt (N=2^15, r=8, p=1, 32 B)
+derives an AES-256-GCM key, and the AAD binds the envelope version and the key
+label, so a ciphertext copied onto another key entry fails authentication.
+
+**Encrypt existing plaintext keys** (the old file is copied to
+`config.yaml.backup` once; a second run is a no-op; providers are inferred and
+persisted so encrypted keys still route correctly):
 
-**Setup with encryption:**
 ```bash
-npm run setup
-# Choose to encrypt keys and enter a master key (min 16 chars)
-```
+saros-proxy keys encrypt
+# or: saros-proxy keys encrypt --config /etc/saros/config.yaml
+# or: saros-proxy keys encrypt --no-backup
+```
+
+The backup is written **in plaintext** (mode 0600) on purpose: it is the
+recovery path if the passphrase is lost. Delete it after the first successful
+boot, or pass `--no-backup` to skip it. A symlinked config (dotfile setups) is
+rewritten through its real target — the link survives and the target is
+encrypted.
+
+**Cost of the KDF:** the envelope uses scrypt N=2^15, r=8, p=1 (about 32 MiB
+and ~70 ms per key on a current laptop). Boot derives the key once per
+encrypted entry, so 10 keys add roughly 0.7 s. Raising N to 2^17 (OWASP's
+recommendation) multiplies that boot cost by ~4 per key; do it only together
+with a migration, and remember that passphrase entropy — not the KDF — is what
+an offline attacker attacks first.
+
+**Passphrase sources, first match wins:**
+
+1. `SAROS_PASSPHRASE` — for systemd, Docker and CI.
+2. The OS secret store, accessed only through the platform CLI:
+   - Linux: `secret-tool lookup service saros-proxy account "$USER"`
+   - macOS: `security find-generic-password -s saros-proxy -a "$USER" -w`
+   - Windows: PowerShell DPAPI (`CurrentUser`) over
+     `%APPDATA%\saros\secret.dpapi`
+3. A hidden TTY prompt — foreground `saros-proxy serve` only, never the daemon
+   child and never when stdin is not a TTY.
 
-**Running with encrypted keys:**
 ```bash
-export OPENCODE_GO_ENCRYPTION_KEY="your-master-key"
-npx tsx src/index.ts
+saros-proxy secret set      # store the passphrase through the OS CLI
+saros-proxy secret status   # which source would win + whether the store is populated
+saros-proxy serve           # foreground; may prompt if no source is available
 ```
 
-**Docker with encrypted keys:**
-```yaml
-# docker-compose.yml
-environment:
-  - OPENCODE_GO_ENCRYPTION_KEY=your-master-key
-```
+`secret set` never writes the passphrase to a file and never prints it; it
+warns when the value is shorter than 12 characters (scrypt makes guessing
+expensive, but passphrase entropy is what actually protects the keys). On
+Linux it is stored with `secret-tool store --label="saros-proxy passphrase"
+service saros-proxy account "$USER"`; on macOS with `security
+add-generic-password -U -s saros-proxy -a "$USER" -w`; on Windows PowerShell
+`ProtectedData.Protect(..., 'CurrentUser')` writes the blob.
+
+`secret status` distinguishes an absent entry (`not found`) from an
+unavailable keyring (`keyring locked or error`), and the same reason is carried
+into the "no passphrase source" boot error — a locked keyring is not reported
+as an empty store.
+
+**systemd-creds recipe** (keeps the passphrase out of the unit file and the
+environment of the shell):
 
-**Notes:**
-- Encrypted keys use AES-256-GCM with scrypt KDF (N=16384, r=8, p=1)
-- Each key has its own random salt and IV
-- Plaintext keys (`sk-...`) still work — backward compatible
-- `OPENCODE_GO_KEYS` env var is always plaintext (for CI/CD)
-- If keys are encrypted but no `OPENCODE_GO_ENCRYPTION_KEY` is set, startup fails with a clear error
+```bash
+# One-time: encrypt stdin into a host+user-bound credential.
+systemd-creds encrypt --name=saros-passphrase --with-key=host+user \
+  /dev/stdin /etc/saros/passphrase.cred
+```
+
+```ini
+# /etc/systemd/system/saros-proxy.service
+[Service]
+LoadCredentialEncrypted=saros-passphrase:/etc/saros/passphrase.cred
+ExecStart=/bin/sh -c 'SAROS_PASSPHRASE="$(cat "$CREDENTIALS_DIRECTORY/saros-passphrase")" exec /usr/bin/saros-proxy serve'
+```
+
+**Behaviour and compatibility:**
+
+- Plaintext keys keep working; startup logs a loud warning and
+  `keys encrypt` fixes them.
+- A config with `enc:v1:` values and no available source exits `1` with a
+  message naming the three options. A wrong passphrase also exits `1` and
+  names the key label — never the key or the passphrase.
+- `GET /health` reports `"encrypted": true` per key; it never returns the
+  ciphertext or the plaintext. The flag is derived from the value being an
+  envelope — an `encrypted: true` field on a plaintext entry is stripped, so
+  the signal cannot be spoofed from YAML.
+- Legacy `enc:scrypt:` keys still decrypt with `OPENCODE_GO_ENCRYPTION_KEY`
+  (with a warning); `keys encrypt` leaves them untouched.
+- `OPENCODE_GO_KEYS` is always plaintext (CI use) and is not covered by the
+  warning.
+- Docker can pass `SAROS_PASSPHRASE` or mount a config whose passphrase comes
+  from a Docker secret; the container has no OS keyring of its own.
+
+The honest threat model — what each option protects and what it does not — is
+in [Security](#security).
 
 ### CLI Flags
 
@@ -526,9 +643,11 @@ Override with `--config`:
 saros-proxy start --port 3000 --config /path/to/config.yaml
 ```
 
-The PID file is stored at `~/.config/saros/daemon.pid`. The child process runs with `NODE_ENV=production` (JSON logging), and its stderr is appended to `~/.config/saros/daemon.log`.
+The PID file, `daemon.log` and captures live in the same directory as `config.yaml` — `~/.config/saros/` on Linux/macOS, `%LOCALAPPDATA%\saros\` on Windows. An installation started before 0.11.0 keeps its pid under `~/.config/saros`; set `SAROS_ALLOW_LEGACY_PID=1` once to stop it, or the new layout takes over on the next start. Without the flag the pre-0.11 PID file is inert — it is never read, migrated or deleted (only `stat`ed, so `stop`/`status` can name it and point at `SAROS_ALLOW_LEGACY_PID=1`) — because that path lives in the operator's real home and an isolated run (a test with a temp config dir, a throwaway container shell) must not signal a live daemon. With the flag set, a live legacy PID is read and migrated into the new directory on first use. `saros-proxy stop` removes the PID file only once the process is confirmed gone: when the kill fails it keeps the handle and exits non-zero, so the next `stop` still finds the daemon (instead of printing "no running proxy daemon" and exiting 0) and `restart` never announces a stop it could not confirm nor start over a busy port. A failed stop also names the exact file it acted on, and removing it never touches the other layout's handle. When the state dir holds no PID but a pre-0.11 one exists, `stop` says where it is and exits non-zero if something still answers `/health` on the configured port — an upgraded install cannot be reported as stopped while it still serves. The child process runs with `NODE_ENV=production` (JSON/NDJSON logging), and **both** its stdout (pino) and stderr are appended to `daemon.log` — the same descriptor for both, with no pipe whose read end the exiting launcher could take away. The file rotates at start: past 10 MB it becomes `daemon.log.1` and up to five are kept. Every boot writes an `evt:"boot"` line — version, node, config path, port, key labels/providers, bundled model count — so an empty log now means the daemon never started, not that logging is silent. When a fresh child dies during startup, `saros-proxy start` reads the lines this boot appended to that same log and reports the reason (`EADDRINUSE`, missing API keys, or the last six lines) before exiting non-zero.
+
+`saros-proxy status` checks the PID file first, then falls back to an os-agnostic `GET /health` port probe — so it reports the truth even when the proxy was started outside the daemon (manually, via autostart, or in another session) and no PID file exists. It also prints the enabled harnesses (`configharness` selection) and, from the daemon's `/health` payload, one line per key with its state (`Keys: 1/2 enabled`, then `work [commandcode] — disabled: auth (401), retry in 42s`). `saros-proxy start` refuses to start a second instance when the configured port is already serving. `saros-proxy stop` exits non-zero whenever something still answers `/health` on the configured port, even when it has no PID file to remove — the process was started outside the daemon or lost its handle.
 
-`saros-proxy status` checks the PID file first, then falls back to an os-agnostic `GET /health` port probe — so it reports the truth even when the proxy was started outside the daemon (manually, via autostart, or in another session) and no PID file exists. It also prints the enabled harnesses (`configharness` selection). `saros-proxy start` refuses to start a second instance when the configured port is already serving.
+Every request writes exactly one `evt:"request.complete"` line (requestId, path, model, provider, keyLabel, status, durationMs, stream, attempt), with key selection at `debug` and upstream failures at `warn`. The full event and redaction contract is in [docs/logging.md](docs/logging.md).
 
 Bare `saros-proxy` (no subcommand) prints the same overview without starting anything: running state, harnesses, masked API keys, and config path. To run the proxy in the foreground (e.g. for development or in a container), use `saros-proxy serve [--port <port>] [--config <path>]` — the daemon child and the Docker entrypoint run `serve` under the hood.
 
@@ -644,9 +763,9 @@ The model list written to each harness comes from the live provider catalogs (op
 Two kinds of upstream quota are visible in the provider documentation but are **not** modelled by Saros, on purpose — the proxy rotates keys and reasons about keys, not about what a single model or plan allows:
 
 - **Model-level free tiers (CommandCode).** `glyph-cluster:free` is capped at 100 requests/day, `beam:free` has no daily cap, and the `laguna-s-2.1-free` tiers cost no credits. Saros counts tokens per key (`token-usage.json`) and per model, but it does not refuse a request because a *model* reached its daily free quota — the upstream returns the error and the key's circuit breaker decides what happens next.
-- **Plan windows (OpenCode Go).** The Go plan meters each model against `5-hour — 20% of the monthly limit`, `weekly — 50%` and `monthly — 100%`. Those windows belong to the subscription: `/zen/go/v1/usage` reports what was consumed, and Saros surfaces it, but the proxy does not predict window exhaustion or re-route on it.
+- **Plan windows (OpenCode Go).** The Go plan meters each model against `5-hour — 20% of the monthly limit`, `weekly — 50%` and `monthly — 100%`. What was consumed is what feeds weighted rotation (see [Usage-Weighted Rotation](#usage-weighted-rotation)), but the proxy does not refuse a request because a model crossed a window: the upstream returns the error and that is what the client sees.
 
-Both are documented here so the behaviour is not mistaken for a bug. Requests through the alternate OpenAI/Anthropic surfaces (`/v1/responses`, `/v1/messages`) and through the decision endpoint (`/v1/systemone`) are forwarded and counted: streamed usage nested under `response.usage` and the `input_tokens`/`output_tokens` shape are booked like any other call.
+Both are documented here so the behaviour is not mistaken for a bug. Requests through the alternate OpenAI/Anthropic surfaces (`/v1/responses`, `/v1/messages`) and through the decision endpoint (`/v1/systemone`) are forwarded and counted: streamed usage nested under `response.usage` (Responses), the counts Anthropic splits between `message_start.message.usage` and `message_delta.usage` (Messages), and the `input_tokens`/`output_tokens` shape are booked like any other call — with one exception: Anthropic **cache** counters (`cache_read_input_tokens`, `cache_creation_input_tokens`) are not counted, so prompt-cached Messages traffic is under-booked on the prompt side.
 
 ---
 
@@ -670,21 +789,41 @@ NODE_ENV=development npx tsx src/index.ts
 NODE_ENV=production npx tsx src/index.ts
 ```
 
-### See which key served a request
+### See which key and provider served a request
 
-Saros adds two debug headers to every response:
+Responses served by an upstream key carry three debug headers:
 
 | Header | Example | What it is |
 |---|---|---|
 | `X-Proxy-Key-Label` | `primary` | Which key was used |
+| `X-Proxy-Provider` | `commandcode` | Provider of that key (`opencode-go` or `commandcode`) |
 | `X-Proxy-Request-Id` | `550e8400-e29b-41d4-a716-446655440000` | Unique ID for log correlation |
 
 ```bash
-curl -s -D - http://127.0.0.1:3000/zen/go/v1/models | grep -i x-proxy
+curl -s -D - http://127.0.0.1:3000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}' | grep -i x-proxy
 # X-Proxy-Key-Label: primary
+# X-Proxy-Provider: opencode-go
 # X-Proxy-Request-Id: 550e8400-e29b-41d4-a716-446655440000
 ```
 
+`X-Proxy-Provider` reports the configured provider of the key that actually served the request. The credential prefix is not re-inferred at routing time: an explicit `provider:` in `config.yaml` wins, so a key declared `provider: commandcode` is sent to CommandCode and reported as `commandcode` even with an `sk-…` credential. For a pinned `model@provider` request the value equals the suffix because the selected key belongs to that provider — not because the header parses the model id.
+
+These headers are emitted only on 2xx responses served by an upstream key. The local routes (`GET /health`, `GET /v1/models`, `GET /zen/go/v1/models`, `GET /debug/recent`) and the 413/429 rejections carry none. The proxy's own error responses — 503 no key, 502 retries exhausted, the 502 synthesized for a bodyless stream, and a forwarded 4xx it re-serializes — omit them even when a key was involved: use the body's `requestId`, and `/debug/recent` still records the `keyLabel`. `/v1/models` is answered by the catalogue handler (`models-fetcher`, no key selected, no provider attribution), which is why it is outside the header contract.
+
+Browser clients can read the three headers: the CORS middleware lists them in `Access-Control-Expose-Headers`.
+
+### Inspect the last requests
+
+```bash
+curl -s http://127.0.0.1:3000/debug/recent | jq
+```
+
+`GET /debug/recent` returns `{capacity, count, entries}` with the last 200 proxied requests, oldest first. Each entry mirrors the `evt:"request.complete"` log line: `requestId`, `at` (ISO, when the response was produced — for a stream that is its headers, not the end of the stream), `method`, `path`, `model`, `provider`, `keyLabel`, `status`, `durationMs`, `stream`, `attempt`. It lives in memory only and never stores keys, headers or bodies — only the public key label — so it starts empty on restart.
+
+Disable it with `SAROS_DEBUG_BUFFER=0`: the endpoint answers `404` and no entry is kept. Like `/health`, it is unauthenticated and metadata-only: `requestId`, paths, models, providers, key labels, status and timing — never keys, headers or bodies. It is designed for the loopback bind; a deployment reachable from the network (including a container/port binding beyond `127.0.0.1`) exposes those request paths, model names and key labels to anyone who can reach the port.
+
 ### Common issues
 
 | Symptom | Likely cause | Fix |
@@ -693,6 +832,7 @@ curl -s -D - http://127.0.0.1:3000/zen/go/v1/models | grep -i x-proxy
 | `ECONNREFUSED` on startup | Port already in use | Change port or kill the existing process |
 | `504 Gateway Timeout` | Upstream too slow | Increase `requestTimeoutMs` |
 | `All API keys are temporarily unavailable` | All keys disabled by circuit breaker | Wait for cooldown or check upstream status |
+| Upstream `403` with `error code: 1010` | Cloudflare in front of the provider rejected the `User-Agent` the client sent | Saros sets the provider's own identity (`cli`); if you see this, the request bypassed the proxy or a provider lost its `extraUpstreamHeaders` |
 | CORS error | Client origin not allowed | Add it to `allowedOrigins` in config |
 
 ---
@@ -771,6 +911,49 @@ test/
 
 For vulnerability reporting, see [SECURITY.md](SECURITY.md).
 
+### Threat model for API keys at rest
+
+The envelope protects the key **file**. It does not make a credential
+unreachable by code running as the same user — every option below ultimately
+hands the plaintext to the proxy process, which that code can inspect.
+
+| Scenario | Plaintext config | `enc:v1` + `SAROS_PASSPHRASE` | `enc:v1` + OS store | `enc:v1` + TTY prompt |
+|---|---|---|---|---|
+| Config file copied to another machine/user | No protection | Protected (passphrase not in the file) | Protected (DPAPI/Keychain is user-bound) | Protected |
+| Dotfile sync / cloud backup / git accident | Leaks | Protected | Protected | Protected |
+| Backup of the config directory only | Leaks | Protected only after deleting `config.yaml.backup` (the migration backup is plaintext) | Same caveat | Same caveat |
+| Shoulder surfing the config file | Leaks | Protected | Protected | Protected |
+| Another local process **running as the same user** | Reads the file | Can read the env (`/proc/<pid>/environ`) | Can call the same OS CLI / read the same DPAPI blob | Can read the terminal or memory |
+| Malware running as the same user | Reads the file | No protection | No protection | No protection |
+| Root / Administrator | Reads the file | No protection | No protection (may impersonate the user) | No protection |
+| Offline brute force of a stolen config | N/A | scrypt N=2^15 slows guessing; strength = passphrase entropy | Same | Same |
+| Passphrase visible in `ps`/shell history | N/A | Avoid `SAROS_PASSPHRASE=… command`; export it or use systemd-creds | `secret set` on macOS passes `-w` on the command line briefly | Typed hidden, not echoed |
+
+Practical guidance:
+
+- Use the OS store for an interactive workstation; it avoids the passphrase
+  being present in every child process environment.
+- Use `SAROS_PASSPHRASE` for containers/systemd; prefer `systemd-creds` (recipe
+  above) over a unit-file `Environment=` line.
+- The passphrase must be high entropy and independent from the API keys; the
+  envelope only makes an offline attack expensive, not impossible. `secret set`
+  warns below 12 characters; no length is enforced.
+- `keys encrypt` writes `<config>.backup` in plaintext (0600) once. Delete it
+  after the first successful boot, or use `--no-backup`. Any directory/dotfile
+  backup taken before that deletion contains the original keys.
+- `saros-proxy secret status` shows which source would win and never prints a
+  value.
+
+### Other controls
+
+- HTTPS-only upstream (SSRF prevention)
+- API key masking in logs, plus envelope/passphrase redaction patterns and
+  pino redact paths for `passphrase`, `secret`, `secretValue`, `masterKey`,
+  `encryptionKey` and `SAROS_PASSPHRASE`
+- CORS origin validation
+- Rate limiting: 100 req/min per IP (hardcoded)
+- Non-root Docker container
+
 ---
 
 ## License

package/dist/cli/daemon.d.ts

@@ -9,13 +9,42 @@
  *
  * Daemon lifecycle:
  *   start   → refuses if the port is already serving, then spawns detached
- *             `node dist/index.js` process, saves PID, logs child stderr
- *   stop    → kills the process (taskkill /T /F on Windows), removes PID file
- *   restart → kills running instance (if any), waits, then starts fresh
+ *             `node dist/index.js` process, saves PID, appends child stdout
+ *             and stderr to daemon.log
+ *   stop    → kills the process (taskkill /T /F on Windows) and removes the
+ *             PID file only once the process is confirmed gone; exits 1 when
+ *             something still serves the port
+ *   restart → kills running instance (if any), waits for it to disappear,
+ *             then starts fresh
  *   status  → checks PID file, falls back to an os-agnostic /health port
  *             probe (instances started outside the daemon have no PID file),
  *             and prints the enabled harnesses
  */
+/**
+ * Open daemon.log for append (0600 — it carries upstream error bodies).
+ * Returns null when the file cannot be opened, so callers fall back to
+ * discarding output. Used for the child's stdout and stderr, which share this
+ * single file. Exported so the wiring can be asserted in tests.
+ */
+export declare function openDaemonLog(): number | null;
+/**
+ * Check if a process is alive by PID.
+ *
+ * `process.kill(pid, 0)` is the portable liveness probe: Node maps it to
+ * OpenProcess on Windows, so a dead PID fails with ESRCH and an EPERM/EACCES
+ * answer means "the PID exists, it is just not ours to signal" → alive.
+ *
+ * The previous win32 path ran `tasklist /FI "PID eq <pid>"`, which exits 0
+ * even when no task matches — every PID looked alive (#83).
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Kill a process and all its children. Returns whether the target is gone.
+ *
+ * Output is piped (never inherited): taskkill's "not found" text used to land
+ * in the caller's console and PowerShell surfaced it as a NativeCommandError.
+ */
+export declare function killProcess(pid: number): boolean;
 /**
  * Probe the proxy's /health endpoint on a port. Returns the parsed body when
  * the endpoint answers with status ok — the strongest cross-platform signal
@@ -27,11 +56,14 @@ export declare function probeProxyHealth(port: number): Promise<{
     body?: Record<string, unknown>;
 }>;
 export declare function daemonStart(port?: number, configPath?: string): Promise<void>;
-export declare function daemonStop(): void;
+export declare function daemonStop(): Promise<void>;
 /**
- * Restart the proxy daemon: stop the running instance (if any), wait
- * briefly for the port to release, then start a fresh instance.
+ * Restart the proxy daemon: stop the running instance (if any), wait for it
+ * to actually disappear and the port to release, then start a fresh instance.
  * Reuses daemonStart which owns its own exit path via setTimeout.
+ *
+ * "Restarting: stopped daemon" used to print before the kill landed, so a
+ * failed stop was followed by a start that died on the busy port.
  */
 export declare function daemonRestart(port?: number, configPath?: string): void;
 export interface DaemonState {