@askalf/dario 6.17.2 → 6.18.1

package/dist/analytics.d.ts

@@ -55,6 +55,23 @@ export interface RequestRecord {
      * reached an upstream.
      */
     timing?: RequestTiming;
+    /**
+     * What a Codex request shared with the previous one on its cache key
+     * (src/cache-trace.ts): the gap, whether the input extends the previous
+     * one, and whether the seat or the prefix changed. Absent off that path.
+     */
+    cache?: RequestCacheTrace;
+}
+export interface RequestCacheTrace {
+    /** The `prompt_cache_key` the request went out under: dario's derived key as is, a caller's own key as a digest. */
+    key: string;
+    items: number;
+    sinceMs: number | null;
+    prevItems: number | null;
+    extends: boolean | null;
+    divergedAt: number | null;
+    seatChanged: boolean | null;
+    prefixChanged: boolean | null;
 }
 export interface RequestContinuation {
     /** See midstream.ts ContinuationOutcome. */

package/dist/cache-trace.d.ts

@@ -0,0 +1,106 @@
+/** One input item, as a short digest of its JSON form. */
+export declare function itemHash(item: unknown): string;
+/**
+ * The key as the trace records it. A key dario derived itself
+ * (codexPromptCacheKey) is already a digest and is kept as it went out, so a
+ * trace matches the request; a caller-supplied key can be anything (a session
+ * id, an email, a secret that happens to look like a derived key) and is
+ * recorded only as a digest, stable per key so a run of traces still groups
+ * by conversation. Only the caller knows which it is, so the shape of the key
+ * decides nothing.
+ */
+export declare function traceKey(key: string, derived: boolean): string;
+/**
+ * The stable front of a request: model, instructions and tool names, as a
+ * short digest. The same material the derived cache key hashes, kept
+ * separately so a changed system prompt between two turns of one
+ * conversation shows up as such.
+ */
+export declare function prefixHash(body: {
+    model?: unknown;
+    instructions?: unknown;
+    tools?: unknown;
+}): string;
+export interface CacheTraceInput {
+    /** The `prompt_cache_key` the request goes out with. */
+    key: string;
+    /** The seat that serves it. */
+    alias: string;
+    /** `prefixHash()` of the outgoing body. */
+    prefix: string;
+    /** `itemHash()` of every input item, in order. */
+    items: readonly string[];
+    /** When it goes out, ms since the epoch. */
+    at: number;
+    /**
+     * Dispatch order, stamped by `peek()` when absent, so two requests that
+     * went out in the same ms still order by which went out first.
+     */
+    seq?: number;
+}
+export interface CacheTraceResult {
+    /** Input items in this request. */
+    items: number;
+    /** ms since the previous request on this key; null on the first. */
+    sinceMs: number | null;
+    /** Input items in the previous request on this key; null on the first. */
+    prevItems: number | null;
+    /**
+     * The previous request's input is a strict prefix of this one: every item
+     * equal, this one longer. The shape a cache hit needs. null on the first,
+     * and when this one is longer but the previous input ran past
+     * CACHE_TRACE_MAX_ITEMS, so its tail was not kept to compare.
+     */
+    extends: boolean | null;
+    /**
+     * Index of the first input item that differs from the previous request,
+     * when one does. null when the inputs agree as far as both go (the new one
+     * extends, equals or shortens the old one) and on the first request.
+     */
+    divergedAt: number | null;
+    /** The seat differs from the previous request's; null on the first. */
+    seatChanged: boolean | null;
+    /** Model, instructions or tool names differ from the previous request's; null on the first. */
+    prefixChanged: boolean | null;
+}
+export declare const CACHE_TRACE_MAX_KEYS = 1000;
+/** Longer than the backend keeps a prefix, so a stale entry cannot look like a live conversation. */
+export declare const CACHE_TRACE_TTL_MS: number;
+/** Items remembered per key. A longer input is compared on its first this many items and its length. */
+export declare const CACHE_TRACE_MAX_ITEMS = 2000;
+export declare class CacheTrace {
+    private readonly seen;
+    private readonly maxKeys;
+    private readonly ttlMs;
+    private readonly now;
+    private dispatched;
+    constructor(opts?: {
+        maxKeys?: number;
+        ttlMs?: number;
+        now?: () => number;
+    });
+    /** Compare a request with the previous one on its key, then remember it. */
+    note(input: CacheTraceInput): CacheTraceResult;
+    /** Compare a request with the previous one on its key, remembering nothing but its dispatch order. */
+    peek(input: CacheTraceInput): CacheTraceResult;
+    /**
+     * Make a request the one the next request on its key compares with, unless
+     * one that went out after it is already remembered: concurrent requests are
+     * accepted in whatever order their upstream headers arrive, and the next
+     * request compares with the latest to go out.
+     */
+    remember(input: CacheTraceInput): void;
+    /** Keys remembered right now. */
+    size(): number;
+    /**
+     * Drop every expired entry, then, while over the cap, the entry that went
+     * out earliest. By `at` rather than Map order: a request accepted late can
+     * be older than entries inserted before it.
+     */
+    private sweep;
+}
+/** The one-line trace for stdout: `key=... since=3.2s items=23 extends=yes read=0/44120 (0%)`. `key` is the `traceKey()` form. */
+export declare function formatCacheTraceLine(requestCount: number, key: string, t: CacheTraceResult, usage: {
+    inputTokens: number;
+    cacheReadTokens: number;
+}, alias?: string): string;

package/dist/cache-trace.js

@@ -0,0 +1,176 @@
+/**
+ * Cache trace: what a Codex request shares with the previous request on the
+ * same `prompt_cache_key`.
+ *
+ * The backend caches prompt prefixes and reports what it read back as
+ * `cached_tokens`, and dario already records that number. What the number
+ * cannot say is WHY a turn missed. The trace records three things that bear
+ * on a hit and are visible to dario before the request goes out. They narrow
+ * the cause down; they do not prove it:
+ *
+ *   1. time: a cache write is not readable at once, so a turn that follows
+ *      the previous one closely may read nothing it wrote. The gap is
+ *      measured here; when the backend's write became readable is not;
+ *   2. shape: a hit needs the previous input to be a strict prefix of this
+ *      one, item for item, with the same front in place. `extends` compares
+ *      the input items only; the model, instructions and tool names are
+ *      compared apart as `prefixChanged`, and tool schemas not at all;
+ *   3. seat: the cache is scoped to the serving account, so a conversation
+ *      that moved seats starts over.
+ *
+ * `note()` answers all three for a request and remembers it for the next one.
+ * `peek()` and `remember()` are its two halves, for a caller that only knows
+ * after the comparison whether the request was served. It keeps hashes only:
+ * no content, no token counts. Pure except for the map it keeps, with an
+ * injectable clock so the tests need no sleeping.
+ */
+import { createHash } from 'node:crypto';
+/** One input item, as a short digest of its JSON form. */
+export function itemHash(item) {
+    return createHash('sha256').update(JSON.stringify(item) ?? 'undefined').digest('hex').slice(0, 12);
+}
+/**
+ * The key as the trace records it. A key dario derived itself
+ * (codexPromptCacheKey) is already a digest and is kept as it went out, so a
+ * trace matches the request; a caller-supplied key can be anything (a session
+ * id, an email, a secret that happens to look like a derived key) and is
+ * recorded only as a digest, stable per key so a run of traces still groups
+ * by conversation. Only the caller knows which it is, so the shape of the key
+ * decides nothing.
+ */
+export function traceKey(key, derived) {
+    if (derived)
+        return key;
+    return `key-${createHash('sha256').update('trace\0').update(key).digest('hex').slice(0, 16)}`;
+}
+/**
+ * The stable front of a request: model, instructions and tool names, as a
+ * short digest. The same material the derived cache key hashes, kept
+ * separately so a changed system prompt between two turns of one
+ * conversation shows up as such.
+ */
+export function prefixHash(body) {
+    const h = createHash('sha256');
+    h.update(String(body.model ?? '')).update('\0');
+    h.update(typeof body.instructions === 'string' ? body.instructions : '').update('\0');
+    const tools = Array.isArray(body.tools) ? body.tools : [];
+    for (const t of tools)
+        h.update(typeof t?.name === 'string' ? t.name : String(t?.type ?? '')).update('\0');
+    return h.digest('hex').slice(0, 12);
+}
+export const CACHE_TRACE_MAX_KEYS = 1000;
+/** Longer than the backend keeps a prefix, so a stale entry cannot look like a live conversation. */
+export const CACHE_TRACE_TTL_MS = 60 * 60 * 1000;
+/** Items remembered per key. A longer input is compared on its first this many items and its length. */
+export const CACHE_TRACE_MAX_ITEMS = 2000;
+export class CacheTrace {
+    seen = new Map();
+    maxKeys;
+    ttlMs;
+    now;
+    dispatched = 0;
+    constructor(opts = {}) {
+        this.maxKeys = opts.maxKeys ?? CACHE_TRACE_MAX_KEYS;
+        this.ttlMs = opts.ttlMs ?? CACHE_TRACE_TTL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Compare a request with the previous one on its key, then remember it. */
+    note(input) {
+        const result = this.peek(input);
+        this.remember(input);
+        return result;
+    }
+    /** Compare a request with the previous one on its key, remembering nothing but its dispatch order. */
+    peek(input) {
+        if (input.seq === undefined)
+            input.seq = ++this.dispatched;
+        const prev = this.seen.get(input.key);
+        const live = prev !== undefined && input.at - prev.at <= this.ttlMs;
+        return live
+            ? {
+                items: input.items.length,
+                sinceMs: Math.max(0, input.at - prev.at),
+                prevItems: prev.count,
+                ...compare(prev, kept(input.items), input.items.length),
+                seatChanged: prev.alias !== input.alias,
+                prefixChanged: prev.prefix !== input.prefix,
+            }
+            : { items: input.items.length, sinceMs: null, prevItems: null, extends: null, divergedAt: null, seatChanged: null, prefixChanged: null };
+    }
+    /**
+     * Make a request the one the next request on its key compares with, unless
+     * one that went out after it is already remembered: concurrent requests are
+     * accepted in whatever order their upstream headers arrive, and the next
+     * request compares with the latest to go out.
+     */
+    remember(input) {
+        const seq = input.seq ?? 0;
+        const prev = this.seen.get(input.key);
+        if (prev !== undefined && (prev.at > input.at || (prev.at === input.at && prev.seq > seq)))
+            return;
+        this.seen.delete(input.key);
+        this.seen.set(input.key, { alias: input.alias, prefix: input.prefix, items: kept(input.items), count: input.items.length, at: input.at, seq });
+        this.sweep(input.at);
+    }
+    /** Keys remembered right now. */
+    size() {
+        return this.seen.size;
+    }
+    /**
+     * Drop every expired entry, then, while over the cap, the entry that went
+     * out earliest. By `at` rather than Map order: a request accepted late can
+     * be older than entries inserted before it.
+     */
+    sweep(at) {
+        for (const [key, r] of this.seen) {
+            if (at - r.at > this.ttlMs)
+                this.seen.delete(key);
+        }
+        while (this.seen.size > this.maxKeys) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [key, r] of this.seen)
+                if (r.at < oldestAt) {
+                    oldest = key;
+                    oldestAt = r.at;
+                }
+            if (oldest === undefined)
+                break;
+            this.seen.delete(oldest);
+        }
+    }
+}
+function kept(items) {
+    return items.length > CACHE_TRACE_MAX_ITEMS ? items.slice(0, CACHE_TRACE_MAX_ITEMS) : items;
+}
+function compare(prev, cur, curCount) {
+    const shared = Math.min(prev.items.length, cur.length);
+    for (let i = 0; i < shared; i++) {
+        if (prev.items[i] !== cur[i])
+            return { extends: false, divergedAt: i };
+    }
+    if (curCount <= prev.count)
+        return { extends: false, divergedAt: null };
+    // Longer than the previous input and equal as far as it was kept; past
+    // that, nothing was kept to say whether it still agrees.
+    return { extends: prev.items.length < prev.count ? null : true, divergedAt: null };
+}
+/** The one-line trace for stdout: `key=... since=3.2s items=23 extends=yes read=0/44120 (0%)`. `key` is the `traceKey()` form. */
+export function formatCacheTraceLine(requestCount, key, t, usage, alias) {
+    const prompt = usage.inputTokens + usage.cacheReadTokens;
+    const pct = prompt > 0 ? Math.round((usage.cacheReadTokens / prompt) * 100) : 0;
+    const yesNo = (v) => (v === null ? '-' : v ? 'yes' : 'no');
+    const since = t.sinceMs === null ? 'first' : `${(t.sinceMs / 1000).toFixed(1)}s`;
+    const parts = [
+        `key=${key.slice(0, 16)}`,
+        alias ? `seat=${alias}` : '',
+        `since=${since}`,
+        `items=${t.items}${t.prevItems === null ? '' : `/${t.prevItems}`}`,
+        `extends=${yesNo(t.extends)}`,
+        t.divergedAt === null ? '' : `diverged_at=${t.divergedAt}`,
+        t.seatChanged ? 'seat_changed' : '',
+        t.prefixChanged ? 'prefix_changed' : '',
+        `read=${usage.cacheReadTokens}/${prompt} (${pct}%)`,
+    ].filter(Boolean);
+    return `[dario] #${requestCount} cache: ${parts.join(' ')}`;
+}

