@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/dist/binary-probe.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Whether a backend's executable is on PATH, without blocking the fleet (#1490).
+ *
+ * `/ui/backends` used to run `execFileSync("which", …)` seven times per request, each with a 2 s timeout, on the fleet's
+ * event loop: up to ~14 s of blocking per request on a slow or broken PATH. The same `which` now runs as an
+ * asynchronous child process. Not an in-process fs walk: on a dead network mount `access`/`stat` can stay pending
+ * forever, each one holding a thread of the libuv pool the whole process shares (fs, DNS, crypto), and nothing can
+ * cancel it (#1498 review). A child is outside that pool and can be killed.
+ *
+ * Every probe answers within PROBE_DEADLINE_MS: the path, null (not on PATH), or unknown (no answer in time, `which`
+ * could not run, or no probe could be admitted). A child counts as running until it has actually exited, not until
+ * its deadline: at most one per binary and PROBE_MAX_RUNNING in all, so a PATH that hangs every lookup costs a fixed
+ * number of stuck processes, never one per request.
+ */
+export type ProbeResult = {
+    known: true;
+    path: string | null;
+} | {
+    known: false;
+};
+/** A running probe: its answer (path or null), a kill switch, and proof that the process is gone. */
+export interface ProbeChild {
+    answer: Promise<string | null>;
+    kill(): void;
+    exited: Promise<void>;
+}
+/** How long a known answer is reused: long enough that a polled route rarely probes, short enough to see installs. */
+export declare const BINARY_PROBE_TTL_MS = 30000;
+/** The old synchronous lookup's timeout, now a deadline on the answer instead of a block on the event loop. */
+export declare const PROBE_DEADLINE_MS = 2000;
+/** Probe processes that may exist at once, stuck ones included (the backend catalog has seven binaries). */
+export declare const PROBE_MAX_RUNNING = 8;
+/** `which <binary>` as a child process. */
+export declare function spawnWhich(binary: string): ProbeChild;
+/**
+ * One probe process: exit 0 with output → the first line, any other exit → null, failing to start → rejection.
+ * `exited` settles on `close` (or a spawn that never produced a process). Exported so tests can run one that hangs.
+ */
+export declare function spawnProbeCommand(command: string, args: string[]): ProbeChild;
+/**
+ * Probe answers per binary, reused for BINARY_PROBE_TTL_MS (monotonic clock); concurrent probes of one binary share
+ * one answer. `fresh: true` wants a lookup that starts after it asked (an install just ran): it skips the cached and
+ * the shared answer and accepts only a child spawned after its request, waiting (within its own deadline) for an older
+ * child of that binary to exit first. Callers that waited together share the next child. An answer is accepted only
+ * while the caller's deadline holds; the newest caller of a binary stores it, `invalidate()` discards what running
+ * probes learn, and an unknown answer is never cached.
+ *
+ * Bounded state (#1498 review): each child is subscribed to once, at spawn (its answer, its exit, and one kill timer at
+ * the deadline); a waiting caller is a removable entry with its own timer, gone when it is woken or its deadline
+ * passes. A child that never exits keeps its reservation (one per binary, PROBE_MAX_RUNNING in all), not the callers.
+ */
+export declare class BinaryProbe {
+    private readonly spawnProbe;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly deadlineMs;
+    private readonly maxRunning;
+    private cache;
+    private shared;
+    private newest;
+    private running;
+    private spawnSeq;
+    constructor(spawnProbe?: (binary: string) => ProbeChild, now?: () => number, ttlMs?: number, deadlineMs?: number, maxRunning?: number);
+    /** Never rejects; settles within the deadline. */
+    probe(binary: string, opts?: {
+        fresh?: boolean;
+    }): Promise<ProbeResult>;
+    /** Probe children not yet exited, stuck ones included: the physical cost the limits bound. */
+    get runningCount(): number;
+    /** Forget every answer (or one binary's); probes already running will not store theirs. */
+    invalidate(binary?: string): void;
+    private attempt;
+    /** The answer, taken (and stored by the newest caller); the loop has re-checked the caller's deadline just before. */
+    private accept;
+    private spawnSlot;
+    /** Until this child answers or exits (true), or the deadline passes (false); the caller is then forgotten. */
+    private waitOn;
+}
+/** The fleet process's shared probe. */
+export declare const binaryProbe: BinaryProbe;

package/dist/binary-probe.js

@@ -0,0 +1,182 @@
+import { spawn } from "node:child_process";
+/** How long a known answer is reused: long enough that a polled route rarely probes, short enough to see installs. */
+export const BINARY_PROBE_TTL_MS = 30_000;
+/** The old synchronous lookup's timeout, now a deadline on the answer instead of a block on the event loop. */
+export const PROBE_DEADLINE_MS = 2_000;
+/** Probe processes that may exist at once, stuck ones included (the backend catalog has seven binaries). */
+export const PROBE_MAX_RUNNING = 8;
+const UNKNOWN = { known: false };
+/** `which <binary>` as a child process. */
+export function spawnWhich(binary) {
+    return spawnProbeCommand("which", [binary]);
+}
+/**
+ * One probe process: exit 0 with output → the first line, any other exit → null, failing to start → rejection.
+ * `exited` settles on `close` (or a spawn that never produced a process). Exported so tests can run one that hangs.
+ */
+export function spawnProbeCommand(command, args) {
+    let markExited;
+    const exited = new Promise((resolve) => { markExited = resolve; });
+    let child;
+    const answer = new Promise((resolve, reject) => {
+        const proc = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+        child = proc;
+        let out = "";
+        proc.stdout?.setEncoding("utf8");
+        proc.stdout?.on("data", (chunk) => { if (out.length < 4096)
+            out += chunk; });
+        proc.once("error", (error) => {
+            reject(error);
+            if (proc.pid === undefined)
+                markExited();
+        });
+        proc.once("close", (code) => {
+            const first = out.trim().split("\n")[0];
+            resolve(code === 0 && first ? first : null); // the answer first, then the exit
+            markExited();
+        });
+    });
+    answer.catch(() => { });
+    return { answer, exited, kill: () => { try {
+            child?.kill("SIGKILL");
+        }
+        catch { /* already gone */ } } };
+}
+/**
+ * Probe answers per binary, reused for BINARY_PROBE_TTL_MS (monotonic clock); concurrent probes of one binary share
+ * one answer. `fresh: true` wants a lookup that starts after it asked (an install just ran): it skips the cached and
+ * the shared answer and accepts only a child spawned after its request, waiting (within its own deadline) for an older
+ * child of that binary to exit first. Callers that waited together share the next child. An answer is accepted only
+ * while the caller's deadline holds; the newest caller of a binary stores it, `invalidate()` discards what running
+ * probes learn, and an unknown answer is never cached.
+ *
+ * Bounded state (#1498 review): each child is subscribed to once, at spawn (its answer, its exit, and one kill timer at
+ * the deadline); a waiting caller is a removable entry with its own timer, gone when it is woken or its deadline
+ * passes. A child that never exits keeps its reservation (one per binary, PROBE_MAX_RUNNING in all), not the callers.
+ */
+export class BinaryProbe {
+    spawnProbe;
+    now;
+    ttlMs;
+    deadlineMs;
+    maxRunning;
+    cache = new Map();
+    shared = new Map();
+    newest = new Map();
+    running = new Map();
+    spawnSeq = 0;
+    constructor(spawnProbe = spawnWhich, now = () => performance.now(), ttlMs = BINARY_PROBE_TTL_MS, deadlineMs = PROBE_DEADLINE_MS, maxRunning = PROBE_MAX_RUNNING) {
+        this.spawnProbe = spawnProbe;
+        this.now = now;
+        this.ttlMs = ttlMs;
+        this.deadlineMs = deadlineMs;
+        this.maxRunning = maxRunning;
+    }
+    /** Never rejects; settles within the deadline. */
+    probe(binary, opts = {}) {
+        if (!opts.fresh) {
+            const joined = this.shared.get(binary);
+            if (joined)
+                return joined;
+            const cached = this.cache.get(binary);
+            if (cached && this.now() - cached.at < this.ttlMs)
+                return Promise.resolve({ known: true, path: cached.path });
+        }
+        const token = {};
+        this.newest.set(binary, token);
+        const minSeq = opts.fresh ? this.spawnSeq + 1 : 0;
+        const result = this.attempt(binary, token, minSeq, this.now() + this.deadlineMs).catch(() => UNKNOWN);
+        this.shared.set(binary, result);
+        void result.then(() => { if (this.shared.get(binary) === result)
+            this.shared.delete(binary); });
+        return result;
+    }
+    /** Probe children not yet exited, stuck ones included: the physical cost the limits bound. */
+    get runningCount() { return this.running.size; }
+    /** Forget every answer (or one binary's); probes already running will not store theirs. */
+    invalidate(binary) {
+        for (const map of [this.cache, this.shared, this.newest]) {
+            if (binary === undefined)
+                map.clear();
+            else
+                map.delete(binary);
+        }
+    }
+    async attempt(binary, token, minSeq, deadline) {
+        let target;
+        for (;;) {
+            // Re-checked on every step, so also when an answer is taken: one that arrives after the caller's deadline is not
+            // an answer, whichever of its event and the deadline timer ran first (#1498 review).
+            if (this.now() >= deadline)
+                return UNKNOWN;
+            if (target) {
+                if (target.answer)
+                    return this.accept(binary, token, target.answer);
+                if (!(await this.waitOn(target, deadline)))
+                    return UNKNOWN;
+                continue;
+            }
+            const slot = this.running.get(binary);
+            if (slot && slot.seq >= minSeq) {
+                target = slot;
+                continue;
+            } // started after we asked: share it
+            if (slot) {
+                if (!(await this.waitOn(slot, deadline)))
+                    return UNKNOWN;
+                continue;
+            } // an older child: let it go
+            if (this.running.size >= this.maxRunning)
+                return UNKNOWN;
+            target = this.spawnSlot(binary);
+        }
+    }
+    /** The answer, taken (and stored by the newest caller); the loop has re-checked the caller's deadline just before. */
+    accept(binary, token, answer) {
+        if (answer.known && this.newest.get(binary) === token)
+            this.cache.set(binary, { at: this.now(), path: answer.path });
+        return answer;
+    }
+    spawnSlot(binary) {
+        const slot = { seq: ++this.spawnSeq, child: this.spawnProbe(binary), answer: undefined, exited: false, waiters: new Set() };
+        this.running.set(binary, slot);
+        const wake = () => { for (const waiter of [...slot.waiters])
+            waiter(); };
+        // No answer by the deadline: kill it. It stays reserved until it has actually exited.
+        const kill = setTimeout(() => { if (!slot.answer)
+            slot.child.kill(); }, this.deadlineMs);
+        kill.unref?.();
+        const answered = slot.child.answer.then((path) => ({ known: true, path }), () => UNKNOWN);
+        void answered.then((answer) => {
+            clearTimeout(kill);
+            slot.answer ??= answer;
+            wake();
+        });
+        // An answer that settled before the exit is the answer; a child that exits without one answered unknown.
+        void slot.child.exited.then(() => Promise.race([answered, Promise.resolve(UNKNOWN)])).then((answer) => {
+            clearTimeout(kill);
+            slot.exited = true;
+            slot.answer ??= answer;
+            if (this.running.get(binary) === slot)
+                this.running.delete(binary);
+            wake();
+        });
+        return slot;
+    }
+    /** Until this child answers or exits (true), or the deadline passes (false); the caller is then forgotten. */
+    waitOn(slot, deadline) {
+        const remaining = deadline - this.now();
+        if (remaining <= 0)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const done = (woken) => { clearTimeout(timer); slot.waiters.delete(wake); resolve(woken); };
+            const wake = () => done(true);
+            const timer = setTimeout(() => done(false), remaining);
+            timer.unref?.();
+            slot.waiters.add(wake);
+        });
+    }
+}
+/** The fleet process's shared probe. */
+export const binaryProbe = new BinaryProbe();
+//# sourceMappingURL=binary-probe.js.map

