@askalf/dario 3.27.0 → 3.29.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <h1 align="center">dario</h1>
-  <p align="center"><strong>A universal LLM router that runs on your machine.<br>One local endpoint, every provider — Anthropic, OpenAI, Groq, OpenRouter, Ollama, any OpenAI-compat URL. Your tools point here and stop caring which vendor is upstream.</strong></p>
+  <p align="center"><strong>A universal LLM router that runs on your machine.<br>One local endpoint, every provider — Anthropic, OpenAI, Groq, OpenRouter, Ollama, any OpenAI-compat URL. Point your tools at localhost and stop caring which vendor is upstream.</strong></p>
 </p>
 
 <p align="center">
@@ -26,7 +26,7 @@ One command, one local URL, every provider behind it. Point `ANTHROPIC_BASE_URL`
 - `llama-3.3-70b`, `deepseek-v3`, anything else → **Groq**, **OpenRouter**, **local LiteLLM**, **vLLM**, **Ollama**, whichever OpenAI-compat backend you wired up
 - Force a backend explicitly with a prefix: `openai:gpt-4o`, `groq:llama-3.3-70b`, `local:qwen-coder`, `claude:opus`
 
-Switching providers is a **model-name change** in your tool. Not a reconfigure. Not new base URLs. Not new API keys. Not a new SDK import. **Zero runtime dependencies. ~8,100 lines of TypeScript across ~15 files. ~840 assertions across 24 test suites. [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) on every release. Nothing phones home, ever.**
+Switching providers is a **model-name change** in your tool. Not a reconfigure. Not new base URLs. Not new API keys. Not a new SDK import. **Zero runtime dependencies. ~11,300 lines of TypeScript across ~25 files. ~1,250 assertions across 32 test suites. [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) on every release. Nothing phones home, ever.**
 
 ---
 
@@ -44,6 +44,8 @@ You point every tool at one URL. Dario reads each request, decides which backend
 
 The tool doesn't know. The backend doesn't know. Dario is the seam.
 
+Beyond routing, the Claude backend is a **full wire-level Claude Code replay** — every observable axis (bytes, headers, body key order, TLS stack, inter-request timing, session-id lifecycle, stream-consumption shape) is captured from your installed CC binary and replayed on outbound requests so Anthropic's classifier sees a CC session. See [Claude subscription backend](#2-claude-subscription-backend) and [Fingerprint axes](#fingerprint-axes).
+
 ---
 
 ## Quick start
@@ -57,6 +59,8 @@ npm install -g @askalf/dario
 # 1. Claude via your Claude Max / Pro subscription (uses your Claude Code
 #    OAuth if CC is installed; runs its own OAuth flow otherwise)
 dario login
+#    or, for SSH / container setups with no browser:
+dario login --manual
 
 # 2. OpenAI or any OpenAI-compat endpoint
 dario backend add openai     --key=sk-proj-...
@@ -76,25 +80,29 @@ export OPENAI_API_KEY=dario
 
 That's it. Every tool that honors these standard env vars now reaches every backend you configured. No per-tool reconfiguration. No SDK changes. One URL, one fake key, every real provider behind it.
 
-Something broken? `dario doctor` prints a single aggregated health report — dario version, Node, platform, CC binary compat, template source + age + drift, OAuth status, pool state, configured backends. Paste that instead of screenshots when you file an issue.
+Something broken? `dario doctor` prints a single aggregated health report — dario version, Node, platform, runtime/TLS classification, CC binary compat, template source + age + drift, OAuth status, pool state, configured backends, sub-agent install state. Paste that instead of screenshots when you file an issue.
 
 ---
 
 ## Why you'll install this
 
-**You want one URL for every provider.** Cursor, Aider, Continue, Zed, OpenHands, Claude Code, your own scripts — every tool you own has its own per-provider config. Dario collapses that into a single `localhost:3456` that speaks both Anthropic and OpenAI protocols and routes by model name. Switching providers is a model-name change in your tool, not a reconfigure of every SDK on your laptop.
+**You want one URL for every provider.** Cursor, Aider, Continue, Zed, OpenHands, Claude Code, your own scripts — every tool you own has its own per-provider config. Dario collapses that into a single `localhost:3456` that speaks both Anthropic and OpenAI protocols and routes by model name.
 
