@askalf/dario 6.15.0 → 6.17.0

package/dist/relaunch-signals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Signal hand-off for the Bun relaunch.
+ *
+ * Under Node, the CLI relaunches itself under Bun as a child and parks (cli.ts). The
+ * child owns the proxy and its graceful shutdown (drain, ledger and key flush), but a
+ * SIGTERM sent to the wrapper never reached it. In a container the wrapper is PID 1,
+ * and the kernel drops a signal PID 1 has no handler for, so `docker stop` waited out
+ * its whole grace period and then SIGKILLed both processes: every recreate took the
+ * full stop timeout and the shutdown flush never ran.
+ *
+ * `forwardSignals` passes SIGTERM and SIGINT on to the child, and `relaunchExitCode`
+ * turns the child's exit into the wrapper's. Both take their process and child as
+ * arguments, so they are tested without spawning anything.
+ */
+/** The signals the wrapper passes on. Each one starts the child's graceful shutdown. */
+export declare const FORWARDED_SIGNALS: readonly ["SIGTERM", "SIGINT"];
+export interface RelaunchChild {
+    kill(signal: NodeJS.Signals): boolean;
+    readonly exitCode: number | null;
+    readonly signalCode: NodeJS.Signals | null;
+}
+export interface SignalSource {
+    on(event: NodeJS.Signals, listener: () => void): unknown;
+}
+/**
+ * Pass each forwarded signal on to the child while it is still running. Once the
+ * wrapper has a handler it no longer exits on the signal itself: it exits when the
+ * child does, through the child's exit listener.
+ */
+export declare function forwardSignals(child: RelaunchChild, source?: SignalSource): void;
+/**
+ * The wrapper's exit code for how the child ended: its own code, or 128 plus the
+ * signal number when a signal killed it, the way a shell reports it.
+ */
+export declare function relaunchExitCode(code: number | null, signal: NodeJS.Signals | null): number;

package/dist/relaunch-signals.js

@@ -0,0 +1,41 @@
+/**
+ * Signal hand-off for the Bun relaunch.
+ *
+ * Under Node, the CLI relaunches itself under Bun as a child and parks (cli.ts). The
+ * child owns the proxy and its graceful shutdown (drain, ledger and key flush), but a
+ * SIGTERM sent to the wrapper never reached it. In a container the wrapper is PID 1,
+ * and the kernel drops a signal PID 1 has no handler for, so `docker stop` waited out
+ * its whole grace period and then SIGKILLed both processes: every recreate took the
+ * full stop timeout and the shutdown flush never ran.
+ *
+ * `forwardSignals` passes SIGTERM and SIGINT on to the child, and `relaunchExitCode`
+ * turns the child's exit into the wrapper's. Both take their process and child as
+ * arguments, so they are tested without spawning anything.
+ */
+import { constants } from 'node:os';
+/** The signals the wrapper passes on. Each one starts the child's graceful shutdown. */
+export const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT'];
+/**
+ * Pass each forwarded signal on to the child while it is still running. Once the
+ * wrapper has a handler it no longer exits on the signal itself: it exits when the
+ * child does, through the child's exit listener.
+ */
+export function forwardSignals(child, source = process) {
+    for (const signal of FORWARDED_SIGNALS) {
+        source.on(signal, () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill(signal);
+        });
+    }
+}
+/**
+ * The wrapper's exit code for how the child ended: its own code, or 128 plus the
+ * signal number when a signal killed it, the way a shell reports it.
+ */
+export function relaunchExitCode(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal !== null)
+        return 128 + (constants.signals[signal] ?? 0);
+    return 0;
+}

package/dist/stream-drain.d.ts

@@ -15,8 +15,8 @@
  * `--drain-on-close` / `DARIO_DRAIN_ON_CLOSE=1` flips the tradeoff: when
  * the downstream client disconnects, dario suppresses the upstream abort
  * and keeps the reader loop spinning until the upstream emits its final
- * event (or `UPSTREAM_TIMEOUT_MS` fires as a hard ceiling — we don't
- * linger on dead upstreams). Writes to the closed `res` are gated off;
+ * event, or until the upstream timeout ends a stream that has gone quiet
+ * (a dead upstream is not waited on). Writes to the closed `res` are gated off;
  * the reads and any accumulator state (analytics, tool-map) continue so
  * the captured usage numbers are complete rather than truncated.
  *
@@ -48,7 +48,8 @@ export type ClientCloseAction = 'abort' | 'drain' | 'noop';
  *   `'noop'`  — already finished / already aborted; handler should return.
  *   `'abort'` — fire `upstreamAbort.abort()` (the v3.24-and-earlier default).
  *   `'drain'` — leave upstream alive; gate off client writes; let the
