@askalf/dario 6.14.3 → 6.16.0

package/dist/body-identity.d.ts

@@ -0,0 +1,25 @@
+/** The three values `metadata.user_id` is built from. */
+export interface BodyIdentity {
+    deviceId: string;
+    accountUuid: string;
+    sessionId: string;
+}
+/**
+ * The `metadata.user_id` string Claude Code sends: a JSON object with
+ * device_id, account_uuid and session_id in that order. Shared by the
+ * template build and the failover rebind so both produce the same bytes.
+ */
+export declare function buildMetadataUserId(identity: BodyIdentity): string;
+/**
+ * `body` with `metadata.user_id` rebuilt for `identity`, for a request that
+ * fails over to another account. `cchVersion` is the Claude Code version to
+ * stamp cch for after the rewrite, or null where the first serialize did not
+ * stamp (DARIO_CCH=random); stampCch is itself a no-op without a seed.
+ *
+ * Returns `body` itself, the same Buffer, when there is nothing to rebind: no
+ * body, a body that is not JSON, no string `metadata.user_id`, or a user_id
+ * that already names `identity`. The body was serialized by JSON.stringify,
+ * so parse and stringify again give the same bytes apart from user_id, and
+ * user_id is replaced in place so key order is kept.
+ */
+export declare function rebindBodyIdentity(body: Buffer | undefined, identity: BodyIdentity, cchVersion: string | null): Buffer | undefined;

package/dist/body-identity.js

@@ -0,0 +1,68 @@
+/**
+ * The account identity a built Claude Code body carries, and how it moves to
+ * another seat when a request fails over mid-flight.
+ *
+ * The template build stamps `metadata.user_id` from the selected account's
+ * device_id and account_uuid plus the session id the
+ * `x-claude-code-session-id` header carries. A 429 or 401/403 failover sends
+ * the same body to a different account, so the body must name that account
+ * and the session id its header now carries; otherwise seat B is sent seat
+ * A's device_id and account_uuid and a session_id that disagrees with its own
+ * header. The cch stamp (src/cch.ts) hashes the body, user_id included, so a
+ * rewritten body is stamped again.
+ *
+ * Pure, and imports nothing that reads the filesystem, so it is unit-testable
+ * without a proxy or a ~/.dario.
+ */
+import { stampCch } from './cch.js';
+/**
+ * The `metadata.user_id` string Claude Code sends: a JSON object with
+ * device_id, account_uuid and session_id in that order. Shared by the
+ * template build and the failover rebind so both produce the same bytes.
+ */
+export function buildMetadataUserId(identity) {
+    return JSON.stringify({
+        device_id: identity.deviceId,
+        account_uuid: identity.accountUuid,
+        session_id: identity.sessionId,
+    });
+}
+/**
+ * `body` with `metadata.user_id` rebuilt for `identity`, for a request that
+ * fails over to another account. `cchVersion` is the Claude Code version to
+ * stamp cch for after the rewrite, or null where the first serialize did not
+ * stamp (DARIO_CCH=random); stampCch is itself a no-op without a seed.
+ *
+ * Returns `body` itself, the same Buffer, when there is nothing to rebind: no
+ * body, a body that is not JSON, no string `metadata.user_id`, or a user_id
+ * that already names `identity`. The body was serialized by JSON.stringify,
+ * so parse and stringify again give the same bytes apart from user_id, and
+ * user_id is replaced in place so key order is kept.
+ */
+export function rebindBodyIdentity(body, identity, cchVersion) {
+    if (!body)
+        return body;
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        return body;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return body;
+    const metadata = parsed.metadata;
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+        return body;
+    const meta = metadata;
+    if (typeof meta.user_id !== 'string')
+        return body;
+    const userId = buildMetadataUserId(identity);
+    if (meta.user_id === userId)
+        return body;
+    meta.user_id = userId;
+    let text = JSON.stringify(parsed);
+    if (cchVersion !== null)
+        text = stampCch(text, cchVersion);
+    return Buffer.from(text);
+}

package/dist/cc-template.js

@@ -9,6 +9,7 @@
  */
 import { loadTemplate, promptVariantsOf, VARIANT_FAMILIES, PLATFORM_ONLY_TOOLS, INTERACTIVE_ONLY_TOOLS, CONFIG_SCOPED_TOOLS, DEFERRED_TOOLS, } from './live-fingerprint.js';
 import { VALID_EFFORT_VALUES, parseEffortSuffix } from './effort.js';
+import { buildMetadataUserId } from './body-identity.js';
 // Re-exported so existing importers (scripts/capture-and-bake.mjs, the template
 // invariant tests) keep their import site. The definitions live in
 // live-fingerprint.ts because loadTemplate must apply the same superset rule to
@@ -1819,13 +1820,7 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
             }
         }
         const body = { ...clientBody, system };
-        body.metadata = {
-            user_id: JSON.stringify({
-                device_id: identity.deviceId,
-                account_uuid: identity.accountUuid,
-                session_id: identity.sessionId,
-            }),
-        };
+        body.metadata = { user_id: buildMetadataUserId(identity) };
         return { body, toolMap: new Map(), unmappedTools: [], genuineCC: true };
     }
     // ── Detect text-tool-protocol clients up-front ──
@@ -2275,13 +2270,7 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
             ccRequest.tool_choice = passed;
     }
     // Metadata
-    ccRequest.metadata = {
-        user_id: JSON.stringify({
-            device_id: identity.deviceId,
-            account_uuid: identity.accountUuid,
-            session_id: identity.sessionId,
-        }),
-    };
+    ccRequest.metadata = { user_id: buildMetadataUserId(identity) };
     ccRequest.max_tokens = resolveMaxTokens(opts.maxTokens, clientBody);
     // Model-specific fields — order: thinking, context_management, output_config
     //

package/dist/cli.d.ts

@@ -114,6 +114,13 @@ export declare function parseBooleanEnv(value: string | undefined): boolean | un
  *   Set(['thinking','env']) — value "thinking,env"        → preserve listed
  */
 export declare function resolvePreserveOrchestrationTags(args: string[], env: string | undefined): Set<string> | undefined;