-**You pay for Claude Max but only use it in Claude Code.** Cursor, Aider, Zed, Continue — they all want API keys and bill per-token while your $200/mo subscription sits idle. Dario's Claude backend routes requests from all of them through your plan by replaying the exact Claude Code wire shape (template, tools, headers, billing tag) that Anthropic's classifier expects for subscription billing. Section [Claude subscription backend](#2-claude-subscription-backend) has the full mechanics.
+**You pay for Claude Max but only use it in Claude Code.** Cursor, Aider, Zed, Continue — they all want API keys and bill per-token while your $200/mo subscription sits idle. Dario's Claude backend routes requests from all of them through your plan by replaying the exact Claude Code wire shape (template, tools, headers, body key order, billing tag) that Anthropic's classifier expects for subscription billing. See [Claude subscription backend](#2-claude-subscription-backend).
 
-**You hit rate limits on long agent runs.** Add a second / third Claude subscription with `dario accounts add work` and pool mode routes each request to whichever account has the most headroom. **Session stickiness** (v3.13.0) pins a multi-turn conversation to one account so the Anthropic prompt cache survives the run. **In-flight 429 failover** retries the same request against a different account before your client sees an error. See [Multi-account pool mode](#multi-account-pool-mode).
+**You hit rate limits on long agent runs.** Add a second / third Claude subscription with `dario accounts add work` and pool mode routes each request to whichever account has the most headroom. **Session stickiness** pins a multi-turn conversation to one account so the Anthropic prompt cache survives the run. **In-flight 429 failover** retries the same request against a different account before your client sees an error. See [Multi-account pool mode](#multi-account-pool-mode).
 
 **You run a coding agent that isn't Claude Code.** Cline, Roo Code, Cursor, Windsurf, Continue.dev, GitHub Copilot, OpenHands, OpenClaw, Hermes — they each ship their own tool schemas and their own validators. Dario's universal `TOOL_MAP` (**~66 schema-verified entries**) pre-maps every major coding agent's tool names to Claude Code's native set on the outbound path and rebuilds to your agent's exact expected shape on the inbound path. No `--preserve-tools`, no fingerprint loss, no validator errors. See [Agent compatibility](#agent-compatibility).
 
-**You want the proxy layer off the wire entirely.** **Shim mode** (v3.12, hardened in v3.13) is an in-process `globalThis.fetch` patch injected via `NODE_OPTIONS=--require`. No HTTP hop, no port to bind, no `BASE_URL` to set. `dario shim -- claude --print "hi"` and CC thinks it's talking directly to `api.anthropic.com`. See [Shim mode](#shim-mode).
+**You want the proxy layer off the wire entirely.** **Shim mode** is an in-process `globalThis.fetch` patch injected via `NODE_OPTIONS=--require`. No HTTP hop, no port to bind, no `BASE_URL` to set. `dario shim -- claude --print "hi"` and CC thinks it's talking directly to `api.anthropic.com`. See [Shim mode](#shim-mode).
+
+**You want dario itself addressable from inside Claude Code or any MCP client.** `dario subagent install` registers a first-party sub-agent under `~/.claude/agents/dario.md` so CC can delegate diagnostics and template-refresh in-session ([Claude Code sub-agent hook](#claude-code-sub-agent-hook-v326)). `dario mcp` turns dario itself into a read-only MCP server — Claude Desktop, Cursor, Zed, any MCP-aware editor can introspect dario's state (auth, pool, backends, template, fingerprint, runtime) without leaving the editor ([dario as MCP server](#dario-as-mcp-server-v327)).
+
+**You want to share capacity with a trusted group without surveilling each other.** The **sealed-sender overflow protocol** uses RSA blind signatures (Chaum 1983, implemented from scratch over Node's `crypto`) so members of a trust group can lend unused Claude capacity to each other with cryptographic unlinkability. Dario ships the primitive; [mux](https://github.com/askalf/mux) is the dedicated product around it. See [Sealed-sender overflow](#sealed-sender-overflow-protocol).
 
-**You want to share capacity with a trusted group without surveilling each other.** The **sealed-sender overflow protocol** (v3.13) uses RSA blind signatures (Chaum 1983, implemented from scratch over Node's `crypto`) so members of a trust group can lend unused Claude capacity to each other with cryptographic unlinkability. A lender verifies "this is a valid group member" without learning *which* member. Dario ships the primitive; [mux](https://github.com/askalf/mux) is the dedicated product around it (group admin, key distribution, member workflow, borrower CLI). See [Sealed-sender overflow](#sealed-sender-overflow-protocol).
+**You want certainty that the proxy isn't trivially fingerprintable.** The "get ahead of Anthropic" release track (v3.22 – v3.28) closed six observable divergence axes between dario and real Claude Code: body field order (v3.22), TLS ClientHello (v3.23), inter-request timing (v3.24), stream-consumption shape (v3.25), sub-agent/MCP reach (v3.26/v3.27), and session-id lifecycle (v3.28). See [Fingerprint axes](#fingerprint-axes).
 
-**You want to actually audit the thing.** ~7,600 lines of TypeScript across ~15 files. Zero runtime dependencies (`npm ls --production` confirms). Credentials at `~/.dario/` with `0600` permissions. `127.0.0.1`-only by default. Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions. Nothing phones home. Small enough to read in a weekend.
+**You want to actually audit the thing.** ~11,300 lines of TypeScript across ~25 files. Zero runtime dependencies (`npm ls --production` confirms). Credentials at `~/.dario/` with `0600` permissions. `127.0.0.1`-only by default. Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions. Nothing phones home. Small enough to read in a weekend.
 
 ---
 
@@ -107,6 +115,7 @@ Something broken? `dario doctor` prints a single aggregated health report — da
 - **Anyone building AI coding tools** who wants provider independence without writing an OpenAI ↔ Anthropic translator themselves.
 - **Claude Max / Pro subscribers** who want their subscription usable from every tool on their machine, not just Claude Code.
 - **Power users on multi-agent workloads** who want multi-account pooling, session stickiness, and in-flight 429 failover on their own machine, against their own subscriptions.
+- **Operators who care about wire-level fidelity** — the fingerprint tightening in v3.22 – v3.28 means proxy mode's divergence from CC is observable (via `dario doctor`) and tunable (flags + env vars for each axis).
 
 **Not a fit if:**
 
@@ -154,26 +163,43 @@ Force a backend with a **provider prefix** on the model field (`openai:gpt-4o`,
 
 ### 2. Claude subscription backend
 
-OAuth-backed Claude Max / Pro, billed against your plan instead of the API. Activated by `dario login`.
+OAuth-backed Claude Max / Pro, billed against your plan instead of the API. Activated by `dario login` (or `dario login --manual` for SSH / container setups without a browser, v3.20).
 
-**What it does.** Every outbound Claude request is rebuilt to look exactly like a request Claude Code itself would make — system prompt, tool definitions, fingerprint headers, billing tag, beta flags, **even the exact header insertion order and request-body key order** — using a live-extracted template from your actually-installed CC binary that self-heals on every Anthropic release. Anthropic's classifier sees a CC session because, from the wire up, it *is* one. That's what keeps your usage on subscription billing instead of API overage.
+**What it does.** Every outbound Claude request is rebuilt to look exactly like a request Claude Code itself would make — system prompt, tool definitions, fingerprint headers, billing tag, beta flags, **header insertion order, static header values, `anthropic-beta` flag set, and top-level request-body key order** — using a live-extracted template from your actually-installed CC binary that self-heals on every Anthropic release. Anthropic's classifier sees a CC session because, from the wire up, it *is* one. That's what keeps your usage on subscription billing instead of API overage.
 
 **Key mechanisms:**
 
-- **Live fingerprint extraction** (v3.11). Dario spawns your installed `claude` binary against a loopback MITM endpoint on startup, captures its outbound request, and extracts the live template (system prompt, tools, user-agent, beta flags, **header insertion order** as of v3.13 replayed by the shim since v3.13 and the proxy since v3.16, **static header values** + **`anthropic-beta` flags** as of v3.19, and **top-level request-body key order** as of v3.22). Eliminates the "Anthropic ships a new CC, dario is stale for 48 hours" window. Cached at `~/.dario/cc-template.live.json` with a 24h TTL. Falls back to the bundled snapshot if CC isn't installed; the bundled snapshot is scrubbed of host-identifying paths at bake time (v3.21).
+- **Live fingerprint extraction.** Dario spawns your installed `claude` binary against a loopback MITM endpoint on startup, captures its outbound request, and extracts the live template — system prompt, tools, user-agent, beta flags, **header insertion order** (replayed by the shim since v3.13 and the proxy since v3.16), **static header values** and **`anthropic-beta` flag set** (v3.19), and **top-level request-body key order** (v3.22, schema v3). Eliminates the "Anthropic ships a new CC, dario is stale for 48 hours" window. Cached at `~/.dario/cc-template.live.json` with a 24h TTL. Falls back to the bundled snapshot if CC isn't installed; the bundled snapshot is scrubbed of host-identifying paths and `mcp__*` tool names at bake time (v3.21 — see `src/scrub-template.ts`).
 - **Drift detection** (v3.17). On startup dario probes the installed `claude` binary and compares against the captured template. Mismatch triggers a forced refresh and prints a one-line warning. Users never silently sit on a stale template again.
-- **Compat matrix** (v3.17). `SUPPORTED_CC_RANGE = { min: "1.0.0", maxTested: "2.1.104" }` is encoded in code. Installed CC outside that band prints a warn (untested above) or fail (below min) — zero-dep dotted-numeric comparator, no `semver` import per the dep policy.
+- **Compat matrix** (v3.17, bumped in v3.19.5). `SUPPORTED_CC_RANGE` is encoded in code; installed CC outside the band prints a warn (untested above) or fail (below min) — zero-dep dotted-numeric comparator, no `semver` import per the dep policy.
 - **Billing tag** reconstructed using CC's own algorithm: `x-anthropic-billing-header: cc_version=<version>.<build_tag>; cc_entrypoint=cli; cch=<5-char-hex>;` where `build_tag = SHA-256(seed + chars[4,7,20] of user message + version).slice(0,3)`.
-- **OAuth config auto-detection** from the installed CC binary. When Anthropic rotates `client_id`, authorize URL, or scopes, dario picks up the new values on the next run without needing a release.
+- **OAuth config auto-detection** from the installed CC binary. When Anthropic rotates `client_id`, authorize URL, or scopes, dario picks up the new values on the next run without needing a release. Cache at `~/.dario/cc-oauth-cache-v4.json`, keyed by the CC binary fingerprint.
 - **Multi-account pool mode** — see [Multi-account pool mode](#multi-account-pool-mode). Automatic when 2+ accounts are configured.
 - **Framework scrubbing** — known fingerprint tokens (`OpenClaw`, `sessions_*` prefixes, orchestration tags) stripped from system prompt and message content before the request leaves your machine.
 - **Atomic cache writes + cache corruption recovery** (v3.17). Template cache writes go through pid-qualified `.tmp` + `rename`, so an OS crash mid-write doesn't leave a half-written file. Unparseable cache files get quarantined to `cc-template.live.json.bad-<timestamp>` and dario self-heals on the next capture.
 - **OAuth single-flight** (v3.17). Two concurrent refreshes for the same account alias now share one outbound `POST /oauth/token`, so the pool's background refresh timer and a user-triggered request at the same millisecond can't race and invalidate each other's refresh token.
-- **Bun auto-relaunch** — when Bun is installed, dario relaunches under it so the TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js.
+- **Bun auto-relaunch.** When Bun is installed, dario relaunches under it so the TLS ClientHello matches CC's runtime (Bun uses BoringSSL; Node uses OpenSSL — distinct JA3/JA4 hashes). Without Bun, dario runs on Node.js — `dario doctor` surfaces the mismatch as of v3.23 and `--strict-tls` refuses to start proxy mode until it's resolved.
 
 **Passthrough mode** (`dario proxy --passthrough`) does an OAuth swap and nothing else — no template, no identity, no scrubbing. Use it when the upstream tool already builds a Claude-Code-shaped request on its own.
 
-**Detection scope.** The Claude backend is a per-request layer. Template replay and scrubbing are designed to be indistinguishable from CC at the request level. What they *cannot* defend against is Anthropic's session-level behavioral classifier, which operates on cumulative per-OAuth aggregates (token throughput, conversation depth, streaming duration, inter-arrival timing). The practical answer is **pool mode** — distribute load across multiple subscriptions so no single account accumulates enough signal to trip anything.
+**Detection scope.** The Claude backend is a per-request layer. Template replay and scrubbing are designed to be indistinguishable from CC at the request level. What they *cannot* defend against on their own is Anthropic's session-level behavioral classifier, which operates on cumulative per-OAuth aggregates. The v3.22 – v3.28 "get ahead of Anthropic" track closed six of those cumulative axes (body order, TLS, pacing, stream-drain, session-id lifecycle, MCP/sub-agent surface); for anything left, **pool mode** distributes load across multiple subscriptions so no single account accumulates enough signal to trip anything.
+
+---
+
+## Fingerprint axes
+
+Between v3.22 and v3.28, dario's Claude backend closed six axes along which a proxy can look different from real Claude Code. Each is a separate knob, each ships with its own test suite, each is surfaced through `dario doctor` where the axis has something to report. Defaults are chosen so existing setups don't regress.
+
+| Axis | Release | What it does | How to tune |
+|---|---|---|---|
+| **Request body key order** | v3.22 | Top-level JSON key order of the outbound `/v1/messages` body is captured from CC's wire serialization and replayed byte-for-byte. Schema bumped v2 → v3; stale caches quarantined. | Automatic once a live capture exists. The baked fallback carries a v2.1.112 snapshot. |
+| **Runtime / TLS ClientHello** | v3.23 | Classifies the runtime as `bun-match` / `bun-bypassed` / `node-only` and surfaces the class + hint in `dario doctor`. Bun yields the BoringSSL ClientHello CC presents; Node yields OpenSSL's (distinct JA3). | `--strict-tls` (or `DARIO_STRICT_TLS=1`) refuses to start proxy mode unless `bun-match`. `DARIO_QUIET_TLS=1` silences the startup banner in known-fine environments. |
+| **Inter-request timing** | v3.24 | Replaces the hardcoded 500 ms floor with a configurable floor + uniform jitter. A 500 ms minimum-inter-arrival edge is fingerprintable at scale; jitter dissolves the edge. | `--pace-min=MS`, `--pace-jitter=MS`, or `DARIO_PACE_MIN_MS` / `DARIO_PACE_JITTER_MS`. Legacy `DARIO_MIN_INTERVAL_MS` still honored. |
+| **Stream-consumption shape** | v3.25 | When a downstream client disconnects mid-stream, CC keeps reading SSE to EOF. Dario now offers the same: drain upstream to completion even when the consumer has left. Default off — don't silently burn tokens. | `--drain-on-close` / `DARIO_DRAIN_ON_CLOSE=1`. Bounded by the existing 5-minute upstream timeout. |
+| **Session-ID lifecycle** | v3.28 | Generalizes the v3.19 hardcoded 15-minute idle rotation into a tunable `SessionRegistry` with jitter, max-age, and per-client bucketing. Fixes a v3.27 body/header rotation race as a side effect. | `--session-idle-rotate=MS` (default 900000), `--session-rotate-jitter=MS`, `--session-max-age=MS`, `--session-per-client`. Env mirrors `DARIO_SESSION_*`. Defaults are bit-identical to v3.27. |
+| **MCP / sub-agent reach** | v3.26 + v3.27 | Not a wire axis — a *surface* axis. CC-aware tools can now address dario directly (sub-agent from inside CC, MCP server for any MCP client), so operators don't have to switch terminals to introspect the proxy. Read-only by design. | `dario subagent install` / `dario mcp`. See dedicated sections below. |
+
+The six-direction "get ahead of Anthropic" roadmap is complete. Subsequent releases return to responding to issues and upstream template drift.
 
 ---
 
@@ -197,7 +223,7 @@ headroom = 1 - max(util_5h, util_7d)
 
 The response's `anthropic-ratelimit-unified-*` headers are parsed back into the pool so the next selection sees fresh utilization. An account that returns a 429 is marked `rejected` and routed around until its window resets. When every account is exhausted, requests queue for up to 60 seconds waiting for headroom to reappear. Plans can mix freely — Max and Pro accounts sit in the same pool; dario doesn't care about tier, only headroom.
 
-### Session stickiness (v3.13)
+### Session stickiness
 
 Multi-turn agent sessions pin to one account for the life of the conversation, so the Anthropic prompt cache isn't destroyed by account rotation between turns.
 
@@ -205,7 +231,7 @@ Multi-turn agent sessions pin to one account for the life of the conversation, s
 
 **The fix.** Dario hashes a conversation's first user message into a 16-hex-char `stickyKey` (SHA-256 truncated, deterministic) and binds the key to whichever account `select()` would have picked on turn 1. Subsequent turns re-use that account as long as it's still healthy (not rejected, token not near expiry, headroom > 2%). On 429 failover, dario rebinds the key to the new account so the next turn doesn't re-select the exhausted one. 6h TTL, 2,000-entry cap, lazy cleanup. No client cooperation required.
 
-### In-flight 429 failover (v3.8+)
+### In-flight 429 failover
 
 When a Claude request hits a 429 mid-flight, dario retries the *same request* against a different account before the client sees an error. The client sees one successful response; the pool sees the rejected account go cold until its window resets. Combined with session stickiness, long agent runs survive pool-level exhaustion without dropping user-facing turns.
 
@@ -220,7 +246,7 @@ Every request carries a `billingBucket` field (`subscription` / `subscription_fa
 
 ---
 
-## Sealed-sender overflow protocol (v3.13)
+## Sealed-sender overflow protocol
 
 Trust-group members can lend each other Claude capacity with **cryptographic unlinkability**: a lender can verify the borrower is a valid group member without learning *which* member, so no one in the pool can surveil another through borrow telemetry.
 
@@ -255,7 +281,7 @@ Under the hood: `dario shim` spawns the child with `NODE_OPTIONS=--require <dari
 
 **Why it matters.** Anthropic can fingerprint a proxy via TLS, headers, IP, or `BASE_URL` env. They literally cannot easily detect a `globalThis.fetch` monkey-patch from inside their own process without shipping signed-binary integrity checks against `globalThis` from inside the CC binary — and even then, the shim runs *before* CC's code loads, so it could patch the integrity check too. The longest-half-life transport against classifier evolution.
 
-**v3.13 hardening** added runtime detection (canary for the day Anthropic ships a Bun-compiled CC), template mtime-based auto-reload (long-running children pick up mid-session fingerprint refreshes without restart), strict defensive `rewriteBody` (requires exactly 3 text blocks, passes through on any mismatch instead of inventing structure), and header-order replay (honors captured CC header sequence so the shim matches CC wire-exact).
+**Hardening (v3.13+)** added runtime detection (canary for the day Anthropic ships a Bun-compiled CC), template mtime-based auto-reload (long-running children pick up mid-session fingerprint refreshes without restart), strict defensive `rewriteBody` (requires exactly 3 text blocks, passes through on any mismatch instead of inventing structure), and header-order replay (honors captured CC header sequence so the shim matches CC wire-exact).
 
 **When to use shim mode:**
 - Running a single CC instance on a locked-down machine where binding a local port is inconvenient.
@@ -272,12 +298,12 @@ Under the hood: `dario shim` spawns the child with `NODE_OPTIONS=--require <dari
 
 ## Agent compatibility
 
-As of **v3.22**, dario's built-in `TOOL_MAP` carries **~66 schema-verified entries** covering the tool schemas of every major coding agent. On the Claude backend, tool calls translate to CC's native `Bash / Read / Write / Edit / Glob / Grep / WebSearch / WebFetch` on the outbound path (keeping the subscription fingerprint intact) and rebuild to your agent's exact expected shape on the inbound path (so your validator is happy). No flag required.
+Dario's built-in `TOOL_MAP` carries **~66 schema-verified entries** covering the tool schemas of every major coding agent. On the Claude backend, tool calls translate to CC's native `Bash / Read / Write / Edit / Glob / Grep / WebSearch / WebFetch` on the outbound path (keeping the subscription fingerprint intact) and rebuild to your agent's exact expected shape on the inbound path (so your validator is happy). No flag required.
 
 | Agent | Covered tool names (subset) |
 |---|---|
 | Claude Code | default — CC's own tools |
-| Cline / Roo Code | `execute_command`, `write_to_file`, `replace_in_file`, `apply_diff`, `list_files`, `search_files`, `read_file` |
+| Cline / Roo Code / Kilo Code | `execute_command`, `write_to_file`, `replace_in_file`, `apply_diff`, `list_files`, `search_files`, `read_file` |
 | Cursor | `run_terminal_cmd`, `edit_file`, `search_replace`, `codebase_search`, `grep_search`, `file_search`, `list_dir`, `read_file` (`target_file`) |
 | Windsurf | `run_command`, `view_file`, `write_to_file`, `replace_file_content`, `find_by_name`, `grep_search`, `list_dir`, `search_web`, `read_url_content` |
 | Continue.dev | `builtin_run_terminal_command`, `builtin_read_file`, `builtin_create_new_file`, `builtin_edit_existing_file`, `builtin_file_glob_search`, `builtin_grep_search`, `builtin_ls` |
@@ -286,29 +312,70 @@ As of **v3.22**, dario's built-in `TOOL_MAP` carries **~66 schema-verified entri
 | OpenClaw | `exec`, `process`, `web_search`, `web_fetch`, `browser`, `message` |
 | Hermes | `terminal`, `patch`, `web_extract`, `clarify` |
 
-If your agent's tool names aren't pre-mapped, there are two escape hatches: **`--preserve-tools`** (forward your schema verbatim, lose the CC fingerprint) or **`--hybrid-tools`** (keep the fingerprint, fill request-context fields from headers). See [Custom tool schemas](#custom-tool-schemas).
+Text-tool clients (Cline / Kilo Code / Roo Code and forks) are auto-detected via system-prompt fingerprint and automatically flipped into preserve-tools mode, because mixing CC's `tools` array with their XML protocol makes the model emit `<function_calls><invoke>` that their parsers can't read. If you run dario specifically for fingerprint fidelity and would rather pick `--preserve-tools` yourself, `--no-auto-detect` (v3.20.1, aka `--no-auto-preserve`) disables the heuristic — explicit operator choice then wins.
+
+If your agent's tool names aren't pre-mapped and its tools carry fields CC's schema doesn't have, there are two escape hatches: **`--preserve-tools`** (forward your schema verbatim, lose the CC fingerprint) or **`--hybrid-tools`** (keep the fingerprint, fill request-context fields from headers). See [Custom tool schemas](#custom-tool-schemas).
 
 The OpenAI-compat backend forwards tool definitions byte-for-byte and doesn't need any of this.
 
 ---
 
+## dario as MCP server (v3.27)
+
+`dario mcp` turns dario itself into a **stdio JSON-RPC 2.0 MCP server**. Claude Desktop, Cursor, Zed, any MCP-aware editor can introspect dario's state without leaving the editor.
+
+```bash
+dario mcp        # spawns the MCP server on stdin/stdout — wire it up to your MCP client
+```
+
+**Strictly read-only.** The exposed tool set is:
+
+| Tool | What it reports |
+|---|---|
+| `doctor` | Full aggregated health report — same output as `dario doctor` |
+| `status` | OAuth authentication state (authenticated / no-credentials / expired-but-refreshable) |
+| `accounts_list` | Pool accounts + expiry times. Never touches API keys. |
+| `backends_list` | Configured OpenAI-compat backends — keys redacted completely (not even a `sk-…` prefix) |
+| `subagent_status` | CC sub-agent install and version-match state |
+| `fingerprint_info` | Runtime / TLS classification, template source + schema version |
+
+Mutations (`login`, `logout`, `accounts add/remove`, `backend add/remove`, `subagent install/remove`, `proxy` start/stop) are **not** exposed. An MCP client can observe dario; changing dario's state stays a CLI action the user types with intent. The test suite asserts the forbidden-tool set stays forbidden so a future accidental drift gets caught.
+
+Zero runtime deps — the JSON-RPC dispatcher is hand-rolled over Node's `readline`. `src/mcp/protocol.ts` + `src/mcp/tools.ts` + `src/mcp/server.ts` are each pure over their inputs (streams are injectable, data sources are injectable) so the e2e test runs in-process against a `PassThrough` pair.
+
+---
+
+## Claude Code sub-agent hook (v3.26)
+
+`dario subagent install` writes `~/.claude/agents/dario.md` so Claude Code has a named handle for running dario diagnostics and template-refresh inside an ongoing CC session. No more `Ctrl+Z → dario doctor → fg` when you hit a `[WARN]` row mid-conversation.
+
+```bash
+dario subagent install    # writes ~/.claude/agents/dario.md
+dario subagent status     # {not-installed, installed+current, installed+stale} + hint
+dario subagent remove     # idempotent
+```
+
+**Tool-scoped.** The sub-agent is restricted to `Bash, Read` and its prompt forbids destructive operations (credential mutation, account pool changes, backend config changes) without explicit user confirmation. `dario proxy` is also off-limits from inside the sub-agent — it would block the parent CC session. CC can ask dario to *report*, not to *change state*. (MCP server has the same read-only boundary for the same reason.)
+
+A version marker (`<!-- dario-sub-agent-version: X -->`) embedded in the markdown lets `dario doctor` distinguish installed-and-current from installed-and-stale; the "Sub-agent" row appears between Backends and Home with an inline refresh command when stale.
+
+---
+
 ## Commands
 
 | Command | Description |
 |---|---|
-| `dario login` | Log in to the Claude backend (detects CC credentials or runs its own OAuth flow) |
+| `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` | Aggregated health report — dario / Node / CC binary + compat / template + drift / OAuth / pool / backends |
+| `dario doctor` | Aggregated health report — dario / Node / runtime-TLS / CC binary + compat / template + drift / OAuth / pool / backends / sub-agent |
 | `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` | List accounts in the multi-account pool |
-| `dario accounts add <alias>` | Add a Claude account to the pool (runs OAuth flow) |
-| `dario accounts remove <alias>` | Remove an account from the pool |
-| `dario backend list` | List configured OpenAI-compat backends |
-| `dario backend add <name> --key=<key> [--base-url=<url>]` | Add an OpenAI-compat backend |
-| `dario backend remove <name>` | Remove an OpenAI-compat backend |
+| `dario accounts list` / `add <alias>` / `remove <alias>` | Multi-account pool management |
+| `dario backend list` / `add <name> --key=<key> [--base-url=<url>]` / `remove <name>` | OpenAI-compat backend management |
 | `dario shim -- <cmd> [args...]` | Run a child process with the in-process fetch patch (see [Shim mode](#shim-mode)) |
+| `dario subagent install` / `remove` / `status` | CC sub-agent lifecycle (v3.26 — see [sub-agent hook](#claude-code-sub-agent-hook-v326)) |
+| `dario mcp` | Run dario as an MCP server over stdio (v3.27 — see [dario as MCP server](#dario-as-mcp-server-v327)) |
 | `dario help` | Full command reference |
 
 ### Proxy options
@@ -316,17 +383,27 @@ The OpenAI-compat backend forwards tool definitions byte-for-byte and doesn't ne
 | 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](#custom-tool-schemas). Auto-enabled for Cline / Kilo Code / Roo Code and forks (dario#40 — detected via system-prompt fingerprint). | off (auto for text-tool clients) |
-| `--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](#hybrid-tool-mode). Overrides the text-tool auto-detect. | off |
-| `--model=<name>` | Force a model. Shortcuts (`opus`, `sonnet`, `haiku`), full IDs (`claude-opus-4-7`), or a **provider prefix** (`openai:gpt-4o`, `groq:llama-3.3-70b`, `claude:opus`, `local:qwen-coder`) to force the backend server-wide. See [Provider prefix](#provider-prefix). | passthrough |
+| `--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](#custom-tool-schemas). Auto-enabled for Cline / Kilo Code / Roo Code and forks (detected via system-prompt fingerprint). | off (auto for text-tool clients) |
+| `--no-auto-detect` / `--no-auto-preserve` | Disable the text-tool-client detector so the CC fingerprint 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](#hybrid-tool-mode). | off |
+| `--model=<name>` | Force a model. Shortcuts (`opus`, `sonnet`, `haiku`), full IDs (`claude-opus-4-7`), or a **provider prefix** (`openai:gpt-4o`, `groq:llama-3.3-70b`, `claude:opus`, `local:qwen-coder`) to force the backend server-wide. | passthrough |
 | `--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 (dario#40). | 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 |
+| `--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 [Fingerprint axes](#fingerprint-axes). (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 fingerprint 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 |
 | `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` | Minimum ms between Claude-backend requests (rate governor) | `500` |
+| `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 |
 
 ---
@@ -418,17 +495,15 @@ curl http://localhost:3456/v1/chat/completions \
 
 ### Streaming, tool use, prompt caching, extended thinking
 
-All supported. Claude backend: full Anthropic SSE format plus OpenAI-SSE translation for tool_use streaming. OpenAI-compat backend: streaming body forwarded byte-for-byte.
+All supported. Claude backend: full Anthropic SSE format plus OpenAI-SSE translation for tool_use streaming. OpenAI-compat backend: streaming body forwarded byte-for-byte. See [Fingerprint axes](#fingerprint-axes) for the v3.25 `--drain-on-close` knob that matches CC's read-to-EOF stream-consumption pattern.
 
 ### Provider prefix
 
-Any request's `model` field can be written as `<provider>:<name>` to force which backend handles it, regardless of what the model name looks like. Useful when regex-based routing (`gpt-*` → OpenAI, `claude-*` → Claude) doesn't match — for example routing a `llama-3.3-70b` request through OpenRouter, or making the same model name go to different providers on different requests.
-
-Recognized prefixes:
+Any request's `model` field can be written as `<provider>:<name>` to force which backend handles it, regardless of what the model name looks like.
 
 | Prefix | Backend |
 |---|---|
-| `openai:` | OpenAI-compat backend (the configured one) |
+| `openai:` | OpenAI-compat backend |
 | `groq:` | OpenAI-compat backend |
 | `openrouter:` | OpenAI-compat backend |
 | `local:` | OpenAI-compat backend |
@@ -452,7 +527,7 @@ Fix: run dario with `--preserve-tools`. That skips the CC tool remap entirely, p
 dario proxy --preserve-tools
 ```
 
-The cost: requests no longer look like CC on the wire, so the CC subscription fingerprint is gone. On a Max/Pro plan, that means the request may be counted against your API usage rather than your subscription quota. If you're on API-key billing already, `--preserve-tools` is free; if you're using dario specifically to route against a subscription, [hybrid tool mode](#hybrid-tool-mode) below is the compromise that keeps both.
+The cost: requests no longer look like CC on the wire, so the CC subscription fingerprint is gone. On a Max/Pro plan, that means the request may be counted against your API usage rather than your subscription quota. [Hybrid tool mode](#hybrid-tool-mode) below is the compromise that keeps both.
 
 The OpenAI-compat backend is unaffected — it forwards tool definitions byte-for-byte and doesn't need this flag.
 
@@ -474,6 +549,7 @@ dario proxy --hybrid-tools
 | Your custom fields are request context (session/request/channel/user ids, timestamps) | `--hybrid-tools` | Keeps the CC fingerprint *and* your validator is satisfied. |
 | Your custom fields need the model's reasoning (e.g. `confidence`, `reasoning_trace`, `tool_selection_rationale`) | `--preserve-tools` | The model has to see the real schema to populate these. Accept the fingerprint loss. |
 | Your client's tools are already a subset of CC's `Bash/Read/Write/Edit/Grep/Glob/WebSearch/WebFetch` | *(neither)* | Default mode works as-is. |
+| You're on a text-tool client (Cline / Kilo Code / Roo Code) and want to override the auto-detect | `--no-auto-detect` (plus `--preserve-tools` or not, your call) | Operator choice outranks the heuristic. |
 
 ### Library mode
 
@@ -515,17 +591,18 @@ Dario handles your OAuth tokens and API keys locally. Here's why you can trust i
 
 | Signal | Status |
 |---|---|
-| **Source code** | ~8,100 lines of TypeScript across ~15 files — small enough to audit in a weekend |
+| **Source code** | ~11,300 lines of TypeScript across ~25 files — small enough to audit in a weekend |
 | **Dependencies** | 0 runtime dependencies. Verify: `npm ls --production` |
 | **npm provenance** | Every release is [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions with sigstore provenance attached to the transparency log |
 | **Security scanning** | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) runs on every push and weekly |
-| **Test footprint** | ~840 assertions across 24 files. Full `npm test` green on every release |
-| **Credential handling** | Tokens and API keys never logged, redacted from errors, stored with `0600` permissions |
-| **OAuth flow** | PKCE (Proof Key for Code Exchange), no client secret |
+| **Test footprint** | ~1,250 assertions across 32 test suites. Full `npm test` green on every release |
+| **Credential handling** | Tokens and API keys never logged, redacted from errors, stored with `0600` permissions. MCP server (v3.27) redacts keys at the tool boundary too — not even a `sk-…` prefix leaks. |
+| **OAuth flow** | PKCE (Proof Key for Code Exchange), no client secret. `--manual` flow for headless setups (v3.20). |
 | **Network scope** | Binds to `127.0.0.1` by default. `--host` allows LAN/mesh with `DARIO_API_KEY` gating. Upstream traffic goes only to the configured backend target URLs over HTTPS |
 | **SSRF protection** | `/v1/messages` hits `api.anthropic.com` only; `/v1/chat/completions` hits the configured backend `baseUrl` only — hardcoded allowlist |
-| **Telemetry** | None. Zero analytics, tracking, or data collection |
+| **Telemetry** | None. Zero analytics, tracking, or data collection. The MCP server (v3.27) and CC sub-agent (v3.26) are read-only by design — no tool can mutate dario's state from inside CC or an MCP client. |
 | **Atomic cache writes + corruption recovery** | v3.17 — template cache writes are pid-qualified `.tmp` + `rename`, corrupt cache files are quarantined and regenerated instead of crashing startup |
+| **Baked template scrub** | v3.21 — the bundled fallback template is stripped of host-identifying paths and `mcp__*` tool names at bake time; the nightly drift watcher guards against regression |
 | **Audit trail** | [CHANGELOG.md](CHANGELOG.md) documents every release with file-level rationale |
 
 Verify the npm tarball matches this repo:
@@ -550,10 +627,10 @@ Claude Max and Claude Pro. Any plan that lets you use Claude Code.
 Should work if your plan includes Claude Code access. Not widely tested yet — open an issue with results.
 
 **Do I need Claude Code installed?**
-Recommended for the Claude backend, not strictly required. With CC installed, `dario login` picks up your credentials automatically, and the live fingerprint extractor reads your CC binary on every startup so the template stays current. Without CC, dario runs its own OAuth flow and falls back to the bundled template snapshot. Drift detection (v3.17) warns you if your installed CC doesn't match the captured template, so upgrade windows don't silently ship stale templates.
+Recommended for the Claude backend, not strictly required. With CC installed, `dario login` picks up your credentials automatically, and the live fingerprint extractor reads your CC binary on every startup so the template stays current. Without CC, dario runs its own OAuth flow and falls back to the bundled template snapshot (scrubbed of host context at bake time as of v3.21). Drift detection warns you if your installed CC doesn't match the captured template, so upgrade windows don't silently ship stale templates.
 
 **Do I need Bun?**
-Optional, recommended for Claude-backend requests. Dario auto-relaunches under Bun when available so the TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js and works fine; the TLS fingerprint is the only difference.
+Optional, strongly recommended for Claude-backend requests. Dario auto-relaunches under Bun when available so the TLS ClientHello matches CC's runtime. Without Bun, dario runs on Node.js and works fine — the TLS fingerprint is the only difference. As of v3.23, `dario doctor` surfaces the mismatch explicitly and `--strict-tls` refuses to start proxy mode until it's resolved. The shim transport sidesteps this entirely (it runs inside CC's own process, so its TLS stack *is* CC's).
 
 **Can I use dario without a Claude subscription?**
 Yes. Skip `dario login`, just run `dario backend add openai --key=...` (or any OpenAI-compat URL) and `dario proxy`. Claude-backend requests will return an authentication error; OpenAI-compat requests will work normally. Dario becomes a local OpenAI-compat router with no Claude involvement.
@@ -562,13 +639,13 @@ Yes. Skip `dario login`, just run `dario backend add openai --key=...` (or any O
 Yes — anything that speaks the OpenAI Chat Completions API. Groq, OpenRouter, LiteLLM, vLLM, Ollama's openai-compat mode, your own vLLM server, any hosted inference endpoint that exposes `/v1/chat/completions`. Just `dario backend add <name> --key=... --base-url=...`.
 
 **Something's wrong. Where do I start?**
-`dario doctor`. One command, one aggregated report — dario version, Node, platform, CC binary compat, template source + age + drift, OAuth status, pool state, backends, home dir. Exit code 1 if any check fails. Paste the output when you file an issue.
+`dario doctor`. One command, one aggregated report — dario version, Node, platform, runtime/TLS classification, CC binary compat, template source + age + drift, OAuth status, pool state, backends, sub-agent install state, home dir. Exit code 1 if any check fails. Paste the output when you file an issue. (If you're inside Claude Code, `dario subagent install` once and then ask CC to "use the dario sub-agent to run doctor" — same output, no context switch.)
 
 **What happens when Anthropic rotates the OAuth config?**
-Dario auto-detects OAuth config from the installed Claude Code binary. When CC ships a new version with rotated values, dario picks them up on the next run. Cache at `~/.dario/cc-oauth-cache-v4.json`, keyed by the CC binary fingerprint.
+Dario auto-detects OAuth config from the installed Claude Code binary. When CC ships a new version with rotated values, dario picks them up on the next run. Cache at `~/.dario/cc-oauth-cache-v4.json`, keyed by the CC binary fingerprint. (Path bumped from v3 → v4 in v3.19.4 to invalidate stale caches across the scope-list change that broke the authorize flow between CC v2.1.104 and v2.1.107.)
 
 **What happens when Anthropic changes the CC request template?**
-Dario extracts the live request template from your installed Claude Code binary on startup — the system prompt, tool schemas, user-agent, beta flags, header insertion order, static header values, and top-level request-body key order — and uses those to replay requests instead of a version pinned into dario itself. When CC ships a new version with a tweaked template, the next `dario proxy` run picks it up automatically. Drift detection (v3.17) forces a refresh when the installed CC version changes under dario, and the nightly `cc-drift-watch` workflow catches upstream rotations (client_id, URLs, tool set, version) the day they ship on npm.
+Dario extracts the live request template from your installed Claude Code binary on startup — the system prompt, tool schemas, user-agent, beta flags, header insertion order, static header values, and top-level request-body key order — and uses those to replay requests instead of a version pinned into dario itself. When CC ships a new version with a tweaked template, the next `dario proxy` run picks it up automatically. Drift detection forces a refresh when the installed CC version changes under dario, and the nightly `cc-drift-watch` workflow catches upstream rotations (client_id, URLs, tool set, version) the day they ship on npm.
 
 **First time setup on a fresh Claude account.**
 If dario is the first thing you run against a brand-new Claude account, prime the account with a few real Claude Code commands first:
@@ -596,7 +673,10 @@ Seeing `seven_day` is a healthy state. Your Max/Pro plan is doing exactly what i
 Standalone writeup: [Discussion #32 — why you see `representative-claim: seven_day` and why it's not a downgrade](https://github.com/askalf/dario/discussions/32).
 
 **My multi-agent workload is getting reclassified to overage even though dario template-replays per request. Why?**
-Reclassification at high agent volume is not a per-request problem. Anthropic's classifier operates on cumulative per-OAuth-session aggregates — token throughput, conversation depth, streaming duration, inter-arrival timing, thinking-block volume. Dario's Claude backend can make each individual request indistinguishable from Claude Code and still hit this wall on a long-running agent session. Thorough diagnostic work was contributed by [@belangertrading](https://github.com/belangertrading) in [#23](https://github.com/askalf/dario/issues/23). The practical answer at the dario layer is **pool mode** — distribute load across multiple subscriptions so no single account accumulates enough signal to trip anything. See [Multi-account pool mode](#multi-account-pool-mode).
+Reclassification at high agent volume is not a per-request problem. Anthropic's classifier operates on cumulative per-OAuth-session aggregates — token throughput, conversation depth, streaming duration, inter-arrival timing, thinking-block volume. Dario's Claude backend can make each individual request indistinguishable from Claude Code and still hit this wall on a long-running agent session. Thorough diagnostic work was contributed by [@belangertrading](https://github.com/belangertrading) in [#23](https://github.com/askalf/dario/issues/23). The practical answer at the dario layer is **pool mode** — distribute load across multiple subscriptions so no single account accumulates enough signal to trip anything. See [Multi-account pool mode](#multi-account-pool-mode). The v3.22 – v3.28 fingerprint track (pacing, stream-drain, session-id lifecycle) also narrows the cumulative signal on a single account — see [Fingerprint axes](#fingerprint-axes).
+
+**My proxy is on Node, not Bun. What's the actual risk?**
+Node uses OpenSSL, Bun uses BoringSSL — the TLS ClientHello differs enough to yield a distinct JA3/JA4 hash. Anthropic can see the hash. Whether they classify on it today is unknown; making the axis visible is the v3.23 contribution. If certainty matters to you, install Bun (dario auto-relaunches under it) or run `dario proxy --strict-tls` to fail loud. If it doesn't, the warning is ignorable — dario still works, the TLS fingerprint is just the one observable axis left.
 
 **Why "dario"?**
 It's a name, not an acronym. Don't overthink it.
@@ -613,22 +693,32 @@ Longer-form writing on how dario works and why it works that way:
 - [Billing tag algorithm and fingerprint analysis](https://github.com/askalf/dario/discussions/8)
 - [Rate limit header analysis](https://github.com/askalf/dario/discussions/1)
 
+The CHANGELOG documents every v3.22 – v3.28 "get ahead of Anthropic" release with file-level rationale; each one is worth reading as a standalone post on the axis it closes.
+
 ---
 
 ## Contributing
 
-PRs welcome. The codebase is small TypeScript — ~8,100 lines across ~15 files:
+PRs welcome. The codebase is small TypeScript — ~11,300 lines across ~25 files:
 
 | File | Purpose |
 |---|---|
-| `src/proxy.ts` | HTTP proxy server, request handler, rate governor, Claude backend dispatch, OpenAI-compat routing, pool failover |
+| `src/proxy.ts` | HTTP proxy server, request handler, rate governor, Claude backend dispatch, OpenAI-compat routing, pool failover, session registry wiring, stream-drain gating |
 | `src/cc-template.ts` | CC request template engine, universal `TOOL_MAP` (~66 schema-verified entries), orchestration and framework scrubbing, header-order + body-field-order replay |
-| `src/cc-template-data.json` | Bundled fallback CC request template (used when live-fingerprint extraction isn't possible). Scrubbed of host-identifying paths at bake time. |
-| `src/scrub-template.ts` | Host-context scrubber for the baked fallback template — strips per-session sections, replaces user-dir paths with a placeholder, drops `mcp__*` tools (v3.21) |
+| `src/cc-template-data.json` | Bundled fallback CC request template (used when live-fingerprint extraction isn't possible). Scrubbed of host-identifying paths and `mcp__*` tools at bake time (v3.21). |
+| `src/scrub-template.ts` | Host-context scrubber for the baked fallback — strips per-session sections, replaces user-dir paths with a placeholder, drops `mcp__*` tools |
 | `src/cc-oauth-detect.ts` | OAuth config auto-detection from the installed CC binary |
 | `src/live-fingerprint.ts` | Live extraction of the CC request template (system prompt, tools, user-agent, beta flags, header order, static header values, body field order) from the installed Claude Code binary, drift detection, compat matrix, atomic cache writes, corruption recovery |
-| `src/doctor.ts` | `dario doctor` health report aggregator — dario/Node/CC/template/drift/OAuth/pool/backends |
-| `src/oauth.ts` | Single-account token storage, PKCE flow, auto-refresh |
+| `src/runtime-fingerprint.ts` | Runtime / TLS classifier (`bun-match` / `bun-bypassed` / `node-only`) surfaced through `dario doctor` and `--strict-tls` (v3.23) |
+| `src/pacing.ts` | Pure inter-request delay calculator with configurable floor + uniform jitter (v3.24) |
+| `src/stream-drain.ts` | Pure decision function for client-disconnect handling — `abort` / `drain` / `noop` (v3.25) |
+| `src/session-rotation.ts` | `SessionRegistry` with LRU eviction + pure `decideSessionRotation` — idle, jitter, max-age, per-client bucketing (v3.28) |
+| `src/subagent.ts` | CC sub-agent install / remove / status lifecycle; `buildSubagentFile(version)` is pure and pinned (v3.26) |
+| `src/mcp/protocol.ts` | Hand-rolled JSON-RPC 2.0 + MCP method dispatcher — zero deps, pure over inputs, tested without streams (v3.27) |
+| `src/mcp/tools.ts` | Six read-only MCP tools — `doctor`, `status`, `accounts_list`, `backends_list`, `subagent_status`, `fingerprint_info`. Redacts credentials at the tool boundary (v3.27) |
+| `src/mcp/server.ts` | Stdio event loop — ordered serial dispatch, back-pressure-aware writes, injectable streams for testing (v3.27) |
+| `src/doctor.ts` | `dario doctor` health report aggregator — dario / Node / runtime-TLS / CC / template / drift / OAuth / pool / backends / sub-agent |
+| `src/oauth.ts` | Single-account token storage, PKCE flow, auto-refresh, manual/headless flow (v3.20) |
 | `src/accounts.ts` | Multi-account credential storage, independent OAuth lifecycle, refresh single-flight |
 | `src/pool.ts` | Account pool, headroom-aware routing, session stickiness, failover target selection |
 | `src/sealed-pool.ts` | Sealed-sender overflow protocol — RSA blind signatures for unlinkable group pooling |
@@ -636,7 +726,7 @@ PRs welcome. The codebase is small TypeScript — ~8,100 lines across ~15 files:
 | `src/openai-backend.ts` | OpenAI-compat backend credential storage and request forwarder |
 | `src/shim/runtime.cjs` | Hand-written CJS payload loaded into child processes via `NODE_OPTIONS=--require`; patches `globalThis.fetch` for Anthropic messages requests only |
 | `src/shim/host.ts` | Parent-side orchestrator for `dario shim` — spawns the child, owns the telemetry socket / named pipe, feeds analytics |
-| `src/cli.ts` | CLI entry point, command routing, Bun auto-relaunch |
+| `src/cli.ts` | CLI entry point, command routing, Bun auto-relaunch, proxy flag parsing |
 | `src/index.ts` | Library exports |
 
 ```bash
@@ -644,7 +734,7 @@ git clone https://github.com/askalf/dario
 cd dario
 npm install
 npm run dev   # runs with tsx, no build step
-npm test      # ~640 assertions across 20 suites
+npm test      # ~1,250 assertions across 32 suites
 npm run e2e   # live proxy + OAuth (requires a working Claude backend)
 ```
 
@@ -659,8 +749,9 @@ npm run e2e   # live proxy + OAuth (requires a working Claude backend)
 | [@nathan-widjaja](https://github.com/nathan-widjaja) | README positioning rewrite structure ([#21](https://github.com/askalf/dario/issues/21)) |
 | [@iNicholasBE](https://github.com/iNicholasBE) | macOS keychain credential detection ([#30](https://github.com/askalf/dario/pull/30)) |
 | [@boeingchoco](https://github.com/boeingchoco) | Reverse-direction tool parameter translation ([#29](https://github.com/askalf/dario/issues/29)), SSE event-group framing regression catch (v3.7.1), provider-comparison diagnostic that surfaced the `--preserve-tools` discoverability gap (v3.8.1), motivating case for hybrid tool mode ([#33](https://github.com/askalf/dario/issues/33), v3.9.0), OpenClaw tool-mapping root cause that drove the universal `TOOL_MAP` work ([#36](https://github.com/askalf/dario/issues/36)) |
-| [@tetsuco](https://github.com/tetsuco) | Framework-name path corruption in scrubber ([#35](https://github.com/askalf/dario/issues/35)), OpenClaw Bash/Glob reverse-mapping collisions ([#37](https://github.com/askalf/dario/issues/37)) |
+| [@tetsuco](https://github.com/tetsuco) | Framework-name path corruption in scrubber ([#35](https://github.com/askalf/dario/issues/35)), OpenClaw Bash/Glob reverse-mapping collisions ([#37](https://github.com/askalf/dario/issues/37)), 20x-tier invalid-x-api-key capture artifact + OAuth-scope rejection report that drove v3.19.2 / v3.19.4 / v3.19.5 ([#42](https://github.com/askalf/dario/issues/42)) |
 | [@mikelovatt](https://github.com/mikelovatt) | Silent subscription-percent drain surfaced via friendly billing buckets ([#34](https://github.com/askalf/dario/issues/34)) |
+| [@ringge](https://github.com/ringge) | Fingerprint-fidelity concern motivating the `--no-auto-detect` opt-out for text-tool-client auto-preserve ([#40](https://github.com/askalf/dario/issues/40), v3.20.1) |
 
 ---
 

package/dist/cc-oauth-detect.d.ts

@@ -42,6 +42,7 @@ export interface DetectedOAuthConfig {
     ccPath?: string;
     ccHash?: string;
 }
+export declare const FALLBACK_FOR_DRIFT_CHECK: Readonly<DetectedOAuthConfig>;
 /**
  * Scan binary bytes for the PROD OAuth config block.
  *

package/dist/cc-oauth-detect.js

@@ -60,6 +60,10 @@ const FALLBACK = {
     scopes: 'user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload',
     source: 'fallback',
 };
+// Re-export of FALLBACK for scripts/check-cc-authorize-probe.mjs. The probe
+// needs the exact values the runtime uses — hardcoding them in the script
+// would drift out of sync silently.
+export const FALLBACK_FOR_DRIFT_CHECK = FALLBACK;
 // -v4 suffix invalidates v3.x caches populated with the 6-scope list that
 // Anthropic now rejects (dario #42). On upgrade, users regenerate the cache
 // with the new FALLBACK scopes automatically — no manual clear required.

package/dist/cli.js

@@ -220,7 +220,16 @@ async function proxy() {
     // read-to-completion pattern. Costs tokens (the response is fully
     // generated even if nobody reads it), so it's opt-in.
     const drainOnClose = args.includes('--drain-on-close') || undefined;
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose });
+    // --session-* knobs (v3.28, direction #1). Control the single-account
+    // session-id lifecycle: idle threshold, jitter on that threshold, hard
+    // max-age, and whether to give each upstream client its own session.
+    // All defaults preserve v3.27 behaviour exactly. Logic lives in
+    // src/session-rotation.ts; these flags just feed resolveSessionRotationConfig.
+    const sessionIdleRotateMs = parsePositiveIntFlag('--session-idle-rotate=');
+    const sessionRotateJitterMs = parsePositiveIntFlag('--session-rotate-jitter=');
+    const sessionMaxAgeMs = parsePositiveIntFlag('--session-max-age=');
+    const sessionPerClient = args.includes('--session-per-client') || undefined;
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient });
 }
 function parsePositiveIntFlag(prefix) {
     const found = args.find(a => a.startsWith(prefix));
@@ -513,6 +522,26 @@ async function help() {
                              is fully generated even if nobody reads
                              it) for fingerprint fidelity. Bounded by
                              the 5-minute upstream timeout. (v3.25)
+    --session-idle-rotate=MS Idle ms before the single-account session
+                             id rotates (default: 900000 = 15 min).
+                             Real CC rotates once per conversation, not
+                             per call; the default matches its observed
+                             cadence. Pool mode is unaffected. (v3.28)
+    --session-rotate-jitter=MS
+                             Max additional uniform-random jitter (ms)
+                             added to the idle threshold, sampled once
+                             per session at creation. Default: 0 (off).
+                             Hides the exact threshold from long-run
+                             rotation statistics. (v3.28)
+    --session-max-age=MS     Hard cap on a session id's lifetime
+                             regardless of activity. Default: off. Set
+                             for always-on pipelines where an idle
+                             window would never trigger. (v3.28)
+    --session-per-client     Give each upstream client (keyed by
+                             x-session-id / x-client-session-id
+                             header) its own rotated session id.
+                             Default: off (single session across all
+                             clients, v3.27 behaviour). (v3.28)
     --port=PORT              Port to listen on (default: 3456)
     --host=ADDRESS           Address to bind to (default: 127.0.0.1)
                              Use 0.0.0.0 for LAN; see README for DARIO_API_KEY

package/dist/proxy.d.ts

@@ -1,3 +1,4 @@
+import { type IncomingMessage } from 'node:http';
 export declare function parseProviderPrefix(model: string): {
     provider: 'openai' | 'claude';
     model: string;
@@ -16,7 +17,18 @@ interface ProxyOptions {
     pacingMinMs?: number;
     pacingJitterMs?: number;
     drainOnClose?: boolean;
+    sessionIdleRotateMs?: number;
+    sessionRotateJitterMs?: number;
+    sessionMaxAgeMs?: number;
+    sessionPerClient?: boolean;
 }
 export declare function sanitizeError(err: unknown): string;
+/**
+ * Two-lane auth: DARIO_API_KEY (x-api-key / Authorization: Bearer) for
+ * normal clients, and MUX_COORD_SECRET (X-Mux-Coord-Secret) for the mux
+ * gateway forwarding a verified sealed borrow. If neither is configured
+ * the request is allowed (loopback-only default). Exported for tests.
+ */
+export declare function authenticateRequest(headers: IncomingMessage['headers'], apiKeyBuf: Buffer | null, mcsBuf: Buffer | null): boolean;
 export declare function startProxy(opts?: ProxyOptions): Promise<void>;
 export {};

package/dist/proxy.js

@@ -97,11 +97,17 @@ function extractFirstUserMessage(body) {
 //
 //   v3.19 keeps the id stable through a conversation window and rotates
 //   only after an idle gap long enough to credibly indicate a new
-//   conversation (SESSION_IDLE_ROTATE_MS). Pool mode still uses the
-//   per-account identity.sessionId (stable across the account's lifetime).
+//   conversation. Pool mode still uses the per-account identity.sessionId
+//   (stable across the account's lifetime).
+//
+//   v3.28 generalises the single hardcoded 15-min window into a tunable
+//   registry (see src/session-rotation.ts) with optional jitter, max-age,
+//   and per-client keying. SESSION_ID below is kept only as a mirror of
+//   the default single-account session so out-of-band consumers (presence
+//   ping, diagnostic logs) can read the most recent id without going
+//   through the registry. It's refreshed after every dispatch-path call
+//   that assigns a new id.
 let SESSION_ID = randomUUID();
-let SESSION_LAST_USED = 0;
-const SESSION_IDLE_ROTATE_MS = 15 * 60 * 1000;
 const OS_NAME = platform === 'win32' ? 'Windows' : platform === 'darwin' ? 'MacOS' : 'Linux';
 // Claude Code device identity — required for Max plan billing classification.
 // Without metadata.user_id, Anthropic classifies requests as third-party and
@@ -327,6 +333,35 @@ export function sanitizeError(err) {
         .replace(/eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g, '[REDACTED_JWT]')
         .replace(/Bearer\s+[^\s,;]+/gi, 'Bearer [REDACTED]');
 }
+/**
+ * Two-lane auth: DARIO_API_KEY (x-api-key / Authorization: Bearer) for
+ * normal clients, and MUX_COORD_SECRET (X-Mux-Coord-Secret) for the mux
+ * gateway forwarding a verified sealed borrow. If neither is configured
+ * the request is allowed (loopback-only default). Exported for tests.
+ */
+export function authenticateRequest(headers, apiKeyBuf, mcsBuf) {
+    if (!apiKeyBuf && !mcsBuf)
+        return true;
+    if (mcsBuf) {
+        const raw = headers['x-mux-coord-secret'];
+        const provided = typeof raw === 'string' ? raw : Array.isArray(raw) ? raw[0] : undefined;
+        if (provided) {
+            const providedBuf = Buffer.from(provided);
+            if (providedBuf.length === mcsBuf.length && timingSafeEqual(providedBuf, mcsBuf))
+                return true;
+        }
+    }
+    if (apiKeyBuf) {
+        const provided = headers['x-api-key']
+            || headers.authorization?.replace(/^Bearer\s+/i, '');
+        if (provided) {
+            const providedBuf = Buffer.from(provided);
+            if (providedBuf.length === apiKeyBuf.length && timingSafeEqual(providedBuf, apiKeyBuf))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * Enrich Anthropic's unhelpful 429 "Error" body with rate limit details from headers.
  */
@@ -593,9 +628,33 @@ export async function startProxy(opts = {}) {
     if (verbose) {
         console.log(`[dario] drain-on-close: ${drainOnClose ? 'enabled' : 'disabled'}`);
     }
+    // Session-ID lifecycle (v3.28, direction #1). Replaces the v3.27 hardcoded
+    // 15-minute idle window with a tunable registry: idle threshold, jitter on
+    // that threshold, optional hard max-age, and optional per-client keying.
+    // Defaults preserve v3.27 behavior exactly. See src/session-rotation.ts.
+    const { SessionRegistry, resolveSessionRotationConfig } = await import('./session-rotation.js');
+    const sessionCfg = resolveSessionRotationConfig({
+        idleRotateMs: opts.sessionIdleRotateMs,
+        jitterMs: opts.sessionRotateJitterMs,
+        maxAgeMs: opts.sessionMaxAgeMs,
+        perClient: opts.sessionPerClient,
+    });
+    const sessionRegistry = new SessionRegistry(sessionCfg, () => randomUUID());
+    if (verbose) {
+        const maxAge = sessionCfg.maxAgeMs !== undefined ? `${sessionCfg.maxAgeMs}ms` : 'off';
+        console.log(`[dario] session: idle=${sessionCfg.idleRotateMs}ms jitter=${sessionCfg.jitterMs}ms maxAge=${maxAge} perClient=${sessionCfg.perClient}`);
+    }
     // Optional proxy authentication — pre-encode key buffer for performance
     const apiKey = process.env.DARIO_API_KEY;
     const apiKeyBuf = apiKey ? Buffer.from(apiKey) : null;
+    // Mux coord-secret — the shared secret mux uses when forwarding sealed
+    // borrow requests to this dario acting as a lender endpoint. A request
+    // carrying a matching X-Mux-Coord-Secret header is authenticated without
+    // needing DARIO_API_KEY. The sealed-sender envelope has already been
+    // verified upstream, so the coord secret is the one-hop auth between
+    // the mux gateway and this instance.
+    const mcs = process.env.MUX_COORD_SECRET;
+    const mcsBuf = mcs ? Buffer.from(mcs) : null;
     // CORS origin defaults to the localhost URL the proxy is served at. Users
     // binding to a non-loopback address (e.g. a Tailscale interface) can
     // override via DARIO_CORS_ORIGIN — otherwise browser-based clients hitting
@@ -611,7 +670,7 @@ export async function startProxy(opts = {}) {
     const CORS_HEADERS = {
         'Access-Control-Allow-Origin': corsOrigin,
         'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key, anthropic-version, anthropic-beta',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key, anthropic-version, anthropic-beta, x-mux-coord-secret',
         'Access-Control-Max-Age': '86400',
         ...SECURITY_HEADERS,
     };
@@ -621,16 +680,7 @@ export async function startProxy(opts = {}) {
     const ERR_FORBIDDEN = JSON.stringify({ error: 'Forbidden', message: 'Path not allowed. Supported paths: POST /v1/messages, POST /v1/chat/completions, GET /v1/models' });
     const ERR_METHOD = JSON.stringify({ error: 'Method not allowed' });
     function checkAuth(req) {
-        if (!apiKeyBuf)
-            return true;
-        const provided = req.headers['x-api-key']
-            || req.headers.authorization?.replace(/^Bearer\s+/i, '');
-        if (!provided)
-            return false;
-        const providedBuf = Buffer.from(provided);
-        if (providedBuf.length !== apiKeyBuf.length)
-            return false;
-        return timingSafeEqual(providedBuf, apiKeyBuf);
+        return authenticateRequest(req.headers, apiKeyBuf, mcsBuf);
     }
     const server = createServer(async (req, res) => {
         if (req.method === 'OPTIONS') {
@@ -958,6 +1008,9 @@ export async function startProxy(opts = {}) {
             // selection toward one we already paid cache cost on — passthrough
             // users aren't doing template replay anyway).
             let stickyKey = null;
+            // Outbound session id resolved once — either inside the template build
+            // (so body metadata matches) or below for passthrough (no body build).
+            let preBodySessionId;
             // Request context for hybrid-mode field injection (#33). Built once
             // per request from incoming headers so the reverse mapper can fill
             // client-declared fields like `sessionId` that CC's schema doesn't
@@ -1010,9 +1063,28 @@ export async function startProxy(opts = {}) {
                                 }
                             }
                         }
+                        // Resolve the outbound session id before the body build so the
+                        // metadata.session_id in the CC body and the x-claude-code-session-id
+                        // header both use the same value. v3.27 consulted SESSION_ID twice
+                        // with rotation between the reads, so on rotation events body and
+                        // header disagreed — harmless for plain operation but a fingerprint
+                        // in its own right.
+                        if (poolAccount) {
+                            preBodySessionId = poolAccount.identity.sessionId;
+                        }
+                        else {
+                            const clientKey = req.headers['x-session-id']
+                                ?? req.headers['x-client-session-id'];
+                            const assigned = sessionRegistry.getOrCreate(clientKey, Date.now());
+                            preBodySessionId = assigned.sessionId;
+                            SESSION_ID = assigned.sessionId;
+                            if (verbose && assigned.rotated && assigned.reason !== 'rotate-new') {
+                                console.log(`[dario] #${requestCount} session: rotate (${assigned.reason})`);
+                            }
+                        }
                         const bodyIdentity = poolAccount
                             ? poolAccount.identity
-                            : { deviceId: identity.deviceId, accountUuid: identity.accountUuid, sessionId: SESSION_ID };
+                            : { deviceId: identity.deviceId, accountUuid: identity.accountUuid, sessionId: preBodySessionId };
                         const { body: ccBody, toolMap, detectedClient } = buildCCRequest(r, billingTag, CACHE_1H, bodyIdentity, {
                             preserveTools: opts.preserveTools ?? false,
                             hybridTools: opts.hybridTools ?? false,
@@ -1102,18 +1174,30 @@ export async function startProxy(opts = {}) {
             }
             lastRequestTime = Date.now();
             // Session ID: pool mode uses the per-account identity.sessionId (stable
-            // per account). Single-account mode keeps SESSION_ID stable through
-            // active conversations and rotates only after an idle gap that looks
-            // like a new conversation — matches CC's observed cadence (see note
-            // at SESSION_ID declaration).
-            if (!poolAccount) {
-                const nowTs = Date.now();
-                if (SESSION_LAST_USED === 0 || nowTs - SESSION_LAST_USED > SESSION_IDLE_ROTATE_MS) {
-                    SESSION_ID = randomUUID();
+            // per account). Single-account mode delegates to the session registry
+            // (src/session-rotation.ts) which applies the configured idle / jitter /
+            // max-age / per-client policy. Resolution happens earlier, at body-build
+            // time, so the CC body's metadata.session_id and the outbound
+            // x-claude-code-session-id header always agree. preBodySessionId holds
+            // the template-build value; in passthrough mode (no template build)
+            // the registry is consulted here instead.
+            let outboundSessionId;
+            if (poolAccount) {
+                outboundSessionId = poolAccount.identity.sessionId;
+            }
+            else if (preBodySessionId !== undefined) {
+                outboundSessionId = preBodySessionId;
+            }
+            else {
+                const clientKey = req.headers['x-session-id']
+                    ?? req.headers['x-client-session-id'];
+                const assigned = sessionRegistry.getOrCreate(clientKey, Date.now());
+                outboundSessionId = assigned.sessionId;
+                SESSION_ID = assigned.sessionId;
+                if (verbose && assigned.rotated && assigned.reason !== 'rotate-new') {
+                    console.log(`[dario] #${requestCount} session: rotate (${assigned.reason})`);
                 }
-                SESSION_LAST_USED = nowTs;
             }
-            const outboundSessionId = poolAccount ? poolAccount.identity.sessionId : SESSION_ID;
             const headers = {
                 ...staticHeaders,
                 'Authorization': `Bearer ${accessToken}`,
@@ -1723,14 +1807,19 @@ export async function startProxy(opts = {}) {
         if (!isLoopbackHost(host)) {
             console.log('');
             console.log(`  ⚠  Bound to ${host} — reachable from other machines on the network.`);
-            if (!apiKey) {
-                console.log('     DARIO_API_KEY is not set. Any host that can reach this port can');
-                console.log('     proxy requests through your OAuth subscription. Set DARIO_API_KEY');
-                console.log('     before exposing dario beyond loopback.');
+            if (!apiKey && !mcs) {
+                console.log('     No auth configured. Any host that can reach this port can proxy');
+                console.log('     requests through your OAuth subscription. Set DARIO_API_KEY (for');
+                console.log('     normal clients) or MUX_COORD_SECRET (for mux lender mode) before');
+                console.log('     exposing dario beyond loopback.');
             }
             else {
-                console.log('     DARIO_API_KEY is set — clients must send x-api-key or Authorization');
-                console.log('     to be accepted.');
+                const lanes = [];
+                if (apiKey)
+                    lanes.push('x-api-key / Authorization (DARIO_API_KEY)');
+                if (mcs)
+                    lanes.push('X-Mux-Coord-Secret (MUX_COORD_SECRET — mux lender mode)');
+                console.log(`     Auth required — accepted credentials: ${lanes.join(' or ')}.`);
             }
         }
         console.log('');

package/dist/session-rotation.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Session-ID lifecycle (v3.28, direction #1 — interactive-side rotation).
+ *
+ * Every outbound request to Anthropic carries a session identifier in the
+ * CC request body's metadata. Real Claude Code holds that id stable through
+ * a conversation and mints a new one when the user returns after an idle
+ * gap — roughly "one id per conversation", not per HTTP call. A proxy that
+ * rotates per-request looks synthetic; one that never rotates looks equally
+ * synthetic over long sessions. v3.19 tightened the per-request leak into a
+ * single hardcoded 15-minute idle window; this module generalises that into
+ * a registry so operators can tune the behaviour and so the multi-client
+ * case (dario fanning multiple UIs through one proxy) stops sharing one id.
+ *
+ * Three independent knobs:
+ *
+ *   idleRotateMs — the v3.19 behaviour: rotate after this many ms of no
+ *                  traffic on a given session. Default 15 min preserves
+ *                  v3.27 exactly when the other knobs stay at defaults.
+ *
+ *   jitterMs     — the observable idle threshold for a given session is
+ *                  idleRotateMs + U(0, jitterMs), sampled once at session
+ *                  creation. A zero-jitter proxy rotates at exactly the
+ *                  same interval every time; adding jitter means the floor
+ *                  can't be inferred from long-run rotation cadence.
+ *
+ *   maxAgeMs     — hard cap on a session's total lifetime regardless of
+ *                  activity. Optional (undefined disables). A chatty
+ *                  always-on pipeline would otherwise keep one session id
+ *                  alive for days; real CC conversations don't.
+ *
+ *   perClient    — when true, the registry keys sessions by the caller's
+ *                  `x-session-id` / `x-client-session-id` header so two
+ *                  upstream UIs talking to one dario don't collapse onto
+ *                  a single session id. Default false preserves v3.27
+ *                  single-account semantics.
+ *
+ * Pure logic (decideSessionRotation) is separated from the stateful cache
+ * (SessionRegistry) so tests can walk every decision branch without Maps,
+ * timers, or UUID sources. The proxy injects a `() => string` id factory
+ * (randomUUID) and `() => number` rng so both are swappable in tests.
+ *
+ * Pool mode is unaffected — each account carries a stable identity.sessionId
+ * for its lifetime, and the caller doesn't consult this registry. This
+ * module only governs the single-account SESSION_ID slot.
+ */
+export interface SessionRotationConfig {
+    /** Idle threshold in ms: if no traffic for this long, the session rotates on the next request. */
+    idleRotateMs: number;
+    /** Max additional uniform-random ms added to the idle threshold at session creation. Pass 0 to disable. */
+    jitterMs: number;
+    /** Optional hard cap on session lifetime in ms. Undefined = no cap. */
+    maxAgeMs?: number;
+    /** When true, key sessions by client header so multiple upstreams get distinct ids. Default false. */
+    perClient: boolean;
+}
+export interface SessionEntry {
+    /** The session id sent to Anthropic in the outbound body. */
+    upstreamSessionId: string;
+    /** Wall-clock creation time (ms since epoch). */
+    createdAt: number;
+    /** Wall-clock time of last outbound use (ms since epoch). */
+    lastUsedAt: number;
+    /** Jitter offset sampled once at creation; added to cfg.idleRotateMs to get this session's effective idle threshold. */
+    idleJitterOffsetMs: number;
+}
+export type RotationDecision = 'keep' | 'rotate-new' | 'rotate-idle' | 'rotate-age';
+/**
+ * Pure decision: should the given entry be rotated at `now`?
+ *
+ * Returns 'rotate-new' when no entry exists yet (first use for this key).
+ * Returns 'rotate-idle' when traffic has been silent for longer than this
+ * entry's sampled threshold. Returns 'rotate-age' when the entry's
+ * absolute lifetime exceeds cfg.maxAgeMs (when set). Otherwise 'keep'.
+ *
+ * Idle is checked before age so an idle-but-young session rotates on a
+ * fresh conversation boundary rather than churning mid-conversation at
+ * exactly its max-age. Negative config values are clamped to 0 (lenient:
+ * a typoed flag should behave like "rotate eagerly", not crash startup).
+ */
+export declare function decideSessionRotation(entry: SessionEntry | undefined, now: number, cfg: SessionRotationConfig): RotationDecision;
+/** Result of SessionRegistry.getOrCreate — both the id to send and why it was chosen. */
+export interface RegistryResult {
+    sessionId: string;
+    rotated: boolean;
+    reason: RotationDecision;
+}
+/**
+ * Per-client session cache with rotation + LRU eviction.
+ *
+ * Not concurrency-safe — the proxy's dispatch loop is single-threaded
+ * JavaScript and call sites are serialized by the event loop. The
+ * registry is intentionally a plain Map, not a TTL cache, because
+ * rotation timing is part of the observable behaviour we're modelling
+ * and a background sweeper would add a separate dimension (WHEN entries
+ * disappear) that doesn't exist in a real CC client.
+ *
+ * maxEntries defaults to 1024 — more than enough for any reasonable
+ * fan-out while capping memory growth against a pathological client
+ * that sends a fresh session header on every request.
+ */
+export declare class SessionRegistry {
+    private readonly cfg;
+    private readonly newId;
+    private readonly rng;
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(cfg: SessionRotationConfig, newId: () => string, rng?: () => number, maxEntries?: number);
+    /**
+     * Resolve the outbound session id for a given client key at time `now`.
+     *
+     * `clientKey` is the caller-side session header when cfg.perClient is
+     * true, and ignored (replaced with 'default') when perClient is false.
+     * Callers pass the raw header value and let the registry decide —
+     * otherwise flipping perClient at runtime would require threading
+     * the decision to every call site.
+     *
+     * Updates lastUsedAt on the entry (whether kept or freshly minted),
+     * and nudges the entry to the end of the insertion-order map so
+     * eviction under maxEntries pressure is LRU.
+     */
+    getOrCreate(clientKey: string | undefined, now: number): RegistryResult;
+    /**
+     * Read the current id for a client key without touching lastUsedAt.
+     *
+     * Used by out-of-band consumers (e.g. presence pings) that want to
+     * reflect the most recently assigned session id but must not count
+     * as activity for rotation purposes. Returns undefined if no entry.
+     */
+    peek(clientKey: string | undefined): string | undefined;
+    size(): number;
+    clear(): void;
+    private evictIfOverCap;
+}
+/**
+ * Resolve a SessionRotationConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_SESSION_IDLE_ROTATE_MS / DARIO_SESSION_JITTER_MS /
+ *      DARIO_SESSION_MAX_AGE_MS / DARIO_SESSION_PER_CLIENT env vars
+ *   3. Defaults: idleRotateMs=15min, jitterMs=0, maxAgeMs=undefined,
+ *      perClient=false — exactly matches the hardcoded v3.27 behaviour.
+ *
+ * Invalid numeric strings fall through to the next source. For perClient,
+ * '1' / 'true' / 'yes' (case-insensitive) enable; anything else stays at
+ * the explicit or default value.
+ */
+export declare function resolveSessionRotationConfig(explicit?: {
+    idleRotateMs?: number;
+    jitterMs?: number;
+    maxAgeMs?: number;
+    perClient?: boolean;
+}, env?: NodeJS.ProcessEnv): SessionRotationConfig;

package/dist/session-rotation.js

@@ -0,0 +1,214 @@
+/**
+ * Session-ID lifecycle (v3.28, direction #1 — interactive-side rotation).
+ *
+ * Every outbound request to Anthropic carries a session identifier in the
+ * CC request body's metadata. Real Claude Code holds that id stable through
+ * a conversation and mints a new one when the user returns after an idle
+ * gap — roughly "one id per conversation", not per HTTP call. A proxy that
+ * rotates per-request looks synthetic; one that never rotates looks equally
+ * synthetic over long sessions. v3.19 tightened the per-request leak into a
+ * single hardcoded 15-minute idle window; this module generalises that into
+ * a registry so operators can tune the behaviour and so the multi-client
+ * case (dario fanning multiple UIs through one proxy) stops sharing one id.
+ *
+ * Three independent knobs:
+ *
+ *   idleRotateMs — the v3.19 behaviour: rotate after this many ms of no
+ *                  traffic on a given session. Default 15 min preserves
+ *                  v3.27 exactly when the other knobs stay at defaults.
+ *
+ *   jitterMs     — the observable idle threshold for a given session is
+ *                  idleRotateMs + U(0, jitterMs), sampled once at session
+ *                  creation. A zero-jitter proxy rotates at exactly the
+ *                  same interval every time; adding jitter means the floor
+ *                  can't be inferred from long-run rotation cadence.
+ *
+ *   maxAgeMs     — hard cap on a session's total lifetime regardless of
+ *                  activity. Optional (undefined disables). A chatty
+ *                  always-on pipeline would otherwise keep one session id
+ *                  alive for days; real CC conversations don't.
+ *
+ *   perClient    — when true, the registry keys sessions by the caller's
+ *                  `x-session-id` / `x-client-session-id` header so two
+ *                  upstream UIs talking to one dario don't collapse onto
+ *                  a single session id. Default false preserves v3.27
+ *                  single-account semantics.
+ *
+ * Pure logic (decideSessionRotation) is separated from the stateful cache
+ * (SessionRegistry) so tests can walk every decision branch without Maps,
+ * timers, or UUID sources. The proxy injects a `() => string` id factory
+ * (randomUUID) and `() => number` rng so both are swappable in tests.
+ *
+ * Pool mode is unaffected — each account carries a stable identity.sessionId
+ * for its lifetime, and the caller doesn't consult this registry. This
+ * module only governs the single-account SESSION_ID slot.
+ */
+/**
+ * Pure decision: should the given entry be rotated at `now`?
+ *
+ * Returns 'rotate-new' when no entry exists yet (first use for this key).
+ * Returns 'rotate-idle' when traffic has been silent for longer than this
+ * entry's sampled threshold. Returns 'rotate-age' when the entry's
+ * absolute lifetime exceeds cfg.maxAgeMs (when set). Otherwise 'keep'.
+ *
+ * Idle is checked before age so an idle-but-young session rotates on a
+ * fresh conversation boundary rather than churning mid-conversation at
+ * exactly its max-age. Negative config values are clamped to 0 (lenient:
+ * a typoed flag should behave like "rotate eagerly", not crash startup).
+ */
+export function decideSessionRotation(entry, now, cfg) {
+    if (!entry)
+        return 'rotate-new';
+    const idleBase = Math.max(0, cfg.idleRotateMs);
+    const idleThreshold = idleBase + Math.max(0, entry.idleJitterOffsetMs);
+    if (now - entry.lastUsedAt > idleThreshold)
+        return 'rotate-idle';
+    if (cfg.maxAgeMs !== undefined && cfg.maxAgeMs > 0 && now - entry.createdAt > cfg.maxAgeMs) {
+        return 'rotate-age';
+    }
+    return 'keep';
+}
+/**
+ * Per-client session cache with rotation + LRU eviction.
+ *
+ * Not concurrency-safe — the proxy's dispatch loop is single-threaded
+ * JavaScript and call sites are serialized by the event loop. The
+ * registry is intentionally a plain Map, not a TTL cache, because
+ * rotation timing is part of the observable behaviour we're modelling
+ * and a background sweeper would add a separate dimension (WHEN entries
+ * disappear) that doesn't exist in a real CC client.
+ *
+ * maxEntries defaults to 1024 — more than enough for any reasonable
+ * fan-out while capping memory growth against a pathological client
+ * that sends a fresh session header on every request.
+ */
+export class SessionRegistry {
+    cfg;
+    newId;
+    rng;
+    maxEntries;
+    entries = new Map();
+    constructor(cfg, newId, rng = Math.random, maxEntries = 1024) {
+        this.cfg = cfg;
+        this.newId = newId;
+        this.rng = rng;
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * Resolve the outbound session id for a given client key at time `now`.
+     *
+     * `clientKey` is the caller-side session header when cfg.perClient is
+     * true, and ignored (replaced with 'default') when perClient is false.
+     * Callers pass the raw header value and let the registry decide —
+     * otherwise flipping perClient at runtime would require threading
+     * the decision to every call site.
+     *
+     * Updates lastUsedAt on the entry (whether kept or freshly minted),
+     * and nudges the entry to the end of the insertion-order map so
+     * eviction under maxEntries pressure is LRU.
+     */
+    getOrCreate(clientKey, now) {
+        const key = this.cfg.perClient ? (clientKey && clientKey.length > 0 ? clientKey : 'default') : 'default';
+        const existing = this.entries.get(key);
+        const decision = decideSessionRotation(existing, now, this.cfg);
+        if (decision === 'keep' && existing) {
+            existing.lastUsedAt = now;
+            // Re-insert to refresh LRU position.
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+            return { sessionId: existing.upstreamSessionId, rotated: false, reason: 'keep' };
+        }
+        const jitterOffset = this.cfg.jitterMs > 0 ? Math.floor(this.rng() * this.cfg.jitterMs) : 0;
+        const entry = {
+            upstreamSessionId: this.newId(),
+            createdAt: now,
+            lastUsedAt: now,
+            idleJitterOffsetMs: jitterOffset,
+        };
+        this.entries.set(key, entry);
+        this.evictIfOverCap();
+        return { sessionId: entry.upstreamSessionId, rotated: true, reason: decision };
+    }
+    /**
+     * Read the current id for a client key without touching lastUsedAt.
+     *
+     * Used by out-of-band consumers (e.g. presence pings) that want to
+     * reflect the most recently assigned session id but must not count
+     * as activity for rotation purposes. Returns undefined if no entry.
+     */
+    peek(clientKey) {
+        const key = this.cfg.perClient ? (clientKey && clientKey.length > 0 ? clientKey : 'default') : 'default';
+        return this.entries.get(key)?.upstreamSessionId;
+    }
+    size() {
+        return this.entries.size;
+    }
+    clear() {
+        this.entries.clear();
+    }
+    evictIfOverCap() {
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}
+/**
+ * Resolve a SessionRotationConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_SESSION_IDLE_ROTATE_MS / DARIO_SESSION_JITTER_MS /
+ *      DARIO_SESSION_MAX_AGE_MS / DARIO_SESSION_PER_CLIENT env vars
+ *   3. Defaults: idleRotateMs=15min, jitterMs=0, maxAgeMs=undefined,
+ *      perClient=false — exactly matches the hardcoded v3.27 behaviour.
+ *
+ * Invalid numeric strings fall through to the next source. For perClient,
+ * '1' / 'true' / 'yes' (case-insensitive) enable; anything else stays at
+ * the explicit or default value.
+ */
+export function resolveSessionRotationConfig(explicit = {}, env = process.env) {
+    const idleRotateMs = pickNonNegativeInt(explicit.idleRotateMs, env.DARIO_SESSION_IDLE_ROTATE_MS) ?? 15 * 60 * 1000;
+    const jitterMs = pickNonNegativeInt(explicit.jitterMs, env.DARIO_SESSION_JITTER_MS) ?? 0;
+    const maxAgeMs = pickPositiveInt(explicit.maxAgeMs, env.DARIO_SESSION_MAX_AGE_MS);
+    const perClient = pickBool(explicit.perClient, env.DARIO_SESSION_PER_CLIENT) ?? false;
+    return { idleRotateMs, jitterMs, maxAgeMs, perClient };
+}
+function pickNonNegativeInt(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null || c === '')
+            continue;
+        const n = typeof c === 'number' ? c : parseInt(c, 10);
+        if (Number.isFinite(n) && n >= 0)
+            return Math.floor(n);
+    }
+    return undefined;
+}
+function pickPositiveInt(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null || c === '')
+            continue;
+        const n = typeof c === 'number' ? c : parseInt(c, 10);
+        if (Number.isFinite(n) && n > 0)
+            return Math.floor(n);
+    }
+    return undefined;
+}
+function pickBool(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null)
+            continue;
+        if (typeof c === 'boolean')
+            return c;
+        const s = c.trim().toLowerCase();
+        if (s === '')
+            continue;
+        if (s === '1' || s === 'true' || s === 'yes' || s === 'on')
+            return true;
+        if (s === '0' || s === 'false' || s === 'no' || s === 'off')
+            return false;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "description": "A local LLM router. One endpoint, every provider — Claude subscriptions, OpenAI, OpenRouter, Groq, local LiteLLM, any OpenAI-compat endpoint — your tools don't need to change.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "tsc && cp src/cc-template-data.json dist/ && node -e \"require('fs').mkdirSync('dist/shim',{recursive:true})\" && cp src/shim/runtime.cjs dist/shim/",
-    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/drift-detection.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
+    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/mux-coord-secret.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/session-rotation.mjs && node test/drift-detection.mjs && node test/cc-authorize-probe-classifier.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",