claude-usage-limits 1.7.1 → 1.8.0

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

@@ -55,7 +55,7 @@ const RATES = {
   'claude-opus-4-8': { input: 5, output: 25 },
   'claude-opus-4-7': { input: 5, output: 25 },
   'claude-opus-4-6': { input: 5, output: 25 },
-  'claude-sonnet-5': { input: 3, output: 15 },
+  'claude-sonnet-5': { input: 2, output: 10 },
   'claude-sonnet-4-6': { input: 3, output: 15 },
   'claude-haiku-4-5': { input: 1, output: 5 },
 };
@@ -296,6 +296,10 @@ function eventFrom(line, seen, project) {
     };
   }
 
+  // Interrupts and client-side errors are written as assistant messages from
+  // a model called <synthetic>, with a usage block of zeros. Not a call.
+  if (entry.message.model === '<synthetic>') return null;
+
   // A resumed or forked session repeats earlier turns in a new file.
   const id = (entry.message.id || '') + '|' + (entry.requestId || '');
   if (id !== '|' && seen) {
@@ -303,23 +307,76 @@ function eventFrom(line, seen, project) {
     seen.add(id);
   }
 
+  const parts = tokenParts(entry.message.usage);
   return {
     at,
     model: entry.message.model || '',
     effort: entry.effort || null,
     cost: costOf(entry.message.usage, entry.message.model),
     tokens: tokensOf(entry.message.usage),
-    parts: tokenParts(entry.message.usage),
+    parts,
+    // What the model was shown on this call: everything except what it wrote.
+    // It is re-sent on every later call, so it is the recurring cost of the
+    // session, and the one number that says how bloated the context has got.
+    context: parts.input + parts.cacheRead + parts.cacheWrite,
     project: project || null,
     sessionId: entry.sessionId || null,
+    // A subagent's turns are written under the parent session with these set.
+    sidechain: Boolean(entry.isSidechain || entry.agentId),
   };
 }
 
+// Whether a transcript line is a prompt the user typed. Tool results are also
+// written as user messages, and so are internal notes marked isMeta; neither
+// is something a person asked for.
+function promptFrom(line) {
+  if (line.indexOf('"user"') === -1) return false;
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch (err) {
+    return false;
+  }
+  if (!entry || entry.type !== 'user' || entry.isMeta || !entry.message) return false;
+  const content = entry.message.content;
+  if (typeof content === 'string') return content.length > 0;
+  if (!Array.isArray(content)) return false;
+  let typed = false;
+  for (const block of content) {
+    if (!block) continue;
+    if (block.type === 'tool_result') return false;
+    if (block.type === 'text') typed = true;
+  }
+  return typed;
+}
+
 async function readEvents(since) {
   if (isCodex()) return codex.readEvents(since);
   return readClaudeEvents(since);
 }
 
