waterplane 0.0.1 → 0.1.6

package/packages/host/dist/limitlog.js

@@ -0,0 +1,154 @@
+/**
+ * Is the account limit-blocked RIGHT NOW — asked of the CLI's own log, not of
+ * the screen.
+ *
+ * `limit.ts` reads the banner off a terminal, which is the only source when
+ * there is nothing else. Its blind spot is that a screen carries no date. The
+ * banner is the last thing a blocked session ever prints, so it stays in the
+ * scrollback tail for as long as that session sits idle — hours, or days. Every
+ * later scan re-reads it and re-affirms a block that ended long ago, and the
+ * bare clock time it carries ("resets 10pm") is resolved against TODAY, so a
+ * Wednesday wall reappears as a Friday one. Nothing then lifts it: while the
+ * session is quiet the banner never leaves the window, so the scan can only
+ * ever confirm.
+ *
+ * The CLI writes the same event down, and dates it. A rejected request lands in
+ * the conversation jsonl as a synthetic assistant turn carrying `quotaLimits`:
+ *
+ *   {"type":"assistant","timestamp":"…","message":{"model":"<synthetic>",…},
+ *    "quotaLimits":{"status":"rejected","resetsAt":1788465600,
+ *                   "rateLimitType":"five_hour",…}}
+ *
+ * That gives the two things a screen cannot: WHEN the wall was hit, and the
+ * reset as an INSTANT rather than a wall-clock time needing a zone and a date.
+ * And an ordinary assistant turn stamped after it is proof the account served
+ * this session again — the positive signal that lifts a block without anyone
+ * typing anything.
+ *
+ * Read-only, and never authoritative when it cannot read: a session whose
+ * conversation id is not known yet, a log that has not appeared, a tmux session
+ * adopted after a restart all answer `unknown`, and the caller keeps the screen
+ * heuristic it had before.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { stamp, toMs } from "./convlog.js";
+import { detectSpendText } from "./limit.js";
+/** How much of the log tail to read. A rejection is followed by very little —
+ *  the turn it killed ended there — so the answer is always near the end. */
+const MAX_READ = 512 * 1024;
+const UNKNOWN = { state: "unknown", rejectedAt: null, resetAt: null, weekly: false, spend: false, servedAt: null, clearedBy: null };
+/** Read the tail of a log. Null when it isn't there. */
+function tailLines(path) {
+    let st;
+    try {
+        st = statSync(path);
+    }
+    catch {
+        return null;
+    }
+    const start = Math.max(0, st.size - MAX_READ);
+    const len = st.size - start;
+    if (len <= 0)
+        return [];
+    const buf = Buffer.allocUnsafe(len);
+    const fd = openSync(path, "r");
+    try {
+        readSync(fd, buf, 0, len, start);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const lines = buf.toString("utf8").split("\n");
+    if (start > 0)
+        lines.shift(); // a tail read starts mid-record
+    return lines;
+}
+/**
+ * What the conversation log says about the account, as of `now`.
+ *
+ * Walks the tail BACKWARDS and stops at the newest of each of the two rows that
+ * matter, so an ordinary check costs one stat, one bounded read and a handful
+ * of `JSON.parse`s — cheap enough for the idle sweep to ask every minute about
+ * every blocked session.
+ */
+export function readLimitLog(path, now = Date.now()) {
+    const lines = tailLines(path);
+    if (!lines)
+        return UNKNOWN;
+    let rejectedAt = null;
+    let resetAt = null;
+    let weekly = false;
+    let spend = false;
+    let servedAt = null;
+    let sawRow = false;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line || line.charCodeAt(0) !== 123 /* { */)
+            continue;
+        const isQuota = rejectedAt == null && line.includes('"quotaLimits"');
+        const isAssistant = servedAt == null && line.includes('"assistant"');
+        // A spend wall is an API-error turn (`isApiErrorMessage`), not a quota row.
+        const isApiErr = rejectedAt == null && line.includes('"isApiErrorMessage":true');
+        if (!isQuota && !isAssistant && !isApiErr)
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        sawRow = true;
+        const q = row.quotaLimits;
+        if (rejectedAt == null && q && q.status === "rejected") {
+            rejectedAt = stamp(row) ?? now;
+            resetAt = toMs(q.resetsAt);
+            weekly = typeof q.rateLimitType === "string" && q.rateLimitType !== "five_hour";
+            continue;
+        }
+        if (rejectedAt == null && isApiErr && !q && row.isApiErrorMessage === true) {
+            const found = detectSpendText(rowText(row));
+            if (found.spend) {
+                rejectedAt = stamp(row) ?? now;
+                resetAt = found.resetAt;
+                spend = true;
+                continue;
+            }
+        }
+        // A REAL assistant turn. The rejection itself is written as one too, with
+        // `<synthetic>` for a model — counting that as service would make every
+        // block clear itself the instant it was recorded.
+        if (servedAt == null && row.type === "assistant") {
+            const model = row.message?.model;
+            if (model === "<synthetic>")
+                continue;
+            servedAt = stamp(row);
+        }
+        if (rejectedAt != null && servedAt != null)
+            break;
+    }
+    if (!sawRow)
+        return UNKNOWN;
+    // Blocked means: nothing has been served since the wall, and the wall's own
+    // reset instant has not passed. Both halves are needed — a session left
+    // sitting at a rejection serves nothing precisely BECAUSE nobody typed into
+    // it, so silence alone would keep a two-day-old block alive for ever.
+    const stale = resetAt != null && resetAt <= now;
+    const superseded = servedAt != null && rejectedAt != null && servedAt > rejectedAt;
+    const state = rejectedAt != null && !stale && !superseded ? "blocked" : "clear";
+    // Which of the three cleared it. `served` outranks `reset` when both hold:
+    // being served again is a fact about the account, where a passed instant is
+    // only a fact about the clock.
+    const clearedBy = state !== "clear" ? null : rejectedAt == null ? "none" : superseded ? "served" : "reset";
+    return { state, rejectedAt, resetAt, weekly, spend: spend && rejectedAt != null, servedAt, clearedBy };
+}
+/** The text of a synthetic assistant turn: a string, or the text blocks of its content. */
+function rowText(row) {
+    const c = row.message?.content;
+    if (typeof c === "string")
+        return c;
+    if (!Array.isArray(c))
+        return "";
+    return c.map((b) => (b && typeof b.text === "string" ? b.text : "")).filter(Boolean).join("\n");
+}
+//# sourceMappingURL=limitlog.js.map