+/**
+ * --upstream-timeout / DARIO_UPSTREAM_TIMEOUT_MS. The flag wins over the env
+ * var even when it is 0, and 0 then resolves to undefined so the proxy's
+ * default applies: an explicit `--upstream-timeout=0` keeps the default
+ * rather than falling through to the env value. Exported for tests.
+ */
+export declare function resolveUpstreamTimeoutMs(flag: number | undefined, env: string | undefined): number | undefined;
 /**
  * The seat shape a running proxy returns from `/accounts`.
  *

package/dist/cli.js

@@ -516,6 +516,12 @@ async function proxy() {
     // used to sever every streaming response after five seconds. dario#1370.
     const shutdownGraceMs = parsePositiveIntFlag('--shutdown-grace=')
         ?? parsePositiveIntEnv(process.env['DARIO_SHUTDOWN_GRACE_MS']);
+    // --upstream-timeout=MS: how long dario waits for upstream (default 300000).
+    // Until the response streams it caps the whole wait; once a 2xx streams it
+    // is the longest gap allowed between two chunks, so a long answer that is
+    // still sending is never cut. 0 keeps the default: an always-firing timer
+    // would fail every request.
+    const upstreamTimeoutMs = resolveUpstreamTimeoutMs(parsePositiveIntFlag('--upstream-timeout='), process.env['DARIO_UPSTREAM_TIMEOUT_MS']);
     // --pool-strategy=headroom|fill-first — where UNBOUND (new) conversations
     // land. `headroom` (default) spreads them to the seat with the most slack;
     // `fill-first` concentrates them on the alphabetically-first eligible seat
@@ -526,9 +532,9 @@ async function proxy() {
     // expires soonest before touching the rest.
     const poolStrategyFromFlag = args.find((a) => a.startsWith('--pool-strategy='))?.split('=')[1];
     if (poolStrategyFromFlag !== undefined
-        && poolStrategyFromFlag !== 'headroom' && poolStrategyFromFlag !== 'fill-first'
-        && poolStrategyFromFlag !== 'expiring-first') {
-        console.error(`[dario] Invalid --pool-strategy "${poolStrategyFromFlag}". Must be headroom, fill-first or expiring-first.`);
+        && poolStrategyFromFlag !== 'headroom' && poolStrategyFromFlag !== 'headroom-by-plan'
+        && poolStrategyFromFlag !== 'fill-first' && poolStrategyFromFlag !== 'expiring-first') {
+        console.error(`[dario] Invalid --pool-strategy "${poolStrategyFromFlag}". Must be headroom, headroom-by-plan, fill-first or expiring-first.`);
         process.exit(1);
     }
     const poolStrategy = poolStrategyFromFlag
@@ -786,7 +792,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, familyFallback, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, upstreamTimeoutMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, familyFallback, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
 }
 /**
  * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
@@ -1208,6 +1214,16 @@ function parsePreserveTagsValue(value) {
         return new Set(['*']);
     return new Set(trimmed.split(',').map(s => s.trim()).filter(Boolean));
 }
+/**
+ * --upstream-timeout / DARIO_UPSTREAM_TIMEOUT_MS. The flag wins over the env
+ * var even when it is 0, and 0 then resolves to undefined so the proxy's
+ * default applies: an explicit `--upstream-timeout=0` keeps the default
+ * rather than falling through to the env value. Exported for tests.
+ */
+export function resolveUpstreamTimeoutMs(flag, env) {
+    const ms = flag ?? parsePositiveIntEnv(env);
+    return ms === 0 ? undefined : ms;
+}
 function parsePositiveIntFlag(prefix) {
     const found = args.find(a => a.startsWith(prefix));
     if (!found)
@@ -2212,6 +2228,12 @@ async function help() {
                              container's stop grace above it, or Docker
                              SIGKILLs the drain. Env:
                              DARIO_SHUTDOWN_GRACE_MS. (dario#1370)
+    --upstream-timeout=MS    How long dario waits on upstream (default:
+                             300000). Until the response streams it caps
+                             the whole wait; while a 2xx streams it is
+                             the longest gap between two chunks, so a
+                             live stream is never cut. 0 keeps the
+                             default. Env: DARIO_UPSTREAM_TIMEOUT_MS.
     --max-concurrent=N       Max in-flight requests across the WHOLE proxy,
                              not per seat (default: 10; a pool defaults to
                              10 per seat). Past it, requests wait in dario.
@@ -2239,11 +2261,13 @@ async function help() {
                              dario returns 504 "queue-timeout"
                              (default: 60000).
                              Env: DARIO_QUEUE_TIMEOUT_MS. (dario#80)
-    --pool-strategy=<headroom|fill-first|expiring-first>
+    --pool-strategy=<headroom|headroom-by-plan|fill-first|expiring-first>
                              Where new conversations land in a multi-
                              account pool. headroom (default) spreads
                              them to the seat with the most slack;
-                             fill-first concentrates them on the
+                             headroom-by-plan (opt-in) counts each
+                             seat's slack by plan size (Max Nx = N,
+                             Pro = 1); fill-first concentrates them on the
                              alphabetically-first eligible seat until
                              it drains to the floor, then spills;
                              expiring-first does the same in order of
@@ -3174,12 +3198,16 @@ if (isDirectEntry) {
     if (!('Bun' in globalThis) && !process.env.DARIO_NO_BUN) {
         try {
             const { execFileSync, spawn } = await import('node:child_process');
+            const { forwardSignals, relaunchExitCode } = await import('./relaunch-signals.js');
             execFileSync('bun', ['--version'], { stdio: 'ignore', timeout: 3000 });
             const child = spawn('bun', ['run', ...process.argv.slice(1)], {
                 stdio: 'inherit',
                 env: { ...process.env, DARIO_NO_BUN: '1' },
             });
-            child.on('exit', (code) => process.exit(code ?? 0));
+            // The child owns the graceful shutdown; as PID 1 in a container this
+            // process would otherwise drop SIGTERM and docker stop would SIGKILL both.
+            forwardSignals(child);
+            child.on('exit', (code, signal) => process.exit(relaunchExitCode(code, signal)));
             // Prevent this process from continuing
             await new Promise(() => { });
         }

package/dist/codex-backend.js

@@ -29,6 +29,7 @@ import { resolveClaudeTarget } from './claude-model.js';
 import { parseEffortSuffix } from './effort.js';
 import { BAKED_BASE_MODELS } from './model-catalog.js';
 import { parseRetryAfterMs } from './provider-cooldown.js';
+import { upstreamDeadline } from './upstream-deadline.js';
 import { noteCodexUsageHeaders, parseCodexUsageEndpoint, recordCodexUsage, codexUsageFor } from './codex-usage.js';
 export const CODEX_BACKEND_BASE_URL = process.env.DARIO_CODEX_BASE_URL || 'https://chatgpt.com/backend-api/codex';
 /** The usage endpoint the Codex CLI's /status reads, beside the Responses base. */
@@ -914,7 +915,8 @@ timing) {
             abort.abort();
     } };
     res.on('close', onClientClose);
-    const timeout = setTimeout(() => abort.abort(), upstreamTimeoutMs);
+    // Caps the wait until headers, then the gap between chunks of the 2xx body.
+    const timeout = upstreamDeadline(upstreamTimeoutMs, () => abort.abort());
     let usage = null;
     try {
         if (verbose)
@@ -962,6 +964,7 @@ timing) {
             return true;
         }
         res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'Access-Control-Allow-Origin': corsOrigin, ...securityHeaders, ...splitHeaders() });
+        timeout.streaming();
         const reader = upstream.body.getReader();
         const decoder = new TextDecoder();
         let tail = '';
@@ -969,6 +972,7 @@ timing) {
         try {
             while (true) {
                 const { done, value } = await reader.read();
+                timeout.touch();
                 if (done)
                     break;
                 if (clientGone)
@@ -1033,7 +1037,7 @@ timing) {
         return true;
     }
     finally {
-        clearTimeout(timeout);
+        timeout.clear();
         res.removeListener('close', onClientClose);
     }
 }
@@ -1196,7 +1200,9 @@ timing) {
     // Usage seen so far, so a stream the client abandoned still reports what the
     // subscription already spent. Populated once the translators exist.
     let usageSoFar = () => null;
-    const timeout = setTimeout(() => abort.abort(), upstreamTimeoutMs);
+    // Caps the wait until headers, then the gap between chunks of the 2xx body:
+    // the backend always streams, so a long answer is never cut mid-way.
+    const timeout = upstreamDeadline(upstreamTimeoutMs, () => abort.abort());
     try {
         if (verbose)
             console.log(`[dario] → codex backend: ${target} (model: ${model})`);
@@ -1324,11 +1330,13 @@ timing) {
         }
         let buffered = '';
         if (upstream.body) {
+            timeout.streaming();
             const reader = upstream.body.getReader();
             const decoder = new TextDecoder();
             try {
                 while (true) {
                     const { done, value } = await reader.read();
+                    timeout.touch();
                     if (done)
                         break;
                     // The abort above normally makes this read reject; a stream that
@@ -1484,7 +1492,7 @@ timing) {
         return true;
     }
     finally {
-        clearTimeout(timeout);
+        timeout.clear();
         res.removeListener('close', onClientClose);
     }
 }

package/dist/config-file.d.ts

@@ -89,7 +89,7 @@ export interface DarioConfig {
          * `expiring-first` is fill-first ordered by each seat's 7-day reset,
          * soonest first.
          */
-        strategy?: 'headroom' | 'fill-first' | 'expiring-first';
+        strategy?: 'headroom' | 'headroom-by-plan' | 'fill-first' | 'expiring-first';
         /** Headroom at/below which a seat counts as drained — ratio 0.02..0.5 (dario#1333). */
         headroomFloor?: number;
     };

package/dist/config-file.js

@@ -309,8 +309,8 @@ function sanitize(parsed) {
     }
     if (isPlainObject(parsed.pool)) {
         out.pool = {};
-        if (parsed.pool.strategy === 'headroom' || parsed.pool.strategy === 'fill-first'
-            || parsed.pool.strategy === 'expiring-first') {
+        if (parsed.pool.strategy === 'headroom' || parsed.pool.strategy === 'headroom-by-plan'
+            || parsed.pool.strategy === 'fill-first' || parsed.pool.strategy === 'expiring-first') {
             out.pool.strategy = parsed.pool.strategy;
         }
         if (typeof parsed.pool.headroomFloor === 'number' && Number.isFinite(parsed.pool.headroomFloor)) {

package/dist/midstream.js

@@ -47,6 +47,7 @@
  * the existing pre-byte failover covers them), and the api-key OpenAI backend.
  * A stream that cannot be continued ends exactly as it did before this module.
  */
+import { upstreamDeadline } from './upstream-deadline.js';
 /**
  * Marks a loopback request as a continuation and carries its DEPTH: `1` for
  * the resume of a client request, `2` for the resume of that resume. A
@@ -836,7 +837,8 @@ export class MidstreamGuard {
         const body = buildResumeBody(this.o.shape, clientBody, target.model, partial);
         const splicer = new Splicer(this.o.shape, s, partial);
         const abort = new AbortController();
-        const timer = setTimeout(() => abort.abort(), r.timeoutMs);
+        // Caps the wait until headers, then the gap between chunks of the resume.
+        const timer = upstreamDeadline(r.timeoutMs, () => abort.abort());
         const startedAt = Date.now();
         try {
             r.onBeforeResume?.();
@@ -854,6 +856,7 @@ export class MidstreamGuard {
             // An SSE comment, ignored by every parser, so a raw capture shows where
             // the second provider took over.
             this.o.write(`${SEAM_COMMENT_PREFIX} ${target.label} after ${partial.length} chars\n\n`);
+            timer.streaming();
             const reader = res.body.getReader();
             const split = new SseFrameSplitter();
             let sawContent = false;
@@ -861,6 +864,7 @@ export class MidstreamGuard {
             try {
                 outer: while (true) {
                     const { done, value } = await reader.read();
+                    timer.touch();
                     if (done)
                         break;
                     if (this.o.isClientGone()) {
@@ -919,7 +923,7 @@ export class MidstreamGuard {
             return 'failed';
         }
         finally {
-            clearTimeout(timer);
+            timer.clear();
         }
     }
     log(line) {

package/dist/openai-backend.js

@@ -15,6 +15,7 @@
 import { readFile, writeFile, mkdir, unlink, readdir } from 'node:fs/promises';
 import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
+import { upstreamDeadline } from './upstream-deadline.js';
 const DARIO_DIR = join(homedir(), '.dario');
 const BACKENDS_DIR = join(DARIO_DIR, 'backends');
 export const MINIMAX_MODELS = ['MiniMax-M3.1-Flash', 'MiniMax-M3'];
@@ -138,7 +139,8 @@ export async function forwardToOpenAI(req, res, body, backend, corsOrigin, secur
     // Drop Anthropic-specific headers entirely
     void clientBeta;
     const abort = new AbortController();
-    const timeout = setTimeout(() => abort.abort(), upstreamTimeoutMs);
+    // Caps the wait until headers, then the gap between chunks of a 2xx body.
+    const timeout = upstreamDeadline(upstreamTimeoutMs, () => abort.abort());
     try {
         if (verbose) {
             console.log(`[dario] → openai backend: ${target}`);
@@ -165,10 +167,13 @@ export async function forwardToOpenAI(req, res, body, backend, corsOrigin, secur
         }
         res.writeHead(upstream.status, respHeaders);
         if (upstream.body) {
+            if (upstream.ok)
+                timeout.streaming();
             const reader = upstream.body.getReader();
             try {
                 while (true) {
                     const { done, value } = await reader.read();
+                    timeout.touch();
                     if (done)
                         break;
                     if (value)
@@ -182,7 +187,7 @@ export async function forwardToOpenAI(req, res, body, backend, corsOrigin, secur
         res.end();
     }
     catch (err) {
-        clearTimeout(timeout);
+        timeout.clear();
         // Log error details server-side only. Responding with err.message
         // exposes internal stack / path / module information (CodeQL
         // js/stack-trace-exposure). The client gets a generic 502.
@@ -205,6 +210,6 @@ export async function forwardToOpenAI(req, res, body, backend, corsOrigin, secur
         return;
     }
     finally {
-        clearTimeout(timeout);
+        timeout.clear();
     }
 }

package/dist/pool.d.ts

@@ -396,8 +396,24 @@ export interface PoolStatus {
  * order is the operator's knob — name seats `1-main` / `2-overflow` to
  * pick the fill order. Sticky bindings behave identically in both modes;
  * strategy only decides where UNBOUND (new) conversations land.
+ *
+ * `headroom-by-plan` (opt-in): headroom, with each seat's headroom counted
+ * by its plan size (see planWeight). Never the default: utilization is a
+ * ratio of an account-wide budget that also carries the owner's own use, no
+ * absolute capacity reaches the wire, and the window that binds (5h or 7d)
+ * matters more than the plan name. A smaller plan regularly has more real
+ * room than a bigger one. It is for operators who know their seats are
+ * otherwise idle and want the bigger plan to carry proportionally more.
+ */
+export type PoolStrategy = 'headroom' | 'headroom-by-plan' | 'fill-first' | 'expiring-first';
+/**
+ * How much a seat's headroom counts under `headroom-by-plan`: N for a Max Nx
+ * plan (from the profile's `rate_limit_tier`, e.g. `default_claude_max_20x`),
+ * 1 for Pro, and 1 for anything unrecognised or unknown, so a seat whose plan
+ * dario cannot read is never favoured. Only the whole `default_claude_max_Nx`
+ * tier name counts; a tier that merely contains `max_Nx` is unrecognised.
  */
-export type PoolStrategy = 'headroom' | 'fill-first' | 'expiring-first';
+export declare function planWeight(rateLimitTier: string | undefined): number;
 /**
  * `expiring-first` — fill-first, ordered by WHEN each seat's capacity expires
  * instead of by alias: new conversations fill the seat whose 7-day window
@@ -602,6 +618,7 @@ export declare function headroomFloorProblem(value: string | number | null | und
  */
 export declare function headroomFloorFlagProblem(value: string): string;
 export declare function resolvePoolHeadroomFloor(explicit?: string | number | null, env?: NodeJS.ProcessEnv): number;
+export declare function pickMaxHeadroom(accounts: PoolAccount[], family?: string | null, byPlan?: boolean): PoolAccount;
 /**
  * The 7-day reset `expiring-first` orders by, in epoch ms: the seat's own
  * reading while it is still ahead of `now`, else +Infinity (never read, or the

package/dist/pool.js

@@ -408,6 +408,18 @@ export function accountAction(account, now = Date.now()) {
         return 'wait';
     return 'none';
 }
+/**
+ * How much a seat's headroom counts under `headroom-by-plan`: N for a Max Nx
+ * plan (from the profile's `rate_limit_tier`, e.g. `default_claude_max_20x`),
+ * 1 for Pro, and 1 for anything unrecognised or unknown, so a seat whose plan
+ * dario cannot read is never favoured. Only the whole `default_claude_max_Nx`
+ * tier name counts; a tier that merely contains `max_Nx` is unrecognised.
+ */
+export function planWeight(rateLimitTier) {
+    const m = /^default_claude_max_(\d+)x$/i.exec(rateLimitTier ?? '');
+    const n = m ? Number(m[1]) : 1;
+    return Number.isFinite(n) && n >= 1 ? n : 1;
+}
 /**
  * `expiring-first` — fill-first, ordered by WHEN each seat's capacity expires
  * instead of by alias: new conversations fill the seat whose 7-day window
@@ -431,7 +443,7 @@ export function resolvePoolStrategy(explicit, env = process.env) {
         if (typeof c !== 'string')
             continue;
         const s = c.trim().toLowerCase();
-        if (s === 'headroom' || s === 'fill-first' || s === 'expiring-first')
+        if (s === 'headroom' || s === 'headroom-by-plan' || s === 'fill-first' || s === 'expiring-first')
             return s;
     }
     return 'headroom';
@@ -446,6 +458,8 @@ export function resolvePoolStrategy(explicit, env = process.env) {
 export function describePoolStrategy(strategy, floor = DEFAULT_POOL_HEADROOM_FLOOR) {
     const pct = `${Math.round(floor * 100)}% floor`;
     switch (strategy) {
+        case 'headroom-by-plan':
+            return `headroom-by-plan: new conversations go to the seat with the most headroom counted by plan size (Max Nx counts N, Pro 1); ${pct}`;
         case 'fill-first':
             return `fill-first — new conversations fill the alphabetically-first seat until the ${pct}, then spill`;
         case 'expiring-first':
@@ -866,14 +880,21 @@ export function resolvePoolHeadroomFloor(explicit, env = process.env) {
 // Pick the account with the most headroom in a single pass. The prior
 // `.reduce()` form recomputed the incumbent's headroom every iteration
 // (~2n computeHeadroom calls); this computes each once (#642-audit).
-function pickMaxHeadroom(accounts, family) {
+// `byPlan` scales positive headroom by planWeight; zero and negative headroom
+// stay unscaled, so a bigger plan that is over its limit never ranks lower
+// than a smaller one that is over by the same amount.
+export function pickMaxHeadroom(accounts, family, byPlan = false) {
+    const score = (a) => {
+        const h = computeHeadroom(a.rateLimit, family);
+        return byPlan && h > 0 ? h * planWeight(a.rateLimitTier) : h;
+    };
     let best = accounts[0];
-    let bestHeadroom = computeHeadroom(best.rateLimit, family);
+    let bestScore = score(best);
     for (let i = 1; i < accounts.length; i++) {
-        const h = computeHeadroom(accounts[i].rateLimit, family);
-        if (h > bestHeadroom) {
+        const s = score(accounts[i]);
+        if (s > bestScore) {
             best = accounts[i];
-            bestHeadroom = h;
+            bestScore = s;
         }
     }
     return best;
@@ -1107,10 +1128,10 @@ export class AccountPool {
                     return first;
             }
             if (!this.hardHeadroomFloor)
-                return pickMaxHeadroom(eligible, family);
+                return pickMaxHeadroom(eligible, family, this.strategy === 'headroom-by-plan');
             const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
             return aboveFloor.length > 0
-                ? pickMaxHeadroom(aboveFloor, family)
+                ? pickMaxHeadroom(aboveFloor, family, this.strategy === 'headroom-by-plan')
                 : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // No seat is eligible. A seat parked inside a live window is not
@@ -1287,10 +1308,10 @@ export class AccountPool {
                     return first;
             }
             if (!this.hardHeadroomFloor)
-                return pickMaxHeadroom(eligible, family);
+                return pickMaxHeadroom(eligible, family, this.strategy === 'headroom-by-plan');
             const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
             return aboveFloor.length > 0
-                ? pickMaxHeadroom(aboveFloor, family)
+                ? pickMaxHeadroom(aboveFloor, family, this.strategy === 'headroom-by-plan')
                 : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // Mid-flight: the seats a 429 could still hand this request to. A seat

package/dist/proxy.d.ts

@@ -126,6 +126,13 @@ export declare function parseProviderPrefix(model: string): {
  * Exported for tests.
  */
 export declare const FABLE_FALLBACK_CREDIT_BETA = "fallback-credit-2026-06-01";
+/**
+ * Marks the request the family fallback sends again through dario's own front
+ * door after a mid-flight 429 (see familyFallbackOn429 in startProxy). A
+ * request carrying it is never sent again itself, so the fallback takes one
+ * hop. A client that sends it only turns that re-send off for its request.
+ */
+export declare const FAMILY_FALLBACK_LEG_HEADER = "x-dario-family-fallback-leg";
 export declare const CONTEXT_1M_BETA = "context-1m-2025-08-07";
 export declare const MID_CONVERSATION_SYSTEM_BETA = "mid-conversation-system-2026-04-07";
 export declare const EFFORT_BETA = "effort-2025-11-24";
@@ -496,7 +503,10 @@ interface ProxyOptions {
     maxConcurrentPerConsumer?: number;
     /**
      * Max ms before the upstream fetch is aborted. Default 300000 (5 min,
-     * matching the Anthropic SDK). Injectable so tests can exercise the
+     * matching the Anthropic SDK). It caps the wait until the response
+     * streams; once a 2xx body is being read it is the longest allowed gap
+     * between two chunks, so a live stream is never cut. `--upstream-timeout`
+     * / `DARIO_UPSTREAM_TIMEOUT_MS`. Injectable so tests can exercise the
      * timeout → slot-release path without waiting 5 minutes (dario#905).
      */
     upstreamTimeoutMs?: number;

package/dist/proxy.js

@@ -13,6 +13,7 @@ import { getServingProbe } from './serving-probe.js';
 import { darioVersion } from './version.js';
 import { CC_TOOL_DEFINITIONS_UNADVERTISABLE, CC_TEMPLATE_PROMPT_BYTES, resolveMaxTokens, buildCCRequest, applyCcPromptCaching, isGenuineCCClient, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, UnsupportedClientToolError, CLIENT_TOOL_MCP_PREFIX, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
+import { rebindBodyIdentity } from './body-identity.js';
 import { foldTiming, timingHeaders, timingLogFields } from './timing.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
 import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, activeParkedBuckets, reconcilePoolAccounts, resolvePoolStrategy, resolvePoolHeadroomFloor, parsePoolHeadroomFloor, describePoolStrategy, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail } from './pool.js';
@@ -59,6 +60,7 @@ import { parseFamilyFallback, familyFallbackModel, describeFamilyFallback } from
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS, resolveMaxConcurrent } from './request-queue.js';
 import { waitForIdle, drainThenClose, shutdownTimers, DEFAULT_SHUTDOWN_GRACE_MS } from './shutdown-drain.js';
 import { clampTimerMs } from './timer-ms.js';
+import { upstreamDeadline } from './upstream-deadline.js';
 import { redactSecrets } from './redact.js';
 import { BAKED_BASE_MODELS, withLongContextVariants, buildOpenAIModelsList, getModelCatalog, getCachedBases, resolveAliasAgainst, prewarmModelCatalog, retryModelCatalogNow, isSuspendedModel } from './model-catalog.js';
 import { classifyUpstreamRejection, diagnosticSnippet, POOL_PARKED } from './upstream-rejection.js';
@@ -66,7 +68,9 @@ import { ProviderCooldowns, canAttempt, allProvidersCooled, cooldownRetryAfterMs
 const ANTHROPIC_API = 'https://api.anthropic.com';
 const DEFAULT_PORT = 3456;
 const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB — generous for large prompts, prevents abuse
-const UPSTREAM_TIMEOUT_MS = 300_000; // 5 min — matches Anthropic SDK default
+// Until the response streams: the whole wait. While a 2xx streams: the longest
+// gap between two chunks (src/upstream-deadline.ts). 5 min, as in the Anthropic SDK.
+const UPSTREAM_TIMEOUT_MS = 300_000;
 const BODY_READ_TIMEOUT_MS = 30_000; // 30s — prevents slow-loris on body reads
 const DEFAULT_HOST = '127.0.0.1';
 // A host is "loopback" if it's one of the well-known localhost literals.
@@ -497,6 +501,13 @@ function filterBillableBetas(betas) {
  * Exported for tests.
  */
 export const FABLE_FALLBACK_CREDIT_BETA = 'fallback-credit-2026-06-01';
+/**
+ * Marks the request the family fallback sends again through dario's own front
+ * door after a mid-flight 429 (see familyFallbackOn429 in startProxy). A
+ * request carrying it is never sent again itself, so the fallback takes one
+ * hop. A client that sends it only turns that re-send off for its request.
+ */
+export const FAMILY_FALLBACK_LEG_HEADER = 'x-dario-family-fallback-leg';
 export const CONTEXT_1M_BETA = 'context-1m-2025-08-07';
 export const MID_CONVERSATION_SYSTEM_BETA = 'mid-conversation-system-2026-04-07';
 export const EFFORT_BETA = 'effort-2025-11-24';
@@ -3646,6 +3657,100 @@ export async function startProxy(opts = {}) {
                     return null;
                 }
             };
+            /**
+             * Family fallback, mid-flight (family-fallback.ts). The 429 that just
+             * came back can be the one that parks the family: the seat's included
+             * Fable credit ran out on this request, or dario restarted and has not
+             * yet seen the credit spent (the pool's readings live in memory). The
+             * fallback runs before selection, so this request missed it, and would
+             * go on to the codex fallback or back to the client as a 429.
+             *
+             * Instead it is sent again, as the client wrote it, through dario's own
+             * front door. That request meets the family parked, so the fallback
+             * re-points it and the whole Claude path builds it for the target model,
+             * with that model's template, betas and effort. Rewriting the model on
+             * the body already built for Fable would send Opus a Fable request.
+             *
+             * One hop: the re-sent request carries FAMILY_FALLBACK_LEG_HEADER and is
+             * never sent again itself. Skipped wherever the fallback before selection
+             * is skipped, for a continuation leg, and for a request already re-pointed.
+             * The queue slot is released first, as a continuation does, so a
+             * one-slot proxy does not wait on itself. True when the client was answered.
+             */
+            const familyFallbackOn429 = async (rejected) => {
+                if (familyFallback.size === 0 || upstreamApiKey || pinnedAccount || modelOverride || fastModelOverride)
+                    return false;
+                if (isResponses || isCountTokens || requestDepth > 0 || req.headers[FAMILY_FALLBACK_LEG_HEADER] !== undefined)
+                    return false;
+                if (res.headersSent || res.getHeader('x-dario-family-fallback') !== undefined)
+                    return false;
+                const fromModel = parseClientBody()?.model;
+                if (typeof fromModel !== 'string')
+                    return false;
+                const now = Date.now();
+                const toModel = familyFallbackModel(familyFallback, fromModel, {
+                    parked: (f) => pool.familyRateLimited(f, now),
+                    servable: (f) => pool.canServe(f, now),
+                });
+                if (!toModel)
+                    return false;
+                void rejected.body?.cancel().catch(() => { });
+                console.log(`[dario] #${requestCount} the 429 parked every seat for ${fromModel} -> sent again as ${toModel} (family fallback)`);
+                releaseQueueSlot();
+                const abort = new AbortController();
+                const onClose = () => { if (!res.writableEnded)
+                    abort.abort(); };
+                res.on('close', onClose);
+                // The loopback leg is timed like the request it replaces: until
+                // headers, then by the gap between chunks of a 2xx body.
+                const timer = upstreamDeadline(upstreamTimeoutMs, () => abort.abort());
+                try {
+                    const leg = await fetch(`${loopbackBase}${isOpenAI ? '/v1/chat/completions' : '/v1/messages'}`, {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json', [FAMILY_FALLBACK_LEG_HEADER]: '1', ...loopbackHeaders() },
+                        body: new Uint8Array(clientBodyBytes),
+                        signal: abort.signal,
+                    });
+                    const responseHeaders = { 'Access-Control-Allow-Origin': corsOrigin, ...SECURITY_HEADERS };
+                    for (const [key, value] of leg.headers.entries()) {
+                        if (key === 'content-type' || key === 'retry-after' || key === 'request-id' || key.startsWith('anthropic-ratelimit') || key.startsWith('x-dario-')) {
+                            responseHeaders[key] = value;
+                        }
+                    }
+                    responseHeaders['x-dario-family-fallback'] = fromModel;
+                    res.writeHead(leg.status, responseHeaders);
+                    if (leg.body) {
+                        if (leg.ok)
+                            timer.streaming();
+                        const reader = leg.body.getReader();
+                        while (true) {
+                            const { done, value } = await reader.read();
+                            timer.touch();
+                            if (done)
+                                break;
+                            if (!res.write(value))
+                                await new Promise((resolve) => { res.once('drain', resolve); res.once('close', resolve); });
+                        }
+                    }
+                    if (!res.writableEnded)
+                        res.end();
+                }
+                catch (err) {
+                    console.error(`[dario] #${requestCount} family fallback: the re-sent request failed: ${sanitizeError(err)}`);
+                    if (!res.headersSent) {
+                        res.writeHead(502, JSON_HEADERS);
+                        res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: 'family fallback: the re-sent request failed' } }));
+                    }
+                    else if (!res.writableEnded) {
+                        res.end();
+                    }
+                }
+                finally {
+                    timer.clear();
+                    res.off('close', onClose);
+                }
+                return true;
+            };
             /**
              * Where a Claude stream that died mid-way resumes: the codex half of the
              * `--pool-fallback` chain, exactly the entry a mid-flight 429 would use.
@@ -4535,6 +4640,10 @@ export async function startProxy(opts = {}) {
             // Outbound session id resolved once — either inside the template build
             // (so body metadata matches) or below for passthrough (no body build).
             let preBodySessionId;
+            // True once the template build has written dario's metadata.user_id
+            // into finalBody. Only such a body names the selected account, so only
+            // it is rebound when a failover switches accounts (see switchAccount).
+            let bodyIdentityOwned = false;
             // Request context for hybrid-mode field injection (#33). Built once
             // per request from incoming headers so the reverse mapper can fill
             // client-declared fields like `sessionId` that CC's schema doesn't
@@ -4780,6 +4889,7 @@ export async function startProxy(opts = {}) {
                         for (const key of Object.keys(r))
                             delete r[key];
                         Object.assign(r, ccBody);
+                        bodyIdentityOwned = true;
                         // `X[1m]` is a client-side LABEL, never a valid wire id — real CC
                         // sends the BASE model id plus the `context-1m-2025-08-07` beta
                         // (live capture 2026-06-09, CC v2.1.170 with --model
@@ -5005,17 +5115,19 @@ export async function startProxy(opts = {}) {
             // upstream fetch so Anthropic stops generating (and billing) a
             // response nobody will read. With `--drain-on-close` set, we
             // instead keep the reader spinning to consume the full SSE — see
-            // src/stream-drain.ts for the fingerprint rationale. The 5-minute
-            // upstream timeout shares the same controller, so a hung upstream
-            // still gets cut off regardless of drain mode.
+            // src/stream-drain.ts for the fingerprint rationale. The upstream
+            // timeout shares the same controller, so a hung upstream still gets
+            // cut off regardless of drain mode: it caps the wait until headers,
+            // then the gap between chunks once a 2xx streams.
             const upstreamAbort = new AbortController();
             let clientDisconnected = false;
-            upstreamTimeout = setTimeout(() => {
+            const deadline = upstreamDeadline(upstreamTimeoutMs, () => {
                 if (!upstreamAbort.signal.aborted) {
                     upstreamAbortReason = 'timeout';
                     upstreamAbort.abort();
                 }
-            }, upstreamTimeoutMs);
+            });
+            upstreamTimeout = deadline;
             onClientClose = () => {
                 const action = decideOnClientClose(res.writableEnded, upstreamAbort.signal.aborted, drainOnClose);
                 if (action === 'abort') {
@@ -5061,6 +5173,25 @@ export async function startProxy(opts = {}) {
             // combination with headroom -- opus-4-1 needs 2.
             const MAX_RECOVERY_PASSES = 4;
             let recoveryPasses = 0;
+            // Move the request to a peer seat: auth, session header, the body's
+            // metadata.user_id and the sticky binding all name `next`. The session
+            // id is resolved once so the header and the body carry the same value
+            // (the same rule as the first build), and the body's device_id and
+            // account_uuid are next's, not the rejected seat's. A body dario did not
+            // build (passthrough, count_tokens) is the client's and is left alone.
+            const switchAccount = (next) => {
+                triedAliases.add(next.alias);
+                poolAccount = next;
+                accessToken = next.accessToken;
+                headers['Authorization'] = `Bearer ${accessToken}`;
+                const sessionId = resolveOutboundSession(next, clientSessionKey).sessionId;
+                headers['x-claude-code-session-id'] = sessionId;
+                if (bodyIdentityOwned) {
+                    finalBody = rebindBodyIdentity(finalBody, { deviceId: next.identity.deviceId, accountUuid: next.identity.accountUuid, sessionId }, process.env.DARIO_CCH !== 'random' ? cliVersion : null);
+                }
+                pool.rebindSticky(stickyKey, next.alias);
+                poolSync?.bindSticky(stickyKey, next.alias);
+            };
             dispatchLoop: while (true) {
                 // Reorder outbound headers to match CC's captured header sequence
                 // when the live template recorded one. No-op on bundled-only installs.
@@ -5400,13 +5531,7 @@ export async function startProxy(opts = {}) {
                         if (poolAccount) {
                             const nextAccount = pool.selectExcluding(triedAliases, modelFamily(requestModel));
                             if (nextAccount) {
-                                triedAliases.add(nextAccount.alias);
-                                poolAccount = nextAccount;
-                                accessToken = nextAccount.accessToken;
-                                headers['Authorization'] = `Bearer ${accessToken}`;
-                                headers['x-claude-code-session-id'] = resolveOutboundSession(nextAccount, clientSessionKey).sessionId;
-                                pool.rebindSticky(stickyKey, nextAccount.alias);
-                                poolSync?.bindSticky(stickyKey, nextAccount.alias);
+                                switchAccount(nextAccount);
                                 peekedBody = null;
                                 continue dispatchLoop;
                             }
@@ -5424,6 +5549,8 @@ export async function startProxy(opts = {}) {
                         // The Claude half is out of quota for this request AND for the next
                         // one — cool it here, honouring the upstream `retry-after` when it
                         // sent one, so the following request does not re-walk the chain.
+                        if (await familyFallbackOn429(upstream))
+                            return;
                         attemptedProviders.add('claude');
                         providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
                         if (!pinnedAccount && await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt })) {
@@ -5502,13 +5629,7 @@ export async function startProxy(opts = {}) {
                     }
                     const nextAccount = pool.selectExcluding(triedAliases, modelFamily(requestModel));
                     if (nextAccount) {
-                        triedAliases.add(nextAccount.alias);
-                        poolAccount = nextAccount;
-                        accessToken = nextAccount.accessToken;
-                        headers['Authorization'] = `Bearer ${accessToken}`;
-                        headers['x-claude-code-session-id'] = resolveOutboundSession(nextAccount, clientSessionKey).sessionId;
-                        pool.rebindSticky(stickyKey, nextAccount.alias);
-                        poolSync?.bindSticky(stickyKey, nextAccount.alias);
+                        switchAccount(nextAccount);
                         continue dispatchLoop;
                     }
                     // No peer available — forward the saved generic-403 bytes when the
@@ -5536,13 +5657,7 @@ export async function startProxy(opts = {}) {
                     if (poolAccount) {
                         const nextAccount = pool.selectExcluding(triedAliases, modelFamily(requestModel));
                         if (nextAccount) {
-                            triedAliases.add(nextAccount.alias);
-                            poolAccount = nextAccount;
-                            accessToken = nextAccount.accessToken;
-                            headers['Authorization'] = `Bearer ${accessToken}`;
-                            headers['x-claude-code-session-id'] = resolveOutboundSession(nextAccount, clientSessionKey).sessionId;
-                            pool.rebindSticky(stickyKey, nextAccount.alias);
-                            poolSync?.bindSticky(stickyKey, nextAccount.alias);
+                            switchAccount(nextAccount);
                             continue dispatchLoop;
                         }
                     }
@@ -5552,6 +5667,8 @@ export async function startProxy(opts = {}) {
                     // into body. See attemptPoolFallbackOn429's doc comment for why this
                     // is one shared function rather than an inline copy.
                     // Same bookkeeping as the other mid-flight site — see there.
+                    if (await familyFallbackOn429(upstream))
+                        return;
                     attemptedProviders.add('claude');
                     providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
                     if (!pinnedAccount && await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt })) {
@@ -5739,11 +5856,17 @@ export async function startProxy(opts = {}) {
                 // parking this handler forever and leaking its queue slot — the
                 // dario#905 wedge. See waitForClientDrain in src/stream-drain.ts.
                 const waitForDrain = () => waitForClientDrain(res, upstreamAbort.signal);
+                // A 2xx stream is timed by the gap between chunks from here, so a
+                // long answer is not cut while it still streams. An error body keeps
+                // the headers-phase cap.
+                if (upstream.status >= 200 && upstream.status < 300)
+                    deadline.streaming();
                 try {
                     let buffer = '';
                     const MAX_LINE_LENGTH = 1_000_000; // 1MB max per SSE line
                     while (true) {
                         const { done, value } = await reader.read();
+                        deadline.touch();
                         if (done) {
                             upstreamDoneAt = Date.now();
                             break;
@@ -6028,7 +6151,7 @@ export async function startProxy(opts = {}) {
             // setup happens after the body-read phase, so on fast-path errors
             // (413, body read timeout) these may still be null — guard accordingly.
             if (upstreamTimeout !== null)
-                clearTimeout(upstreamTimeout);
+                upstreamTimeout.clear();
             if (onClientClose !== null)
                 req.off('close', onClientClose);
             releaseQueueSlot();
@@ -6321,8 +6444,13 @@ export async function startProxy(opts = {}) {
             catch { /* best-effort flush — never block shutdown on it */ }
         }));
     };
