@askalf/dario 3.22.0 → 3.24.0

package/README.md

@@ -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. ~7,600 lines of TypeScript across ~15 files. ~640 assertions across 20 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. ~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.**
 
 ---
 
@@ -88,7 +88,7 @@ Something broken? `dario doctor` prints a single aggregated health report — da
 
 **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 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` (**71 entries as of v3.15**) 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 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).
 
@@ -156,11 +156,11 @@ Force a backend with a **provider prefix** on the model field (`openai:gpt-4o`,
 
 OAuth-backed Claude Max / Pro, billed against your plan instead of the API. Activated by `dario login`.
 
-**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** — 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, **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.
 
 **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 on the wire by the shim since v3.13 and the proxy since v3.16). 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.
+- **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).
 - **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.
 - **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)`.
@@ -272,7 +272,7 @@ Under the hood: `dario shim` spawns the child with `NODE_OPTIONS=--require <dari
 
 ## Agent compatibility
 
-As of **v3.18**, dario's built-in `TOOL_MAP` carries **~65 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.
+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.
 
 | Agent | Covered tool names (subset) |
 |---|---|
@@ -515,11 +515,11 @@ Dario handles your OAuth tokens and API keys locally. Here's why you can trust i
 
 | Signal | Status |
 |---|---|
-| **Source code** | ~7,600 lines of TypeScript across ~15 files — small enough to audit in a weekend |
+| **Source code** | ~8,100 lines of TypeScript across ~15 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** | ~640 assertions across 20 files. Full `npm test` green on every release |
+| **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 |
 | **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 |
@@ -568,7 +568,7 @@ Yes — anything that speaks the OpenAI Chat Completions API. Groq, OpenRouter,
 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.
 
 **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, and header insertion 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.
+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.
 
 **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:
@@ -617,15 +617,16 @@ Longer-form writing on how dario works and why it works that way:
 
 ## Contributing
 
-PRs welcome. The codebase is small TypeScript — ~7,600 lines across ~15 files:
+PRs welcome. The codebase is small TypeScript — ~8,100 lines across ~15 files:
 
 | File | Purpose |
 |---|---|
 | `src/proxy.ts` | HTTP proxy server, request handler, rate governor, Claude backend dispatch, OpenAI-compat routing, pool failover |
-| `src/cc-template.ts` | CC request template engine, universal `TOOL_MAP` (~65 schema-verified entries), orchestration and framework scrubbing, header-order replay |
-| `src/cc-template-data.json` | Bundled fallback CC request template (used when live-fingerprint extraction isn't possible) |
+| `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-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) from the installed Claude Code binary, drift detection, compat matrix, atomic cache writes, corruption recovery |
+| `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/accounts.ts` | Multi-account credential storage, independent OAuth lifecycle, refresh single-flight |

package/dist/cli.js