- *               read loop consume to EOF (bounded by UPSTREAM_TIMEOUT_MS).
+ *               read loop consume to EOF (until the stream goes quiet
+ *               for UPSTREAM_TIMEOUT_MS).
  */
 export declare function decideOnClientClose(writableEnded: boolean, upstreamAborted: boolean, drainOnClose: boolean): ClientCloseAction;
 /**

package/dist/stream-drain.js

@@ -15,8 +15,8 @@
  * `--drain-on-close` / `DARIO_DRAIN_ON_CLOSE=1` flips the tradeoff: when
  * the downstream client disconnects, dario suppresses the upstream abort
  * and keeps the reader loop spinning until the upstream emits its final
- * event (or `UPSTREAM_TIMEOUT_MS` fires as a hard ceiling — we don't
- * linger on dead upstreams). Writes to the closed `res` are gated off;
+ * event, or until the upstream timeout ends a stream that has gone quiet
+ * (a dead upstream is not waited on). Writes to the closed `res` are gated off;
  * the reads and any accumulator state (analytics, tool-map) continue so
  * the captured usage numbers are complete rather than truncated.
  *
@@ -47,7 +47,8 @@
  *   `'noop'`  — already finished / already aborted; handler should return.
  *   `'abort'` — fire `upstreamAbort.abort()` (the v3.24-and-earlier default).
  *   `'drain'` — leave upstream alive; gate off client writes; let the
- *               read loop consume to EOF (bounded by UPSTREAM_TIMEOUT_MS).
+ *               read loop consume to EOF (until the stream goes quiet
+ *               for UPSTREAM_TIMEOUT_MS).
  */
 export function decideOnClientClose(writableEnded, upstreamAborted, drainOnClose) {
     if (writableEnded || upstreamAborted)

package/dist/tui/tabs/config.js

@@ -38,7 +38,7 @@ const FIELDS = [
     { path: 'thinkTime.maxMs', label: 'Think-time cap (ms)', type: 'number', hint: 'upper bound for the whole formula' },
     { path: 'sessionStart.minMs', label: 'Session-start min', type: 'number', hint: 'first-request delay floor' },
     { path: 'sessionStart.jitterMs', label: 'Session-start jitter', type: 'number' },
-    { path: 'pool.strategy', label: 'Pool strategy', type: 'string', hint: '"headroom" (default), "expiring-first" or "fill-first"' },
+    { path: 'pool.strategy', label: 'Pool strategy', type: 'string', hint: '"headroom" (default), "headroom-by-plan", "expiring-first" or "fill-first"' },
     // ── Overage-guard (v4.1, dario#288) ─────────────────────────
     { path: 'overageGuard.enabled', label: 'Overage-guard', type: 'bool', hint: 'halt proxy on any representative-claim=overage' },
     { path: 'overageGuard.behavior', label: 'Overage behavior', type: 'string', hint: '"halt" (default) or "warn"' },
@@ -271,7 +271,7 @@ function commitEdit(state) {
  */
 const STRING_ENUMS = {
     'overageGuard.behavior': ['halt', 'warn'],
-    'pool.strategy': ['headroom', 'fill-first', 'expiring-first'],
+    'pool.strategy': ['headroom', 'headroom-by-plan', 'fill-first', 'expiring-first'],
 };
 function doSave(state) {
     try {

package/dist/upstream-deadline.d.ts

@@ -0,0 +1,25 @@
+/** Injectable clock and timers; tests drive them by hand. */
+export interface DeadlineTimers {
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+    /** A monotonic ms clock: a wall-clock jump must not end a live stream. */
+    now: () => number;
+}
+export interface UpstreamDeadline {
+    /**
+     * The response is a 2xx and its body is about to be read: from here `ms`
+     * is an idle gap, counted from now. Only the first call has an effect.
+     */
+    streaming(): void;
+    /** A chunk arrived from upstream. Resets the idle gap; ignored before `streaming()`. */
+    touch(): void;
+    /** Disarm for good, without calling `onTimeout`. Safe to call more than once. */
+    clear(): void;
+    /** True once `onTimeout` has run. */
+    readonly fired: boolean;
+}
+/**
+ * Arms the headers phase at once. `ms` goes through clampTimerMs, so a value
+ * past Node's timer ceiling waits as long as a timer can, not 1 ms.
+ */
+export declare function upstreamDeadline(ms: number, onTimeout: () => void, timers?: DeadlineTimers): UpstreamDeadline;

package/dist/upstream-deadline.js

@@ -0,0 +1,76 @@
+/**
+ * The upstream timeout, in two phases.
+ *
+ * Until the response starts streaming, `ms` caps the whole wait: connect,
+ * send, and the time to first byte (a retry inside the same request counts
+ * against the same budget). Once a 2xx body is being read, `ms` is the
+ * longest gap allowed between two chunks instead. A single timer armed for
+ * the whole request used to abort agent turns that were still streaming
+ * after five minutes (max_tokens is 64000), and the mid-stream guard then
+ * re-sent the full prompt to continue, or truncated an open tool_use block.
+ * A stream that stops sending still dies `ms` after its last chunk.
+ *
+ * `touch()` runs once per chunk, so it only records the time: the timer is
+ * re-armed for the remainder when it fires early, not on every chunk.
+ */
+import { clampTimerMs } from './timer-ms.js';
+const defaultTimers = {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h),
+    now: () => performance.now(),
+};
+/**
+ * Arms the headers phase at once. `ms` goes through clampTimerMs, so a value
+ * past Node's timer ceiling waits as long as a timer can, not 1 ms.
+ */
+export function upstreamDeadline(ms, onTimeout, timers = defaultTimers) {
+    const limit = clampTimerMs(ms);
+    let phase = 'headers';
+    let lastChunkAt = 0;
+    let handle = null;
+    let fired = false;
+    const disarm = () => {
+        if (handle !== null) {
+            timers.clearTimeout(handle);
+            handle = null;
+        }
+    };
+    const arm = (delay) => {
+        handle = timers.setTimeout(onFire, clampTimerMs(delay));
+    };
+    function onFire() {
+        handle = null;
+        if (phase === 'done')
+            return;
+        if (phase === 'idle') {
+            const idle = timers.now() - lastChunkAt;
+            if (idle < limit) {
+                arm(limit - idle);
+                return;
+            }
+        }
+        phase = 'done';
+        fired = true;
+        onTimeout();
+    }
+    arm(limit);
+    return {
+        streaming() {
+            if (phase !== 'headers')
+                return;
+            phase = 'idle';
+            lastChunkAt = timers.now();
+            disarm();
+            arm(limit);
+        },
+        touch() {
+            if (phase === 'idle')
+                lastChunkAt = timers.now();
+        },
+        clear() {
+            phase = 'done';
+            disarm();
+        },
+        get fired() { return fired; },
+    };
+}

package/docs/analytics.md

@@ -8,13 +8,13 @@ Every surface below is a view over those two. Nothing here collects anything new
 
 | path | what | format |
 |---|---|---|
-| `GET /analytics` | window summary + `queue` snapshot + `lifetime` ledger summary | JSON |
-| `GET /analytics/ledger` | the ledger's per-day table | JSON |
+| `GET /analytics` | window summary (with `window.perFiveMinutes`, the hour in twelve bins) + `queue` snapshot + `overage` (the halt state, for a reader who cannot open `/admin/resume`) + `lifetime` ledger summary | JSON |
+| `GET /analytics/ledger` | the ledger's per-day table, with `priced`: the same rows as USD at each day's rate | JSON |
 | `GET /analytics/stream` | live tail of request records (drives the TUI) | SSE |
 | `GET /metrics` | the same state as Prometheus text exposition | text/plain 0.0.4 |
 | `GET /analytics/donuts.svg` | spend by model / by key / by billing | SVG |
-| `GET /analytics/view` | server-rendered dashboard body | HTML fragment |
-| `GET /analytics/ui` | the dashboard shell (no data; asks for the token, loads `/view` every 60 s) | HTML page |
+| `GET /analytics/view` | the server-rendered summary (the page before 6.17; still served) | HTML fragment |
+| `GET /analytics/ui` | the dashboard (no data of its own; asks for the token, then reads the routes above, `/accounts`, `/codex` and `/health` with it and tails `/analytics/stream`) | HTML page |
 
 CLI: `dario usage` prints the ledger; `--json` dumps `/analytics`; `--card[=file]` writes the share card; `--donut[=file]` writes the three rings.
 
@@ -24,7 +24,7 @@ By default the proxy binds loopback and these paths need no credential. With `DA
 
 `--analytics-token=<secret>` (or `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on exactly the paths in the table above, on `GET` only. It is refused on `/v1/*`, `/accounts`, `/status`, `/admin/*`, and any non-GET. That is the point: a Grafana box or a browser tab can hold the numbers without holding request rights. The root key keeps working on the analytics paths too. On an unkeyed proxy the token gates nothing, and the proxy says so at startup.
 
-`/analytics/ui` itself is served without a credential because it contains no data. It stores the token you type in `sessionStorage` and sends it as a bearer on every fetch of `/analytics/view`.
+`/analytics/ui` itself is served without a credential because it contains no data. It stores the token you type in `sessionStorage` and sends it as a bearer on every read. With the analytics token it shows spend, routing, the live feed and the ledger; the seats panel needs an API key, because `/accounts` and `/codex` refuse the read-only token, and the keys panel needs the admin API (`DARIO_ADMIN=1`, the admin token). The page loads nothing from outside the proxy, follows the system theme (with a toggle), has a table view behind every chart, and opened from disk (`dist/analytics-ui.html`) it runs on sample data.
 
 ## `/metrics` families
 
@@ -35,19 +35,21 @@ Names ending in `_total` are counters; everything else is a gauge. Labels are es
 | `dario_info` | `version` | always 1 |
 | `dario_requests_total`, `dario_tokens_total{kind}`, `dario_estimated_cost_usd_total`, `dario_error_rate` | `kind` ∈ input, output, cache_read, cache_create, thinking | since start |
 | `dario_window_requests`, `_avg_latency_ms`, `_error_rate`, `_cached_prompt_percent`, `_estimated_cost_usd` | `window_minutes` | rolling window |
-| `dario_window_billing_requests` | `bucket` ∈ subscription, subscription_fallback, extra_usage, api, unknown | claims folded by `billingBucketFromClaim` |
+| `dario_window_billing_requests` | `bucket` ∈ subscription, subscription_fallback, extra_usage, api, credits, unknown | claims folded by `billingBucketFromClaim` |
 | `dario_account_requests_total`, `dario_account_estimated_cost_usd`, `dario_account_utilization{window}` | `account`, `window` ∈ 5h, 7d | last rate-limit headers per seat |
 | `dario_model_requests_total`, `dario_model_estimated_cost_usd` | `model` | since start |
 | `dario_consumer_requests_total`, `dario_consumer_estimated_cost_usd` | `consumer` (named key or `x-dario-consumer`) | since start |
-| `dario_queue_active`, `_queued`, `_max_concurrent`, `_max_queued`, `_stalled`, `_max_wait_ms`, `_consumers_active` | — | request queue |
+| `dario_queue_active`, `_queued`, `_max_concurrent`, `_max_queued`, `_stalled`, `_max_wait_ms`, `_consumers_active` | (none) | request queue |
 | `dario_request_latency_ms{quantile}` + `_sum`, `_count` | `quantile` ∈ 0.5, 0.9, 0.99 | nearest-rank over the most recent 1,000 records |
 | `dario_queue_wait_ms`, `dario_pacing_wait_ms`, `dario_upstream_ttfb_ms`, `dario_upstream_latency_ms`, `dario_overhead_ms` — each `{quantile}` + `_sum`, `_count` | `quantile` ∈ 0.5, 0.9, 0.99 | the timing split (below), nearest-rank over the recent records that carry one |
 | `dario_window_avg_upstream_ttfb_ms`, `_avg_upstream_latency_ms`, `_avg_overhead_ms`, `_avg_queue_wait_ms`, `_avg_pacing_wait_ms` | `window_minutes` | the split averaged over the rolling window; omitted until a request has carried one |
-| `dario_predicted_exhaustion_minutes` (omitted when unknown), `dario_burn_tokens_per_minute`, `dario_burn_cost_usd_per_minute` | — | window predictions |
+| `dario_predicted_exhaustion_minutes` (omitted when unknown), `dario_burn_tokens_per_minute`, `dario_burn_total_tokens_per_minute`, `dario_burn_cost_usd_per_minute` | (none) | window predictions |
 | `dario_ledger_requests_total`, `_api_equivalent_usd`, `_metered_usd`, `_recent_api_equivalent_usd{window}`, `_model_api_equivalent_usd{model,provider}`, `_model_requests_total{model,provider}`, `_consumer_api_equivalent_usd{consumer}` | `window` ∈ today, 7d, 30d | ledger (absent when the ledger is off) |
 
 `dario_request_latency_ms` is the number dario has always kept: dispatch to response end, as the client saw it. Since 6.9 every request also carries the split below, so the one figure can be read as its parts.
 
+The two token burn gauges differ in scope: `dario_burn_tokens_per_minute` is input and output only, cache reads and writes are not in it, while `dario_burn_total_tokens_per_minute` counts every kind. On a cached prompt the second is many times the first. `/analytics` carries the same pair as `predictions.tokenBurnRate` and `predictions.totalTokenBurnRate`.
+
 ## The timing split
 
 A request's wall-clock time through dario is five stamps (`src/timing.ts`), all in milliseconds, all on dario's clock:

package/docs/api-equivalent-spend.md

@@ -36,7 +36,10 @@ Two columns per row:
 - **metered** — billed per token anyway: an API key upstream (`api`) or
   Anthropic's paid overage (`overage` → `extra_usage`). That money was spent.
   It is reported on its own line ("Paid per token on top") and never counted
-  as saved.
+  as saved. The credits rung of the failover chain (`credits:<model>`) lands
+  in this column too: those credits were spent. The ledger keeps the two
+  columns only; the rolling window and the dashboard tell credits, API key
+  and extra usage apart.
 
 A mid-stream continuation (6.1) is two upstream requests and records as two
 rows, one per provider, each with the tokens that leg actually consumed.
@@ -124,7 +127,11 @@ by the anonymous traffic.
 ```
 
 `GET /analytics/ledger` is the file itself: `{ path, version, since, updated,
-days: { "YYYY-MM-DD": { "<model>": { covered: {…}, metered: {…} } } } }`.
+days: { "YYYY-MM-DD": { "<model>": { covered: {…}, metered: {…} } } } }`, plus
+`priced`, the same rows as money: `{ days: { "YYYY-MM-DD": { "<model>": {
+covered: 1.23, metered: 0.04 } } }, consumers: {…} }`, each bucket priced at
+that day's rate by the function the summary uses, so a reader charting the
+table (the dashboard, a script) needs no price list of its own.
 
 ## Pricing on the ChatGPT leg
 

package/docs/commands.md

@@ -53,7 +53,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--session-rotate-jitter=<ms>` / `DARIO_SESSION_JITTER_MS` | Jitter sampled once per session at creation — hides the exact idle floor. (v3.28) | `0` |
 | `--session-max-age=<ms>` / `DARIO_SESSION_MAX_AGE_MS` | Hard ceiling on a session-id's lifetime regardless of activity. (v3.28) | off |
 | `--session-per-client` / `DARIO_SESSION_PER_CLIENT=1` | Split session-id registry by a per-client header so multi-UI fan-out doesn't collapse onto one id. (v3.28) | off |
-| `--pool-strategy=<headroom\|fill-first\|expiring-first>` / `DARIO_POOL_STRATEGY` | Where new conversations land in a multi-account pool. `headroom` spreads them to the seat with the most slack; `fill-first` concentrates them on the alphabetically-first eligible seat until it drains to the floor, then spills to the next — primary/backup semantics, alias naming (`1-main`, `2-overflow`) picks the fill order; `expiring-first` does the same in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. Sticky bindings behave identically under all three. See [Multi-account pool](./multi-account-pool.md#routing-strategy). | `headroom` |
+| `--pool-strategy=<headroom\|headroom-by-plan\|fill-first\|expiring-first>` / `DARIO_POOL_STRATEGY` | Where new conversations land in a multi-account pool. `headroom` spreads them to the seat with the most slack; `fill-first` concentrates them on the alphabetically-first eligible seat until it drains to the floor, then spills to the next: primary/backup semantics, alias naming (`1-main`, `2-overflow`) picks the fill order; `expiring-first` does the same in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. `headroom-by-plan` (opt-in) is headroom with each seat's slack counted by plan size (Max Nx counts N, Pro 1). Sticky bindings behave identically under all of them. See [Multi-account pool](./multi-account-pool.md#routing-strategy). | `headroom` |
 | `--pool-fallback=<models>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), serve the request as `<model>` from whichever provider can, instead of surfacing the 429/503. Accepts a **chain** — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each provider taking the first entry it can serve. A Codex/ChatGPT subscription that lists the model is preferred (no per-token cost) and works on **both** wire shapes; otherwise a configured openai-compat backend, which is still OpenAI-path only (no Messages translation on that route). A chain also makes failover **symmetric**: a rate-limited or failing subscription hands the request back to the Claude pool. Only a 429/5xx fails over — a 400 surfaces, since a bad request would just reproduce itself elsewhere. Every substituted response carries `x-dario-pool-fallback: <model>` — never silent. Needs a Codex account (`dario add altman`) or a backend (`dario backend add …`); `dario doctor` reports it as INERT with neither. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
 | `--family-fallback=<family=model,...>` / `DARIO_FAMILY_FALLBACK` / config `familyFallback` | Strictly opt-in. When a rate limit keeps every pool seat off a model family, serve that family's requests as `<model>` on the Claude pool, while some seat can serve the target's family. Written for Fable: its included credit runs out while the seat still has room for Opus, so `fable=claude-opus-5-5` keeps Fable traffic on the subscription instead of a local 429 until the credit resets. The target must be a `claude-*` model of another family; one step, never chained. Runs before `--pool-fallback`, so a pool with room for the target never leaves the Claude pool. Skipped in upstream API-key mode, under `--model`/`--fast-model` and for a seat-pinned request. A `[1m]` tag on the request carries over. Every switched response carries `x-dario-family-fallback: <requested model>`. Empty flag value disables, overriding env + config. See [Family fallback](./multi-account-pool.md#family-fallback). | off |
 | `--system-prompt=<verbatim\|partial\|aggressive\|filepath>` / `DARIO_SYSTEM_PROMPT` | System-prompt mode for outbound CC-shaped requests. `partial` strips behavioral constraints (Tone-and-style, Text-output, scope/verbosity/comment bullets) for ~1.2–2.8× output capability on open-ended work. `aggressive` adds prompt-level RLHF restatement removal (<3% over partial — alignment is RLHF-trained). `<filepath>` fully replaces the slot with file contents. Empirically validated as unfingerprinted by the billing classifier — see [`system-prompt.md`](./system-prompt.md) and [`research/system-prompt-classifier-study.md`](./research/system-prompt-classifier-study.md). (v3.34) | `verbatim` |

package/docs/configuration.md

@@ -41,6 +41,7 @@ Halts the proxy when an upstream response reports `representative-claim: overage
 | `DARIO_MAX_CONCURRENT` | `--max-concurrent=N` | `10` | in-flight ceiling |
 | `DARIO_MAX_QUEUED` | `--max-queued=N` | `128` | buffered waiting for a slot; over this, dario returns 429 `queue-full` |
 | `DARIO_QUEUE_TIMEOUT_MS` | `--queue-timeout=MS` | `60000` | a queued request waiting longer gets 504 `queue-timeout` |
+| `DARIO_UPSTREAM_TIMEOUT_MS` | `--upstream-timeout=MS` | `300000` (5 min) | until the response streams, the whole wait for upstream (504 `upstream-timeout`); while a 2xx streams, the longest gap between two chunks, so a long answer that is still sending is never cut. `0` keeps the default |
 | `DARIO_MAX_CONCURRENT_PER_CONSUMER` | `--max-concurrent-per-consumer=N` | `0` (off) | in-flight ceiling per consumer, keyed by the `x-dario-consumer` request header; a consumer at the cap waits in the queue while everyone else keeps flowing. See [Consumers](./multi-account-pool.md#consumers-who-a-request-is-for) |
 
 ## Named keys

package/docs/faq.md

@@ -30,6 +30,11 @@ Two questions to verify at any time — and the exact check to run the day a rev
 
 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.
 
+**Max plans now include monthly API credits. Do I still need dario?**
+Since October 2026 a Max 5x plan includes $100 of Claude API credits a month and Max 20x includes $200 ([Monthly API credits for Max and Team plans](https://support.claude.com/en/articles/17154008)). They are spent through a Console API key on the Claude API and the Agent SDK, not in Claude Code, they expire at the end of each billing cycle, and when they are gone API requests stop. Your seat's own five-hour and weekly windows are a different bucket, and Anthropic's note on the change says third-party apps may still use them ([the October 7 update](https://support.claude.com/en/articles/15036540)). dario is how every tool draws on the seat first, so the credits are not the only thing between you and a meter. Run `dario usage` for a week: the API-equivalent figure is what your seat absorbed, and the comparison with $100 or $200 is yours to make.
+
+The credits can be the last rung of the failover chain. Put the Console key in `DARIO_CREDITS_API_KEY` and name the rung in the chain, `--pool-fallback=credits:claude-sonnet-5`: when every seat is parked, the request goes to the Claude API on that key as a plain API request, both wire shapes, the response says `x-dario-pool-fallback: credits:claude-sonnet-5`, `/analytics` and the dashboard show it under its own bucket, `credits`, and the ledger counts it as metered, so the receipt stays honest ([failover](./two-plans.md#failover-between-subscriptions)). A metered openai-compat backend can be a rung the same way, shown under API key. Neither is on until you name it.
+
 **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.
 

package/docs/multi-account-pool.md

@@ -33,6 +33,8 @@ Alias order is the operator's knob: name seats `1-main` / `2-overflow` to pick t
 
 `--pool-strategy=expiring-first` is fill-first ordered by **when each seat's capacity expires** instead of by alias: new conversations fill the seat whose 7-day window resets soonest (`anthropic-ratelimit-unified-7d-reset`) until it drains to the floor, then spill to the next-soonest; failover follows the same order. Subscription capacity is use-it-or-lose-it, so this is the order that gets the most of it used — the case it was built for is a seat that just got a limit reset, or joined the pool mid-week, sitting beside one whose window has days left. A seat with no 7-day reading yet, or whose window has already rolled, goes last; ties break by alias, so a pool with no readings behaves exactly like fill-first.
 
+`--pool-strategy=headroom-by-plan` is headroom with each seat's headroom counted by its plan size: a Max Nx seat counts N times (from the profile's `rate_limit_tier`), Pro and any plan dario cannot read count once. A Max 20x seat at 30% headroom then outranks a Pro at 90%. It is opt-in and never the default, because the ratios dario reads are account-wide (they include the owner's own use of the seat), no absolute capacity reaches the wire, and the window that binds matters more than the plan name: a smaller plan often has more real room. Use it when your seats are otherwise idle and you want the bigger plan to carry proportionally more. Floors, parking and sticky bindings work exactly as under `headroom`.
+
 ## Session stickiness
 
 Multi-turn agent sessions pin to one account for the life of the conversation, so the Anthropic prompt cache isn't destroyed by account rotation between turns.
@@ -202,7 +204,7 @@ Where it shows: `GET /analytics` gains `perConsumer` (requests, tokens, cache sh
 
 **Fairness.** `--max-concurrent-per-consumer=N` (`DARIO_MAX_CONCURRENT_PER_CONSUMER`) caps in-flight requests per named consumer. A consumer at the cap waits in the queue while slots are free for everyone else; when a slot frees, the first waiter whose consumer is under its cap is admitted, so one heavy user's backlog never holds up another user's next turn. Requests that name no consumer are never capped. Off by default — the plain `--max-concurrent` ceiling still applies to everyone together.
 
-Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `unknown`) so you can see which bucket each request billed against and a `subscriptionPercent` headline number tells you at a glance whether dario is actually routing through your subscription or silently falling to API overage.
+Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `credits` / `unknown`) so you can see which bucket each request billed against and a `subscriptionPercent` headline number tells you at a glance whether dario is actually routing through your subscription or silently falling to API overage.
 
 ## Refresh-token grant age
 

package/docs/pool-keys-and-analytics.md

@@ -73,6 +73,8 @@ The rolling window forgets on every restart; the **ledger** does not. Since 6.6
 
 Only served requests count. Traffic that was metered anyway — an API key upstream, or Anthropic's paid `extra_usage` overage — is kept in its own column and reported as spent, not saved. `dario usage --card` writes the headline as a 640×320 SVG you can drop in a README or a post, and `--donut` writes the same number as three rings — by model, by key, subscription vs metered; `--no-ledger` / `DARIO_LEDGER=0` turns the file off, `DARIO_LEDGER_PATH` moves it, and `GET /analytics/ledger` is the per-day table behind the number. Details: [api-equivalent-spend.md](api-equivalent-spend.md).
 
+A request served on a Max plan's API credits (the `credits:<model>` rung of the failover chain, key in `DARIO_CREDITS_API_KEY`, [failover](two-plans.md#failover-between-subscriptions)) is counted as spent the same way in the ledger; `/analytics`, `/metrics` and the dashboard show it under its own bucket, `credits`.
+
 **Scrape it, or open it.** `GET /metrics` is the same state as Prometheus text exposition — window, seats, models, consumers, queue, latency quantiles, burn rates, ledger — so Grafana reads dario like anything else. Since 6.9 every request also carries its **timing split**: queue wait, governor sleep, the provider's time to first byte, the provider's total, and what is left — dario's own overhead — as `x-dario-*-ms` response headers on the request itself, as `window.timing` on `/analytics`, and as five more `/metrics` families, so "was that Anthropic or the proxy?" is a `curl -i` away ([details](analytics.md#the-timing-split)). `GET /analytics/ui` is a self-contained dashboard page with the headline, the rings and the tables, refreshing every minute. Both sit behind the same gate as `/analytics`; `--analytics-token` (env `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on those paths and nowhere else, so a scraper or a browser can hold the numbers without holding request rights. Families and the gate: [analytics.md](analytics.md).
 
 ---

package/docs/two-plans.md

@@ -44,6 +44,8 @@ That is a **chain**, read left to right; each provider takes the first entry it
 
 A single-entry chain is one-way and means what it always meant, so an existing config is unaffected. Failover is opt-in: without `--pool-fallback`, a drained pool still returns its honest 429/503. Only a **429 or 5xx** fails over; a 400 surfaces, because a bad request that fails over just reproduces itself on the other provider and buries the real cause. A 429 also cools that provider for a bounded interval, its `retry-after` if it sent one and 60 s otherwise, never longer than 15 min, and an entry that already declined is not asked again within the same request. When every entry is cooling, the request ends on one honest `429` with a `retry-after` instead of a retry storm. The Claude entry has to be a model the pool can actually serve, checked positively against the live catalog, so a typo can't trade a recoverable 429 for an unrecoverable 404.
 
+An entry written `credits:<model>` is a rung on the API credits a Max plan includes ($100 a month on Max 5x, $200 on Max 20x, spent through a Console key). It is opt-in twice: the entry has to be in the chain, and the key has to be in `DARIO_CREDITS_API_KEY` (env only, never a flag, so it never lands in argv). When every seat is drained or cooling and no subscription rung can serve, the request goes to `api.anthropic.com` on the Messages path as a plain API request: the client's own body with the model swapped, `x-api-key`, no Claude Code template and no OAuth beta. Both wire shapes work, since the Claude path already translates OpenAI-shape requests. The response says `x-dario-pool-fallback: credits:<model>`. The rolling window, `/metrics` and the dashboard file the request under its own billing bucket, `credits`, next to extra usage and API key; the persistent ledger counts it in its metered total, as spent, the way it counts an API key. The overage guard does not halt on it: a rung you configured is not a surprise bill. A subscription rung always goes first; between the credits rung and an openai-compat backend, the chain's own left-to-right order decides. Tier maps take it too (`opus:credits:claude-opus-5`). Without the key the entry is inert, the startup line says so and `dario doctor` says so in its Failover line.
+
 The chain also covers a stream that dies **mid-answer**. Until 6.1 that was the one failure nothing could catch: bytes were on the wire, so the socket reset, the in-band `overloaded_error`, the codex `response.failed` all ended the stream where they happened, with no `message_stop`, and the client threw away every word it already had. Now dario finishes the same stream — on the same model first, a fresh request through its own front door; on the other subscription when that delivers nothing or dies too. The resume picks up inside the still-open content block, a comment marks each seam (`: dario continuation claude-opus-5 (same model) after 1240 chars`), and the client sees one message. The model is asked to repeat the last few words verbatim and dario trims the repeat, so the join is rendered by a model and cut by a parser, never guessed. Text only — a cut inside a tool call ends as it always did. On by default, `--no-midstream-continue` turns it off; without a chain the second hop is simply not there. [How it works](midstream-continuation.md).
 
 `dario doctor` tells you which of these you are actually in:

package/docs/who-its-for.md

@@ -1,10 +1,10 @@
 # Who it's for
 
-**Best fit:** developers juggling multiple LLM tools and per-tool API keys · Claude Pro/Max subscribers who want their plan usable everywhere, not just in Claude Code · ChatGPT Plus/Pro subscribers who want their plan in OpenAI-compatible harnesses · teams running local or hosted OpenAI-compat servers who want one stable local endpoint · Agent SDK users who want subscription routing with zero code change · power users wanting multi-account pooling with 429 failover.
+**Best fit:** developers juggling multiple LLM tools and per-tool API keys · Claude Pro/Max subscribers who want their plan usable everywhere, not just in Claude Code · ChatGPT Plus/Pro subscribers who want their plan in OpenAI-compatible harnesses · teams running local or hosted OpenAI-compat servers who want one stable local endpoint · Agent SDK users who want subscription routing with zero code change · power users wanting multi-account pooling with 429 failover · anyone who wants one number for what their plans absorbed across every tool.
 
 **Not a fit:** you need vendor-managed production SLAs (use the provider APIs) · you want a hosted multi-tenant team platform with dashboards and SSO (dario is a single-owner local proxy) · you want a chat UI (use claude.ai).
 
-**How it compares.** Only one of these routes a consumer subscription; the others route API keys, and that is the whole split.
+**How it compares.** Only one of these routes a consumer subscription and prices every request against the API rate card; the others route API keys, and that is the whole split.
 
 | Tool | What it is | When it wins |
 |---|---|---|

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@askalf/dario",
-  "version": "6.15.0",
-  "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
+  "version": "6.17.0",
+  "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, opt-in failover when one hits its limit, and a ledger of what each plan absorbed.",
   "type": "module",
   "bin": {
     "dario": "./dist/cli.js"
@@ -22,7 +22,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && cp src/cc-template-data.json dist/",
+    "build": "tsc && cp src/cc-template-data.json src/analytics-ui.html dist/",
     "test": "node --test test/all.test.mjs",
     "test:serial": "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/live-fingerprint.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/session-rotation.mjs && node test/drift-detection.mjs && node test/cc-authorize-probe-classifier.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/doctor-identity-drift.mjs && node test/doctor-oauth-pool.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/durable-token-persist.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs && node test/context-bleed.mjs && node test/passthrough-header-forwarding.mjs && node test/capture-provenance.mjs && node test/sanitize-messages.mjs && node test/platform-tools.mjs && node test/strict-template-flags.mjs && node test/request-queue.mjs && node test/effort-flag.mjs && node test/template-invariants.mjs",
     "audit": "npm audit --production --audit-level=high",
@@ -71,7 +71,11 @@
     "ollama",
     "groq",
     "cli",
-    "developer-tools"
+    "developer-tools",
+    "usage-ledger",
+    "dashboard",
+    "api-credits",
+    "rate-limits"
   ],
   "author": "askalf (https://github.com/askalf)",
   "license": "MIT",