@askalf/dario 5.4.16 → 5.4.19

package/dist/cc-template.d.ts

@@ -170,6 +170,17 @@ export declare const CC_AGENT_IDENTITY: string;
  */
 export declare const CLIENT_SYSTEM_PREFACE: string;
 export declare function resolveSystemPrompt(arg: string | undefined, model?: string): string;
+/**
+ * Pick the CC-identity headers out of an inbound request so the passthrough
+ * path can forward them unchanged.
+ *
+ * Pure and exported so the allow/deny behaviour is unit-testable without
+ * standing up the proxy, matching `orderHeadersForOutbound` and
+ * `overlayTemplateHeaderValues`. Array-valued headers (Node allows repeats)
+ * take the first value; empty strings are skipped so a client sending a blank
+ * header cannot blank out a value dario would otherwise supply.
+ */
+export declare function forwardClientCCIdentityHeaders(reqHeaders: Record<string, string | string[] | undefined>): Record<string, string>;
 /**
  * Overlay a captured template's `header_values` onto the outbound header record,
  * skipping the keys that must never be replayed.

package/dist/cc-template.js

@@ -283,6 +283,74 @@ function stripBehavioralConstraints(input, level) {
  * so new captures are clean. This skip list is what makes every ALREADY-baked
  * template and warm cache self-heal without waiting for a re-bake.
  */