@@ -200,9 +200,33 @@ async function proxy() {
     // when Cline/Kilo/Roo is detected can pass --no-auto-detect; they keep
     // explicit control with --preserve-tools per session. dario#40 (ringge).
     const noAutoDetect = args.includes('--no-auto-detect') || args.includes('--no-auto-preserve');
+    // --strict-tls refuses to start proxy mode when the process's TLS stack
+    // doesn't match Claude Code's (i.e. we're on Node without Bun). Opt-in
+    // hard guardrail for operators who want certainty that the JA3 the
+    // proxy presents to Anthropic is Bun's BoringSSL ClientHello, not
+    // Node's OpenSSL one. v3.23 (direction #3).
+    const strictTls = args.includes('--strict-tls');
     const modelArg = args.find(a => a.startsWith('--model='));
     const model = modelArg ? modelArg.split('=')[1] : undefined;
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect });
+    // --pace-min=MS / --pace-jitter=MS (v3.24, direction #6 — behavioral
+    // smoothing). Inter-request gap floor + optional uniform-random jitter.
+    // Defaults preserve v3.23 behavior (500ms floor, no jitter). The pure
+    // calc lives in src/pacing.ts; the flags just feed it.
+    const pacingMinMs = parsePositiveIntFlag('--pace-min=');
+    const pacingJitterMs = parsePositiveIntFlag('--pace-jitter=');
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs });
+}
+function parsePositiveIntFlag(prefix) {
+    const found = args.find(a => a.startsWith(prefix));
+    if (!found)
+        return undefined;
+    const raw = found.slice(prefix.length);
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        console.error(`[dario] Invalid ${prefix.replace(/=$/, '')} value: ${JSON.stringify(raw)}. Must be a non-negative integer (ms).`);
+        process.exit(1);
+    }
+    return n;
 }
 async function accounts() {
     const sub = args[1];
@@ -446,6 +470,22 @@ async function help() {
                              intact even when a text-tool client is
                              detected; use --preserve-tools per session
                              when edits are needed. (dario#40)
+    --strict-tls             Refuse to start proxy mode if this process
+                             isn't running under Bun. Bun is what Claude
+                             Code uses; matching its TLS stack keeps the
+                             proxy's JA3/JA4 ClientHello indistinguishable
+                             from a stock CC request. Install Bun
+                             (https://bun.sh) so dario auto-relaunches
+                             under it, or use shim mode. (v3.23)
+    --pace-min=MS            Minimum ms between upstream requests
+                             (default: 500). Prevents request floods
+                             that are distinguishable from human-paced
+                             CC traffic.
+    --pace-jitter=MS         Max additional uniform-random jitter (ms)
+                             added on top of --pace-min per request.
+                             Default: 0 (off). Set to e.g. 300 to hide
+                             the floor from long-run inter-arrival
+                             statistics. (v3.24)
     --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/doctor.js

@@ -72,6 +72,26 @@ export async function runChecks() {
         label: 'Platform',
         detail: `${platform()} ${arch()} (${release()})`,
     });
+    // ---- Runtime TLS fingerprint (v3.23, direction #3)
+    // Proxy mode terminates TLS in this process, so Bun-vs-Node is a
+    // fingerprint axis Anthropic can read directly off the wire.
+    try {
+        const { detectRuntimeFingerprint } = await import('./runtime-fingerprint.js');
+        const rt = detectRuntimeFingerprint();
+        const status = rt.status === 'bun-match' ? 'ok' : 'warn';
+        checks.push({
+            status,
+            label: 'Runtime / TLS',
+            detail: rt.hint ? `${rt.detail}. ${rt.hint}` : rt.detail,
+        });
+    }
+    catch (err) {
+        checks.push({
+            status: 'warn',
+            label: 'Runtime / TLS',
+            detail: `check failed: ${err.message}`,
+        });
+    }
     // ---- CC binary
     const cc = safely(() => findInstalledCC(), { path: null, version: null });
     if (cc.path && cc.version) {

package/dist/pacing.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Inter-request pacing (v3.24, direction #6 — behavioral smoothing).
+ *
+ * Real CC traffic has human-paced gaps between requests — sub-second when
+ * the model is streaming tool-loop output, multi-second when the user is
+ * typing the next message. A proxy that fires requests at machine speed
+ * with perfectly uniform spacing stands out against that rhythm.
+ *
+ * This module supplies the pure gap-calculation function the proxy's
+ * rate governor calls before every outbound fetch. Two knobs:
+ *
+ *   minGapMs    — lower bound on the wall-clock distance between requests.
+ *                 Was a hardcoded 500ms through v3.23; keep 500 as default
+ *                 so back-compat is exact when both knobs stay at defaults.
+ *
+ *   jitterMs    — uniform random addition on top of minGap. The *effective*
+ *                 gap for a given request is minGap + U(0, jitter). Adds
+ *                 non-uniformity so an observer can't infer the floor from
+ *                 the long-run minimum of inter-arrival times.
+ *
+ * Pure over (now, lastRequestTime, minGap, jitter, rng) so the tests can
+ * exercise every edge without spawning timers. The proxy passes
+ * `Math.random` as the rng at runtime; tests pass a deterministic stub.
+ *
+ * The first request in a session (lastRequestTime === 0) is never paced —
+ * the purpose is smoothing the *gap between* requests, not delaying the
+ * first one from whenever the consumer happens to connect.
+ */
+export interface PacingConfig {
+    /** Minimum wall-clock milliseconds between the completion of one request and the start of the next. */
+    minGapMs: number;
+    /** Max additional uniform-random jitter (ms) added on top of minGap. Pass 0 to disable. */
+    jitterMs: number;
+}
+/**
+ * How many milliseconds to sleep before the next upstream fetch.
+ *
+ * Returns 0 when no delay is required — either because this is the first
+ * request of the session, or enough wall-clock time has already elapsed
+ * since `lastRequestTime`.
+ *
+ * `rng` defaults to Math.random; tests inject a deterministic stub.
+ * Negative configuration values are clamped to 0 (lenient, not an error).
+ */
+export declare function computePacingDelay(now: number, lastRequestTime: number, cfg: PacingConfig, rng?: () => number): number;
+/**
+ * Resolve a PacingConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_PACE_MIN_MS / DARIO_PACE_JITTER_MS env vars
+ *   3. Legacy DARIO_MIN_INTERVAL_MS env var (minGap only — matches v3.23
+ *      behavior so existing setups don't regress silently)
+ *   4. Defaults: minGap=500, jitter=0
+ *
+ * Invalid strings (non-numeric, negative) are ignored and fall through to
+ * the next source — a typoed env var shouldn't fail-loud at startup.
+ */
+export declare function resolvePacingConfig(explicit?: {
+    minGapMs?: number;
+    jitterMs?: number;
+}, env?: NodeJS.ProcessEnv): PacingConfig;

package/dist/pacing.js

@@ -0,0 +1,78 @@
+/**
+ * Inter-request pacing (v3.24, direction #6 — behavioral smoothing).
+ *
+ * Real CC traffic has human-paced gaps between requests — sub-second when
+ * the model is streaming tool-loop output, multi-second when the user is
+ * typing the next message. A proxy that fires requests at machine speed
+ * with perfectly uniform spacing stands out against that rhythm.
+ *
+ * This module supplies the pure gap-calculation function the proxy's
+ * rate governor calls before every outbound fetch. Two knobs:
+ *
+ *   minGapMs    — lower bound on the wall-clock distance between requests.
+ *                 Was a hardcoded 500ms through v3.23; keep 500 as default
+ *                 so back-compat is exact when both knobs stay at defaults.
+ *
+ *   jitterMs    — uniform random addition on top of minGap. The *effective*
+ *                 gap for a given request is minGap + U(0, jitter). Adds
+ *                 non-uniformity so an observer can't infer the floor from
+ *                 the long-run minimum of inter-arrival times.
+ *
+ * Pure over (now, lastRequestTime, minGap, jitter, rng) so the tests can
+ * exercise every edge without spawning timers. The proxy passes
+ * `Math.random` as the rng at runtime; tests pass a deterministic stub.
+ *
+ * The first request in a session (lastRequestTime === 0) is never paced —
+ * the purpose is smoothing the *gap between* requests, not delaying the
+ * first one from whenever the consumer happens to connect.
+ */
+/**
+ * How many milliseconds to sleep before the next upstream fetch.
+ *
+ * Returns 0 when no delay is required — either because this is the first
+ * request of the session, or enough wall-clock time has already elapsed
+ * since `lastRequestTime`.
+ *
+ * `rng` defaults to Math.random; tests inject a deterministic stub.
+ * Negative configuration values are clamped to 0 (lenient, not an error).
+ */
+export function computePacingDelay(now, lastRequestTime, cfg, rng = Math.random) {
+    if (lastRequestTime <= 0)
+        return 0;
+    const minGap = Math.max(0, cfg.minGapMs);
+    const jitter = Math.max(0, cfg.jitterMs);
+    const jitterAdd = jitter > 0 ? Math.floor(rng() * jitter) : 0;
+    const effectiveGap = minGap + jitterAdd;
+    const elapsed = now - lastRequestTime;
+    if (elapsed >= effectiveGap)
+        return 0;
+    return effectiveGap - elapsed;
+}
+/**
+ * Resolve a PacingConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_PACE_MIN_MS / DARIO_PACE_JITTER_MS env vars
+ *   3. Legacy DARIO_MIN_INTERVAL_MS env var (minGap only — matches v3.23
+ *      behavior so existing setups don't regress silently)
+ *   4. Defaults: minGap=500, jitter=0
+ *
+ * Invalid strings (non-numeric, negative) are ignored and fall through to
+ * the next source — a typoed env var shouldn't fail-loud at startup.
+ */
+export function resolvePacingConfig(explicit = {}, env = process.env) {
+    const minGap = pickNonNegativeInt(explicit.minGapMs, env.DARIO_PACE_MIN_MS, env.DARIO_MIN_INTERVAL_MS) ?? 500;
+    const jitter = pickNonNegativeInt(explicit.jitterMs, env.DARIO_PACE_JITTER_MS) ?? 0;
+    return { minGapMs: minGap, jitterMs: jitter };
+}
+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;
+}

package/dist/proxy.d.ts

@@ -12,6 +12,9 @@ interface ProxyOptions {
     preserveTools?: boolean;
     hybridTools?: boolean;
     noAutoDetect?: boolean;
+    strictTls?: boolean;
+    pacingMinMs?: number;
+    pacingJitterMs?: number;
 }
 export declare function sanitizeError(err: unknown): string;
 export declare function startProxy(opts?: ProxyOptions): Promise<void>;

package/dist/proxy.js

@@ -363,6 +363,22 @@ export async function startProxy(opts = {}) {
     const host = opts.host ?? process.env.DARIO_HOST ?? DEFAULT_HOST;
     const verbose = opts.verbose ?? false;
     const passthrough = opts.passthrough ?? false;
+    // TLS-fingerprint axis (v3.23, direction #3). Proxy mode terminates TLS
+    // to api.anthropic.com from this process; if we're not on Bun, the
+    // ClientHello that reaches Anthropic is Node's OpenSSL shape, not CC's
+    // Bun/BoringSSL shape. `--strict-tls` turns this silent divergence into
+    // a startup refusal. Doctor + the always-on banner below surface the
+    // same information without aborting, for users who know they're fine
+    // (API-key billing, single-call invocations, shim-mode-elsewhere, etc.).
+    const { detectRuntimeFingerprint } = await import('./runtime-fingerprint.js');
+    const runtimeFp = detectRuntimeFingerprint();
+    if (opts.strictTls && runtimeFp.status !== 'bun-match') {
+        console.error(`[dario] --strict-tls: ${runtimeFp.detail}`);
+        if (runtimeFp.hint)
+            console.error(`[dario]   → ${runtimeFp.hint}`);
+        console.error('[dario] refusing to start proxy mode. Omit --strict-tls to run anyway.');
+        process.exit(1);
+    }
     // Text-tool-protocol client families that have already logged a
     // "detected → auto-enabling preserve-tools" banner this session.
     // Set once on first sighting per family so the startup log stays
@@ -555,10 +571,19 @@ export async function startProxy(opts = {}) {
         betaBase = betaBase ? `${betaBase},oauth-2025-04-20` : 'oauth-2025-04-20';
     }
     const betaWithoutContext1m = betaBase.split(',').filter((t) => t !== 'context-1m-2025-08-07').join(',');
-    // Rate governor — minimum 500ms between requests. Fast enough for agents,
-    // slow enough to not look like a scripted flood of identical traffic.
+    // Rate governor — floor + optional jitter between requests. A hardcoded
+    // 500ms floor keeps the default behavior identical to v3.23; `--pace-min`
+    // and `--pace-jitter` let callers tune the distribution. Pure calc lives
+    // in src/pacing.ts so the edge cases are unit-tested without timers.
+    const { computePacingDelay, resolvePacingConfig } = await import('./pacing.js');
     let lastRequestTime = 0;
-    const MIN_REQUEST_INTERVAL_MS = parseInt(process.env.DARIO_MIN_INTERVAL_MS || '500', 10);
+    const pacingCfg = resolvePacingConfig({
+        minGapMs: opts.pacingMinMs,
+        jitterMs: opts.pacingJitterMs,
+    });
+    if (verbose) {
+        console.log(`[dario] pacing: min=${pacingCfg.minGapMs}ms jitter=${pacingCfg.jitterMs}ms`);
+    }
     // Optional proxy authentication — pre-encode key buffer for performance
     const apiKey = process.env.DARIO_API_KEY;
     const apiKeyBuf = apiKey ? Buffer.from(apiKey) : null;
@@ -1060,11 +1085,11 @@ export async function startProxy(opts = {}) {
                     beta = beta.split(',').filter((t) => t.length > 0 && !rejectedSet.has(t)).join(',');
                 }
             }
-            // Rate governor — prevent inhuman request cadence
-            const now = Date.now();
-            const elapsed = now - lastRequestTime;
-            if (elapsed < MIN_REQUEST_INTERVAL_MS && lastRequestTime > 0) {
-                await new Promise(r => setTimeout(r, MIN_REQUEST_INTERVAL_MS - elapsed));
+            // Rate governor — prevent inhuman request cadence. See src/pacing.ts
+            // for the pure delay calculator (floor + uniform jitter).
+            const pacingDelay = computePacingDelay(Date.now(), lastRequestTime, pacingCfg);
+            if (pacingDelay > 0) {
+                await new Promise(r => setTimeout(r, pacingDelay));
             }
             lastRequestTime = Date.now();
             // Session ID: pool mode uses the per-account identity.sessionId (stable
@@ -1635,6 +1660,15 @@ export async function startProxy(opts = {}) {
     if (compat.status === 'below-min' || compat.status === 'untested-above') {
         console.log(`[dario] ⚠  CC compat: ${compat.message}`);
     }
+    // TLS-fingerprint banner (v3.23). Proxy mode terminates TLS from this
+    // process, so the Bun-vs-Node runtime choice is actually on the wire.
+    // Silence via DARIO_QUIET_TLS=1 for known-fine environments.
+    if (runtimeFp.status !== 'bun-match' && process.env.DARIO_QUIET_TLS !== '1') {
+        console.log(`[dario] ⚠  TLS fingerprint: ${runtimeFp.detail}`);
+        if (runtimeFp.hint)
+            console.log(`[dario]    → ${runtimeFp.hint}`);
+        console.log('[dario]    (silence with DARIO_QUIET_TLS=1, or use --strict-tls to hard-fail)');
+    }
     // Kick off a live fingerprint refresh in the background. Re-captures the
     // user's own CC binary request shape and updates ~/.dario/cc-template.live.json
     // for the next startup. No-op if CC isn't installed or the cache is fresh.

package/dist/runtime-fingerprint.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Runtime TLS-fingerprint detector (direction #3 from the v3.22 roadmap).
+ *
+ * The Claude Code binary is a Bun-compiled standalone executable, so every
+ * HTTPS request it makes goes out through Bun's BoringSSL-derived TLS stack.
+ * That ClientHello (JA3/JA4 hash) is what Anthropic's TLS-layer classifier
+ * actually sees on the wire.
+ *
+ * Dario has two transports with different exposure to this axis:
+ *
+ *   - **Shim mode** runs inside CC's own process (NODE_OPTIONS=--require),
+ *     so its outbound fetch rides on CC's TLS stack by construction.
+ *     Nothing to reconcile — the shim is always TLS-matched to CC.
+ *
+ *   - **Proxy mode** is a separate process holding its own TLS sessions
+ *     to api.anthropic.com. Anthropic sees the proxy's TLS fingerprint,
+ *     not the consumer client's. If the proxy runs under Node, the
+ *     ClientHello is OpenSSL-shaped — distinct from Bun's BoringSSL shape.
+ *     That's the JA3 gap this module flags.
+ *
+ * Mitigation today: dario auto-relaunches under Bun when Bun is on PATH
+ * (see top of `src/cli.ts`). When Bun isn't available the auto-relaunch
+ * is a silent no-op, so proxy mode silently runs on Node's TLS stack
+ * with no indication to the operator. This module makes the runtime
+ * status a first-class check: `dario doctor` reports it, proxy startup
+ * warns when the axis is mismatched, and `--strict-tls` hard-fails
+ * instead of silently running with a divergent fingerprint.
+ *
+ * Pure-function: every input is passed in explicitly so tests can
+ * exercise each runtime combination without spawning processes.
+ */
+/** Canonical buckets the caller pivots on. */
+export type RuntimeFingerprintStatus = 
+/** Running under Bun — TLS stack matches CC. */
+'bun-match'
+/** Running under Node, Bun available on PATH but auto-relaunch was bypassed. */
+ | 'bun-bypassed'
+/** Running under Node, Bun not installed. */
+ | 'node-only';
+export interface RuntimeFingerprint {
+    status: RuntimeFingerprintStatus;
+    /** 'bun' or 'node' — which runtime this process is actually on. */
+    runtime: 'bun' | 'node';
+    /** Version string from the runtime (e.g. "1.1.30" or "v20.11.1"). */
+    runtimeVersion: string;
+    /** Bun version discovered on PATH, if any. undefined when runtime==='bun' or bun-not-found. */
+    availableBunVersion?: string;
+    /** Why auto-relaunch didn't fire when `status === 'bun-bypassed'`. */
+    bypassReason?: 'DARIO_NO_BUN' | 'unknown';
+    /** Human-readable one-line explanation for the check label. */
+    detail: string;
+    /** Actionable hint when status !== 'bun-match'. undefined otherwise. */
+    hint?: string;
+}
+/**
+ * Probe the Bun binary on PATH without relaunching. Returns undefined
+ * when bun isn't installed or the version probe fails for any reason
+ * (timeout, non-zero exit, etc.). Kept synchronous to match cli.ts's
+ * pre-import flow; doctor.ts is the only other caller and is fine with
+ * the (~sub-100ms) cost when Bun is installed.
+ */
+export declare function probeBunVersion(): string | undefined;
+/**
+ * Synthesize the TLS-fingerprint status from three inputs. All three are
+ * passed explicitly so tests can cover every combination without touching
+ * the real environment. Production callers pass
+ *   `classifyRuntimeFingerprint(typeof Bun !== 'undefined', probeBunVersion(), process.env)`.
+ *
+ * The `env` parameter is read-only — this function never mutates it.
+ */
+export declare function classifyRuntimeFingerprint(runningUnderBun: boolean, availableBunVersion: string | undefined, env: Record<string, string | undefined>, nodeVersion?: string): RuntimeFingerprint;
+/**
+ * Convenience wrapper that reads the current process state. doctor.ts
+ * calls this once; tests do not — they exercise classifyRuntimeFingerprint
+ * directly with synthetic inputs.
+ */
+export declare function detectRuntimeFingerprint(): RuntimeFingerprint;

package/dist/runtime-fingerprint.js

@@ -0,0 +1,117 @@
+/**
+ * Runtime TLS-fingerprint detector (direction #3 from the v3.22 roadmap).
+ *
+ * The Claude Code binary is a Bun-compiled standalone executable, so every
+ * HTTPS request it makes goes out through Bun's BoringSSL-derived TLS stack.
+ * That ClientHello (JA3/JA4 hash) is what Anthropic's TLS-layer classifier
+ * actually sees on the wire.
+ *
+ * Dario has two transports with different exposure to this axis:
+ *
+ *   - **Shim mode** runs inside CC's own process (NODE_OPTIONS=--require),
+ *     so its outbound fetch rides on CC's TLS stack by construction.
+ *     Nothing to reconcile — the shim is always TLS-matched to CC.
+ *
+ *   - **Proxy mode** is a separate process holding its own TLS sessions
+ *     to api.anthropic.com. Anthropic sees the proxy's TLS fingerprint,
+ *     not the consumer client's. If the proxy runs under Node, the
+ *     ClientHello is OpenSSL-shaped — distinct from Bun's BoringSSL shape.
+ *     That's the JA3 gap this module flags.
+ *
+ * Mitigation today: dario auto-relaunches under Bun when Bun is on PATH
+ * (see top of `src/cli.ts`). When Bun isn't available the auto-relaunch
+ * is a silent no-op, so proxy mode silently runs on Node's TLS stack
+ * with no indication to the operator. This module makes the runtime
+ * status a first-class check: `dario doctor` reports it, proxy startup
+ * warns when the axis is mismatched, and `--strict-tls` hard-fails
+ * instead of silently running with a divergent fingerprint.
+ *
+ * Pure-function: every input is passed in explicitly so tests can
+ * exercise each runtime combination without spawning processes.
+ */
+import { execFileSync } from 'node:child_process';
+/**
+ * Probe the Bun binary on PATH without relaunching. Returns undefined
+ * when bun isn't installed or the version probe fails for any reason
+ * (timeout, non-zero exit, etc.). Kept synchronous to match cli.ts's
+ * pre-import flow; doctor.ts is the only other caller and is fine with
+ * the (~sub-100ms) cost when Bun is installed.
+ */
+export function probeBunVersion() {
+    try {
+        const out = execFileSync('bun', ['--version'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 3000,
+            encoding: 'utf-8',
+        });
+        const trimmed = out.trim();
+        // `bun --version` prints just the version like "1.1.30". Reject anything
+        // longer than a sanity threshold so an unrelated `bun` binary can't
+        // poison the detection.
+        if (trimmed.length > 0 && trimmed.length < 32 && /^[0-9]/.test(trimmed)) {
+            return trimmed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Synthesize the TLS-fingerprint status from three inputs. All three are
+ * passed explicitly so tests can cover every combination without touching
+ * the real environment. Production callers pass
+ *   `classifyRuntimeFingerprint(typeof Bun !== 'undefined', probeBunVersion(), process.env)`.
+ *
+ * The `env` parameter is read-only — this function never mutates it.
+ */
+export function classifyRuntimeFingerprint(runningUnderBun, availableBunVersion, env, nodeVersion = process.version) {
+    if (runningUnderBun) {
+        // When we're under Bun, we expose the Bun version if globalThis.Bun.version
+        // is readable; we don't require a separate probe. The caller passes the
+        // resolved version string as `availableBunVersion` in the bun case.
+        const bunVer = availableBunVersion ?? 'unknown';
+        return {
+            status: 'bun-match',
+            runtime: 'bun',
+            runtimeVersion: bunVer,
+            detail: `Bun v${bunVer} — TLS fingerprint matches Claude Code`,
+        };
+    }
+    if (availableBunVersion !== undefined) {
+        const reason = env.DARIO_NO_BUN ? 'DARIO_NO_BUN' : 'unknown';
+        return {
+            status: 'bun-bypassed',
+            runtime: 'node',
+            runtimeVersion: nodeVersion,
+            availableBunVersion,
+            bypassReason: reason,
+            detail: `Node ${nodeVersion} — Bun v${availableBunVersion} on PATH but auto-relaunch bypassed (${reason})`,
+            hint: reason === 'DARIO_NO_BUN'
+                ? 'Unset DARIO_NO_BUN to auto-relaunch under Bun on the next invocation.'
+                : 'Run dario fresh (no inherited DARIO_NO_BUN) so auto-relaunch can fire.',
+        };
+    }
+    return {
+        status: 'node-only',
+        runtime: 'node',
+        runtimeVersion: nodeVersion,
+        detail: `Node ${nodeVersion} — Bun not installed; proxy-mode TLS fingerprint diverges from Claude Code`,
+        hint: 'Install Bun (https://bun.sh) so dario can auto-relaunch under it, or use shim mode ' +
+            '(`dario shim -- claude …`) which runs inside CC\'s own process and inherits its TLS stack.',
+    };
+}
+/**
+ * Convenience wrapper that reads the current process state. doctor.ts
+ * calls this once; tests do not — they exercise classifyRuntimeFingerprint
+ * directly with synthetic inputs.
+ */
+export function detectRuntimeFingerprint() {
+    const bunGlobal = globalThis.Bun;
+    const runningUnderBun = typeof bunGlobal?.version === 'string';
+    if (runningUnderBun) {
+        return classifyRuntimeFingerprint(true, bunGlobal?.version, process.env);
+    }
+    const probed = probeBunVersion();
+    return classifyRuntimeFingerprint(false, probed, process.env);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.22.0",
+  "version": "3.24.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/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/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/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",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",