@ashlr/hub 3.8.0 → 3.9.0

package/dist/core/verse/adapters/grok.js

@@ -11,20 +11,42 @@
  * Parse: NDJSON in the Anthropic Messages API wire format (message_start,
  * content_block_start/delta/stop, message_delta{usage}, message_stop). The
  * parser is the shared Anthropic-stream parser, which also accepts claude's
- * `stream_event` wrapper and whole-message envelopes.
+ * `stream_event` wrapper and whole-message envelopes. Grok's terminal `result`
+ * carries `modelUsage.<key>.contextWindow` on the current model's row only
+ * (the key can differ from the CLI id — `grok-4.6-build` for `grok-4.6`), and
+ * a `system/compact_boundary` line marks an auto-compaction; the shared parser
+ * turns both into the usage event's window and a `compaction` event.
+ *
+ * V3.9 context. Grok has no per-invocation compaction budget flag, so there
+ * are no mode flags: it always runs its catalog budget (80% of 500k). Shared
+ * project memory reaches it as `--rules=<block>` — `--rules <RULES>` "Extra
+ * rules to append to the system prompt" (alias `--append-system-prompt`) is in
+ * `grok --help` on the pinned 0.2.118 binary. Grok can reach only `--cwd`, so
+ * the memory directory itself is never granted; the block carries the file's
+ * contents and says this seat may only read it (`writable: false`).
  */
+import { canonicalModelId } from '../context-math.js';
 import { createAnthropicStreamParser } from './claude.js';
