@askalf/dario 6.11.1 → 6.11.2

package/README.md

@@ -28,7 +28,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. The subscriptions you already pay for.</strong></p>
 
-<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~39k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
+<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~40k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub><a href="#start-in-60-seconds">Start</a> · <a href="#why-people-pick-it">Why dario</a> · <a href="#what-it-does-with-a-request">Routing</a> · <a href="#will-my-account-get-suspended">Risk</a> · <a href="#reference">Reference</a> · <a href="#trust--transparency">Trust</a> · <a href="docs/returning.md">Coming back after a while?</a></sub>
 
@@ -113,7 +113,7 @@ dario runs entirely on your machine, authenticates as you with your own Claude l
 
 | Signal | Status |
 |---|---|
-| Source | **~39k** lines of TypeScript across **77** files, auditable in a weekend. One credential path since v5: the pool. |
+| Source | **~40k** lines of TypeScript across **78** files, auditable in a weekend. One credential path since v5: the pool. |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
 | Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore, published with OIDC trusted publishing — no long-lived npm token exists to leak |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push and weekly · [ClusterFuzzLite](./.github/workflows/cflite.yml) fuzzes the SSE translator and rejection parsers weekly · [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/askalf/dario) and [Best Practices](https://www.bestpractices.dev/projects/13638) badges above are live |
@@ -228,11 +228,9 @@ MIT — see [LICENSE](LICENSE) and [DISCLAIMER.md](DISCLAIMER.md). The embedded
 dario is the routing layer of **[Own Your Stack](https://github.com/askalf)**, open tools for owning your AI infrastructure instead of renting it by the token. One subscription. Your box. Your terms.
 
 - **[dario](https://github.com/askalf/dario)** — own your routing _(you are here)_
-- **[hybrid](https://github.com/askalf/hybrid)** — own your inference
 - **[browser-bridge](https://github.com/askalf/browser-bridge)** — own your browser
 - **[redstamp](https://github.com/askalf/redstamp)** — own your agent security
 - **[truecopy](https://github.com/askalf/truecopy)** — own your agent skills
-- **[agent-security-stack](https://github.com/askalf/agent-security-stack)** — own your agent security stack: redstamp + truecopy + strongroom leases, one MCP server
 - **[cordon](https://github.com/askalf/cordon)** — own your prompts · [pair it with dario](./docs/integrations/cordon.md)
 - **[plumbline](https://github.com/askalf/plumbline)** — own your agent oversight
 - **[amnesia](https://github.com/askalf/amnesia)** — own your search

package/dist/admin-api.d.ts

@@ -76,6 +76,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { CodexSeatState } from './codex-accounts.js';
+import { type CodexUsageView } from './codex-usage.js';
 import { type KeyStore } from './keys.js';
 /** Persisted account metadata surfaced by `GET /admin/accounts`. */
 export interface AdminAccountRecord {
@@ -163,6 +164,8 @@ export interface AdminCodexAccountRecord extends CodexSeatState {
     expiresAt: number;
     /** The clock's opinion. `status` is the proxy's (dario#1343). */
     needsRefresh: boolean;
+    /** The seat's utilisation (codex-usage.ts); null before its first answer or read. */
+    usage: CodexUsageView | null;
 }
 export interface AdminAuditEvent {
     action: 'login_start' | 'login_complete' | 'account_remove' | 'auth_reject' | 'rate_limited' | 'key_create' | 'key_revoke' | 'key_rotate' | 'key_budget';

package/dist/admin-api.js

@@ -2,6 +2,7 @@ import { maskEmail } from './pool.js';
 import { timingSafeEqual } from 'node:crypto';
 import { startAddAccount, completeAddAccount, removeAccount, listAccountAliases, loadAccount, } from './accounts.js';
 import { startAddCodexAccount, completeAddCodexAccount, removeCodexAccount, loadAllCodexAccounts, listCodexAccountAliases, codexAccountNeedsRefresh, codexSeatStatus, parseCodexManualPaste, } from './codex-accounts.js';
+import { codexUsageView } from './codex-usage.js';
 import { parseManualPaste } from './oauth.js';
 import { grantAge } from './refresh-grant.js';
 import { createKey, revokeKey, rotateKey, parseExpiry, publicKey, setKeyBudget, normalizeBudget, KEY_NAME_RE } from './keys.js';
@@ -173,7 +174,7 @@ async function doCompleteCodexLogin(alias, rawCode, now, deps, remote) {
 async function listCodexAccountRecords() {
     const all = await loadAllCodexAccounts();
     return all
-        .map((a) => ({ alias: a.alias, expiresAt: a.expiresAt, needsRefresh: codexAccountNeedsRefresh(a), ...codexSeatStatus(a.alias) }))
+        .map((a) => ({ alias: a.alias, expiresAt: a.expiresAt, needsRefresh: codexAccountNeedsRefresh(a), ...codexSeatStatus(a.alias), usage: codexUsageView(a.alias) }))
         .sort((x, y) => x.alias.localeCompare(y.alias));
 }
 /** On-disk account inventory — the default `AdminDeps.listAccounts`. */

package/dist/analytics.js

@@ -210,6 +210,10 @@ export const PRICING = {
     // fast-mode tier is $10/$50, but that rides `speed:"fast"` on the API path,
     // which the subscription surface dario proxies never sends.)
     'claude-opus-5': { input: 5, output: 25, cacheRead: 0.5, cacheCreate: 6.25 },
+    // Opus 5.5 (2026-09-22) is the first Opus cheaper than the one before it: $4/$20,
+    // 5m cache-write $5, and cache-read $0.20 — 0.05x input where every other model
+    // is 0.1x (the pricing page footnotes it). Not a derived row; copy the table.
+    'claude-opus-5-5': { input: 4, output: 20, cacheRead: 0.2, cacheCreate: 5 },
     'claude-opus-4-8': { input: 5, output: 25, cacheRead: 0.5, cacheCreate: 6.25 },
     'claude-opus-4-7': { input: 5, output: 25, cacheRead: 0.5, cacheCreate: 6.25 },
     // Opus 4.6 is $5/$25 (same as 4.7/4.8), not the old $15/$75 Opus-4.1 rate.

package/dist/cli.d.ts

@@ -10,6 +10,7 @@
  *   dario logout    — Remove saved credentials
  */
 import { type EffortValue } from './cc-template.js';
+import { type CodexUsageView } from './codex-usage.js';
 /**
  * Bare words after `proxy` (dario#1353). `dario proxy` takes flags only, but it
  * read them by prefix and ignored everything else, so `dario proxy status`,
@@ -171,9 +172,11 @@ export interface LiveCodexSeat {
         status: number;
         message: string;
     } | null;
+    /** Absent from a proxy older than the usage reading; null until the seat has answered or been read. */
+    usage?: CodexUsageView | null;
 }
 /** Lines for `dario codex list --live` — pure, so the shape is testable without a proxy. */
-export declare function formatLiveCodexListing(accounts: readonly LiveCodexSeat[], port: number): string[];
+export declare function formatLiveCodexListing(accounts: readonly LiveCodexSeat[], port: number, now?: number): string[];
 /**
  * Decide whether this module is being invoked as the CLI entry point or
  * imported as a library. Pure, exported for tests; the file-bottom uses

package/dist/cli.js

@@ -63,6 +63,7 @@ import { VALID_EFFORT_VALUES } from './cc-template.js';
 import { grantAge, describeGrantAge } from './refresh-grant.js';
 import { listAccountAliases, loadAllAccounts, addAccountViaOAuth, addAccountViaManualOAuth, addAccountFromKeychain, KeychainImportError, removeAccount, ensureLoginCredentialsInPool, resyncLoginFromCredentialsIfStale, MIGRATED_LOGIN_ALIAS } from './accounts.js';
 import { listCodexAccountAliases, loadAllCodexAccounts, startAddCodexAccount, completeAddCodexAccount, removeCodexAccount, parseCodexManualPaste } from './codex-accounts.js';
+import { describeCodexWindow } from './codex-usage.js';
 import { listBackends, saveBackend, removeBackend } from './openai-backend.js';
 import { parseOutboundProxy, installOutboundProxyWrapper } from './outbound-proxy.js';
 // `args` / `command` at module scope — command handlers below close over
@@ -1228,7 +1229,7 @@ export function formatLiveAccountsListing(payload, port, now) {
     return lines;
 }
 /** Lines for `dario codex list --live` — pure, so the shape is testable without a proxy. */
-export function formatLiveCodexListing(accounts, port) {
+export function formatLiveCodexListing(accounts, port, now = Date.now()) {
     const out = ['', `  dario — Codex accounts (live, from http://127.0.0.1:${port}/codex)`, '  ───────────────────────────────────────', ''];
     if (accounts.length === 0) {
         out.push('  No Codex accounts.', '');
@@ -1250,6 +1251,15 @@ export function formatLiveCodexListing(accounts, port) {
         }
         out.push(`    ${a.alias.padEnd(20)} ${state}`);
         out.push(`    ${''.padEnd(20)} token expires in ${expiry}, ${a.requestCount} request${a.requestCount === 1 ? '' : 's'} served`);
+        if (a.usage === null) {
+            out.push(`    ${''.padEnd(20)} usage: no reading yet (the seat's first answer or the /wham/usage read supplies it)`);
+        }
+        else if (a.usage) {
+            const windows = a.usage.windows.map((w) => describeCodexWindow(w, now)).join(' · ');
+            const head = a.usage.headroom === null ? '' : ` — ${Math.round(a.usage.headroom * 100)}% headroom`;
+            const reached = a.usage.limitReached ? ` — AT LIMIT (${a.usage.limitReached})` : '';
+            out.push(`    ${''.padEnd(20)} usage: ${windows || 'no windows reported'}${head}${reached} (${a.usage.source === 'headers' ? 'from its last answer' : 'from /wham/usage'})`);
+        }
     }
     out.push('');
     return out;

package/dist/codex-accounts.d.ts

@@ -1,3 +1,4 @@
+import { type PoolStrategy } from './pool.js';
 export interface CodexAccountCredentials {
     alias: string;
     accessToken: string;
@@ -104,6 +105,18 @@ export declare function getFreshCodexAccount(creds: CodexAccountCredentials): Pr
  * a dead refresh token must not become a token-endpoint storm, one per request.
  */
 export declare function forceRefreshCodexAccount(creds: CodexAccountCredentials): Promise<CodexAccountCredentials>;
+/** The proxy sets this from the same resolved values the Claude pool runs with. */
+export declare function setCodexRouting(routing: {
+    strategy: PoolStrategy;
+    floor: number;
+}): void;
+/** Seat order for new conversations and failover: above-floor seats in strategy order, then the rest by headroom. */
+export declare function orderCodexSeats<T extends {
+    alias: string;
+}>(seats: readonly T[], now?: number, routing?: {
+    strategy: PoolStrategy;
+    floor: number;
+}): T[];
 /** Record that `alias` declined, for as long as the upstream asked. */
 export declare function noteCodexDecline(alias: string, retryAfterMs?: number | null): number;
 /** A seat that just served is not rate-limited — clear it. */
@@ -133,9 +146,9 @@ export declare function rebindCodexSticky(key: string | null | undefined, alias:
  *      pin is an instruction, so it is honoured even while cooling; the caller
  *      asked for that seat and gets its answer, 429 included.
  *   2. the seat this conversation is already bound to, unless it is cooling.
- *   3. the first seat alphabetically that is not cooling — deterministic, so a
- *      given conversation lands on the same seat across a restart and keeps its
- *      prompt cache.
+ *   3. the first seat that is not cooling, in orderCodexSeats' order (the pool
+ *      strategy over each seat's utilisation; alphabetical when there are no
+ *      readings, so a fresh process is deterministic).
  *   4. null when every seat is cooling. The caller answers from that rather
  *      than spending a request that can only 429 again.
  */

package/dist/codex-accounts.js

@@ -16,6 +16,8 @@ import { randomBytes } from 'node:crypto';
 import { generateCodexPKCE, buildCodexAuthorizeUrl, exchangeCodexAuthorizationCode, refreshCodexAccessToken, CodexRefreshError, } from './codex-oauth.js';
 import { durableWriteFile } from './durable-write.js';
 import { ProviderCooldowns } from './provider-cooldown.js';
+import { codexHeadroom, codexLongWindowResetAt } from './codex-usage.js';
+import { DEFAULT_POOL_HEADROOM_FLOOR, resolvePoolStrategy } from './pool.js';
 const DARIO_DIR = join(homedir(), '.dario');
 const CODEX_ACCOUNTS_DIR = join(DARIO_DIR, 'codex-accounts');
 /** Same alias charset/traversal guard as accounts.ts's safeAliasPath. */
@@ -374,14 +376,34 @@ async function refreshNow(creds) {
  * come out behind. So a conversation binds to a seat and stays there until that
  * seat actually declines.
  *
- * Deliberately NOT headroom routing like the Claude pool. Claude responds with
- * `anthropic-ratelimit-*` headers on every response, so that pool can read
- * utilisation before it picks. The Codex backend states nothing until it 429s —
- * the only signal is the decline itself plus its `retry-after` — so this is
- * fill-first with cool-down eviction, which is what the available signal
- * supports. If the backend ever starts reporting utilisation, this is where
- * headroom would go.
+ * NEW conversations are placed by the Claude pool's strategy and floor over
+ * each seat's utilisation (codex-usage.ts); an unread seat counts as full
+ * headroom so a new seat gets used. Cooling still overrides any reading.
  */
+let codexRouting = null;
+/** The proxy sets this from the same resolved values the Claude pool runs with. */
+export function setCodexRouting(routing) {
+    codexRouting = routing;
+}
+function currentCodexRouting() {
+    return codexRouting ?? { strategy: resolvePoolStrategy(), floor: DEFAULT_POOL_HEADROOM_FLOOR };
+}
+/** Seat order for new conversations and failover: above-floor seats in strategy order, then the rest by headroom. */
+export function orderCodexSeats(seats, now = Date.now(), routing = currentCodexRouting()) {
+    const byAlias = (a, b) => a.alias.localeCompare(b.alias);
+    const head = (s) => codexHeadroom(s.alias, now) ?? 1;
+    const byHeadroom = (a, b) => head(b) - head(a) || byAlias(a, b);
+    const alpha = [...seats].sort(byAlias);
+    const over = alpha.filter((s) => head(s) > routing.floor);
+    const under = alpha.filter((s) => head(s) <= routing.floor).sort(byHeadroom);
+    if (routing.strategy === 'fill-first')
+        return [...over, ...under];
+    if (routing.strategy === 'expiring-first') {
+        const soon = (s) => codexLongWindowResetAt(s.alias, now) ?? Number.POSITIVE_INFINITY;
+        return [...over.sort((a, b) => soon(a) - soon(b) || byAlias(a, b)), ...under];
+    }
+    return [...over.sort(byHeadroom), ...under];
+}
 let codexCooldowns = new ProviderCooldowns();
 /** conversation sticky key -> alias. Bounded; swept when it exceeds the cap. */
 const codexSticky = new Map();
@@ -444,9 +466,9 @@ export function rebindCodexSticky(key, alias) {
  *      pin is an instruction, so it is honoured even while cooling; the caller
  *      asked for that seat and gets its answer, 429 included.
  *   2. the seat this conversation is already bound to, unless it is cooling.
- *   3. the first seat alphabetically that is not cooling — deterministic, so a
- *      given conversation lands on the same seat across a restart and keeps its
- *      prompt cache.
+ *   3. the first seat that is not cooling, in orderCodexSeats' order (the pool
+ *      strategy over each seat's utilisation; alphabetical when there are no
+ *      readings, so a fresh process is deterministic).
  *   4. null when every seat is cooling. The caller answers from that rather
  *      than spending a request that can only 429 again.
  */
@@ -473,7 +495,7 @@ export async function selectCodexAccount(preferredAlias, opts) {
             codexSticky.delete(key);
         }
     }
-    const free = byAlias.find((c) => !codexCooldowns.isCooled(c.alias));
+    const free = orderCodexSeats(byAlias).find((c) => !codexCooldowns.isCooled(c.alias));
     if (!free)
         return null;
     if (key)
@@ -501,8 +523,7 @@ export async function selectCodexAccountExcluding(tried) {
     const all = await loadAllCodexAccounts();
     if (all.length === 0)
         return null;
-    return [...all]
-        .sort((a, b) => a.alias.localeCompare(b.alias))
+    return orderCodexSeats(all)
         .find((c) => !tried.has(c.alias) && !codexCooldowns.isCooled(c.alias)) ?? null;
 }
 /** Every seat is cooling — the fail-fast condition, for the caller's message. */

package/dist/codex-backend.d.ts

@@ -5,6 +5,12 @@ import { type ModelResolver, type ClaudeTarget } from './claude-model.js';
 import { type EffortValue } from './effort.js';
 import type { MidstreamGuard } from './midstream.js';
 export declare const CODEX_BACKEND_BASE_URL: string;
+/** The usage endpoint the Codex CLI's /status reads, beside the Responses base. */
+export declare const CODEX_USAGE_URL: string;
+/** Read a seat's utilisation without a model call. Never refreshes the token; false on any failure. */
+export declare function seedCodexUsage(creds: CodexAccountCredentials, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<boolean>;
+/** Seed every seat that has no reading, or one older than `maxAgeMs`. Returns the aliases read. */
+export declare function seedStaleCodexUsage(seats: readonly CodexAccountCredentials[], maxAgeMs: number, now?: number, fetchImpl?: typeof fetch): Promise<string[]>;
 /**
  * Client version sent on the model-discovery call. The backend REQUIRES the
  * `client_version` query parameter and rejects the request without it; the

package/dist/codex-backend.js

@@ -29,7 +29,43 @@ 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 { 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. */
+export const CODEX_USAGE_URL = process.env.DARIO_CODEX_USAGE_URL || `${CODEX_BACKEND_BASE_URL.replace(/\/+$/, '').replace(/\/codex$/, '')}/wham/usage`;
+/** Read a seat's utilisation without a model call. Never refreshes the token; false on any failure. */
+export async function seedCodexUsage(creds, fetchImpl = fetch, timeoutMs = 5000) {
+    // A real access token is a JWT; anything else would 401 (and keeps test placeholders off the network).
+    if (typeof creds.accessToken !== 'string' || creds.accessToken.split('.').length !== 3)
+        return false;
+    try {
+        const headers = { ...buildCodexHeaders(creds), Accept: 'application/json' };
+        delete headers['Content-Type'];
+        delete headers['OpenAI-Beta'];
+        const res = await fetchImpl(CODEX_USAGE_URL, { method: 'GET', headers, signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) {
+            await res.text().catch(() => '');
+            return false;
+        }
+        const usage = parseCodexUsageEndpoint(await res.json(), Date.now());
+        if (!usage)
+            return false;
+        recordCodexUsage(creds.alias, usage);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Seed every seat that has no reading, or one older than `maxAgeMs`. Returns the aliases read. */
+export async function seedStaleCodexUsage(seats, maxAgeMs, now = Date.now(), fetchImpl = fetch) {
+    const stale = seats.filter((s) => {
+        const u = codexUsageFor(s.alias);
+        return !u || now - u.observedAt > maxAgeMs;
+    });
+    const results = await Promise.all(stale.map(async (s) => ((await seedCodexUsage(s, fetchImpl)) ? s.alias : null)));
+    return results.filter((a) => a !== null);
+}
 /** Originator string the codex CLI identifies itself with. */
 const CODEX_ORIGINATOR = 'codex_cli_rs';
 /**
@@ -830,6 +866,11 @@ timing) {
             fetchStartedAt = Date.now();
         const r = await fetchImpl(input, init);
         upstreamHeadersAt = Date.now();
+        // Every answer, 429s included, carries the seat's utilisation.
+        try {
+            noteCodexUsageHeaders(creds.alias, r.headers, upstreamHeadersAt);
+        }
+        catch { /* best-effort */ }
         return r;
     };
     const ttfbMs = () => (fetchStartedAt && upstreamHeadersAt ? Math.max(0, upstreamHeadersAt - fetchStartedAt) : 0);
@@ -1057,6 +1098,11 @@ timing) {
             fetchStartedAt = Date.now();
         const r = await fetchImpl(input, init);
         upstreamHeadersAt = Date.now();
+        // Every answer, 429s included, carries the seat's utilisation.
+        try {
+            noteCodexUsageHeaders(creds.alias, r.headers, upstreamHeadersAt);
+        }
+        catch { /* best-effort */ }
         return r;
     };
     const ttfbMs = () => (fetchStartedAt && upstreamHeadersAt ? Math.max(0, upstreamHeadersAt - fetchStartedAt) : 0);

package/dist/codex-usage.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ChatGPT-seat utilisation, the Codex twin of the Claude pool's unified
+ * rate-limit readings. Every Responses answer carries
+ * `x-codex-{primary,secondary}-{used-percent,window-minutes,reset-at}` (reset
+ * in unix seconds; the family codex-rs/codex-api/src/rate_limits.rs parses),
+ * and `/backend-api/wham/usage` answers the same without a model call.
+ * Window shapes vary by plan (prolite: one weekly window), so nothing assumes
+ * which slot is which. Pure and memory-only, so codex-accounts and
+ * codex-backend can both import it without a cycle.
+ */
+export interface CodexUsageWindow {
+    /** As reported, 0–100. */
+    usedPercent: number;
+    /** Window length, when the backend states it. */
+    windowMinutes: number | null;
+    /** When the window rolls over, epoch ms. */
+    resetAt: number | null;
+}
+export interface CodexUsage {
+    primary: CodexUsageWindow | null;
+    secondary: CodexUsageWindow | null;
+    /** The backend's own "you are at the limit" flag: a reached-type header, or `limit_reached` on the usage endpoint. */
+    limitReached: string | null;
+    observedAt: number;
+    source: 'headers' | 'usage-endpoint';
+}
+/** Anything with a `get(name)` — a fetch `Headers`, or a stub in tests. */
+export interface HeaderReader {
+    get(name: string): string | null;
+}
+/**
+ * Read the default (`codex`) rate-limit header family off a backend response.
+ * Null when the response carries no usage at all (an error body from a proxy
+ * in front, a stub), so a header-less response never erases a real reading.
+ */
+export declare function parseCodexUsageHeaders(h: HeaderReader, now?: number): CodexUsage | null;
+/** Read a `GET /backend-api/wham/usage` body. Null when it carries no window. */
+export declare function parseCodexUsageEndpoint(body: unknown, now?: number): CodexUsage | null;
+/** How often an IDLE seat is re-read from /wham/usage. A seat that is serving is read from every answer and never polled. */
+export declare const DEFAULT_CODEX_USAGE_POLL_MS: number;
+/** `DARIO_CODEX_USAGE_POLL_MS`: unset/garbage → default, `0` → off, anything else floored at one minute. */
+export declare function resolveCodexUsagePollMs(raw: string | undefined): number;
+/** Record a reading for a seat. A newer reading replaces an older one; an older one never replaces a newer one. */
+export declare function recordCodexUsage(alias: string, usage: CodexUsage): void;
+/** The response hook: parse and record in one call; a header-less response changes nothing. */
+export declare function noteCodexUsageHeaders(alias: string, h: HeaderReader, now?: number): void;
+export declare function codexUsageFor(alias: string): CodexUsage | null;
+/** Test seam. */
+export declare function _resetCodexUsageForTest(): void;
+/**
+ * Fraction of the tightest window still available, 0–1; null when the seat
+ * has no reading. A reached-limit flag reads as 0 until every window it could
+ * refer to has rolled.
+ */
+export declare function codexHeadroom(alias: string, now?: number): number | null;
+/**
+ * When the seat's LONGEST window rolls over, epoch ms, if it is still ahead —
+ * the codex mirror of the Claude pool's 7-day reset, for `expiring-first`.
+ */
+export declare function codexLongWindowResetAt(alias: string, now?: number): number | null;
+/** The JSON shape surfaces print: numbers plus ISO times, never a credential. */
+export interface CodexUsageView {
+    headroom: number | null;
+    limitReached: string | null;
+    source: CodexUsage['source'];
+    observedAt: string;
+    windows: Array<{
+        slot: 'primary' | 'secondary';
+        usedPercent: number;
+        windowMinutes: number | null;
+        resetAt: string | null;
+    }>;
+}
+export declare function codexUsageView(alias: string, now?: number): CodexUsageView | null;
+/** "6% of 7d, resets in 6d 22h" — one window, human-sized. */
+export declare function describeCodexWindow(w: {
+    usedPercent: number;
+    windowMinutes: number | null;
+    resetAt: string | number | null;
+}, now?: number): string;

package/dist/codex-usage.js

@@ -0,0 +1,179 @@
+/**
+ * ChatGPT-seat utilisation, the Codex twin of the Claude pool's unified
+ * rate-limit readings. Every Responses answer carries
+ * `x-codex-{primary,secondary}-{used-percent,window-minutes,reset-at}` (reset
+ * in unix seconds; the family codex-rs/codex-api/src/rate_limits.rs parses),
+ * and `/backend-api/wham/usage` answers the same without a model call.
+ * Window shapes vary by plan (prolite: one weekly window), so nothing assumes
+ * which slot is which. Pure and memory-only, so codex-accounts and
+ * codex-backend can both import it without a cycle.
+ */
+function finite(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return null;
+    const n = typeof raw === 'number' ? raw : Number(String(raw).trim());
+    return Number.isFinite(n) ? n : null;
+}
+/** Unix seconds → epoch ms. A value already in ms (> ~2286 in seconds) passes through. */
+function toMs(raw) {
+    const n = finite(raw);
+    if (n === null)
+        return null;
+    return n > 1e12 ? n : n * 1000;
+}
+function headerWindow(h, prefix) {
+    const used = finite(h.get(`${prefix}-used-percent`));
+    if (used === null)
+        return null;
+    const windowMinutes = finite(h.get(`${prefix}-window-minutes`));
+    // A one-window plan sends the unused slot zeroed with an empty reset: no window, not 0%.
+    if (windowMinutes !== null && windowMinutes <= 0)
+        return null;
+    return { usedPercent: used, windowMinutes, resetAt: toMs(h.get(`${prefix}-reset-at`)) };
+}
+/**
+ * Read the default (`codex`) rate-limit header family off a backend response.
+ * Null when the response carries no usage at all (an error body from a proxy
+ * in front, a stub), so a header-less response never erases a real reading.
+ */
+export function parseCodexUsageHeaders(h, now = Date.now()) {
+    const primary = headerWindow(h, 'x-codex-primary');
+    const secondary = headerWindow(h, 'x-codex-secondary');
+    if (!primary && !secondary)
+        return null;
+    const reached = h.get('x-codex-rate-limit-reached-type');
+    return { primary, secondary, limitReached: reached && reached.trim() ? reached.trim() : null, observedAt: now, source: 'headers' };
+}
+function endpointWindow(w, now) {
+    if (!w || typeof w !== 'object')
+        return null;
+    const used = finite(w.used_percent);
+    if (used === null)
+        return null;
+    const secs = finite(w.limit_window_seconds);
+    let resetAt = toMs(w.reset_at);
+    if (resetAt === null) {
+        const after = finite(w.reset_after_seconds);
+        if (after !== null)
+            resetAt = now + after * 1000;
+    }
+    return { usedPercent: used, windowMinutes: secs === null ? null : Math.round(secs / 60), resetAt };
+}
+/** Read a `GET /backend-api/wham/usage` body. Null when it carries no window. */
+export function parseCodexUsageEndpoint(body, now = Date.now()) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    const rl = b.rate_limit;
+    if (!rl || typeof rl !== 'object')
+        return null;
+    const primary = endpointWindow(rl.primary_window, now);
+    const secondary = endpointWindow(rl.secondary_window, now);
+    if (!primary && !secondary)
+        return null;
+    const type = typeof b.rate_limit_reached_type === 'string' && b.rate_limit_reached_type ? b.rate_limit_reached_type : null;
+    const limitReached = type ?? (rl.limit_reached === true ? 'limit_reached' : null);
+    return { primary, secondary, limitReached, observedAt: now, source: 'usage-endpoint' };
+}
+/** How often an IDLE seat is re-read from /wham/usage. A seat that is serving is read from every answer and never polled. */
+export const DEFAULT_CODEX_USAGE_POLL_MS = 30 * 60 * 1000;
+/** `DARIO_CODEX_USAGE_POLL_MS`: unset/garbage → default, `0` → off, anything else floored at one minute. */
+export function resolveCodexUsagePollMs(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_CODEX_USAGE_POLL_MS;
+    const n = Number(raw.trim());
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_CODEX_USAGE_POLL_MS;
+    if (n === 0)
+        return 0;
+    return Math.max(60_000, Math.round(n));
+}
+const readings = new Map();
+/** Record a reading for a seat. A newer reading replaces an older one; an older one never replaces a newer one. */
+export function recordCodexUsage(alias, usage) {
+    const prev = readings.get(alias);
+    if (prev && prev.observedAt > usage.observedAt)
+        return;
+    readings.set(alias, usage);
+}
+/** The response hook: parse and record in one call; a header-less response changes nothing. */
+export function noteCodexUsageHeaders(alias, h, now = Date.now()) {
+    const u = parseCodexUsageHeaders(h, now);
+    if (u)
+        recordCodexUsage(alias, u);
+}
+export function codexUsageFor(alias) {
+    return readings.get(alias) ?? null;
+}
+/** Test seam. */
+export function _resetCodexUsageForTest() {
+    readings.clear();
+}
+/** A window whose reset time has passed has rolled over: it counts as empty until the next reading says otherwise. */
+function effectiveUsed(w, now) {
+    if (!w)
+        return null;
+    if (w.resetAt !== null && w.resetAt <= now)
+        return 0;
+    return Math.min(100, Math.max(0, w.usedPercent));
+}
+/**
+ * Fraction of the tightest window still available, 0–1; null when the seat
+ * has no reading. A reached-limit flag reads as 0 until every window it could
+ * refer to has rolled.
+ */
+export function codexHeadroom(alias, now = Date.now()) {
+    const u = readings.get(alias);
+    if (!u)
+        return null;
+    const used = [effectiveUsed(u.primary, now), effectiveUsed(u.secondary, now)].filter((x) => x !== null);
+    if (used.length === 0)
+        return null;
+    const rolled = [u.primary, u.secondary].every((w) => !w || (w.resetAt !== null && w.resetAt <= now));
+    if (u.limitReached && !rolled)
+        return 0;
+    return (100 - Math.max(...used)) / 100;
+}
+/**
+ * When the seat's LONGEST window rolls over, epoch ms, if it is still ahead —
+ * the codex mirror of the Claude pool's 7-day reset, for `expiring-first`.
+ */
+export function codexLongWindowResetAt(alias, now = Date.now()) {
+    const u = readings.get(alias);
+    if (!u)
+        return null;
+    const windows = [u.primary, u.secondary].filter((w) => w !== null);
+    if (windows.length === 0)
+        return null;
+    const longest = windows.reduce((a, b) => ((b.windowMinutes ?? 0) > (a.windowMinutes ?? 0) ? b : a));
+    return longest.resetAt !== null && longest.resetAt > now ? longest.resetAt : null;
+}
+export function codexUsageView(alias, now = Date.now()) {
+    const u = readings.get(alias);
+    if (!u)
+        return null;
+    const windows = [];
+    for (const slot of ['primary', 'secondary']) {
+        const w = u[slot];
+        if (w)
+            windows.push({ slot, usedPercent: w.usedPercent, windowMinutes: w.windowMinutes, resetAt: w.resetAt === null ? null : new Date(w.resetAt).toISOString() });
+    }
+    return { headroom: codexHeadroom(alias, now), limitReached: u.limitReached, source: u.source, observedAt: new Date(u.observedAt).toISOString(), windows };
+}
+/** "6% of 7d, resets in 6d 22h" — one window, human-sized. */
+export function describeCodexWindow(w, now = Date.now()) {
+    const mins = w.windowMinutes;
+    const span = mins === null ? 'window' : mins >= 1440 ? `${Math.round(mins / 1440)}d` : mins >= 60 ? `${Math.round(mins / 60)}h` : `${mins}m`;
+    const resetMs = w.resetAt === null ? null : typeof w.resetAt === 'number' ? w.resetAt : Date.parse(w.resetAt);
+    let reset = '';
+    if (resetMs !== null && Number.isFinite(resetMs)) {
+        const left = resetMs - now;
+        if (left <= 0)
+            reset = ', rolled over';
+        else {
+            const h = Math.floor(left / 3_600_000);
+            reset = h >= 24 ? `, resets in ${Math.floor(h / 24)}d ${h % 24}h` : `, resets in ${h}h ${Math.floor((left % 3_600_000) / 60_000)}m`;
+        }
+    }
+    return `${Math.round(w.usedPercent)}% of ${span}${reset}`;
+}

package/dist/proxy.js

@@ -48,7 +48,9 @@ import { responsesRequestToAnthropic, unsupportedOnClaudeError, ResponsesRequest
 import { isClaudeServableModel } from './claude-model.js';
 import { MODEL_UNROUTABLE } from './upstream-rejection.js';
 import { readCompareTarget, teeResponse, runCompare, writeCompareRecord, COMPARE_RESULT_HEADER } from './compare.js';
-import { listCodexAccountAliases, loadAllCodexAccounts, codexAccountNeedsRefresh, hasAnyCodexAccount, selectCodexAccount, selectCodexAccountExcluding, rebindCodexSticky, getFreshCodexAccount, noteCodexDecline, clearCodexDecline, allAliasesCooled, CodexCredentialsUnavailableError, resetCodexPresenceCache, codexSeatStatus, } from './codex-accounts.js';
+import { listCodexAccountAliases, loadAllCodexAccounts, codexAccountNeedsRefresh, hasAnyCodexAccount, selectCodexAccount, selectCodexAccountExcluding, rebindCodexSticky, getFreshCodexAccount, noteCodexDecline, clearCodexDecline, allAliasesCooled, CodexCredentialsUnavailableError, resetCodexPresenceCache, codexSeatStatus, setCodexRouting, } from './codex-accounts.js';
+import { codexUsageView, resolveCodexUsagePollMs } from './codex-usage.js';
+import { seedStaleCodexUsage } from './codex-backend.js';
 import { route as routeProvider } from './provider-adapter.js';
 import { selectPoolFallbackModels } from './pool-fallback-tier.js';
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS, resolveMaxConcurrent } from './request-queue.js';
@@ -1524,6 +1526,24 @@ export async function startProxy(opts = {}) {
     // Always named, the default included: a deployment that overrides the
     // default should be visible at a glance, and one that does not should say so.
     console.log(`  Pool strategy: ${describePoolStrategy(poolStrategy, pool.headroomFloor)}`);
+    // ChatGPT seats: same strategy and floor. Idle seats are read from
+    // /wham/usage (no model call) at most once per DARIO_CODEX_USAGE_POLL_MS.
+    setCodexRouting({ strategy: poolStrategy, floor: pool.headroomFloor });
+    const codexUsagePollMs = resolveCodexUsagePollMs(process.env['DARIO_CODEX_USAGE_POLL_MS']);
+    let codexUsageTimer = null;
+    if (codexUsagePollMs > 0) {
+        const readIdleCodexSeats = async () => {
+            try {
+                const seats = (await loadAllCodexAccounts()).filter((a) => !codexAccountNeedsRefresh(a));
+                if (seats.length > 0)
+                    await seedStaleCodexUsage(seats, codexUsagePollMs);
+            }
+            catch { /* best-effort: selection falls back to header readings */ }
+        };
+        void readIdleCodexSeats();
+        codexUsageTimer = setInterval(() => { void readIdleCodexSeats(); }, codexUsagePollMs);
+        codexUsageTimer.unref?.();
+    }
     if (poolSync) {
         console.log(`  Pool shared state: on (instance ${poolSync.instance}, via ${lockUrl}, pulling peers every ${poolSync.intervalMs}ms; fails open)`);
         poolSync.start();
@@ -2806,6 +2826,7 @@ export async function startProxy(opts = {}) {
                 // for a minute (DEV-179a412f). Read from memory only — a status read
                 // never spends or exposes a credential, so there is no token in any of it.
                 ...codexSeatStatus(a.alias),
+                usage: codexUsageView(a.alias, now),
             }));
             res.writeHead(200, JSON_HEADERS);
             res.end(JSON.stringify({
@@ -5785,6 +5806,8 @@ export async function startProxy(opts = {}) {
             }
         }
     });
+    server.on('close', () => { if (codexUsageTimer)
+        clearInterval(codexUsageTimer); });
     server.on('error', async (err) => {
         if (err.code === 'EADDRINUSE') {
             // Before erroring, check whether dario itself is already running on this

package/docs/admin-api.md

@@ -267,7 +267,7 @@ The same flow for a ChatGPT Plus/Pro seat, for a proxy that never sees a termina
 |---|---|---|
 | `POST /admin/codex/login/start` | `{ "alias"?: string }` | `{ alias, authorize_url, expires_at, instructions }` — default alias `altman-1`, `altman-2`, … ; `409` if the alias already holds a seat |
 | `POST /admin/codex/login/complete` | `{ "alias": string, "code": string }` — the redirect URL, or the bare code | `{ alias, status: "added", expires_at }` |
-| `GET /admin/codex/accounts` | — | `{ accounts: [{ alias, expiresAt, needsRefresh }], count }` |
+| `GET /admin/codex/accounts` | — | `{ accounts: [{ alias, expiresAt, needsRefresh, status, cooldownRemainingMs, lastRefreshError, usage }], count }`. `usage` is the seat's latest utilisation (`headroom` 0–1, `windows[]` with `usedPercent`, `windowMinutes`, `resetAt`, and `source`: `headers` or `usage-endpoint`), or `null` before its first answer or read |
 | `DELETE /admin/codex/accounts/<alias>` | — | `{ alias, removed }` (`404` if no such alias) |
 
 A running proxy serves the new seat on its next request; nothing restarts. Same token, same rate limits, same audit log — codex events carry `engine: "codex"`. The seat is stored where the CLI stores it (`~/.dario/codex-accounts/<alias>.json`), so `dario codex list` and `dario codex remove` see it too.

package/docs/cli-and-endpoints.md

@@ -22,7 +22,7 @@
 | `GET /health` · `GET /livez` | Serviceability (503 when not) · liveness. `/health?probe=1` sends one real request |
 | `GET /status` · `GET /accounts` · `GET /analytics` | OAuth detail · per-seat utilization and grant age · per-account / per-model stats and burn rate |
 | `POST /v1/messages/count_tokens` · `POST /v1/complete` | Token counting and the legacy Text Completions shape |
-| `GET /analytics/stream` · `GET /analytics/ledger` · `GET /codex` | Live analytics over SSE · the ledger's per-day table · ChatGPT-seat status, read without spending or exposing a token |
+| `GET /analytics/stream` · `GET /analytics/ledger` · `GET /codex` | Live analytics over SSE · the ledger's per-day table · ChatGPT-seat status and utilisation (used %, window, reset, headroom), read without spending or exposing a token |
 | `/admin/*` | Provisioning, `GET /admin/accounts`, `/admin/keys`, `POST /admin/resume`; only with `DARIO_ADMIN=1` ([admin API](admin-api.md)) |
 
 Flags: [commands.md](commands.md), plus `dario --help` for the ones it doesn't list yet (`--effort`, `--max-tokens`, `--model-alias`, `--fast-model`, session rotation, concurrency caps, the pacing knobs behind `--stealth`) · env vars grouped by task, for Docker / k8s / systemd: [configuration.md](configuration.md) · SDK examples: [usage.md](usage.md).

package/docs/configuration.md

@@ -50,6 +50,13 @@ Halts the proxy when an upstream response reports `representative-claim: overage
 | `DARIO_KEYS` | `--no-keys` | on | `0` ignores `~/.dario/keys.json`: only `DARIO_API_KEY` authenticates. See [Named keys](./keys.md) |
 | `DARIO_KEYS_PATH` | `--keys-path=<file>` | `~/.dario/keys.json` | where the key hashes live; `dario keys` and the running proxy read the same file |
 
+## ChatGPT seats
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `DARIO_CODEX_USAGE_POLL_MS` | — | `1800000` (30 min) | how stale a ChatGPT seat's utilisation reading may get before the proxy re-reads it from `/backend-api/wham/usage` (no model call). A seat that is serving is read from every answer and never polled; boot reads each seat once. `0` turns the reads off and leaves only the per-answer headers. Floored at one minute |
+| `DARIO_CODEX_USAGE_URL` | — | derived from `DARIO_CODEX_BASE_URL` | the usage endpoint; `…/backend-api/wham/usage` beside the Responses base |
+
 ## Multi-instance
 
 | Variable | Flag | Default | Notes |

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

@@ -21,6 +21,20 @@ Three things it does that a round-robin doesn't:
 
 <img src="../.github/readme/pool.jpg" alt="Three pooled seats, work, personal and side, each with a headroom bar. dario routes the request to the seat with the most headroom." width="100%">
 
+## ChatGPT seats
+
+ChatGPT plans added with `dario codex add <alias>` pool the same way. The Codex backend states a seat's utilisation on every answer (`x-codex-primary-used-percent`, `-window-minutes`, `-reset-at`, and the same for the secondary window: the family the Codex CLI itself parses), so dario reads it off each response and places new conversations by the same `--pool-strategy` and floor as the Claude pool. A seat nothing has asked yet is read once from `/backend-api/wham/usage`, which spends no model call, and an idle seat is re-read at most every `DARIO_CODEX_USAGE_POLL_MS` (30 min). A conversation stays on the seat it started on, because the Codex prompt cache is scoped to the serving account; a seat that declines is cooled and skipped whatever its last reading said, and the request fails over mid-flight. Which windows a seat has depends on the plan: a Plus or Pro seat carries a short window and a weekly one, a Pro Lite seat a single weekly window.
+
+`dario codex list --live` and `GET /codex` show each seat's used %, window and reset time, and its headroom:
+
+```
+    fleet                ok
+                         token expires in 5523m, 214 requests served
+                         usage: 6% of 7d, resets in 6d 22h — 94% headroom (from its last answer)
+```
+
+Earlier releases placed ChatGPT conversations fill-first in alias order with cool-down eviction only, on the belief that the backend reported nothing before a 429, so a second seat served nothing until the first one declined.
+
 `--pool-strategy=fill-first` concentrates new conversations on one seat until it drains, for primary/backup setups; `--pool-strategy=expiring-first` fills in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. `--pool-headroom-floor=5%` (env `DARIO_POOL_HEADROOM_FLOOR`, config `pool.headroomFloor`; default 2%) moves the line at which a seat counts as drained: a sticky session rebinds off it and new conversations skip it once its headroom is at or below the floor, so a seat that answers with API errors in its last percent is left alone before the 429, not at it. Refresh tokens expire about 28 days after the original grant regardless of rotation, so every seat's grant age is tracked and surfaced in `dario accounts list`, `dario doctor` and `GET /accounts` before it becomes a silent outage. Provision over HTTP with the headless [admin API](admin-api.md); pin one request to one seat with `dario accounts check <alias>` (admin API required: `DARIO_ADMIN=1` and a `DARIO_ADMIN_TOKEN`). Internals and the live `/accounts` + `/analytics` endpoints: [multi-account-pool.md](multi-account-pool.md); covered end-to-end by [`test/pool-e2e.mjs`](../test/pool-e2e.mjs).
 
 ## One key per developer

package/package.json

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