@askalf/dario 4.1.1 → 4.2.0

package/README.md

@@ -172,15 +172,24 @@ The moment any upstream response carries `representative-claim: overage`, dario
 }
 ```
 
-The TUI's Status tab pins the loud version:
+The state surfaces in four TUI tabs simultaneously — each answers a different question a user has when their bill suddenly starts moving:
+
+| Tab | Question it answers | What it renders |
+|---|---|---|
+| **Status** | What's happening RIGHT NOW? | `⚠ HALTED` banner with triggering request, cause, live countdown to auto-resume, manual-resume hint |
+| **Hits** | Which specific request triggered it? | Pinned banner across the top + red `!` marker + red row on the triggering request in the live buffer + 503-status row for any blocked-while-halted requests |
+| **Analytics** | How often is this happening across my traffic? | New "Overage" bar in the rate-limit cluster, alongside 5h/7d — red the moment count is non-zero |
+| **Config** | How do I tune this? | Four in-place-editable fields: `overageGuard.enabled`, `.behavior` (enum-validated halt/warn), `.cooldownMs`, `.notifyOs` |
+
+Status and Hits during an active halt:
 
 ```
-┌─ dario v4 ──────────────────────────[ q quit · Tab next · ? help ]──┐
+┌─ dario v4.1 ────────────────────────[ q quit · Tab next · ? help ]──┐
 │  ▎Status▎  Config   Analytics   Hits   Accounts   Backends         │
 ├─────────────────────────────────────────────────────────────────────┤
 │  Overage-guard                                                      │
 │  ⚠ HALTED   overage detected 12s ago                                │
-│    Request:        claude-opus-4-7  account=default                 │
+│    Request:        claude-opus-4-7  account=work                    │
 │    Cause:          representative-claim = overage                   │
 │    Auto-resume in  29m 48s                                          │
 │    Manual resume   press R here, or `dario resume` from any shell   │