package/packages/host/dist/limitlog.js.map

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

package/packages/host/dist/limitretry.d.ts

@@ -0,0 +1,135 @@
+/**
+ * **When to try a limit-blocked session again — and when to stop.**
+ *
+ * Lifted out of `SessionManager` as a pure decision for the reason
+ * `sessionSearch.ts` was: what it answers is arithmetic
+ * over four numbers, the failure it had was invisible on a screen, and the
+ * sentence worth having when it rots is "this cadence gives up before the reset
+ * it is waiting for" rather than "the session never came back".
+ *
+ * ── The failure this replaces ────────────────────────────────────────────────
+ *
+ * A WEEKLY wall was scheduled as *now + 5 s, then every ten minutes*, bounded by
+ * an attempts cap of 24. The 5 s had a good argument behind it — a weekly
+ * banner prints a bare clock time with no date, so the reset it resolves to is
+ * the wrong day, and a plan that has just been upgraded serves immediately, so
+ * probing is worth one attempt. The cadence behind it did not: twenty-four
+ * attempts ten minutes apart is under four hours, and a weekly window resets
+ * DAYS later. Every weekly wall therefore ran out of attempts on the same
+ * afternoon, emitted `gaveup`, and the conversation stayed shut until somebody
+ * reopened it by hand — while the phone had been told it would come back.
+ *
+ * Three rules replace it, and each one is a thing that was being conflated:
+ *
+ *  1. **A DATED reset is trusted, weekly or not.** What is unreliable is a bare
+ *     time scraped off a screen, not the instant the CLI recorded in its own log
+ *     (`limitlog.ts`'s `resetsAt`). Those were being thrown away together.
+ *  2. **Waiting is not churn.** With no dated reset the delay WIDENS —
+ *     `LADDER_MS` — instead of hammering a flat cadence: a few quick probes for
+ *     the cases that resolve immediately, then hours between attempts, which is
+ *     the right rate for something that resets next week.
+ *  3. **Patience is a CLOCK, not a count.** The attempts cap is a churn guard
+ *     and says nothing about how long a wall may last; `giveUpMs` is the bound
+ *     that means what "stop waiting" should mean. A session may now wait out a
+ *     weekly window and still stop rather than retrying for ever.
+ */
+/**
+ * The widening delay, by attempt index, when nobody has dated the reset.
+ *
+ * The first rung is short on purpose (an upgraded plan, or a banner left over
+ * from a wall that has already lifted, both answer immediately); the last is the
+ * cap, and it is the one that has to be small enough that the reset is not
+ * missed by much and large enough that a week costs tens of attempts rather than
+ * hundreds. Six hours puts the worst case at a quarter-day late on a window
+ * measured in days.
+ */
+export declare const LADDER_MS: readonly number[];
+export interface LimitRetryInput {
+    /** Attempts already spent on THIS block (`SessionLimit.attempts`). */
+    attempts: number;
+    /**
+     * The reset as an INSTANT, or null when nobody could date one.
+     *
+     * Null is the honest value for a screen-scraped weekly banner: its bare time
+     * resolves to today, which is the wrong day. A dated instant from the CLI's
+     * own log belongs here whether the window is weekly or five-hourly.
+     */
+    resetAt: number | null;
+    /** When this block started (`SessionLimit.blockedSince`). */
+    blockedSince: number;
+    now: number;
+    /** Host-wide hold-off: a resume that came back still blocked proves the wall
+     *  is up for the ACCOUNT, so no session's next attempt may precede it. */
+    holdUntil?: number;
+    /** Fire this long after the reset instant, so a clock a second fast does not
+     *  spend an attempt on a wall that is still up. */
+    buffer: number;
+    /**
+     * The FIRST rung, when something needs it shorter than five seconds.
+     *
+     * A knob for the same reason every other timing in this subsystem has one: an
+     * e2e cannot sit out a real cadence, and a test that waits for the production
+     * delay is a test nobody runs. Absent means `LADDER_MS[0]`; it never affects
+     * the rungs after it, so a shortened probe cannot turn the backoff into the
+     * flat cadence this module replaced.
+     */
+    probeMs?: number;
+    /**
+     * The whole ladder, when a caller has its own.
+     *
+     * `probeMs`'s argument, one rung further: a test about the SECOND wall cannot
+     * sit out a minute any more than one about the first can sit out five
+     * seconds. Absent means `LADDER_MS`, which is the only value production ever
+     * passes — an override short enough to be sat out is short enough to be the
+     * flat cadence this module exists to replace, so it belongs to tests.
+     */
+    ladder?: readonly number[];
+    /** Churn guard. It bounds how MANY times we try, never how long we wait. */
+    maxAttempts: number;
+    /** Patience. Past this much of one continuous block, stop. */
+    giveUpMs: number;
+}
+export type LimitRetry = {
+    kind: "at";
+    at: number;
+    why: "probe" | "reset" | "backoff";
+} | {
+    kind: "giveup";
+    why: string;
+};
+/**
+ * The next attempt for one blocked session, or the reason there is no next one.
+ *
+ * `why` on the `at` branch is what the log and the tests read: *probe* is the
+ * one cheap early try, *reset* is an instant somebody actually recorded, and
+ * *backoff* is the widening wait for a wall nobody dated.
+ */
+export declare function nextLimitAttempt(i: LimitRetryInput): LimitRetry;
+/**
+ * What a session that has just been REOPENED into a wall should count as: the
+ * block it was carrying, or a fresh one.
+ *
+ * Here rather than inline in `markLimitBlocked` because it is the rule that
+ * silently defeated everything above it. A reopened conversation re-blocks
+ * seconds later, and "a block beginning" zeroed `attempts` and stamped
+ * `blockedSince` now — so across a resurrection the backoff restarted at its
+ * shortest rung and the patience clock restarted at zero, every time. A weekly
+ * wall then reopened the conversation for days, hundreds of processes deep, and
+ * neither bound was ever reached because neither was ever more than one reopen
+ * old.
+ *
+ * Stale carries are dropped rather than trusted: a session that came back,
+ * worked for a week and met a NEW wall must not adopt the old one's clock and
+ * give up on arrival.
+ */
+export interface CarriedBlock {
+    attempts: number;
+    blockedSince: number;
+    /** When the carry was written — i.e. when the reopen happened. */
+    at: number;
+}
+export declare function adoptCarriedBlock(carried: CarriedBlock | undefined | null, now: number, carryMs: number): {
+    attempts: number;
+    blockedSince: number;
+    carried: boolean;
+};