+/**
+ * Headers a genuine Claude Code client sends to identify itself, which the
+ * passthrough path forwards verbatim instead of substituting template values.
+ *
+ * The template exists to SYNTHESISE CC's shape for clients that are not CC. On
+ * the passthrough path `isGenuineCCClient` has already established that the
+ * caller really is Claude Code, so its own headers are the authentic article and
+ * a capture is at best a good imitation of them. Measured before this changed:
+ * of 13 CC-identity headers a real client sent, 12 were replaced with template
+ * values and 1 was dropped — 0 forwarded (dario#885).
+ *
+ * Deliberately NOT in this list, because dario must own them:
+ *
+ *   authorization / x-api-key   must become the pool account's credential
+ *   x-claude-code-session-id    session rotation is a feature, not an accident
+ *   anthropic-beta              merged with operator pins + the per-account
+ *                               rejection cache; the client's set is not final
+ *   anthropic-version           already read from the client at the call site
+ *   accept / content-type       body framing, owned by the proxy
+ *   host / connection /         transport, owned by the HTTP stack; forwarding
+ *   content-length /            them corrupts the request
+ *   transfer-encoding /
+ *   accept-encoding / keep-alive
+ *
+ * Anything a future CC adds under the `x-stainless-*` or `x-claude-code-*`
+ * prefixes is forwarded by the prefix rules in
+ * `forwardClientCCIdentityHeaders` rather than needing to be enumerated here —
+ * the capture cannot see first-party-conditional headers at all (dario#885), so
+ * an allowlist of exact names would silently miss them.
+ */
+const CC_IDENTITY_HEADERS_TO_FORWARD = new Set([
+    'user-agent',
+    'x-app',
+    'anthropic-dangerous-direct-browser-access',
+]);
+/** Prefixes whose every member is CC self-identification, forwarded wholesale. */
+const CC_IDENTITY_HEADER_PREFIXES = ['x-stainless-', 'x-claude-code-', 'x-client-'];
+/** Never forwarded from the client even when it matches a prefix above. */
+const NEVER_FORWARD_FROM_CLIENT = new Set([
+    'x-claude-code-session-id', // dario rotates sessions deliberately
+]);
+/**
+ * Pick the CC-identity headers out of an inbound request so the passthrough
+ * path can forward them unchanged.
+ *
+ * Pure and exported so the allow/deny behaviour is unit-testable without
+ * standing up the proxy, matching `orderHeadersForOutbound` and
+ * `overlayTemplateHeaderValues`. Array-valued headers (Node allows repeats)
+ * take the first value; empty strings are skipped so a client sending a blank
+ * header cannot blank out a value dario would otherwise supply.
+ */
+export function forwardClientCCIdentityHeaders(reqHeaders) {
+    const out = {};
+    for (const [rawName, rawValue] of Object.entries(reqHeaders)) {
+        const name = rawName.toLowerCase();
+        if (NEVER_FORWARD_FROM_CLIENT.has(name))
+            continue;
+        const allowed = CC_IDENTITY_HEADERS_TO_FORWARD.has(name)
+            || CC_IDENTITY_HEADER_PREFIXES.some((p) => name.startsWith(p));
+        if (!allowed)
+            continue;
+        const value = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+        if (typeof value !== 'string' || value.length === 0)
+            continue;
+        out[name] = value;
+    }
+    return out;
+}
 const NEVER_REPLAY_HEADER_VALUES = new Set([
     'x-api-key',
     'x-stainless-os',

package/dist/live-fingerprint.d.ts

@@ -336,12 +336,6 @@ export interface DriftResult {
  *   callers pass nothing and the real binary probe runs.
  */
 export declare function detectDrift(t: TemplateData, installedOverride?: string | null): DriftResult;
-/**
- * Reset the memoized `claude --version` probe. Test-only — production
- * code should never need to clear the cache since the installed binary
- * doesn't change mid-process.
- */
-export declare function _resetInstalledVersionProbeForTest(): void;
 /**
  * The CC version range the current dario release has been exercised
  * against. Update `maxTested` every time we validate against a new CC

package/dist/live-fingerprint.js

@@ -919,14 +919,6 @@ export function detectDrift(t, installedOverride) {
         message: `cache is from CC v${cachedVersion} but installed CC is v${installed} — background refresh will re-capture`,
     };
 }
-/**
- * Reset the memoized `claude --version` probe. Test-only — production
- * code should never need to clear the cache since the installed binary
- * doesn't change mid-process.
- */
-export function _resetInstalledVersionProbeForTest() {
-    _installedVersionProbe = { value: null, cached: false };
-}
 // ============================================================
 //  CC version compat matrix (v3.17)
 // ============================================================

package/dist/proxy.js

@@ -9,7 +9,7 @@ import { arch, platform } from 'node:process';
 import { getAccessToken, getStatus } from './oauth.js';
 import { buildHealthResponse, derivePoolStatus, shouldDiscloseHealthInternals } from './health-response.js';
 import { darioVersion } from './version.js';
-import { buildCCRequest, applyCcPromptCaching, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
+import { buildCCRequest, applyCcPromptCaching, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { describeTemplate, detectDrift, checkCCCompat } from './live-fingerprint.js';
 import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, reconcilePoolAccounts, resolvePoolStrategy } from './pool.js';
@@ -2064,6 +2064,12 @@ export async function startProxy(opts = {}) {
         let requestModel = '';
         let detectedClientForLog;
         let preserveToolsEffective = Boolean(opts.preserveTools);
+        // Per-request: did isGenuineCCClient recognise the caller as real Claude
+        // Code? Hoisted because the header build below needs it and `genuineCC` is
+        // block-scoped where buildCCRequest destructures it. NOT the same thing as
+        // `passthrough`, which is a startup CLI flag — conflating the two is why
+        // the first version of this forwarded nothing (dario#885).
+        let genuineCCRequest = false;
         try {
             // Select an account by headroom (v5.0: the pool is the one credential
             // model, so every OAuth request selects from it — a plain `dario login`
@@ -2442,6 +2448,7 @@ export async function startProxy(opts = {}) {
                         preserveToolsEffective = Boolean(opts.preserveTools)
                             || Boolean(genuineCC)
                             || (Boolean(detectedClient) && !opts.hybridTools && !opts.mergeTools);
+                        genuineCCRequest = Boolean(genuineCC);
                         if (genuineCC && !ccPassthroughLogged) {
                             ccPassthroughLogged = true;
                             console.log('[dario] genuine Claude Code client — system + tools forwarded verbatim (byte-faithful passthrough)');
@@ -2688,15 +2695,31 @@ export async function startProxy(opts = {}) {
                     console.log(`[dario] #${requestCount} session: rotate (${assigned.reason})${poolAccount ? ` [${poolAccount.alias}]` : ''}`);
                 }
             }
+            // On the passthrough path `isGenuineCCClient` has already established the
+            // caller IS Claude Code, so its own identity headers are the authentic
+            // article — forward them instead of substituting template values. The
+            // template is for synthesising CC's shape when the client is not CC; here it
+            // would only be an imitation of headers we already hold. Measured before
+            // this: 12 of 13 client CC-identity headers were replaced and 1 dropped,
+            // 0 forwarded (dario#885). Spread AFTER staticHeaders so the client wins
+            // over template values, and BEFORE the dario-owned block below so auth,
+            // session rotation and the merged beta set still win over the client.
+            const forwardedIdentity = (passthrough || genuineCCRequest)
+                ? forwardClientCCIdentityHeaders(req.headers)
+                : {};
             const headers = {
                 ...staticHeaders,
+                ...forwardedIdentity,
                 ...upstreamAuthHeaders(upstreamApiKey, accessToken),
                 'x-claude-code-session-id': outboundSessionId,
                 'anthropic-version': passthrough ? (req.headers['anthropic-version'] || '2023-06-01') : '2023-06-01',
                 'anthropic-beta': beta,
-                'x-client-request-id': randomUUID(),
+                // Prefer the client's own when passthrough forwarded one: a genuine CC
+                // request already carries a real request id, and synthesising over it
+                // discards information for no gain. Falls back to a fresh uuid otherwise.
+                'x-client-request-id': forwardedIdentity['x-client-request-id'] ?? randomUUID(),
                 // CC sends 600 on first request per session. With rotation, every request is "first"
-                'x-stainless-timeout': '600',
+                'x-stainless-timeout': forwardedIdentity['x-stainless-timeout'] ?? '600',
             };
             // Client-disconnect abort: if the client drops the connection before
             // we've finished sending the response, we default to aborting the

package/dist/version.d.ts

@@ -1,3 +1 @@
 export declare function darioVersion(): string;
-/** Test-only: clear the memoized version. */
-export declare function _resetVersionCacheForTest(): void;

package/dist/version.js

@@ -26,7 +26,3 @@ export function darioVersion() {
     cached = v;
     return v;
 }
-/** Test-only: clear the memoized version. */
-export function _resetVersionCacheForTest() {
-    cached = null;
-}

package/docs/admin-api.md

@@ -0,0 +1,154 @@
+# Headless admin API
+
+An opt-in HTTP control plane for managing dario's account pool without console
+access: provision the first account on an empty proxy, add or remove accounts
+later, and read live per-account status — all over HTTP, with no `dario login`,
+no TTY, and no restart. Built for the deployments where a console is the
+awkward part: Docker, Kubernetes, a Raspberry Pi in a closet, a VPS you'd
+rather not SSH into.
+
+Requires dario **v4.8.111+** (the `/status` / `/health` behavior described
+below is accurate as of **v4.8.117**).
+
+## Enabling it
+
+```bash
+DARIO_ADMIN=1 DARIO_ADMIN_TOKEN=<long-random-string> dario proxy
+```
+
+| Variable | Purpose |
+|---|---|
+| `DARIO_ADMIN=1` | Mounts the API at `/admin/*`. Off by default — the endpoints don't exist otherwise. |
+| `DARIO_ADMIN_TOKEN` | Bearer token for every admin call. Falls back to `DARIO_API_KEY` if unset. |
+| `DARIO_ADMIN_RATE_LIMIT=off` | Disables the built-in rate limiting (see below). Leave on. |
+
+Two deliberate security properties:
+
+- **Auth is always required, even on loopback.** These endpoints add and remove
+  OAuth credentials; the localhost trust shortcut the proxy key allows for LLM
+  routes does not apply here.
+- **Enabled-but-tokenless fails closed.** `DARIO_ADMIN=1` with neither
+  `DARIO_ADMIN_TOKEN` nor `DARIO_API_KEY` set returns `403` with a message
+  telling you to set the token — account control is never left open.
+
+Admin mode also changes one startup behavior: the proxy **starts with zero
+accounts** instead of exiting `Not authenticated`. Until an account exists,
+LLM requests return a truthful `503 { "error": "No account configured" }` with
+a hint pointing at `POST /admin/login/start`.
+
+## Zero to serving, over HTTP only
+
+The login flow mirrors `dario accounts add --manual` (PKCE + manual code
+paste), split into two calls:
+
+```bash
+ADMIN='authorization: Bearer <your DARIO_ADMIN_TOKEN>'
+BASE=http://127.0.0.1:3456
+
+# 1. Start a login. Alias is optional — omit it and a non-colliding
+#    default (account-1, account-2, …) is generated and returned.
+curl -s -X POST -H "$ADMIN" "$BASE/admin/login/start" -d '{"alias":"main"}'
+# -> { "alias": "main",
+#      "authorize_url": "https://claude.ai/oauth/authorize?...",
+#      "expires_at": "...",
+#      "instructions": "Open authorize_url, approve, then POST ... to /admin/login/complete." }
+
+# 2. Open authorize_url in any browser on any machine, approve, and copy the
+#    code Anthropic displays. Paste it back ("code#state" or bare code both work):
+curl -s -X POST -H "$ADMIN" "$BASE/admin/login/complete" \
+  -d '{"alias":"main","code":"<pasted code>"}'
+# -> { "alias": "main", "status": "added", "expires_at": "..." }
+```
+
+**The account is routable the moment the `200` lands.** `login/complete` (and
+account removal) hot-reload the live pool from disk before responding — no
+proxy restart, superseding the "takes effect on next restart" behavior of
+early builds. The model catalog also refetches immediately with the new
+account's credentials, so `/v1/models` upgrades from the baked list without
+waiting out a retry window.
+
+Pending-login mechanics, for scripting against it:
+
+- A pending login lives **10 minutes** and is **single-use** — `/complete`
+  consumes it whether or not the token exchange succeeds.
+- **One pending login per alias**; a second `/start` for the same alias
+  replaces the first.
+- If the pasted blob carries a `state` and it doesn't match the pending
+  login's, `/complete` refuses (`400 state mismatch`) — the code came from a
+  different login attempt.
+- An expired or unknown alias gets `410` — start a new login.
+- The PKCE verifier and state never touch disk and are never returned to the
+  client.
+
+## Endpoint reference
+
+All endpoints accept the token as `authorization: Bearer <token>` or
+`x-api-key: <token>`.
+
+| Method + path | Body | Returns |
+|---|---|---|
+| `POST /admin/login/start` | `{ "alias"?: string }` | `{ alias, authorize_url, expires_at, instructions }` |
+| `POST /admin/login/complete` | `{ "alias": string, "code": string }` | `{ alias, status: "added", expires_at }` |
+| `GET /admin/accounts` | — | `{ accounts: [...], count }` |
+| `DELETE /admin/accounts/<alias>` | — | `{ alias, removed }` (`404` if no such alias) |
+
+`GET /admin/accounts` is the monitoring surface: each entry carries the
+persisted metadata (`alias`, `scopes`, `expires_in_ms`) **plus live pool
+status whenever pool mode is active** — `util5h` / `util7d` utilization,
+representative `claim` (e.g. `five_hour`), routing `status`, and
+`request_count`. It's the admin-token-gated equivalent of the proxy-key-gated
+`GET /accounts` pool view; a headless operator needs only the admin token to
+watch headroom.
+
+## What the generic surfaces report (v4.8.117+)
+
+`/status` and `/health` derive from the live pool whenever pool mode is
+active, so they track the admin lifecycle truthfully:
+
+| Stage | `/status` | `/health` |
+|---|---|---|
+| Started empty (`DARIO_ADMIN=1`, no accounts) | `authenticated:false`, `status:"none"`, hint: add one via `POST /admin/login/start` | **503** `degraded` — correct: every LLM call 503s until an account exists |
+| ≥1 account added | `authenticated:true`, `status:"healthy"`, `mode:"pool"`, `accounts:N`, earliest token expiry | **200** `ok` — docker healthchecks and `depends_on: service_healthy` pass |
+| All accounts in auth-cooldown (upstream 401s) | `status:"broken"`, `authenticated:false` | **503** `degraded` — the next request would fail |
+
+If you're wiring a container healthcheck against a proxy that starts empty,
+expect it to report unhealthy until the first account is provisioned — that's
+the API telling you the truth, not a bug. Gate your bootstrap job on the
+container being *up* (TCP/HTTP response), not *healthy*.
+
+## Audit trail
+
+Every mutation (`login_start`, `login_complete`, `account_remove`) and every
+auth reject or throttle is logged with the action, target alias, outcome, HTTP
+status, and client address — to the console always (so `docker logs` /
+journald has the trail with zero setup), and as a structured
+`event: "admin.<action>"` line when `--log-file` / `DARIO_LOG_FILE` is set.
+Secrets never reach the audit sink.
+
+## Rate limiting
+
+Two global token buckets (per proxy, not per-IP — the surface is
+loopback-default, so per-IP keying buys nothing), applied **after** auth for
+mutations and **to failed auth attempts** separately:
+
+- **Failed auth**: 10 burst, then 1 per 2s — a wrong-token flood is slowed,
+  not answered at full speed.
+- **Mutations** (`login/start`, `login/complete`, account removal): 30 burst,
+  then 1 per 1s.
+
+Over the limit returns `429` with a `Retry-After` header, and the throttle
+itself is audited (`rate_limited`). Reads (`GET /admin/accounts`) and
+successful auth are never throttled. `DARIO_ADMIN_RATE_LIMIT=off` disables
+both buckets; the defaults are generous for a human plus scripts and only
+bite runaway callers.
+
+## Relationship to the CLI
+
+The admin API and `dario accounts add/remove/list` manage the same on-disk
+store (`~/.dario/accounts/`) and can be mixed freely. Pool mode activates at
+**one** account, so a single `login/start`/`complete` round-trip on a fresh
+box yields a serving proxy — `dario login` remains the single-default-account
+one-liner for interactive setups and is never required on the admin path. See
+[`docs/multi-account-pool.md`](./multi-account-pool.md) for how the pool
+routes, and [`docs/docker.md`](./docker.md) for the container deployment this
+API was built for.

package/docs/commands.md

@@ -0,0 +1,77 @@
+# Commands and proxy options
+
+This page is the per-flag reference. For environment variables grouped by task — overage guard, request queue, template fidelity, pacing — see [`configuration.md`](./configuration.md), which also covers the precedence order and the boolean-parsing rules.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `dario login [--manual]` | Log in to the Claude backend. Detects CC credentials or runs its own OAuth flow. `--manual` (v3.20) mirrors CC's code-paste flow for SSH / container setups without a browser. |
+| `dario proxy` | Start the local API proxy on port 3456 |
+| `dario doctor [--probe] [--auth-check] [--json] [--bun-bootstrap]` | Aggregated health report — dario / Node / runtime-TLS / CC binary + compat / template + drift / per-request overhead / OAuth / pool + pool routing (next account in rotation when 2+ loaded) / backends / sub-agent. `--probe` (v3.31.7) hits the live `claude.ai/oauth/authorize` endpoint and surfaces the verdict, so scope-policy drift is catchable from a user's machine (not just CI). `--auth-check` (v3.31.9) opens a one-shot `x-api-key` listener and classifies whatever a client actually sends (match / mismatch / no-auth / timeout), with only redacted previews in output. `--json` (v3.31.8) emits structured output for deepdive's health probes and CI scrapers. `--bun-bootstrap` runs the canonical bun.sh installer when the runtime/TLS check is warning that Bun isn't on PATH. |
+| `dario usage [--port=N] [--json]` | Burn-rate summary of the running proxy's traffic over the last 60 minutes: requests, input/output tokens, avg latency, error rate, subscription % vs. extra-usage, estimated API-equivalent cost, plus per-account breakdown when pool mode is active. Hits `/analytics` on the local proxy. When the proxy isn't reachable, prints a hint pointing at `dario doctor --usage` (the one-off rate-limit probe). `--json` emits the raw `/analytics` payload for status bars / CI dashboards. Also exposed as the `usage` tool in `dario mcp`. |
+| `dario config [--json]` | Prints the effective dario configuration with credentials redacted. Complementary to `doctor` — doctor answers *is it working?*, config answers *what IS it?* (v3.31.10) |
+| `dario upgrade` | Safe wrapper over `npm install -g @askalf/dario@latest` — probes npm for the `@latest` version first (3s timeout, 60s cache), refuses to run if already on latest, fails with a clear hint if npm is missing. (v3.31.10) |
+| `dario status` | Show Claude backend OAuth token health and expiry |
+| `dario refresh` | Force an immediate Claude token refresh |
+| `dario logout` | Delete stored Claude credentials |
+| `dario accounts list` / `add <alias>` / `remove <alias>` | Multi-account pool management. `add <alias>` on a fresh pool auto back-fills your existing `dario login` credentials as `login`, so your first `add` trips the 2+ pool threshold on its own — see [Multi-account pool mode](./multi-account-pool.md). |
+| `dario backend list` / `add <name> --key=<key> [--base-url=<url>]` / `remove <name>` | OpenAI-compat backend management |
+| `dario subagent install` / `remove` / `status` | CC sub-agent lifecycle. See [sub-agent hook](./sub-agent.md). |
+| `dario mcp` | Run dario as an MCP server over stdio. See [MCP server](./mcp-server.md). |
+| `dario help` | Full command reference |
+
+## Proxy options
+
+| Flag / env | Description | Default |
+|---|---|---|
+| `--passthrough` / `--thin` | Thin proxy for the Claude backend — OAuth swap only, no template injection | off |
+| `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC's. Required for clients whose tools have fields CC doesn't — see [Custom tool schemas](./integrations/agent-compat.md#custom-tool-schemas). Auto-enabled for Cline / Kilo Code / Roo Code and forks (detected via system-prompt identity markers). | off (auto for text-tool clients) |
+| `--no-auto-detect` / `--no-auto-preserve` | Disable the text-tool-client detector so the CC wire shape stays intact on Cline/Kilo/Roo prompts (v3.20.1, dario#40). Explicit `--preserve-tools` still wins. | off |
+| `--hybrid-tools` / `--context-inject` | Remap to CC tools **and** inject request-context values (`sessionId`, `requestId`, `channelId`, `userId`, `timestamp`) into client-declared fields CC's schema doesn't carry. See [Hybrid tool mode](./integrations/agent-compat.md#hybrid-tool-mode). | off |
+| `--merge-tools` / `--append-tools` | **EXPERIMENTAL.** Send CC's canonical tools first, append the client's custom tools after (deduped by name, case-insensitive). Model can call either side; tool calls flow back unchanged. Mutually exclusive with `--preserve-tools` and `--hybrid-tools`. Anthropic's billing classifier may flip routing on the appended suffix — validate with `--verbose` and watch the `billing: <bucket>` line on the first 1-2 requests before relying on it. | off |
+| `--model=<name>` | Force a model. Shortcuts (`fable`, `opus`, `sonnet`, `haiku`, and their `1m` long-context forms) always resolve to the newest model of that family in the live catalog; version pins (`opus48`, `opus47`, `opus46`, `sonnet46`) never float. Also full IDs (`claude-fable-5`, `claude-opus-5`), or a **provider prefix** (`openai:gpt-4o`, `groq:llama-3.3-70b`, `claude:fable`, `claude:opus`, `local:qwen-coder`) to force the backend server-wide. | passthrough |
+| `--model-alias=<name=target>` / `DARIO_MODEL_ALIASES` / config `modelAliases` | User-defined model alias, repeatable. Applied to the client's model name before provider-prefix parsing, so a target may carry a prefix and retarget the backend (`--model-alias=my-fast=openai:gpt-4o-mini`). Advertised on `/v1/models` so client pickers offer it. Names match case-insensitively; targets forward verbatim; one step, never recursive. An alias may shadow a real id or built-in shortcut — that's how you remap every `opus` call from a client whose picker you don't control. Merge order per-key: config < env < flags. `--model` still wins downstream (it overrides the resolved model server-wide). | none |
+| `--port=<n>` | Port to listen on | `3456` |
+| `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
+| `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
+| `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
+| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
+| `--pool-fallback=<model>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down, forward OpenAI-shape requests (`/v1/chat/completions`) to the configured openai-compat backend as `<model>` instead of surfacing the 429/503. Every fallback response carries `x-dario-pool-fallback: <model>` — never silent. Anthropic-shape requests keep the error (no reverse response translation). Requires an openai-compat backend (`dario backend add …`); inert without one. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
+| `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |
+| `--strict-tls` / `DARIO_STRICT_TLS=1` | Refuse to start proxy mode unless runtime classifies as `bun-match` — i.e. the TLS ClientHello matches CC's. See [Wire-fidelity axes](./wire-fidelity.md). (v3.23) | off |
+| `--pace-min=<ms>` / `DARIO_PACE_MIN_MS` | Minimum inter-request gap in ms. Replaces the legacy hardcoded 500 ms. (v3.24) | `500` |
+| `--pace-jitter=<ms>` / `DARIO_PACE_JITTER_MS` | Uniform random jitter added to each gap. Dissolves the minimum-inter-arrival observable edge. (v3.24) | `0` |
+| `--drain-on-close` / `DARIO_DRAIN_ON_CLOSE=1` | When a downstream client disconnects mid-stream, keep reading upstream SSE to completion (match CC's consumption shape). Bounded by the 5-min upstream timeout. (v3.25) | off |
+| `--session-idle-rotate=<ms>` / `DARIO_SESSION_IDLE_ROTATE_MS` | Idle threshold before a session-id rotates. (v3.28) | `900000` (15 min) |
+| `--session-rotate-jitter=<ms>` / `DARIO_SESSION_JITTER_MS` | Jitter sampled once per session at creation — hides the exact idle floor. (v3.28) | `0` |
+| `--session-max-age=<ms>` / `DARIO_SESSION_MAX_AGE_MS` | Hard ceiling on a session-id's lifetime regardless of activity. (v3.28) | off |
+| `--session-per-client` / `DARIO_SESSION_PER_CLIENT=1` | Split session-id registry by a per-client header so multi-UI fan-out doesn't collapse onto one id. (v3.28) | off |
+| `--pool-strategy=<headroom\|fill-first>` / `DARIO_POOL_STRATEGY` | Where new conversations land in a multi-account pool. `headroom` spreads them to the seat with the most slack; `fill-first` concentrates them on the alphabetically-first eligible seat until it drains to the 2% floor, then spills to the next — primary/backup semantics, alias naming (`1-main`, `2-overflow`) picks the fill order. Sticky bindings behave identically under both. See [Multi-account pool](./multi-account-pool.md#routing-strategy). | `headroom` |
+| `--pool-fallback=<model>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), forward **OpenAI-shape** requests (`/v1/chat/completions`) to the configured openai-compat backend as `<model>` instead of surfacing the 429/503. Every substituted response carries `x-dario-pool-fallback: <model>` — a swapped model is never silent. Anthropic-shape requests (`/v1/messages`) keep the error: dario has no OpenAI→Anthropic response translation. Requires `dario backend add …`; inert otherwise. Empty flag value (`--pool-fallback=`) disables, overriding env + config. See [Multi-account pool](./multi-account-pool.md#pool-exhausted-fallback). | off |
+| `--system-prompt=<verbatim\|partial\|aggressive\|filepath>` / `DARIO_SYSTEM_PROMPT` | System-prompt mode for outbound CC-shaped requests. `partial` strips behavioral constraints (Tone-and-style, Text-output, scope/verbosity/comment bullets) for ~1.2–2.8× output capability on open-ended work. `aggressive` adds prompt-level RLHF restatement removal (<3% over partial — alignment is RLHF-trained). `<filepath>` fully replaces the slot with file contents. Empirically validated as unfingerprinted by the billing classifier — see [`system-prompt.md`](./system-prompt.md) and [`research/system-prompt-classifier-study.md`](./research/system-prompt-classifier-study.md). (v3.34) | `verbatim` |
+| `--upstream-proxy=<url>` / `--via=<url>` / `DARIO_UPSTREAM_PROXY` | Route dario's outbound fetches (api.anthropic.com, OpenAI-compat backends, OAuth) through an HTTP/HTTPS proxy. Pair with the HTTP proxy mode of a VPN provider (Mullvad, AirVPN), a corporate proxy, privoxy/Tor, etc. Localhost calls bypass. Requires Bun runtime; SOCKS5 not supported. Full provider matrix + setup in [`vpn-routing.md`](./vpn-routing.md). (v3.35) | unset |
+| `DARIO_API_KEY` | If set, all endpoints (except `/health`) require a matching `x-api-key` or `Authorization: Bearer` header. Required when `--host` binds non-loopback. | unset (open) |
+| `DARIO_CORS_ORIGIN` | Override browser CORS origin | `http://localhost:${port}` |
+| `DARIO_QUIET_TLS` | Suppress the runtime/TLS mismatch startup banner | unset |
+| `DARIO_NO_BUN` | Disable automatic Bun relaunch | unset |
+| `DARIO_MIN_INTERVAL_MS` | Legacy name for `DARIO_PACE_MIN_MS`. Still honored; new name wins when both are set. | — |
+| `DARIO_CC_PATH` | Override path to the Claude Code binary for OAuth detection | auto-detect |
+| `DARIO_OAUTH_CLIENT_ID` | Override the detected Claude OAuth client id as an emergency escape hatch | unset |
+| `DARIO_OAUTH_AUTHORIZE_URL` | Override the detected Claude OAuth authorize URL | unset |
+| `DARIO_OAUTH_TOKEN_URL` | Override the detected Claude OAuth token URL | unset |
+| `DARIO_OAUTH_SCOPES` | Override the detected Claude OAuth scopes | unset |
+| `DARIO_OAUTH_OVERRIDE_PATH` | Override file path for JSON OAuth overrides | `~/.dario/oauth-config.override.json` |
+| `DARIO_OAUTH_DISABLE_OVERRIDE=1` | Ignore env/file OAuth overrides entirely | unset |
+
+## Endpoints
+
+| Path | Description |
+|---|---|
+| `POST /v1/messages` | Anthropic Messages API (Claude backend) |
+| `POST /v1/chat/completions` | OpenAI-compatible Chat API (routes by model name) |
+| `GET /v1/models` | Model list (Claude models — OpenAI models come from the OpenAI backend directly) |
+| `GET /health` | Proxy health + OAuth status + request count |
+| `GET /status` | Detailed Claude OAuth token status |
+| `GET /accounts` | Pool snapshot including sticky binding count (pool mode only) |
+| `GET /analytics` | Per-account / per-model stats, burn rate, exhaustion predictions, `billingBucket` + `subscriptionPercent` per request |

package/docs/configuration.md

@@ -0,0 +1,109 @@
+# Configuration
+
+Every knob below is settable three ways. Precedence, highest first:
+
+1. a CLI flag
+2. an environment variable
+3. `~/.dario/config.json`
+4. the built-in default
+
+`dario --help` is the complete list and always matches the binary you have installed. [`commands.md`](./commands.md) documents the proxy options flag-by-flag, including the OAuth overrides, session-rotation and TLS vars not repeated here.
+
+This page is the other view: grouped by what you are trying to do, covering the vars that matter when you cannot pass a flag — Docker, Compose, k8s, systemd — plus the ones whose behaviour has a sharp edge worth stating in prose. Anything documented in `commands.md` is deliberately not restated here; two copies of a default is one that goes stale.
+
+## Booleans
+
+Two shapes, and the difference is not cosmetic.
+
+**Off-switches** (`DARIO_OVERAGE_GUARD`, `DARIO_OVERAGE_NOTIFY`) accept `on|1|true|yes` and `off|0|false|no`. They guard features that default **on**, so they have to be able to say no.
+
+**On-switches** (everything else) accept only `1|true|yes|on`. They guard features that default **off**, so an unset var and a falsy var mean the same thing and there is nothing to express.
+
+An unrecognised value is ignored in both cases and the next source down wins. A typo leaves you on the default rather than silently flipping the knob.
+
+> `DARIO_OVERAGE_GUARD=off` and `DARIO_OVERAGE_NOTIFY=off` were documented in `cli.ts` from v4.1 but did nothing until v5.4.14 — the shared parser could only return `true` or `undefined`, so `off` fell through the `?? … ?? true` chain and the guard stayed on. Container deployments were the only ones affected, because a flag was the sole working way to turn it off.
+
+## Overage guard
+
+Halts the proxy when an upstream response reports `representative-claim: overage`, so a subscription never silently starts billing per token. Defaults on. See [`#288`](https://github.com/askalf/dario/issues/288).
+
+| Variable | Flag | Default | Values |
+|---|---|---|---|
+| `DARIO_OVERAGE_GUARD` | `--no-overage-guard` | on | off-switch |
+| `DARIO_OVERAGE_BEHAVIOR` | `--overage-behavior=` | `halt` | `halt` returns 503 until cooldown or `dario resume`; `warn` logs and keeps serving |
+| `DARIO_OVERAGE_COOLDOWN` | `--overage-cooldown=MS` | `1800000` (30 min) | ms |
+| `DARIO_OVERAGE_NOTIFY` | `--no-overage-notify` | on | off-switch; suppresses the desktop notification only |
+
+## Request queue
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `DARIO_MAX_CONCURRENT` | `--max-concurrent=N` | `10` | in-flight ceiling |
+| `DARIO_MAX_QUEUED` | `--max-queued=N` | `128` | buffered waiting for a slot; over this, dario returns 429 `queue-full` |
+| `DARIO_QUEUE_TIMEOUT_MS` | `--queue-timeout=MS` | `60000` | a queued request waiting longer gets 504 `queue-timeout` |
+
+## Template fidelity
+
+dario replays Claude Code's wire shape from a template it captures from your installed `claude` binary, falling back to a baked snapshot. These two make the unsafe states require intent ([`#77`](https://github.com/askalf/dario/issues/77)).
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `DARIO_NO_LIVE_CAPTURE` | `--no-live-capture` | off | Never spawn the installed CC; use the baked snapshot only. For air-gapped and reproducible-build runs. |
+| `DARIO_STRICT_TEMPLATE` | `--strict-template` | off | Refuse to start if the live capture never succeeded or drifts from the installed CC version. |
+
+## Client shape
+
+Off by default, each one a deliberate divergence from what real CC sends.
+
+| Variable | Flag | Notes |
+|---|---|---|
+| `DARIO_STEALTH` | `--stealth` | Behavioural-stealth preset. Per-knob pacing vars below still win, so you can flip this on and tune one axis. |
+| `DARIO_HONOR_CLIENT_THINKING` | `--honor-client-thinking` | Pass a client's own `thinking` block through unchanged. |
+| `DARIO_PRESERVE_OUTPUT_FORMAT` | `--preserve-output-format` | Carry a client's `output_config.format` schema through, for structured-output SDKs. |
+| `DARIO_PRESERVE_ORCHESTRATION_TAGS` | `--preserve-orchestration-tags` | Keep orchestration tags instead of stripping them ([`#78`](https://github.com/askalf/dario/issues/78)). |
+| `DARIO_EFFORT` | `--effort=` | Forces a reasoning-effort level. Can flip requests to overage billing — watch `-v` logs for representative-claim changes ([`#87`](https://github.com/askalf/dario/issues/87)). |
+| `DARIO_MAX_TOKENS` | `--max-tokens=` | Anthropic enforces the per-model ceiling server-side, so too-high values return a clean 400 ([`#88`](https://github.com/askalf/dario/issues/88)). |
+
+## Pacing
+
+Only meaningful with stealth, and all default to 0 (off) except the cap. See [`wire-fidelity.md`](./wire-fidelity.md).
+
+| Variable | Flag | Default |
+|---|---|---|
+| `DARIO_THINK_TIME_BASE_MS` | `--think-time-base=MS` | `0` |
+| `DARIO_THINK_TIME_PER_TOKEN_MS` | `--think-time-per-token=MS` | `0` |
+| `DARIO_THINK_TIME_JITTER_MS` | `--think-time-jitter=MS` | `0` |
+| `DARIO_THINK_TIME_MAX_MS` | `--think-time-max=MS` | `30000` |
+| `DARIO_SESSION_START_MIN_MS` | `--session-start-min=MS` | `0` |
+| `DARIO_SESSION_START_JITTER_MS` | `--session-start-jitter=MS` | `0` |
+
+## Pool and routing
+
+The pool-strategy, fallback-model, alias and upstream-proxy vars live in [`commands.md`](./commands.md).
+
+| Variable | Flag | Notes |
+|---|---|---|
+| `DARIO_SUSPENDED_MODELS` | — | Filters families from `/v1/models` so it never advertises a model that 404s. |
+| `DARIO_SKIP_FIELDS` | `--skip-fields=CSV` | Drop named fields from the outbound body. |
+
+## Networking and caches
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `DARIO_DNS_RESULT_ORDER` | — | `ipv4first` | `verbatim` uses the resolver's own order. IPv4-first because an IPv6 answer is not universally routable. |
+| `DARIO_MODEL_CATALOG_TTL_MS` | — | `3600000` (1h) | How long `/v1/models` caches Anthropic's live catalog. Model launches are rare; shorten it if you are chasing one. |
+| `DARIO_USAGE_PORT` | `--port=N` | `3456` | Which proxy the `dario usage` subcommand queries. |
+
+## Escape hatches
+
+Reversible switches for behaviour that is normally correct. You should not need them; they exist so a bad guess on our side is not fatal.
+
+| Variable | Values | Notes |
+|---|---|---|
+| `DARIO_CCH` | `random` | Stops replaying a calibrated `cch` token in the billing tag and randomises it per request instead. Only affects CC versions we hold a seed for — current CC sends no `cch` at all, so dario omits it and this does nothing. |
+
+## Not part of the supported surface
+
+`DARIO_LIVE_TEMPLATE_CACHE` and `DARIO_TEST_URL` exist for the test suite. They are not configuration, are not covered by semver, and can change or vanish in a patch release.
+
+If an unsupported var is the only way to do something you need, that is a missing flag. Open an issue.