package/dist/cli.js

@@ -393,6 +393,9 @@ async function proxy() {
         || args.includes('--verbose=2')
         || process.env.DARIO_LOG_BODIES === '1';
     const verbose = verboseBodies || args.includes('--verbose') || args.includes('-v');
+    // --cache-trace / DARIO_CACHE_TRACE=1: one line per Codex request on what it
+    // shared with the previous request on its cache key (src/cache-trace.ts).
+    const cacheTrace = args.includes('--cache-trace') || process.env.DARIO_CACHE_TRACE === '1';
     const passthrough = args.includes('--passthrough') || args.includes('--thin');
     const preserveTools = args.includes('--preserve-tools') || args.includes('--keep-tools');
     const hybridTools = args.includes('--hybrid-tools') || args.includes('--context-inject');
@@ -792,7 +795,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, 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 });
+    await startProxy({ port, host, verbose, verboseBodies, cacheTrace, 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
@@ -2387,6 +2390,10 @@ async function help() {
     --verbose, -v            Log all requests
     --verbose=2, -vv         Also dump redacted request bodies
                              (env: DARIO_LOG_BODIES=1)
+    --cache-trace            One line per ChatGPT (codex) request on what it
+                             shared with the previous request on its cache
+                             key: the gap, whether the input extends it, a
+                             seat or prompt change (env: DARIO_CACHE_TRACE=1)
     --log-file=PATH          Append one JSON-ND record per completed
                              request to PATH. Useful for backgrounded
                              proxies where stdout is unobserved (where

package/dist/codex-backend.d.ts

@@ -4,6 +4,7 @@ import { type ResponsesReasoningConfig, type ResponsesUsage } from './anthropic-
 import { type ModelResolver, type ClaudeTarget } from './claude-model.js';
 import { type EffortValue } from './effort.js';
 import type { MidstreamGuard } from './midstream.js';
+import { type CacheTraceResult } from './cache-trace.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;
@@ -52,7 +53,14 @@ export interface CodexForwardOutcome {
     stream: boolean;
     model: string;
     alias: string;
+    /** What the request shared with the previous one on its cache key (src/cache-trace.ts). Absent when no key went out. */
+    cache?: CodexCacheTrace;
 }
+/** The cache trace of one request, with the key it went out under (`traceKey()`: a caller's own key only as a digest). */
+export interface CodexCacheTrace extends CacheTraceResult {
+    key: string;
+}
+export declare function _resetCacheTraceForTest(): void;
 /** Why a forward DECLINED, for the caller's cool-down bookkeeping. `status` is
  *  the upstream status, or 0 when the request never got one (transport). */
 export interface CodexDecline {
@@ -274,7 +282,38 @@ export declare function createResponsesTranslator(model: string): {
 export declare const CODEX_SUPPORTED_FIELDS: readonly string[];
 /** Drop every field this backend does not accept. Pure; exported for tests. */
 export declare function toCodexSupportedBody(body: Record<string, unknown>): Record<string, unknown>;
-export declare function buildCodexHeaders(creds: CodexAccountCredentials): Record<string, string>;
+/** What a request adds to the seat's headers: its conversation and its model. */
+export interface CodexRequestHeaderInput {
+    /** The `prompt_cache_key` the body goes out with; empty when none. */
+    cacheKey?: string;
+    /** The model the body names; empty when none. */
+    model?: string;
+}
+/**
+ * A header value for a key the request supplies. Printable ASCII without
+ * spaces goes as it is (the Codex CLI's session ids are UUIDs); anything
+ * else is sent as a stable digest, so a key with a space, a quote or a
+ * non-ASCII character cannot break the request or smuggle a header.
+ */
+export declare function sessionHeaderValue(key: string): string;
+/**
+ * The headers of one request to the ChatGPT backend: the seat's identity and,
+ * when the request is known, its conversation and model.
+ *
+ * The backend's prompt cache lives on individual machines and a request is
+ * routed to one by its `session-id` header: the Codex CLI sends its session
+ * id there on every turn (codex-rs: "ChatGPT derives cache affinity from the
+ * Responses session-id header") with the same value as its `prompt_cache_key`
+ * and a `thread-id`, and `x-codex-routing-hint: model=<model>`. Without the
+ * header a conversation's turns scatter across machines and read a cached
+ * prefix only when one happens to land where an earlier turn wrote it: with
+ * turns a few seconds apart and every input a strict extension of the last,
+ * a review loop through dario read its prefix on 8 of 23 turns, and what it
+ * read was a snapshot several turns old. So the key goes out in the header
+ * too, and the raw `/v1/responses` path sends it for the Codex CLI, whose
+ * own headers dario does not forward.
+ */
+export declare function buildCodexHeaders(creds: CodexAccountCredentials, request?: CodexRequestHeaderInput): Record<string, string>;
 /**
  * Serve a Responses-shape request (`POST /v1/responses`) from a stored Codex
  * account with NO translation: the ChatGPT backend speaks this shape natively,

package/dist/codex-backend.js

@@ -31,6 +31,7 @@ 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';
+import { CacheTrace, itemHash, prefixHash, traceKey } from './cache-trace.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`;
@@ -130,6 +131,25 @@ export async function fetchCodexModels(creds, fetchImpl = fetch) {
     }
     return slugs;
 }
+// One trace per process: the comparison is between consecutive requests on a
+// key, whichever seat or client path they came through.
+let cacheTrace = new CacheTrace();
+export function _resetCacheTraceForTest() {
+    cacheTrace = new CacheTrace();
+}
+/**
+ * Make a request the one the next request on its key compares with. Called
+ * once a seat has accepted it: a declined attempt retried on a peer is the
+ * same request, and must not become its own predecessor.
+ */
+function rememberTrace(traced) {
+    if (!traced)
+        return;
+    try {
+        cacheTrace.remember(traced);
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
+}
 /** The cached slug list for an alias WITHOUT fetching. For the admin surface:
  *  a status read must never cost an upstream call or a token refresh. */
 export function peekCodexModelSlugs(alias) {
@@ -776,7 +796,35 @@ export function toCodexSupportedBody(body) {
     }
     return out;
 }
-export function buildCodexHeaders(creds) {
+/**
+ * A header value for a key the request supplies. Printable ASCII without
+ * spaces goes as it is (the Codex CLI's session ids are UUIDs); anything
+ * else is sent as a stable digest, so a key with a space, a quote or a
+ * non-ASCII character cannot break the request or smuggle a header.
+ */
+export function sessionHeaderValue(key) {
+    if (/^[\x21-\x7e]{1,256}$/.test(key))
+        return key;
+    return createHash('sha256').update(key).digest('hex').slice(0, 32);
+}
+/**
+ * The headers of one request to the ChatGPT backend: the seat's identity and,
+ * when the request is known, its conversation and model.
+ *
+ * The backend's prompt cache lives on individual machines and a request is
+ * routed to one by its `session-id` header: the Codex CLI sends its session
+ * id there on every turn (codex-rs: "ChatGPT derives cache affinity from the
+ * Responses session-id header") with the same value as its `prompt_cache_key`
+ * and a `thread-id`, and `x-codex-routing-hint: model=<model>`. Without the
+ * header a conversation's turns scatter across machines and read a cached
+ * prefix only when one happens to land where an earlier turn wrote it: with
+ * turns a few seconds apart and every input a strict extension of the last,
+ * a review loop through dario read its prefix on 8 of 23 turns, and what it
+ * read was a snapshot several turns old. So the key goes out in the header
+ * too, and the raw `/v1/responses` path sends it for the Codex CLI, whose
+ * own headers dario does not forward.
+ */
+export function buildCodexHeaders(creds, request = {}) {
     const headers = {
         'Content-Type': 'application/json',
         'Accept': 'text/event-stream',
@@ -787,6 +835,13 @@ export function buildCodexHeaders(creds) {
     const accountId = extractChatGPTAccountId(creds.idToken);
     if (accountId)
         headers['ChatGPT-Account-ID'] = accountId;
+    if (request.cacheKey) {
+        const id = sessionHeaderValue(request.cacheKey);
+        headers['session-id'] = id;
+        headers['thread-id'] = id;
+    }
+    if (request.model && /^[\x21-\x7e]{1,128}$/.test(request.model))
+        headers['x-codex-routing-hint'] = `model=${request.model}`;
     return headers;
 }
 /**
@@ -884,13 +939,15 @@ timing) {
     });
     const model = String(body.model ?? '');
     let reported = false;
+    let cache;
+    let traced;
     const report = (status, usage) => {
         if (reported || !onDone)
             return;
         reported = true;
         try {
             onDone({ status, latencyMs: Date.now() - startedAt, upstreamTtfbMs: ttfbMs(), upstreamMs: upstreamMsNow(), inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0,
-                cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0, stream: true, model, alias: creds.alias });
+                cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0, stream: true, model, alias: creds.alias, cache });
         }
         catch { /* never break a served request */ }
     };
@@ -905,6 +962,20 @@ timing) {
     // default to make its next turn's previous_response_id resolvable, and
     // Codex CLI sends false itself.
     const upstreamBody = { ...body, stream: true };
+    // The same trace as forwardToCodex, under the key the client sent (Codex CLI
+    // sends its session id on every request); none when it sent no key.
+    // Compared here, remembered only once the seat accepts the request.
+    try {
+        const key = typeof body.prompt_cache_key === 'string' ? body.prompt_cache_key : '';
+        if (key) {
+            // The Responses API also takes a bare string input: one item, so a
+            // changed string diverges like a changed message would.
+            const input = Array.isArray(body.input) ? body.input : typeof body.input === 'string' ? [body.input] : [];
+            traced = { key, alias: creds.alias, prefix: prefixHash(body), items: input.map(itemHash), at: Date.now() };
+            cache = { key: traceKey(key, false), ...cacheTrace.peek(traced) };
+        }
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
     const target = `${CODEX_BACKEND_BASE_URL.replace(/\/$/, '')}/responses`;
     const abort = new AbortController();
     let clientGone = false;
@@ -922,13 +993,17 @@ timing) {
         if (verbose)
             console.log(`[dario] → codex backend (responses passthrough): ${target} (model: ${model})`);
         let activeCreds = creds;
-        let upstream = await timedFetch(target, { method: 'POST', headers: buildCodexHeaders(activeCreds), body: JSON.stringify(upstreamBody), signal: abort.signal });
+        // The client's own key as the session: the Codex CLI's headers do not
+        // pass through dario, so its cache affinity is rebuilt here from the key
+        // it sends in the body.
+        const requestHeaders = { cacheKey: typeof body.prompt_cache_key === 'string' ? body.prompt_cache_key : '', model };
+        let upstream = await timedFetch(target, { method: 'POST', headers: buildCodexHeaders(activeCreds, requestHeaders), body: JSON.stringify(upstreamBody), signal: abort.signal });
         if (isCodexAuthFailure(upstream.status)) {
             await upstream.text().catch(() => ''); // release the rejected response before retrying
             const fresh = await refreshAfterCodexAuthFailure(activeCreds, verbose);
             if (fresh) {
                 activeCreds = fresh;
-                upstream = await timedFetch(target, { method: 'POST', headers: buildCodexHeaders(activeCreds), body: JSON.stringify(upstreamBody), signal: abort.signal });
+                upstream = await timedFetch(target, { method: 'POST', headers: buildCodexHeaders(activeCreds, requestHeaders), body: JSON.stringify(upstreamBody), signal: abort.signal });
             }
         }
         if (!upstream.ok || !upstream.body) {
@@ -963,6 +1038,7 @@ timing) {
             report(clientGone ? 499 : upstream.status, null);
             return true;
         }
+        rememberTrace(traced);
         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();
@@ -1118,6 +1194,8 @@ timing) {
         fetchStartedAt: fetchStartedAt || Date.now(), upstreamTtfbMs: ttfbMs(),
     });
     let reported = false;
+    let cache;
+    let traced;
     const report = (status, usage, stream, model) => {
         if (reported || !onDone)
             return;
@@ -1127,7 +1205,7 @@ timing) {
                 status, latencyMs: Date.now() - startedAt, upstreamTtfbMs: ttfbMs(), upstreamMs: upstreamMsNow(),
                 inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0,
                 cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0,
-                stream, model, alias: creds.alias,
+                stream, model, alias: creds.alias, cache,
             });
         }
         catch { /* a reporting failure must never break a served request */ }
@@ -1155,10 +1233,27 @@ timing) {
     const upstreamBody = isAnthropic
         ? { ...anthropicToResponsesRequest(parsed, model, effort ? { effort } : {}), stream: true }
         : chatCompletionsToResponses(parsed);
+    const ownCacheKey = upstreamBody.prompt_cache_key;
     const scrubbed = toCodexSupportedBody({
         ...upstreamBody,
         prompt_cache_key: codexPromptCacheKey(shape, parsed, upstreamBody),
     });
+    // What this request shares with the previous one on its key, for the
+    // analytics row and the log line (src/cache-trace.ts). Hashes only, and a
+    // failure here never costs the request. Compared here, remembered only once
+    // the seat accepts the request.
+    try {
+        const key = String(scrubbed.prompt_cache_key ?? '');
+        if (key) {
+            const input = Array.isArray(scrubbed.input) ? scrubbed.input : [];
+            // Kept as is only when dario derived it; a client's own key is digested
+            // whatever it looks like.
+            const derived = !(typeof ownCacheKey === 'string' && ownCacheKey.length > 0);
+            traced = { key, alias: creds.alias, prefix: prefixHash(scrubbed), items: input.map(itemHash), at: Date.now() };
+            cache = { key: traceKey(key, derived), ...cacheTrace.peek(traced) };
+        }
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
     const target = `${CODEX_BACKEND_BASE_URL.replace(/\/$/, '')}/responses`;
     const abort = new AbortController();
     // Once the client is gone there is nobody left to write to, but the upstream
@@ -1207,9 +1302,12 @@ timing) {
         if (verbose)
             console.log(`[dario] → codex backend: ${target} (model: ${model})`);
         let activeCreds = creds;
+        // The key the body goes out with, derived or the client's own, is the
+        // session the backend routes the conversation by.
+        const requestHeaders = { cacheKey: String(scrubbed.prompt_cache_key ?? ''), model: String(scrubbed.model ?? model) };
         let upstream = await timedFetch(target, {
             method: 'POST',
-            headers: buildCodexHeaders(activeCreds),
+            headers: buildCodexHeaders(activeCreds, requestHeaders),
             body: JSON.stringify(scrubbed),
             signal: abort.signal,
         });
@@ -1222,7 +1320,7 @@ timing) {
                 activeCreds = fresh;
                 upstream = await timedFetch(target, {
                     method: 'POST',
-                    headers: buildCodexHeaders(activeCreds),
+                    headers: buildCodexHeaders(activeCreds, requestHeaders),
                     body: JSON.stringify(scrubbed),
                     signal: abort.signal,
                 });
@@ -1277,6 +1375,7 @@ timing) {
             report(upstream.status, null, clientWantsStream, model);
             return true;
         }
+        rememberTrace(traced);
         // OpenAI shape: one stateful line-in/line-out translator (unchanged).
         // Anthropic shape: parse the typed Responses event stream, then map events
         // to Anthropic SSE, keeping the terminal `response` for the collapse.

package/dist/proxy.d.ts

@@ -4,6 +4,7 @@ import { getAccessToken, getStatus } from './oauth.js';
 import { type EffortValue } from './cc-template.js';
 import { type KeySocket } from './keys.js';
 import { type BackendCredentials } from './openai-backend.js';
+import { type CodexCacheTrace } from './codex-backend.js';
 /**
  * Assemble the `x-anthropic-billing-header` system-block text, following
  * Claude Code's format:
@@ -358,6 +359,7 @@ interface ProxyOptions {
     host?: string;
     verbose?: boolean;
     verboseBodies?: boolean;
+    cacheTrace?: boolean;
     model?: string;
     fastModel?: string;
     noClaudeAuth?: boolean;
@@ -743,7 +745,18 @@ export interface ProxyLogEntry {
     reject?: string;
     error?: string;
     event?: string;
+    /** The cache trace of a Codex request (src/cache-trace.ts): the key it went out under and what it shared with the previous request on that key. */
+    cache_key?: string;
+    cache_items?: number;
+    cache_since_ms?: number | null;
+    cache_prev_items?: number | null;
+    cache_extends?: boolean | null;
+    cache_diverged_at?: number | null;
+    cache_seat_changed?: boolean | null;
+    cache_prefix_changed?: boolean | null;
 }
+/** The log fields of a cache trace; nothing when the request carried none. */
+export declare function cacheLogFields(c: CodexCacheTrace | undefined): Partial<ProxyLogEntry>;
 /**
  * Append a JSON-ND line to the proxy log file. No-op when stream is
  * null (logFile not configured). Errors are swallowed — log writes

package/dist/proxy.js

@@ -33,6 +33,7 @@ import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI, isMiniMaxBackend, MINIMAX_MODELS } from './openai-backend.js';
 import { forwardToCodex, forwardResponsesToCodex, getCodexModelSlugs, peekCodexModelSlugs, isCodexModel, pickCodexFallback, pickClaudeTarget, CODEX_BACKEND_BASE_URL } from './codex-backend.js';
+import { formatCacheTraceLine } from './cache-trace.js';
 import { effortForCodex } from './effort.js';
 import { MidstreamGuard, guardFor, loopbackBaseFor, chaosCutFetch, chaosCutState, CONTINUATION_HEADER, CONTINUATION_OF_HEADER, MAX_CONTINUATION_DEPTH, continuationDepth, continuationOfRequest } from './midstream.js';
 /**
@@ -1075,6 +1076,15 @@ export const OPENAI_MODELS_LIST = buildOpenAIModelsList(withLongContextVariants(
 export function requiresClaudeLogin(poolSize, adminEnabled, hasUpstreamApiKey, noClaudeAuth, hasCodexAccount = false) {
     return poolSize === 0 && !adminEnabled && !hasUpstreamApiKey && !noClaudeAuth && !hasCodexAccount;
 }
+/** The log fields of a cache trace; nothing when the request carried none. */
+export function cacheLogFields(c) {
+    if (!c)
+        return {};
+    return {
+        cache_key: c.key, cache_items: c.items, cache_since_ms: c.sinceMs, cache_prev_items: c.prevItems,
+        cache_extends: c.extends, cache_diverged_at: c.divergedAt, cache_seat_changed: c.seatChanged, cache_prefix_changed: c.prefixChanged,
+    };
+}
 /**
  * Append a JSON-ND line to the proxy log file. No-op when stream is
  * null (logFile not configured). Errors are swallowed — log writes
@@ -1418,6 +1428,11 @@ export async function startProxy(opts = {}) {
     // -v stays quiet because bodies can carry file content and tool
     // output. Reported in dario#40 by @ringge.
     const verboseBodies = Boolean(opts.verboseBodies) || process.env.DARIO_LOG_BODIES === '1';
+    // Cache trace line: --cache-trace / DARIO_CACHE_TRACE=1, and under -v. One
+    // line per Codex request saying what it shared with the previous request on
+    // its cache key (src/cache-trace.ts), so a low cache share can be read as
+    // a timing, a shape or a seat problem instead of a number.
+    const cacheTraceLines = Boolean(opts.cacheTrace) || process.env.DARIO_CACHE_TRACE === '1' || verbose;
     // Operator-declared beta passthrough set. Sourced from CLI flag or env;
     // both are CSV strings of beta-flag names. Trimmed, deduped, empty
     // entries dropped. Stays a Set for fast membership checks in the per-
@@ -2455,6 +2470,60 @@ export async function startProxy(opts = {}) {
                 providerCooldowns.note('codex', d.retryAfterMs);
         }).catch(() => { });
     };
+    /**
+     * The /analytics row, request-log line and usage lines of one codex request.
+     *
+     * ONE function for BOTH routes that reach a seat: the codex route (a client
+     * asking for a GPT model) and the pool-exhausted fallback below. The fallback
+     * route passed no reporter until 6.18.1, so a request it served left no row
+     * anywhere: /analytics, the request log and the ledger all showed a drained
+     * Claude pool and nothing of the subscription that answered in its place.
+     * The seat's served count and its decline state move here with the row, so a
+     * route cannot have one without the others.
+     */
+    const reportCodexOutcome = (o, ctx) => {
+        codexRequestCounts.set(o.alias, (codexRequestCounts.get(o.alias) ?? 0) + 1);
+        // A seat that actually SERVED is not rate-limited. Keyed on a 2xx, never on
+        // forwardToCodex returning true: that means "I wrote a response", which is
+        // equally true when it wrote the upstream 429.
+        if (o.status >= 200 && o.status < 300)
+            clearCodexDecline(o.alias);
+        analytics.record({
+            timestamp: Date.now(),
+            consumer: ctx.consumer,
+            account: o.alias,
+            model: o.model || ctx.model || 'codex',
+            inputTokens: o.inputTokens, outputTokens: o.outputTokens,
+            // Anthropic convention, like every other row: inputTokens is
+            // net of the cached prefix, which sits in cacheReadTokens.
+            cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens, thinkingTokens: 0,
+            // No Anthropic rate-limit headers on this path; the claim
+            // names the engine and is subscription billing, so the
+            // overage guard (#288) leaves it alone.
+            claim: CODEX_CLAIM, util5h: 0, util7d: 0, overageUtil: 0,
+            latencyMs: o.latencyMs, status: o.status, isStream: o.stream, isOpenAI: ctx.isOpenAI,
+            continuation: continuationOf(ctx.codexGuard, ctx.requestDepth),
+            timing: { queueMs: ctx.queueMs, pacingMs: 0, upstreamTtfbMs: o.upstreamTtfbMs, upstreamMs: o.upstreamMs, totalMs: Math.max(0, Date.now() - ctx.arrivedAt) },
+            cache: o.cache,
+        });
+        writeLogLine(logFileStream, {
+            ts: new Date().toISOString(), req: ctx.codexReq,
+            method: ctx.method, path: ctx.urlPath, model: o.model || ctx.model || undefined,
+            status: o.status, latency_ms: o.latencyMs, in_tokens: o.inputTokens, out_tokens: o.outputTokens,
+            cache_read: o.cacheReadTokens, cache_create: o.cacheCreateTokens,
+            claim: CODEX_CLAIM, bucket: 'subscription', account: o.alias, consumer: ctx.consumer, stream: o.stream,
+            ...(ctx.codexGuard?.outcome ? { continued: ctx.codexGuard.outcome, continued_by: ctx.codexGuard.continuedBy ?? undefined, continued_after: ctx.codexGuard.partialChars } : {}),
+            ...ctx.continuationLeg,
+            ...cacheLogFields(o.cache),
+        });
+        if (verbose)
+            console.log(formatUsageLogLine(ctx.codexReq, {
+                inputTokens: o.inputTokens, outputTokens: o.outputTokens,
+                cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens,
+            }, ctx.consumer));
+        if (cacheTraceLines && o.cache)
+            console.log(formatCacheTraceLine(ctx.codexReq, o.cache.key, o.cache, o, o.alias));
+    };
     /**
      * Serve a pool-exhausted request from the ChatGPT subscription (v6.0.0).
      *
@@ -2473,7 +2542,13 @@ export async function startProxy(opts = {}) {
      */
     const tryCodexPoolFallback = async (req, res, body, fallbackModels, shape, why, attempted, 
     /** The request's queue wait and arrival, so the codex response carries the timing headers too. */
-    timing) => {
+    timing, 
+    /**
+     * Files the request the seat answered (reportCodexOutcome), under the
+     * request number its console line carried. Required: a route that reaches
+     * a seat without it serves GPT that nothing counts.
+     */
+    onDone) => {
         if (fallbackModels.length === 0)
             return false;
         // Never a second codex attempt in the same request, and never one while it
@@ -2556,13 +2631,18 @@ export async function startProxy(opts = {}) {
             const fallbackBody = buildPoolFallbackBody(body, fallbackModel);
             if (!fallbackBody)
                 return false;
-            console.log(`[dario] #${requestCount} ${why} → codex account ${seat.alias} as ${fallbackModel}`);
+            const reqNo = requestCount;
+            console.log(`[dario] #${reqNo} ${why} → codex account ${seat.alias} as ${fallbackModel}`);
             requestCount++;
             // Marked only once an attempt is actually being made. Marking it before
             // the guards above would tell the rest of the request that codex had been
             // tried when it had not, suppressing a later legitimate attempt.
             attempted.add('codex');
-            served = await forwardToCodex(req, res, fallbackBody, seat, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption || peer !== null, undefined, codexOnDecline, 
+            served = await forwardToCodex(req, res, fallbackBody, seat, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption || peer !== null, 
+            // The row files under the model the seat served as; the substituted
+            // one when the seat named none. The client's own model is the Claude
+            // one, which this request never reached.
+            (o) => onDone({ ...o, model: o.model || fallbackModel }, reqNo), codexOnDecline, 
             // The mirror of the Claude side (dario#1161): an operator who writes
             // `--pool-fallback=gpt-5.6-terra:high` is choosing the effort the
             // failover runs at, so the entry's own suffix reaches the request rather
@@ -2604,6 +2684,8 @@ export async function startProxy(opts = {}) {
      * this by construction, not by remembering to copy six lines correctly.
      */
     const attemptPoolFallbackOn429 = async (req, res, body, isOpenAI, attempted, timing, 
+    /** Files a request the subscription served; see tryCodexPoolFallback. */
+    onDone, 
     /**
      * Re-arm THIS request on the credits rung (credits-rung.ts): returns true
      * once the request is re-pointed at the key, and the caller re-enters its
@@ -2611,7 +2693,7 @@ export async function startProxy(opts = {}) {
      */
     armCredits) => {
         const chain = selectPoolFallbackForBody(body);
-        if (await tryCodexPoolFallback(req, res, body, chain, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted mid-flight (429, no peer)', attempted, timing)) {
+        if (await tryCodexPoolFallback(req, res, body, chain, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted mid-flight (429, no peer)', attempted, timing, onDone)) {
             return 'served';
         }
         // The metered rungs, in the chain's own order. The credits rung is never
@@ -3693,6 +3775,14 @@ export async function startProxy(opts = {}) {
             const continuationLeg = requestDepth > 0
                 ? { continuation_depth: requestDepth, continuation_of: continuationOfRequest(req.headers[CONTINUATION_OF_HEADER]) }
                 : {};
+            // The row of a request the pool-exhausted fallback handed to the
+            // subscription, under the number the fallback's console line carried.
+            // No model of its own to file under (the client asked for a Claude one)
+            // and no midstream guard: that route does not resume a dead stream.
+            const reportFallbackCodex = (o, reqNo) => reportCodexOutcome(o, {
+                consumer, codexReq: reqNo, method: req.method ?? '', urlPath, model: '', isOpenAI,
+                queueMs, arrivedAt, requestDepth, codexGuard: null, continuationLeg,
+            });
             /**
              * First hop: the SAME model again, through the front door. The pool
              * picks a seat (sticky binding keeps the prompt cache warm), and if the
@@ -4365,51 +4455,18 @@ export async function startProxy(opts = {}) {
                         // Reporting is one function for BOTH codex shapes below: the Responses
                         // passthrough and the translated Messages path record the same row, so a
                         // GPT request looks the same in /analytics whichever shape asked for it.
+                        // The row itself is reportCodexOutcome, shared with the pool-exhausted
+                        // fallback route.
                         //
                         // Before this hook a codex request left no trace: nothing in /analytics,
                         // nothing in the request log, no per-account count. The dock (and anyone
                         // reading /analytics) saw a proxy that served GPT all day and reported
                         // zero of it. A decline (the request handed to the Claude pool) reports
                         // nothing here; the Claude path records what it then serves.
-                        const codexOnDone = (o) => {
-                            codexRequestCounts.set(o.alias, (codexRequestCounts.get(o.alias) ?? 0) + 1);
-                            // A seat that actually SERVED is not rate-limited. Keyed on a 2xx,
-                            // never on forwardToCodex returning true — that means "I wrote a
-                            // response", which is equally true when it wrote the upstream 429.
-                            if (o.status >= 200 && o.status < 300)
-                                clearCodexDecline(o.alias);
-                            analytics.record({
-                                timestamp: Date.now(),
-                                consumer,
-                                account: o.alias,
-                                model: o.model || rawModel || 'codex',
-                                inputTokens: o.inputTokens, outputTokens: o.outputTokens,
-                                // Anthropic convention, like every other row: inputTokens is
-                                // net of the cached prefix, which sits in cacheReadTokens.
-                                cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens, thinkingTokens: 0,
-                                // No Anthropic rate-limit headers on this path; the claim
-                                // names the engine and is subscription billing, so the
-                                // overage guard (#288) leaves it alone.
-                                claim: CODEX_CLAIM, util5h: 0, util7d: 0, overageUtil: 0,
-                                latencyMs: o.latencyMs, status: o.status, isStream: o.stream, isOpenAI,
-                                continuation: continuationOf(codexGuard, requestDepth),
-                                timing: { queueMs, pacingMs: 0, upstreamTtfbMs: o.upstreamTtfbMs, upstreamMs: o.upstreamMs, totalMs: Math.max(0, Date.now() - arrivedAt) },
-                            });
-                            writeLogLine(logFileStream, {
-                                ts: new Date().toISOString(), req: codexReq,
-                                method: req.method ?? '', path: urlPath, model: o.model || rawModel || undefined,
-                                status: o.status, latency_ms: o.latencyMs, in_tokens: o.inputTokens, out_tokens: o.outputTokens,
-                                cache_read: o.cacheReadTokens, cache_create: o.cacheCreateTokens,
-                                claim: CODEX_CLAIM, bucket: 'subscription', account: o.alias, consumer, stream: o.stream,
-                                ...(codexGuard?.outcome ? { continued: codexGuard.outcome, continued_by: codexGuard.continuedBy ?? undefined, continued_after: codexGuard.partialChars } : {}),
-                                ...continuationLeg,
-                            });
-                            if (verbose)
-                                console.log(formatUsageLogLine(codexReq, {
-                                    inputTokens: o.inputTokens, outputTokens: o.outputTokens,
-                                    cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens,
-                                }, consumer));
-                        };
+                        const codexOnDone = (o) => reportCodexOutcome(o, {
+                            consumer, codexReq, method: req.method ?? '', urlPath, model: rawModel, isOpenAI,
+                            queueMs, arrivedAt, requestDepth, codexGuard, continuationLeg,
+                        });
                         // Mid-flight seat failover. A 429 lands BEFORE any body is written —
                         // forwardToCodex only returns false on the decline path — so the same
                         // request can be handed to a healthy peer instead of failing. Without
@@ -4656,7 +4713,7 @@ export async function startProxy(opts = {}) {
             if (!upstreamApiKey && !poolAccount) {
                 attemptedProviders.add('claude');
             }
-            if (!upstreamApiKey && !poolAccount && !pinnedAccount && await tryCodexPoolFallback(req, res, body, selectPoolFallbackForBody(body), isOpenAI ? 'openai' : 'anthropic', 'pool exhausted', attemptedProviders, { queueMs, arrivedAt })) {
+            if (!upstreamApiKey && !poolAccount && !pinnedAccount && await tryCodexPoolFallback(req, res, body, selectPoolFallbackForBody(body), isOpenAI ? 'openai' : 'anthropic', 'pool exhausted', attemptedProviders, { queueMs, arrivedAt }, reportFallbackCodex)) {
                 return;
             }
             // `isOpenAI` is REQUIRED here and was not, before v6.0.0 — the selector's
@@ -5735,7 +5792,7 @@ export async function startProxy(opts = {}) {
                         if (!creditsRung)
                             providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
                         if (!pinnedAccount) {
-                            const outcome = await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt }, rearmOnCredits);
+                            const outcome = await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt }, reportFallbackCodex, rearmOnCredits);
                             if (outcome === 'served')
                                 return;
                             if (outcome === 'credits') {
@@ -5870,7 +5927,7 @@ export async function startProxy(opts = {}) {
                     if (!creditsRung)
                         providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
                     if (!pinnedAccount) {
-                        const outcome = await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt }, rearmOnCredits);
+                        const outcome = await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders, { queueMs, arrivedAt }, reportFallbackCodex, rearmOnCredits);
                         if (outcome === 'served')
                             return;
                         if (outcome === 'credits') {

package/docs/analytics.md

@@ -77,6 +77,26 @@ scrape_configs:
     authorization: { credentials: '<DARIO_ANALYTICS_TOKEN>' }
 ```
 
+## The cache trace
+
+A ChatGPT (codex) request reports how much of its prompt the backend read from its cache, and that number alone cannot say why a turn missed. dario records next to it what it can see before the request goes out that bears on a hit (`src/cache-trace.ts`). These narrow a miss down to likely causes; they do not prove one:
+
+| field | says | a miss reads as |
+|---|---|---|
+| `sinceMs` | ms since the previous request on the same `prompt_cache_key`; null on the first | a write is not readable at once, so a turn close behind the last may read nothing it wrote; the gap is measured, the backend's readiness is not |
+| `items`, `prevItems`, `extends` | input items now and before, and whether the previous input is a strict prefix of this one, item for item; `extends` is null when the previous input ran past the first 2000 items, which are all that is kept; input items only, the front of the prompt is `prefixChanged` | a client that rewrites or reorders its history has no prefix to hit |
+| `divergedAt` | the first input item that differs, when one does | which turn the rewrite happened at |
+| `prefixChanged` | the model, system prompt or tool names changed between the two; tool schemas are not compared | the front of the prompt moved, so nothing behind it can match |
+| `seatChanged` | a different account served this one | the cache is per account; a conversation that moved seats starts over |
+
+The trace is hashes and counts only: no content leaves the request. It rides on every `/analytics` row of that path as `cache` (with the `key`: dario's own derived `dario-…` key as it went out, a key the client set itself only as a `key-…` digest of it; a `/v1/responses` request goes through as the client wrote it, so it is traced under its own key, as Codex CLI sends one on every request, and carries no trace when it sent none), on the `--log-file` record as `cache_key`, `cache_items`, `cache_since_ms`, `cache_prev_items`, `cache_extends`, `cache_diverged_at`, `cache_seat_changed`, `cache_prefix_changed`, and with `--cache-trace` / `DARIO_CACHE_TRACE=1` (or `-v`) as one stdout line per request:
+
+```
+[dario] #412 cache: key=dario-3f9a2c7e1b0d44a6 seat=work since=3.1s items=23/21 extends=yes read=0/44120 (0%)
+```
+
+Read a run of them by key. `extends=yes` with `read=0`, a short `since` and no `prefix_changed` or `seat_changed` points at the backend's write delay rather than the shape of the input, but only as the likely explanation: the trace measures the gap, not when the write became readable, and `extends` compares input items only, so a changed tool schema, which the trace does not compare, misses the same way. `extends=no` with a `diverged_at` names the item the client changed; `prefix_changed` is a moved model, system prompt or tool name in front of an input that may still extend; `seat_changed` is the pool moving a conversation. The entry for a key is kept for an hour, longer than the backend keeps a prefix, so a stale key never reads as a live conversation.
+
 ## The rings
 
 `dario usage --donut` and `/analytics/donuts.svg` render the ledger's lifetime spend as three rings: **by model**, **by key** (empty until a named key or `x-dario-consumer` has traffic), and **subscription vs metered**. Each ring keeps the top five and folds the rest into *other*. Shares are of API-equivalent plus metered spend, so a model that only ever ran on an API key still shows.

package/docs/commands.md

@@ -39,9 +39,10 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
 | `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
 | `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
+| `--cache-trace` / `DARIO_CACHE_TRACE=1` | One line per ChatGPT (codex) request on what it shared with the previous request on its `prompt_cache_key`: the gap in seconds, the input item counts, whether the input extends the previous one item for item (the shape a cache hit needs) and where it diverged if not, a seat change, a model, system prompt or tool change, and the cached share that came back. Also on under `-v`. The same facts ride on the `--log-file` record (`cache_*`) and the `/analytics` row (`cache`) whether or not the line is on. See [Analytics](./analytics.md#the-cache-trace). | off |
 | `--key-socket=<path>=<key>` / `DARIO_KEY_SOCKETS` | Also listen on a unix socket bound to one named key: every request on it is that key's, with no secret sent or stored by the caller; the socket's directory and group decide who may connect. Repeatable. See [Key sockets](./keys.md#a-key-with-no-secret-key-sockets). | none |
 | `--no-keys` / `DARIO_KEYS=0`; `--keys-path=<file>` / `DARIO_KEYS_PATH` | Ignore named keys (`~/.dario/keys.json`) so only `DARIO_API_KEY` authenticates; or move the file. See [Named keys](./keys.md). (v6.8) | on, `~/.dario/keys.json` |
-| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
+| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths, and on a ChatGPT (codex) request the cache trace `cache_key`, `cache_items`, `cache_since_ms`, `cache_prev_items`, `cache_extends`, `cache_diverged_at`, `cache_seat_changed`, `cache_prefix_changed`. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
 | `--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 |
 | `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |

package/docs/docker.md

@@ -109,6 +109,7 @@ All flags have env-var equivalents. The image sets sensible container defaults:
 | `DARIO_CORS_ORIGIN`       | unset            | Override the default `http://localhost:<port>` allow-list |
 | `DARIO_LOG_FILE`          | unset            | Path inside the container (mount a volume)    |
 | `DARIO_LOG_BODIES`        | unset            | `1` to log request/response bodies            |
+| `DARIO_CACHE_TRACE`       | unset            | `1` to log one cache-trace line per ChatGPT (codex) request, see [`docs/analytics.md`](./analytics.md#the-cache-trace) |
 | `DARIO_PASSTHROUGH_BETAS` | unset            | `1` to forward `anthropic-beta` headers as-is |
 | `DARIO_CLAUDE_BIN`        | unset            | Path to a Claude Code binary (optional, for live template capture) |
 | `DARIO_NO_BUN`            | unset            | `1` to skip the Bun auto-relaunch (not recommended) |

package/docs/multi-instance.md

@@ -136,6 +136,10 @@ Anthropic's token endpoint is the one mocked part, and only that — hammering t
 
 ## If you need true HA
 
-There is no shared-state mode today, and building one is a larger change than a lock: rate-limit snapshots and sticky bindings would both have to move out of process memory, which means every routing decision takes a network hop.
+Everything above is as far as dario goes today: shared credentials through the lock, and shared rate-limit readings and sticky bindings through `--pool-shared-state`, both eventually consistent and both failing open. Three things are still per instance:
 
-If you want that, say so on [#993](https://github.com/askalf/dario/issues/993) with your deployment shape. Concrete requirements are considerably more useful than a general "make it HA" — the design depends heavily on whether you need precise accounting or merely approximate.
+- **ChatGPT seats.** The Codex accounts have their own refresh flow and usage windows; neither the lock nor the shared state covers them.
+- **The ledger.** Each instance writes its own file, so `dario usage` and `/analytics` show that instance's share of the spend.
+- **The overage guard's halt**, which each instance tracks on its own.
+
+A design where every routing decision reads Redis on the request path is not planned: it adds a network hop per request and turns the coordination point into a hard dependency, which is exactly what the fail-open rule avoids. Extending the report-and-pull model to the ChatGPT seats is the natural next step. If you need it, say so on [#1733](https://github.com/askalf/dario/issues/1733) with your deployment shape: replica count, Claude only or both plans, and whether accounting has to be exact or may lag a pull interval.

package/docs/two-plans.md

@@ -26,9 +26,9 @@ curl localhost:3456/v1/messages -H 'content-type: application/json' \
 
 **Model names are discovered, not hardcoded.** The set a ChatGPT subscription may use is per-account and moves; dario asks the backend which models this account lists, caches the answer, and advertises them on `GET /v1/models`. Anything not on that list (`gpt-4o` and friends) still routes to a configured API-key backend as before. `codex:<model>` / `chatgpt:<model>` forces the route.
 
-Streaming, tool calls and tool-result round trips work on both shapes, and chat-shape `image_url` parts are carried as Responses `input_image` parts with `detail` preserved: dario translates chat/completions **or** Messages into the Responses API the subscription backend speaks, and translates the stream back into `chat.completion.chunk` or Anthropic message events. There is no `/v1/responses` inbound yet. The Codex backend does not accept every chat field, so `response_format`, `stop`, `n`, `logprobs`, `stream_options` and the sampling parameters `temperature`, `top_p`, `max_tokens`, `max_completion_tokens` are intentionally lossy; with `--verbose`, dario reports each field that does not reach Codex once per process. Codex accounts live in `~/.dario/codex-accounts/`, separate from the Claude pool.
+Streaming, tool calls and tool-result round trips work on both shapes, and chat-shape `image_url` parts are carried as Responses `input_image` parts with `detail` preserved: dario translates chat/completions **or** Messages into the Responses API the subscription backend speaks, and translates the stream back into `chat.completion.chunk` or Anthropic message events. A `/v1/responses` request needs no translation: the backend speaks that shape, so the body goes through as the client wrote it (model resolved) and the stream comes back untouched, on the same seats and failover as the other shapes (see [Codex CLI](./integrations/codex-cli.md)). The Codex backend does not accept every chat field, so `response_format`, `stop`, `n`, `logprobs`, `stream_options` and the sampling parameters `temperature`, `top_p`, `max_tokens`, `max_completion_tokens` are intentionally lossy; with `--verbose`, dario reports each field that does not reach Codex once per process. Codex accounts live in `~/.dario/codex-accounts/`, separate from the Claude pool.
 
-**Prompt caching:** the backend caches prompt prefixes of 1,024 tokens and up on its own; what dario adds is the `prompt_cache_key` that routes same-prefix requests to the cache that holds them, the way the Codex CLI does with its session id. A chat/completions client that sets its own key keeps it; an Anthropic-shape request gets one per Claude Code session (a hash of `metadata.user_id`, never the raw ids); anything else is keyed on its model, instructions and tool names, so repeated system prompts from any caller land together. Cached tokens come back as `prompt_tokens_details.cached_tokens` on chat/completions and as `cache_read_input_tokens` on `/v1/messages`, and show up in `/analytics` and the `-v` usage line like a Claude request's do.
+**Prompt caching:** the backend caches prompt prefixes of 1,024 tokens and up on its own; what dario adds is the `prompt_cache_key` that routes same-prefix requests to the cache that holds them, the way the Codex CLI does with its session id. A chat/completions client that sets its own key keeps it; an Anthropic-shape request gets one per Claude Code session (a hash of `metadata.user_id`, never the raw ids); anything else is keyed on its model, instructions and tool names, so repeated system prompts from any caller land together. The key also goes out as the `session-id` header (with `thread-id` and `x-codex-routing-hint: model=<model>`, as the Codex CLI sends them): the backend's cache lives on individual machines and that header is what routes a conversation's next turn to the machine holding its prefix; the body key alone does not. Cached tokens come back as `prompt_tokens_details.cached_tokens` on chat/completions and as `cache_read_input_tokens` on `/v1/messages`, and show up in `/analytics` and the `-v` usage line like a Claude request's do. When the share is lower than the conversation shape would predict, the [cache trace](./analytics.md#the-cache-trace) shows what may explain it: turns close enough together that the write may not yet have been readable, a rewritten history, a changed system prompt or tool names, or a changed seat.
 
 ## Failover between subscriptions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.17.2",
+  "version": "6.18.1",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, opt-in failover when one hits its limit, and a ledger of what each plan absorbed.",
   "type": "module",
   "bin": {