package/packages/host/dist/limitretry.js

@@ -0,0 +1,115 @@
+/**
+ * **When to try a limit-blocked session again — and when to stop.**
+ *
+ * Lifted out of `SessionManager` as a pure decision for the reason
+ * `sessionSearch.ts` was: what it answers is arithmetic
+ * over four numbers, the failure it had was invisible on a screen, and the
+ * sentence worth having when it rots is "this cadence gives up before the reset
+ * it is waiting for" rather than "the session never came back".
+ *
+ * ── The failure this replaces ────────────────────────────────────────────────
+ *
+ * A WEEKLY wall was scheduled as *now + 5 s, then every ten minutes*, bounded by
+ * an attempts cap of 24. The 5 s had a good argument behind it — a weekly
+ * banner prints a bare clock time with no date, so the reset it resolves to is
+ * the wrong day, and a plan that has just been upgraded serves immediately, so
+ * probing is worth one attempt. The cadence behind it did not: twenty-four
+ * attempts ten minutes apart is under four hours, and a weekly window resets
+ * DAYS later. Every weekly wall therefore ran out of attempts on the same
+ * afternoon, emitted `gaveup`, and the conversation stayed shut until somebody
+ * reopened it by hand — while the phone had been told it would come back.
+ *
+ * Three rules replace it, and each one is a thing that was being conflated:
+ *
+ *  1. **A DATED reset is trusted, weekly or not.** What is unreliable is a bare
+ *     time scraped off a screen, not the instant the CLI recorded in its own log
+ *     (`limitlog.ts`'s `resetsAt`). Those were being thrown away together.
+ *  2. **Waiting is not churn.** With no dated reset the delay WIDENS —
+ *     `LADDER_MS` — instead of hammering a flat cadence: a few quick probes for
+ *     the cases that resolve immediately, then hours between attempts, which is
+ *     the right rate for something that resets next week.
+ *  3. **Patience is a CLOCK, not a count.** The attempts cap is a churn guard
+ *     and says nothing about how long a wall may last; `giveUpMs` is the bound
+ *     that means what "stop waiting" should mean. A session may now wait out a
+ *     weekly window and still stop rather than retrying for ever.
+ */
+/**
+ * The widening delay, by attempt index, when nobody has dated the reset.
+ *
+ * The first rung is short on purpose (an upgraded plan, or a banner left over
+ * from a wall that has already lifted, both answer immediately); the last is the
+ * cap, and it is the one that has to be small enough that the reset is not
+ * missed by much and large enough that a week costs tens of attempts rather than
+ * hundreds. Six hours puts the worst case at a quarter-day late on a window
+ * measured in days.
+ */
+export const LADDER_MS = [
+    5_000,
+    60_000,
+    5 * 60_000,
+    30 * 60_000,
+    2 * 3_600_000,
+    6 * 3_600_000,
+];
+/**
+ * The next attempt for one blocked session, or the reason there is no next one.
+ *
+ * `why` on the `at` branch is what the log and the tests read: *probe* is the
+ * one cheap early try, *reset* is an instant somebody actually recorded, and
+ * *backoff* is the widening wait for a wall nobody dated.
+ */
+export function nextLimitAttempt(i) {
+    // Patience first: a block that has lasted longer than anybody means by "it
+    // comes back at the reset" is over, whatever the attempt count says. Stated
+    // in whole hours because that is the unit the sentence is read in.
+    const blockedFor = i.now - i.blockedSince;
+    if (i.blockedSince > 0 && blockedFor >= i.giveUpMs) {
+        return { kind: "giveup", why: `blocked for ${Math.round(blockedFor / 3_600_000)}h — longer than this desktop waits out a usage limit` };
+    }
+    if (i.attempts >= i.maxAttempts) {
+        return { kind: "giveup", why: `${i.attempts} attempts on one block — stopping rather than retrying for ever` };
+    }
+    const floor = Math.max(i.now, i.holdUntil ?? 0);
+    // The two candidates, and the answer is the EARLIER of them.
+    //
+    //  - the ladder: when the next check-in would be if nobody had dated
+    //    anything. The first rung is short on purpose (an upgraded plan, or a
+    //    banner left over from a wall that has already lifted, both answer
+    //    immediately and cost one attempt to find out), and it widens from there.
+    //  - the reset: an instant somebody actually recorded, trusted whatever the
+    //    window is. A reset in the PAST is not an instant to wait for and falls
+    //    through to the ladder rather than firing in a loop.
+    //
+    // Taking the earlier is what keeps BOTH properties. Waiting only for the
+    // reset means a wall that lifts early — an upgraded plan, a reset parsed a
+    // day late — is never noticed; hammering only the ladder is the cadence that
+    // ran a weekly wall out of attempts in an afternoon. So: check in on the
+    // ladder while the reset is far away, and land exactly on the reset once it
+    // is the nearer of the two.
+    const ladder = i.ladder?.length ? i.ladder : LADDER_MS;
+    const rung = i.attempts === 0 && i.probeMs != null && i.probeMs > 0
+        ? i.probeMs
+        : ladder[Math.min(i.attempts, ladder.length - 1)];
+    const rungAt = i.now + rung;
+    const target = i.resetAt != null ? i.resetAt + i.buffer : null;
+    // **A reset we can sit out is sat out.** Within one slowest check-in of now,
+    // the instant IS the answer — second-guessing it would spend attempts at a
+    // wall somebody has already told us the end of, and typing `continue` at a
+    // live wall costs a queue slot and the host-wide hold-off behind it.
+    //
+    // Past that horizon the ladder runs underneath the wait instead, because the
+    // instant may be days out and a wall that lifts EARLY — an upgraded plan, a
+    // reset parsed a day late — would otherwise never be noticed. The attempt
+    // still lands exactly on the reset once it comes inside the horizon.
+    const horizon = ladder[ladder.length - 1];
+    const useReset = target != null && target > i.now && (target <= rungAt || target - i.now <= horizon);
+    const at = Math.max(floor, useReset ? target : rungAt);
+    return { kind: "at", at, why: useReset ? "reset" : i.attempts === 0 ? "probe" : "backoff" };
+}
+export function adoptCarriedBlock(carried, now, carryMs) {
+    if (carried && now - carried.at <= carryMs && carried.blockedSince > 0) {
+        return { attempts: carried.attempts, blockedSince: carried.blockedSince, carried: true };
+    }
+    return { attempts: 0, blockedSince: now, carried: false };
+}
+//# sourceMappingURL=limitretry.js.map