-    // Graceful shutdown
+    // Graceful shutdown. Runs once: a Ctrl+C in a terminal reaches the Bun child
+    // directly and again through the relaunch wrapper's forwarding.
+    let shuttingDown = false;
     const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         console.log('\n[dario] Shutting down...');
         clearInterval(presenceInterval);
         clearInterval(refreshInterval);

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/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/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.
@@ -96,7 +98,7 @@ dario proxy --family-fallback=fable=claude-opus-5-5
 - **Not for.** Upstream API-key mode (no pool), a server-wide `--model`/`--fast-model` (which replaces the name anyway) and a seat-pinned request (`x-dario-account`), which asked for that seat as it is.
 - **Shape.** The source is a family (`opus`, `sonnet`, `haiku`, `fable`); the target a `claude-*` model of another family. One step, never chained. Bad entries are dropped with a warning at startup and in `dario doctor`. A `[1m]` tag on the request carries over to a target without one.
 
-The first Fable request after the credit runs out still goes upstream and comes back `429`: that answer is what parks Fable on the seat. Every Fable request after it is switched, including after the seat has served Opus since.
+The first Fable request after the credit runs out still goes upstream and comes back `429`: that answer is what parks Fable on the seat. dario does not hand that `429` to the client: it sends the same request again, as the client wrote it, through its own front door, where the fallback now applies and the request is built for the target model (its own template, betas and effort). So is the first Fable request after a restart, which is when dario has not seen the credit spent yet. That re-sent request is never re-sent itself, and it does not wait on its own queue slot. Every Fable request after it is switched before it is sent, including after the seat has served Opus since.
 
 ## In-flight 429 failover
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.14.3",
+  "version": "6.16.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.",
   "type": "module",
   "bin": {