+/** The launch record's memory block, when the snapshot is well-formed; anything else means memory off. */
+function launchMemoryBlock(launch) {
+    const memory = launch.memory;
+    if (typeof memory !== 'object' || memory === null)
+        return null;
+    const block = memory.block;
+    return typeof block === 'string' && block.trim().length > 0 ? block : null;
+}
 function buildGrokLaunch(session, text, launch) {
     if (!session.nativeSessionId) {
         throw new Error('grok session is missing its native session id');
     }
     const prefix = launch.launcher ? [...launch.launcher] : ['grok'];
+    const memoryBlock = launchMemoryBlock(launch);
     const argv = [
         ...prefix,
         '--output-format', 'streaming-messages-json',
         '--include-partial-messages',
         '--cwd', session.projectPath,
-        '--model', session.model,
+        '--model', canonicalModelId(session.model),
         // NOT 'acceptEdits'. Grok's acceptEdits auto-approves edits but NOT
         // `run_terminal_command`, and there is no interactive approver in a seat, so
         // the first shell command cancels the turn: measured
@@ -46,6 +68,10 @@ function buildGrokLaunch(session, text, launch) {
         // `workspaces.ts engineSupportsExtraRoots()` returns false for grok, so
         // the roots view marks the extras unreachable and says why, instead of
         // letting the operator believe the agent can see them.
+        // Shared project memory, the SAME snapshotted block every turn (cache-
+        // stable). The `=` spelling is the one clap accepts for a value that
+        // starts with `-`, exactly as for `--single` below.
+        ...(memoryBlock !== null ? [`--rules=${memoryBlock}`] : []),
         ...(session.turnCount > 0 ? ['--resume', session.nativeSessionId] : ['--session-id', session.nativeSessionId]),
         `--single=${text}`,
     ];

package/dist/core/verse/adapters/grok.js.map

@@ -1 +1 @@
-{"version":3,"file":"grok.js","sourceRoot":"","sources":["../../../../src/core/verse/adapters/grok.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE1D,SAAS,eAAe,CAAC,OAAqB,EAAE,IAAY,EAAE,MAAuB;IACnF,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG;QACX,GAAG,MAAM;QACT,iBAAiB,EAAE,yBAAyB;QAC5C,4BAA4B;QAC5B,OAAO,EAAE,OAAO,CAAC,WAAW;QAC5B,SAAS,EAAE,OAAO,CAAC,KAAK;QACxB,oEAAoE;QACpE,6EAA6E;QAC7E,qDAAqD;QACrD,0EAA0E;QAC1E,uEAAuE;QACvE,qEAAqE;QACrE,4EAA4E;QAC5E,mBAAmB,EAAE,SAAS;QAC9B,2EAA2E;QAC3E,sDAAsD;QACtD,EAAE;QACF,sEAAsE;QACtE,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,kDAAkD;QAClD,EAAE;QACF,wEAAwE;QACxE,uEAAuE;QACvE,uDAAuD;QACvD,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;QAC9G,YAAY,IAAI,EAAE;KACnB,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,WAAW,EAAE,eAAe;IAC5B,YAAY,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC;CAC9E,CAAC"}
+{"version":3,"file":"grok.js","sourceRoot":"","sources":["../../../../src/core/verse/adapters/grok.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE1D,0GAA0G;AAC1G,SAAS,iBAAiB,CAAC,MAAuB;IAChD,MAAM,MAAM,GAAY,MAAM,CAAC,MAAM,CAAC;IACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,KAAK,GAAI,MAA8B,CAAC,KAAK,CAAC;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7E,CAAC;AAED,SAAS,eAAe,CAAC,OAAqB,EAAE,IAAY,EAAE,MAAuB;IACnF,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG;QACX,GAAG,MAAM;QACT,iBAAiB,EAAE,yBAAyB;QAC5C,4BAA4B;QAC5B,OAAO,EAAE,OAAO,CAAC,WAAW;QAC5B,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC;QAC1C,oEAAoE;QACpE,6EAA6E;QAC7E,qDAAqD;QACrD,0EAA0E;QAC1E,uEAAuE;QACvE,qEAAqE;QACrE,4EAA4E;QAC5E,mBAAmB,EAAE,SAAS;QAC9B,2EAA2E;QAC3E,sDAAsD;QACtD,EAAE;QACF,sEAAsE;QACtE,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,kDAAkD;QAClD,EAAE;QACF,wEAAwE;QACxE,uEAAuE;QACvE,uDAAuD;QAEvD,uEAAuE;QACvE,qEAAqE;QACrE,oDAAoD;QACpD,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;QAC9G,YAAY,IAAI,EAAE;KACnB,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,WAAW,EAAE,eAAe;IAC5B,YAAY,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC;CAC9E,CAAC"}

package/dist/core/verse/adapters/index.d.ts

@@ -25,9 +25,41 @@ export interface VerseTurnParser {
     /** Vendor conversation id observed in the output (codex thread id, claude session id), or null. */
     nativeSessionId(): string | null;
 }
+/**
+ * V3.9 — what a telemetry hook gets. Hooks are the ONE place an adapter may
+ * read the filesystem: some CLIs (codex) never put exact per-call context on
+ * stdout, only in their own session files. Hooks must be bounded (tail reads,
+ * size caps), synchronous, fast, and must never throw.
+ */
+export interface VerseAdapterTurnContext {
+    session: VerseSession;
+    launch: VerseSeatLaunch;
+    turnId: string;
+    /** Epoch ms when the process was spawned. */
+    startedAt: number;
+    /** Native id observed so far this turn (parser), else the session's. */
+    nativeSessionId: string | null;
+    /** This turn's parser, for hooks that need what it captured. */
+    parser: VerseTurnParser;
+    /** Per-turn scratch the hooks own (e.g. a file offset); starts empty. */
+    state: Record<string, unknown>;
+}
 export interface VerseAdapter {
     buildLaunch(session: VerseSession, text: string, launch: VerseSeatLaunch): VerseTurnLaunch;
     createParser(turnId: string): VerseTurnParser;
+    /**
+     * V3.9, optional. Polled every VERSE_TELEMETRY_POLL_MS while a turn runs
+     * (live meter). Typically returns `context` events.
+     */
+    pollTelemetry?(ctx: VerseAdapterTurnContext): VerseParsedEvent[];
+    /**
+     * V3.9, optional. Called once after the process exits and AFTER the
+     * parser's `finish()` events were applied. Typically returns `context` and
+     * `compaction` events read from the CLI's own session files.
+     */
+    afterTurn?(ctx: VerseAdapterTurnContext): VerseParsedEvent[];
 }
+/** V3.9 — live telemetry poll interval for adapters that implement `pollTelemetry`. */
+export declare const VERSE_TELEMETRY_POLL_MS = 2000;
 export declare function adapterFor(engine: VerseEngine): VerseAdapter;
 export {};

package/dist/core/verse/adapters/index.js

@@ -14,6 +14,8 @@
 import { claudeAdapter } from './claude.js';
 import { codexAdapter } from './codex.js';
 import { grokAdapter } from './grok.js';
+/** V3.9 — live telemetry poll interval for adapters that implement `pollTelemetry`. */
+export const VERSE_TELEMETRY_POLL_MS = 2_000;
 export function adapterFor(engine) {
     switch (engine) {
         case 'claude':

package/dist/core/verse/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/verse/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAsBxC,MAAM,UAAU,UAAU,CAAC,MAAmB;IAC5C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,aAAa,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,YAAY,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,WAAW,CAAC;QACrB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,KAAK,GAAU,MAAM,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/verse/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAqDxC,uFAAuF;AACvF,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAE7C,MAAM,UAAU,UAAU,CAAC,MAAmB;IAC5C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,aAAa,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,YAAY,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,WAAW,CAAC;QACrB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,KAAK,GAAU,MAAM,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/verse/codex-rollout.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Codex rollout reader — the ONLY place Verse learns a codex turn's exact
+ * context occupancy, its window, its compactions and its true per-turn usage.
+ *
+ * WHY THIS EXISTS. `codex exec --json` never prints per-call usage or the
+ * window: its `turn.completed.usage` is a SUM over every model call in the
+ * turn (a 20-call turn reports ~20× the live prompt), and codex seeds that sum
+ * from the rollout when a thread is resumed, so on `exec resume` it is the
+ * THREAD's running total rather than the turn's. The CLI's own session file
+ * does carry the truth, one `token_count` per model call:
+ *
+ *   <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-<local ts>-<thread id>.jsonl
+ *     {"timestamp":…,"type":"event_msg","payload":{"type":"token_count","info":{
+ *        "total_token_usage":{…cumulative…},"last_token_usage":{…this call…},
+ *        "model_context_window":258400}}}
+ *     {"timestamp":…,"type":"event_msg","payload":{"type":"task_started","model_context_window":258400}}
+ *     {"timestamp":…,"type":"compacted","payload":{…replacement history, often MEGABYTES…}}
+ *     {"timestamp":…,"type":"token_usage_record","payload":{"thread_id":…,"turn_token_usage":{…}}}   (0.149+)
+ *
+ * (Shapes verified against 4,001 rollouts on this machine, CLI 0.136 – 0.155.)
+ *
+ * WHAT "OCCUPANCY" MEANS HERE. `last_token_usage.total_tokens` — the last
+ * call's prompt plus its reply. That is the quantity codex itself compares to
+ * its auto-compaction limit (no uncompacted call ever exceeded 244,800 = 90% of
+ * the raw 272k window, across 62,104 calls), and it is what the NEXT call's
+ * prompt starts from, so the meter and the compaction tick share one unit.
+ * Right after a compaction codex writes a `token_count` whose cumulative total
+ * is unchanged but whose `last_token_usage` is the post-compaction size — so a
+ * reading is taken from EVERY token_count, while usage is only summed for
+ * records whose cumulative total moved (a real model call).
+ *
+ * BOUNDS. A `compacted` line is routinely 2–17 MB (it embeds the replacement
+ * history), so nothing here ever holds a whole line in memory: lines are
+ * scanned in chunks and only their first CODEX_ROLLOUT_LINE_HEAD_BYTES are
+ * kept. The small records (token_count ≤ 1 KB) are parsed whole; an oversized
+ * line is classified from its head alone. First reads look at most
+ * CODEX_ROLLOUT_TAIL_BYTES back from EOF (doubling to a hard cap only when the
+ * turn's start is not in that window); incremental reads scan at most
+ * CODEX_ROLLOUT_MAX_SCAN_BYTES. A missing, pruned, rewritten or unreadable file
+ * yields null / "no reading" — nothing here throws.
+ *
+ * PRIVACY. Paths computed here name native-profile directories (account
+ * identity). They are used to read files and are never returned in events,
+ * logged, or persisted.
+ */
+/** First read of a rollout: at most this much from EOF (spec: ≤ 2 MB). */
+export declare const CODEX_ROLLOUT_TAIL_BYTES: number;
+/**
+ * When the turn's first record is not inside the first tail window (a turn
+ * that wrote megabytes before the first poll — i.e. an early compaction), the
+ * window doubles up to this cap. Past it the turn is accounted as partial.
+ */
+export declare const CODEX_ROLLOUT_MAX_TAIL_BYTES: number;
+/** One incremental read scans at most this much; beyond it the reader jumps to the tail and records a gap. */
+export declare const CODEX_ROLLOUT_MAX_SCAN_BYTES: number;
+/** Bytes of each line retained for classification. Every record we parse whole is far smaller. */
+export declare const CODEX_ROLLOUT_LINE_HEAD_BYTES: number;
+/** One usage block as codex writes it. `inputTokens` INCLUDES the cached portion. */
+export interface CodexTokenTotals {
+    inputTokens: number;
+    cachedInputTokens: number;
+    /** 0.155+ only; 0 when absent. */
+    cacheWriteInputTokens: number;
+    outputTokens: number;
+    reasoningOutputTokens: number;
+    totalTokens: number;
+}
+export type CodexRolloutRecord = {
+    kind: 'token-count';
+    /** Byte offset of the line — a stable identity for "already seen". */
+    offset: number;
+    /** Epoch ms from the record's `timestamp`, or null when absent/unparsable. */
+    at: number | null;
+    total: CodexTokenTotals;
+    last: CodexTokenTotals;
+    modelContextWindow: number | null;
+} | {
+    kind: 'task-started';
+    offset: number;
+    at: number | null;
+    modelContextWindow: number | null;
+} | {
+    kind: 'compacted';
+    offset: number;
+    at: number | null;
+} | {
+    kind: 'token-usage-record';
+    offset: number;
+    at: number | null;
+    threadId: string | null;
+    turn: CodexTokenTotals | null;
+};
+export interface CodexRolloutRead {
+    /** File size when the read started. */
+    size: number;
+    /** First byte the read considered. */
+    start: number;
+    /** Offset just past the last COMPLETE line consumed — where an incremental read resumes. */
+    end: number;
+    records: CodexRolloutRecord[];
+    /** True when bytes between `start` and `size` were skipped for the scan budget. */
+    skipped: boolean;
+}
+export declare const ZERO_CODEX_TOTALS: Readonly<CodexTokenTotals>;
+/** A codex usage block → totals, or null when it is not one. `total_tokens` falls back to input + output. */
+export declare function codexTotals(value: unknown): CodexTokenTotals | null;
+export declare function addCodexTotals(a: CodexTokenTotals, b: CodexTokenTotals): CodexTokenTotals;
+/** a − b, each bucket clamped at 0 (a counter that went backwards is a reset, never negative usage). */
+export declare function subtractCodexTotals(a: CodexTokenTotals, b: CodexTokenTotals): CodexTokenTotals;
+/**
+ * The live occupancy one `token_count` describes: its last call's
+ * `total_tokens` (prompt + reply), the figure codex compacts against.
+ */
+export declare function codexOccupancy(last: CodexTokenTotals): number;
+/**
+ * Complete records from the last `maxBytes` of a rollout (never more than
+ * CODEX_ROLLOUT_MAX_TAIL_BYTES). A line cut by the window start is dropped.
+ * Null when the file is missing or unreadable.
+ */
+export declare function readCodexRolloutTail(file: string, maxBytes?: number): CodexRolloutRead | null;
+/**
+ * Complete records from byte `from` to EOF, scanning at most `maxScanBytes`.
+ * Null when the file is missing, unreadable, or SHORTER than `from` (rewritten
+ * or truncated — the caller must start over rather than trust its offset).
+ */
+export declare function readCodexRolloutFrom(file: string, from: number, maxScanBytes?: number): CodexRolloutRead | null;
+/** What one read of a rollout says, in the shape the spec names. */
+export interface CodexRolloutSummary {
+    /** The LAST `token_count` in the window: occupancy and the window codex measured it against. */
+    lastTokenCount: {
+        /** `last_token_usage.total_tokens` — live occupancy (see file header). */
+        lastTotalTokens: number;
+        /** `last_token_usage.input_tokens` — that call's prompt alone. */
+        lastInputTokens: number;
+        modelContextWindow: number | null;
+        /** Cumulative `total_token_usage` at that point. */
+        total: CodexTokenTotals;
+    } | null;
+    /** `model_context_window` of the last `task_started` in the window. */
+    taskStartedWindow: number | null;
+    /** `compacted` records at or after `afterOffset`. */
+    compactions: number;
+    size: number;
+    end: number;
+}
+/**
+ * One-shot extraction from a rollout's tail (or from `afterOffset`, when
+ * given). Missing or pruned file → null; never throws.
+ */
+export declare function summarizeCodexRollout(file: string, opts?: {
+    afterOffset?: number;
+    maxBytes?: number;
+}): CodexRolloutSummary | null;
+/**
+ * The CODEX_HOME a seat's launcher pins, derived from the launcher argv the
+ * session was created with — the same `<profile>/launcher.mjs` ⇒
+ * `<profile>/native-state` relation `accounts.ts` (codexSessionRoots) and
+ * `mcp-seat-view.ts` use, preferring the profile's own `profile.json`
+ * `nativeStatePath` when it is readable.
+ *
+ * Null for a launcher-less seat: Verse never reads the unpinned global
+ * `~/.codex`, whose rollouts belong to other tools and other accounts.
+ */
+export declare function codexNativeStatePath(launcher: readonly string[] | null | undefined): string | null;
+export declare function isCodexThreadId(value: unknown): value is string;
+/** Creation time embedded in a UUIDv7 (first 48 bits, epoch ms), else null. */
+export declare function uuidV7Millis(id: string): number | null;
+export interface LocateCodexRolloutOptions {
+    /**
+     * Also run the bounded newest-first scan of every day directory when the
+     * id's own date does not hold the file. Callers polling every few seconds
+     * pass false after their first attempt so a missing file costs three
+     * `readdir`s, not hundreds.
+     */
+    fullScan?: boolean;
+}
+/**
+ * Path of the rollout for `threadId` under `<nativeStatePath>/sessions`, or
+ * null when there is none (never run, pruned, `--ephemeral`, unreadable).
+ *
+ * Cheap path first: a UUIDv7 id carries its creation instant, so the file is
+ * in that LOCAL day's directory (±1 day for a timezone change or a thread
+ * created just before midnight). Otherwise a bounded newest-first descent.
+ * If several files match (never observed), the most recently written wins.
+ */
+export declare function locateCodexRollout(nativeStatePath: string, threadId: string, opts?: LocateCodexRolloutOptions): string | null;
+/** Test seam: forget cached profile and rollout paths. */
+export declare function resetCodexRolloutCaches(): void;
+export interface CodexCompactionObservation {
+    /** Occupancy at the last reading before the compaction (this turn's or the previous turn's). */
+    preTokens: number | null;
+    /** Occupancy of the first reading after it; null until one is seen. */
+    postTokens: number | null;
+}
+/**
+ * Everything one turn has learned from its thread's rollout. Plain data, held
+ * in the adapter hook's per-turn `ctx.state`, advanced by
+ * `advanceCodexTurnTracker` on every poll and once more after the turn.
+ */
+export interface CodexTurnTracker {
+    file: string | null;
+    ino: number | null;
+    /** Where the next incremental read starts. */
+    offset: number;
+    /** `offset` lands inside a line (a skipped oversized line); drop up to the next newline. */
+    midLine: boolean;
+    /** The first read (turn-start discovery) has happened. */
+    initialized: boolean;
+    /** This turn's first record was located, so everything it wrote has been seen. */
+    regionFound: boolean;
+    /** Some bytes this turn wrote were skipped (scan budget / tail cap). Sums are then partial. */
+    gap: boolean;
+    /** Cumulative totals just before this turn; `ZERO` when the thread had none; null when unknown. */
+    baseline: CodexTokenTotals | null;
+    /** Cumulative `total_tokens` of the latest token_count seen — a record that repeats it is not a new call. */
+    prevTotalTokens: number | null;
+    /** Model calls this turn and the sum of their `last_token_usage`. */
+    calls: number;
+    callSum: CodexTokenTotals;
+    /** Cumulative totals at this turn's first and latest call (the first call's own usage alongside). */
+    firstCall: {
+        total: CodexTokenTotals;
+        last: CodexTokenTotals;
+    } | null;
+    lastTotals: CodexTokenTotals | null;
+    /** The CLI's own per-turn figure (0.149+ `token_usage_record.turn_token_usage`), when written. */
+    turnUsage: CodexTokenTotals | null;
+    /** The latest occupancy reading, and whether this turn produced it. */
+    reading: {
+        tokens: number;
+        window: number | null;
+        inTurn: boolean;
+        offset: number;
+    } | null;
+    /** `task_started.model_context_window` of this turn. */
+    taskStartedWindow: number | null;
+    compactions: CodexCompactionObservation[];
+}
+export declare function createCodexTurnTracker(): CodexTurnTracker;
+/**
+ * Bring a turn's tracker up to date with `file`. Returns false when the file
+ * cannot be read (the tracker keeps what it had). Bounded: one discovery of
+ * ≤ CODEX_ROLLOUT_MAX_TAIL_BYTES, then ≤ CODEX_ROLLOUT_MAX_SCAN_BYTES per call.
+ */
+export declare function advanceCodexTurnTracker(tracker: CodexTurnTracker, file: string, startedAtMs: number, threadId?: string | null): boolean;
+export type CodexTurnUsageSource = 
+/** The CLI's own per-turn record (0.149+). */
+'turn-record'
+/** Sum of every call this turn made, all of which were seen. */
+ | 'calls'
+/** `turn.completed.usage` as printed (a first turn, or a per-turn figure). */
+ | 'reported'
+/** `turn.completed.usage` was the thread's running total; the pre-turn total was subtracted. */
+ | 'reported-delta'
+/** Only part of the turn was seen; the calls that were. A lower bound. */
+ | 'calls-partial';
+export interface CodexTurnUsage {
+    totals: CodexTokenTotals;
+    source: CodexTurnUsageSource;
+}
+/**
+ * This turn's true usage, from the best evidence available.
+ *
+ * WHY `turn.completed` IS NOT TRUSTED ON ITS OWN: codex prints its session's
+ * `total_token_usage` there, and on `exec resume` that session is seeded from
+ * the rollout — so turn 5 reports turns 1–5. Summing it per turn (which is
+ * what the engine does with `usage` events) would count turn 1 five times.
+ * The rollout's per-call records are the ground truth either way; the printed
+ * figure is used only when the rollout cannot answer, and even then a figure
+ * that equals the rollout's running total is converted to a delta.
+ *
+ * Verified on this machine's rollouts (221 turns with a CLI per-turn record):
+ * the per-call sum equals codex's own `turn_token_usage` exactly on every
+ * fully observed turn WITHOUT a compaction; with one, the record is larger by
+ * that compaction request's usage, which codex never writes as a
+ * `token_count` (its running total does not move either). The record is
+ * therefore preferred when present (0.149+); on older CLIs no codex surface —
+ * rollout or stdout — counts compaction requests, and neither does this.
+ *
+ * @param reported   `turn.completed.usage` (null when the turn printed none)
+ * @param firstTurn  true when this turn STARTED the thread — its printed
+ *                   figure is per-turn by construction
+ */
+export declare function codexTurnUsage(tracker: CodexTurnTracker | null, reported: CodexTokenTotals | null, firstTurn: boolean): CodexTurnUsage | null;