package/packages/host/dist/limitretry.js.map

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

package/packages/host/dist/livesources.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The ONE way a reader outside the session slices reaches a live session's
+ * `BackendSources` (`docs/analysis/backends-design.md` §2, WP1c).
+ *
+ * `deliver.ts`, `settle.ts`, `sessions/record.ts` and `sessions/ctxseries.ts`
+ * each ask a source for one fact — a landed prompt, the user turns since a
+ * delivery, the reader's document, the current fill — and none of them owns the
+ * channel that answers. The channel (attach, health, teardown) is the side
+ * channel slice's (`sessions/sidechannel.ts`, WP1b), so this module is a narrow
+ * LOOKUP the slice installs and the readers consult, the same singleton posture
+ * as `setCliHealth` / `setOpenDeliveries`:
+ *
+ *  - **Nothing installed ⇒ every lookup is null ⇒ every reader is exactly
+ *    today's.** That is the whole compatibility argument: a backend with no
+ *    `sources`, or a host whose slice has not wired this yet, takes the path it
+ *    always took, byte for byte.
+ *  - **A throwing lookup is a null**, never an exception into a delivery: a
+ *    source is a higher rung, and losing it can only cost the fact, never the
+ *    send.
+ *  - `channelUp` is asked only by `deliver.ts`, where a down channel would make
+ *    `landed` wait out its whole timeout for an answer it cannot give. The other
+ *    readers ask the source and trust its `null` — that is the source contract.
+ */
+import type { BackendSources, ChannelHealth, SourceSession } from "@waterplane/shared";
+/** One live session as the readers see its sources. */
+export interface LiveSource {
+    readonly session: SourceSession;
+    readonly sources: BackendSources;
+    /** The attached handle's health; null when no handle is attached (yet). */
+    health(): ChannelHealth | null;
+}
+export type LiveSourceLookup = (sessionId: string) => LiveSource | null;
+/** Installed by the side channel slice (or a test); null uninstalls. */
+export declare function setLiveSourceLookup(fn: LiveSourceLookup | null): void;
+/** The live session's sources, or null — never a throw. */
+export declare function liveSourceFor(sessionId: string): LiveSource | null;
+/** Is the channel attached and up? A handle that cannot say is not up. */
+export declare function channelUp(l: LiveSource): boolean;

