claude-usage-limits 1.9.1 → 1.11.0

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

@@ -23,6 +23,7 @@ const readline = require('readline');
 
 const host = require('./host.js');
 const codex = require('./codex.js');
+const live = require('./live.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
@@ -69,6 +70,11 @@ const RATES = {
 // An unrecognised family falls back to Opus rates on purpose: over-estimating
 // cost understates headroom, and that is the safe direction for a budget.
 const FAMILIES = ['fable', 'mythos', 'opus', 'sonnet', 'haiku'];
+
+// Settings that name a strategy rather than a model. `opusplan` plans on Opus
+// and executes on Sonnet, so it spends into both families and neither of them
+// is what a substring match would find on its own.
+const MODEL_ALIASES = { opusplan: ['opus', 'sonnet'] };
 const FALLBACK_RATE = { input: 5, output: 25 };
 
 function familyOf(model) {
@@ -117,13 +123,85 @@ const CACHE_WRITE_5M = 1.25;
 const CACHE_WRITE_1H = 2;
 const CACHE_READ = 0.1;
 
+// `family` marks a window that caps one model family rather than the account
+// as a whole. It is what tells the rest of the file that a window cannot stop
+// work which does not use that family.
 const WINDOWS = [
   { key: 'five_hour', label: '5-hour', span: 5 * HOUR },
   { key: 'seven_day', label: 'weekly', span: 7 * DAY },
-  { key: 'seven_day_opus', label: 'weekly (Opus)', span: 7 * DAY },
-  { key: 'seven_day_sonnet', label: 'weekly (Sonnet)', span: 7 * DAY },
+  { key: 'seven_day_opus', label: 'weekly (Opus)', span: 7 * DAY, family: 'opus' },
+  { key: 'seven_day_sonnet', label: 'weekly (Sonnet)', span: 7 * DAY, family: 'sonnet' },
 ];
 
+// Which model families this agent can actually spend into.
+//
+// A per-model weekly caps one family's spend and nothing else, so it can only
+// ever stop work that uses that family. Reported without that qualification it
+// becomes the loudest number in the brief for a limit the session cannot move:
+// a session running Opus was told to weigh a Fable weekly at 88%, and no
+// amount of work it did would have moved it a single point.
+//
+// The configured model is the floor. A session's own turns are added on top,
+// because subagents and a mid-session /model both spend into families the
+// setting never mentions. Other sessions' turns are deliberately not counted:
+// what another window is burning is not this one's constraint.
+//
+// An empty set means the model could not be worked out at all, and nothing is
+// suppressed on the strength of a guess.
+function familiesInUse(events, sessionId, models) {
+  const families = new Set();
+  const hints = Array.isArray(models) ? models : [models];
+  for (const hint of hints) {
+    const name = normalizeModel(hint);
+    // Some settings name more than one model. `opusplan` plans on Opus and
+    // executes on Sonnet, so a session set to it spends into both, and reading
+    // only the first would suppress a Sonnet weekly while Sonnet is running.
+    const alias = MODEL_ALIASES[name];
+    if (alias) {
+      for (const family of alias) families.add(family);
+      continue;
+    }
+    const family = familyOf(name);
+    if (family) families.add(family);
+  }
+  // This session's own turns only. What another window is burning is not this
+  // one's constraint, and counting it is how a weekly for a model this agent
+  // never runs gets weighed against work that cannot move it. With no session
+  // to scan - the CLI report - the configured model is the whole answer, and
+  // when that says nothing usable, nothing is suppressed.
+  if (sessionId) {
+    for (const event of events || []) {
+      if (!event || event.sessionId !== sessionId) continue;
+      const family = familyOf(event.model);
+      if (family) families.add(family);
+    }
+  }
+  return families;
+}
+
+// Whether a window is one this agent can spend into. Windows that cap the whole
+// account always are; a per-model one only when that model is in use.
+function appliesTo(window, families) {
+  if (!window || !window.family) return true;
+  if (!families || !families.size) return true;
+  // Only ever suppress on a family this file recognises on both sides. A
+  // scoped weekly names its model by display name, and one for a model
+  // released after this table was written falls back to that raw name - which
+  // familyOf() will never return for the setting either, so the window would
+  // be suppressed permanently, including while it is the thing being spent.
+  if (FAMILIES.indexOf(window.family) === -1) return true;
+  return families.has(window.family);
+}
+
+// Stamps the answer onto each window so every reader - the binding choice, the
+// critical warning, the report table - makes the same call from the same field.
+function markApplicable(windows, families) {
+  for (const window of windows || []) {
+    if (window) window.applies = appliesTo(window, families);
+  }
+  return windows;
+}
+
 // organizationType gives the family; the rate limit tier is what separates
 // Max 5x from Max 20x. Both come out of oauthAccount.
 // Abbreviations for the status line, where there is no room to spell it out.
@@ -185,10 +263,35 @@ function configDir() {
 
 // The CLI keeps its account state in ~/.claude.json, or next to the config
 // directory when CLAUDE_CONFIG_DIR moves it.
-function accountFile() {
+//
+// Both can exist at once, and the one in the config directory is not
+// necessarily the one with the meter in it: a Claude Code migration writes a
+// small ~/.claude/.claude.json holding machine ids and migration flags while
+// the account state, including cachedUsageUtilization, stays in the home
+// directory file. Picking on existence alone found that stub, reported no
+// snapshot, and sent host detection off to Codex - which is how a Claude
+// session ends up quoting another agent's meter entirely. So choose the file
+// that actually carries a snapshot, and only fall back to existence.
+function accountFiles() {
   const scoped = path.join(configDir(), '.claude.json');
-  if (fs.existsSync(scoped)) return scoped;
-  return path.join(os.homedir(), '.claude.json');
+  const home = path.join(os.homedir(), '.claude.json');
+  return scoped === home ? [home] : [scoped, home];
+}
+
+function hasSnapshot(file) {
+  const parsed = readJson(file);
+  return Boolean(parsed && parsed.cachedUsageUtilization);
+}
+
+function accountFile() {
+  const candidates = accountFiles();
+  for (const file of candidates) {
+    if (hasSnapshot(file)) return file;
+  }
+  for (const file of candidates) {
+    if (fs.existsSync(file)) return file;
+  }
+  return candidates[candidates.length - 1];
 }
 
 function readJson(file) {
@@ -403,6 +506,29 @@ function freshFiles(dir, since) {
     .filter((file) => fresh(file, since));
 }
 
+// Every transcript under a session's subagents directory. Plain subagents
+// write straight into it; the agents a Workflow runs write under
+// subagents/workflows/<run id>/, and eight of those spending in parallel is
+// exactly the burst that empties a window between two readings, so they must
+// be counted. Two levels down is as deep as Claude Code goes today; a bounded
+// walk copes if that changes.
+function subagentTranscripts(dir, since, depth) {
+  const left = Number.isFinite(depth) ? depth : 3;
+  const files = freshFiles(dir, since);
+  if (left <= 0) return files;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    return files;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    for (const file of subagentTranscripts(path.join(dir, entry.name), since, left - 1)) files.push(file);
+  }
+  return files;
+}
+
 async function readClaudeEvents(since) {
   const root = path.join(configDir(), 'projects');
   let dirs = [];
@@ -427,7 +553,7 @@ async function readClaudeEvents(since) {
         // 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)) {
+        for (const file of subagentTranscripts(path.join(full, entry.name, 'subagents'), since)) {
           files.push({ file, project: dir.name });
         }
         continue;
@@ -676,8 +802,8 @@ function creditsFrom(utilization) {
 // Turn cost is not a single number, it is a spread: a turn that reads three
 // 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 = mainThread(events)
+function callPercentiles(events) {
+  const costs = (events || [])
     .map((event) => event.cost)
     .filter((cost) => Number.isFinite(cost) && cost > 0)
     .sort((a, b) => a - b);
@@ -687,6 +813,124 @@ function costPercentiles(events) {
   return { median: at(0.5), high: at(0.8), sample: costs.length };
 }
 
+function costPercentiles(events) {
+  return callPercentiles(mainThread(events));
+}
+
+// What a turn of each model family has actually cost on this machine.
+//
+// The account's snapshot has no model dimension at all. It says a window is at
+// 88 per cent and never says whose turns put it there, so the report could say
+// how much room was left and not what that room would buy. Every transcript
+// line carries its model, which is the half the snapshot is missing.
+//
+// Cost is measured over main-thread turns, because a turn of headroom means a
+// main-thread turn everywhere else in this file. A family that has only ever
+// run as a subagent has none to measure - Sonnet on this machine had 114 calls
+// and not one turn - and pricing it at nothing would hand back an unlimited
+// budget, so it is priced per call instead and the row says so.
+function modelSpend(events) {
+  const byFamily = new Map();
+  for (const event of events || []) {
+    const family = familyOf(event.model);
+    if (!family) continue;
+    if (!byFamily.has(family)) byFamily.set(family, []);
+    byFamily.get(family).push(event);
+  }
+
+  const rows = [];
+  for (const [family, own] of byFamily) {
+    const spent = totals(own);
+    const main = costPercentiles(own);
+    const rates = main || callPercentiles(own);
+    rows.push({
+      family,
+      calls: own.length,
+      turns: spent.turns,
+      usd: spent.cost,
+      tokens: spent.tokens,
+      usdPerTurn: rates ? rates.median : null,
+      sample: rates ? rates.sample : 0,
+      // True when the figure prices a subagent call rather than a turn.
+      perCall: !main,
+    });
+  }
+  return rows.sort((a, b) => b.usd - a.usd);
+}
+
+// Which window a family's spend lands in: its own weekly where the account
+// gives it one, and the shared weekly otherwise.
+function windowForFamily(windows, family) {
+  const own = (windows || []).find((w) => w && w.family === family);
+  if (own) return own;
+  return (windows || []).find((w) => w && w.key === 'seven_day') || null;
+}
+
+// Too few turns to price one. The figure is divided into the whole remaining
+// budget, so an error in it is multiplied up rather than averaged away.
+const MIN_MODEL_SAMPLE = 5;
+
+// What the room that is left buys, counted in turns of each model.
+//
+// Families that share the weekly window are alternatives, not additions: each
+// row says what the same remaining room would buy if it all went on that model.
+// A family with a weekly of its own is the exception, and it is the case worth
+// knowing about, because it is the one where changing model changes which wall
+// the work is walking towards.
+function modelHeadroom(windows, events, families, remembered) {
+  return modelSpend(events).map((row) => {
+    const window = windowForFamily(windows, row.family);
+    const learned = remembered && remembered[row.family];
+    // A handful of turns prices a turn badly. What was measured when there was
+    // a proper sample is better evidence than what this week happens to hold.
+    const thin = row.sample < MIN_MODEL_SAMPLE;
+    const canRemember =
+      thin && Boolean(learned) && Number.isFinite(learned.usdPerTurn) && learned.usdPerTurn > 0 &&
+      // A remembered per-call price is not a turn price either, whatever it is
+      // worth for delegation. See below.
+      !learned.perCall;
+    const usdPerTurn = canRemember ? learned.usdPerTurn : row.usdPerTurn;
+    const perCall = canRemember ? Boolean(learned.perCall) : row.perCall;
+    // No turn count for a model that has never taken a turn.
+    //
+    // A family that has only ever run as a subagent has errands to price, not
+    // turns: 114 Sonnet calls here averaged under two cents because they were
+    // one-shot lookups, and dividing the remaining budget by that promised
+    // twenty-two thousand Sonnet turns. Those turns would not be doing the work
+    // the Opus turns are doing, and the error is in the direction that promises
+    // room, which is the direction that gets a session cut off mid-edit. The
+    // row still says what the model has cost; it does not project from it.
+    //
+    // Nor against a window that has already rolled over. Its remaining money
+    // describes the allowance the stale reading was taken from, not the one
+    // running now, and dividing by a turn price turns that into a confident
+    // count of turns nobody has: a weekly past its reset offered five hundred.
+    const turnsLeft =
+      !perCall &&
+      window &&
+      !window.stale &&
+      Number.isFinite(window.remainingUSD) &&
+      Number.isFinite(usdPerTurn) &&
+      usdPerTurn > 0
+        ? Math.max(0, Math.floor(window.remainingUSD / usdPerTurn))
+        : null;
+    return Object.assign({}, row, {
+      windowKey: window ? window.key : null,
+      windowLabel: window ? window.label : null,
+      // True when this family has a weekly of its own rather than sharing.
+      ownWindow: Boolean(window && window.family),
+      // False when the window is one this agent cannot spend into anyway.
+      windowApplies: !window || window.applies !== false,
+      inUse: !families || !families.size || families.has(row.family),
+      usdPerTurn,
+      perCall,
+      // True when the price came off the record rather than this week's turns.
+      remembered: Boolean(canRemember),
+      turnsLeft,
+    });
+  });
+}
+
 // What a job of this many turns would take out of one window.
 function forecastWindow(window, turns, rates) {
   if (!window || !rates || !window.usdPerPercent || window.stale) return null;
@@ -791,6 +1035,70 @@ function writeCalibration(all) {
   }
 }
 
+// What each model has cost, kept so the next session does not have to have
+// spent anything to know.
+//
+// The transcripts only answer for as long as they are on disk and as far back
+// as the scan reaches, which is eight days. A session that opens on a model it
+// has not used this week would otherwise have no price for it at all, and what
+// Sonnet would buy is worth answering before the first Sonnet turn rather than
+// after. One entry per family, so it cannot grow.
+//
+// It is stamped with the plan and read back through the same guard as the
+// window calibration. What a turn costs is a fact about the model; what it buys
+// is a fact about the allowance, and that moves when the plan does.
+function modelRecordFile() {
+  const dir = isCodex() ? codex.homeDir() : configDir();
+  return path.join(dir, 'usage-limits-models.json');
+}
+
+function readModelRecord() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(modelRecordFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    return {};
+  }
+}
+
+function writeModelRecord(all) {
+  try {
+    fs.mkdirSync(path.dirname(modelRecordFile()), { recursive: true });
+    fs.writeFileSync(modelRecordFile(), JSON.stringify(all), 'utf8');
+  } catch (err) {
+    // The record is a convenience for a thin week, not a source of truth.
+  }
+}
+
+// The measurement to keep. Deliberately the freshest adequate one rather than
+// the largest: what a turn costs drifts as a session's context grows, so an old
+// figure with a big sample behind it is not the better answer, only the better
+// attested one.
+function modelSamples(headroom, previous) {
+  const kept = Object.assign({}, previous || {});
+  let changed = false;
+  for (const row of headroom || []) {
+    if (row.remembered) continue;
+    if (!Number.isFinite(row.usdPerTurn) || row.usdPerTurn <= 0) continue;
+    if (row.sample < MIN_MODEL_SAMPLE) continue;
+    // Rounded before comparing, so a fraction of a cent of drift does not
+    // rewrite the file on every prompt.
+    const usdPerTurn = Math.round(row.usdPerTurn * 1e6) / 1e6;
+    const before = kept[row.family];
+    if (
+      before &&
+      before.usdPerTurn === usdPerTurn &&
+      before.perCall === Boolean(row.perCall) &&
+      before.sample === row.sample
+    ) {
+      continue;
+    }
+    kept[row.family] = { usdPerTurn, sample: row.sample, perCall: Boolean(row.perCall) };
+    changed = true;
+  }
+  return { models: kept, changed };
+}
+
 // Everything learned about a budget belongs to the plan it was learned on.
 //
 // A point of a window is a share of an allowance, so changing the allowance
@@ -921,7 +1229,14 @@ function buildWindow(spec, snapshot, events, now, options) {
     severity: null,
     isActive: false,
     scoped: false,
-    family: null,
+    // The model family this window caps, when it caps one. Set from the spec
+    // here for the bucket-table weeklies, and again by the caller for the
+    // per-model limits that only exist in the account's own `limits` list.
+    family: spec.family || null,
+    // Whether this session's models spend into it. Filled in by
+    // markApplicable once the models in use are known; assume they do until
+    // then, so a reader that never marks them behaves exactly as before.
+    applies: true,
     verdict: 'unknown',
   };
 
@@ -1124,6 +1439,10 @@ function criticalOthers(windows, bindingKey, threshold) {
       w &&
       w.key !== bindingKey &&
       !w.stale &&
+      // A full window that this session cannot spend into is not a warning, it
+      // is someone else's news. Told to weigh it, the only thing an agent can
+      // do about it is less work, against a limit its work never touches.
+      w.applies !== false &&
       w.percentUsed !== null &&
       w.percentUsed >= limit
   );
@@ -1131,7 +1450,18 @@ function criticalOthers(windows, bindingKey, threshold) {
 
 // The window that will stop the work first.
 function bindingWindow(windows) {
-  const known = windows.filter((w) => w.percentUsed !== null);
+  // A per-model weekly for a model that is not running cannot be the window
+  // that stops the work, however full it is - and the account's own is_active
+  // flag says nothing about which model this session happens to be using, so
+  // it must not promote one either. Kept as a fallback in the impossible case
+  // that every window is a model's, so this never returns nothing.
+  // Ordered this way round on purpose: the fallback has to fire when there is
+  // no readable window left after suppression, not merely no window. Testing
+  // the unfiltered list first returned nothing at all where a suppressed
+  // per-model weekly was the only window carrying a reading.
+  const readable = windows.filter((w) => w && w.percentUsed !== null);
+  const relevant = readable.filter((w) => w.applies !== false);
+  const known = relevant.length ? relevant : readable;
   // Prefer windows we can still trust; fall back only if every one is stale.
   const fresh = known.filter((w) => !w.stale);
   const live = fresh.length ? fresh : known;
@@ -1320,12 +1650,39 @@ function collect(now) {
   return collectClaude(now);
 }
 
+// Whether the plugin's own live reading should stand in for Claude Code's
+// cache. Both describe the same account; the newer one is simply the more
+// recent fact. A reading for a different account, or one stamped from a clock
+// that is ahead, is not a fresher reading of this account.
+function preferLive(cache, fresh, accountUuid, now) {
+  if (!fresh || !fresh.utilization || typeof fresh.utilization !== 'object') return false;
+  if (!Number.isFinite(fresh.fetchedAtMs)) return false;
+  if (fresh.fetchedAtMs > now + MINUTE) return false;
+  if (fresh.accountUuid && accountUuid && fresh.accountUuid !== accountUuid) return false;
+  if (!cache || !Number.isFinite(cache.fetchedAtMs)) return true;
+  return fresh.fetchedAtMs > cache.fetchedAtMs;
+}
+
+// The account the login belongs to, so a live reading can be stamped with it.
+function accountUuid() {
+  const account = readJson(accountFile());
+  return account && account.oauthAccount && account.oauthAccount.accountUuid
+    ? account.oauthAccount.accountUuid
+    : null;
+}
+
 function collectClaude(now) {
   const account = readJson(accountFile()) || {};
   const settings = readJson(path.join(configDir(), 'settings.json')) || {};
   const cache = account.cachedUsageUtilization || null;
-  const utilization = cache && cache.utilization ? cache.utilization : null;
   const oauth = account.oauthAccount || {};
+  // The panel and the status line take the same reading Claude Code takes for
+  // /usage and keep it in a file of their own. When that is newer than what
+  // Claude Code cached, it is the better description of the same account.
+  const fresh = live.readLive();
+  const useLive = preferLive(cache, fresh, oauth.accountUuid, now);
+  const snapshot = useLive ? fresh : cache;
+  const utilization = snapshot && snapshot.utilization ? snapshot.utilization : null;
   const plan = detectPlan(oauth);
 
   return {
@@ -1337,8 +1694,9 @@ function collectClaude(now) {
     planId: plan.id,
     planTier: plan.tier,
     planAdvice: plan.advice,
-    snapshotAgeMs: cache && cache.fetchedAtMs ? now - cache.fetchedAtMs : null,
-    snapshotFetchedAt: cache && cache.fetchedAtMs ? cache.fetchedAtMs : null,
+    snapshotAgeMs: snapshot && snapshot.fetchedAtMs ? now - snapshot.fetchedAtMs : null,
+    snapshotFetchedAt: snapshot && snapshot.fetchedAtMs ? snapshot.fetchedAtMs : null,
+    snapshotSource: utilization ? (useLive ? 'live' : 'cache') : null,
     utilization,
     settings: {
       model: settings.model || 'default',
@@ -1644,6 +2002,28 @@ async function report(now, options) {
     calibrated.planChanged ? new Map() : rejections
   );
 
+  // Which of those windows this agent can actually spend into. Everything that
+  // ranks or warns about a window reads the answer off the window itself.
+  const families = familiesInUse(
+    events,
+    options && options.sessionId,
+    [base.settings && base.settings.model, process.env.ANTHROPIC_MODEL]
+  );
+  markApplicable(windows, families);
+
+  // What the room left buys in turns of each model, and the record that lets a
+  // later session answer that for a model it has not run yet. Scoped to a week
+  // because every window a family draws on here is a weekly one.
+  const remembered = calibrationForPlan(readModelRecord(), base.planId).learned;
+  const headroom = modelHeadroom(
+    windows,
+    events.filter((event) => event.at >= now - 7 * DAY),
+    families,
+    remembered
+  );
+  const sampled = modelSamples(headroom, remembered);
+  if (sampled.changed) writeModelRecord(stampPlan(sampled.models, base.planId));
+
   // Keep the best sample seen so far, so a thin baseline never has to guess.
   const updated = Object.assign({}, learned);
   for (const window of windows) {
@@ -1685,10 +2065,14 @@ async function report(now, options) {
     credits: base.codexCredits || creditsFrom(base.utilization),
     sessions: activeSessions(events, now, CONCURRENT_WINDOW_MS),
     session: sessionSpend(events, options && options.sessionId),
-    staleWindows: windows.filter((w) => w.stale).length,
+    // A per-model weekly for a model that is not running could be a week past
+    // its reset without that saying anything about the numbers this agent is
+    // working from, and it should not put "run /usage" on every prompt.
+    staleWindows: windows.filter((w) => w.stale && w.applies !== false).length,
     rates: costPercentiles(recentEvents.length >= 5 ? recentEvents : scoped),
     resumeAt: binding ? binding.resetsAt : null,
     models: scopedModels,
+    modelHeadroom: headroom,
     projects: byProject(scoped),
     tokens: scopedTotals.parts,
     reasoning: reasoningSpend(scopedModels, scopedTotals.parts),
@@ -1755,6 +2139,13 @@ function statusLine(collected) {
   if (!utilization) return '';
 
   const now = collected.now || Date.now();
+  // No transcripts here on purpose, so the only thing that says which model is
+  // running is the setting. That is enough to keep a weekly for a model this
+  // agent is not using out of a line that is meant to read as "your room".
+  const families = familiesInUse(null, null, [
+    collected.settings && collected.settings.model,
+    process.env.ANTHROPIC_MODEL,
+  ]);
   const parts = [];
   for (const spec of collected.windowSpecs && collected.windowSpecs.length
     ? collected.windowSpecs
@@ -1767,6 +2158,11 @@ function statusLine(collected) {
       label: SHORT_LABELS[spec.key] || spec.label,
       percent: snapshot.utilization,
       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
+      // the only thing telling this line which model is running is the
+      // setting, which can be behind. It just does not raise the alarm.
+      idle: !appliesTo(spec, families),
       stale: msToReset !== null && msToReset <= 0,
       // Zero with no reset time is not an empty window, it is a bucket that is
       // not reporting: a real window at 0% has just reset and says when it will
@@ -1775,9 +2171,33 @@ function statusLine(collected) {
       unreported: snapshot.utilization === 0 && !Number.isFinite(resetsAt),
     });
   }
+
+  // The per-model weeklies are not bucket keys, they are entries in the
+  // account's own `limits` list, so a loop over the bucket table never saw
+  // them. On a plan where the Fable weekly is the limit that actually binds,
+  // that meant the status line quoting the shared weekly at 24% while the
+  // window about to stop the work sat at 76, which is the wrong number in the
+  // most convincing possible place.
+  for (const limit of limitWindows(utilization)) {
+    if (!limit.family) continue;
+    const msToReset = Number.isFinite(limit.resetsAt) ? limit.resetsAt - now : null;
+    parts.push({
+      label: limit.family,
+      percent: limit.percent,
+      msToReset,
+      idle: !appliesTo(limit, families),
+      stale: msToReset !== null && msToReset <= 0,
+      unreported: false,
+    });
+  }
+
   if (!parts.length) return '';
 
-  const trusted = parts.filter((part) => !part.stale && !part.unreported);
+  // Shown, but never the alarm. Hiding a limit outright is the one failure
+  // worse than over-reporting one, and the only thing telling this line which
+  // model is running is the setting, which can be behind a /model. So an idle
+  // per-model weekly stays on the line and is left out of the worst-of.
+  const trusted = parts.filter((part) => !part.stale && !part.unreported && !part.idle);
   const worst = trusted.length
     ? trusted.reduce((a, b) => (b.percent > a.percent ? b : a))
     : null;
@@ -1806,7 +2226,9 @@ function render(data) {
   lines.push('  Plan       ' + data.plan);
   lines.push(
     '  Snapshot   ' +
-      (data.snapshotAgeMs === null ? 'none on disk' : formatDuration(data.snapshotAgeMs) + ' old')
+      (data.snapshotAgeMs === null
+        ? 'none on disk'
+        : formatDuration(data.snapshotAgeMs) + ' old' + (data.snapshotSource === 'live' ? ' (live reading)' : ''))
   );
   lines.push('  Settings   model=' + data.settings.model + '  effort=' + data.settings.effortLevel);
   if (data.planChanged) {
@@ -1869,11 +2291,18 @@ function render(data) {
     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';
+    // A per-model weekly for a model that is not running still belongs in the
+    // table - it is real, and switching to that model would make it bite - but
+    // it is not this agent's room, and a bare percentage next to the others
+    // reads as though it were. The row says which it is.
+    const idle = window.applies === false;
     const marker = bound
       ? '   <- binding' + (critical ? ', critical' : '')
-      : critical
-        ? '   critical'
-        : '';
+      : idle
+        ? '   not in use' + (critical ? ', critical for that model' : '')
+        : critical
+          ? '   critical'
+          : '';
     lines.push(
       '  ' + pad(window.label, 15) +
         padLeft(
@@ -1890,8 +2319,62 @@ function render(data) {
         marker
     );
   }
+  if (data.windows.some((window) => window.applies === false)) {
+    // Named from what is actually running rather than from the setting, which
+    // can say 'default', or name a strategy like 'opusplan', or be behind a
+    // /model - and the legend would then assert a model nothing was decided
+    // from.
+    const running = (data.modelHeadroom || [])
+      .filter((row) => row.inUse)
+      .map((row) => row.family);
+    lines.push(
+      '    not in use  caps one model, and this agent is running ' +
+        (running.length ? running.join(' and ') : 'another model') +
+        ', so nothing here spends into it'
+    );
+  }
   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.
+  // The account's own figures cannot say this - they have no model in them.
+  const headroom = money ? (data.modelHeadroom || []) : [];
+  if (headroom.some((row) => row.turnsLeft !== null)) {
+    lines.push('  Model headroom, what the room left buys in turns of each model');
+    lines.push(
+      '  ' + pad('  Model', 12) + pad('Window', 17) + padLeft('Turns', 7) +
+        padLeft('Spent', 9) + padLeft('Per turn', 10) + padLeft('Turns left', 12)
+    );
+    for (const row of headroom) {
+      lines.push(
+        '  ' + pad('  ' + row.family, 12) +
+          pad(row.windowLabel || '-', 17) +
+          padLeft(formatCount(row.sample), 7) +
+          padLeft(formatUSD(row.usd), 9) +
+          padLeft(formatUSD(row.usdPerTurn) + (row.perCall ? '*' : ''), 10) +
+          padLeft(row.turnsLeft === null ? '-' : '~' + formatCount(row.turnsLeft), 12) +
+          (row.inUse ? '   <- running' : '')
+      );
+    }
+    if (headroom.some((row) => row.perCall)) {
+      lines.push('    * a subagent call, not a turn: this model has taken no turns of its own,');
+      lines.push('      so there is nothing here to project a turn count from. The price is');
+      lines.push('      still what delegating to it has cost.');
+    }
+    if (headroom.some((row) => row.remembered)) {
+      lines.push('    A row with too few turns this week is priced from the record of what');
+      lines.push('    that model cost when there were enough.');
+    }
+    // The two tables price the same window differently on purpose, and someone
+    // is going to notice, so say why before it gets read as a bug.
+    lines.push('    Turns left in the table above is a blend of every model on record;');
+    lines.push("    these are each model's own measured cost per turn, and rows sharing a");
+    lines.push('    window are alternatives rather than additions: the same room, spent on');
+    lines.push('    a different model.');
+    lines.push('');
+  }
+
   // A bucket with no span cannot be priced or projected, but saying nothing
   // about one that is nearly full would be the worse failure.
   if (data.otherLimits && data.otherLimits.length) {
@@ -2097,6 +2580,9 @@ function renderForecast(data, turns) {
   }
 
   const rows = data.windows
+    // A limit this agent cannot spend into is not what a job fails to fit in,
+    // so it is never offered as a reason to cut the work down.
+    .filter((window) => window.applies !== false)
     .map((window) => forecastWindow(window, turns, data.rates))
     .filter(Boolean);
 
@@ -2316,7 +2802,10 @@ async function main(argv) {
     const turns = Number(argv[forecastAt + 1]);
     if (wantsJson) {
       const rows = data.windows
-        .map((window) => forecastWindow(window, turns, data.rates))
+        // A limit this agent cannot spend into is not what a job fails to fit in,
+    // so it is never offered as a reason to cut the work down.
+    .filter((window) => window.applies !== false)
+    .map((window) => forecastWindow(window, turns, data.rates))
         .filter(Boolean);
       process.stdout.write(JSON.stringify({ turns, rates: data.rates, windows: rows }, null, 2) + '\n');
     } else {
@@ -2358,12 +2847,27 @@ module.exports = {
   isCodex,
   otherLimits,
   collectClaude,
+  preferLive,
+  accountUuid,
+  subagentTranscripts,
   readClaudeEvents,
   RATES,
   WINDOWS,
   rateFor,
   familyOf,
   familyAverage,
+  familiesInUse,
+  appliesTo,
+  markApplicable,
+  callPercentiles,
+  modelSpend,
+  windowForFamily,
+  modelHeadroom,
+  modelSamples,
+  modelRecordFile,
+  readModelRecord,
+  writeModelRecord,
+  MIN_MODEL_SAMPLE,
   isKnownModel,
   costOf,
   tokensOf,
@@ -2376,6 +2880,7 @@ module.exports = {
   SATURATION_LIMIT,
   MIN_BASELINE_TURNS,
   MIN_BASELINE_PERCENT,
+  accountFile,
   buildWindows,
   limitWindows,
   lastRejections,