@askalf/dario 5.4.15 → 5.4.17

package/docs/drift-monitor.md

@@ -0,0 +1,290 @@
+# Drift monitor
+
+Dario's bundled CC template (`src/cc-template-data.json`) is the wire-shape
+fallback the proxy uses when it can't fingerprint a live CC install. For that
+fallback to be honest, the bundle has to keep up with what real CC is actually
+sending on the wire. CC drifts in two distinct ways, and there are two
+distinct watchers — one of which needs a self-hosted runner.
+
+## Two classes of drift
+
+**Class A — npm-release drift.** Anthropic ships a new `@anthropic-ai/claude-code`
+to npm. The binary changes; the wire shape usually changes with it (new tools,
+new system-prompt slots, beta-header swaps). This is the visible kind.
+
+> Watched by `.github/workflows/cc-drift-watch.yml`. Runs on a GitHub-hosted
+> runner, no auth required — polls npm, diffs the dist file, opens an issue
+> when the bundled `_version` is behind latest.
+
+**Class B — same-binary remote-config drift.** Anthropic does *not* ship a new
+npm version, but the wire shape changes anyway. We documented an instance of
+this in [CHANGELOG `4.2.1`](../CHANGELOG.md#421---2026-05-17): same CC `2.1.143`
+binary, same machine, captures 24h apart produced materially different
+`/v1/messages` bodies (different anthropic-beta header, +355 char system
+prompt). The npm watcher can't see this; the binary is unchanged.
+
+> Watched by `.github/workflows/cc-drift-template-watch.yml`. Runs on a
+> **self-hosted** runner because it needs a live, authenticated CC install
+> to capture against. Runs `node scripts/capture-and-bake.mjs --check` every
+> 30 min and opens (or comments on) a `cc-drift-template`-labeled issue when
+> the captured template diverges from the committed bundle.
+>
+> Watched-by-the-watcher: `.github/workflows/cc-drift-watcher-liveness.yml`
+> runs every 2 hours on a github-hosted runner and opens a
+> `cc-watcher-liveness`-labeled alert if the class-B watcher has not had a
+> successful run within 8 hours (≥ 16 missed cycles). Catches "runner went
+> offline silently" — the failure mode where class-B drift goes uncaught
+> because the watcher itself is down. The liveness watcher lives on
+> github-hosted infrastructure deliberately so it survives the exact failure
+> modes it's designed to detect.
+
+**Class C — billing-classifier drift** *(v4.6.0)*. Different signal again:
+Anthropic changes the classifier *rules* — adds a new signal, tightens an
+existing one, flips a threshold — and dario's canonical-rebuild output no
+longer scores as `subscription` even though CC's wire shape is unchanged.
+The template-drift watcher cannot see this because nothing in CC's outbound
+has moved; only an end-to-end "send a real request, inspect the billing
+bucket" probe catches it.
+
+> Watched by `.github/workflows/cc-billing-classifier-canary.yml`. Runs daily
+> at 06:30 UTC on the same self-hosted runner. Sends one tiny haiku request
+> through `dario proxy` (canonical-rebuild mode, NOT `--passthrough`),
+> captures the `representative-claim` response header, opens a
+> `cc-billing-canary`-labeled alert when it flips to `overage` / `api`
+> / `unknown`. Auto-closes when it next returns a subscription bucket.
+> Cost: ~1 small subscription request per day.
+
+## What --check considers drift
+
+The `--check` mode in `scripts/capture-and-bake.mjs` deliberately ignores
+fields that always differ between runs (`_captured` timestamp, user-agent
+string, `_version` / `_supportedMaxTested` labels). It flags **shape** drift in:
+
+- **tools** added or removed (by name set)
+- **anthropic_beta** header values added or removed
+- **system_prompt** content (any character delta)
+- **body_field_order** (top-level JSON key order)
+- **header_order**
+- **agent_identity** content
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| 0   | Full match — wire shape AND `_version` label both current |
+| 1   | Infrastructure failure (CC not on PATH, capture timeout, scrub leak, or installed CC **older** than the bundle's capture — stale runner) |
+| 2   | **Shape** drift vs current bundled template (needs a real re-bake) |
+| 3   | **Label-only** drift — wire shape matches but `_version` lags the live CC version |
+
+The workflow swallows exit 2 and 3 (continues to the next step) so the
+remediation steps can run; exit 1 fails the job.
+
+The stale-runner case matters because an older binary cannot observe forward
+drift — it re-captures the *previous* wire shape, which `--check` would report
+as exit-2 drift and the watcher would auto-rebake as a template **downgrade**.
+That exact sequence reached the ship gate on 2026-07-02 (PR #632: runner CC at
+2.1.197 against the 2.1.198-baked bundle reported the afk-mode beta
+"removed"). The guard compares the captured CC version against the bundle's
+`_version` and exits 1 with an update-the-runner message when the binary is
+older. A *deliberate* downgrade bake (an upstream CC release gets pulled and
+the bundle must go backward) bypasses it with `--allow-older-cc`.
+
+### Exit 2 vs exit 3 — why the split, and why only one auto-merges
+
+Because `--check` ignores `_version`, a CC release whose wire shape is
+*unchanged* (the common case for a patch bump) produces a bundle whose shape
+matches live CC but whose `_version` label is stale. The shape-only detector
+sees no drift (exit 0 territory), yet `sdk-drift-watch.yml` — which compares
+the `_version` label against `@anthropic-ai/claude-code@latest` on npm — flags
+it, with **nothing to re-bake**. That mismatch used to require a hand PR every
+time (issues #418, #426/#427, #445/#451).
+
+Exit 3 captures exactly that case (`computeDrift` empty **and**
+`bundled._version !== live._version`) and writes the live version to
+`label-target.txt`. The **Label-sync** workflow step then runs
+`scripts/label-sync.mjs`, which bumps only the three version-label fields
+(`_version`, `_supportedMaxTested`, and the `claude-cli/<v>` token in the
+user-agent header) — never the wire shape — patch-bumps `package.json`,
+promotes the CHANGELOG, opens a `bot/template-label-*` PR, and turns on
+**auto-merge**.
+
+Auto-merge is safe for exit 3 but **not** for exit 2: an empty `computeDrift`
+is a proof that the tools / system_prompt / beta headers / field orders are
+byte-identical at the live version, so only the version string moves — the
+same deterministic-bump risk class `cc-drift-watch.yml` already auto-merges for
+`SUPPORTED_CC_RANGE.maxTested`. Auto-merge still gates on the required checks
+(build ×3, compat, test, docker-cap-drop-smoke); a red check leaves the PR open
+with the bot branch preserved. A shape rebake (exit 2) changes the wire-shape
+contract, so a human reviews compat-test + the diff before merging.
+
+## Setting up the self-hosted runner
+
+Any dedicated Linux host works. Hetzner / DO / EC2 / etc. The runner needs
+Node 22, a logged-in `claude` CLI, and disk for a clone of the repo (~200 MB
+including `node_modules`).
+
+### Prerequisites
+
+```bash
+# 1. Node 22 + npm
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
+sudo apt-get install -y nodejs
+
+# 2. GitHub CLI (`gh`) — the workflow's issue-open step shells out to it.
+#    Without this, --check correctly detects drift but the "Open / update
+#    drift issue" step fails with `gh: command not found`.
+sudo apt-get install -y gh   # or follow https://github.com/cli/cli#installation
+
+# 3. CC + dario CLI (dario provides the headless OAuth flow)
+sudo npm i -g @anthropic-ai/claude-code @askalf/dario
+
+# 4. OAuth — manual flow for headless boxes. Run from the host's shell,
+#    follow the printed URL in any browser, paste the post-login callback
+#    URL back into the SSH session.
+#
+#    SHARE the credential with any other CC clients that auto-refresh
+#    (e.g. a platform dario container running 24/7). Just run the standard
+#    `dario login --manual` against /root/.claude/.credentials.json and let
+#    that long-running refresh authority keep the token fresh. The workflows
+#    read whatever's current at fire time and never attempt a refresh from
+#    the runner side.
+#
+#    History: v4.4.1 isolated the runner's credential at /root/.claude-runner
+#    to avoid OAuth refresh-token rotation races between the runner and other
+#    CC clients on the host. The isolation worked for races but introduced a
+#    different failure: the isolated token had no refresh authority between
+#    workflow fires (each <10 min, often hours apart), and Anthropic invalidates
+#    refresh tokens that idle too long. Result: `invalid_grant` on every
+#    workflow fire, recoverable only via interactive `dario login --manual`.
+#
+#    Sharing with a 24/7 refresh authority (typical setup: the docker-stack
+#    dario container) fixes that. The race the isolation was protecting
+#    against is rare in practice — platform dario refreshes proactively
+#    when the access token has ~1h life remaining, so workflow runs hit a
+#    fresh token and don't need to refresh themselves.
+dario login --manual
+
+# 5. Smoke test:
+echo "Reply with PONG" | claude --print     # should print PONG
+```
+
+### One-time repo setup
+
+The workflow's issue-open step calls `gh issue create --label cc-drift-template`
+which fails if the label doesn't exist in the repo. Create it once before the
+runner's first execution:
+
+```bash
+gh label create cc-drift-template \
+  --description "Bundled CC template has drifted from live capture" \
+  --color FBCA04
+```
+
+### Register the runner
+
+In a browser: `https://github.com/<owner>/<repo>/settings/actions/runners/new`.
+Pick Linux x64. GitHub prints a `mkdir`/`curl`/`tar`/`./config.sh` snippet.
+Paste it into the host. At the labels prompt, type **`dario-drift`** — the
+workflow gates on `runs-on: [self-hosted, dario-drift]`, so the label is
+load-bearing.
+
+### Install as a systemd service
+
+```bash
+cd ~/actions-runner
+sudo ./svc.sh install $(whoami)   # run as the same user that owns ~/.claude
+sudo ./svc.sh start
+sudo ./svc.sh status              # → "active (running)"
+```
+
+If the runner runs as `root` and `~/.claude/.credentials.json` lives under
+`/root/`, `RUNNER_ALLOW_RUNASROOT=1 ./config.sh ...` lets `./config.sh` run as
+root; GitHub's runner otherwise refuses root by default.
+
+### Trigger once to verify
+
+GitHub UI → Actions → **CC template drift watch (self-hosted)** → "Run
+workflow." It should pick up the labeled runner within seconds and finish
+within ~60s. Exit 0 (no drift) or exit 2 (issue auto-opened with the drift
+report) both mean the pipeline is healthy. Exit 1 means the capture broke;
+check the workflow logs.
+
+After the first successful run, the `*/30 * * * *` cron takes over.
+
+## When --check fires an issue
+
+The workflow opens (or comments on) an issue labeled `cc-drift-template`
+containing the `[bake]` output — the list of differing slots, sizes, tool
+names. From there:
+
+```bash
+# On a maintainer machine with CC + a logged-in OAuth credential:
+npm run build
+node scripts/capture-and-bake.mjs   # rewrites src/cc-template-data.json
+git diff src/cc-template-data.json  # review
+# Open a PR with the re-bake; the auto-release pipeline publishes a patch
+# version. The next clean --check cycle auto-closes the drift issue.
+```
+
+## Optional: PAT for downstream workflow triggers
+
+Since v4.4.0, the watcher auto-opens a `bot/template-rebake-*` PR on detection. Since v4.3.0, `compat-test-self-hosted.yml` is supposed to run on PRs touching `src/cc-template-data.json`. **Without the setup below, it doesn't.** GitHub Actions has a deliberate restriction: workflows authenticated by the default `GITHUB_TOKEN` cannot trigger downstream workflow runs ([docs](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow)). The auto-rebake PR is therefore invisible to compat-test, and the validation gate the v4.4.0 design promised is effectively bypassed.
+
+To close the gap, create a fine-grained personal access token (PAT) scoped to this repo and expose it to the watcher as `DARIO_DRIFT_BOT_PAT`:
+
+1. **Generate** at `https://github.com/settings/personal-access-tokens/new`:
+   - Resource owner: your user (or org)
+   - Repository access: select `dario` only
+   - Permissions: **Contents: read & write**, **Pull requests: read & write**, **Issues: read & write**
+   - Expiration: whatever your security policy mandates (90 days / 1 year)
+
+2. **Store** at `Settings → Secrets and variables → Actions → New repository secret`:
+   - Name: `DARIO_DRIFT_BOT_PAT`
+   - Value: the PAT from step 1
+
+3. **Verify** on the next watcher cycle that detects drift. The auto-rebake PR's "Checks" tab should now include the `compat` job (which it didn't pre-v4.6.5).
+
+The watcher workflow uses `GH_TOKEN: ${{ secrets.DARIO_DRIFT_BOT_PAT || secrets.GITHUB_TOKEN }}` for `gh` CLI ops, so the PAT is **optional** — the watcher keeps working without it, you just don't get compat-test gating on auto-rebake PRs (same behavior as v4.4.0 through v4.6.4). The fallback exists so a maintainer can defer the PAT setup without breaking the loop.
+
+## Runner credential rate-limit headroom
+
+Workflows that exercise live `dario proxy` paths (compat-test, billing canary, future end-to-end probes) all consume against the runner credential's subscription pool. The cadence assumptions are:
+
+| Workflow | Declared cadence | Observed cadence | Requests per fire |
+|---|---|---|---|
+| `cc-drift-template-watch.yml` (`--check`) | every 30 min (`*/30 * * * *`) | typically every 2-4h | 1 capture (no /v1/messages traffic — MITM-only) |
+| `cc-billing-classifier-canary.yml` | daily 06:30 UTC | daily | 1 small haiku request |
+| `compat-test-self-hosted.yml` | per qualifying PR | per qualifying PR | ~11 small requests |
+
+**Cron scheduler reality.** GitHub Actions' free-tier cron scheduler is best-effort, not guaranteed. The class-B watcher declares `*/30 * * * *` but in practice GitHub honors it every 2-4 hours on this repo. The liveness alarm (added v4.4.2) has its threshold set to 8h (raised from 3h in v4.7.1) to absorb this skew — anything past that is signal, not scheduler noise. If you need a tighter SLA (sub-hour), self-host the runner *and* the cron driver (e.g. a cron entry on the same Hetzner box invoking `gh workflow run` directly).
+
+At steady state, this is comfortably inside Pro/Max headroom. The failure mode to watch for is **batched firing** — manually re-triggering the same workflow several times in a single hour, or PRs landing in rapid succession that each fire compat-test. We tripped this during the v4.6.x rollout: a half-dozen manual re-runs in a 2-hour window 429'd the runner credential. Pro/Max accounts have per-hour rate caps as well as per-5h / per-7d pools, and the per-hour cap is what surfaces first.
+
+If the runner credential is rate-limited and a workflow run reports 429s across the board, the right diagnosis order is: (a) check `claude --print` directly — if it 429s, the credential pool is dry, just wait an hour; (b) check the credential is still on a subscription account (`dario doctor`); (c) check workflow cadence assumptions haven't changed.
+
+The runner shares its OAuth credential with any other long-running CC client on the box (typically the platform dario container, which auto-refreshes 24/7). Sharing is intentional: a workflow that fires sparsely cannot keep its own refresh token alive — Anthropic invalidates idle refresh tokens, and `invalid_grant` then breaks every subsequent run. Letting a 24/7 refresh authority own the token rotation eliminates that failure mode at the cost of competing for the same Pro/Max headroom. With current cadence (drift-template-watch every 30 min + compat per PR + canary daily), runner-side burn on the shared account is a manageable fraction of the headroom available on a Max plan; reducing cadence further is a knob if a particular workload needs more of it.
+
+## Why a self-hosted runner
+
+GitHub-hosted runners can't capture CC. They have no Pro/Max subscription
+session, no MITM cert trust for CC's loopback proxy, no way to authenticate
+against `claude.ai/oauth`. Anything that needs real CC running against real
+Anthropic has to live on a host you control with an account you've logged
+in to.
+
+The runner is read-only against the repo (`contents: read`) and only writes
+to issues (`issues: write`). It cannot push, tag, or release.
+
+## Platform-superset preservation
+
+CC ships different tools on different platforms — currently just `PowerShell`
+on Windows, but the surface grows over time. The bundled template is meant to
+be a **union** across platforms, and `filterToolsForPlatform()` strips it down
+at request time. So a bake on Linux must not silently drop the Windows tool
+set, or Windows dario users would lose those tools on the next release.
+
+`scripts/capture-and-bake.mjs` preserves tools from the previous bundle whose
+names are listed in `PLATFORM_ONLY_TOOLS` for a platform other than the
+baking host's. The merged set is re-sorted alphabetically to match CC's wire
+order. The runner can therefore bake from Linux without regressing Windows
+users.

package/docs/faq.md

@@ -0,0 +1,145 @@
+# FAQ
+
+**Does this violate Anthropic's terms of service?**
+Mechanically: dario's Claude backend uses your existing Claude Code credentials with the same OAuth tokens CC uses. It authenticates you as you, with your subscription, through Anthropic's official API endpoints. Whether any particular use complies with Anthropic's current terms of service is between you and Anthropic — consult their terms and your own subscription agreement. This project is an independent, unofficial, third-party tool and does not provide legal advice. See [DISCLAIMER.md](../DISCLAIMER.md).
+
+**What subscription plans work on the Claude backend?**
+Any plan whose account currently has Claude Code access — Max has it unconditionally; Pro has it as of this writing but that's an upstream decision that has moved once already (see next entry). If `claude /login` on your account works and `claude -p "hi"` returns a response on subscription billing, dario's Claude backend will work too. If Anthropic removes Claude Code from your plan tier, dario's Claude backend stops working on that account — there is nothing dario can do at the client side to change that. Swap to a plan with Claude Code access, or use an OpenAI-compat backend instead.
+
+**Is it true Anthropic removed Claude Code from Pro plans?**
+On 2026-04-21 Anthropic temporarily removed Claude Code from new Pro signups, per [wheresyoured.at](https://www.wheresyoured.at/news-anthropic-removes-pro-cc/). Existing Pro users reportedly kept access; Anthropic's Head of Growth characterized it as "a small test of 2% of new prosumer signups," and the change was reversed at an unknown time. If you are a Pro user and dario's Claude backend stops billing against your subscription without warning, this is the class of thing to check — run `claude -p "hi"` directly and see whether Anthropic itself routes you to subscription billing. If they don't, dario can't either. The practical mitigation on dario's side is [multi-account pool mode](./multi-account-pool.md) — having a backup account on a plan Anthropic hasn't moved the goalposts on, so a single plan-tier change doesn't take all your traffic down at once.
+
+**Does it work with Team / Enterprise?**
+Yes — tested and confirmed working as long as your plan includes Claude Code access.
+
+**Anthropic announced that `claude -p` and Agent SDK usage would move to a separate credit pool on 2026-06-15. Did that break dario's Claude backend?**
+No — and the split itself was **paused before it took effect**. Anthropic announced it 2026-05-13, scheduled it for 2026-06-15, then paused it before that date; the Help Center now states Agent-SDK and `claude -p` usage continue drawing from your existing subscription pool unchanged, with a promise of advance notice before any revised version. So today `claude -p` and the Agent SDK still bill subscription whether or not you use dario.
+
+dario is built to hold either way. The Claude backend sends every request as **interactive Claude Code** wire-shape — full template replay of headers, body key order, TLS ClientHello, session-id lifecycle, inter-request timing. The upstream billing classifier sees an interactive CC session regardless of which local tool (claude -p subprocess, Agent SDK app, Cline, Aider, your own scripts) originated the call. That's the entire point of the wire-fidelity work in [`wire-fidelity.md`](./wire-fidelity.md), and it predates the announcement.
+
+What that means in practice:
+
+- Workloads that route through dario bill against your **subscription pool** (Pro $20, Max 5x $100, Max 20x $200) — the same today as before the announcement, and the same if a revised split ships later.
+- If the split does return, workloads that bypass dario and call `claude -p` directly would count against the **separate credit pool** (a fixed monthly grant rather than the rolling subscription bucket — and once exhausted, metered API pricing). Right now, paused, they bill subscription like everything else.
+- Workloads that use the Agent SDK with API keys are unaffected either way (already metered API).
+
+Two questions to verify at any time — and the exact check to run the day a revived split lands:
+
+1. **Is dario's traffic still landing in the subscription bucket?** Run `claude -p "hi"` directly (no dario), check `representative-claim` and related rate-limit headers — that tells you the bucket Anthropic put the direct call in. Then run the same prompt through dario and check the same headers. Both should show a subscription bucket (`five_hour` / `seven_day`). If dario's path ever shows an agent-credit or `overage` bucket, file an issue — that's the drift the live template extractor, the [drift detector](./../scripts/capture-full-body.mjs), and the daily billing-classifier canary exist to catch (the canary runs this exact check automatically and opens an issue on a bad bucket).
+2. **Did Anthropic tighten OAuth-token classification?** If access-token bearer alone ever signals "non-interactive," dario would have to add session affinity or a re-auth dance. The same rate-limit-header diagnostic surfaces it. None of this is observed today.
+
+No config change is needed on the user side, split or no split — same install, same `localhost:3456`, same `ANTHROPIC_BASE_URL=http://localhost:3456` env var.
+
+**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 template 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, 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 ClientHello is the only observable difference. As of v3.23, `dario doctor` surfaces the mismatch explicitly and `--strict-tls` refuses to start proxy mode until it's resolved.
+
+**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.
+
+**Can I route non-OpenAI providers through dario?**
+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=...`.
+
+**My subscription usage through dario is higher than running Claude Code directly. Why?**
+Two things drive this, and neither is proxy overhead — on the genuine-Claude-Code path dario forwards your request verbatim (system prompt + tools), adding only a ~20-token billing tag. First, the dominant cost on any cold turn is your **own** system prompt: agent harnesses (OpenClaw, context-mode, custom frameworks) can inject 100K+ tokens of instructions, and dario relays them byte-for-byte, so they cost the same sent direct. Second is the **prompt-cache TTL**. Anthropic caches your system+tools prefix so repeat turns read it warm instead of rebuilding — but the default lifetime is **5 minutes**. Interactive Claude Code on a subscription requests a **1-hour** TTL (`cache_control:{"type":"ephemeral","ttl":"1h"}` plus the `extended-cache-ttl-2025-04-11` beta); many SDK/agent harnesses only send the bare 5-minute stamp. dario mirrors exactly what your client sends — so if your harness sends 5m and you leave gaps longer than 5 minutes between messages, the prefix expires and is re-created every time. (Quick check: two messages **30 seconds** apart should be cheap; two messages **6 minutes** apart on a 5-minute stamp both pay full creation — that gap is the cost, not dario.)
+
+Fixes, cheapest first:
+- Keep turns within 5 minutes where you can — the prefix stays cached.
+- Trim the injected system prompt; it's the biggest line item on every cold turn.
+- Have your harness emit the 1-hour stamp + the `extended-cache-ttl-2025-04-11` beta — dario mirrors it and the prefix survives idle gaps.
+- If the harness can't, set **`DARIO_CACHE_TTL_1H=1`**: dario forces the 1-hour TTL (and adds the enabling beta) on every request. Tradeoff — 1-hour cache *writes* bill ~2× the 5-minute rate, so it only wins when your idle gaps routinely exceed 5 minutes; on rapid back-to-back turns it costs more. `DARIO_CACHE_TTL_5M=1` forces the opposite (always 5m). Background: [#678](https://github.com/askalf/dario/issues/678).
+
+  **Delivering the env var:** it has to reach dario's own process. Running directly, prefix it — `DARIO_CACHE_TTL_1H=1 dario proxy …`. In **Docker / Compose**, put it in the container's `environment:` (or `env_file:`) — a value only in a host `.env` that the compose file doesn't pass through never reaches the process, and the flag is silently a no-op. Confirm it landed with `docker exec <container> printenv DARIO_CACHE_TTL_1H` (expect `1`).
+
+**Something's wrong. Where do I start?**
+`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.)
+
+**OpenClaw returns 401 after I set `DARIO_API_KEY` (or upgrade past v3.30.6).**
+If you run `dario proxy --host=0.0.0.0` (non-loopback), dario requires `DARIO_API_KEY` to be set so it's not an open subscription relay. OpenClaw 2026.2.17+ prefers `~/.openclaw/agents/main/agent/auth-profiles.json` over `openclaw.json`'s `apiKey` field or the `ANTHROPIC_API_KEY` env var — so if you have a stale Anthropic token in `auth-profiles.json` from an earlier setup, OpenClaw sends *that* token instead of `dario`, and dario rejects the request with `Authorization present but value mismatch` (visible under `dario proxy -v`, added in v3.31.2).
+
+Three fixes, in order of simplicity:
+
+1. **Use loopback.** `dario proxy --host=127.0.0.1` — auth only enforced on non-loopback binds, no `DARIO_API_KEY` required, no OpenClaw changes. Best if you don't actually need LAN reach to dario.
+2. **Delete the Anthropic auth profile.** Remove the `"anthropic:default"` entry from `~/.openclaw/agents/main/agent/auth-profiles.json`. OpenClaw then falls back through the config chain and picks up `ANTHROPIC_API_KEY=dario` from the env. Confirmed working by [@tetsuco in #97](https://github.com/askalf/dario/issues/97).
+3. **Overwrite the auth profile.** `openclaw models auth paste-token --provider anthropic` and paste `dario`. Replaces whatever key was in there — keep a backup if you use it elsewhere.
+
+Diagnose with `dario proxy -v` — the reject log (v3.31.2+) reports header-name only (never the value, since it may be a real credential you mistyped) and tells you which of the three configs is actually being hit.
+
+**Claude Code's WebFetch fails on every domain with "Unable to verify if domain … is safe to fetch."**
+Not a dario issue — dario is not in this code path, and no dario configuration can affect it. Before fetching a URL, Claude Code runs a domain-safety preflight: a direct call to `https://api.anthropic.com/api/web/domain_info?domain=…` (older builds used `claude.ai`, which the error text still names). That URL is absolute, so it ignores `ANTHROPIC_BASE_URL` entirely — the preflight never reaches dario, and only the real fetch happens after it passes. The error means the preflight *request itself* failed to complete, not that the domain is blocklisted — common in proxy setups, headless/CI boxes, and networks where that direct call can't succeed.
+
+Fix: skip the preflight. Add to `~/.claude/settings.json` (or the project's `.claude/settings.json`) and restart Claude Code:
+
+```json
+{ "skipWebFetchPreflight": true }
+```
+
+The setting is Claude Code's own, meant for "enterprise environments with restrictive security policies"; with it set, WebFetch skips the domain check and fetches directly. Granting `Bash(curl:*)` so CC falls back to curl works too. Background: [#822](https://github.com/askalf/dario/issues/822).
+
+**My RDP / RemotePC session randomly drops while claude is working. Logs say `error 121` / `0x80070079` / "ERROR_SEM_TIMEOUT". Network is otherwise fine — other devices don't drop, gateway pings are clean.**
+Cause: heavy claude tool work bursts CPU on a small machine, the kernel network IO threads can't get scheduled, the RDP socket write times out, your session drops. The drops are real but the network path is not — they're caused by CPU starvation above the NIC layer, which is why every adapter (Ethernet, Wi-Fi, USB Wi-Fi) drops the same way. Confirmed pattern when running claude on a 4-core / 4-thread CPU you're RDP'd into.
+
+Two fixes, in order of progressively-stronger:
+
+1. **Lower claude's scheduling priority so the kernel can preempt it for network IO.** On Windows, launch it below-normal — `start /belownormal /b claude` (cmd), or set it after spawn with `(Get-Process claude).PriorityClass = 'BelowNormal'` (or Process Lasso for permanence). Same throughput when nothing else needs CPU. Escalate to `Idle` priority if drops continue — claude then only runs when nothing else is ready (~5-10% slower agent loops in practice). *(Before v5.0, `dario shim --priority=below-normal -- claude` did this for you; shim was removed in v5.0 — set the priority via the OS instead.)*
+2. **Reserve a CPU core for the OS.** On Windows, `(Get-Process claude).ProcessorAffinity = 0x07` reserves logical CPU 3 (mask covers cores 0-2). Set after spawn or via Process Lasso for permanence. On a 4-core/4-thread machine, this guarantees the kernel always has a free core for network IO no matter what claude does.
+
+If drops continue past all three: the underlying cause is hardware capacity. The same workload on a modern 8C/16T machine will not exhibit this. Move the heavy claude session off the RDP host, or upgrade the host.
+
+**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-v6.json`, keyed by the CC binary fingerprint. The cache path version bumps each time the canonical OAuth config shape changes so stale caches regenerate automatically on upgrade — v3 → v4 in v3.19.4 (scope-list flip CC v2.1.104 → v2.1.107), v4 → v5 in v3.31.3 (authorize URL `claude.com/cai/` → `claude.ai/` host normalization), v5 → v6 in v3.31.4 (6-scope restore after CC v2.1.116).
+
+If Anthropic rotates the values before the detector is updated, you can temporarily override any field with env vars (`DARIO_OAUTH_CLIENT_ID`, `DARIO_OAUTH_AUTHORIZE_URL`, `DARIO_OAUTH_TOKEN_URL`, `DARIO_OAUTH_SCOPES`) or by writing `~/.dario/oauth-config.override.json`:
+
+```json
+{
+  "clientId": "...",
+  "authorizeUrl": "https://claude.com/cai/oauth/authorize",
+  "tokenUrl": "https://platform.claude.com/v1/oauth/token",
+  "scopes": "user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload"
+}
+```
+
+Env vars win over the file. Set `DARIO_OAUTH_DISABLE_OVERRIDE=1` to force pure auto-detection.
+
+**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 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.
+
+**Why does `dario accounts list` show an account called `login` I never added?**
+That's your `dario login` credentials, materialized into the pool automatically. As of v5.0 the account pool is dario's one credential model, so a plain `dario login` is a **pool of one** stored as `~/.dario/accounts/login.json` under the reserved `login` alias — the back-fill runs on `dario login` itself and again on `dario proxy` startup. Your original `~/.dario/credentials.json` is untouched (the copy is one-way), so `dario accounts remove login` is safe if you don't want it pooled — the next `dario login` / `dario proxy` just re-materializes it. See [The account pool](./multi-account-pool.md) for the full picture.
+
+**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:
+```bash
+claude --print "hello"
+claude --print "hello"
+```
+This establishes a session baseline. Without priming, brand-new accounts occasionally see billing classification issues on first use.
+
+**I'm hitting rate limits on the Claude backend. What do I do?**
+Claude subscriptions have rolling 5-hour and 7-day usage windows. Check utilization with Claude Code's `/usage` command or the [statusline](https://code.claude.com/docs/en/statusline). For multi-agent workloads, add more accounts and let pool mode distribute the load: `dario accounts add <alias>`. Session stickiness keeps long conversations pinned to one account so the prompt cache isn't destroyed by rotation.
+
+**I'm seeing `representative-claim: seven_day` in my rate-limit headers instead of `five_hour`. Am I being downgraded to API billing?**
+
+**No.** You're still on subscription billing. Both `five_hour` and `seven_day` are the same subscription billing mode — two different accounting buckets inside it.
+
+| Claim | What it means |
+|---|---|
+| `five_hour` | You're well inside your 5-hour window; billing against the short-term bucket. |
+| `seven_day` | You've exhausted (or come close to exhausting) the 5-hour window for this rolling cycle, so Anthropic is charging this request against the 7-day bucket. **Still subscription billing. Still your plan.** Not API pricing, not overage. |
+| `overage` | Both subscription windows are effectively exhausted. *This* is where per-token Extra Usage charges kick in — if you've enabled Extra Usage on the account. If not, you get 429'd instead. |
+
+Seeing `seven_day` is a healthy state. Your Max plan is doing exactly what it's supposed to do: letting you keep working past short bursts of heavy use by absorbing them into the larger 7-day bucket. When your 5-hour window rolls forward enough, the claim on new requests will go back to `five_hour` on its own. If the 7-day bucket is painful, add more Claude subscriptions to the pool — each account has its own independent 5h/7d windows, and pool mode routes each request to the account with the most headroom.
+
+Standalone writeup: [Discussion #1 — full rate-limit-header breakdown](https://github.com/askalf/dario/discussions/1).
+
+**My multi-agent workload is getting reclassified to overage even though dario mirrors the CC wire shape per request. Why?**
+Reclassification at high agent volume is not a per-request problem. The upstream billing logic takes cumulative per-OAuth-session aggregates into account — token throughput, conversation depth, streaming duration, inter-arrival timing, thinking-block volume. Dario's Claude backend can make each individual request match 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 signal along any single dimension. See [Multi-account pool mode](./multi-account-pool.md). The v3.22 – v3.28 wire-fidelity track (pacing, stream-drain, session-id lifecycle) also narrows the cumulative signal on a single account — see [Wire-fidelity axes](./wire-fidelity.md).
+
+**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. The upstream service can see the hash. Whether any routing decisions depend on it today is not published; 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 ClientHello is just the one observable axis left.
+
+**Why "dario"?**
+It's a name, not an acronym. Don't overthink it.