package/packages/host/dist/livesources.js

@@ -0,0 +1,26 @@
+let lookup = null;
+/** Installed by the side channel slice (or a test); null uninstalls. */
+export function setLiveSourceLookup(fn) {
+    lookup = fn;
+}
+/** The live session's sources, or null — never a throw. */
+export function liveSourceFor(sessionId) {
+    if (!lookup)
+        return null;
+    try {
+        return lookup(sessionId) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Is the channel attached and up? A handle that cannot say is not up. */
+export function channelUp(l) {
+    try {
+        return l.health()?.state === "up";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=livesources.js.map

package/packages/host/dist/livesources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"livesources.js","sourceRoot":"","sources":["../src/livesources.ts"],"names":[],"mappings":"AAmCA,IAAI,MAAM,GAA4B,IAAI,CAAC;AAE3C,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CAAC,EAA2B;IAC7D,MAAM,GAAG,EAAE,CAAC;AACd,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC;QAAC,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;AAClE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,CAAa;IACrC,IAAI,CAAC;QAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AACpE,CAAC"}

package/packages/host/dist/localledger.d.ts

@@ -0,0 +1,69 @@
+import { type BackendTokensDoc, type TokenStatsDoc, type UserPriceTable } from "@waterplane/shared";
+/** `WATERPLANE_PRICES` (a path), else `<config dir>/prices.json`. */
+export declare function pricesFilePath(): string;
+/** The parsed table, its path, and what in it was refused. A missing file is an
+ *  empty table and NO problem — not having one is the normal case. */
+export declare function readUserPrices(): {
+    table: UserPriceTable;
+    file: string;
+};
+/**
+ * The NON-Anthropic models in Claude Code's own ledger, as a backend ledger —
+ * what `GET /api/tokenstats/claude-local` answers.
+ *
+ * claude-local is the same binary pointed at another runner, so its tokens are
+ * in the SAME jsonl logs this store reads: there is no second ledger to open,
+ * and a second tally would drift. This is a CUT of the one ledger by model id
+ * (`isAnthropicModel`), off the per-model buckets the store already keeps —
+ * `models` for the all-time split, `TokenDay.byModel` for the days. The Claude
+ * Code tab makes the complementary cut, so between them every token is shown
+ * exactly once and never summed across the two.
+ *
+ * `sessions` is ABSENT: a conversation is not per model, and a count of the
+ * logs a model appeared in is a different fact from what the field means.
+ *
+ * Money, per model, in this order: the backend's own catalogue says it runs on
+ * this machine (`zeroCost`) ⇒ 0 (`source: "local"`) — first, so a price glob
+ * written for a hosted twin cannot charge a loopback model; else `costOfAny`
+ * (the list, then the person's file); else a SENTENCE saying how to add a
+ * price. Never a guessed rate, never a $0 for "unknown".
+ */
+export declare function localSliceLedger(doc: TokenStatsDoc, opts: {
+    label: string;
+    prices: UserPriceTable;
+    pricesFile: string;
+    zeroCost: ReadonlySet<string>;
+    /** The models this backend owns (`modelOwner`); absent ⇒ every non-Anthropic model. */
+    keep?: (model: string) => boolean;
+}): BackendTokensDoc;
+/**
+ * Which claude-jsonl backend a non-Anthropic model's tokens belong to, when
+ * several write into Claude Code's one set of logs (claude-local, claude-endpoint).
+ *
+ * The first backend, in registry order, whose LIVE catalogue lists the model
+ * owns it; else the first whose REMEMBERED catalogue (`known`, what it listed
+ * before — `rememberCatalogues`) does; else the FIRST backend (claude-local: a
+ * model Ollama no longer has still ran somewhere other than Anthropic). The
+ * memory is what stops an endpoint's tokens migrating to the claude-local tab
+ * whenever that endpoint is unreachable and its live list is empty. So every
+ * token lands on exactly one tab — never on two, never summed.
+ */
+export declare function modelOwner(model: string, backends: ReadonlyArray<{
+    id: string;
+    ids: readonly string[];
+    known?: readonly string[];
+}>): string | null;
+/**
+ * Fold each backend's live catalogue into the remembered one (live ids first,
+ * then the older ones, capped) and hand back the sharers with `known` filled.
+ * A failed write keeps the in-memory memory and degrades to "remembered until
+ * restart" — never a throw on a statistics read.
+ */
+export declare function rememberCatalogues<T extends {
+    id: string;
+    ids: readonly string[];
+}>(stateDir: string, sharers: readonly T[]): Array<T & {
+    known: string[];
+}>;
+/** Test seam: forget the in-memory copy so the next read goes to disk. */
+export declare function forgetCatalogueCache(): void;