package/dist/binary-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-probe.js","sourceRoot":"","sources":["../src/binary-probe.ts"],"names":[],"mappings":"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"}

package/dist/cache-analysis.d.ts

@@ -0,0 +1,92 @@
+/**
+ * #1468: the prompt-cache expiry analysis — pure, over a ledger (cache-ledger.ts). For a window [from, to]:
+ *
+ * - Each gap carries the TTL of the cache it sat on, as that session last wrote it: Claude Code's own write split
+ *   (1 hour, or 5 minutes), Codex's 30 minutes (GPT-5.6 and later). Sessions of one instance can differ.
+ * - An expired request: one that came after a gap longer than its TTL and had to write at least half of the context
+ *   the previous request left cached (the cache can outlive its TTL; then nothing was lost). What it rewrote, up to
+ *   that context, is the expiry's tokens; its cost is those tokens at the write rate minus what reading them would
+ *   have cost, at the returning request's own price tier.
+ * - Keep-warm, simulated: a ping at every I = TTL − TTL/10 after a request (t + k·I, k ≥ 1, up to and including
+ *   the moment the gap ends — floor(gap / I) of them), each reading the cached context at that context's own tier.
+ *   Only pings whose instant falls inside the window are counted. A gap that ended in an expired request inside the
+ *   window saves its expiry cost; any other gap only pays for its pings. After a session's last request the pings
+ *   are pure loss, up to the moment the next session of the instance starts, or the window ends.
+ * - Recommendation: on when the simulated pings cost less than the expiries they prevent (by a margin), else off.
+ *
+ * Money is list price (cache-prices.ts). If any model the window touches — requests, pinged contexts, idle tails —
+ * is missing from the table, the whole instance is weighed in input-price units instead (write 1.25x, 1-hour write
+ * 2x, read 0.1x, output 5x) and shows no dollars.
+ */
+import { type Rates } from "./cache-prices.js";
+import { type GapEvent, type Ledger } from "./cache-ledger.js";
+export type Backend = "claude" | "codex";
+export interface SimOptions {
+    rates: (model: string, prompt: number) => Rates;
+    from: number;
+    to: number;
+    /** Codex: use each event's measured write (the instance records real writes) rather than the estimate. */
+    measured: boolean;
+}
+export interface SimTail {
+    t: number;
+    ctx: number;
+    model: string;
+    ttl: number;
+    until: number;
+}
+export interface SimResult {
+    pastTtl: number;
+    expired: number;
+    rewriteTokens: number;
+    /** Expiry cost — and, below, every amount — in USD, or in input-price units when the instance is not priced. */
+    expiryCost: number;
+    pings: number;
+    pingCost: number;
+    tailPings: number;
+    tailCost: number;
+    /** What keep-warm would have saved, net of every ping. */
+    net: number;
+    /** A gap judged in this window used an estimated write (Codex's uncached input), not a recorded one. */
+    estimated: boolean;
+}
+export declare const UNITS: Rates;
+export declare const pingIntervalMs: (ttlSec: number) => number;
+/** Pings at t + k·I (k ≥ 1) no later than `end`, counted only where they fall inside [from, to]. */
+export declare function pingsBetween(t: number, end: number, intervalMs: number, from: number, to: number): number;
+/** The keep-warm simulation over a window's long gaps and its sessions' ends. */
+export declare function simulate(gaps: readonly GapEvent[], tails: readonly SimTail[], o: SimOptions): SimResult;
+/**
+ * Each session's end: its last request, until the next session of the instance starts (the earliest other session
+ * that starts at or after it — one that starts at the same instant leaves no idle time), or `to`.
+ */
+export declare function sessionTails(ledger: Ledger, to: number): SimTail[];
+/** Codex GPT-5.6 and later bill cache writes and keep a prefix 30 minutes. */
+export declare const isOpenAiTtlModel: (model: string) => boolean;
+export interface InstanceAnalysis {
+    requests: number;
+    /** The TTL the instance's latest session uses (each gap is judged by its own session's TTL). */
+    ttlSec: number;
+    /** Writes (and so expiries) are estimated: Codex records none. Also true for a Codex model whose TTL is assumed. */
+    estimate: boolean;
+    priced: boolean;
+    models: string[];
+    gapBuckets: number[];
+    sim: SimResult;
+    totalCost: number;
+    share: number | null;
+    recommendation: {
+        on: boolean;
+        reason: "quiet" | "never_expired" | "saves" | "costs_more";
+        pingsPerExpiry?: number;
+    };
+}
+export interface AnalyzeOptions {
+    backend: Backend;
+    from: number;
+    to: number;
+    rates?: (model: string, prompt: number) => Rates | null;
+}
+/** Requests in a window below this are too few to say anything. */
+export declare const MIN_REQUESTS = 3;
+export declare function analyzeLedger(ledger: Ledger, o: AnalyzeOptions): InstanceAnalysis;

