@askalf/dario 5.5.39 → 5.5.41

package/README.md

@@ -207,6 +207,7 @@ The split isn't live, but it was announced once on short notice and could return
 - **Multi-account pool.** Several Claude seats behind one endpoint, routed by per-model headroom with sticky-session cache locality and in-flight 429 failover. → [Multi-account pool](#multi-account-pool)
 - **Byte-faithful passthrough for real Claude Code.** A genuine CC request already *is* the CC shape, so dario forwards it verbatim — system prompt, tools, thinking, key order untouched — keeping only its billing tag, identity, and cache breakpoints. Covers CC's whole family: the main loop, its Task/Agent sub-agents, and the permission classifier. Non-CC clients get the full template rebuild that keeps them routing. Background: [#678](https://github.com/askalf/dario/issues/678).
 - **Headless admin API (`DARIO_ADMIN=1`).** Provision and manage pool accounts entirely over HTTP — start with zero accounts, `POST /admin/login/start`, paste the code back, routable the moment the `200` lands (live hot-reload, no restart). Token-gated even on loopback, audit-logged, rate-limited. Built for Docker / k8s / Pi. → [`docs/admin-api.md`](./docs/admin-api.md)
+- **More than one instance, same accounts.** Anthropic's refresh tokens are single-use, so two replicas refreshing the same account leaves one holding a dead token. An optional refresh lock (Redis or Cloudflare backend, same contract, fails open) makes the loser adopt the winner's fresh credentials instead. Safe credential sharing — *not* full HA: rate-limit accounting and sticky routing stay per-instance. → [`docs/multi-instance.md`](./docs/multi-instance.md)
 - **Runs any agent.** A 64-entry schema-verified `TOOL_MAP` pre-maps Cline, Roo, Kilo, Cursor, Windsurf, Continue, Copilot, OpenHands, OpenClaw, Hermes, and [hands](https://github.com/askalf/hands) tool names to CC's native set — no flag, no validator errors. MCP tools (`mcp__server__tool`) forward verbatim. [Compatibility matrix](./docs/integrations/compat-matrix.md) · [agent-compat.md](./docs/integrations/agent-compat.md).
 - **Behavioral stealth (`--stealth`).** Adds *when* a request arrives to *what* it looks like — response-length-correlated think time and session-start latency. → [`docs/wire-fidelity.md`](./docs/wire-fidelity.md)
 - **VPN / egress routing.** Route dario's upstream traffic through a VPN without putting the whole host on one. → [`docs/vpn-routing.md`](./docs/vpn-routing.md)

package/dist/live-fingerprint.d.ts

@@ -456,7 +456,7 @@ export declare function detectDrift(t: TemplateData, installedOverride?: string
  */
 export declare const SUPPORTED_CC_RANGE: {
     readonly min: "1.0.0";
-    readonly maxTested: "2.1.237";
+    readonly maxTested: "2.1.238";
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/live-fingerprint.js

@@ -1145,7 +1145,7 @@ export function detectDrift(t, installedOverride) {
  */
 export const SUPPORTED_CC_RANGE = {
     min: '1.0.0',
-    maxTested: '2.1.237',
+    maxTested: '2.1.238',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/docs/multi-instance.md

@@ -0,0 +1,120 @@
+# Running more than one dario against the same accounts
+
+Short answer: **you can share credentials safely between instances, but dario is not HA.** Those are different claims, and the difference matters before you scale a Deployment to 2.
+
+This page covers what actually breaks with two instances, which part is solved, how to turn the fix on, and how to prove it works on your own infrastructure.
+
+Raised in [#993](https://github.com/askalf/dario/issues/993).
+
+---
+
+## What breaks with two instances
+
+Three things, and they fail differently.
+
+### 1. The OAuth refresh race — **solved**
+
+Anthropic's refresh tokens are **single-use**. Refreshing returns a new access token *and* a new refresh token, and invalidates the old one.
+
+Two instances holding the same account both notice the token is near expiry, and both refresh. One wins. The loser's refresh token is now dead, and it has no way to know — so that instance is locked out of the account until someone runs `dario login` again. On a shared NAS or a k8s volume this is not a rare race; it is the normal outcome of two pods with synchronized clocks and the same 45-minute refresh margin.
+
+A plain mutex does not fix this. The loser waits, acquires the lock, and then refreshes with a token that is *already* stale — it just loses more slowly. The fix is that the loser **adopts the winner's fresh credentials** instead of attempting its own. That is what dario's refresh lock does.
+
+### 2. Rate-limit accounting — **not solved**
+
+`pool.ts` keeps `accounts: Map<string, PoolAccount>` in process memory, and updates it only from rate-limit headers on responses *that instance* saw.
+
+Two instances sharing an account each believe it has full headroom. Both route to it. Neither can see what the other is spending, so the pool overshoots the real 5-hour and 7-day windows and starts getting rejections it did not predict. Adding instances makes this worse, not better.
+
+### 3. Session stickiness — **not solved**
+
+`computeStickyKey()` hashes the first user message and pins that conversation to one account, so its prompt cache stays warm. The binding lives in process memory.
+
+With two instances behind one Service, the same conversation can land on either, and get a different account each time. The prefix is re-cached per account, so you pay cache writes instead of reads. See [`docs/multi-account-pool.md`](./multi-account-pool.md) for why that costs real money.
+
+---
+
+## So what should you actually run?
+
+| you want | do this |
+|---|---|
+| Zero-downtime restarts / rolling deploys | Two instances **with the refresh lock**. Brief overlap is fine; the credential race is the only thing that corrupts state, and the lock covers it. |
+| More throughput from more accounts | **One instance, more accounts in the pool.** The pool is the horizontal-scaling mechanism; a second instance is not. |
+| Survive a node failure | Two instances with the lock, and accept that rate-limit accounting is approximate while both are live. |
+| Precise rate-limit accounting | One instance. There is no shared-state mode today. |
+
+dario starts in well under a second, so for most people a single replica with a sensible `restartPolicy` is the honest answer — which is roughly where [#993](https://github.com/askalf/dario/issues/993) landed too.
+
+---
+
+## Turning the refresh lock on
+
+Two reference backends implement the identical contract. `src/accounts.ts` knows only the two environment variables — it has no idea which one is answering.
+
+```
+DARIO_REFRESH_LOCK_URL=http://<lock-host>:8080
+DARIO_REFRESH_LOCK_TOKEN=<shared secret>
+```
+
+Set both on **every** instance. Unset `DARIO_REFRESH_LOCK_URL` and the code path is byte-identical to not having the feature at all.
+
+### Redis backend — no external dependency
+
+Use this if you are airgapped, or do not want dario's availability to depend on a third party.
+
+```
+cd redis-lock
+docker build -t dario-refresh-lock .
+docker run -d -p 8080:8080 \
+  -e LOCK_TOKEN=<a real random value, not reused from another service> \
+  -e REDIS_HOST=<your redis host> \
+  -e REDIS_PORT=6379 \
+  dario-refresh-lock
+```
+
+Zero new runtime dependencies — the RESP2 client is hand-rolled over `node:net` rather than pulling in `redis`/`ioredis`, so dario's zero-dependency invariant is intact. Details in [`redis-lock/README.md`](../redis-lock/README.md).
+
+**Be clear about what this is:** a single Redis instance holding lock and credential-handoff state. It is a coordination point, not a consensus system. If Redis is down, the lock fails open (below). It does not do leader election, and it is not Raft — if you need split-brain guarantees, this is not that.
+
+### Cloudflare backend — nothing to host
+
+A Durable Object gives you serialized access without running anything yourself. See [`cloudflare/refresh-lock/README.md`](../cloudflare/refresh-lock/README.md).
+
+Not suitable for airgapped deployments, and it adds an internet dependency to a component that otherwise only talks to Anthropic.
+
+### It fails open, deliberately
+
+Any lock-service error — bad response, network failure, timeout — and dario proceeds with its own refresh exactly as if no lock were configured.
+
+The lock is resilience layered on top of dario's job, not a new dependency dario's core function needs. An outage of your Redis must not stop your proxy serving traffic. The cost of that choice is that during a lock outage you are back to the plain race, so do not treat the lock as a hard guarantee.
+
+---
+
+## Proving it works on your own setup
+
+Do not take the above on trust. `test/integration/dual-instance-race.mjs` runs the real scenario: **two genuinely separate `node` processes**, each with its own isolated `~/.dario`, sharing nothing but the lock service, both racing to refresh the same account at the same instant.
+
+```
+npm run test:refresh-lock-race
+```
+
+Point it at your own lock service by setting `DARIO_REFRESH_LOCK_URL` / `DARIO_REFRESH_LOCK_TOKEN` first.
+
+**Run it both ways.** The flag is the useful part:
+
+```
+node test/integration/dual-instance-race.mjs --no-lock   # reproduce the failure
+node test/integration/dual-instance-race.mjs             # show it prevented
+```
+
+Without the lock you should watch one instance end up holding a dead refresh token. With it, the loser adopts the winner's credentials and both keep working. Seeing the failure first is what makes the fix mean something.
+
+Anthropic's token endpoint is the one mocked part, and only that — hammering the real endpoint with production credentials for adversarial testing risks burning your actual refresh token. The lock calls, the two processes, the isolated homes and the race itself are all real.
+
+---
+
+## If you need true HA
+
+There is no shared-state mode today, and building one is a larger change than a lock: rate-limit snapshots and sticky bindings would both have to move out of process memory, which means every routing decision takes a network hop.
+
+If you want that, say so on [#993](https://github.com/askalf/dario/issues/993) with your deployment shape. Concrete requirements are considerably more useful than a general "make it HA" — the design depends heavily on whether you need precise accounting or merely approximate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "5.5.39",
+  "version": "5.5.41",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {