saros-proxy 0.10.1 → 0.11.0

package/README.md

@@ -44,7 +44,8 @@ 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.
 
 ---
@@ -125,7 +126,9 @@ queryable quota API (CommandCode): their keys report no percentages, but
 #### 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 +286,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 +343,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,8 +370,9 @@ 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)).
 
@@ -372,33 +386,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.
 
-**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
+**systemd-creds recipe** (keeps the passphrase out of the unit file and the
+environment of the shell):
+
+```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 +607,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). `saros-proxy start` refuses to start a second instance when the configured port is already serving.
+`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.
+
+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.
 
@@ -639,6 +722,17 @@ The model list written to each harness comes from the live provider catalogs (op
 
 ---
 
+## What the proxy does *not* enforce
+
+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.
+
+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.
+
+---
+
 ## Troubleshooting
 
 ### Check proxy health
@@ -659,21 +753,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 |
@@ -728,6 +842,7 @@ src/
   providers/            — Multi-provider key abstraction (KeyProvider, adapters, identifyKey)
   models-fetcher.ts     — Upstream model list fetching + caching
   models-sync.ts        — Auto-sync models from upstream to opencode config
+  models-catalog.ts     — Single source of truth: loads bundled models.json
   cli/
     setup.ts            — Interactive setup wizard
     daemon.ts           — Background process management
@@ -759,6 +874,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 {