@@ -189,10 +198,61 @@ The TUI's Status tab pins the loud version:
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
+```
+┌─ dario v4.1 ────────────────────────[ q quit · Tab next · ? help ]──┐
+│  Status   Config   Analytics   ▎Hits▎   Accounts   Backends         │
+├─────────────────────────────────────────────────────────────────────┤
+│  Hits   248 buffered · live                                         │
+│                                                                     │
+│   ⚠ HALTED  overage detected at 15:54:28 on opus-4-7 acct=work      │
+│   → New /v1/messages return 503 until R here, or `dario resume`     │
+│                                                                     │
+│     time      model           in     out    lat     st              │
+│   ▎15:54:31  opus-4-7        2.1k   —     —      503                │
+│     15:54:29  haiku-4-5      120    24    0.3s   200                │
+│   ! 15:54:28  opus-4-7       1.4k   216   1.2s   200    ◀ red row   │
+│     15:54:25  sonnet-4-6     1.2k   480   0.8s   200                │
+│     15:54:20  opus-4-7       842    216   1.2s   200                │
+│   ──────────────────────────────────────────────────────────────    │
+│   Selected: 15:54:31  req_011Cb52VKMBsB6z6w28NvMn                   │
+│     Account:         work                                           │
+│     Model:           claude-opus-4-7                                │
+│     Billing bucket:  (halted before upstream — no claim)            │
+│     Status:          503  dario_overage_guard                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Analytics — the burn-rate view, with the new Overage bar at the bottom of the rate-limit cluster (here showing one overage hit out of 248 — which is enough to halt by default):
+
+```
+┌─ dario v4.1 ────────────────────────[ q quit · Tab next · ? help ]──┐
+│  Status   Config   ▎Analytics▎   Hits   Accounts   Backends         │
+├─────────────────────────────────────────────────────────────────────┤
+│  Analytics — last 60 min                                            │
+│                                                                     │
+│   Requests:        248  (4.1/min)                                   │
+│   Tokens in:       142,830                                          │
+│   Tokens out:       38,200                                          │
+│   Subscription %:    99%                                            │
+│                                                                     │
+│  Rate-limit                                                         │
+│   5h       ████░░░░░░░░░░░░░░░░░░░░░░░░  18%                        │
+│   7d       ██░░░░░░░░░░░░░░░░░░░░░░░░░░   8%                        │
+│   Overage  █░░░░░░░░░░░░░░░░░░░░░░░░░░░   1 req of 248              │
+│            ⮤ red — the moment count is non-zero                     │
+│                                                                     │
+│  Billing                                                            │
+│   subscription           247 req                                    │
+│   extra_usage              1 req                                    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
 Why "halt at hit #1" is the right default: subscribers should never see a single overage response during normal operation. One means something is wrong — wire-shape drift, classifier change, account misconfig — and continuing to forward requests in the same shape bleeds real money for accounts with extra-usage enabled, or returns wall-of-rejections for accounts without it. The first hit is the signal; the second through hundredth are damage.
 
 **Resume paths** — `dario resume` from any shell, `R` on the TUI Status tab, or the cooldown timer (default 30 min). **Configuration** — `~/.dario/config.json` → `overageGuard`, or CLI flags (`--overage-behavior=warn` for visibility-only, `--no-overage-guard` to disable, `--overage-cooldown=<ms>` to tune). **OS notification** — best-effort native toast (osascript / notify-send / BurntToast) plus terminal BEL as the unconditional floor. See [#288](https://github.com/askalf/dario/issues/288).
 
+**Verified end-to-end live.** [`test/overage-guard-e2e-live.mjs`](./test/overage-guard-e2e-live.mjs) patches `globalThis.fetch` to mock the upstream, starts a real dario proxy in-process, and drives the five-stage halt cycle through real HTTP: subscription request flows → upstream returns overage → guard halts → next request returns 503 with the `dario_overage_guard` body → `POST /admin/resume` clears state → requests flow again. 20/20 assertions, 3 upstream calls intercepted (the halted request short-circuited at the request handler, never touched the upstream). Run with `node test/overage-guard-e2e-live.mjs`.
+
 ---
 
 ## Does it actually work?
@@ -276,7 +336,7 @@ The tool doesn't know. The backend doesn't know. Dario is the seam.
 - **Multi-account pool.** Drop 2+ Claude accounts in `~/.dario/accounts/` and pool mode auto-activates: every request routes to the account with the most headroom, multi-turn sessions pin to one account so the prompt cache survives, in-flight 429s fail over to a peer before your client sees an error. `dario accounts add work` / `dario accounts add personal`. → [`docs/multi-account-pool.md`](./docs/multi-account-pool.md)
 - **Behavioral stealth (`--stealth`).** Static wire fidelity covers *what* the request looks like; `--stealth` adds *when* it arrives — response-length-correlated think time and 1.2–4.2s session-start latency, the inter-arrival pattern real interactive sessions have and agent loops don't. → [`docs/wire-fidelity.md`](./docs/wire-fidelity.md)
 - **Runs any non-Claude-Code agent.** A 64-entry schema-verified `TOOL_MAP` pre-maps Cline, Roo, Kilo, Cursor, Windsurf, Continue, Copilot, OpenHands, OpenClaw, Hermes, [hands](https://github.com/askalf/hands) tool names to CC's native set. No flag, no validator errors. → [`docs/agent-compat.md`](./docs/agent-compat.md)
-- **Shim mode.** Take the proxy off the wire entirely — `dario shim -- claude --print "hi"` patches `globalThis.fetch` in-process. No HTTP hop, no port, no `BASE_URL`. → [`docs/shim.md`](./docs/shim.md)
+- **Shim mode** *(deprecated in v4.2; removal scheduled for v5.x)*. The original "no HTTP hop" path that patched `globalThis.fetch` inside a `dario shim -- <cmd>` child process. Empirically only matches 3 of the 8 wire-shape axes the billing classifier inspects (system blocks, agent identity, header order) and falls back to total passthrough when the client sends a 1-block system — which `claude -p` and Agent-SDK both do. Use **proxy mode** for any non-CC client; that's the only mode that rebuilds every request to CC's full canonical shape. Shim emits a deprecation banner on every invocation. See [CHANGELOG v4.2.0](./CHANGELOG.md) for the side-by-side fingerprint diff that drove this call.
 - **Recover output capability.** `dario proxy --system-prompt=partial` strips CC's tone/verbosity/no-comments constraints for 1.2–2.8× more output on open-ended work — empirically without flipping billing (the classifier doesn't read that slot). [Discussion #183](https://github.com/askalf/dario/discussions/183) has the per-prompt receipts. → [`docs/system-prompt.md`](./docs/system-prompt.md)
 - **Reachable from inside CC / any MCP client.** `dario subagent install` registers a CC sub-agent for in-session diagnostics; `dario mcp` exposes dario as a read-only MCP server. → [`docs/sub-agent.md`](./docs/sub-agent.md) · [`docs/mcp-server.md`](./docs/mcp-server.md)
 - **Active overage protection (v4.1).** Halts the proxy on any `representative-claim: overage` response and returns 503 to subsequent requests until you run `dario resume` or the cooldown clears. Visibility-only mode (`--overage-behavior=warn`) for operators who want the signal without disrupting traffic. Halt state visible in TUI Status/Hits/Analytics tabs, surfaced as named SSE events, and as a best-effort native desktop notification. [#288](https://github.com/askalf/dario/issues/288).

package/dist/cli.js

@@ -1053,8 +1053,13 @@ async function help() {
     dario backend add NAME --key=sk-... [--base-url=...]
                              Add an OpenAI-compat backend (OpenAI, OpenRouter, Groq, etc.)
     dario backend remove N   Remove an OpenAI-compat backend
-    dario shim -- CMD ARGS   Run CMD inside the dario shim (experimental,
-                             stealth fingerprint via in-process fetch patch)
+    dario shim -- CMD ARGS   [DEPRECATED — removal scheduled for v5.x]
+                             Run CMD with dario's fetch-patch in-process.
+                             Only replaces 3 of 8 billing-classifier axes
+                             (system blocks, agent identity, header order).
+                             Falls back to passthrough on 1-block system
+                             requests (\`claude -p\`, Agent SDK). Use proxy
+                             mode for non-CC clients. See CHANGELOG v4.2.0.
     dario subagent install   Register ~/.claude/agents/dario.md so Claude Code
                              can delegate dario diagnostics / template-refresh
                              operations to a named sub-agent (v3.26)
@@ -1435,6 +1440,50 @@ async function shim() {
         console.error('         dario shim --priority=below-normal -- claude   (recommended on Windows when RDP\'d into the host)');
         process.exit(1);
     }
+    // v4.2.0+: shim mode is DEPRECATED — set for removal in v5.x.
+    //
+    // The empirical reason (verified by side-by-side fingerprint diff of
+    // shim's `_rewriteBody` against the proxy's `buildCCRequest` — see
+    // CHANGELOG v4.2.0 entry): shim mode only replaces 3 of the 8 axes
+    // Anthropic's billing classifier actually inspects (system blocks,
+    // agent identity, header order). It leaves the client's JSON key
+    // order, max_tokens value, metadata billing tag, and any non-CC
+    // fields (temperature, top_p, service_tier) unchanged on the wire.
+    // And on the most-common claude -p / Agent-SDK request shape (which
+    // sends a 1-block system, not the 3-block shape shim's shape-check
+    // hardcodes), shim silently falls back to total passthrough — sending
+    // the client's raw body to api.anthropic.com with zero replay.
+    //
+    // For interactive CC (`dario shim -- claude`), this is mostly a no-op
+    // because CC's own outbound already matches every axis dario would
+    // synthesize. But for any non-CC client (`dario shim -- aider`,
+    // `dario shim -- cline`, your own scripts), shim mode does not deliver
+    // the wire fidelity the README claims.
+    //
+    // We warn loudly here instead of silently breaking, and point users
+    // at proxy mode. Set DARIO_SHIM_NO_DEPRECATION_WARNING=1 to suppress
+    // the banner for scripts that need the exit-code semantics but have
+    // already migrated their understanding.
+    if (process.env['DARIO_SHIM_NO_DEPRECATION_WARNING'] !== '1') {
+        console.error('');
+        console.error('[dario] ⚠ DEPRECATION: `dario shim` is deprecated in v4.2 and scheduled for removal in v5.x.');
+        console.error('[dario]');
+        console.error('[dario] Shim mode only matches a subset of the wire-shape axes Anthropic\'s billing classifier');
+        console.error('[dario] inspects. Specifically, it does not normalize JSON key order, max_tokens, metadata');
+        console.error('[dario] billing-tag, or non-CC body fields. On `claude -p` / Agent-SDK style requests (1-block');
+        console.error('[dario] system), shim falls back to total passthrough — the client\'s raw body reaches the');
+        console.error('[dario] upstream unchanged.');
+        console.error('[dario]');
+        console.error('[dario] Use proxy mode instead, which rebuilds every request to CC\'s exact wire shape:');
+        console.error('[dario]');
+        console.error('[dario]   Terminal 1:  dario proxy');
+        console.error('[dario]   Terminal 2:  ANTHROPIC_BASE_URL=http://localhost:3456 \\');
+        console.error('[dario]                ANTHROPIC_API_KEY=dario \\');
+        console.error('[dario]                ' + childArgs.join(' '));
+        console.error('[dario]');
+        console.error('[dario] To suppress this banner: DARIO_SHIM_NO_DEPRECATION_WARNING=1');
+        console.error('');
+    }
     const { runShim } = await import('./shim/host.js');
     try {
         const result = await runShim({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "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": {