package/dist/cache-analysis.js

@@ -0,0 +1,147 @@
+/**
+ * #1468: the prompt-cache expiry analysis — pure, over a ledger (cache-ledger.ts). For a window [from, to]:
+ *
+ * - Each gap carries the TTL of the cache it sat on, as that session last wrote it: Claude Code's own write split
+ *   (1 hour, or 5 minutes), Codex's 30 minutes (GPT-5.6 and later). Sessions of one instance can differ.
+ * - An expired request: one that came after a gap longer than its TTL and had to write at least half of the context
+ *   the previous request left cached (the cache can outlive its TTL; then nothing was lost). What it rewrote, up to
+ *   that context, is the expiry's tokens; its cost is those tokens at the write rate minus what reading them would
+ *   have cost, at the returning request's own price tier.
+ * - Keep-warm, simulated: a ping at every I = TTL − TTL/10 after a request (t + k·I, k ≥ 1, up to and including
+ *   the moment the gap ends — floor(gap / I) of them), each reading the cached context at that context's own tier.
+ *   Only pings whose instant falls inside the window are counted. A gap that ended in an expired request inside the
+ *   window saves its expiry cost; any other gap only pays for its pings. After a session's last request the pings
+ *   are pure loss, up to the moment the next session of the instance starts, or the window ends.
+ * - Recommendation: on when the simulated pings cost less than the expiries they prevent (by a margin), else off.
+ *
+ * Money is list price (cache-prices.ts). If any model the window touches — requests, pinged contexts, idle tails —
+ * is missing from the table, the whole instance is weighed in input-price units instead (write 1.25x, 1-hour write
+ * 2x, read 0.1x, output 5x) and shows no dollars.
+ */
+import { ratesFor } from "./cache-prices.js";
+import { GAP_BUCKETS } from "./cache-ledger.js";
+export const UNITS = { input: 1, read: 0.1, write5m: 1.25, write1h: 2, write: 1.25, output: 5 };
+const M = 1_000_000;
+export const pingIntervalMs = (ttlSec) => Math.round(ttlSec * 900);
+const writeRate = (r, ttlSec) => (ttlSec >= 3600 ? r.write1h : ttlSec <= 300 ? r.write5m : r.write);
+/** Pings at t + k·I (k ≥ 1) no later than `end`, counted only where they fall inside [from, to]. */
+export function pingsBetween(t, end, intervalMs, from, to) {
+    if (!(intervalMs > 0))
+        return 0;
+    const kMin = Math.max(1, Math.ceil((from - t) / intervalMs));
+    const kMax = Math.floor((Math.min(end, to) - t) / intervalMs);
+    return Math.max(0, kMax - kMin + 1);
+}
+/** The keep-warm simulation over a window's long gaps and its sessions' ends. */
+export function simulate(gaps, tails, o) {
+    const res = { pastTtl: 0, expired: 0, rewriteTokens: 0, expiryCost: 0, pings: 0, pingCost: 0, tailPings: 0, tailCost: 0, net: 0, estimated: false };
+    let saved = 0;
+    for (const [tEnd, gap, ctx, ctxModel, ttl, model, prompt, measured, estimated] of gaps) {
+        if (tEnd < o.from)
+            continue;
+        const start = tEnd - Math.round(gap * 1000);
+        const pings = pingsBetween(start, tEnd, pingIntervalMs(ttl), o.from, o.to);
+        if (pings) {
+            res.pings += pings;
+            res.pingCost += pings * ctx * o.rates(ctxModel, ctx).read / M;
+        }
+        if (tEnd > o.to || !(gap > ttl))
+            continue;
+        res.pastTtl++;
+        const useMeasured = o.measured && measured !== null;
+        if (!useMeasured)
+            res.estimated = true;
+        const rewrite = useMeasured ? measured : estimated;
+        const lost = Math.min(rewrite, ctx);
+        if (ctx > 0 && lost >= ctx / 2) {
+            const r = o.rates(model, prompt);
+            const cost = lost * (writeRate(r, ttl) - r.read) / M;
+            res.expired++;
+            res.rewriteTokens += lost;
+            res.expiryCost += cost;
+            saved += cost;
+        }
+    }
+    for (const tail of tails) {
+        const n = pingsBetween(tail.t, tail.until, pingIntervalMs(tail.ttl), o.from, o.to);
+        if (!n)
+            continue;
+        res.tailPings += n;
+        res.tailCost += n * tail.ctx * o.rates(tail.model, tail.ctx).read / M;
+    }
+    res.net = saved - res.pingCost - res.tailCost;
+    return res;
+}
+/**
+ * Each session's end: its last request, until the next session of the instance starts (the earliest other session
+ * that starts at or after it — one that starts at the same instant leaves no idle time), or `to`.
+ */
+export function sessionTails(ledger, to) {
+    const sessions = Object.values(ledger.files).filter((f) => f.last && f.first !== undefined).map((f) => ({ first: f.first, last: f.last }));
+    return sessions.map((s) => {
+        let until = to;
+        for (const o of sessions)
+            if (o !== s && o.first >= s.last.t && o.first < until)
+                until = o.first;
+        return { t: s.last.t, ctx: s.last.ctx, model: s.last.model, ttl: s.last.ttl, until };
+    });
+}
+/** Codex GPT-5.6 and later bill cache writes and keep a prefix 30 minutes. */
+export const isOpenAiTtlModel = (model) => /^gpt-(5\.(6|[7-9])|[6-9])/.test(model);
+/** Requests in a window below this are too few to say anything. */
+export const MIN_REQUESTS = 3;
+export function analyzeLedger(ledger, o) {
+    const listed = o.rates ?? ratesFor;
+    const inWindow = (h) => h + 3_600_000 > o.from && h <= o.to;
+    const tails = sessionTails(ledger, o.to);
+    const estimatedTotals = o.backend === "codex" && !ledger.writesSeen;
+    // One unit for the whole instance: dollars when every model that contributes to this window is priced — the
+    // window's requests, and whatever the simulation itself prices (a pinged context, an expired request, an idle tail).
+    // A probe run records exactly the models the simulation asks a rate for.
+    const requestModels = new Set();
+    for (const [hk, hour] of Object.entries(ledger.hours)) {
+        if (!inWindow(Number(hk)))
+            continue;
+        for (const mk of Object.keys(hour.m))
+            requestModels.add(mk.slice(0, mk.lastIndexOf("|")));
+    }
+    const touched = new Set(requestModels);
+    simulate(ledger.gaps, tails, { rates: (model) => { touched.add(model); return UNITS; }, from: o.from, to: o.to, measured: !estimatedTotals });
+    const priced = [...touched].every((m) => listed(m, 0) !== null);
+    const rates = (model, prompt) => (priced ? listed(model, prompt) : null) ?? UNITS;
+    const gapBuckets = new Array(GAP_BUCKETS).fill(0);
+    let requests = 0, totalCost = 0;
+    for (const [hk, hour] of Object.entries(ledger.hours)) {
+        if (!inWindow(Number(hk)))
+            continue;
+        hour.g.forEach((n, i) => { gapBuckets[i] += n; });
+        for (const [mk, [n, uncached, read, write5m, write1h, write, output]] of Object.entries(hour.m)) {
+            const bar = mk.lastIndexOf("|");
+            const model = mk.slice(0, bar), long = mk.slice(bar + 1) === "1";
+            requests += n;
+            const r = rates(model, long ? Number.MAX_SAFE_INTEGER : 0);
+            // Codex on GPT-5.6+ with no recorded writes: its uncached input is what got written (the estimate).
+            const uncachedRate = estimatedTotals && isOpenAiTtlModel(model) ? r.write : r.input;
+            totalCost += (uncached * uncachedRate + read * r.read + write5m * r.write5m + write1h * r.write1h + write * r.write + output * r.output) / M;
+        }
+    }
+    const sim = simulate(ledger.gaps, tails, { rates, from: o.from, to: o.to, measured: !estimatedTotals });
+    const latest = tails.reduce((a, t) => (!a || t.t > a.t ? t : a), null);
+    const ttlSec = latest ? latest.ttl : o.backend === "codex" ? 1800 : 3600;
+    const assumedTtl = o.backend === "codex" && [...requestModels].some((m) => !isOpenAiTtlModel(m));
+    let recommendation;
+    if (requests < MIN_REQUESTS)
+        recommendation = { on: false, reason: "quiet" };
+    else if (!sim.expired)
+        recommendation = { on: false, reason: "never_expired" };
+    else if (sim.net > 0 && sim.net >= sim.expiryCost * 0.1)
+        recommendation = { on: true, reason: "saves" };
+    else
+        recommendation = { on: false, reason: "costs_more", pingsPerExpiry: Math.round((sim.pings + sim.tailPings) / sim.expired) };
+    return {
+        // An estimate when anything shown used one: the totals (Codex with no recorded write), a gap's rewrite, a TTL.
+        requests, ttlSec, estimate: (estimatedTotals && requests > 0) || sim.estimated || assumedTtl, priced, models: [...requestModels].sort(), gapBuckets, sim,
+        totalCost, share: totalCost > 0 ? sim.expiryCost / totalCost : null, recommendation,
+    };
+}
+//# sourceMappingURL=cache-analysis.js.map

