claude-usage-limits 1.11.7 → 1.13.0

package/skills/usage-limits/scripts/usage.js

@@ -24,6 +24,7 @@ const readline = require('readline');
 const host = require('./host.js');
 const codex = require('./codex.js');
 const live = require('./live.js');
+const reading = require('./reading.js');
 
 // Which agent's meter to read. Resolved once from the command line or the
 // environment, because a process that changed its mind halfway through would
@@ -439,6 +440,10 @@ function eventFrom(line, seen, project) {
   const parts = tokenParts(entry.message.usage);
   return {
     at,
+    // Carried on the event so the scan cache can dedup across files without
+    // re-parsing them: a resumed or forked session repeats earlier turns, and
+    // a cached file is never read again to find that out.
+    dedupId: id === '|' ? null : id,
     model: entry.message.model || '',
     effort: entry.effort || null,
     cost: costOf(entry.message.usage, entry.message.model),
@@ -479,9 +484,9 @@ function promptFrom(line) {
   return typed;
 }
 
-async function readEvents(since) {
-  if (isCodex()) return codex.readEvents(since);
-  return readClaudeEvents(since);
+async function readEvents(since, options) {
+  if (isCodex()) return codex.readEvents(since, options);
+  return readClaudeEvents(since, options);
 }
 
 // A file last touched before the window opened holds nothing useful.
@@ -529,7 +534,7 @@ function subagentTranscripts(dir, since, depth) {
   return files;
 }
 
-async function readClaudeEvents(since) {
+function claudeTranscriptFiles(since) {
   const root = path.join(configDir(), 'projects');
   let dirs = [];
   try {
@@ -564,26 +569,459 @@ async function readClaudeEvents(since) {
       files.push({ file, project: dir.name });
     }
   }
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// The effort level in force right now
+// ---------------------------------------------------------------------------
+//
+// Claude Code stamps `effort` on every assistant line it writes, which makes
+// the transcript the only source that is always current. It follows /effort
+// the moment the model answers; it exists for a session that has no status
+// line at all, which is every VS Code window; and it can say "max", which
+// settings.json is not allowed to hold at all.
+//
+// Reading it off settings.json instead is what made the panel insist on
+// "xhigh" through a whole session running at max, and made a session with no
+// status line show the setting rather than the session.
+//
+// Only the tail is read, and only whole lines from it are parsed, so a
+// megabyte is enough however long the transcript grows.
+const EFFORT_TAIL_BYTES = 1024 * 1024;
+const EFFORT_TAIL_LINES = 60;
+
+function sessionTranscriptFile(sessionId) {
+  if (!sessionId) return null;
+  const root = path.join(configDir(), 'projects');
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(root, { withFileTypes: true });
+  } catch (err) {
+    return null;
+  }
+  let best = null;
+  for (const dir of dirs) {
+    if (!dir.isDirectory()) continue;
+    const file = path.join(root, dir.name, sessionId + '.jsonl');
+    let stat;
+    try {
+      stat = fs.statSync(file);
+    } catch (err) {
+      continue;
+    }
+    // A session id is unique, but a resumed session can leave a copy under an
+    // older project directory; the one being written to is the live one.
+    if (!best || stat.mtimeMs > best.at) best = { file, at: stat.mtimeMs, size: stat.size };
+  }
+  return best;
+}
+
+// The newest effort this session ran at, with the time it was stamped, so a
+// caller holding a status-line reading can take whichever is newer.
+function liveEffort(sessionId) {
+  const found = sessionTranscriptFile(sessionId);
+  if (!found) return null;
+  const from = Math.max(0, found.size - EFFORT_TAIL_BYTES);
+  const text = readSlice(found.file, from, found.size).toString('utf8');
+  const lines = text.split('\n');
+  // The first line of a mid-file slice is a fragment, and the last is whatever
+  // was half-written when the read happened. Neither is parsed.
+  const start = Math.max(from > 0 ? 1 : 0, lines.length - EFFORT_TAIL_LINES);
+  for (let i = lines.length - 1; i >= start; i -= 1) {
+    const line = lines[i];
+    if (!line || line.indexOf('"effort"') === -1) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (err) {
+      // A fragment, or the half-written tail.
+      continue;
+    }
+    if (!entry || typeof entry.effort !== 'string' || !entry.effort) continue;
+    const at = Date.parse(entry.timestamp);
+    return { effort: entry.effort, at: Number.isFinite(at) ? at : found.at };
+  }
+  return null;
+}
+
+// The model a session is running, from the tail of its own transcript. Every
+// assistant line carries message.model, so this is the session's word rather
+// than a setting's or another window's. The VS Code panel has no status line
+// of its own to ask, and until this existed it borrowed the newest status-line
+// slot on the machine - which on 2026-09-08 was a 19-hour-old Opus session,
+// shown over a Fable one.
+function liveModel(sessionId) {
+  const found = sessionTranscriptFile(sessionId);
+  if (!found) return null;
+  const from = Math.max(0, found.size - EFFORT_TAIL_BYTES);
+  const text = readSlice(found.file, from, found.size).toString('utf8');
+  const lines = text.split('\n');
+  const start = Math.max(from > 0 ? 1 : 0, lines.length - EFFORT_TAIL_LINES);
+  for (let i = lines.length - 1; i >= start; i -= 1) {
+    const line = lines[i];
+    if (!line || line.indexOf('"assistant"') === -1 || line.indexOf('"model"') === -1) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (err) {
+      continue;
+    }
+    const model = entry && entry.message && typeof entry.message.model === 'string' ? entry.message.model : null;
+    if (!model || model === '<synthetic>') continue;
+    const at = Date.parse(entry.timestamp);
+    return { model, at: Number.isFinite(at) ? at : found.at };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// The scan cache
+// ---------------------------------------------------------------------------
+//
+// Reading every transcript from the start, every time, is what the scan used to
+// do, and it stopped being affordable the moment workflows arrived. One machine
+// here had 950 subagent transcripts totalling 114 MB inside the eight-day
+// window, and a full scan took 200 seconds. The prompt hook is given ten, so it
+// was killed on every prompt and the reported percentage froze at whatever a
+// cached view last said: 3% while the account was at 32%.
+//
+// Transcripts are append-only, and almost all of them are finished. So each
+// file's parsed events are kept, keyed by its size and mtime, and a file that
+// has grown is read only from where the last read stopped. The offset is
+// counted in bytes, at the last complete line, so a half-written tail is simply
+// read again next time.
+const SCAN_VERSION = 1;
+// A day wider than the widest window anything asks for, so a report never wants
+// an event the cache has just pruned.
+const SCAN_KEEP_MS = 9 * DAY;
+// Enough for weeks of heavy use; the oldest go first if it is ever reached.
+const SCAN_MAX_EVENTS = 250000;
+
+function scanFile() {
+  return path.join(configDir(), 'usage-limits-scan.json');
+}
+
+function readScanCache() {
+  const parsed = readJson(scanFile());
+  if (!parsed || parsed.version !== SCAN_VERSION || !parsed.files || typeof parsed.files !== 'object') {
+    return { version: SCAN_VERSION, files: {} };
+  }
+  return { version: SCAN_VERSION, files: parsed.files };
+}
+
+// Every state file the plugin shares between processes goes through here.
+//
+// Two windows run the same hooks at the same moment, and the status line runs
+// every few hundred milliseconds. A plain writeFileSync is a truncate followed
+// by a write, and a reader that lands between the two sees an empty or
+// half-written file, parses nothing, and - for anything read, changed and
+// written back, like the tally - then writes its own slot over everyone
+// else's. Writing beside the file and renaming into place means every read
+// sees either the old whole or the new whole. A rename Windows refuses leaves
+// nothing behind, and the caller carries on with what is on disk.
+function writeJsonAtomic(file, value) {
+  const temp = file + '.' + process.pid + '.usage-limits-tmp';
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(temp, JSON.stringify(value), 'utf8');
+    fs.renameSync(temp, file);
+    return true;
+  } catch (err) {
+    try {
+      fs.unlinkSync(temp);
+    } catch (gone) {
+      // Nothing to clean up.
+    }
+    return false;
+  }
+}
+
+// Losing the scan cache costs one slow scan, never a wrong number.
+function writeScanCache(cache) {
+  return writeJsonAtomic(scanFile(), cache);
+}
+
+// A byte range of a file, without pulling the whole thing into memory.
+function readSlice(file, start, end) {
+  const length = Math.max(0, end - start);
+  if (!length) return Buffer.alloc(0);
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch (err) {
+    return Buffer.alloc(0);
+  }
+  try {
+    const buffer = Buffer.allocUnsafe(length);
+    let read = 0;
+    while (read < length) {
+      const got = fs.readSync(fd, buffer, read, length - read, start + read);
+      if (got <= 0) break;
+      read += got;
+    }
+    return read === length ? buffer : buffer.subarray(0, read);
+  } catch (err) {
+    return Buffer.alloc(0);
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch (err) {
+      // Already closed.
+    }
+  }
+}
+
+// Events are kept as tuples rather than objects, because in a file of ten
+// thousand of them the key names alone were two thirds of the bytes. The
+// project is a property of the file, so it is stored once on the entry and put
+// back on the way out.
+const ROW_TURN = 0;
+const ROW_REFUSAL = 1;
+
+function whole(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function packEvent(event) {
+  if (event.rejected) {
+    const rejected = event.rejected;
+    return [
+      ROW_REFUSAL,
+      event.at,
+      event.sessionId || '',
+      rejected.status || '',
+      rejected.key || '',
+      Number.isFinite(rejected.resetsAt) ? rejected.resetsAt : 0,
+    ];
+  }
+  const parts = event.parts || {};
+  return [
+    ROW_TURN,
+    event.at,
+    whole(event.cost),
+    whole(event.tokens),
+    whole(parts.input),
+    whole(parts.cacheWrite),
+    whole(parts.cacheRead),
+    whole(parts.output),
+    whole(parts.reasoning),
+    event.sidechain ? 1 : 0,
+    event.model || '',
+    event.sessionId || '',
+    event.effort || '',
+    event.dedupId || '',
+  ];
+}
+
+function unpackEvent(row, project) {
+  if (!Array.isArray(row)) return null;
+  if (row[0] === ROW_REFUSAL) {
+    return {
+      at: row[1],
+      model: '',
+      effort: null,
+      cost: 0,
+      tokens: 0,
+      parts: { input: 0, cacheWrite: 0, cacheRead: 0, output: 0, reasoning: 0 },
+      project: project || null,
+      sessionId: row[2] || null,
+      rejected: {
+        status: row[3] || null,
+        key: row[4] || null,
+        resetsAt: row[5] || null,
+      },
+    };
+  }
+  const parts = {
+    input: row[4],
+    cacheWrite: row[5],
+    cacheRead: row[6],
+    output: row[7],
+    reasoning: row[8],
+  };
+  return {
+    at: row[1],
+    dedupId: row[13] || null,
+    model: row[10] || '',
+    effort: row[12] || null,
+    cost: row[2],
+    tokens: row[3],
+    parts,
+    context: parts.input + parts.cacheRead + parts.cacheWrite,
+    project: project || null,
+    sessionId: row[11] || null,
+    sidechain: row[9] === 1,
+  };
+}
+
+// Split on newlines in the buffer itself rather than after decoding, because
+// the offset has to be a byte count: a transcript is full of characters that
+// are more than one byte, and counting them as one would drift the offset and
+// silently drop turns. A trailing partial line is left unconsumed.
+function parseSlice(buffer, project, baseOffset) {
+  const events = [];
+  let start = 0;
+  let consumed = 0;
+  for (let i = 0; i < buffer.length; i += 1) {
+    if (buffer[i] !== 0x0a) continue;
+    const event = eventFrom(buffer.toString('utf8', start, i), null, project);
+    if (event) events.push(event);
+    start = i + 1;
+    consumed = start;
+  }
+  return { events, offset: baseOffset + consumed };
+}
+
+// One file's events, reusing whatever the cache already holds of it.
+function eventsForFile(entry, cache, keepFrom) {
+  let stat;
+  try {
+    stat = fs.statSync(entry.file);
+  } catch (err) {
+    delete cache.files[entry.file];
+    return null;
+  }
+
+  const cached = cache.files[entry.file];
+  const usable =
+    cached &&
+    Array.isArray(cached.rows) &&
+    Number.isFinite(cached.offset) &&
+    Number.isFinite(cached.size) &&
+    // Appended to, or untouched. Anything else - a rewrite, a truncation, a
+    // clock that went backwards - is read again from the beginning, because
+    // the offset can no longer be trusted to point where it says.
+    stat.size >= cached.size &&
+    cached.offset <= stat.size;
+
+  if (usable && stat.size === cached.size && stat.mtimeMs === cached.mtimeMs) {
+    return { rows: cached.rows, project: cached.project || entry.project, changed: false };
+  }
+
+  const from = usable ? cached.offset : 0;
+  const parsed = parseSlice(readSlice(entry.file, from, stat.size), entry.project, from);
+  const rows = (usable ? cached.rows : [])
+    .concat(parsed.events.map(packEvent))
+    .filter((row) => row[1] >= keepFrom);
+  cache.files[entry.file] = {
+    mtimeMs: stat.mtimeMs,
+    size: stat.size,
+    offset: parsed.offset,
+    project: entry.project,
+    rows,
+  };
+  return { rows, project: entry.project, changed: true };
+}
+
+async function readClaudeEvents(since, options) {
+  const opts = options || {};
+  const startedAt = Date.now();
+  // Zero is a real budget - spent before the first file - not "no budget";
+  // absent or negative means unlimited. A test relies on zero being exact,
+  // which Date.now() cannot promise: a scan of a few small files fits inside
+  // one millisecond tick, so "elapsed > 0" stayed false all the way through
+  // and the scan reported a complete total it had no right to. The budget is
+  // measured on the monotonic sub-millisecond clock, and spent means reached.
+  const clock = performance.now();
+  const budgetMs = Number.isFinite(opts.budgetMs) && opts.budgetMs >= 0 ? opts.budgetMs : null;
+  const keepFrom = Math.min(since, startedAt - SCAN_KEEP_MS);
+
+  const files = claudeTranscriptFiles(since);
+  // Newest first, so a scan that runs out of time has done the files that
+  // describe the window running now rather than the ones from last Tuesday.
+  const ordered = files
+    .map((entry) => {
+      let at = 0;
+      try {
+        at = fs.statSync(entry.file).mtimeMs;
+      } catch (err) {
+        at = 0;
+      }
+      return Object.assign({ at }, entry);
+    })
+    .sort((a, b) => b.at - a.at);
+
+  const cache = opts.cache === false ? { version: SCAN_VERSION, files: {} } : readScanCache();
+  const collected = [];
+  const alive = new Set();
+  let changed = false;
+  let partial = false;
+
+  for (const entry of ordered) {
+    if (budgetMs !== null && performance.now() - clock >= budgetMs) {
+      partial = true;
+      break;
+    }
+    alive.add(entry.file);
+    const result = eventsForFile(entry, cache, keepFrom);
+    if (!result) {
+      changed = true;
+      continue;
+    }
+    if (result.changed) changed = true;
+    collected.push(result);
+  }
+
+  // Files that have gone cold or been deleted, and anything left over the cap.
+  if (opts.cache !== false) {
+    let total = 0;
+    for (const file of Object.keys(cache.files)) {
+      const held = cache.files[file];
+      if (!held || !Array.isArray(held.rows)) {
+        delete cache.files[file];
+        changed = true;
+        continue;
+      }
+      // Past the window is gone whatever happened. An entry the scan merely
+      // did not reach is dropped only when the scan was complete: a partial
+      // one has not seen every file and must not be what decides they are dead.
+      const tooOld = !(Number.isFinite(held.mtimeMs) && held.mtimeMs >= keepFrom);
+      if (tooOld || (!partial && !alive.has(file))) {
+        delete cache.files[file];
+        changed = true;
+        continue;
+      }
+      total += held.rows.length;
+    }
+    if (total > SCAN_MAX_EVENTS) {
+      const oldest = Object.keys(cache.files).sort(
+        (a, b) => (cache.files[a].mtimeMs || 0) - (cache.files[b].mtimeMs || 0)
+      );
+      for (const file of oldest) {
+        if (total <= SCAN_MAX_EVENTS) break;
+        total -= cache.files[file].rows.length;
+        delete cache.files[file];
+        changed = true;
+      }
+    }
+    // Through a temporary file named for this process, so two windows running
+    // the hook at the same moment cannot interleave a half-written cache.
+    if (changed) writeScanCache(cache);
+  }
 
   const seen = new Set();
   const events = [];
-  for (const entry of files) {
-    const stream = fs.createReadStream(entry.file, { encoding: 'utf8' });
-    const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    try {
-      for await (const line of lines) {
-        const event = eventFrom(line, seen, entry.project);
-        if (event && event.at >= since) events.push(event);
+  for (const held of collected) {
+    for (const row of held.rows) {
+      if (row[1] < since) continue;
+      const id = row[0] === ROW_TURN ? row[13] : '';
+      if (id) {
+        if (seen.has(id)) continue;
+        seen.add(id);
       }
-    } catch (err) {
-      // A half-written line at the tail of a live session is expected.
-    } finally {
-      lines.close();
-      stream.destroy();
+      const event = unpackEvent(row, held.project);
+      if (event) events.push(event);
     }
   }
 
   events.sort((a, b) => a.at - b.at);
+  if (partial) {
+    // Non-enumerable, so nothing that iterates or serialises the events can
+    // trip over it; the report reads it to say the correction may be short.
+    Object.defineProperty(events, 'partial', { value: true, enumerable: false });
+  }
   return events;
 }
 
@@ -656,6 +1094,12 @@ const MIN_PACE_SAMPLE = 5;
 // ordinary turn, and treating that as "the" turn cost sends the headroom
 // estimate swinging: a single $7 turn once put a 13% full window at nine turns
 // left. Too few recent turns to be sure, so widen to the whole window.
+// A turn that fanned out ten agents is real, and so is the budget it spent, but
+// it should not price every remaining turn as though it will do the same. Five
+// is generous enough to catch a habitually agent-heavy session and mean enough
+// that one workflow does not flatten the estimate to nothing.
+const SUBAGENT_FACTOR_MAX = 5;
+
 function typicalTurnCost(recentEvents, windowEvents, allEvents, minSample) {
   const floor = Number.isFinite(minSample) ? minSample : MIN_PACE_SAMPLE;
 
@@ -663,14 +1107,20 @@ function typicalTurnCost(recentEvents, windowEvents, allEvents, minSample) {
   // is being measured against, so a thin window borrows from a wider sample
   // rather than inventing a figure from two turns. Subagent calls are left
   // out: they are small and many, and would make a turn look cheap.
-  const tiers = [mainThread(recentEvents), mainThread(windowEvents), mainThread(allEvents)];
+  const sources = [recentEvents, windowEvents, allEvents];
+  const tiers = sources.map((tier) => mainThread(tier));
   let pool = [];
-  for (const tier of tiers) {
-    if (tier && tier.length >= floor) {
-      pool = tier;
+  let source = null;
+  for (let i = 0; i < tiers.length; i++) {
+    if (tiers[i] && tiers[i].length >= floor) {
+      pool = tiers[i];
+      source = sources[i];
       break;
     }
-    if (tier && tier.length > pool.length) pool = tier;
+    if (tiers[i] && tiers[i].length > pool.length) {
+      pool = tiers[i];
+      source = sources[i];
+    }
   }
   const costs = pool
     .map((event) => event.cost)
@@ -692,7 +1142,34 @@ function typicalTurnCost(recentEvents, windowEvents, allEvents, minSample) {
   const cut = costs.length >= MIN_PACE_SAMPLE ? Math.max(1, Math.round(costs.length * 0.1)) : 0;
   const kept = cut > 0 ? costs.slice(cut, costs.length - cut) : costs;
   const middle = kept.length ? kept : costs;
-  return middle.reduce((sum, cost) => sum + cost, 0) / middle.length;
+  const perMainThreadTurn = middle.reduce((sum, cost) => sum + cost, 0) / middle.length;
+
+  // And then the part that was missing, which is why a fan-out session was
+  // promised four hundred turns and got sixty.
+  //
+  // Subagent calls are excluded from the sample above for a good reason: they
+  // are small and many, and counting each as a turn makes a turn look cheap.
+  // But their spend does not disappear - it comes out of the same window. A
+  // turn that dispatches three research agents costs what the agents cost, and
+  // measuring only its main-thread half prices it as though they were free.
+  //
+  // Rather than attributing each call to a parent turn, which the transcripts
+  // do not reliably say, scale by how much of this pool's spend the main
+  // thread actually accounts for. If subagents were two thirds of it, a turn
+  // costs three times its visible half. Clamped, because a single enormous
+  // fan-out should not price every future turn as another one.
+  const total = sumCost(source);
+  const visible = sumCost(pool);
+  const factor = visible > 0 && total > visible ? Math.min(SUBAGENT_FACTOR_MAX, total / visible) : 1;
+  return perMainThreadTurn * factor;
+}
+
+function sumCost(events) {
+  let total = 0;
+  for (const event of events || []) {
+    if (event && Number.isFinite(event.cost) && event.cost > 0) total += event.cost;
+  }
+  return total;
 }
 
 function dominantEffort(events) {
@@ -708,6 +1185,142 @@ function dominantEffort(events) {
   return best ? best[0] : null;
 }
 
+// What a turn has actually cost at each effort level, measured separately.
+//
+// The blended cost per turn is the right answer to "what has this been
+// costing" and the wrong one the moment the effort changes. An account that
+// usually runs at medium and switches to ultra is priced at the medium rate
+// until enough ultra turns have landed to drag the average up - and on a plan
+// with a small window there is no "enough", because the window is gone first.
+//
+// That is not hypothetical either. A ChatGPT Plus account running gpt-6-astra
+// at ultra effort emptied a whole five-hour window on one ordinary task, with
+// this plugin reporting room the entire way, because every turn it had on
+// record was a cheaper one.
+//
+// Subagent calls are left out for the same reason turns leave them out: they
+// are errands, not turns, and averaging them in makes a turn look cheap.
+function effortRates(events) {
+  const rows = new Map();
+  for (const event of events || []) {
+    if (!event || event.rejected || event.sidechain) continue;
+    if (!event.effort) continue;
+    if (!rows.has(event.effort)) {
+      rows.set(event.effort, { effort: event.effort, turns: 0, cost: 0, tokens: 0, output: 0, reasoning: 0 });
+    }
+    const row = rows.get(event.effort);
+    const parts = event.parts || {};
+    row.turns += 1;
+    row.cost += Number.isFinite(event.cost) ? event.cost : 0;
+    row.tokens += Number.isFinite(event.tokens) ? event.tokens : 0;
+    row.output += Number.isFinite(parts.output) ? parts.output : 0;
+    row.reasoning += Number.isFinite(parts.reasoning) ? parts.reasoning : 0;
+  }
+  return [...rows.values()]
+    .map((row) =>
+      Object.assign(row, {
+        perTurn: row.turns ? row.cost / row.turns : null,
+        // What the effort setting actually moves. Cost per turn is dominated by
+        // how big the context happened to be, which is why measuring it that
+        // way can report "low" as dearer than "ultra": a small ultra turn on a
+        // short context really did cost less than a huge low-effort one. The
+        // output is the part the setting controls, and it is the dear part -
+        // eight times the weight of fresh input on Codex's own meter.
+        outputPerTurn: row.turns ? row.output / row.turns : null,
+        reasoningPerTurn: row.turns ? row.reasoning / row.turns : null,
+      })
+    )
+    .sort((a, b) => (a.outputPerTurn || 0) - (b.outputPerTurn || 0));
+}
+
+// Enough turns at one effort to believe the figure at all.
+const MIN_EFFORT_SAMPLE = 3;
+// Dearer than the cheapest measured effort by this much before it is worth
+// saying anything. Below it the setting is not what is spending the budget.
+const EFFORT_DEARER_BY = 1.5;
+// At or under this many turns left at the CURRENT effort, say so whether or
+// not a cheaper effort has ever been measured.
+const FEW_TURNS_AT_EFFORT = 12;
+
+// The other agent's meter, for the surfaces that draw both.
+//
+// view.js is required at call time rather than at the top of the file: it
+// requires this module back, and a cycle resolved at load time would hand it a
+// half-built exports object. By the time a report is being built both are
+// finished loading.
+function codexBlock(now) {
+  if (isCodex()) return null;
+  try {
+    if (!host.codexHasSessions()) return null;
+    const display = require('./view.js');
+    const other = codex.collect(now);
+    const block = display.buildCodex({
+      now,
+      utilization: other.utilization,
+      fetchedAtMs: other.snapshotFetchedAt,
+      windowSpecs: other.windowSpecs,
+      plan: other.plan,
+      windowless: other.windowless,
+      unreadable: other.unreadable,
+    });
+    return block.present ? block : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+// The warning that would have caught that incident: what the window holds at
+// the effort actually set, rather than at the average of everything ever run.
+function effortWarning(events, current, window) {
+  if (!current || !window || window.stale) return null;
+  const rates = effortRates(events);
+  const here = rates.find((row) => row.effort === current);
+  if (!here || here.turns < MIN_EFFORT_SAMPLE || !here.perTurn || here.perTurn <= 0) return null;
+
+  // Compared on output per turn, because that is what the effort setting
+  // moves; cost per turn is mostly a fact about how long the context was.
+  const measure = (row) => (Number.isFinite(row.outputPerTurn) && row.outputPerTurn > 0 ? row.outputPerTurn : null);
+  const mine = measure(here);
+  const cheaper = mine
+    ? rates.find(
+        (row) =>
+          row.effort !== current &&
+          row.turns >= MIN_EFFORT_SAMPLE &&
+          measure(row) &&
+          mine / measure(row) >= EFFORT_DEARER_BY
+      )
+    : null;
+
+  const turnsLeft =
+    Number.isFinite(window.usdPerPercent) && window.usdPerPercent > 0 && Number.isFinite(window.percentLeft)
+      ? Math.max(0, Math.floor((window.percentLeft * window.usdPerPercent) / here.perTurn))
+      : null;
+
+  // Nothing to say when the effort is not the dear one and the window is not
+  // nearly out at it.
+  if (!cheaper && (turnsLeft === null || turnsLeft > FEW_TURNS_AT_EFFORT)) return null;
+
+  return {
+    effort: current,
+    perTurn: here.perTurn,
+    sample: here.turns,
+    turnsLeft,
+    blendedTurnsLeft: Number.isFinite(window.turnsLeft) ? window.turnsLeft : null,
+    outputPerTurn: here.outputPerTurn,
+    cheaper: cheaper
+      ? {
+          effort: cheaper.effort,
+          perTurn: cheaper.perTurn,
+          outputPerTurn: cheaper.outputPerTurn,
+          // How many times more the current setting writes per turn. This is
+          // the number worth saying out loud: "ultra writes 6x the output of
+          // medium" is what makes someone change it.
+          multiple: measure(cheaper) ? mine / measure(cheaper) : null,
+        }
+      : null,
+  };
+}
+
 // What the thinking actually cost, rather than what it is generally said to
 // cost. Reasoning is billed as output, so it is priced at the output rate of
 // whichever models did the thinking, weighted by how much each of them did.
@@ -1028,8 +1641,7 @@ function readCalibration() {
 
 function writeCalibration(all) {
   try {
-    fs.mkdirSync(path.dirname(calibrationFile()), { recursive: true });
-    fs.writeFileSync(calibrationFile(), JSON.stringify(all), 'utf8');
+    writeJsonAtomic(calibrationFile(), all);
   } catch (err) {
     // Losing it costs accuracy on the next thin baseline, nothing more.
   }
@@ -1063,8 +1675,7 @@ function readModelRecord() {
 
 function writeModelRecord(all) {
   try {
-    fs.mkdirSync(path.dirname(modelRecordFile()), { recursive: true });
-    fs.writeFileSync(modelRecordFile(), JSON.stringify(all), 'utf8');
+    writeJsonAtomic(modelRecordFile(), all);
   } catch (err) {
     // The record is a convenience for a thin week, not a source of truth.
   }
@@ -1152,19 +1763,24 @@ function stampPlan(all, planId) {
 // Turn count only breaks the tie: it says how much local spend sat behind the
 // reading, not how precise the denominator was, and preferring it outright is
 // how a 44-turn baseline read at 1% once beat every honest sample after it.
+// Which of two prices to keep, and which to write back to disk.
+//
+// A wider reading is a better measurement, so percent still ranks - but only
+// between two readings that are measurements at all. An entry learned at either
+// end of the meter is not one, and ranking on percent alone meant a price
+// learned at 100 could never be displaced by an honest one from the middle:
+// 100 is the highest number there is, so it won every comparison and was
+// written back for ever. The file could not heal itself even once the readers
+// had started ignoring it.
 function betterCalibration(current, candidate) {
-  if (!candidate || !Number.isFinite(candidate.usdPerPercent) || candidate.usdPerPercent <= 0) {
-    return current || null;
-  }
-  if (!current || !Number.isFinite(current.turns)) return candidate;
-  if (
-    Number.isFinite(candidate.percent) &&
-    Number.isFinite(current.percent) &&
-    candidate.percent !== current.percent
-  ) {
-    return candidate.percent > current.percent ? candidate : current;
+  const fresh = usableCalibration(candidate);
+  const held = usableCalibration(current);
+  if (!fresh) return held || null;
+  if (!held || !Number.isFinite(held.turns)) return fresh;
+  if (Number.isFinite(fresh.percent) && Number.isFinite(held.percent) && fresh.percent !== held.percent) {
+    return fresh.percent > held.percent ? fresh : held;
   }
-  return candidate.turns > current.turns ? candidate : current;
+  return fresh.turns > held.turns ? fresh : held;
 }
 
 // Everything the report needs about one limit window.
@@ -1285,22 +1901,19 @@ function buildWindow(spec, snapshot, events, now, options) {
     // holding. The learned price covers it: what a point costs is a property
     // of the plan, not of this reading.
     const selfPriced =
-      rawPercent >= MIN_BASELINE_PERCENT && upTo.cost > 0 && upTo.turns >= MIN_BASELINE_TURNS
+      rawPercent >= MIN_BASELINE_PERCENT &&
+      rawPercent <= MAX_BASELINE_PERCENT &&
+      upTo.cost > 0 &&
+      upTo.turns >= MIN_BASELINE_TURNS
         ? { usdPerPercent: upTo.cost / rawPercent, turns: upTo.turns, percent: rawPercent }
         : null;
     // A metered window has nothing to learn: its price per point is stated.
     if (selfPriced && !extra.metered) window.calibration = selfPriced;
 
-    const known = extra.knownCalibration;
-    // A remembered price read off a near-empty meter is the same rounding
-    // bracket in disguise, so it is no more usable than measuring one now.
-    const usable =
-      known &&
-      Number.isFinite(known.usdPerPercent) &&
-      known.usdPerPercent > 0 &&
-      !(Number.isFinite(known.percent) && known.percent < MIN_BASELINE_PERCENT)
-        ? known
-        : null;
+    // A remembered price is only as good as the reading it was learned from,
+    // and both ends of the meter lie. One gate, shared with the headroom
+    // arithmetic below.
+    const usable = usableCalibration(extra.knownCalibration);
     // Trust the better-measured of the two, whichever that is; a stated price
     // beats both.
     const stated =
@@ -1349,10 +1962,17 @@ function buildWindow(spec, snapshot, events, now, options) {
   // window reading 1% divided a full hour of spend by one and priced the
   // remaining 99 points at thousands of dollars. Below the floor the learned
   // price takes over through the fallback chain.
+  // The ceiling is the same rule the other way up: at 100 the meter has
+  // stopped counting, so the spend past it divides against points that were
+  // never registered and every remaining point looks cheaper than it is.
   const measured =
-    percent !== null && percent >= MIN_BASELINE_PERCENT && spent.cost > 0 && !thin;
+    percent !== null &&
+    percent >= MIN_BASELINE_PERCENT &&
+    percent <= MAX_BASELINE_PERCENT &&
+    spent.cost > 0 &&
+    !thin;
   const derived = measured ? spent.cost / percent : null;
-  const known = extra.knownCalibration;
+  const known = usableCalibration(extra.knownCalibration);
   const metered =
     Boolean(extra.metered) && Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0;
   const priced = metered
@@ -1387,6 +2007,22 @@ function buildWindow(spec, snapshot, events, now, options) {
     }
   }
 
+  // When spending has gone further past the snapshot than the snapshot said was
+  // left, the percentage is a floor and the price per point was derived from a
+  // denominator that is no longer true. Everything downstream of it is worse
+  // than useless: measured live, the line read "13 per cent used, about 1301
+  // turns of headroom" in the same breath as warning that the window was
+  // probably already exhausted. A number that confident, that wrong, beside its
+  // own contradiction, is the failure this whole plugin exists to avoid.
+  //
+  // There is no honest count to print here, so none is printed. The warning
+  // that the snapshot has been outrun stands on its own.
+  if (window.pointsBeyondSnapshot) {
+    window.turnsLeft = null;
+    window.headroomMs = null;
+    window.remainingUSD = null;
+  }
+
   // A reset time in the past means the window already turned over and the
   // cached percentage describes a window that no longer exists. Reporting it
   // as current would claim the budget is gone when it has just come back.
@@ -1730,6 +2366,36 @@ const MIN_BASELINE_TURNS = 5;
 // truly at 35.
 const MIN_BASELINE_PERCENT = 5;
 
+// And a reading near the top cannot price one either, for the opposite reason.
+//
+// The price of a point is the spend inside the window divided by the meter's
+// own percentage, and that arithmetic assumes the meter is still counting. It
+// stops at 100. Everything spent past the cap is real money that moved no
+// points, so dividing by 100 counts it against points that were never
+// registered and the price comes out too cheap - which then converts later
+// spend into far more points than it moved, and the reported percentage
+// overshoots the account.
+//
+// Measured here on 2026-09-07: a five-hour price learned at a reading of 100
+// said a point cost $0.67, while the same window measured between two live
+// readings in the healthy range - 24% to 47% on $20.85 - said $0.91. Thirty-six
+// per cent too cheap, and the display was reading 54% against an account at 47.
+const MAX_BASELINE_PERCENT = 95;
+
+// Whether a remembered price may be used at all.
+//
+// Defined once because the question is asked in two different places, and
+// gating only one of them was exactly how the capped price kept getting
+// through: the correction refused it and the headroom arithmetic took it
+// anyway. A price with no reading recorded against it predates this check and
+// is taken on trust; a recorded one has to be from the middle of the meter.
+function usableCalibration(known) {
+  if (!known || !Number.isFinite(known.usdPerPercent) || known.usdPerPercent <= 0) return null;
+  if (!Number.isFinite(known.percent)) return known;
+  if (known.percent < MIN_BASELINE_PERCENT || known.percent > MAX_BASELINE_PERCENT) return null;
+  return known;
+}
+
 // Past this much of a window, a handful of local turns is not what spent it,
 // so their total is not a fair price for a point.
 const UNEXPLAINED_PERCENT = 20;
@@ -1954,7 +2620,11 @@ async function report(now, options) {
   // A stale snapshot can put a window's start slightly further back than
   // seven days, so give the scan a day of slack.
   const earliest = now - 8 * DAY;
-  const all = await readEvents(earliest);
+  // A hook is given ten seconds; the panel and the CLI have all the time they
+  // want. A scan that runs out of its budget returns what it managed to read
+  // and says so, which is how the report knows its correction may be short.
+  const all = await readEvents(earliest, options && options.budgetMs ? { budgetMs: options.budgetMs } : undefined);
+  const scanPartial = Boolean(all && all.partial);
   // A refused request is a record of the limit, not a turn against it, so it is
   // kept apart from everything that measures spend or pace.
   const rejections = lastRejections(all);
@@ -2043,6 +2713,20 @@ async function report(now, options) {
   const recent = totals(recentEvents);
 
   const binding = bindingWindow(windows);
+
+  // The effort the next turn will run at. Codex states it outright in
+  // config.toml; Claude Code stamps it on every assistant line, which is the
+  // only source that follows /effort mid-session. The setting is last.
+  let effortNow = (options && options.effort) || null;
+  if (!effortNow && !isCodex() && options && options.sessionId) {
+    const seen = liveEffort(options.sessionId);
+    if (seen && seen.effort) effortNow = seen.effort;
+  }
+  if (!effortNow) {
+    const configured = base.settings && base.settings.effortLevel;
+    if (configured && configured !== 'default') effortNow = configured;
+  }
+  if (!effortNow) effortNow = dominantEffort(recentEvents) || null;
   const scopeStart = binding ? binding.windowStart : now - 7 * DAY;
   const scoped = events.filter((event) => event.at >= scopeStart && event.at <= now);
   const scopedTotals = totals(scoped);
@@ -2086,6 +2770,17 @@ async function report(now, options) {
     },
     measuredTurns: mainThread(events).length,
     subagentTurns: events.length - mainThread(events).length,
+    // The effort the NEXT turn will run at, and what a turn has cost at each
+    // effort on record. Codex states it in config.toml; Claude Code stamps it
+    // on every line of the transcript.
+    effortNow,
+    effortRates: effortRates(events),
+    effortWarning: effortWarning(events, effortNow, binding),
+    codex: codexBlock(now),
+    // True when the scan hit its time budget before it had read everything, so
+    // the spend since the snapshot is a floor rather than a total. Anything
+    // that warns on the number says "at least" when this is set.
+    scanPartial,
   });
 }
 
@@ -2154,9 +2849,16 @@ function statusLine(collected) {
     if (!snapshot || typeof snapshot.utilization !== 'number') continue;
     const resetsAt = snapshot.resets_at ? Date.parse(snapshot.resets_at) : null;
     const msToReset = Number.isFinite(resetsAt) ? resetsAt - now : null;
+    // The snapshot is what the account last said; the spend since then is
+    // measured by a transcript scan this line can never afford. When a hook has
+    // already paid for that scan recently, use its answer. Measured on a real
+    // session, the difference was 13 per cent here against 73 in the report,
+    // and the flattering one was the one on screen.
+    const corrected = reading.correctedFor(spec.key, now, collected.snapshotFetchedAt);
     parts.push({
       label: SHORT_LABELS[spec.key] || spec.label,
-      percent: snapshot.utilization,
+      percent: corrected ? corrected.percentUsed : snapshot.utilization,
+      adjusted: Boolean(corrected && corrected.adjusted),
       msToReset,
       // A per-model weekly for a model that is not running is shown - hiding a
       // limit outright is the one failure worse than over-reporting one, and
@@ -2264,7 +2966,11 @@ function render(data) {
     // Two different situations, and telling them apart matters. Nothing to read
     // is a setup problem. Nothing to report is the correct answer on a plan
     // whose usage scales with credits rather than resetting on a clock.
-    if (data.windowless) {
+    if (data.unreadable) {
+      lines.push('  The meter reports usage windows but no readable percentage for them.');
+      lines.push('  That is a reading problem, not flexible pricing: the limit still');
+      lines.push('  applies. Run /status in Codex, or try again in a minute.');
+    } else if (data.windowless) {
       lines.push('  This account reports no rolling usage window.');
       lines.push('  On flexible pricing there is no percentage to run down: usage scales');
       lines.push('  with credits, so the credit balance above is the budget to plan against.');
@@ -2335,6 +3041,26 @@ function render(data) {
   }
   lines.push('');
 
+  // The other agent, directly under this one's windows and counting the other
+  // way: Codex reports what is LEFT, so every figure here says "left" and none
+  // of them can be read as a percentage spent.
+  if (data.codex && data.codex.rows.length) {
+    lines.push('  Codex usage' + (data.codex.plan ? '   ' + data.codex.plan : ''));
+    lines.push('  Window           Left   Resets in');
+    for (const row of data.codex.rows) {
+      lines.push(
+        '  ' + pad(row.title, 15) +
+          padLeft(row.percentLeft === null ? (row.stale ? 'rolled' : '-') : row.percentLeft + '%', 6) +
+          padLeft(row.stale ? '-' : formatDuration(row.msToReset), 12)
+      );
+    }
+    if (data.codex.note) lines.push('    ' + data.codex.note);
+    else if (Number.isFinite(data.codex.ageMs)) {
+      lines.push('    reading from ' + formatDuration(data.codex.ageMs) + ' ago, out of the rollouts Codex writes');
+    }
+    lines.push('');
+  }
+
   // How much room is left is only half the question. The other half is what
   // that room buys, and the answer is different for every model: the same
   // weekly holds a few hundred Fable turns or several thousand Sonnet ones.
@@ -2476,6 +3202,48 @@ function render(data) {
       (data.subagentTurns > 0 ? ' (+' + formatCount(data.subagentTurns) + ' subagent calls)' : '')
   );
 
+  // What a turn costs at each effort, when more than one has been measured.
+  // The single most useful line for anyone wondering where the budget went:
+  // effort changes the price of every turn rather than how many there are.
+  const rates = (data.effortRates || []).filter((row) => row.turns >= MIN_EFFORT_SAMPLE && row.outputPerTurn);
+  if (rates.length > 1) {
+    lines.push('');
+    lines.push('  What each effort costs, measured on this machine');
+    lines.push('    Effort        Turns   Output/turn' + (money ? '   Per turn' : ''));
+    for (const row of rates) {
+      lines.push(
+        '    ' +
+          String(row.effort + (row.effort === data.effortNow ? ' *' : '')).padEnd(12) +
+          padLeft(formatCount(row.turns), 7) +
+          padLeft(formatCount(Math.round(row.outputPerTurn)), 14) +
+          (money ? padLeft(formatUSD(row.perTurn), 11) : '')
+      );
+    }
+    if (data.effortNow) lines.push('    * the effort set now');
+    lines.push('    Output per turn is the part the effort setting controls; cost per turn');
+    lines.push('    also moves with how big the context happened to be.');
+  }
+
+  if (data.effortWarning) {
+    const warning = data.effortWarning;
+    lines.push('');
+    if (Number.isFinite(warning.turnsLeft)) {
+      lines.push(
+        '  Careful       at ' + warning.effort + ' effort this window holds about ' +
+          formatCount(warning.turnsLeft) + ' more turns' +
+          (Number.isFinite(warning.blendedTurnsLeft) && warning.blendedTurnsLeft > warning.turnsLeft
+            ? ', not the ' + formatCount(warning.blendedTurnsLeft) + ' above'
+            : '')
+      );
+    }
+    if (warning.cheaper && Number.isFinite(warning.cheaper.multiple)) {
+      lines.push(
+        '                ' + warning.effort + ' writes about ' + warning.cheaper.multiple.toFixed(1) +
+          'x the output per turn that ' + warning.cheaper.effort + ' does'
+      );
+    }
+  }
+
   if (data.windows.some((window) => window.adjusted)) {
     lines.push(
       '  Note          ~ includes spend since the snapshot was taken, which its own'
@@ -2850,7 +3618,20 @@ module.exports = {
   preferLive,
   accountUuid,
   subagentTranscripts,
+  claudeTranscriptFiles,
   readClaudeEvents,
+  SCAN_VERSION,
+  SCAN_KEEP_MS,
+  SCAN_MAX_EVENTS,
+  sessionTranscriptFile,
+  liveEffort,
+  liveModel,
+  EFFORT_TAIL_BYTES,
+  scanFile,
+  readScanCache,
+  writeScanCache,
+  writeJsonAtomic,
+  parseSlice,
   RATES,
   WINDOWS,
   rateFor,
@@ -2880,6 +3661,8 @@ module.exports = {
   SATURATION_LIMIT,
   MIN_BASELINE_TURNS,
   MIN_BASELINE_PERCENT,
+  usableCalibration,
+  MAX_BASELINE_PERCENT,
   accountFile,
   buildWindows,
   limitWindows,
@@ -2892,6 +3675,12 @@ module.exports = {
   calibrationFile,
   CRITICAL_PERCENT,
   dominantEffort,
+  effortRates,
+  codexBlock,
+  effortWarning,
+  MIN_EFFORT_SAMPLE,
+  EFFORT_DEARER_BY,
+  FEW_TURNS_AT_EFFORT,
   typicalTurnCost,
   activeSessions,
   sessionSpend,