+// A file last touched before the window opened holds nothing useful.
+function fresh(file, since) {
+  try {
+    return fs.statSync(file).mtimeMs >= since;
+  } catch (err) {
+    return false;
+  }
+}
+
+function freshFiles(dir, since) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    return [];
+  }
+  return names
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => path.join(dir, name))
+    .filter((file) => fresh(file, since));
+}
+
 async function readClaudeEvents(since) {
   const root = path.join(configDir(), 'projects');
   let dirs = [];
@@ -333,21 +390,25 @@ async function readClaudeEvents(since) {
   for (const dir of dirs) {
     if (!dir.isDirectory()) continue;
     const full = path.join(root, dir.name);
-    let names = [];
+    let entries = [];
     try {
-      names = fs.readdirSync(full);
+      entries = fs.readdirSync(full, { withFileTypes: true });
     } catch (err) {
       continue;
     }
-    for (const name of names) {
-      if (!name.endsWith('.jsonl')) continue;
-      const file = path.join(full, name);
-      try {
-        // A file last touched before the window opened holds nothing useful.
-        if (fs.statSync(file).mtimeMs < since) continue;
-      } catch (err) {
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        // A session's subagents write their transcripts under
+        // <project>/<session id>/subagents/. Same budget, different file, and
+        // for a long time an Explore or Plan agent's whole spend went unseen.
+        for (const file of freshFiles(path.join(full, entry.name, 'subagents'), since)) {
+          files.push({ file, project: dir.name });
+        }
         continue;
       }
+      if (!entry.name.endsWith('.jsonl')) continue;
+      const file = path.join(full, entry.name);
+      if (!fresh(file, since)) continue;
       files.push({ file, project: dir.name });
     }
   }
@@ -374,13 +435,20 @@ async function readClaudeEvents(since) {
   return events;
 }
 
+// A turn is one main-thread call, the unit the headroom is planned in. A
+// subagent's calls spend the same budget, so they count in the money and the
+// tokens, and are counted apart so they never inflate the turn figures.
 function totals(events) {
   let cost = 0;
   let tokens = 0;
+  let turns = 0;
+  let subagentTurns = 0;
   const parts = { input: 0, cacheWrite: 0, cacheRead: 0, output: 0, reasoning: 0 };
   for (const event of events) {
     cost += event.cost;
     tokens += event.tokens;
+    if (event.sidechain) subagentTurns += 1;
+    else turns += 1;
     if (event.parts) {
       parts.input += event.parts.input;
       parts.cacheWrite += event.parts.cacheWrite;
@@ -389,7 +457,11 @@ function totals(events) {
       parts.reasoning += event.parts.reasoning || 0;
     }
   }
-  return { cost, tokens, turns: events.length, parts };
+  return { cost, tokens, turns, subagentTurns, parts };
+}
+
+function mainThread(events) {
+  return (events || []).filter((event) => !event.sidechain);
 }
 
 // What each model actually cost, dearest first.
@@ -437,8 +509,9 @@ function typicalTurnCost(recentEvents, windowEvents, allEvents, minSample) {
 
   // What a turn costs is a fact about how you work, not about which budget it
   // is being measured against, so a thin window borrows from a wider sample
-  // rather than inventing a figure from two turns.
-  const tiers = [recentEvents, windowEvents, allEvents];
+  // 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)];
   let pool = [];
   for (const tier of tiers) {
     if (tier && tier.length >= floor) {
@@ -578,7 +651,7 @@ function creditsFrom(utilization) {
 // files costs many times one that answers from context. A median alone
 // under-promises on the expensive half, so carry a high end too.
 function costPercentiles(events) {
-  const costs = (events || [])
+  const costs = mainThread(events)
     .map((event) => event.cost)
     .filter((cost) => Number.isFinite(cost) && cost > 0)
     .sort((a, b) => a - b);
@@ -640,11 +713,25 @@ function activeSessions(events, now, windowMs) {
 
 // The slice of the shared budget this session is actually getting. With
 // another session spending half of it, only half those turns are yours.
-function shareOf(sessions, sessionId) {
-  if (!sessions || sessions.length < 2) return 1;
-  const mine = sessions.find((row) => row.sessionId === sessionId);
-  if (!mine) return 1 / sessions.length;
-  return mine.share > 0 ? mine.share : 1 / sessions.length;
+//
+// Past spend says how the budget has been going, not how it will go. A
+// session that has only just started has almost none of it, and dividing its
+// headroom by that share once turned 208 turns into "about 6 turns left" two
+// tool calls into a session at 13 per cent used. So an equal split is the
+// floor: a measured share can raise it, never lower it. `activeCount` is how
+// many sessions are open, which can exceed how many have spent yet; the split
+// is among all of them.
+function shareOf(sessions, sessionId, activeCount) {
+  const spent = sessions || [];
+  const n = Math.max(spent.length, Number.isFinite(activeCount) ? activeCount : 0);
+  if (n < 2) return 1;
+  const equal = 1 / n;
+  // One session's spend is not a comparison. Until a second one has spent,
+  // being the only one on record says nothing about who owns the budget.
+  if (spent.length < 2) return equal;
+  const mine = spent.find((row) => row.sessionId === sessionId);
+  if (!mine || !(mine.share > 0)) return equal;
+  return Math.max(mine.share, equal);
 }
 
 // What a point of a window costs is a property of the plan, not of the moment,
@@ -768,6 +855,7 @@ function buildWindow(spec, snapshot, events, now, options) {
     spentUSD: spent.cost,
     spentTokens: spent.tokens,
     turns: spent.turns,
+    subagentTurns: spent.subagentTurns,
     recentTurns: recent.turns,
     recentUSDPerHour: recent.cost / recentHours,
     recentUSDPerTurn: recent.turns ? recent.cost / recent.turns : null,
@@ -789,6 +877,14 @@ function buildWindow(spec, snapshot, events, now, options) {
     correctionUnreliable: false,
     // The price-per-point this window derived from its own baseline.
     calibration: null,
+    // True when the bucket quoted its limit in dollars, so the price of a
+    // point is known rather than learned.
+    metered: false,
+    // What the account's own list of limits says about this one.
+    severity: null,
+    isActive: false,
+    scoped: false,
+    family: null,
     verdict: 'unknown',
   };
 
@@ -840,16 +936,23 @@ function buildWindow(spec, snapshot, events, now, options) {
       rawPercent > 0 && upTo.cost > 0 && upTo.turns >= MIN_BASELINE_TURNS
         ? { usdPerPercent: upTo.cost / rawPercent, turns: upTo.turns, percent: rawPercent }
         : null;
-    if (selfPriced) window.calibration = selfPriced;
+    // A metered window has nothing to learn: its price per point is stated.
+    if (selfPriced && !extra.metered) window.calibration = selfPriced;
 
     const known = extra.knownCalibration;
     const usable =
       known && Number.isFinite(known.usdPerPercent) && known.usdPerPercent > 0 ? known : null;
-    // Trust the better-sampled of the two, whichever that is.
+    // Trust the better-sampled of the two, whichever that is; a stated price
+    // beats both.
+    const stated =
+      extra.metered && Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0
+        ? { usdPerPercent: extra.usdPerPercent, turns: Infinity }
+        : null;
     const chosen =
-      selfPriced && usable
+      stated ||
+      (selfPriced && usable
         ? (usable.turns > selfPriced.turns ? usable : selfPriced)
-        : selfPriced || usable;
+        : selfPriced || usable);
 
     if (after.cost > 0 && chosen) {
       const pricePerPoint = chosen.usdPerPercent;
@@ -859,6 +962,10 @@ function buildWindow(spec, snapshot, events, now, options) {
       // not the window. Better to leave the reading uncorrected and say the
       // snapshot is old than to assert a budget that is gone.
       if (rawPercent + sinceSnapshot > SATURATION_LIMIT) {
+        // Keep the size of the overshoot: the brief needs it to say how far
+        // past the snapshot the spending has gone, instead of repeating the
+        // snapshot figure for hours as if it were current.
+        window.pointsBeyondSnapshot = Math.round(sinceSnapshot);
         sinceSnapshot = 0;
         window.correctionUnreliable = true;
       } else if (sinceSnapshot >= 1) {
@@ -884,14 +991,18 @@ function buildWindow(spec, snapshot, events, now, options) {
   const measured = percent !== null && percent > 0 && spent.cost > 0 && !thin;
   const derived = measured ? spent.cost / percent : null;
   const known = extra.knownCalibration;
-  const priced =
-    derived !== null
+  const metered =
+    Boolean(extra.metered) && Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0;
+  const priced = metered
+    ? extra.usdPerPercent
+    : derived !== null
       ? derived
       : Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0
         ? extra.usdPerPercent
         : known && Number.isFinite(known.usdPerPercent) && known.usdPerPercent > 0
           ? known.usdPerPercent
           : null;
+  window.metered = metered;
 
   if (percent !== null && priced !== null) {
     window.usdPerPercent = priced;
@@ -989,6 +1100,10 @@ function bindingWindow(windows) {
     const theirs = soonest(best);
     if (mine !== theirs) return mine < theirs ? w : best;
 
+    // Equally urgent by our own measure: the account says which limit it is
+    // enforcing, and that is worth more than a rule of thumb.
+    if (Boolean(w.isActive) !== Boolean(best.isActive)) return w.isActive ? w : best;
+
     // Equally urgent: the shorter window is the one hit first in practice, so
     // the 5-hour limit wins a tie against the weekly one.
     const myspan = Number.isFinite(w.spanMs) ? w.spanMs : Infinity;
@@ -1023,6 +1138,14 @@ function formatUSD(value) {
   return '$' + value.toFixed(3);
 }
 
+// Money to two places. Three below a dollar is right for a per-turn price and
+// wrong for a total someone reads after every reply.
+function formatMoney(value) {
+  if (value === null || !Number.isFinite(value)) return '-';
+  if (value >= 100) return '$' + Math.round(value);
+  return '$' + value.toFixed(2);
+}
+
 function formatTokens(value) {
   if (!Number.isFinite(value)) return '-';
   if (value >= 1e9) return (value / 1e9).toFixed(1) + 'B';
@@ -1099,6 +1222,49 @@ function otherLimits(utilization, threshold) {
   return rows.sort((a, b) => b.percentUsed - a.percentUsed);
 }
 
+// Beside the per-window buckets, the snapshot carries `limits`: one entry per
+// limit the account enforces, with a severity, whether it is the active one,
+// and for the per-model weeklies which model it scopes to. It is the account's
+// own description of its limits, and it can name a window the bucket table
+// does not: on a Max plan the Fable weekly sat at 17% while the shared weekly
+// read 11%, and nothing reported the higher of the two.
+const LIMIT_KINDS = { session: 'five_hour', weekly_all: 'seven_day' };
+
+function limitWindows(utilization) {
+  const list = utilization && Array.isArray(utilization.limits) ? utilization.limits : [];
+  const rows = [];
+  for (const limit of list) {
+    if (!limit || typeof limit !== 'object' || typeof limit.percent !== 'number') continue;
+    const resetsAt = limit.resets_at ? Date.parse(limit.resets_at) : null;
+    const base = {
+      kind: limit.kind,
+      percent: limit.percent,
+      severity: typeof limit.severity === 'string' ? limit.severity : null,
+      isActive: Boolean(limit.is_active),
+      resetsAt: Number.isFinite(resetsAt) ? resetsAt : null,
+      family: null,
+    };
+    if (LIMIT_KINDS[limit.kind]) {
+      rows.push(Object.assign(base, { key: LIMIT_KINDS[limit.kind] }));
+      continue;
+    }
+    if (limit.kind === 'weekly_scoped' && limit.scope && limit.scope.model) {
+      const model = limit.scope.model;
+      const name = model.display_name || model.id || 'model';
+      const family = familyOf(name) || familyOf(model.id) || String(name).toLowerCase();
+      rows.push(
+        Object.assign(base, {
+          key: 'seven_day_scoped:' + family,
+          label: 'weekly (' + name + ')',
+          family,
+          spanMs: 7 * DAY,
+        })
+      );
+    }
+  }
+  return rows;
+}
+
 function collect(now) {
   if (isCodex()) return codex.collect(now);
   return collectClaude(now);
@@ -1236,11 +1402,10 @@ function buildWindows(utilization, events, now, fetchedAt, learned, specs, rejec
   // of its two windows in the payload, so it hands its own spans in rather than
   // having them assumed.
   const table = specs && specs.length ? specs : WINDOWS;
-  return table.map((spec) => {
-    const snapshot = utilization[spec.key];
-    // The per-model weekly windows only exist on some plans.
-    if (spec.key !== 'five_hour' && spec.key !== 'seven_day' && !snapshot) return null;
+  const limits = limitWindows(utilization);
+  const limitByKey = new Map(limits.map((limit) => [limit.key, limit]));
 
+  const one = (spec, snapshot, own, limit) => {
     const known = learned ? learned[spec.key] : null;
     const refusal = refused.get(spec.key);
 
@@ -1261,34 +1426,91 @@ function buildWindows(utilization, events, now, fetchedAt, learned, specs, rejec
       }
     }
 
-    const window = buildWindow(spec, anchored, events, now, {
-      fetchedAt,
-      knownCalibration: known,
-      ...(windowStart === undefined ? {} : { windowStart }),
-    });
+    // A bucket that quotes its limit in dollars needs no calibration: a
+    // hundred dollars is a hundred points. Null on the plans seen so far, but
+    // the field is there, and when it fills in it beats any estimate.
+    const dollars =
+      snapshot && Number.isFinite(snapshot.limit_dollars) && snapshot.limit_dollars > 0
+        ? snapshot.limit_dollars / 100
+        : null;
+
+    const window = buildWindow(
+      spec,
+      anchored,
+      own,
+      now,
+      Object.assign(
+        { fetchedAt, knownCalibration: known },
+        windowStart === undefined ? {} : { windowStart },
+        dollars === null ? {} : { metered: true, usdPerPercent: dollars }
+      )
+    );
     if (refusal) {
       window.refusedAt = refusal.at;
       window.refusedResetsAt = refusal.resetsAt;
     }
+
+    let result = window;
     if (!window.stale) {
-      return reconstructUnanchored(spec, window, events, now, known) || window;
+      result = reconstructUnanchored(spec, window, own, now, known) || window;
+    } else {
+      // Rolled over. Rebuild from local history rather than going blind on it.
+      const rebuilt = reconstructWindow(spec, snapshot, own, now);
+      if (rebuilt) {
+        result = buildWindow(
+          spec,
+          { utilization: rebuilt.percentUsed, resets_at: null },
+          own,
+          now,
+          {
+            estimated: true,
+            windowStart: rebuilt.windowStart,
+            usdPerPercent: rebuilt.usdPerPercent,
+          }
+        );
+      }
+    }
+    // What the account itself says about this limit rides along.
+    if (limit) {
+      result.severity = limit.severity;
+      result.isActive = limit.isActive;
     }
+    return result;
+  };
 
-    // Rolled over. Rebuild from local history rather than going blind on it.
-    const rebuilt = reconstructWindow(spec, snapshot, events, now);
-    if (!rebuilt) return window;
-    return buildWindow(
-      spec,
-      { utilization: rebuilt.percentUsed, resets_at: null },
-      events,
-      now,
-      {
-        estimated: true,
-        windowStart: rebuilt.windowStart,
-        usdPerPercent: rebuilt.usdPerPercent,
+  const windows = table
+    .map((spec) => {
+      let snapshot = utilization[spec.key];
+      const limit = limitByKey.get(spec.key);
+      // The account's own list can carry a window the bucket table does not.
+      if ((!snapshot || typeof snapshot.utilization !== 'number') && limit) {
+        snapshot = {
+          utilization: limit.percent,
+          resets_at: limit.resetsAt ? new Date(limit.resetsAt).toISOString() : null,
+        };
       }
-    );
-  }).filter(Boolean);
+      // The per-model weekly windows only exist on some plans.
+      if (spec.key !== 'five_hour' && spec.key !== 'seven_day' && !snapshot) return null;
+      return one(spec, snapshot, events, limit);
+    })
+    .filter(Boolean);
+
+  // A per-model weekly is a limit on one model's spend, so it is priced from
+  // that model's calls alone; the shared windows still see everything.
+  for (const limit of limits) {
+    if (!limit.family) continue;
+    const spec = { key: limit.key, label: limit.label, span: limit.spanMs };
+    const own = events.filter((event) => familyOf(event.model) === limit.family);
+    const snapshot = {
+      utilization: limit.percent,
+      resets_at: limit.resetsAt ? new Date(limit.resetsAt).toISOString() : null,
+    };
+    const window = one(spec, snapshot, own, limit);
+    window.scoped = true;
+    window.family = limit.family;
+    windows.push(window);
+  }
+  return windows;
 }
 
 // What one session has spent, out of everything on record.
@@ -1296,12 +1518,14 @@ function sessionSpend(events, sessionId) {
   if (!sessionId) return null;
   let cost = 0;
   let turns = 0;
+  let tokens = 0;
   for (const event of events) {
     if (event.sessionId !== sessionId) continue;
     cost += event.cost;
-    turns += 1;
+    tokens += event.tokens || 0;
+    if (!event.sidechain) turns += 1;
   }
-  return turns ? { turns, cost } : null;
+  return turns ? { turns, cost, tokens } : null;
 }
 
 async function report(now, options) {
@@ -1413,7 +1637,8 @@ async function report(now, options) {
       tokens: recent.tokens,
       effort: dominantEffort(recentEvents),
     },
-    measuredTurns: events.length,
+    measuredTurns: mainThread(events).length,
+    subagentTurns: events.length - mainThread(events).length,
   });
 }
 
@@ -1578,7 +1803,14 @@ function render(data) {
       (money ? padLeft('Left', 10) : '') + padLeft('Turns left', 12)
   );
   for (const window of data.windows) {
-    const marker = data.binding && window.key === data.binding.key ? '   <- binding' : '';
+    const bound = data.binding && window.key === data.binding.key;
+    // The account's own severity, when it says critical, is worth a word.
+    const critical = window.severity === 'critical';
+    const marker = bound
+      ? '   <- binding' + (critical ? ', critical' : '')
+      : critical
+        ? '   critical'
+        : '';
     lines.push(
       '  ' + pad(window.label, 15) +
         padLeft(
@@ -1693,7 +1925,10 @@ function render(data) {
   } else {
     lines.push('  Recent pace   no turns in the last hour');
   }
-  lines.push('  Measured      ' + formatCount(data.measuredTurns) + ' turns of local transcript');
+  lines.push(
+    '  Measured      ' + formatCount(data.measuredTurns) + ' turns of local transcript' +
+      (data.subagentTurns > 0 ? ' (+' + formatCount(data.subagentTurns) + ' subagent calls)' : '')
+  );
 
   if (data.windows.some((window) => window.adjusted)) {
     lines.push(
@@ -1861,6 +2096,102 @@ function renderForecast(data, turns) {
   return lines.join('\n');
 }
 
+// The session history kept by the Stop hook, one row per session.
+function sessionTokens(session) {
+  const t = (session && session.tokens) || {};
+  return (t.input || 0) + (t.cacheWrite || 0) + (t.cacheRead || 0) + (t.output || 0);
+}
+
+function shortId(sessionId) {
+  return String(sessionId || '').slice(0, 8);
+}
+
+function renderSessions(list, now) {
+  const lines = [];
+  lines.push('Sessions on this machine, newest first');
+  lines.push('');
+  if (!list || !list.length) {
+    lines.push('  No sessions on record yet. The Stop hook writes one after each reply, so');
+    lines.push('  this fills in as soon as a session with the hook installed has run.');
+    return lines.join('\n');
+  }
+  lines.push(
+    '  ' + pad('Id', 10) + pad('When', 12) + pad('Project', 24) + padLeft('Prompts', 7) +
+      padLeft('Turns', 9) + padLeft('Tokens', 9) + padLeft('Cost', 9)
+  );
+  for (const session of list) {
+    const turns =
+      String(session.turns || 0) + (session.subagentTurns > 0 ? '+' + session.subagentTurns : '');
+    lines.push(
+      '  ' + pad(shortId(session.sessionId), 10) +
+        pad(Number.isFinite(session.lastAt) ? formatDuration(now - session.lastAt) + ' ago' : '-', 12) +
+        pad(shortenProject(session.project || '-', 22), 24) +
+        padLeft(session.prompts || 0, 7) +
+        padLeft(turns, 9) +
+        padLeft(formatTokens(sessionTokens(session)), 9) +
+        padLeft(formatMoney(session.cost || 0), 9) +
+        (Number.isFinite(session.endedAt) ? '' : '  open')
+    );
+  }
+  lines.push('');
+  lines.push('  Turns are main-thread calls; +N is what subagents made on top.');
+  return lines.join('\n');
+}
+
+function renderSession(session, now) {
+  const lines = [];
+  lines.push('Session ' + shortId(session.sessionId) + (session.project ? ' (' + session.project + ')' : ''));
+  lines.push('');
+  const started = Number.isFinite(session.firstAt)
+    ? formatClock(session.firstAt) + ', ' + formatDuration(now - session.firstAt) + ' ago, '
+    : '';
+  const ended = Number.isFinite(session.endedAt)
+    ? 'closed ' + formatDuration(now - session.endedAt) + ' ago' + (session.reason ? ' (' + session.reason + ')' : '')
+    : 'still open';
+  lines.push('  Started    ' + started + ended);
+  lines.push('  Prompts    ' + (session.prompts || 0));
+  lines.push(
+    '  Turns      ' + (session.turns || 0) +
+      (session.subagentTurns > 0 ? ', plus ' + session.subagentTurns + ' by subagents' : '')
+  );
+  const t = session.tokens || {};
+  lines.push(
+    '  Tokens     ' + formatTokens(sessionTokens(session)) + ': input ' + formatTokens(t.input || 0) +
+      ', cache write ' + formatTokens(t.cacheWrite || 0) + ', cache read ' + formatTokens(t.cacheRead || 0) +
+      ', output ' + formatTokens(t.output || 0) +
+      (t.reasoning > 0 ? ' (' + formatTokens(t.reasoning) + ' of it reasoning)' : '')
+  );
+  lines.push('  Cost       ' + formatMoney(session.cost || 0));
+  if (Number.isFinite(session.context) && session.context > 0) {
+    lines.push('  Context    ' + formatTokens(session.context) + ' tokens at the last call');
+  }
+  const models = Object.keys(session.models || {}).sort(
+    (a, b) => (session.models[b].cost || 0) - (session.models[a].cost || 0)
+  );
+  models.forEach((id, index) => {
+    const row = session.models[id];
+    lines.push(
+      (index === 0 ? '  Models     ' : '             ') + pad(id, 24) +
+        padLeft((row.turns || 0) + ' turns', 12) + padLeft(formatMoney(row.cost || 0), 10)
+    );
+  });
+  return lines.join('\n');
+}
+
+// "last", an exact id, or an unambiguous prefix of one.
+function pickSession(list, which) {
+  const rows = list || [];
+  if (!rows.length) return null;
+  const want = String(which || 'last');
+  if (want === 'last') {
+    return rows.slice().sort((a, b) => (b.lastAt || 0) - (a.lastAt || 0))[0];
+  }
+  const exact = rows.find((row) => row.sessionId === want);
+  if (exact) return exact;
+  const prefixed = rows.filter((row) => String(row.sessionId || '').startsWith(want));
+  return prefixed.length === 1 ? prefixed[0] : null;
+}
+
 async function main(argv) {
   // Settle the host before anything reads a file, so one run never mixes one
   // agent's percentages with the other's turns.
@@ -1872,6 +2203,29 @@ async function main(argv) {
     return 0;
   }
 
+  // The session history is a file the Stop hook keeps, so neither of these
+  // opens a transcript. Required lazily: tally.js depends on this module.
+  const sessionAt = argv.indexOf('--session');
+  if (sessionAt !== -1 || argv.indexOf('--sessions') !== -1) {
+    const tally = require('./tally.js');
+    const list = tally.sessions(tally.readState());
+    const now = Date.now();
+    const json = argv.indexOf('--json') !== -1;
+    if (sessionAt !== -1) {
+      const next = argv[sessionAt + 1];
+      const which = next && next.indexOf('--') !== 0 ? next : 'last';
+      const picked = pickSession(list, which);
+      if (!picked) {
+        process.stderr.write('usage: no session matches "' + which + '". Run --sessions to list them.\n');
+        return 2;
+      }
+      process.stdout.write((json ? JSON.stringify(picked, null, 2) : renderSession(picked, now)) + '\n');
+      return 0;
+    }
+    process.stdout.write((json ? JSON.stringify(list, null, 2) : renderSessions(list, now)) + '\n');
+    return 0;
+  }
+
   // Codex writes its meter into the session rollouts, so the cached reading is
   // only as fresh as the last request it made. Asking Codex itself is a second
   // and a child process, which is why it is opt-in rather than the default.
@@ -1915,13 +2269,8 @@ async function main(argv) {
   return 0;
 }
 
-if (require.main === module) {
-  main(process.argv.slice(2)).catch((err) => {
-    process.stderr.write('usage: ' + (err && err.message ? err.message : String(err)) + '\n');
-    process.exitCode = 1;
-  });
-}
-
+// Assigned before main() can run: tally.js requires this module back, and a
+// lazy require from inside main() would otherwise see an empty exports object.
 module.exports = {
   main,
   setHost,
@@ -1939,12 +2288,15 @@ module.exports = {
   costOf,
   tokensOf,
   eventFrom,
+  promptFrom,
   readEvents,
+  readCalibration,
   buildWindow,
   reconstructWindow,
   SATURATION_LIMIT,
   MIN_BASELINE_TURNS,
   buildWindows,
+  limitWindows,
   lastRejections,
   bindingWindow,
   criticalOthers,
@@ -1962,7 +2314,11 @@ module.exports = {
   MIN_PACE_SAMPLE,
   formatDuration,
   formatUSD,
+  formatMoney,
   formatCount,
+  renderSessions,
+  renderSession,
+  pickSession,
   verdictLine,
   render,
   report,
@@ -1983,3 +2339,10 @@ module.exports = {
   formatTokens,
   PLANS,
 };
+
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write('usage: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  });
+}