package/dist/cache-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-analysis.js","sourceRoot":"","sources":["../src/cache-analysis.ts"],"names":[],"mappings":"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"}

package/dist/cache-ledger.d.ts

@@ -0,0 +1,108 @@
+/**
+ * #1468: what the prompt-cache analysis keeps per instance — never the transcripts themselves. Each model request a
+ * CLI made (a Claude assistant message, a Codex `token_count`) becomes a "turn"; the ledger folds turns into:
+ * - hourly totals per model and price tier (requests and tokens: uncached input, cache reads, cache writes, output)
+ *   with the hour's histogram of gaps between consecutive requests of the same session;
+ * - one event per long gap (≥ GAP_EVENT_SEC): when it ended, how long it was, the context it left cached, what the
+ *   request after it wrote to the cache — all the keep-warm simulation needs;
+ * - per transcript file: where reading stopped (a line start), and the session's first and last request.
+ * That keeps a month of a busy fleet in kilobytes per instance, and a file is read once, incrementally.
+ *
+ * Usage fields (real shapes, checked 2026-10-09):
+ * - Claude Code: `message.usage` { input_tokens, cache_read_input_tokens, cache_creation_input_tokens,
+ *   cache_creation: { ephemeral_5m_input_tokens, ephemeral_1h_input_tokens }, output_tokens }. A message spans several
+ *   lines (one per content block) carrying the same id and usage: counted once.
+ * - Codex (0.160): `event_msg` `token_count` with `info.last_token_usage` { input_tokens (cached included),
+ *   cached_input_tokens, cache_write_input_tokens, output_tokens }. The write field exists but was 0 in every one of
+ *   38,551 real events on GPT-5.6+ models — so a write is estimated as the request's uncached input unless a real
+ *   write count shows up. The model comes from the preceding `turn_context`.
+ */
+import { type ScanLine } from "./cache-scan.js";
+export type TranscriptKind = "claude" | "codex";
+/** One model request, as the transcript records it. */
+export interface Turn {
+    t: number;
+    model: string;
+    /** Everything the request sent: uncached input + cache reads + cache writes. */
+    prompt: number;
+    uncached: number;
+    read: number;
+    write5m: number;
+    write1h: number;
+    /** An OpenAI cache write as recorded (null: not recorded, 0 included when the field is absent). */
+    write: number | null;
+    output: number;
+}
+/** Gap histogram edges, seconds: ≤5 min, ≤30 min, ≤1 h, ≤2 h, ≤6 h, ≤24 h, longer. */
+export declare const GAP_EDGES: readonly [300, 1800, 3600, 7200, 21600, 86400];
+export declare const GAP_BUCKETS: number;
+/** Gaps at least this long are kept one by one (the shortest keep-warm interval is a 5-minute TTL's 270 s). */
+export declare const GAP_EVENT_SEC = 240;
+export declare const KEEP_DAYS = 31;
+/** [requests, uncached, read, write5m, write1h, write, output] */
+export type HourTotals = [number, number, number, number, number, number, number];
+export interface HourAgg {
+    m: Record<string, HourTotals>;
+    g: number[];
+}
+/**
+ * One long gap: [tEnd, gapSec, contextCached, contextModel, ttlSec, model, promptAfter, measuredWrite, estimatedWrite].
+ * - `contextCached`/`contextModel`: what the previous request left cached, and its model — what a ping would read.
+ * - `ttlSec`: the TTL of that cache as the session last wrote it (Claude's own write split; Codex's 30 minutes).
+ * - `measuredWrite`: what the request after the gap recorded writing (Claude always; Codex its write field, 0
+ *   included, or null when the field is absent). `estimatedWrite`: Codex's uncached input — used only while the
+ *   instance has never recorded a real write (the field exists but stays 0 on the CLIs seen so far).
+ */
+export type GapEvent = [number, number, number, string, number, string, number, number | null, number];
+export interface SessionPoint {
+    t: number;
+    ctx: number;
+    model: string;
+    ttl: number;
+}
+export interface FileCursor {
+    kind: TranscriptKind;
+    ino: number;
+    offset: number;
+    first?: number;
+    last?: SessionPoint;
+    /** Claude: the TTL the session's latest cache write used (1 h or 5 min). */
+    ttl?: number;
+    /** The file size at which only an unfinished line was left: not read again until the file grows. */
+    stalled?: number;
+    /** Codex: the model of the latest turn_context; the last cumulative total (token_count repeats itself). */
+    model?: string;
+    total?: number;
+    /** Claude: ids of the last messages counted (one message spans several lines). */
+    ids?: string[];
+}
+export interface Ledger {
+    v: 2;
+    files: Record<string, FileCursor>;
+    hours: Record<string, HourAgg>;
+    gaps: GapEvent[];
+    /** A real OpenAI cache-write count was seen (Codex): writes are then measured, not estimated. */
+    writesSeen?: boolean;
+}
+export declare function emptyLedger(): Ledger;
+/** A ledger read back from disk; anything that is not one is a fresh ledger. */
+export declare function reviveLedger(raw: unknown): Ledger;
+export declare const hourOf: (t: number) => number;
+export declare const gapBucket: (sec: number) => number;
+/** The key hourly totals are kept under: the model, and whether the request paid its long-prompt row. */
+export declare const modelKey: (model: string, prompt: number) => string;
+/** Codex keeps a prefix 30 minutes (GPT-5.6 and later; assumed for any other Codex model, which is then an estimate). */
+export declare const CODEX_TTL_SEC = 1800;
+/** The TTL a Claude request's own cache writes used: its write split decides; no write leaves the session's as it was. */
+export declare function claudeTtlAfter(turn: Turn, current: number | undefined): number;
+/**
+ * Fold one turn into the ledger, in file order. Turns older than `cutoff` only move the session's last point (the
+ * next gap needs it); everything else is counted. Pure apart from mutating `ledger`.
+ */
+export declare function addTurn(ledger: Ledger, file: FileCursor, turn: Turn, cutoff: number): void;
+/** Drop what is older than `cutoff` (hours and gap events). */
+export declare function pruneLedger(ledger: Ledger, cutoff: number): void;
+/** The turn a Claude Code transcript line records, or null; a message already counted (`file.ids`) is null too. */
+export declare function claudeLine(line: ScanLine, file: FileCursor): Turn | null;
+/** The turn a Codex rollout line records, or null. A `turn_context` line updates the file's model. */
+export declare function codexLine(line: ScanLine, file: FileCursor): Turn | null;