tledger 0.3.1 → 0.4.0

package/lib/token-ledger-importer.mjs

@@ -15,7 +15,10 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import {
   access,
+  chmod,
+  lstat,
   mkdtemp,
+  open,
   readdir,
   rm,
   stat,
@@ -24,25 +27,94 @@ import { homedir, tmpdir } from "node:os";
 import {
   basename,
   extname,
+  relative,
   resolve,
 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
 import { DatabaseSync } from "node:sqlite";
+import { Readable, Transform } from "node:stream";
+import {
+  isMainThread,
+  parentPort,
+  Worker,
+  workerData,
+} from "node:worker_threads";
 
-import { writePrivateSnapshot } from "./token-ledger-snapshot.mjs";
+import { stagePrivateSnapshot } from "./token-ledger-snapshot.mjs";
+import {
+  containsLocalPath,
+  LOCAL_LABEL,
+  safeExportLabel,
+} from "./token-ledger-labels.mjs";
+import {
+  DURABLE_LEDGER_COMPACTED_RETENTION_DAYS,
+  DURABLE_LEDGER_RETENTION_DAYS,
+  DURABLE_LEDGER_SCHEMA_VERSION,
+  codexHomeFingerprint,
+  durableSourceId,
+  durableQuotaObservationKey,
+  normalizeQuotaObservationFields,
+  readDurableSourceContinuity,
+  resolveDurableLedgerPath,
+  updateDurableLedger,
+} from "./token-ledger-ledger.mjs";
+import {
+  QUOTA_IDENTITY_CONTRACT_VERSION,
+} from "./token-ledger-quota-contract.mjs";
+import {
+  calculateCodexPurchasedCredits,
+  CODEX_CREDIT_RATE_CARD_AS_OF,
+  CODEX_CREDIT_RATE_CARD_KIND,
+  CODEX_CREDIT_RATE_CARD_SCOPE,
+  CODEX_CREDIT_RATE_CARD_URL,
+  hasDetailedTokenBreakdown,
+  normalizeCodexCreditModel,
+} from "./token-ledger-rates.mjs";
+import {
+  collectionScope,
+  normalizeCollectionSince,
+} from "./token-ledger-collection.mjs";
 import {
   buildUsageBuckets,
+  checkedFiniteAdd,
+  checkedTokenPartitionAdd,
+  checkedTokenAdd,
+  isValidTokenValue,
+  MAX_SAFE_TOKEN_COUNT,
   SNAPSHOT_SCHEMA_VERSION,
+  splitUsageBucketsAtBoundaries,
+  tokenValue,
   usageBucketStats,
 } from "./token-ledger-usage.mjs";
-
-const RATE_CARD_AS_OF = "2026-08-17";
-const FAST_MODE_MULTIPLIER = 1.5;
-const RATE_CARD_URL = "https://help.openai.com/en/articles/20001106";
 const WEEK_MINUTES = 10_080;
+const SCAN_CONCURRENCY = 4;
+const USAGE_SPOOL_DIRECTORY = /^token-ledger-import-([1-9]\d*)-[A-Za-z0-9]{6}$/;
 const UUID_AT_END =
   /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+const RELEVANT_EVENT_TYPES = new Set([
+  "task_started",
+  "thread_settings_applied",
+  "token_count",
+]);
+const RELEVANT_CALL_TYPES = new Set([
+  "function_call",
+  "custom_tool_call",
+  "tool_search_call",
+  "web_search_call",
+  "image_generation_call",
+]);
+export const SOURCE_WATERMARK_VERSION = 1;
+export const SOURCE_COLLECTION_MAX_ATTEMPTS = 3;
+const SOURCE_MUTATION_ERROR_CODES = Object.freeze([
+  "ENOENT",
+  "ENOTDIR",
+  "EISDIR",
+  "ERR_SOURCE_IDENTITY_CHANGED",
+  "ERR_SOURCE_SIZE_CHANGED",
+  "ERR_SOURCE_CONTENT_CHANGED",
+]);
+const MAX_TRAILING_SCAN_BYTES = 1 * 1024 * 1024;
 
 function spoolText(value, maximumLength = 2_000) {
   try {
@@ -55,13 +127,119 @@ function spoolText(value, maximumLength = 2_000) {
 function spoolSource(value) {
   const descriptor = sourceDescriptor(value);
   if (descriptor.subagent) return '{"subagent":true}';
-  return descriptor.label || "";
+  if (containsLocalPath(descriptor.label)) return "/";
+  return safeExportLabel(descriptor.label, 80, "");
+}
+
+function spoolCwd(value) {
+  const path = spoolText(value).replaceAll("\\", "/").replace(/\/+$/, "");
+  return safeExportLabel(basename(path), 160, "");
+}
+
+function spoolGitOrigin(value) {
+  const origin = spoolText(value).trim();
+  return origin ? projectLabel("", origin) : "";
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM still proves that the PID exists. Only ESRCH is authoritative
+    // evidence that no process currently owns the spool namespace.
+    return error?.code !== "ESRCH";
+  }
+}
+
+export async function cleanupOrphanedUsageSpools({
+  tempDirectory = tmpdir(),
+  currentPid = process.pid,
+  currentUid = process.getuid?.(),
+  beforeRevalidate = null,
+} = {}) {
+  if (!Number.isSafeInteger(currentUid) || currentUid < 0) return 0;
+  let entries;
+  try {
+    entries = await readdir(tempDirectory, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const entry of entries) {
+    const match = String(entry.name).match(USAGE_SPOOL_DIRECTORY);
+    if (!match) continue;
+    const ownerPid = Number(match[1]);
+    if (
+      !Number.isSafeInteger(ownerPid) ||
+      ownerPid <= 0 ||
+      ownerPid === currentPid ||
+      processIsAlive(ownerPid)
+    ) continue;
+    const candidate = resolve(tempDirectory, entry.name);
+    let initial;
+    try {
+      initial = await lstat(candidate);
+    } catch {
+      continue;
+    }
+    if (
+      !initial.isDirectory() ||
+      initial.isSymbolicLink() ||
+      Number(initial.uid) !== currentUid
+    ) continue;
+
+    if (beforeRevalidate !== null) await beforeRevalidate(candidate);
+    // Revalidate the exact directory immediately before removal. Node's
+    // recursive rm unlinks symlinks rather than traversing them, and the
+    // inode check also refuses a root-path swap between inspection steps.
+    let current;
+    try {
+      current = await lstat(candidate);
+    } catch {
+      continue;
+    }
+    if (
+      !current.isDirectory() ||
+      current.isSymbolicLink() ||
+      Number(current.uid) !== currentUid ||
+      Number(current.dev) !== Number(initial.dev) ||
+      Number(current.ino) !== Number(initial.ino) ||
+      processIsAlive(ownerPid)
+    ) continue;
+    try {
+      await rm(candidate, { recursive: true, force: false });
+      removed += 1;
+    } catch {
+      // Cleanup is best-effort. The new private spool remains usable even if
+      // an orphan races away or local permissions prevent reclamation.
+    }
+  }
+  return removed;
 }
 
 async function createUsageSpool() {
-  const directory = await mkdtemp(resolve(tmpdir(), "token-ledger-import-"));
+  await cleanupOrphanedUsageSpools();
+  const directory = await mkdtemp(
+    resolve(tmpdir(), `token-ledger-import-${process.pid}-`),
+  );
   const path = resolve(directory, "usage.sqlite");
   const database = new DatabaseSync(path);
+  try {
+    await chmod(path, 0o600);
+  } catch (error) {
+    try {
+      database.close();
+    } catch {
+      // The chmod failure remains authoritative.
+    }
+    try {
+      await rm(directory, { recursive: true, force: true });
+    } catch {
+      // The chmod failure remains authoritative.
+    }
+    throw error;
+  }
   database.exec(`
     PRAGMA journal_mode = OFF;
     PRAGMA synchronous = OFF;
@@ -75,6 +253,11 @@ async function createUsageSpool() {
       output_tokens REAL NOT NULL,
       reasoning_tokens REAL NOT NULL,
       total_tokens REAL NOT NULL,
+      tool_calls REAL NOT NULL DEFAULT 0,
+      call_count REAL NOT NULL DEFAULT 1,
+      detailed_call_count REAL NOT NULL DEFAULT 1,
+      input_call_count REAL NOT NULL DEFAULT 1,
+      components_valid INTEGER NOT NULL,
       timestamp TEXT NOT NULL,
       thread_id TEXT NOT NULL,
       model TEXT NOT NULL,
@@ -83,7 +266,16 @@ async function createUsageSpool() {
       git_origin TEXT,
       raw_source TEXT,
       service_tier TEXT,
-      original_likely INTEGER NOT NULL
+      original_likely INTEGER NOT NULL,
+      project TEXT,
+      display_model TEXT,
+      source_label TEXT,
+      use_type TEXT,
+      rate_card_model TEXT,
+      rate_card_credits REAL,
+      identity_kind TEXT NOT NULL DEFAULT 'exact',
+      range_allocation_estimated INTEGER NOT NULL DEFAULT 0,
+      range_allocation_origin TEXT
     ) WITHOUT ROWID;
     CREATE TABLE tool_calls (
       call_key TEXT PRIMARY KEY,
@@ -109,9 +301,19 @@ async function createUsageSpool() {
     INSERT OR IGNORE INTO token_events (
       event_key, turn_id, input_tokens, cached_input_tokens,
       cache_write_input_tokens, output_tokens, reasoning_tokens,
-      total_tokens, timestamp, thread_id, model, effort, cwd,
-      git_origin, raw_source, service_tier, original_likely
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      total_tokens, tool_calls, call_count, detailed_call_count,
+      input_call_count, components_valid, timestamp, thread_id, model, effort,
+      cwd, git_origin, raw_source, service_tier, original_likely, project,
+      display_model, source_label, use_type, rate_card_model, rate_card_credits,
+      identity_kind, range_allocation_estimated, range_allocation_origin
+    ) VALUES (
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?, ?
+    )
   `);
   const promoteToken = database.prepare(`
     UPDATE token_events
@@ -120,6 +322,28 @@ async function createUsageSpool() {
            original_likely = 1
      WHERE event_key = ? AND original_likely = 0
   `);
+  const restoreTokenPlacement = database.prepare(`
+    UPDATE token_events
+       SET timestamp = ?, range_allocation_estimated = ?,
+           range_allocation_origin = ?
+     WHERE event_key = ?
+  `);
+  const enrichToken = database.prepare(`
+    UPDATE token_events
+       SET tool_calls = MAX(tool_calls, COALESCE(?, 0)),
+           project = COALESCE(project, ?),
+           display_model = COALESCE(display_model, ?),
+           source_label = COALESCE(source_label, ?),
+           use_type = COALESCE(use_type, ?),
+           rate_card_model = COALESCE(rate_card_model, ?),
+           rate_card_credits = COALESCE(rate_card_credits, ?),
+           identity_kind = COALESCE(identity_kind, ?),
+           range_allocation_estimated = MAX(
+             range_allocation_estimated, COALESCE(?, 0)
+           ),
+           range_allocation_origin = COALESCE(range_allocation_origin, ?)
+     WHERE event_key = ?
+  `);
   const insertCall = database.prepare(`
     INSERT OR IGNORE INTO tool_calls (
       call_key, turn_id, thread_id, original_likely
@@ -154,6 +378,7 @@ async function createUsageSpool() {
      WHERE turn_id = ?
   `);
   let writing = true;
+  const activeReadStatements = new Set();
 
   function originValues(candidate) {
     return [
@@ -165,8 +390,8 @@ async function createUsageSpool() {
         : Number.MAX_SAFE_INTEGER,
       spoolText(candidate.model, 200),
       spoolText(candidate.effort, 80),
-      spoolText(candidate.cwd),
-      spoolText(candidate.gitOrigin),
+      spoolCwd(candidate.cwd),
+      spoolGitOrigin(candidate.gitOrigin),
       spoolSource(candidate.rawSource),
       candidate.serviceTier == null
         ? null
@@ -193,7 +418,14 @@ async function createUsageSpool() {
         values[0],
       );
     },
-    insertToken(eventKey, turnId, usage, occurrence, originalLikely) {
+    insertToken(
+      eventKey,
+      turnId,
+      usage,
+      occurrence,
+      originalLikely,
+      metadata = {},
+    ) {
       const values = [
         eventKey,
         turnId,
@@ -203,17 +435,35 @@ async function createUsageSpool() {
         usage.outputTokens,
         usage.reasoningTokens,
         usage.totalTokens,
+        usage.toolCalls ?? 0,
+        metadata.callCount ?? 1,
+        metadata.detailedCallCount ?? (
+          hasDetailedTokenBreakdown(usage) ? 1 : 0
+        ),
+        metadata.inputCallCount ?? (usage.inputTokens > 0 ? 1 : 0),
+        usage.componentsValid ? 1 : 0,
         occurrence.timestamp,
         occurrence.threadId,
         spoolText(occurrence.model, 200),
         spoolText(occurrence.effort, 80),
-        spoolText(occurrence.cwd),
-        spoolText(occurrence.gitOrigin),
+        spoolCwd(occurrence.cwd),
+        spoolGitOrigin(occurrence.gitOrigin),
         spoolSource(occurrence.rawSource),
         occurrence.serviceTier == null
           ? null
           : spoolText(occurrence.serviceTier, 80),
         originalLikely ? 1 : 0,
+        metadata.project ?? null,
+        metadata.displayModel ?? null,
+        metadata.source ?? null,
+        metadata.useType ?? null,
+        metadata.rateCardModel ?? null,
+        metadata.rateCardCredits ?? null,
+        metadata.identityKind ?? "exact",
+        metadata.rangeAllocationEstimated ? 1 : 0,
+        metadata.rangeAllocationOrigin == null
+          ? null
+          : JSON.stringify(metadata.rangeAllocationOrigin),
       ];
       const inserted = insertToken.run(...values).changes > 0;
       if (!inserted && originalLikely) {
@@ -223,8 +473,8 @@ async function createUsageSpool() {
           occurrence.threadId,
           spoolText(occurrence.model, 200),
           spoolText(occurrence.effort, 80),
-          spoolText(occurrence.cwd),
-          spoolText(occurrence.gitOrigin),
+          spoolCwd(occurrence.cwd),
+          spoolGitOrigin(occurrence.gitOrigin),
           spoolSource(occurrence.rawSource),
           occurrence.serviceTier == null
             ? null
@@ -232,8 +482,35 @@ async function createUsageSpool() {
           eventKey,
         );
       }
+      if (!inserted && metadata && Object.keys(metadata).length > 0) {
+        enrichToken.run(
+          usage.toolCalls ?? 0,
+          metadata.project ?? null,
+          metadata.displayModel ?? null,
+          metadata.source ?? null,
+          metadata.useType ?? null,
+          metadata.rateCardModel ?? null,
+          metadata.rateCardCredits ?? null,
+          metadata.identityKind ?? null,
+          metadata.rangeAllocationEstimated ? 1 : 0,
+          metadata.rangeAllocationOrigin == null
+            ? null
+            : JSON.stringify(metadata.rangeAllocationOrigin),
+          eventKey,
+        );
+      }
       return inserted;
     },
+    restoreTokenPlacement(eventKey, occurrence, metadata = {}) {
+      return restoreTokenPlacement.run(
+        occurrence.timestamp,
+        metadata.rangeAllocationEstimated ? 1 : 0,
+        metadata.rangeAllocationOrigin == null
+          ? null
+          : JSON.stringify(metadata.rangeAllocationOrigin),
+        eventKey,
+      ).changes > 0;
+    },
     insertCall(callKey, turnId, threadId, originalLikely) {
       const inserted = insertCall.run(
         callKey,
@@ -250,8 +527,11 @@ async function createUsageSpool() {
       database.exec("COMMIT");
       writing = false;
     },
-    tokenRows() {
-      return database.prepare(`
+    *tokenRows() {
+      // Node 22 does not keep StatementSync alive through a bare iterator.
+      // Keep an explicit heap reference until iteration has completed; a
+      // generator-local reference alone can still be finalized on long scans.
+      const statement = database.prepare(`
         SELECT token.event_key AS eventKey, token.turn_id AS turnId,
                token.input_tokens AS inputTokens,
                token.cached_input_tokens AS cachedInputTokens,
@@ -259,12 +539,26 @@ async function createUsageSpool() {
                token.output_tokens AS outputTokens,
                token.reasoning_tokens AS reasoningTokens,
                token.total_tokens AS totalTokens,
+               token.tool_calls AS toolCalls,
+               token.call_count AS callCount,
+               token.detailed_call_count AS detailedCallCount,
+               token.input_call_count AS inputCallCount,
+               token.components_valid AS componentsValid,
                token.timestamp, token.thread_id AS threadId,
                token.model, token.effort, token.cwd,
                token.git_origin AS gitOrigin,
                token.raw_source AS rawSource,
                token.service_tier AS serviceTier,
                token.original_likely AS originalLikely,
+               token.project,
+               token.display_model AS displayModel,
+               token.source_label AS sourceLabel,
+               token.use_type AS useType,
+               token.rate_card_model AS rateCardModel,
+               token.rate_card_credits AS rateCardCredits,
+               token.identity_kind AS identityKind,
+               token.range_allocation_estimated AS rangeAllocationEstimated,
+               token.range_allocation_origin AS rangeAllocationOrigin,
                origin.thread_id AS originThreadId,
                origin.timestamp AS originTimestamp,
                origin.model AS originModel,
@@ -276,15 +570,31 @@ async function createUsageSpool() {
           FROM token_events AS token
           LEFT JOIN turn_origins AS origin ON origin.turn_id = token.turn_id
          ORDER BY token.timestamp, token.event_key
-      `).iterate();
+      `);
+      activeReadStatements.add(statement);
+      try {
+        for (const row of statement.iterate()) {
+          yield repairTokenTimestamp(row);
+        }
+      } finally {
+        activeReadStatements.delete(statement);
+      }
     },
-    callRows() {
-      return database.prepare(`
-        SELECT call.turn_id AS turnId,
+    *callRows() {
+      const statement = database.prepare(`
+        SELECT call.call_key AS callKey,
+               call.turn_id AS turnId,
+               call.original_likely AS originalLikely,
                COALESCE(origin.thread_id, call.thread_id) AS threadId
           FROM tool_calls AS call
           LEFT JOIN turn_origins AS origin ON origin.turn_id = call.turn_id
-      `).iterate();
+      `);
+      activeReadStatements.add(statement);
+      try {
+        yield* statement.iterate();
+      } finally {
+        activeReadStatements.delete(statement);
+      }
     },
     close() {
       if (writing) {
@@ -300,18 +610,6 @@ async function createUsageSpool() {
   };
 }
 
-const RATE_CARD = {
-  "gpt-5.6-sol": { input: 125, cached: 12.5, output: 750 },
-  "gpt-5.6-terra": { input: 50, cached: 5, output: 300 },
-  "gpt-5.6-luna": { input: 5, cached: 0.5, output: 30 },
-  "gpt-5.5": { input: 125, cached: 12.5, output: 750 },
-  "gpt-5.5-cyber": { input: 500, cached: 50, output: 3_000 },
-  "gpt-5.4": { input: 62.5, cached: 6.25, output: 375 },
-  "gpt-5.4-mini": { input: 18.75, cached: 1.875, output: 113 },
-  "gpt-5.3-codex": { input: 43.75, cached: 4.375, output: 350 },
-  "gpt-5.2": { input: 43.75, cached: 4.375, output: 350 },
-};
-
 function usage() {
   return `Token Ledger local collector
 
@@ -319,21 +617,25 @@ Usage:
   node token-ledger-importer.mjs [options]
 
 Options:
-  --output <file>       Snapshot destination (default: token-ledger-snapshot-v2.json.gz)
+  --output <file>       Snapshot destination (default: token-ledger-snapshot-v3.json.gz)
   --codex-home <dir>    Codex data root (default: CODEX_HOME or ~/.codex)
-  --since <ISO date>    Ignore model calls before this timestamp
+  --since <ISO timestamp> Ignore model calls before this timestamp
   --no-archived         Skip archived_sessions
   --help                Show this help
 
 The snapshot contains usage metadata and Codex display titles only. It never
 contains message bodies, tool payloads, reasoning text, credential fields, or
-full local paths in its output. Codex display titles may contain user-written
-text.`;
+full local paths in its output. Path-like source labels are categorized, and
+local path tokens in other labels are redacted. Codex display titles may still
+contain unrelated user-written text. Refreshes also update the app-owned
+durable ledger in ~/.token-ledger. Selecting another snapshot output never
+relocates SQLite state.
+The ledger retains committed observations when source files later disappear.`;
 }
 
 function parseArgs(argv) {
   const options = {
-    output: resolve("token-ledger-snapshot-v2.json.gz"),
+    output: resolve("token-ledger-snapshot-v3.json.gz"),
     codexHome: resolve(process.env.CODEX_HOME || `${homedir()}/.codex`),
     includeArchived: true,
     since: null,
@@ -355,10 +657,8 @@ function parseArgs(argv) {
       options.codexHome = resolve(value);
     } else if (argument === "--since") {
       const value = argv[++index];
-      if (!value || Number.isNaN(new Date(value).getTime())) {
-        throw new Error("--since requires a valid ISO date.");
-      }
-      options.since = new Date(value);
+      if (!value) throw new Error("--since requires a valid ISO timestamp.");
+      options.since = new Date(normalizeCollectionSince(value));
     } else {
       throw new Error(`Unknown option: ${argument}`);
     }
@@ -389,9 +689,10 @@ function safeIso(value, fallback = null) {
 }
 
 function tokenTuple(value) {
-  // token_count payloads arrive from untrusted JSONL. Read the named usage
-  // fields once and coerce each to a finite count so malformed records
-  // contribute zeros instead of leaking odd shapes downstream.
+  // token_count payloads arrive from untrusted JSONL. Token counts are kept
+  // only when they are primitive, non-negative safe integers. Invalid
+  // components become unknown breakdown values; the total is validated by the
+  // caller before the record enters the usage spool.
   const {
     input_tokens: inputTokens,
     cached_input_tokens: cachedInputTokens,
@@ -400,76 +701,40 @@ function tokenTuple(value) {
     reasoning_output_tokens: reasoningOutputTokens,
     total_tokens: totalTokens,
   } = value ?? {};
-  return [
-    asFiniteNumber(inputTokens),
-    asFiniteNumber(cachedInputTokens),
-    asFiniteNumber(cacheWriteInputTokens),
-    asFiniteNumber(outputTokens),
-    asFiniteNumber(reasoningOutputTokens),
-    asFiniteNumber(totalTokens),
+  const rawValues = [
+    inputTokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    outputTokens,
+    reasoningOutputTokens,
+    totalTokens,
   ];
+  return {
+    values: rawValues.map((value) => tokenValue(value)),
+    valid: rawValues.map((value, index) =>
+      index < 5 && value === undefined
+        ? true
+        : isValidTokenValue(value)),
+  };
 }
 
 function usageFromTuple(tuple) {
   // Cached input is a subset of input and reasoning is a subset of output.
   // Clamp at export so one out-of-range source record cannot skew subset
   // math downstream.
-  const inputTokens = tuple[0];
-  const outputTokens = tuple[3];
+  const inputTokens = tuple.values[0];
+  const outputTokens = tuple.values[3];
   return {
     inputTokens,
-    cachedInputTokens: Math.min(inputTokens, tuple[1]),
-    cacheWriteInputTokens: tuple[2],
+    cachedInputTokens: Math.min(inputTokens, tuple.values[1]),
+    cacheWriteInputTokens: tuple.values[2],
     outputTokens,
-    reasoningTokens: Math.min(outputTokens, tuple[4]),
-    totalTokens: tuple[5],
+    reasoningTokens: Math.min(outputTokens, tuple.values[4]),
+    totalTokens: tuple.values[5],
+    componentsValid: tuple.valid.slice(0, -1).every(Boolean),
   };
 }
 
-function hasDetailedBreakdown(usage) {
-  if (usage.totalTokens === 0) return true;
-  return (
-    usage.inputTokens + usage.outputTokens === usage.totalTokens &&
-    (usage.inputTokens > 0 || usage.outputTokens > 0)
-  );
-}
-
-function normalizeModel(model) {
-  // Collapse underscore and whitespace separators to dashes so variants like
-  // "gpt-5.4 mini" resolve to their own rate-card entry instead of falling
-  // back to the base model's higher rate. Keep in lockstep with
-  // normalizeModel in bin/token-ledger-rates.mjs.
-  const value = String(model || "unknown")
-    .trim()
-    .toLowerCase()
-    .replace(/[\s_]+/g, "-");
-  if (RATE_CARD[value]) return value;
-  if (value.startsWith("gpt-5.6-sol")) return "gpt-5.6-sol";
-  if (value.startsWith("gpt-5.6-terra")) return "gpt-5.6-terra";
-  if (value.startsWith("gpt-5.6-luna")) return "gpt-5.6-luna";
-  if (value.startsWith("gpt-5.5-cyber")) return "gpt-5.5-cyber";
-  if (value.startsWith("gpt-5.5")) return "gpt-5.5";
-  if (value.startsWith("gpt-5.4-mini")) return "gpt-5.4-mini";
-  if (value.startsWith("gpt-5.4")) return "gpt-5.4";
-  if (value.startsWith("gpt-5.3-codex")) return "gpt-5.3-codex";
-  if (value.startsWith("gpt-5.2")) return "gpt-5.2";
-  return value || "unknown";
-}
-
-function creditsForUsage(model, usage) {
-  if (!hasDetailedBreakdown(usage)) return null;
-  const rate = RATE_CARD[normalizeModel(model)];
-  if (!rate) return null;
-  const cached = Math.min(usage.inputTokens, usage.cachedInputTokens);
-  const uncached = Math.max(0, usage.inputTokens - cached);
-  return (
-    (uncached * rate.input +
-      cached * rate.cached +
-      usage.outputTokens * rate.output) /
-    1_000_000
-  );
-}
-
 function primitiveString(value) {
   try {
     const text = String.prototype.valueOf.call(value);
@@ -479,6 +744,12 @@ function primitiveString(value) {
   }
 }
 
+function liveRecordTimestamp(value) {
+  const source = primitiveString(value);
+  if (source === null || source.length === 0) return null;
+  return safeIso(source, null);
+}
+
 function sourceDescriptor(value) {
   // Thread sources reach us in two representations: rollout session_meta
   // lines carry parsed JSON (a label string or an object with subagent
@@ -503,6 +774,9 @@ function sourceDescriptor(value) {
 
 function sourceLabels(threadSource, rawSource) {
   const source = sourceDescriptor(rawSource);
+  const safeThreadSource = safeExportLabel(threadSource, 40, "");
+  const localThreadSource = containsLocalPath(threadSource);
+  const localRawSource = containsLocalPath(source.label);
   if (threadSource === "subagent" || source.subagent) {
     return { source: "subagent", useType: "subagent" };
   }
@@ -516,13 +790,21 @@ function sourceLabels(threadSource, rawSource) {
   if (source.label === "vscode") {
     return { source: "desktop", useType: "interactive" };
   }
+  if (localThreadSource || localRawSource) {
+    return {
+      source: LOCAL_LABEL,
+      useType: localThreadSource
+        ? LOCAL_LABEL
+        : safeThreadSource || "interactive",
+    };
+  }
   if (source.label) {
     return {
-      source: source.label.slice(0, 40),
-      useType: threadSource || "interactive",
+      source: safeExportLabel(source.label, 40, "unknown"),
+      useType: safeThreadSource || "interactive",
     };
   }
-  return { source: "unknown", useType: threadSource || "unknown" };
+  return { source: "unknown", useType: safeThreadSource || "unknown" };
 }
 
 function cleanRemote(value) {
@@ -542,17 +824,40 @@ function cleanRemote(value) {
   }
 }
 
+function isRemoteOrigin(value) {
+  const remote = spoolText(value).trim();
+  return (
+    /^(?:https?|git|ssh|git\+ssh):\/\//i.test(remote) ||
+    /^[^@\s/:]+@[^:\s/]+:.+$/.test(remote)
+  );
+}
+
 function projectLabel(cwd, gitOrigin) {
   const remote = cleanRemote(gitOrigin);
+  if (remote && isRemoteOrigin(gitOrigin)) {
+    const parts = remote.split("/").filter(Boolean);
+    return safeExportLabel(
+      parts.slice(-2).join("/"),
+      160,
+      "Unknown project",
+    );
+  }
+  if (containsLocalPath(gitOrigin)) return LOCAL_LABEL;
   if (remote) {
     const parts = remote.split("/").filter(Boolean);
-    return parts.slice(-2).join("/") || "Unknown project";
+    return safeExportLabel(
+      parts.slice(-2).join("/"),
+      160,
+      "Unknown project",
+    );
   }
-  const path = String(cwd || "").replaceAll("\\", "/").replace(/\/+$/, "");
+  const path = spoolText(cwd).replaceAll("\\", "/").replace(/\/+$/, "");
   const worktree = path.match(/\/\.codex\/worktrees\/[^/]+\/([^/]+)$/);
-  if (worktree) return worktree[1];
+  if (worktree) return safeExportLabel(worktree[1], 160, "Unknown project");
   const name = basename(path);
-  return name && name !== "." && name !== "/" ? name : "Unknown project";
+  return name && name !== "." && name !== "/"
+    ? safeExportLabel(name, 160, "Unknown project")
+    : "Unknown project";
 }
 
 function safeTitle(row, sessionTitle) {
@@ -565,18 +870,16 @@ function safeTitle(row, sessionTitle) {
     candidate.includes("<codex_delegation>") ||
     (subagent && candidate.length > 120)
   ) {
-    if (row?.agent_nickname) return `Subagent · ${row.agent_nickname}`;
+    if (row?.agent_nickname) {
+      return safeExportLabel(
+        `Subagent · ${row.agent_nickname}`,
+        180,
+        "Subagent",
+      );
+    }
     return subagent ? `Subagent · ${String(row?.id || "").slice(0, 8)}` : "Untitled task";
   }
-  return candidate
-    .replace(/\/Users\/[^\s"'`]+/g, "[local path]")
-    .replace(/\/(?:private\/)?tmp\/[^\s"'`]+/g, "[temporary path]")
-    .replace(
-      /\b(?:sk-[A-Za-z0-9_-]{16,}|lin_api_[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9_-]{16,})\b/g,
-      "[redacted credential-like text]",
-    )
-    .replace(/\s+/g, " ")
-    .slice(0, 180);
+  return safeExportLabel(candidate, 180, "Untitled task");
 }
 
 async function pathExists(path) {
@@ -604,26 +907,425 @@ export async function listJsonlFiles(root) {
   return found;
 }
 
-export async function latestSourceModifiedAt(codexHome, includeArchived = true) {
-  const roots = [resolve(codexHome, "sessions")];
-  if (includeArchived) {
-    roots.push(resolve(codexHome, "archived_sessions"));
+function sourceManifestEntry(codexHome, path, sourceStat) {
+  return [
+    hash(relative(resolve(codexHome), path), 64),
+    sourceStat.size,
+    sourceStat.mtimeMs,
+    sourceStat.ctimeMs,
+    sourceStat.dev ?? null,
+    sourceStat.ino ?? null,
+  ];
+}
+
+function normalizeSourcePath(value) {
+  const normalized = String(value).replaceAll("\\", "/");
+  return normalized.replace(/\/{2,}/g, "/").replace(/\/$/, "") || "/";
+}
+
+export function sourceLocationForPath(codexHome, path) {
+  const root = normalizeSourcePath(codexHome);
+  const candidate = normalizeSourcePath(path);
+  const archiveRoot = `${root}/archived_sessions`;
+  return candidate === archiveRoot || candidate.startsWith(`${archiveRoot}/`)
+    ? "archived"
+    : "active";
+}
+
+function sourceIdsForRolloutPaths(codexHome, entries) {
+  const root = resolve(codexHome);
+  const sourceIds = new Map();
+  for (const { path, sourceStat } of entries) {
+    const baseId = durableSourceId(root, path);
+    const fileIdentity = sourceStat.dev != null && sourceStat.ino != null
+      ? `inode:${sourceStat.dev}:${sourceStat.ino}`
+      : `path:${relative(root, path)}`;
+    sourceIds.set(path, `${baseId}:file:${hash(fileIdentity, 16)}`);
   }
-  const files = (await Promise.all(roots.map((root) => listJsonlFiles(root))))
-    .flat();
-  const metadataFiles = [
-    resolve(codexHome, "session_index.jsonl"),
+  return sourceIds;
+}
+
+function sourceWatermarkFromEntries(entries) {
+  const serialized = JSON.stringify(entries);
+  return {
+    version: SOURCE_WATERMARK_VERSION,
+    fingerprint: hash(serialized, 64),
+    sourceCount: entries.length,
+    latestModifiedAt: entries.reduce(
+      (latest, entry) => Math.max(latest, entry[2]),
+      0,
+    ),
+  };
+}
+
+export function sourceWatermarksEqual(left, right) {
+  return Boolean(
+    left &&
+      right &&
+      left.version === SOURCE_WATERMARK_VERSION &&
+      right.version === SOURCE_WATERMARK_VERSION &&
+      left.fingerprint === right.fingerprint &&
+      left.sourceCount === right.sourceCount &&
+      left.latestModifiedAt === right.latestModifiedAt,
+  );
+}
+
+async function prefixFingerprint(path, byteLength) {
+  const fingerprint = createHash("sha256");
+  if (byteLength === 0) return fingerprint.digest("hex");
+  const input = createReadStream(path, {
+    start: 0,
+    end: byteLength - 1,
+  });
+  for await (const chunk of input) fingerprint.update(chunk);
+  return fingerprint.digest("hex");
+}
+
+async function descriptorPrefixFingerprint(handle, byteLength) {
+  const fingerprint = createHash("sha256");
+  let offset = 0;
+  while (offset < byteLength) {
+    const chunkLength = Math.min(MAX_TRAILING_SCAN_BYTES, byteLength - offset);
+    const chunk = Buffer.allocUnsafe(chunkLength);
+    const { bytesRead } = await handle.read(
+      chunk,
+      0,
+      chunkLength,
+      offset,
+    );
+    if (bytesRead !== chunkLength) return null;
+    fingerprint.update(chunk.subarray(0, bytesRead));
+    offset += bytesRead;
+  }
+  return fingerprint.digest("hex");
+}
+
+function sourceIdentityChanged(sourceStat, expectedIdentity) {
+  return expectedIdentity?.device != null &&
+    expectedIdentity?.inode != null &&
+    (
+      Number(sourceStat.dev) !== Number(expectedIdentity.device) ||
+      Number(sourceStat.ino) !== Number(expectedIdentity.inode)
+    );
+}
+
+function sourceIdentityDiffers(left, right) {
+  const leftHasIdentity = left?.dev != null && left?.ino != null;
+  const rightHasIdentity = right?.dev != null && right?.ino != null;
+  return leftHasIdentity !== rightHasIdentity ||
+    (leftHasIdentity &&
+      (
+        Number(left.dev) !== Number(right.dev) ||
+        Number(left.ino) !== Number(right.ino)
+      ));
+}
+
+function sourceRevisionChanged(left, right) {
+  return (
+    Number(left.size) !== Number(right.size) ||
+    Number(left.mtimeMs) !== Number(right.mtimeMs) ||
+    Number(left.ctimeMs) !== Number(right.ctimeMs) ||
+    sourceIdentityDiffers(left, right)
+  );
+}
+
+async function revalidateScannedRollout(
+  path,
+  handle,
+  opened,
+  expectedIdentity,
+  maximumBytes,
+  cursorFingerprint,
+) {
+  const bounded = Number.isSafeInteger(maximumBytes) && maximumBytes >= 0;
+  const descriptor = await handle.stat();
+  if (bounded && Number(descriptor.size) < maximumBytes) {
+    const error = new Error(
+      "Rollout became shorter while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_SIZE_CHANGED";
+    throw error;
+  }
+  if (
+    bounded &&
+    Number(descriptor.size) === Number(opened.size) &&
+    (
+      Number(descriptor.mtimeMs) !== Number(opened.mtimeMs) ||
+      Number(descriptor.ctimeMs) !== Number(opened.ctimeMs)
+    )
+  ) {
+    const error = new Error(
+      "Rollout revision changed while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_CONTENT_CHANGED";
+    throw error;
+  }
+  if (sourceIdentityChanged(descriptor, expectedIdentity)) {
+    const error = new Error(
+      "Rollout identity changed while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_IDENTITY_CHANGED";
+    throw error;
+  }
+
+  const pathBefore = await stat(path);
+  if (
+    sourceIdentityChanged(pathBefore, expectedIdentity) ||
+    sourceIdentityDiffers(pathBefore, opened)
+  ) {
+    const error = new Error(
+      "Rollout identity changed while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_IDENTITY_CHANGED";
+    throw error;
+  }
+
+  if (bounded && Number(pathBefore.size) < maximumBytes) {
+    const error = new Error(
+      "Rollout became shorter while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_SIZE_CHANGED";
+    throw error;
+  }
+
+  const verifyPrefix = async () => {
+    const rereadFingerprint = await descriptorPrefixFingerprint(
+      handle,
+      maximumBytes,
+    );
+    if (rereadFingerprint !== cursorFingerprint) {
+      const error = new Error(
+        "Rollout content changed while its bounded prefix was being read.",
+      );
+      error.code = "ERR_SOURCE_CONTENT_CHANGED";
+      throw error;
+    }
+  };
+
+  // The streaming scan already hashed this exact prefix. Re-read it only if
+  // the descriptor or path stat changed while the scan was in flight; stable
+  // size, timestamps, and identity are the normal case and need no second
+  // pass over the file.
+  if (
+    bounded &&
+    (
+      sourceRevisionChanged(descriptor, opened) ||
+      sourceRevisionChanged(pathBefore, opened)
+    )
+  ) {
+    await verifyPrefix();
+  }
+
+  const pathAfter = await stat(path);
+  if (
+    sourceIdentityChanged(pathAfter, expectedIdentity) ||
+    sourceIdentityDiffers(pathAfter, opened)
+  ) {
+    const error = new Error(
+      "Rollout identity changed while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_IDENTITY_CHANGED";
+    throw error;
+  }
+  if (bounded && Number(pathAfter.size) < maximumBytes) {
+    const error = new Error(
+      "Rollout became shorter while its bounded prefix was being read.",
+    );
+    error.code = "ERR_SOURCE_SIZE_CHANGED";
+    throw error;
+  }
+  if (bounded && sourceRevisionChanged(pathAfter, pathBefore)) {
+    await verifyPrefix();
+  }
+}
+
+async function scanCutoffForFile(entry) {
+  const size = Number(entry.size);
+  if (!Number.isSafeInteger(size) || size <= 0) return Math.max(0, size || 0);
+
+  const handle = await open(entry.path, "r");
+  try {
+    // Start with the bounded trailing window, then continue backwards if an
+    // unterminated record is larger than that window. A zero cutoff would
+    // discard every complete record before the oversized partial record.
+    let chunkEnd = size;
+    while (chunkEnd > 0) {
+      const chunkLength = Math.min(chunkEnd, MAX_TRAILING_SCAN_BYTES);
+      const chunk = Buffer.allocUnsafe(chunkLength);
+      const chunkStart = chunkEnd - chunkLength;
+      const { bytesRead } = await handle.read(
+        chunk,
+        0,
+        chunkLength,
+        chunkStart,
+      );
+      if (bytesRead <= 0) return 0;
+      const lastNewline = chunk.subarray(0, bytesRead).lastIndexOf(0x0a);
+      if (lastNewline >= 0) return chunkStart + lastNewline + 1;
+      chunkEnd = chunkStart;
+    }
+    return 0;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function sourceInventoryPreservesCutoff(before, after) {
+  const initial = new Map(
+    before.files.map((entry) => [String(entry.sourceId), entry]),
+  );
+  const current = new Map(
+    after.files.map((entry) => [String(entry.sourceId), entry]),
+  );
+
+  for (const [sourceId, cutoff] of initial) {
+    const observed = current.get(sourceId);
+    const scanBytes = Number.isSafeInteger(Number(cutoff.scanBytes)) &&
+        Number(cutoff.scanBytes) >= 0
+      ? Number(cutoff.scanBytes)
+      : cutoff.size;
+    if (!observed || observed.size < scanBytes) return false;
+    const unchanged =
+      observed.path === cutoff.path &&
+      observed.size === cutoff.size &&
+      observed.mtimeMs === cutoff.mtimeMs &&
+      observed.ctimeMs === cutoff.ctimeMs &&
+      observed.dev === cutoff.dev &&
+      observed.ino === cutoff.ino;
+    if (unchanged) continue;
+    const cutoffFingerprint = primitiveString(cutoff.cursorFingerprint);
+    if (
+      cutoffFingerprint === null ||
+      cutoffFingerprint.length !== 64 ||
+      await prefixFingerprint(observed.path, scanBytes) !==
+        cutoffFingerprint
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function acceptedSourceWatermark(before, after) {
+  const initialRolloutPaths = new Set(
+    before.lifecycleFiles.map((entry) => entry.path),
+  );
+  const rolloutPaths = new Set([
+    ...initialRolloutPaths,
+    ...after.lifecycleFiles.map((entry) => entry.path),
+  ]);
+  const entries = [
+    ...before.watermarkEntries.filter(({ path }) =>
+      initialRolloutPaths.has(path)),
+    ...after.watermarkEntries.filter(({ path }) => !rolloutPaths.has(path)),
+  ]
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map(({ manifest }) => manifest);
+  return sourceWatermarkFromEntries(entries);
+}
+
+export async function sourceInventory(codexHome, includeArchived = true) {
+  const root = resolve(codexHome);
+  const activeRolloutFiles = await listJsonlFiles(
+    resolve(codexHome, "sessions"),
+  );
+  // Active-only reports must not parse archived rollouts, but they still need
+  // archive identities to distinguish a move from an unexplained deletion.
+  // Tracking stat-only lifecycle entries prevents the first --no-archived
+  // refresh after a move from continuing to attribute the source as active.
+  const archivedRolloutFiles = await listJsonlFiles(
+    resolve(codexHome, "archived_sessions"),
+  );
+  const lifecycleRolloutFiles = [
+    ...activeRolloutFiles,
+    ...archivedRolloutFiles,
+  ];
+  const rolloutFiles = includeArchived
+    ? lifecycleRolloutFiles
+    : activeRolloutFiles;
+  const sqliteFiles = [
     resolve(codexHome, "state_5.sqlite"),
     resolve(codexHome, "sqlite", "state_5.sqlite"),
   ];
+  const metadataFiles = [
+    resolve(codexHome, "session_index.jsonl"),
+    ...sqliteFiles.flatMap((path) => [path, `${path}-wal`]),
+  ];
   const existingMetadataFiles = [];
   for (const path of metadataFiles) {
     if (await pathExists(path)) existingMetadataFiles.push(path);
   }
-  const sourceFiles = [...files, ...existingMetadataFiles];
-  if (!sourceFiles.length) return 0;
-  const stats = await Promise.all(sourceFiles.map((path) => stat(path)));
-  return Math.max(...stats.map((entry) => entry.mtimeMs));
+  const sourceFiles = [
+    ...new Set([...lifecycleRolloutFiles, ...existingMetadataFiles]),
+  ]
+    .sort();
+  const sourceStats = await Promise.all(
+    sourceFiles.map(async (path) => ({
+      path,
+      sourceStat: await stat(path),
+    })),
+  );
+  const sourceStatByPath = new Map(
+    sourceStats.map((entry) => [entry.path, entry.sourceStat]),
+  );
+  const entries = sourceStats.map(({ path, sourceStat }) =>
+    sourceManifestEntry(root, path, sourceStat),
+  );
+  const rolloutSourceIds = sourceIdsForRolloutPaths(
+    root,
+    lifecycleRolloutFiles.map((path) => ({
+      path,
+      sourceStat: sourceStatByPath.get(path),
+    })),
+  );
+  const entryForPath = (path) => ({
+    path,
+    size: sourceStatByPath.get(path).size,
+    mtimeMs: sourceStatByPath.get(path).mtimeMs,
+    ctimeMs: sourceStatByPath.get(path).ctimeMs,
+    dev: sourceStatByPath.get(path).dev ?? null,
+    ino: sourceStatByPath.get(path).ino ?? null,
+    sourceId: rolloutSourceIds.get(path),
+    location: sourceLocationForPath(root, path),
+  });
+  const lifecycleFiles = lifecycleRolloutFiles.sort().map(entryForPath);
+  const lifecycleByPath = new Map(
+    lifecycleFiles.map((entry) => [entry.path, entry]),
+  );
+  const lifecyclePathSet = new Set(lifecycleRolloutFiles);
+  const watermarkEntries = sourceStats.map(({ path, sourceStat }) => ({
+    path,
+    manifest: sourceManifestEntry(root, path, sourceStat),
+  }));
+  return {
+    files: rolloutFiles.sort().map((path) => lifecycleByPath.get(path)),
+    lifecycleFiles,
+    watermarkEntries,
+    metadataWatermark: sourceWatermarkFromEntries(
+      watermarkEntries
+        .filter(({ path }) => !lifecyclePathSet.has(path))
+        .map(({ manifest }) => manifest),
+    ),
+    watermark: sourceWatermarkFromEntries(entries),
+    cutoffAt: new Date().toISOString(),
+  };
+}
+
+export async function latestSourceModifiedAt(codexHome, includeArchived = true) {
+  return (
+    await sourceInventory(codexHome, includeArchived)
+  ).watermark.latestModifiedAt;
+}
+
+function metadataTimestampMs(value) {
+  if (value == null) return null;
+  if (String(value).trim().length === 0) return null;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) {
+    return numeric < 10_000_000_000 ? numeric * 1_000 : numeric;
+  }
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : null;
 }
 
 async function readSessionTitles(path) {
@@ -636,11 +1338,16 @@ async function readSessionTitles(path) {
     try {
       const record = JSON.parse(line);
       if (!record?.id || !record?.thread_name) continue;
-      const timestamp = new Date(record.updated_at || 0).getTime();
+      const timestamp = metadataTimestampMs(record.updated_at);
       const current = titles.get(record.id);
-      if (!current || timestamp >= current.timestamp) {
+      if (
+        !current ||
+        timestamp === null ||
+        current.timestamp === null ||
+        timestamp >= current.timestamp
+      ) {
         titles.set(record.id, {
-          title: String(record.thread_name).replace(/\s+/g, " ").slice(0, 180),
+          title: spoolText(record.thread_name).replace(/\s+/g, " "),
           timestamp,
         });
       }
@@ -651,48 +1358,269 @@ async function readSessionTitles(path) {
   return titles;
 }
 
-async function readState(codexHome) {
-  const preferred = resolve(codexHome, "state_5.sqlite");
-  const legacy = resolve(codexHome, "sqlite", "state_5.sqlite");
-  const path = (await pathExists(preferred))
-    ? preferred
-    : (await pathExists(legacy))
-      ? legacy
-      : null;
-  const rows = new Map();
-  const parents = new Map();
-  if (!path) return { path: null, rows, parents };
+const STATE_DATABASE_BUSY_TIMEOUT_MS = 250;
+const STATE_THREAD_COLUMNS = [
+  "id",
+  "created_at",
+  "updated_at",
+  "source",
+  "cwd",
+  "title",
+  "name",
+  "tokens_used",
+  "git_sha",
+  "git_branch",
+  "git_origin_url",
+  "agent_nickname",
+  "agent_role",
+  "model",
+  "reasoning_effort",
+  "thread_source",
+];
+const ROLLOUT_METADATA_COLUMNS = [
+  "source",
+  "cwd",
+  "git_origin_url",
+  "model",
+  "reasoning_effort",
+  "thread_source",
+];
 
-  const database = new DatabaseSync(path, { readOnly: true });
-  try {
-    const threadRows = database
-      .prepare(
-        `SELECT id, created_at, updated_at, source, cwd, title, name,
-                tokens_used, git_sha, git_branch, git_origin_url,
-                agent_nickname, agent_role, model, reasoning_effort,
-                thread_source
-           FROM threads`,
-      )
-      .all();
-    for (const row of threadRows) rows.set(String(row.id), row);
+function currentThreadMetadataFingerprints(state) {
+  const threadIds = new Set(state.rows.keys());
+  const fingerprints = new Map();
+  for (const threadId of threadIds) {
+    const row = state.rows.get(threadId);
+    fingerprints.set(
+      String(threadId),
+      hash(JSON.stringify(
+        ROLLOUT_METADATA_COLUMNS.map((column) => row?.[column] ?? null),
+      ), 64),
+    );
+  }
+  return fingerprints;
+}
 
-    const edgeRows = database
-      .prepare(
-        "SELECT parent_thread_id, child_thread_id FROM thread_spawn_edges",
-      )
-      .all();
-    for (const edge of edgeRows) {
-      parents.set(String(edge.child_thread_id), String(edge.parent_thread_id));
-    }
-  } finally {
-    database.close();
+function threadMetadataRecordChanged(current, previous, fields) {
+  if (!previous) return true;
+  return fields.some((field) =>
+    (current?.[field] ?? null) !== (previous?.[field] ?? null)
+  );
+}
+
+function providedThreadMetadataFields(threadId, state) {
+  const row = state.rows.get(threadId);
+  const fields = [];
+  if (row?.cwd != null || row?.git_origin_url != null) fields.push("project");
+  if (row?.model != null) fields.push("model");
+  if (row?.reasoning_effort != null) fields.push("effort");
+  if (row?.thread_source != null || row?.source != null) {
+    fields.push("source", "useType");
   }
-  return { path, rows, parents };
+  return fields;
 }
 
-function taskStartCandidate(record, threadId, stateRow, fileContext) {
-  const outerMs = new Date(record.timestamp).getTime();
-  const started = asFiniteNumber(record.payload?.started_at);
+function metadataChangedThreadIds({
+  state,
+  titles,
+  currentFingerprints,
+  previousFingerprints,
+  persistedThreads,
+}) {
+  if (previousFingerprints instanceof Map) {
+    const threadIds = new Set([
+      ...currentFingerprints.keys(),
+      ...previousFingerprints.keys(),
+    ]);
+    return new Set([...threadIds].filter((threadId) =>
+      currentFingerprints.get(threadId) !== previousFingerprints.get(threadId)
+    ));
+  }
+  if (!(persistedThreads instanceof Map)) return null;
+
+  // Existing v3 ledgers predate per-thread fingerprints. Seed them without a
+  // one-time full rescan by comparing today's normalized metadata with the
+  // private thread records already stored in the ledger. Ambiguous rollout
+  // names still use the conservative global fallback below.
+  const changed = new Set();
+  for (const threadId of currentFingerprints.keys()) {
+    const current = threadMetadata(
+      threadId,
+      state.rows,
+      titles,
+      state.parents,
+      {},
+      persistedThreads,
+    );
+    const providedFields = providedThreadMetadataFields(threadId, state);
+    if (
+      threadMetadataRecordChanged(
+        current,
+        persistedThreads.get(threadId),
+        providedFields,
+      )
+    ) {
+      changed.add(threadId);
+    }
+  }
+  return changed;
+}
+
+function stateDatabaseResult(status, rows, parents, reason = null) {
+  return {
+    rows,
+    parents,
+    metadata: {
+      status,
+      reason,
+      threadRows: rows.size,
+      parentEdges: parents.size,
+    },
+  };
+}
+
+function stateDatabaseFailureReason(error) {
+  const errorNumber = Number(error?.errcode);
+  if (errorNumber === 5 || errorNumber === 6) return "busy";
+  if (errorNumber === 11 || errorNumber === 26) return "corrupt";
+  const message = String(error?.message || "").toLowerCase();
+  if (message.includes("locked") || message.includes("busy")) return "busy";
+  if (
+    message.includes("corrupt") ||
+    message.includes("malformed") ||
+    message.includes("not a database")
+  ) {
+    return "corrupt";
+  }
+  if (message.includes("no such table") || message.includes("no such column")) {
+    return "schema-mismatch";
+  }
+  return "read-error";
+}
+
+function expectedStateDatabaseFailure(error) {
+  const code = String(error?.code || "");
+  return code.startsWith("ERR_SQLITE") ||
+    ["EACCES", "EISDIR", "ENOENT", "ENOTDIR", "EPERM"].includes(code);
+}
+
+function stateTableExists(database, table) {
+  return Boolean(
+    database
+      .prepare(
+        "SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?",
+      )
+      .get(table),
+  );
+}
+
+function stateTableColumns(database, table) {
+  return new Set(
+    database
+      .prepare(`PRAGMA table_info("${table}")`)
+      .all()
+      .map((column) => String(column.name)),
+  );
+}
+
+async function readState(codexHome) {
+  const preferred = resolve(codexHome, "state_5.sqlite");
+  const legacy = resolve(codexHome, "sqlite", "state_5.sqlite");
+  const path = (await pathExists(preferred))
+    ? preferred
+    : (await pathExists(legacy))
+      ? legacy
+      : null;
+  const rows = new Map();
+  const parents = new Map();
+  if (!path) return stateDatabaseResult("missing", rows, parents);
+
+  let database;
+  try {
+    database = new DatabaseSync(path, { readOnly: true });
+    database.exec(`PRAGMA busy_timeout = ${STATE_DATABASE_BUSY_TIMEOUT_MS}`);
+    if (!stateTableExists(database, "threads")) {
+      return stateDatabaseResult(
+        "unavailable",
+        rows,
+        parents,
+        "schema-mismatch",
+      );
+    }
+    const threadColumns = stateTableColumns(database, "threads");
+    if (!threadColumns.has("id")) {
+      return stateDatabaseResult(
+        "unavailable",
+        rows,
+        parents,
+        "schema-mismatch",
+      );
+    }
+    const projection = STATE_THREAD_COLUMNS.map((column) =>
+      threadColumns.has(column)
+        ? `"${column}"`
+        : `NULL AS "${column}"`,
+    ).join(", ");
+    const threadRows = database
+      .prepare(`SELECT ${projection} FROM threads`)
+      .all();
+    for (const row of threadRows) rows.set(String(row.id), row);
+
+    if (!stateTableExists(database, "thread_spawn_edges")) {
+      return stateDatabaseResult("available", rows, parents);
+    }
+    const edgeColumns = stateTableColumns(database, "thread_spawn_edges");
+    if (
+      !edgeColumns.has("parent_thread_id") ||
+      !edgeColumns.has("child_thread_id")
+    ) {
+      return stateDatabaseResult(
+        "partial",
+        rows,
+        parents,
+        "schema-mismatch",
+      );
+    }
+    try {
+      const edgeRows = database
+        .prepare(
+          "SELECT parent_thread_id, child_thread_id FROM thread_spawn_edges",
+        )
+        .all();
+      for (const edge of edgeRows) {
+        parents.set(String(edge.child_thread_id), String(edge.parent_thread_id));
+      }
+    } catch (error) {
+      if (!expectedStateDatabaseFailure(error)) throw error;
+      return stateDatabaseResult(
+        "partial",
+        rows,
+        parents,
+        stateDatabaseFailureReason(error),
+      );
+    }
+    return stateDatabaseResult("available", rows, parents);
+  } catch (error) {
+    if (!expectedStateDatabaseFailure(error)) throw error;
+    return stateDatabaseResult(
+      "unavailable",
+      new Map(),
+      new Map(),
+      stateDatabaseFailureReason(error),
+    );
+  } finally {
+    try {
+      database?.close();
+    } catch {
+      // State metadata is optional enrichment; close failures cannot erase
+      // additive usage recovered from rollout JSONL.
+    }
+  }
+}
+
+function taskStartCandidate(record, threadId, stateRow, fileContext) {
+  const outerMs = new Date(record.timestamp).getTime();
+  const started = asFiniteNumber(record.payload?.started_at);
   const startedMs = started > 10_000_000_000 ? started : started * 1_000;
   const timestamp = isoFromEpoch(started, safeIso(record.timestamp, new Date(0).toISOString()));
   const deltaMs =
@@ -714,78 +1642,144 @@ function taskStartCandidate(record, threadId, stateRow, fileContext) {
   };
 }
 
-function rememberQuota(quotaMap, rateLimits, occurrence) {
-  // rate_limits payloads come straight from JSONL. Read the named fields
-  // once; records without usable buckets drop out via the filter below.
+function quotaCandidates(rateLimits, occurrence) {
+  if (rateLimits == null) return { candidates: [], invalidRecords: 0 };
+  if (Object(rateLimits) !== rateLimits || Array.isArray(rateLimits)) {
+    return { candidates: [], invalidRecords: 1 };
+  }
   const {
     primary,
     secondary,
     limit_id: limitId,
     limit_name: limitName,
     plan_type: planType,
-  } = rateLimits ?? {};
-  const buckets = [primary, secondary].filter(Boolean);
-  for (const bucket of buckets) {
-    const windowMinutes = asFiniteNumber(bucket.window_minutes);
-    const usedPercent = asFiniteNumber(bucket.used_percent);
-    const resetsAt = asFiniteNumber(bucket.resets_at);
-    if (!windowMinutes || !resetsAt) continue;
-    const limitKey = String(limitId || limitName || "anonymous");
-    const key = [
-      hash(limitKey, 16),
+  } = rateLimits;
+  const limitIdText = limitId == null ? null : primitiveString(limitId);
+  const limitNameText = limitName == null ? null : primitiveString(limitName);
+  const planTypeText = planType == null ? null : primitiveString(planType);
+  if (
+    (limitId != null && limitIdText == null) ||
+    (limitName != null && limitNameText == null) ||
+    (planType != null && planTypeText == null)
+  ) {
+    return { candidates: [], invalidRecords: 1 };
+  }
+  // Codex treats an omitted limit id as the default `codex` bucket. Keep the
+  // provider id authoritative: a human label is optional display metadata and
+  // must never create a second durable identity for the same quota pool.
+  const canonicalLimitId = (limitIdText ?? "")
+    .trim()
+    .replace(/[A-Z-]/g, (character) =>
+      character === "-" ? "_" : character.toLowerCase()) || "codex";
+  const normalizedLimitName = limitNameText == null
+    ? null
+    : safeExportLabel(limitNameText, 80, null);
+  const normalizedPlanType = planTypeText == null
+    ? "unknown"
+    : safeExportLabel(planTypeText, 80, null);
+  if (normalizedPlanType == null) {
+    return { candidates: [], invalidRecords: 1 };
+  }
+  const scope = canonicalLimitId === "codex" ? "account" : "named";
+  const candidates = [];
+  let invalidRecords = 0;
+  for (const bucket of [primary, secondary]) {
+    // Providers use null for an unavailable secondary window.
+    if (bucket == null) continue;
+    if (Object(bucket) !== bucket || Array.isArray(bucket)) {
+      invalidRecords += 1;
+      continue;
+    }
+    const normalized = normalizeQuotaObservationFields({
+      windowMinutes: bucket.window_minutes,
+      usedPercent: bucket.used_percent,
+      resetsAt: bucket.resets_at,
+    });
+    if (!normalized) {
+      invalidRecords += 1;
+      continue;
+    }
+    const { windowMinutes, usedPercent, resetsAt } = normalized;
+    const stableLimitKey = hash(canonicalLimitId, 16);
+    const observationKey = durableQuotaObservationKey({
+      limitKey: stableLimitKey,
       windowMinutes,
       resetsAt,
       usedPercent,
-    ].join("|");
-    const candidate = {
-      id: `quota-${hash(key)}`,
-      // Keep the first and last occurrence of an unchanged reading without
-      // storing every repeated provider sample in the snapshot.
+    });
+    candidates.push({
+      observationKey,
+      id: `quota-${hash(observationKey)}`,
       timestamp: occurrence.timestamp,
       lastSeenAt: occurrence.timestamp,
       usedPercent,
       windowMinutes,
       resetsAt,
-      planType: String(planType || "unknown"),
-      limitKey: hash(limitKey, 16),
-      limitName: limitName ? String(limitName).slice(0, 80) : null,
+      planType: normalizedPlanType,
+      limitKey: stableLimitKey,
+      limitName: normalizedLimitName,
+      scope,
       source: "log",
       turnId: occurrence.turnId || null,
       originalLikely: occurrence.originalLikely,
-    };
-    const current = quotaMap.get(key);
-    if (
-      !current ||
-      (!current.originalLikely && candidate.originalLikely)
-    ) {
-      quotaMap.set(key, candidate);
-    } else if (current.originalLikely === candidate.originalLikely) {
-      quotaMap.set(key, {
-        ...current,
-        timestamp:
-          candidate.timestamp < current.timestamp
-            ? candidate.timestamp
-            : current.timestamp,
-        lastSeenAt:
-          candidate.timestamp > current.lastSeenAt
-            ? candidate.timestamp
-            : current.lastSeenAt,
-      });
-    }
+    });
+  }
+  return { candidates, invalidRecords };
+}
+
+function rememberQuotaLabel(quotaLabels, sourceId, candidate) {
+  if (candidate.limitName == null) return;
+  const observedAt = Date.parse(candidate.timestamp);
+  const key = JSON.stringify([String(sourceId), candidate.limitKey]);
+  const current = quotaLabels.get(key);
+  if (
+    !current ||
+    observedAt > current.observedAtMs ||
+    (
+      observedAt === current.observedAtMs &&
+      candidate.limitName > current.limitName
+    )
+  ) {
+    quotaLabels.set(key, {
+      sourceId: String(sourceId),
+      limitKey: candidate.limitKey,
+      limitName: candidate.limitName,
+      observedAt: candidate.timestamp,
+      observedAtMs: observedAt,
+    });
+  }
+}
+
+function rememberQuota(quotaMap, candidate, sinceMs = -Infinity) {
+  if (Date.parse(candidate.timestamp) < sinceMs) return;
+  const { observationKey, ...storedCandidate } = candidate;
+  const current = quotaMap.get(observationKey);
+  if (
+    !current ||
+    (!current.originalLikely && storedCandidate.originalLikely)
+  ) {
+    quotaMap.set(observationKey, storedCandidate);
+  } else if (current.originalLikely === storedCandidate.originalLikely) {
+    // Keep the first and last occurrence of an unchanged reading without
+    // storing every repeated provider sample in the snapshot.
+    quotaMap.set(observationKey, {
+      ...current,
+      timestamp:
+        storedCandidate.timestamp < current.timestamp
+          ? storedCandidate.timestamp
+          : current.timestamp,
+      lastSeenAt:
+        storedCandidate.timestamp > current.lastSeenAt
+          ? storedCandidate.timestamp
+          : current.lastSeenAt,
+    });
   }
 }
 
 function responseCall(record) {
   if (record.type !== "response_item") return null;
   const payload = record.payload;
-  const allowed = new Set([
-    "function_call",
-    "custom_tool_call",
-    "tool_search_call",
-    "web_search_call",
-    "image_generation_call",
-  ]);
-  if (!payload || !allowed.has(payload.type)) return null;
+  if (!payload || !RELEVANT_CALL_TYPES.has(payload.type)) return null;
   return {
     type: payload.type,
     name: String(payload.name || payload.namespace || payload.type).slice(0, 80),
@@ -793,10 +1787,249 @@ function responseCall(record) {
   };
 }
 
-async function scanRollout(path, context) {
+function inspectJsonLine(line) {
+  let index = 0;
+  let topType = { kind: "absent" };
+  let payloadType = { kind: "absent" };
+
+  function skipWhitespace() {
+    while (
+      line[index] === " " ||
+      line[index] === "\t" ||
+      line[index] === "\n" ||
+      line[index] === "\r"
+    ) {
+      index += 1;
+    }
+  }
+
+  function parseString() {
+    if (line[index] !== '"') return { valid: false };
+    index += 1;
+    const start = index;
+    let simple = true;
+    while (index < line.length) {
+      const code = line.charCodeAt(index);
+      if (code === 34) {
+        const value = simple ? line.slice(start, index) : null;
+        index += 1;
+        return { valid: true, simple, value };
+      }
+      if (code === 92) {
+        simple = false;
+        index += 1;
+        if (index >= line.length) return { valid: false };
+        if (line[index] === "u") {
+          if (!/^[0-9a-f]{4}$/i.test(line.slice(index + 1, index + 5))) {
+            return { valid: false };
+          }
+          index += 5;
+        } else if ('"\\/bfnrt'.includes(line[index])) {
+          index += 1;
+        } else {
+          return { valid: false };
+        }
+        continue;
+      }
+      if (code < 0x20) return { valid: false };
+      index += 1;
+    }
+    return { valid: false };
+  }
+
+  function parseNumber() {
+    const start = index;
+    if (line[index] === "-") index += 1;
+    if (line[index] === "0") {
+      index += 1;
+    } else if (line[index] >= "1" && line[index] <= "9") {
+      while (line[index] >= "0" && line[index] <= "9") index += 1;
+    } else {
+      return false;
+    }
+    if (line[index] === ".") {
+      index += 1;
+      const fractionStart = index;
+      while (line[index] >= "0" && line[index] <= "9") index += 1;
+      if (index === fractionStart) return false;
+    }
+    if (line[index] === "e" || line[index] === "E") {
+      index += 1;
+      if (line[index] === "+" || line[index] === "-") index += 1;
+      const exponentStart = index;
+      while (line[index] >= "0" && line[index] <= "9") index += 1;
+      if (index === exponentStart) return false;
+    }
+    return index > start;
+  }
+
+  function parseLiteral(value) {
+    if (line.slice(index, index + value.length) !== value) return false;
+    index += value.length;
+    return true;
+  }
+
+  function captureValue() {
+    if (line[index] === '"') {
+      const result = parseString();
+      if (!result.valid) return { valid: false };
+      return result.simple
+        ? { valid: true, kind: "string", value: result.value }
+        : { valid: true, kind: "unknown" };
+    }
+    return parseValue()
+      ? { valid: true, kind: "other" }
+      : { valid: false };
+  }
+
+  function rememberType(current, captured) {
+    if (current.kind === "unknown") return current;
+    return captured.kind === "unknown"
+      ? { kind: "unknown" }
+      : captured.kind === "string"
+        ? { kind: "string", value: captured.value }
+        : { kind: "other" };
+  }
+
+  function parseObject(scope = "generic") {
+    if (line[index] !== "{") return false;
+    index += 1;
+    skipWhitespace();
+    if (line[index] === "}") {
+      index += 1;
+      return true;
+    }
+    while (index < line.length) {
+      const key = parseString();
+      if (!key.valid) return false;
+      skipWhitespace();
+      if (line[index] !== ":") return false;
+      index += 1;
+      skipWhitespace();
+
+      if (scope === "top" && !key.simple) {
+        topType = { kind: "unknown" };
+        payloadType = { kind: "unknown" };
+      }
+      if (scope === "payload" && !key.simple) {
+        payloadType = { kind: "unknown" };
+      }
+
+      if (scope === "top" && key.simple && key.value === "type") {
+        const captured = captureValue();
+        if (!captured.valid) return false;
+        topType = rememberType(topType, captured);
+      } else if (scope === "top" && key.simple && key.value === "payload") {
+        if (line[index] === "{") {
+          if (!parseObject("payload")) return false;
+          if (payloadType.kind === "absent") {
+            payloadType = { kind: "other" };
+          }
+        } else {
+          const captured = captureValue();
+          if (!captured.valid) return false;
+          payloadType = { kind: "other" };
+        }
+      } else if (scope === "payload" && key.simple && key.value === "type") {
+        const captured = captureValue();
+        if (!captured.valid) return false;
+        payloadType = rememberType(payloadType, captured);
+      } else if (!parseValue()) {
+        return false;
+      }
+
+      skipWhitespace();
+      if (line[index] === "}") {
+        index += 1;
+        return true;
+      }
+      if (line[index] !== ",") return false;
+      index += 1;
+      skipWhitespace();
+    }
+    return false;
+  }
+
+  function parseArray() {
+    if (line[index] !== "[") return false;
+    index += 1;
+    skipWhitespace();
+    if (line[index] === "]") {
+      index += 1;
+      return true;
+    }
+    while (index < line.length) {
+      if (!parseValue()) return false;
+      skipWhitespace();
+      if (line[index] === "]") {
+        index += 1;
+        return true;
+      }
+      if (line[index] !== ",") return false;
+      index += 1;
+      skipWhitespace();
+    }
+    return false;
+  }
+
+  function parseValue() {
+    if (line[index] === '"') return parseString().valid;
+    if (line[index] === "{") return parseObject();
+    if (line[index] === "[") return parseArray();
+    if (line[index] === "t") return parseLiteral("true");
+    if (line[index] === "f") return parseLiteral("false");
+    if (line[index] === "n") return parseLiteral("null");
+    return parseNumber();
+  }
+
+  skipWhitespace();
+  try {
+    if (line[index] !== "{" || !parseObject("top")) return null;
+  } catch {
+    // Deeply nested values can exhaust the call stack before JSON.parse
+    // would; treat that as inconclusive and let the real parser decide.
+    return null;
+  }
+  skipWhitespace();
+  if (index !== line.length) return null;
+  return { topType, payloadType };
+}
+
+function lineMayAffectUsage(line) {
+  const inspected = inspectJsonLine(line);
+  if (!inspected) return true;
+  if (inspected.topType.kind === "unknown") return true;
+  if (inspected.topType.kind !== "string") return false;
+  if (inspected.topType.value === "session_meta") return true;
+  if (inspected.topType.value === "turn_context") return true;
+  if (inspected.topType.value === "event_msg") {
+    return (
+      inspected.payloadType.kind === "unknown" ||
+      (inspected.payloadType.kind === "string" &&
+        RELEVANT_EVENT_TYPES.has(inspected.payloadType.value))
+    );
+  }
+  if (inspected.topType.value === "response_item") {
+    return (
+      inspected.payloadType.kind === "unknown" ||
+      (inspected.payloadType.kind === "string" &&
+        RELEVANT_CALL_TYPES.has(inspected.payloadType.value))
+    );
+  }
+  return false;
+}
+
+async function scanRollout(
+  path,
+  stateRows,
+  signal,
+  continuityBytes = null,
+  maximumBytes = null,
+  expectedIdentity = null,
+) {
   const match = path.match(UUID_AT_END);
   const threadId = match?.[1] || `file-${hash(path)}`;
-  const stateRow = context.stateRows.get(threadId);
+  const stateRow = stateRows.get(threadId);
   const fileContext = {
     model: stateRow?.model || "unknown",
     effort: stateRow?.reasoning_effort || "unknown",
@@ -806,215 +2039,507 @@ async function scanRollout(path, context) {
     serviceTier: null,
   };
   const callOrdinals = new Map();
+  const tokenSignatures = new Map();
+  let nextTokenOrdinal = 0;
   let currentTurnId = "";
   let currentCandidate = null;
-  let currentCandidateSelected = false;
   let previousCumulative = null;
+  const operations = [];
+  let parseErrors = 0;
+  let correctionIntervals = 0;
+  let invalidTokenRecords = 0;
+  let invalidQuotaRecords = 0;
 
-  const input = createReadStream(path, { encoding: "utf8" });
-  const lines = createInterface({ input, crlfDelay: Infinity });
-  for await (const line of lines) {
-    if (!line.trim()) continue;
-    let record;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      context.parseErrors += 1;
-      continue;
+  const contentHash = createHash("sha256");
+  const continuityHash = Number.isSafeInteger(continuityBytes) &&
+      continuityBytes >= 0
+    ? createHash("sha256")
+    : null;
+  let continuityRemaining = continuityHash ? continuityBytes : 0;
+  const bounded = Number.isSafeInteger(maximumBytes) && maximumBytes >= 0;
+  const sourceOptions = { signal, autoClose: false };
+  if (bounded) {
+    sourceOptions.start = 0;
+    sourceOptions.end = maximumBytes - 1;
+  }
+  const handle = await open(path, "r");
+  let source;
+  let opened;
+  try {
+    opened = await handle.stat();
+    if (bounded && Number(opened.size) < maximumBytes) {
+      const error = new Error(
+        "Rollout became shorter between inventory and collection.",
+      );
+      error.code = "ERR_SOURCE_SIZE_CHANGED";
+      throw error;
+    }
+    if (
+      expectedIdentity?.device != null &&
+      expectedIdentity?.inode != null &&
+      (
+        Number(opened.dev) !== Number(expectedIdentity.device) ||
+        Number(opened.ino) !== Number(expectedIdentity.inode)
+      )
+    ) {
+      const error = new Error(
+        "Rollout identity changed between inventory and collection.",
+      );
+      error.code = "ERR_SOURCE_IDENTITY_CHANGED";
+      throw error;
+    }
+    if (bounded && maximumBytes === 0) {
+      source = Readable.from([]);
+    } else {
+      source = handle.createReadStream(sourceOptions);
     }
+  } catch (error) {
+    await handle.close().catch(() => {});
+    throw error;
+  }
+  const input = new Transform({
+    transform(chunk, encoding, callback) {
+      contentHash.update(chunk);
+      if (continuityHash && continuityRemaining > 0) {
+        const included = chunk.subarray(
+          0,
+          Math.min(chunk.byteLength, continuityRemaining),
+        );
+        continuityHash.update(included);
+        continuityRemaining -= included.byteLength;
+      }
+      callback(null, chunk);
+    },
+  });
+  source.on("error", (error) => input.destroy(error));
+  source.pipe(input);
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  try {
+    for await (const line of lines) {
+      if (!line.trim() || !lineMayAffectUsage(line)) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        parseErrors += 1;
+        continue;
+      }
+
+      if (record.type === "session_meta") {
+        const payload = record.payload;
+        if (payload?.id === threadId) {
+          fileContext.cwd = payload.cwd || fileContext.cwd;
+          fileContext.gitOrigin =
+            payload.git?.repository_url || fileContext.gitOrigin;
+          fileContext.rawSource = payload.source || fileContext.rawSource;
+          if (payload.parent_thread_id || payload.forked_from_id) {
+            operations.push({
+              kind: "parent",
+              threadId,
+              parentThreadId: String(
+                payload.parent_thread_id || payload.forked_from_id,
+              ),
+            });
+          }
+          const spawnedParent =
+            payload.source?.subagent?.thread_spawn?.parent_thread_id;
+          if (spawnedParent) {
+            operations.push({
+              kind: "parent",
+              threadId,
+              parentThreadId: String(spawnedParent),
+            });
+          }
+        }
+        continue;
+      }
 
-    if (record.type === "session_meta") {
-      const payload = record.payload;
-      if (payload?.id === threadId) {
-        fileContext.cwd = payload.cwd || fileContext.cwd;
-        fileContext.gitOrigin =
-          payload.git?.repository_url || fileContext.gitOrigin;
-        fileContext.rawSource = payload.source || fileContext.rawSource;
-        if (payload.parent_thread_id || payload.forked_from_id) {
-          context.parents.set(
+      if (record.type === "event_msg" && record.payload?.type === "task_started") {
+        currentTurnId = String(record.payload.turn_id || currentTurnId || "");
+        if (currentTurnId) {
+          currentCandidate = taskStartCandidate(
+            record,
             threadId,
-            String(payload.parent_thread_id || payload.forked_from_id),
+            stateRow,
+            fileContext,
           );
+          operations.push({
+            kind: "origin",
+            candidate: { ...currentCandidate },
+          });
         }
-        const spawnedParent =
-          payload.source?.subagent?.thread_spawn?.parent_thread_id;
-        if (spawnedParent) context.parents.set(threadId, String(spawnedParent));
+        continue;
       }
-      continue;
-    }
 
-    if (record.type === "event_msg" && record.payload?.type === "task_started") {
-      currentTurnId = String(record.payload.turn_id || currentTurnId || "");
-      if (currentTurnId) {
-        currentCandidate = taskStartCandidate(
-          record,
-          threadId,
-          stateRow,
-          fileContext,
-        );
-        currentCandidateSelected = context.spool.insertOrigin(currentCandidate);
+      if (record.type === "turn_context") {
+        currentTurnId = String(record.payload?.turn_id || currentTurnId || "");
+        fileContext.model = record.payload?.model || fileContext.model;
+        fileContext.effort = record.payload?.effort || fileContext.effort;
+        fileContext.cwd = record.payload?.cwd || fileContext.cwd;
+        if (currentCandidate?.turnId === currentTurnId) {
+          currentCandidate.model = fileContext.model;
+          currentCandidate.effort = fileContext.effort;
+          currentCandidate.cwd = fileContext.cwd;
+          operations.push({
+            kind: "origin_update",
+            turnId: currentTurnId,
+            model: fileContext.model,
+            effort: fileContext.effort,
+            cwd: fileContext.cwd,
+          });
+        }
+        continue;
       }
-      continue;
-    }
 
-    if (record.type === "turn_context") {
-      currentTurnId = String(record.payload?.turn_id || currentTurnId || "");
-      fileContext.model = record.payload?.model || fileContext.model;
-      fileContext.effort = record.payload?.effort || fileContext.effort;
-      fileContext.cwd = record.payload?.cwd || fileContext.cwd;
-      if (currentCandidate?.turnId === currentTurnId) {
-        currentCandidate.model = fileContext.model;
-        currentCandidate.effort = fileContext.effort;
-        currentCandidate.cwd = fileContext.cwd;
-        if (currentCandidateSelected) {
-          context.spool.updateOrigin(currentCandidate);
-        }
+      if (
+        record.type === "event_msg" &&
+        record.payload?.type === "thread_settings_applied"
+      ) {
+        const settings = record.payload?.thread_settings;
+        fileContext.model = settings?.model || fileContext.model;
+        fileContext.effort = settings?.reasoning_effort || fileContext.effort;
+        const serviceTier = String(settings?.service_tier ?? "").trim();
+        fileContext.serviceTier = serviceTier
+          ? serviceTier.slice(0, 40)
+          : null;
+        continue;
       }
-      continue;
-    }
 
-    if (
-      record.type === "event_msg" &&
-      record.payload?.type === "thread_settings_applied"
-    ) {
-      const settings = record.payload?.thread_settings;
-      fileContext.model = settings?.model || fileContext.model;
-      fileContext.effort = settings?.reasoning_effort || fileContext.effort;
-      const serviceTier = String(settings?.service_tier ?? "").trim();
-      fileContext.serviceTier = serviceTier
-        ? serviceTier.slice(0, 40)
+      const tokenCountRecord =
+        record.type === "event_msg" && record.payload?.type === "token_count";
+      const tokenTimestamp = tokenCountRecord
+        ? liveRecordTimestamp(record.timestamp)
         : null;
-      continue;
-    }
-
-    const originalLikely = Boolean(currentCandidate?.deltaMs <= 2_000);
-    const occurrence = {
-      threadId,
-      turnId: currentTurnId,
-      timestamp: safeIso(
-        record.timestamp,
-        currentCandidate?.timestamp || new Date(0).toISOString(),
-      ),
-      originalLikely,
-      model: fileContext.model,
-      effort: fileContext.effort,
-      cwd: fileContext.cwd,
-      gitOrigin: fileContext.gitOrigin,
-      rawSource: fileContext.rawSource,
-      serviceTier: fileContext.serviceTier,
-    };
+      if (tokenCountRecord && tokenTimestamp === null) {
+        if (record.payload?.info?.last_token_usage !== undefined) {
+          invalidTokenRecords += 1;
+        }
+        if (record.payload?.rate_limits != null) invalidQuotaRecords += 1;
+        continue;
+      }
 
-    const call = responseCall(record);
-    if (call) {
-      const ordinalBase = `${currentTurnId}|${call.type}|${call.name}`;
-      const ordinal = (callOrdinals.get(ordinalBase) || 0) + 1;
-      callOrdinals.set(ordinalBase, ordinal);
-      const callKey = call.stableId
-        ? `id|${call.stableId}`
-        : `ordinal|${ordinalBase}|${ordinal}`;
-      context.spool.insertCall(
-        callKey,
-        currentTurnId,
+      const originalLikely = Boolean(currentCandidate?.deltaMs <= 2_000);
+      const occurrence = {
         threadId,
+        turnId: currentTurnId,
+        timestamp: tokenTimestamp || safeIso(
+          record.timestamp,
+          currentCandidate?.timestamp || new Date(0).toISOString(),
+        ),
         originalLikely,
-      );
-      continue;
-    }
+        model: fileContext.model,
+        effort: fileContext.effort,
+        cwd: fileContext.cwd,
+        gitOrigin: fileContext.gitOrigin,
+        rawSource: fileContext.rawSource,
+        serviceTier: fileContext.serviceTier,
+      };
 
-    if (record.type !== "event_msg" || record.payload?.type !== "token_count") {
-      continue;
-    }
+      const call = responseCall(record);
+      if (call) {
+        const ordinalBase = `${currentTurnId}|${call.type}|${call.name}`;
+        const ordinal = (callOrdinals.get(ordinalBase) || 0) + 1;
+        callOrdinals.set(ordinalBase, ordinal);
+        const callKey = call.stableId
+          ? `id|${call.stableId}`
+          : `ordinal|${ordinalBase}|${ordinal}`;
+        operations.push({
+          kind: "call",
+          callKey,
+          turnId: currentTurnId,
+          threadId,
+          originalLikely,
+        });
+        continue;
+      }
 
-    rememberQuota(context.quotas, record.payload.rate_limits, occurrence);
-    const info = record.payload.info;
-    if (!info?.last_token_usage) continue;
+      if (!tokenCountRecord) continue;
 
-    const totalTuple = tokenTuple(info.total_token_usage);
-    const lastTuple = tokenTuple(info.last_token_usage);
-    if (lastTuple[5] <= 0) continue;
-    const contextWindow = asFiniteNumber(info.model_context_window);
-    const eventKey = currentTurnId
-      ? JSON.stringify([
-          currentTurnId,
-          totalTuple,
-          lastTuple,
-          contextWindow,
-        ])
-      : JSON.stringify(["legacy", totalTuple, lastTuple, contextWindow]);
+      const info = record.payload.info;
+      const quotaResult = quotaCandidates(
+        record.payload.rate_limits,
+        occurrence,
+      );
+      invalidQuotaRecords += quotaResult.invalidRecords;
+      if (quotaResult.candidates.length > 0) {
+        operations.push({
+          kind: "quota",
+          candidates: quotaResult.candidates,
+        });
+      }
+      if (info?.last_token_usage === undefined) continue;
 
-    if (
-      previousCumulative !== null &&
-      totalTuple[5] < previousCumulative
-    ) {
-      context.correctionIntervals += 1;
-    }
-    previousCumulative = totalTuple[5];
+      const totalTuple = tokenTuple(info.total_token_usage);
+      const lastTuple = tokenTuple(info.last_token_usage);
+      if (!lastTuple.valid[5]) {
+        invalidTokenRecords += 1;
+        continue;
+      }
+      if (lastTuple.values[5] <= 0) continue;
+      const contextWindow = asFiniteNumber(info.model_context_window);
+      const tokenSignature = JSON.stringify([
+        totalTuple.values,
+        totalTuple.valid,
+        lastTuple.values,
+        lastTuple.valid,
+        contextWindow,
+      ]);
+      const signatureScope = currentTurnId || "legacy";
+      const signatures = tokenSignatures.get(signatureScope) || new Map();
+      let eventOrdinal = signatures.get(tokenSignature);
+      if (!eventOrdinal) {
+        nextTokenOrdinal += 1;
+        const ordinal = nextTokenOrdinal;
+        eventOrdinal = ordinal;
+        signatures.set(tokenSignature, eventOrdinal);
+        tokenSignatures.set(signatureScope, signatures);
+      }
+      const eventKey = currentTurnId
+        ? JSON.stringify([
+            currentTurnId,
+            totalTuple.values,
+            totalTuple.valid,
+            lastTuple.values,
+            lastTuple.valid,
+            contextWindow,
+          ])
+        : JSON.stringify([
+            "legacy",
+            totalTuple.values,
+            totalTuple.valid,
+            lastTuple.values,
+            lastTuple.valid,
+            contextWindow,
+          ]);
 
-    const inserted = context.spool.insertToken(
-      eventKey,
-      currentTurnId,
-      usageFromTuple(lastTuple),
-      occurrence,
-      originalLikely,
-    );
-    if (!inserted) {
-      context.duplicateEventsSkipped += 1;
+      if (
+        totalTuple.valid[5] &&
+        previousCumulative !== null &&
+        totalTuple.values[5] < previousCumulative
+      ) {
+        correctionIntervals += 1;
+      }
+      previousCumulative = totalTuple.valid[5] ? totalTuple.values[5] : null;
+
+      operations.push({
+        kind: "token",
+        eventKey,
+        turnId: currentTurnId,
+        usage: usageFromTuple(lastTuple),
+        occurrence,
+        eventOrdinal,
+        originalLikely,
+      });
     }
+  } finally {
+    lines.close();
   }
-}
-
-function threadMetadata(threadId, stateRows, titles, parents, fallback = {}) {
-  const row = stateRows.get(threadId);
+  try {
+    const cursorFingerprint = contentHash.digest("hex");
+    await revalidateScannedRollout(
+      path,
+      handle,
+      opened,
+      expectedIdentity,
+      maximumBytes,
+      cursorFingerprint,
+    );
+    return {
+      path,
+      cursorFingerprint,
+      continuityBytes,
+      continuityFingerprint: continuityHash && continuityRemaining === 0
+        ? continuityHash.digest("hex")
+        : null,
+      operations,
+      parseErrors,
+      correctionIntervals,
+      invalidTokenRecords,
+      invalidQuotaRecords,
+    };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+function threadMetadata(
+  threadId,
+  stateRows,
+  titles,
+  parents,
+  fallback = {},
+  persistedRows = new Map(),
+) {
+  const row = stateRows.get(threadId);
+  const persisted = persistedRows.get(threadId);
+  const metadataRow = row || persisted;
   const sessionTitle = titles.get(threadId)?.title;
   const labels = sourceLabels(
-    row?.thread_source,
-    fallback.rawSource || row?.source,
+    fallback.source || metadataRow?.thread_source || metadataRow?.source,
+    fallback.rawSource || metadataRow?.source,
   );
   return {
     id: threadId,
-    title: safeTitle(row, sessionTitle),
-    project: projectLabel(
-      fallback.cwd || row?.cwd,
-      fallback.gitOrigin || row?.git_origin_url,
+    title: safeExportLabel(
+      fallback.title || sessionTitle || metadataRow?.title || metadataRow?.name,
+      180,
+      safeTitle(metadataRow, sessionTitle),
+    ),
+    project: safeExportLabel(
+      fallback.project || metadataRow?.project || projectLabel(
+        fallback.cwd || metadataRow?.cwd,
+        fallback.gitOrigin || metadataRow?.git_origin_url,
+      ),
+      160,
+      "Unknown project",
+    ),
+    model: safeExportLabel(
+      normalizeCodexCreditModel(
+        fallback.model || metadataRow?.model || "unknown",
+      ),
+      80,
+      "unknown",
+    ),
+    effort: safeExportLabel(
+      fallback.effort || metadataRow?.reasoning_effort || metadataRow?.effort ||
+        "unknown",
+      40,
+      "unknown",
     ),
-    model: normalizeModel(fallback.model || row?.model || "unknown"),
-    effort: String(
-      fallback.effort || row?.reasoning_effort || "unknown",
-    ).slice(0, 40),
     source: labels.source,
     useType: labels.useType,
-    parentThreadId: parents.get(threadId) || null,
+    parentThreadId: safeExportLabel(
+      fallback.parentThreadId ||
+        parents.get(threadId) ||
+        metadataRow?.parentThreadId,
+      80,
+      null,
+    ),
     reportedCumulativeTokens:
-      row && row.tokens_used !== null
-        ? asFiniteNumber(row.tokens_used)
+      metadataRow && isValidTokenValue(
+        fallback.reportedCumulativeTokens ?? metadataRow.tokens_used ??
+          metadataRow.reportedCumulativeTokens,
+      )
+        ? fallback.reportedCumulativeTokens ?? metadataRow.tokens_used ??
+          metadataRow.reportedCumulativeTokens
         : null,
-    createdAt: isoFromEpoch(row?.created_at),
-    updatedAt: isoFromEpoch(row?.updated_at),
+    createdAt: fallback.createdAt || isoFromEpoch(
+      metadataRow?.created_at || metadataRow?.createdAt,
+    ),
+    updatedAt: fallback.updatedAt || isoFromEpoch(
+      metadataRow?.updated_at || metadataRow?.updatedAt,
+    ),
+  };
+}
+
+const TIMESTAMP_CORRECTION_KIND = "before-own-turn";
+
+function timestampCorrectionOrigin(value, originalTimestamp, fallbackTimestamp) {
+  const parsed = parsedRangeAllocationOrigin(value);
+  const origin = parsed && !Array.isArray(parsed) ? { ...parsed } : {};
+  const current = origin.timestampCorrection;
+  if (
+    current &&
+    !Array.isArray(current) &&
+    Object(current) === current &&
+    current.kind === TIMESTAMP_CORRECTION_KIND &&
+    current.originalTimestamp === originalTimestamp &&
+    current.fallbackTimestamp === fallbackTimestamp
+  ) {
+    return origin;
+  }
+  origin.timestampCorrection = {
+    kind: TIMESTAMP_CORRECTION_KIND,
+    originalTimestamp,
+    fallbackTimestamp,
+  };
+  return origin;
+}
+
+function timestampRepairForToken(token) {
+  if (!token || typeof token !== "object") return null;
+  if (
+    token.identityKind != null &&
+    primitiveString(token.identityKind) !== "exact"
+  ) return null;
+  const turnId = primitiveString(token.turnId)?.trim();
+  const threadId = primitiveString(token.threadId)?.trim();
+  const originThreadId = primitiveString(token.originThreadId)?.trim();
+  if (!turnId || !threadId || !originThreadId || threadId !== originThreadId) {
+    return null;
+  }
+  const tokenTimestamp = token.timestamp == null
+    ? null
+    : safeIso(token.timestamp, null);
+  const originTimestamp = token.originTimestamp == null
+    ? null
+    : safeIso(token.originTimestamp, null);
+  if (!tokenTimestamp || !originTimestamp) return null;
+  const tokenMs = Date.parse(tokenTimestamp);
+  const originMs = Date.parse(originTimestamp);
+  if (!Number.isFinite(tokenMs) || !Number.isFinite(originMs)) return null;
+  // There is no clock-skew tolerance here: an event before its own known turn
+  // is impossible, and the turn origin is the only defensible fallback.
+  if (tokenMs >= originMs) return null;
+  return {
+    timestamp: originTimestamp,
+    rangeAllocationEstimated: true,
+    rangeAllocationOrigin: timestampCorrectionOrigin(
+      token.rangeAllocationOrigin,
+      tokenTimestamp,
+      originTimestamp,
+    ),
+  };
+}
+
+function repairTokenTimestamp(token) {
+  const repair = timestampRepairForToken(token);
+  if (!repair) return token;
+  return {
+    ...token,
+    timestamp: repair.timestamp,
+    rangeAllocationEstimated: repair.rangeAllocationEstimated,
+    rangeAllocationOrigin: repair.rangeAllocationOrigin,
   };
 }
 
 function resolvedOccurrence(token) {
-  const origin = token.originThreadId == null
+  const resolvedToken = repairTokenTimestamp(token);
+  const origin = resolvedToken.originThreadId == null
     ? null
     : {
-        threadId: token.originThreadId,
-        timestamp: token.originTimestamp,
-        model: token.originModel,
-        effort: token.originEffort,
-        cwd: token.originCwd,
-        gitOrigin: token.originGitOrigin,
-        rawSource: token.originRawSource,
-        serviceTier: token.originServiceTier,
+        threadId: resolvedToken.originThreadId,
+        timestamp: resolvedToken.originTimestamp,
+        model: resolvedToken.originModel,
+        effort: resolvedToken.originEffort,
+        cwd: resolvedToken.originCwd,
+        gitOrigin: resolvedToken.originGitOrigin,
+        rawSource: resolvedToken.originRawSource,
+        serviceTier: resolvedToken.originServiceTier,
       };
-  const occurrence = token.originalLikely || !origin ? token : origin;
+  const occurrence = resolvedToken.originalLikely || !origin
+    ? resolvedToken
+    : origin;
   return {
     origin,
     occurrence,
     threadId: origin?.threadId || occurrence.threadId,
-    timestamp: token.timestamp || origin?.timestamp,
+    timestamp: resolvedToken.timestamp || origin?.timestamp,
   };
 }
 
+function parsedRangeAllocationOrigin(value) {
+  if (value && Object(value) === value) return value;
+  const source = primitiveString(value);
+  if (source === null || source.length === 0) return null;
+  try {
+    const parsed = JSON.parse(source);
+    return parsed && Object(parsed) === parsed ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 function newThreadAggregate(metadata, timestamp) {
   return {
     metadata,
@@ -1030,33 +2555,131 @@ function newThreadAggregate(metadata, timestamp) {
     unknownBreakdownTokens: 0,
     rateCardCredits: 0,
     ratedTokens: 0,
+    hasPositiveUnrated: false,
     eventCount: 0,
   };
 }
 
 function addToThreadAggregate(aggregate, event) {
+  const allowFractional = event.rangeAllocationEstimated === true;
   aggregate.lastActiveAt = event.timestamp;
-  aggregate.inputTokens += event.inputTokens;
-  aggregate.cachedInputTokens += event.cachedInputTokens;
-  aggregate.outputTokens += event.outputTokens;
-  aggregate.reasoningTokens += event.reasoningTokens;
-  aggregate.totalTokens += event.totalTokens;
-  aggregate.toolCalls += event.toolCalls;
-  aggregate.eventCount += 1;
+  aggregate.inputTokens = checkedTokenAdd(
+    aggregate.inputTokens,
+    event.inputTokens,
+    { allowFractional },
+  );
+  aggregate.cachedInputTokens = checkedTokenAdd(
+    aggregate.cachedInputTokens,
+    event.cachedInputTokens,
+    { allowFractional },
+  );
+  aggregate.outputTokens = checkedTokenAdd(
+    aggregate.outputTokens,
+    event.outputTokens,
+    { allowFractional },
+  );
+  aggregate.reasoningTokens = checkedTokenAdd(
+    aggregate.reasoningTokens,
+    event.reasoningTokens,
+    { allowFractional },
+  );
+  aggregate.totalTokens = checkedTokenAdd(
+    aggregate.totalTokens,
+    event.totalTokens,
+    { allowFractional },
+  );
+  aggregate.toolCalls = checkedTokenAdd(
+    aggregate.toolCalls,
+    event.toolCalls,
+    { allowFractional },
+  );
+  aggregate.cachedInputTokens = Math.min(
+    aggregate.inputTokens,
+    aggregate.cachedInputTokens,
+  );
+  aggregate.reasoningTokens = Math.min(
+    aggregate.outputTokens,
+    aggregate.reasoningTokens,
+  );
+  aggregate.eventCount = checkedTokenAdd(
+    aggregate.eventCount,
+    Number.isFinite(event.callCount) && event.callCount > 0
+      ? event.callCount
+      : 1,
+    { allowFractional: true },
+  );
   if (event.breakdownAvailable) {
-    aggregate.detailedTokens += event.totalTokens;
+    aggregate.detailedTokens = checkedTokenAdd(
+      aggregate.detailedTokens,
+      event.totalTokens,
+      { allowFractional },
+    );
   } else {
-    aggregate.unknownBreakdownTokens += event.totalTokens;
+    aggregate.unknownBreakdownTokens = checkedTokenAdd(
+      aggregate.unknownBreakdownTokens,
+      event.totalTokens,
+      { allowFractional },
+    );
   }
   if (event.rateCardCredits !== null) {
-    aggregate.rateCardCredits += event.rateCardCredits;
-    aggregate.ratedTokens += event.totalTokens;
+    aggregate.rateCardCredits = checkedFiniteAdd(
+      aggregate.rateCardCredits,
+      event.rateCardCredits,
+    );
+    aggregate.ratedTokens = checkedTokenAdd(
+      aggregate.ratedTokens,
+      event.totalTokens,
+    );
+  } else if (event.totalTokens > 0) {
+    aggregate.hasPositiveUnrated = true;
   }
 }
 
+function representableUnknownBreakdownTokens(
+  observedTokens,
+  detailedTokens,
+  unknownBreakdownTokens,
+) {
+  if (
+    observedTokens >= MAX_SAFE_TOKEN_COUNT &&
+    detailedTokens >= MAX_SAFE_TOKEN_COUNT
+  ) {
+    return unknownBreakdownTokens;
+  }
+  return Math.min(
+    unknownBreakdownTokens,
+    Math.max(0, observedTokens - detailedTokens),
+  );
+}
+
 function buildSnapshot(context, options, titles) {
   context.spool.finishWrites();
-  const sinceMs = options.since ? options.since.getTime() : -Infinity;
+  const scope = collectionScope(options);
+  const sinceMs = scope.since === null ? -Infinity : Date.parse(scope.since);
+
+  function scopedTokenTimestamp(token, timestamp) {
+    const timestampMs = Date.parse(timestamp);
+    if (!Number.isFinite(timestampMs)) return null;
+    if (sinceMs === -Infinity || timestampMs >= sinceMs) return timestamp;
+    const range = parsedRangeAllocationOrigin(token.rangeAllocationOrigin);
+    const bounds = [timestampMs, range?.startAt, range?.endAt]
+      .map((value) => Date.parse(String(value ?? "")))
+      .filter(Number.isFinite);
+    const endExclusive = Math.max(...bounds) + 1;
+    if (endExclusive <= sinceMs) return null;
+    const startMs = Math.max(sinceMs, Math.min(...bounds));
+    return new Date(Math.round(
+      startMs + (endExclusive - startMs - 1) / 2,
+    )).toISOString();
+  }
+
+  function scopedEventFragments(event) {
+    if (sinceMs === -Infinity) return [event];
+    return splitUsageBucketsAtBoundaries([event], [sinceMs]).filter(
+      (fragment) => Date.parse(fragment.timestamp) >= sinceMs,
+    );
+  }
+
   const lastEventKeyByTurn = new Map();
   let earliestEventAt = null;
   let latestEventAt = null;
@@ -1065,9 +2688,20 @@ function buildSnapshot(context, options, titles) {
   // receives each turn's tool calls without retaining the usage rows.
   for (const token of context.spool.tokenRows()) {
     const { threadId, timestamp } = resolvedOccurrence(token);
-    if (Date.parse(timestamp) < sinceMs) continue;
-    earliestEventAt ||= timestamp;
-    latestEventAt = timestamp;
+    const scopedTimestamp = scopedTokenTimestamp(token, timestamp);
+    if (!scopedTimestamp) continue;
+    if (
+      earliestEventAt === null ||
+      Date.parse(scopedTimestamp) < Date.parse(earliestEventAt)
+    ) {
+      earliestEventAt = scopedTimestamp;
+    }
+    if (
+      latestEventAt === null ||
+      Date.parse(scopedTimestamp) > Date.parse(latestEventAt)
+    ) {
+      latestEventAt = scopedTimestamp;
+    }
     const key = token.turnId || `thread:${threadId}`;
     lastEventKeyByTurn.set(key, token.eventKey);
   }
@@ -1079,22 +2713,30 @@ function buildSnapshot(context, options, titles) {
   }
 
   const threadAggregates = new Map();
+  const coverage = {
+    detailedTokens: 0,
+    unknownBreakdownTokens: 0,
+  };
   let observedTokens = 0;
-  let detailedTokens = 0;
   let legacyHeuristicEvents = 0;
   let observedModelCalls = 0;
+  let exactObservedModelCalls = 0;
+  let migratedCompactedCalls = 0;
+  let migratedCompactedTokens = 0;
 
   function* compactableEvents() {
     for (const token of context.spool.tokenRows()) {
       const { origin, occurrence, threadId, timestamp } = resolvedOccurrence(token);
-      if (Date.parse(timestamp) < sinceMs) continue;
       const metadata = threadMetadata(
         threadId,
         context.stateRows,
         titles,
         context.parents,
         origin || occurrence,
+        context.persistedThreads,
       );
+      const rangeAllocationEstimated =
+        Number(token.rangeAllocationEstimated) === 1;
       const usage = {
         inputTokens: Number(token.inputTokens),
         cachedInputTokens: Number(token.cachedInputTokens),
@@ -1102,45 +2744,106 @@ function buildSnapshot(context, options, titles) {
         outputTokens: Number(token.outputTokens),
         reasoningTokens: Number(token.reasoningTokens),
         totalTokens: Number(token.totalTokens),
+        componentsValid: Number(token.componentsValid) === 1,
+        toolCalls: Number(token.toolCalls),
+        callCount: Number(token.callCount),
+        detailedCallCount: Number(token.detailedCallCount),
+        inputCallCount: Number(token.inputCallCount),
+        rangeAllocationEstimated,
       };
-      const breakdownAvailable = hasDetailedBreakdown(usage);
-      const serviceTier = occurrence.serviceTier || null;
-      const baseCredits = creditsForUsage(metadata.model, usage);
+      const rangeAllocationOrigin = parsedRangeAllocationOrigin(
+        token.rangeAllocationOrigin,
+      );
+      const storedRateCardCredits = token.rateCardCredits == null
+        ? null
+        : Number(token.rateCardCredits);
+      const breakdownAvailable = hasDetailedTokenBreakdown(usage);
+      const serviceTier = safeExportLabel(occurrence.serviceTier, 40, null);
       const turnKey = token.turnId || `thread:${threadId}`;
+      const sourceToolCalls = lastEventKeyByTurn.get(turnKey) === token.eventKey
+        ? toolCounts.get(turnKey) || 0
+        : 0;
+      const persistedToolCalls = Number.isFinite(Number(token.toolCalls))
+        ? Math.max(0, Number(token.toolCalls))
+        : 0;
       const event = {
         ...usage,
         timestamp,
+        startAt: rangeAllocationOrigin?.startAt || timestamp,
+        endAt: rangeAllocationOrigin?.endAt || timestamp,
         threadId,
-        project: metadata.project,
-        model: metadata.model,
-        effort: metadata.effort,
-        source: metadata.source,
-        useType: metadata.useType,
-        toolCalls:
-          lastEventKeyByTurn.get(turnKey) === token.eventKey
-            ? toolCounts.get(turnKey) || 0
-            : 0,
+        project: token.project || metadata.project,
+        model: token.displayModel || metadata.model,
+        rateCardModel: token.rateCardModel || occurrence.model || metadata.model,
+        effort: token.effort || metadata.effort,
+        source: token.sourceLabel || metadata.source,
+        useType: token.useType || metadata.useType,
+        toolCalls: Math.max(sourceToolCalls, persistedToolCalls),
         serviceTier,
-        rateCardCredits:
-          baseCredits === null
-            ? null
-            : serviceTier === "priority"
-              ? baseCredits * FAST_MODE_MULTIPLIER
-              : baseCredits,
+        // Keep the canonical model for snapshot display, but preserve the raw
+        // identifier for multiplier selection so unsupported aliases do not
+        // inherit a canonical Daybreak multiplier.
+        rateCardCredits: Number.isFinite(storedRateCardCredits)
+          ? storedRateCardCredits
+          : calculateCodexPurchasedCredits({
+            model: occurrence.model || metadata.model,
+            serviceTier,
+            usage,
+          }),
         breakdownAvailable,
+        rangeAllocationEstimated,
+        rangeAllocationOrigin,
       };
 
-      let aggregate = threadAggregates.get(threadId);
-      if (!aggregate) {
-        aggregate = newThreadAggregate(metadata, timestamp);
-        threadAggregates.set(threadId, aggregate);
+      for (const scopedEvent of scopedEventFragments(event)) {
+        let aggregate = threadAggregates.get(threadId);
+        if (!aggregate) {
+          aggregate = newThreadAggregate(metadata, scopedEvent.timestamp);
+          threadAggregates.set(threadId, aggregate);
+        }
+        addToThreadAggregate(aggregate, scopedEvent);
+        observedTokens = checkedTokenAdd(
+          observedTokens,
+          scopedEvent.totalTokens,
+          { allowFractional: scopedEvent.rangeAllocationEstimated === true },
+        );
+        checkedTokenPartitionAdd(coverage, scopedEvent.totalTokens, {
+          detailed: scopedEvent.breakdownAvailable,
+        });
+        if (token.identityKind === "exact" && !token.turnId) {
+          legacyHeuristicEvents += 1;
+        }
+        observedModelCalls = checkedTokenAdd(
+          observedModelCalls,
+          Number.isFinite(scopedEvent.callCount) && scopedEvent.callCount > 0
+            ? scopedEvent.callCount
+            : 1,
+          { allowFractional: true },
+        );
+        if (token.identityKind === "migrated_compacted") {
+          migratedCompactedCalls = checkedTokenAdd(
+            migratedCompactedCalls,
+            Number.isFinite(scopedEvent.callCount) && scopedEvent.callCount > 0
+              ? scopedEvent.callCount
+              : 1,
+            { allowFractional: true },
+          );
+          migratedCompactedTokens = checkedTokenAdd(
+            migratedCompactedTokens,
+            scopedEvent.totalTokens,
+            { allowFractional: scopedEvent.rangeAllocationEstimated === true },
+          );
+        } else {
+          exactObservedModelCalls = checkedTokenAdd(
+            exactObservedModelCalls,
+            Number.isFinite(scopedEvent.callCount) && scopedEvent.callCount > 0
+              ? scopedEvent.callCount
+              : 1,
+            { allowFractional: true },
+          );
+        }
+        yield scopedEvent;
       }
-      addToThreadAggregate(aggregate, event);
-      observedTokens += event.totalTokens;
-      if (breakdownAvailable) detailedTokens += event.totalTokens;
-      if (!token.turnId) legacyHeuristicEvents += 1;
-      observedModelCalls += 1;
-      yield event;
     }
   }
 
@@ -1151,8 +2854,15 @@ function buildSnapshot(context, options, titles) {
   toolCounts.clear();
   lastEventKeyByTurn.clear();
 
-  const allThreadIds = new Set(context.stateRows.keys());
+  const allThreadIds = new Set(
+    scope.since === null ? context.stateRows.keys() : threadAggregates.keys(),
+  );
   for (const threadId of threadAggregates.keys()) allThreadIds.add(threadId);
+  if (scope.since === null) {
+    for (const threadId of context.persistedThreads.keys()) {
+      allThreadIds.add(threadId);
+    }
+  }
   const threads = [];
   for (const threadId of allThreadIds) {
     const aggregate = threadAggregates.get(threadId);
@@ -1161,13 +2871,25 @@ function buildSnapshot(context, options, titles) {
       context.stateRows,
       titles,
       context.parents,
+      {},
+      context.persistedThreads,
     );
-    if (!aggregate && !(metadata.reportedCumulativeTokens > 0)) continue;
+    if (
+      !aggregate &&
+      (scope.since !== null || !(metadata.reportedCumulativeTokens > 0))
+    ) continue;
     const eventCount = aggregate?.eventCount || 0;
+    const unknownBreakdownTokens = aggregate
+      ? representableUnknownBreakdownTokens(
+          aggregate.totalTokens,
+          aggregate.detailedTokens,
+          aggregate.unknownBreakdownTokens,
+        )
+      : 0;
     const threadCoverage =
       eventCount === 0
         ? "unresolved"
-        : aggregate.detailedTokens === aggregate.totalTokens
+        : aggregate.unknownBreakdownTokens === 0
           ? "complete"
           : aggregate.detailedTokens > 0
             ? "partial"
@@ -1185,7 +2907,7 @@ function buildSnapshot(context, options, titles) {
       lastActiveAt: aggregate?.lastActiveAt || metadata.updatedAt,
       totalTokens: aggregate?.totalTokens || 0,
       detailedTokens: aggregate?.detailedTokens || 0,
-      unknownBreakdownTokens: aggregate?.unknownBreakdownTokens || 0,
+      unknownBreakdownTokens,
       reportedCumulativeTokens: metadata.reportedCumulativeTokens,
       inputTokens: aggregate?.inputTokens || 0,
       cachedInputTokens: aggregate?.cachedInputTokens || 0,
@@ -1193,6 +2915,7 @@ function buildSnapshot(context, options, titles) {
       reasoningTokens: aggregate?.reasoningTokens || 0,
       rateCardCredits:
         aggregate?.totalTokens > 0 &&
+        !aggregate.hasPositiveUnrated &&
         aggregate.ratedTokens === aggregate.totalTokens
           ? aggregate.rateCardCredits
           : null,
@@ -1213,19 +2936,29 @@ function buildSnapshot(context, options, titles) {
       const exported = { ...quota };
       delete exported.turnId;
       delete exported.originalLikely;
+      if (
+        sinceMs !== -Infinity &&
+        Date.parse(exported.timestamp) < sinceMs &&
+        Date.parse(exported.lastSeenAt) >= sinceMs
+      ) {
+        exported.timestamp = new Date(sinceMs).toISOString();
+      }
       return exported;
     })
     .filter((quota) => {
-      if (!options.since) return true;
       return Date.parse(quota.lastSeenAt) >= sinceMs;
     })
     .sort(
       (left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp),
     );
 
-  const unknownBreakdownTokens = observedTokens - detailedTokens;
+  const { detailedTokens, unknownBreakdownTokens } = coverage;
+  const coverageTokens = detailedTokens + unknownBreakdownTokens;
   const stateCounterSumNonAdditive = threads.reduce(
-    (sum, thread) => sum + (thread.reportedCumulativeTokens || 0),
+    (sum, thread) => checkedTokenAdd(
+      sum,
+      thread.reportedCumulativeTokens || 0,
+    ),
     0,
   );
   const unresolvedThreadCounters = threads.filter(
@@ -1237,11 +2970,9 @@ function buildSnapshot(context, options, titles) {
     (quota) => quota.windowMinutes === WEEK_MINUTES,
   );
   const accountWideWeekly = weeklyCandidates.filter(
-    (quota) => !quota.limitName,
+    (quota) => quota.scope === "account",
   );
-  const weekly = [
-    ...(accountWideWeekly.length ? accountWideWeekly : weeklyCandidates),
-  ]
+  const weekly = accountWideWeekly
     .sort(
       (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt),
     )[0];
@@ -1249,18 +2980,26 @@ function buildSnapshot(context, options, titles) {
     ? (weekly.resetsAt - weekly.windowMinutes * 60) * 1_000
     : null;
   const completeSinceWindowStart = Boolean(
-    weeklyStart &&
+    scope.since === null &&
+      scope.includeArchived &&
+      weeklyStart &&
       earliestEventAt &&
       Date.parse(earliestEventAt) <= weeklyStart &&
-      context.parseErrors === 0,
+      context.parseErrors === 0 &&
+      context.invalidTokenRecords === 0 &&
+      context.invalidQuotaRecords === 0 &&
+      !context.durableLedger?.sourceSummary?.sourceIncomplete &&
+      migratedCompactedCalls === 0,
   );
 
   const notes = [
     "Observed totals sum globally de-duplicated last_token_usage model-call events.",
     "The snapshot keeps exact recent calls and compacts older usage into time buckets; token, cache, model, project, tool-call, and thread totals remain additive.",
     "Codex thread counters are retained only as non-additive reference values because forks and subagents inherit cumulative history.",
-    "Historical rollout files can be pruned; a state-only counter cannot reveal that thread's unique token contribution.",
+    "Historical rollout files can be pruned; the private durable ledger keeps committed observations without making a state-only counter additive.",
     "Legacy events without turn IDs use a high-specificity usage-signature heuristic and are labeled in the ledger.",
+    "Source files are mutable inputs. Missing or tombstoned sources never delete committed observations and are surfaced in coverage.",
+    "Migrated compacted rows preserve totals but do not invent exact event or turn identities; estimated values remain marked.",
   ];
 
   return {
@@ -1269,16 +3008,48 @@ function buildSnapshot(context, options, titles) {
     label: "Local Codex snapshot",
     provenance: {
       kind: "codex-local-metadata",
+      collection: scope,
+      sourceCutoffAt: context.sourceInventory.cutoffAt,
       privacy:
-        "Contains token metadata and Codex display titles only; credential fields, message bodies, reasoning text, tool payloads, and full local paths are not exported. Display titles may contain user-written text.",
-      rateCardAsOf: RATE_CARD_AS_OF,
-      rateCardUrl: RATE_CARD_URL,
+        "Contains token metadata and Codex display titles only; credential fields, message bodies, reasoning text, tool payloads, and full local paths are not exported. Path-like source labels are categorized and local path tokens in other labels are redacted; unrelated user-written title text may remain.",
+      rateCardKind: CODEX_CREDIT_RATE_CARD_KIND,
+      rateCardAsOf: CODEX_CREDIT_RATE_CARD_AS_OF,
+      rateCardUrl: CODEX_CREDIT_RATE_CARD_URL,
+      rateCardScope: CODEX_CREDIT_RATE_CARD_SCOPE,
+    },
+    metadata: {
+      stateDatabase: context.stateDatabase,
+      durableLedger: context.durableLedger
+        ? {
+            schemaVersion: DURABLE_LEDGER_SCHEMA_VERSION,
+            revision: context.durableLedger.revision,
+            quotaIdentityContract: QUOTA_IDENTITY_CONTRACT_VERSION,
+            codexHomeFingerprint: codexHomeFingerprint(context.codexHome),
+            retentionDays: DURABLE_LEDGER_RETENTION_DAYS,
+            compactedRetentionDays: DURABLE_LEDGER_COMPACTED_RETENTION_DAYS,
+            legacySnapshotStatus:
+              context.durableLedger.legacySnapshotStatus || null,
+            legacyQuotaStatus:
+              context.durableLedger.legacyQuotaStatus || null,
+            legacyQuotaRowsSkipped:
+              context.durableLedger.legacyQuotaRowsSkipped || 0,
+            quotaContractUpgradeStatus:
+              context.durableLedger.quotaContractUpgradeStatus || null,
+            quotaContractRowsDiscarded:
+              (context.durableLedger.quotaContractMigratedRowsDiscarded || 0) +
+              (context.durableLedger.quotaContractExactRowsDiscarded || 0),
+          }
+        : null,
     },
     coverage: {
       filesScanned: context.filesScanned,
       bytesScanned: context.bytesScanned,
+      filesReused: context.filesReused,
+      bytesReused: context.bytesReused,
       parseErrors: context.parseErrors,
       duplicateEventsSkipped: context.duplicateEventsSkipped,
+      invalidTokenRecords: context.invalidTokenRecords,
+      invalidQuotaRecords: context.invalidQuotaRecords,
       correctionIntervals: context.correctionIntervals,
       observedTokens,
       detailedTokens,
@@ -1287,10 +3058,35 @@ function buildSnapshot(context, options, titles) {
       unresolvedThreadCounters,
       legacyHeuristicEvents,
       observedModelCalls,
+      exactObservedModelCalls,
+      migratedCompactedCalls,
+      migratedCompactedTokens,
+      migratedCompactedBuckets:
+        context.durableLedger?.migratedUsageRows || 0,
+      migratedQuotaObservations:
+        context.durableLedger?.migratedQuotaRows || 0,
+      compactedUsageBuckets:
+        context.durableLedger?.compactedUsageRows || 0,
+      legacySnapshotStatus:
+        context.durableLedger?.legacySnapshotStatus || null,
+      legacyQuotaStatus:
+        context.durableLedger?.legacyQuotaStatus || null,
+      legacyQuotaRowsSkipped:
+        context.durableLedger?.legacyQuotaRowsSkipped || 0,
+      sourceIncomplete: Boolean(
+        context.durableLedger?.sourceSummary?.sourceIncomplete,
+      ),
+      sourceStates: context.durableLedger?.sourceSummary?.counts || {
+        active: 0,
+        archived: 0,
+        missing: 0,
+        tombstoned: 0,
+        changed: 0,
+      },
       usageBucketCount: usageStats.bucketCount,
       maximumUsageResolutionSeconds: usageStats.maximumResolutionSeconds,
       detailedPercent:
-        observedTokens > 0 ? (detailedTokens / observedTokens) * 100 : 100,
+        coverageTokens > 0 ? (detailedTokens / coverageTokens) * 100 : 100,
       earliestEventAt,
       latestEventAt,
       completeSinceWindowStart,
@@ -1302,65 +3098,1062 @@ function buildSnapshot(context, options, titles) {
   };
 }
 
-export async function collectUsage(options, onProgress = () => {}) {
-  const state = await readState(options.codexHome);
-  const titles = await readSessionTitles(
-    resolve(options.codexHome, "session_index.jsonl"),
-  );
-  const roots = [resolve(options.codexHome, "sessions")];
-  if (options.includeArchived) {
-    roots.push(resolve(options.codexHome, "archived_sessions"));
-  }
-  const files = (
-    await Promise.all(roots.map((root) => listJsonlFiles(root)))
-  )
-    .flat()
-    .sort();
-  const sizes = await Promise.all(files.map((path) => stat(path)));
-  const spool = await createUsageSpool();
-
-  const context = {
+function createCollectionContext(state, spool, options) {
+  return {
+    codexHome: options.codexHome,
     stateRows: state.rows,
     parents: state.parents,
+    stateDatabase: state.metadata,
     quotas: new Map(),
+    quotaLabels: new Map(),
+    eventSources: new Map(),
+    eventPositions: [],
+    callSources: new Map(),
+    quotaSources: new Map(),
+    quotaSourceBounds: new Map(),
+    persistedThreads: new Map(),
+    trustedScannedSourceIds: new Set(),
+    durableLedger: null,
     spool,
     filesScanned: 0,
     bytesScanned: 0,
+    filesReused: 0,
+    bytesReused: 0,
     parseErrors: 0,
     duplicateEventsSkipped: 0,
+    invalidTokenRecords: 0,
+    invalidQuotaRecords: 0,
     correctionIntervals: 0,
+    uncertainSourceIds: new Set(),
+    quotaUncertainSourceIds: new Set(),
+    // Capture the complete observed ledger even when the requested snapshot
+    // is filtered. buildSnapshot applies the requested scope on materialize.
+    sinceMs: -Infinity,
+  };
+}
+
+function sourceMatchesDurableCursor(entry, prior) {
+  if (
+    !prior ||
+    prior.reconciliationPending ||
+    prior.quotaReconciliationPending
+  ) return false;
+  const size = Number(entry.size);
+  const cursorBytes = Number(prior.cursorBytes);
+  const device = entry.dev == null ? null : Number(entry.dev);
+  const inode = entry.ino == null ? null : Number(entry.ino);
+  return (
+    Number.isSafeInteger(size) &&
+    size >= 0 &&
+    Number.isSafeInteger(cursorBytes) &&
+    cursorBytes >= 0 &&
+    cursorBytes <= size &&
+    size === Number(prior.sizeBytes) &&
+    Number(entry.mtimeMs) === Number(prior.mtimeMs) &&
+    Number(entry.ctimeMs) === Number(prior.ctimeMs) &&
+    device === prior.device &&
+    inode === prior.inode &&
+    prior.cursorFingerprint.length === 64
+  );
+}
+
+function durableLedgerRelatedPaths(options) {
+  const ledgerPath = resolveDurableLedgerPath(options);
+  return [
+    ledgerPath,
+    `${ledgerPath}.writer-lock.sqlite`,
+    `${ledgerPath}-journal`,
+    `${ledgerPath}-wal`,
+    `${ledgerPath}-shm`,
+  ];
+}
+
+function addSourceAssociation(map, key, sourceId) {
+  if (!sourceId) return;
+  const sourceIds = map.get(key) || new Set();
+  sourceIds.add(sourceId);
+  map.set(key, sourceIds);
+}
+
+function addQuotaSourceBounds(map, key, sourceId, timestamp) {
+  if (!sourceId) return;
+  const bySource = map.get(key) || new Map();
+  const current = bySource.get(sourceId);
+  bySource.set(sourceId, {
+    firstSeenAt: current && current.firstSeenAt < timestamp
+      ? current.firstSeenAt
+      : timestamp,
+    lastSeenAt: current && current.lastSeenAt > timestamp
+      ? current.lastSeenAt
+      : timestamp,
+  });
+  map.set(key, bySource);
+}
+
+function eventMetadataForToken(token, context, titles) {
+  const { origin, occurrence, threadId } = resolvedOccurrence(token);
+  const metadata = threadMetadata(
+    threadId,
+    context.stateRows,
+    titles,
+    context.parents,
+    origin || occurrence,
+    context.persistedThreads,
+  );
+  return {
+    project: token.project || metadata.project,
+    model: token.displayModel || metadata.model,
+    source: token.sourceLabel || metadata.source,
+    useType: token.useType || metadata.useType,
+    rateCardModel: token.rateCardModel || occurrence.model || metadata.model,
   };
+}
 
-  try {
-    for (let index = 0; index < files.length; index += 1) {
-      await scanRollout(files[index], context);
-      context.filesScanned += 1;
-      context.bytesScanned += sizes[index].size;
-      if (
-        index === 0 ||
-        index === files.length - 1 ||
-        (index + 1) % 10 === 0
-      ) {
-        onProgress({
-          current: index + 1,
-          total: files.length,
-          path: files[index],
+function threadRecordsForLedger(context, titles) {
+  const records = new Map();
+  const remember = (threadId, fallback = {}) => {
+    if (!threadId) return;
+    const metadata = threadMetadata(
+      threadId,
+      context.stateRows,
+      titles,
+      context.parents,
+      fallback,
+      context.persistedThreads,
+    );
+    records.set(threadId, metadata);
+  };
+  for (const threadId of context.stateRows.keys()) remember(threadId);
+  for (const threadId of context.parents.keys()) remember(threadId);
+  for (const [threadId, persisted] of context.persistedThreads) {
+    const sessionTitle = titles.get(threadId)?.title;
+    // A title-only index change is a real metadata observation. Untouched
+    // persisted rows remain read-only fallbacks so retention can expire them.
+    if (sessionTitle == null) continue;
+    const current = threadMetadata(
+      threadId,
+      context.stateRows,
+      titles,
+      context.parents,
+      {},
+      context.persistedThreads,
+    );
+    if (current.title === persisted.title) continue;
+    remember(threadId);
+  }
+  for (const token of context.spool.tokenRows()) {
+    const { origin, occurrence, threadId } = resolvedOccurrence(token);
+    remember(threadId, origin || occurrence);
+  }
+  return [...records.values()];
+}
+
+const DURABLE_USAGE_FIELDS = Object.freeze([
+  "inputTokens",
+  "cachedInputTokens",
+  "cacheWriteInputTokens",
+  "outputTokens",
+  "reasoningTokens",
+  "totalTokens",
+  "toolCalls",
+  "rateCardCredits",
+]);
+const DURABLE_COUNT_FIELDS = Object.freeze([
+  "callCount",
+  "detailedCallCount",
+  "inputCallCount",
+]);
+
+function subtractCompactedRows(
+  row,
+  currentRowsByEventKey,
+  currentCallKeys,
+) {
+  const compactedEventKeys = row.compactedEventKeys;
+  if (
+    compactedEventKeys == null ||
+    !compactedEventKeys[Symbol.iterator]
+  ) {
+    return row;
+  }
+  const matches = [];
+  for (const eventKey of compactedEventKeys) {
+    const current = currentRowsByEventKey.get(String(eventKey));
+    if (current) matches.push(current);
+  }
+  const ownedToolCallKeys = Array.isArray(row.toolCallKeys)
+    ? row.toolCallKeys.map((callKey) => String(callKey))
+    : null;
+  const activeToolCallKeys = ownedToolCallKeys
+    ? ownedToolCallKeys.filter((callKey) => currentCallKeys.has(callKey))
+    : [];
+  if (!matches.length && !activeToolCallKeys.length) return row;
+  const residual = { ...row };
+  for (const field of DURABLE_USAGE_FIELDS) {
+    if (field === "rateCardCredits") {
+      const known = matches.every((match) => match.rateCardCredits != null);
+      residual[field] = known
+        ? Math.max(
+          0,
+          Number(row[field] || 0) - matches.reduce(
+            (sum, match) => sum + Number(match.rateCardCredits || 0),
+            0,
+          ),
+        )
+        : row[field];
+      continue;
+    }
+    residual[field] = Math.max(
+      0,
+      Number(row[field] || 0) - matches.reduce(
+        (sum, match) => sum + Number(match[field] || 0),
+        0,
+      ),
+    );
+  }
+  if (ownedToolCallKeys) {
+    residual.toolCalls = Math.max(
+      0,
+      Number(row.toolCalls || 0) - activeToolCallKeys.length,
+    );
+    residual.toolCallKeys = ownedToolCallKeys.filter(
+      (callKey) => !currentCallKeys.has(callKey),
+    );
+  }
+  for (const field of DURABLE_COUNT_FIELDS) {
+    residual[field] = Math.max(
+      0,
+      Number(row[field] || 0) - matches.reduce(
+        (sum, match) => sum + Number(match[field] || 0),
+        0,
+      ),
+    );
+  }
+  if (residual.totalTokens <= 0 && residual.callCount <= 0) return null;
+  const origin = row.rangeAllocationOrigin &&
+    Object(row.rangeAllocationOrigin) === row.rangeAllocationOrigin
+    ? { ...row.rangeAllocationOrigin }
+    : null;
+  if (origin) {
+    origin.inputTokens = residual.inputTokens;
+    origin.totalTokens = residual.totalTokens;
+    origin.callCount = residual.callCount;
+    residual.rangeAllocationOrigin = origin;
+  }
+  residual.compactedEventKeys = [];
+  return residual;
+}
+
+function createDurableSpoolSink(context) {
+  // Keep the durable read independent from the ingest metadata map. These
+  // lookup sets are allocated only after ingest has finished and only when a
+  // compacted or tool row actually needs them.
+  let currentRowsByEventKey = null;
+  let currentCallKeys = null;
+  const ensureCurrentCallKeys = () => {
+    if (currentCallKeys) return;
+    currentCallKeys = new Set();
+    for (const call of context.spool.callRows()) {
+      currentCallKeys.add(String(call.callKey));
+    }
+  };
+  const ensureCurrentRows = () => {
+    if (currentRowsByEventKey) return;
+    currentRowsByEventKey = new Map();
+    for (const current of context.spool.tokenRows()) {
+      currentRowsByEventKey.set(String(current.eventKey), current);
+    }
+    ensureCurrentCallKeys();
+  }
+
+  function consumeUsage(storedRow) {
+    if (storedRow.identityKind === "compacted") ensureCurrentRows();
+    const row = storedRow.identityKind === "compacted"
+      ? subtractCompactedRows(
+        storedRow,
+        currentRowsByEventKey,
+        currentCallKeys,
+      )
+      : repairTokenTimestamp(storedRow);
+    if (!row) return;
+    if (row.originThreadId) {
+      context.spool.insertOrigin({
+        turnId: row.turnId,
+        threadId: row.originThreadId,
+        timestamp: row.originTimestamp || row.timestamp,
+        deltaMs: 0,
+        model: row.originModel || row.model,
+        effort: row.originEffort || row.effort,
+        cwd: row.originCwd || row.cwd,
+        gitOrigin: row.originGitOrigin || row.gitOrigin,
+        rawSource: row.originRawSource || row.rawSource,
+        serviceTier: row.originServiceTier || row.serviceTier,
+      });
+    }
+    const occurrence = {
+      threadId: row.threadId,
+      timestamp: row.timestamp,
+      model: row.model,
+      effort: row.effort,
+      cwd: row.cwd,
+      gitOrigin: row.gitOrigin,
+      rawSource: row.rawSource,
+      serviceTier: row.serviceTier,
+    };
+    context.spool.insertToken(
+      row.eventKey || row.observationId,
+      row.turnId,
+      {
+        inputTokens: row.inputTokens,
+        cachedInputTokens: row.cachedInputTokens,
+        cacheWriteInputTokens: row.cacheWriteInputTokens,
+        outputTokens: row.outputTokens,
+        reasoningTokens: row.reasoningTokens,
+        totalTokens: row.totalTokens,
+        toolCalls: row.identityKind === "exact" ? 0 : row.toolCalls,
+        componentsValid: row.componentsValid,
+      },
+      occurrence,
+      true,
+      {
+        project: row.project,
+        displayModel: row.displayModel,
+        source: row.source,
+        useType: row.useType,
+        rateCardModel: row.rateCardModel,
+        rateCardCredits: row.rateCardCredits,
+        identityKind: row.identityKind,
+        rangeAllocationEstimated: row.rangeAllocationEstimated,
+        rangeAllocationOrigin: row.rangeAllocationOrigin,
+        callCount: row.callCount,
+        detailedCallCount: row.detailedCallCount,
+        inputCallCount: row.inputCallCount,
+      },
+    );
+    if (row.identityKind === "exact") {
+      context.spool.restoreTokenPlacement(
+        row.eventKey || row.observationId,
+        occurrence,
+        {
+          rangeAllocationEstimated: row.rangeAllocationEstimated,
+          rangeAllocationOrigin: row.rangeAllocationOrigin,
+        },
+      );
+    }
+  }
+
+  function consumeTool(call) {
+    ensureCurrentCallKeys();
+    if (!call.usageOwned) return;
+    const hasUnscannedSource = [...call.sourceIds].some(
+      (sourceId) => !context.trustedScannedSourceIds.has(String(sourceId)),
+    );
+    if (!hasUnscannedSource) return;
+    context.spool.insertCall(
+      call.callKey,
+      call.turnId,
+      call.threadId,
+      call.originalLikely,
+    );
+  }
+
+  function addMetadata(ledger) {
+    for (const quota of ledger.quotaRows) {
+      const key = durableQuotaObservationKey({
+        limitKey: quota.limitKey,
+        windowMinutes: quota.windowMinutes,
+        resetsAt: quota.resetsAt,
+        usedPercent: quota.usedPercent,
+      });
+      context.quotas.set(key, quota);
+    }
+    for (const row of ledger.threadRows) {
+      context.persistedThreads.set(row.id, row);
+      if (row.parentThreadId && !context.parents.has(row.id)) {
+        context.parents.set(row.id, row.parentThreadId);
+      }
+    }
+    context.durableLedger = ledger;
+  }
+
+  return { consumeUsage, consumeTool, addMetadata };
+}
+
+function reduceScanResult(result, context, inventorySourceId = null) {
+  const sourceId = inventorySourceId ||
+    durableSourceId(context.codexHome, result.path);
+  const uncertain = result.parseErrors > 0 || result.invalidTokenRecords > 0;
+  const quotaUncertain = uncertain || result.invalidQuotaRecords > 0;
+  if (quotaUncertain) {
+    context.quotaUncertainSourceIds.add(String(sourceId));
+  }
+  // A source-local omission makes every operation from that scan unsafe: a
+  // shifted ordinal can overwrite an older observation, and partial calls can
+  // reassign ownership even when membership pruning is disabled. Retain the
+  // coverage evidence and source watermark, but let the durable ledger keep
+  // the last complete interpretation until this source scans cleanly.
+  if (uncertain) {
+    context.uncertainSourceIds.add(String(sourceId));
+    context.parseErrors += result.parseErrors;
+    context.invalidTokenRecords += result.invalidTokenRecords || 0;
+    context.invalidQuotaRecords += result.invalidQuotaRecords || 0;
+    context.correctionIntervals += result.correctionIntervals;
+    return;
+  }
+  context.trustedScannedSourceIds.add(String(sourceId));
+  let currentCandidate = null;
+  let currentCandidateSelected = false;
+  for (const operation of result.operations) {
+    if (operation.kind === "parent") {
+      context.parents.set(operation.threadId, operation.parentThreadId);
+      continue;
+    }
+    if (operation.kind === "origin") {
+      currentCandidate = operation.candidate;
+      currentCandidateSelected = context.spool.insertOrigin(currentCandidate);
+      continue;
+    }
+    if (operation.kind === "origin_update") {
+      if (currentCandidate?.turnId === operation.turnId) {
+        currentCandidate.model = operation.model;
+        currentCandidate.effort = operation.effort;
+        currentCandidate.cwd = operation.cwd;
+        if (currentCandidateSelected) {
+          context.spool.updateOrigin(currentCandidate);
+        }
+      }
+      continue;
+    }
+    if (operation.kind === "quota") {
+      for (const candidate of operation.candidates) {
+        if (!quotaUncertain) {
+          rememberQuotaLabel(context.quotaLabels, sourceId, candidate);
+        }
+        rememberQuota(context.quotas, candidate, context.sinceMs);
+        addSourceAssociation(
+          context.quotaSources,
+          candidate.observationKey,
+          sourceId,
+        );
+        addQuotaSourceBounds(
+          context.quotaSourceBounds,
+          candidate.observationKey,
+          sourceId,
+          candidate.timestamp,
+        );
+      }
+      continue;
+    }
+    if (operation.kind === "call") {
+      context.spool.insertCall(
+        operation.callKey,
+        operation.turnId,
+        operation.threadId,
+        operation.originalLikely,
+      );
+      addSourceAssociation(context.callSources, operation.callKey, sourceId);
+      continue;
+    }
+    if (operation.kind === "token") {
+      const inserted = context.spool.insertToken(
+        operation.eventKey,
+        operation.turnId,
+        operation.usage,
+        operation.occurrence,
+        operation.originalLikely,
+      );
+      if (!inserted) context.duplicateEventsSkipped += 1;
+      addSourceAssociation(context.eventSources, operation.eventKey, sourceId);
+      if (operation.eventOrdinal !== null && operation.eventOrdinal !== undefined) {
+        context.eventPositions.push({
+          sourceId,
+          ordinal: operation.eventOrdinal,
+          eventKey: operation.eventKey,
         });
       }
+      continue;
+    }
+    throw new Error(`Unknown rollout operation: ${operation.kind}`);
+  }
+  context.parseErrors += result.parseErrors;
+  context.invalidTokenRecords += result.invalidTokenRecords || 0;
+  context.invalidQuotaRecords += result.invalidQuotaRecords || 0;
+  context.correctionIntervals += result.correctionIntervals;
+}
+
+function createProgressReporter(files, onProgress) {
+  let completed = 0;
+  return async (index) => {
+    completed += 1;
+    if (
+      completed === 1 ||
+      completed === files.length ||
+      completed % 10 === 0
+    ) {
+      await onProgress({
+        current: completed,
+        total: files.length,
+        path: files[index],
+      });
+    }
+  };
+}
+
+function workerError(error, terminal) {
+  const result = new Error(error?.message || "Rollout worker failed.");
+  result.name = error?.name || "Error";
+  if (terminal) result.rolloutWorkerFailure = true;
+  if (error?.code) result.code = error.code;
+  if (error?.stack) result.stack = error.stack;
+  return result;
+}
+
+async function scanFilesSequential(
+  files,
+  stateRows,
+  continuityBytes,
+  maximumBytes,
+  sourceIdentities,
+  onProgress,
+  onResult,
+) {
+  const reportCompleted = createProgressReporter(files, onProgress);
+  for (let index = 0; index < files.length; index += 1) {
+    const result = await scanRollout(
+      files[index],
+      stateRows,
+      undefined,
+      continuityBytes[index],
+      maximumBytes[index],
+      sourceIdentities[index],
+    );
+    await onResult(result, index);
+    await reportCompleted(index);
+  }
+}
+
+export function rolloutWorkerStateEntry(path, stateRows) {
+  const threadId = String(path).match(UUID_AT_END)?.[1];
+  if (!threadId) return null;
+  const row = stateRows.get(threadId);
+  if (!row) return null;
+  // A rollout scan needs only these five enrichment fields. In particular,
+  // do not clone titles (which may contain large user-authored text) or the
+  // rest of the state database into every worker isolate.
+  return [threadId, {
+    model: row.model,
+    reasoning_effort: row.reasoning_effort,
+    cwd: row.cwd,
+    git_origin_url: row.git_origin_url,
+    source: row.source,
+  }];
+}
+
+async function scanFilesWithWorkers(
+  files,
+  stateRows,
+  continuityBytes,
+  maximumBytes,
+  sourceIdentities,
+  concurrency,
+  onProgress,
+  onResult,
+) {
+  const reportCompleted = createProgressReporter(files, onProgress);
+  const workerCount = Math.min(concurrency, files.length);
+  const maxReorderWindow = Math.max(1, concurrency * 2);
+  const workers = [];
+  try {
+    for (let index = 0; index < workerCount; index += 1) {
+      workers.push(
+        new Worker(new URL(import.meta.url), {
+          type: "module",
+          workerData: {
+            tokenLedgerImporterWorker: true,
+          },
+          execArgv: ["--no-warnings"],
+        }),
+      );
+    }
+  } catch (error) {
+    await Promise.all(workers.map((worker) => worker.terminate()));
+    throw error;
+  }
+
+  let nextIndex = 0;
+  let completedCount = 0;
+  let closed = false;
+  const assignments = new Map();
+  const pendingResults = new Map();
+  let nextResultIndex = 0;
+  let resolveDone;
+  let rejectDone;
+  const done = new Promise((resolve, reject) => {
+    resolveDone = resolve;
+    rejectDone = reject;
+  });
+
+  // Progress callbacks may be async; serialize them, dispatch further files
+  // only after each settles, and hold completion open until the queue drains,
+  // so a rejection fails the scan instead of becoming an unhandled rejection.
+  let progressChain = Promise.resolve();
+  function queueProgress(index) {
+    progressChain = progressChain
+      .then(() => reportCompleted(index))
+      .then(() => {
+        if (!closed) dispatchAvailable();
+      });
+    progressChain.catch((error) => close(error));
+  }
+
+  function close(error = null) {
+    if (closed) return;
+    closed = true;
+    Promise.all([
+      Promise.all(workers.map((worker) => worker.terminate())),
+      progressChain,
+    ]).then(
+      () => {
+        if (error) rejectDone(error);
+        else resolveDone();
+      },
+      (cleanupError) => rejectDone(error || cleanupError),
+    );
+  }
+
+  function dispatch(worker) {
+    if (closed || nextIndex >= files.length) return;
+    const index = nextIndex;
+    nextIndex += 1;
+    assignments.set(worker, { index });
+    try {
+      worker.postMessage({
+        index,
+        path: files[index],
+        continuityBytes: continuityBytes[index],
+        maximumBytes: maximumBytes[index],
+        expectedIdentity: sourceIdentities[index],
+        stateEntry: rolloutWorkerStateEntry(files[index], stateRows),
+      });
+    } catch (error) {
+      close(error);
+    }
+  }
+
+  function flushResults() {
+    while (pendingResults.has(nextResultIndex)) {
+      const result = pendingResults.get(nextResultIndex);
+      pendingResults.delete(nextResultIndex);
+      onResult(result, nextResultIndex);
+      nextResultIndex += 1;
+    }
+  }
+
+  function dispatchAvailable() {
+    while (
+      !closed &&
+      nextIndex < files.length &&
+      nextIndex - nextResultIndex < maxReorderWindow
+    ) {
+      const worker = workers.find((candidate) => !assignments.has(candidate));
+      if (!worker) return;
+      dispatch(worker);
+    }
+  }
+
+  for (const worker of workers) {
+    worker.on("message", (message) => {
+      if (closed) return;
+      const assignment = assignments.get(worker);
+      if (assignment?.index !== message.index) {
+        close(new Error("Rollout worker returned an unexpected file index."));
+        return;
+      }
+      assignments.delete(worker);
+      if (message.error) {
+        // Filesystem mutation errors stay retryable regardless of how much
+        // of the queue already completed, so pruning mid-scan re-inventories
+        // instead of aborting the refresh.
+        close(
+          workerError(
+            message.error,
+            !SOURCE_MUTATION_ERROR_CODES.includes(message.error?.code),
+          ),
+        );
+        return;
+      }
+      pendingResults.set(message.index, message.result);
+      try {
+        flushResults();
+      } catch (error) {
+        close(error);
+        return;
+      }
+      queueProgress(message.index);
+      completedCount += 1;
+      if (completedCount === files.length) close();
+    });
+    worker.on("error", (error) => close(error));
+    worker.on("exit", (code) => {
+      if (!closed) {
+        close(
+          new Error(
+            `Rollout worker exited before completing its scan (code ${code}).`,
+          ),
+        );
+      }
+    });
+  }
+  dispatchAvailable();
+  return done;
+}
+
+async function scanFiles(
+  files,
+  stateRows,
+  continuityBytes,
+  maximumBytes,
+  sourceIdentities,
+  concurrency,
+  onProgress,
+  onResult,
+) {
+  if (!files.length) return;
+  if (concurrency <= 1) {
+    return scanFilesSequential(
+      files,
+      stateRows,
+      continuityBytes,
+      maximumBytes,
+      sourceIdentities,
+      onProgress,
+      onResult,
+    );
+  }
+  return scanFilesWithWorkers(
+    files,
+    stateRows,
+    continuityBytes,
+    maximumBytes,
+    sourceIdentities,
+    concurrency,
+    onProgress,
+    onResult,
+  );
+}
+
+async function collectUsageWithConcurrency(
+  options,
+  inventory,
+  onProgress,
+  concurrency,
+  reuseUnchanged = true,
+) {
+  const state = await readState(options.codexHome);
+  const titles = await readSessionTitles(
+    resolve(options.codexHome, "session_index.jsonl"),
+  );
+  const spool = await createUsageSpool();
+  const context = createCollectionContext(state, spool, options);
+  context.sourceInventory = inventory;
+  const durableContinuity = await readDurableSourceContinuity(
+    resolveDurableLedgerPath(options),
+    {
+      codexHome: options.codexHome,
+      inventory,
+    },
+  );
+  const priorContinuity = durableContinuity.sources;
+  if (durableContinuity.threadRecords instanceof Map) {
+    for (const [threadId, row] of durableContinuity.threadRecords) {
+      context.persistedThreads.set(threadId, row);
     }
-    return buildSnapshot(context, options, titles);
+  }
+  const threadMetadataFingerprints = currentThreadMetadataFingerprints(state);
+  const metadataChanged = !sourceWatermarksEqual(
+    durableContinuity.metadataWatermark,
+    inventory.metadataWatermark,
+  );
+  const changedMetadataThreadIds = metadataChanged
+    ? metadataChangedThreadIds({
+        state,
+        titles,
+        currentFingerprints: threadMetadataFingerprints,
+        previousFingerprints: durableContinuity.threadMetadataFingerprints,
+        persistedThreads: durableContinuity.threadRecords,
+      })
+    : new Set();
+  const scanIndexes = [];
+  for (let index = 0; index < inventory.files.length; index += 1) {
+    const entry = inventory.files[index];
+    const prior = priorContinuity.get(String(entry.sourceId));
+    const threadId = entry.path.match(UUID_AT_END)?.[1] || null;
+    const metadataRequiresScan = metadataChanged && (
+      changedMetadataThreadIds === null ||
+      threadId === null ||
+      changedMetadataThreadIds.has(threadId)
+    );
+    if (
+      reuseUnchanged &&
+      sourceMatchesDurableCursor(entry, prior) &&
+      !metadataRequiresScan
+    ) {
+      entry.cursorFingerprint = prior.cursorFingerprint;
+      entry.scanBytes = prior.cursorBytes;
+      entry.continuityBytes = prior.cursorBytes;
+      entry.continuityFingerprint = prior.cursorFingerprint;
+      context.filesReused += 1;
+      context.bytesReused += entry.size;
+    } else {
+      scanIndexes.push(index);
+    }
+  }
+  const files = scanIndexes.map((index) => inventory.files[index].path);
+  const continuityBytes = scanIndexes.map((index) =>
+    priorContinuity.get(String(inventory.files[index].sourceId))?.cursorBytes ?? null
+  );
+  const maximumBytes = [];
+  for (const index of scanIndexes) {
+    const entry = inventory.files[index];
+    const scanBytes = await scanCutoffForFile(entry);
+    entry.scanBytes = scanBytes;
+    maximumBytes.push(scanBytes);
+  }
+  const sourceIdentities = scanIndexes.map((index) => ({
+    device: inventory.files[index].dev,
+    inode: inventory.files[index].ino,
+  }));
+  let publicationWatermark = inventory.watermark;
+  let stagedWatermark = null;
+
+  try {
+    await scanFiles(
+      files,
+      state.rows,
+      continuityBytes,
+      maximumBytes,
+      sourceIdentities,
+      concurrency,
+      onProgress,
+      (result, index) => {
+        const inventoryIndex = scanIndexes[index];
+        inventory.files[inventoryIndex].cursorFingerprint = result.cursorFingerprint;
+        inventory.files[inventoryIndex].continuityBytes = result.continuityBytes;
+        inventory.files[inventoryIndex].continuityFingerprint =
+          result.continuityFingerprint;
+        reduceScanResult(
+          result,
+          context,
+          inventory.files[inventoryIndex]?.sourceId,
+        );
+        context.filesScanned += 1;
+        context.bytesScanned += inventory.files[inventoryIndex].scanBytes ??
+          inventory.files[inventoryIndex].size;
+      },
+    );
+    const after = await sourceInventory(
+      options.codexHome,
+      options.includeArchived,
+    );
+    // Every rollout worker read a bounded byte range captured by `inventory`.
+    // Once all reads complete, that dataset is a valid point-in-time cutoff;
+    // source changes observed afterward belong to the next refresh and must
+    // not force a complete rescan of the already-captured files.
+    publicationWatermark = acceptedSourceWatermark(inventory, after);
+    context.spool.finishWrites();
+    // Durable reconciliation makes several sequential passes. Give each pass
+    // a fresh anchored SQLite iterator instead of retaining every spool row in
+    // the parent JavaScript heap for the lifetime of the refresh.
+    const tokenRows = {
+      [Symbol.iterator]: () => context.spool.tokenRows(),
+    };
+    const callRows = {
+      [Symbol.iterator]: () => context.spool.callRows(),
+    };
+    const durableSpool = createDurableSpoolSink(context);
+    const eventMetadata = new Map();
+    for (const token of tokenRows) {
+      eventMetadata.set(
+        String(token.eventKey),
+        eventMetadataForToken(token, context, titles),
+      );
+    }
+    const validateSources = async () => {
+      // A completed bounded scan is the staged CLI candidate's point-in-time
+      // cutoff. Source activity after those reads cannot change its contents;
+      // publish once and reconcile later activity on the next refresh.
+      if (options.stageSnapshot instanceof Function) {
+        publicationWatermark = stagedWatermark ?? publicationWatermark;
+        return;
+      }
+      const finalInventory = await sourceInventory(
+        options.codexHome,
+        options.includeArchived,
+      );
+      if (!(await sourceInventoryPreservesCutoff(
+        inventory,
+        finalInventory,
+      ))) {
+        const error = new Error(
+          "Local Codex sources changed during collection; the candidate snapshot was not published.",
+        );
+        error.code = "ERR_SOURCE_CHANGED_DURING_COLLECTION";
+        throw error;
+      }
+      const acceptedWatermark = acceptedSourceWatermark(
+        inventory,
+        finalInventory,
+      );
+      // Rollout integrity is checked against the captured cutoff above. Once a
+      // snapshot is staged, retain that accepted watermark: Codex may keep
+      // appending advisory SQLite/session metadata while the ledger commits,
+      // and that activity must not discard an otherwise valid snapshot.
+      publicationWatermark = stagedWatermark ?? acceptedWatermark;
+    };
+    let stagedSnapshot = null;
+    const stageCandidate = async ({ ledger }) => {
+      if (!(options.stageSnapshot instanceof Function)) return null;
+      durableSpool.addMetadata(ledger);
+      const candidate = {
+        ...buildSnapshot(context, options, titles),
+        sourceWatermark: publicationWatermark,
+      };
+      stagedWatermark = publicationWatermark;
+      stagedSnapshot = await options.stageSnapshot(candidate);
+      return stagedSnapshot;
+    };
+    const ledger = await updateDurableLedger({
+      options,
+      codexHome: options.codexHome,
+      inventory,
+      includeArchived: options.includeArchived,
+      tokenRows,
+      callRows,
+      quotas: [...context.quotas.values()],
+      eventSources: context.eventSources,
+      eventPositions: context.eventPositions,
+      callSources: context.callSources,
+      quotaSources: context.quotaSources,
+      quotaSourceBounds: context.quotaSourceBounds,
+      quotaLabelEvidence: [...context.quotaLabels.values()].map((evidence) => ({
+        sourceId: evidence.sourceId,
+        limitKey: evidence.limitKey,
+        limitName: evidence.limitName,
+        observedAt: evidence.observedAt,
+      })),
+      uncertainSourceIds: context.uncertainSourceIds,
+      quotaUncertainSourceIds: context.quotaUncertainSourceIds,
+      eventMetadata,
+      threadRecords: threadRecordsForLedger(context, titles),
+      threadMetadataFingerprints,
+      nowMs: Date.now(),
+      faultInjector: options.faultInjector,
+      validateBeforeCommit: validateSources,
+      validateAfterCommit: validateSources,
+      stageBeforeCommit: stageCandidate,
+      onMaterializedRow: ({ kind, row }) => {
+        if (kind === "usage") durableSpool.consumeUsage(row);
+        else if (kind === "tool") durableSpool.consumeTool(row);
+      },
+    });
+    if (stagedSnapshot) return stagedSnapshot.snapshot;
+    durableSpool.addMetadata(ledger);
+    return {
+      ...buildSnapshot(context, options, titles),
+      sourceWatermark: publicationWatermark,
+    };
   } finally {
     spool.close();
     await rm(spool.directory, { recursive: true, force: true });
   }
 }
 
+async function collectUsageAttempt(options, inventory, onProgress) {
+  return collectUsageWithConcurrency(
+    options,
+    inventory,
+    onProgress,
+    SCAN_CONCURRENCY,
+  );
+}
+
+function isSourceMutationError(error) {
+  return (
+    !error?.rolloutWorkerFailure &&
+    (
+      SOURCE_MUTATION_ERROR_CODES.includes(error?.code) ||
+      error?.code === "ERR_SOURCE_CHANGED_DURING_COLLECTION"
+    )
+  );
+}
+
+export async function collectUsage(options, onProgress = () => {}) {
+  for (let attempt = 1; attempt <= SOURCE_COLLECTION_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const before = await sourceInventory(
+        options.codexHome,
+        options.includeArchived,
+      );
+      const snapshot = await collectUsageAttempt(options, before, onProgress);
+      return snapshot;
+    } catch (error) {
+      if (!isSourceMutationError(error)) {
+        throw error;
+      }
+      if (attempt === SOURCE_COLLECTION_MAX_ATTEMPTS) {
+        const exhausted = new Error(
+          `Local Codex sources changed during collection after ${SOURCE_COLLECTION_MAX_ATTEMPTS} attempts; no snapshot was published.`,
+          { cause: error },
+        );
+        exhausted.code = "ERR_SOURCE_CHANGED_DURING_COLLECTION";
+        throw exhausted;
+      }
+    }
+  }
+
+  const error = new Error(
+    `Local Codex sources changed during collection after ${SOURCE_COLLECTION_MAX_ATTEMPTS} attempts; no snapshot was published.`,
+  );
+  error.code = "ERR_SOURCE_CHANGED_DURING_COLLECTION";
+  throw error;
+}
+
+export async function collectUsageSequential(options, onProgress = () => {}) {
+  for (let attempt = 1; attempt <= SOURCE_COLLECTION_MAX_ATTEMPTS; attempt += 1) {
+    const inventory = await sourceInventory(
+      options.codexHome,
+      options.includeArchived,
+    );
+    try {
+      const snapshot = await collectUsageWithConcurrency(
+        options,
+        inventory,
+        onProgress,
+        1,
+        false,
+      );
+      return snapshot;
+    } catch (error) {
+      if (!isSourceMutationError(error)) throw error;
+      if (attempt === SOURCE_COLLECTION_MAX_ATTEMPTS) {
+        const exhausted = new Error(
+          `Local Codex sources changed during collection after ${SOURCE_COLLECTION_MAX_ATTEMPTS} attempts; no snapshot was published.`,
+          { cause: error },
+        );
+        exhausted.code = "ERR_SOURCE_CHANGED_DURING_COLLECTION";
+        throw exhausted;
+      }
+    }
+  }
+  throw new Error("Unreachable sequential collection state.");
+}
+
 async function main() {
   let options;
   try {
     options = parseArgs(process.argv.slice(2));
   } catch (error) {
-    process.stderr.write(`${error.message}\n\n${usage()}\n`);
+    process.stderr.write(`${safeExportLabel(error.message, 2_000, "Invalid collector arguments")}\n\n${usage()}\n`);
     process.exitCode = 1;
     return;
   }
@@ -1373,14 +4166,23 @@ async function main() {
   }
 
   process.stdout.write("Token Ledger: scanning local Codex metadata…\n");
-  const snapshot = await collectUsage(options, ({ current, total }) => {
+  let writeResult = null;
+  const snapshot = await collectUsage({
+    ...options,
+    stageSnapshot: async (candidate) => {
+      process.stdout.write("\nToken Ledger: writing privacy-reduced snapshot…\n");
+      writeResult = await stagePrivateSnapshot(options.output, candidate, {
+        reservedPaths: durableLedgerRelatedPaths(options),
+      });
+      return writeResult;
+    },
+  }, ({ current, total }) => {
     process.stdout.write(
       `\rToken Ledger: scanned ${current.toLocaleString()}/${total.toLocaleString()} rollout files`,
     );
   });
-  process.stdout.write("\nToken Ledger: writing privacy-reduced snapshot…\n");
-  const writeResult = await writePrivateSnapshot(options.output, snapshot);
-  const storedSnapshot = writeResult.snapshot;
+  process.stdout.write("\n");
+  const storedSnapshot = snapshot;
   process.stdout.write(
     [
       `Snapshot: ${options.output}`,
@@ -1388,6 +4190,8 @@ async function main() {
       `Unique model calls: ${storedSnapshot.coverage.observedModelCalls.toLocaleString()}`,
       `Stored usage buckets: ${storedSnapshot.events.length.toLocaleString()}`,
       `Duplicate/copied events skipped: ${storedSnapshot.coverage.duplicateEventsSkipped.toLocaleString()}`,
+      `Invalid token records excluded: ${storedSnapshot.coverage.invalidTokenRecords.toLocaleString()}`,
+      `Invalid quota records excluded: ${storedSnapshot.coverage.invalidQuotaRecords.toLocaleString()}`,
       `Threads with unresolved state-only counters: ${storedSnapshot.coverage.unresolvedThreadCounters.toLocaleString()}`,
       `Snapshot size: ${(writeResult.bytesWritten / 1_000_000).toFixed(1)} MB (${writeResult.encoding}; ${(writeResult.jsonBytes / 1_000_000).toFixed(1)} MB JSON before encoding)`,
       `Snapshot safety limit: ${(writeResult.maxBytes / 1_000_000).toFixed(1)} MB`,
@@ -1395,12 +4199,49 @@ async function main() {
   );
 }
 
+if (!isMainThread && workerData?.tokenLedgerImporterWorker && parentPort) {
+  parentPort.on("message", async ({
+    index,
+    path,
+    continuityBytes,
+    maximumBytes,
+    expectedIdentity,
+    stateEntry,
+  }) => {
+    try {
+      const result = await scanRollout(
+        path,
+        stateEntry ? new Map([stateEntry]) : new Map(),
+        undefined,
+        continuityBytes,
+        maximumBytes,
+        expectedIdentity,
+      );
+      parentPort.postMessage({ index, result });
+    } catch (error) {
+      parentPort.postMessage({
+        index,
+        error: {
+          name: error?.name,
+          message: error?.message || String(error),
+          stack: error?.stack,
+          code: error?.code,
+        },
+      });
+    }
+  });
+}
+
 const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
-if (import.meta.url === invokedPath) {
+if (isMainThread && import.meta.url === invokedPath) {
   main().catch((error) => {
     process.stderr.write(
       `Token Ledger collector failed: ${
-        error instanceof Error ? error.message : String(error)
+        safeExportLabel(
+          error instanceof Error ? error.message : String(error),
+          2_000,
+          "Unknown collector error",
+        )
       }\n`,
     );
     process.exitCode = 1;