claude-usage-limits 1.11.6 → 1.13.0

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

@@ -46,6 +46,9 @@ const POLL_FLOOR_MS = 15 * SECOND;
 const FILE_CHECK_MS = SECOND;
 const FRAME_MS = 100;
 const MIN_COLUMNS = 24;
+// The widest thing that follows a Codex bar, plus its space: "no reading" is
+// ten characters and "100% left" is nine.
+const CODEX_SUFFIX = 11;
 const TITLE = 'Claude usage';
 const LEVEL_RANK = { fill: 0, warning: 1, error: 2 };
 
@@ -156,8 +159,38 @@ async function snapshot(options) {
   const slots = onCodex ? {} : feed.readFeed();
   // Stay with the session already being described, so two windows on the same
   // model at different efforts do not make the header flip back and forth.
-  const slot = feed.stickySlot(slots, opts.sessionId, now);
-  const seen = onCodex ? { working: codexWorking(now), ultracode: false, model: null } : activity.summarise(activity.read(), now);
+  const marks = onCodex ? {} : activity.read();
+  // The session to describe: the one this display was already describing,
+  // else the newest mark. Every session writes a mark, but only a terminal
+  // session writes a feed slot, so choosing from the feed meant a VS Code
+  // window with no status line was never the one described and its own
+  // ultrathink never showed.
+  const freshest = Object.keys(marks)
+    .filter((key) => key !== '_' && marks[key] && Number.isFinite(marks[key].at) && now - marks[key].at <= activity.STALE_MS)
+    .sort((a, b) => marks[b].at - marks[a].at)[0];
+  const sticky = opts.sessionId && marks[opts.sessionId] && now - marks[opts.sessionId].at <= feed.STICKY_QUIET_MS;
+  const described = (sticky ? opts.sessionId : null) || freshest || opts.sessionId || null;
+  // A described session with no status line of its own (VS Code) must not be
+  // dressed in another session's slot: that is how a Fable window came to say
+  // Opus. Its transcript speaks for it instead. Only a panel with no session
+  // at all falls back to the newest slot on the machine.
+  const slot = (described && slots[described]) || (described ? null : feed.stickySlot(slots, opts.sessionId, now));
+  const spoken = !onCodex && described && !slot ? usage.liveModel(described) : null;
+  // The marks are machine-wide, and this panel describes ONE session. Reading
+  // the machine-wide summary here is what let a prompt in another window put
+  // ultrathink on this window's bars. When the session being described is
+  // known, its own mark is the only one that speaks for it.
+  // A panel that was given a session speaks for that session alone. A panel
+  // with none of its own is the machine's, and there the newest working
+  // session's word is the one shown - two windows in different modes would
+  // otherwise make it depend on whose tool call landed last.
+  const seen = onCodex
+    ? { working: codexWorking(now), ultracode: false, ultrathink: false, model: null }
+    : opts.sessionId && marks[opts.sessionId]
+      ? Object.assign(feed.ownState(marks, opts.sessionId, now), {
+          model: (marks[opts.sessionId] && marks[opts.sessionId].model) || null,
+        })
+      : activity.summarise(marks, now);
   const settings = onCodex ? {} : settingsFor();
 
   const built = view.build({
@@ -168,26 +201,28 @@ async function snapshot(options) {
     windowSpecs: collected.windowSpecs || null,
     headers: slot ? slot.rateLimits : null,
     headersAt: slot ? slot.headersAt : null,
-    model: (slot && slot.model) || seen.model || null,
+    model: (slot && slot.model) || seen.model || (spoken && spoken.model) || null,
     modelName: slot ? slot.modelName : null,
-    // The status line is told the effort by Claude Code itself; the setting is
-    // the fallback, and it is what says "ultracode" when no status line is
-    // installed.
-    effort:
-      (slot && slot.effort) ||
-      (collected.settings && collected.settings.effortLevel && collected.settings.effortLevel !== 'default'
-        ? collected.settings.effortLevel
-        : null),
+    // Whichever of the status line and the transcript spoke last. The setting
+    // is only the last resort: a panel beside a VS Code window has no status
+    // line to ask, and the setting there never moves, which is how it came to
+    // report xhigh through a session running at max.
+    effort: view.pickEffort(
+      slot && slot.effort ? { effort: slot.effort, at: slot.at } : null,
+      onCodex || !described ? null : usage.liveEffort(described),
+      collected.settings ? collected.settings.effortLevel : null
+    ),
     working: seen.working || feed.isWorking(slot, now),
     // Ultracode comes from the effort level above, not from here. Ultrathink
     // is a word in a prompt, and the hooks record it per session.
     ultrathink: Boolean(seen.ultrathink),
+    ultracode: Boolean(seen.ultracode) || settings.ultracode === true,
     settingsModel: collected.settings ? collected.settings.model : null,
     outcome,
     env,
   });
   built.now = now;
-  built.sessionId = slot && slot.sessionId ? slot.sessionId : null;
+  built.sessionId = described || (slot && slot.sessionId) || null;
   built.host = onCodex ? 'codex' : 'claude';
   built.title = onCodex ? 'Codex usage' : TITLE;
   built.plan = collected.plan || null;
@@ -203,6 +238,28 @@ async function snapshot(options) {
   // the report, so it is taken with the readings, not with every frame; the
   // frames in between carry the last answer forward.
   built.pace = opts.pace !== undefined ? opts.pace : await paceOf(now);
+  // The other agent's meter, drawn under this one's.
+  //
+  // Read from Codex's own rollouts on disk and nothing else: no child process,
+  // no network, no waiting. Codex having nothing to say, or not being installed
+  // at all, must never be a reason the Claude panel is late or absent.
+  built.codex = null;
+  if (!onCodex && host.codexHasSessions()) {
+    try {
+      const other = codex.collect(now);
+      const block = view.buildCodex({
+        now,
+        utilization: other.utilization,
+        fetchedAtMs: other.snapshotFetchedAt,
+        windowSpecs: other.windowSpecs,
+        plan: other.plan,
+        windowless: other.windowless,
+      });
+      if (block.present) built.codex = block;
+    } catch (err) {
+      // An unreadable Codex is simply no Codex row.
+    }
+  }
   // Whether the panel is allowed the network at all, which is what the footer
   // reports. A frame rebuilt from disk between readings is not "network off".
   built.fetch = opts.network !== undefined ? Boolean(opts.network) : Boolean(opts.fetch);
@@ -244,10 +301,65 @@ function codexWorking(now) {
   }
 }
 
-// The sessions this machine has heard from lately, from every file the hooks
-// and the status line keep. The tally is required lazily: it requires usage.js
-// back, and this module is loaded by the VS Code extension too.
+// Codex runs no hooks on this machine, so it writes no marks, and its sessions
+// never appeared beside the Claudes. Its rollout files say what a mark would:
+// a rollout appended in the last half minute is a session at work, one touched
+// within the stale window is one idling. The first line of a rollout is the
+// session's meta record - its id, its working directory, what launched it.
+function codexSessions(now, opts) {
+  const o = opts || {};
+  const stale = Number.isFinite(o.staleMs) ? o.staleMs : activity.STALE_MS;
+  const busyMs = Number.isFinite(o.busyMs) ? o.busyMs : 30 * SECOND;
+  let files = [];
+  try {
+    files = Array.isArray(o.files) ? o.files : codex.rolloutFiles(now - stale);
+  } catch (err) {
+    return [];
+  }
+  const rows = [];
+  for (const entry of files) {
+    if (!entry || !Number.isFinite(entry.at) || entry.at < now - stale) continue;
+    let meta = null;
+    try {
+      const fd = fs.openSync(entry.file, 'r');
+      const buf = Buffer.alloc(4096);
+      const n = fs.readSync(fd, buf, 0, 4096, 0);
+      fs.closeSync(fd);
+      const first = buf.toString('utf8', 0, n).split(String.fromCharCode(10))[0];
+      const parsed = JSON.parse(first);
+      meta = parsed && parsed.payload && typeof parsed.payload === 'object' ? parsed.payload : null;
+    } catch (err) {
+      meta = null;
+    }
+    const id = (meta && (meta.session_id || meta.id)) || path.basename(entry.file, '.jsonl');
+    rows.push({
+      key: 'codex:' + id,
+      id,
+      host: 'codex',
+      state: entry.at >= now - busyMs ? 'working' : 'idle',
+      stateAt: entry.at,
+      lastAt: entry.at,
+      model: null,
+      modelName: 'Codex' + (meta && meta.originator ? ' (' + String(meta.originator) + ')' : ''),
+      cwd: meta && meta.cwd ? String(meta.cwd) : null,
+      ultracode: false,
+      ultrathink: false,
+    });
+  }
+  rows.sort((x, y) => y.lastAt - x.lastAt);
+  return rows;
+}
+
+// Every session this machine has heard from lately: the Claudes from the
+// files the hooks and the status line keep, and the Codexes from their own
+// rollouts.
 function loadSessions(now) {
+  return claudeSessions(now).concat(codexSessions(now));
+}
+
+// The tally is required lazily: it requires usage.js back, and this module is
+// loaded by the VS Code extension too.
+function claudeSessions(now) {
   let tallyList = [];
   try {
     const tally = require('./tally.js');
@@ -303,6 +415,22 @@ function shortTitle(row) {
   return String(row.title).replace(/^Current week /, 'Week ').replace(/^Current /, '');
 }
 
+// Codex's own row titles are already short; these are for a very narrow pane.
+function shortCodexTitle(row) {
+  if (row.key === 'five_hour') return '5h';
+  if (row.key === 'seven_day') return 'Week';
+  return String(row.title).replace(/ limit$/, '');
+}
+
+// The Codex rows say "left", so their sublines have to as well, and they must
+// never point at a Claude Code command to fix a Codex reading.
+function codexSubline(row, mode, opts) {
+  if (row.stale) return bars.dim('window rolled over since Codex last ran', mode);
+  if (row.percentLeft === null) return bars.dim('no reading yet', mode);
+  const reset = bars.formatReset(row.msToReset, row.resetsAtMs, opts.now, { clock: opts.clock });
+  return reset ? bars.dim(reset, mode) : '';
+}
+
 function subline(row, mode, opts) {
   if (row.stale) return bars.dim('window rolled over, taking a fresh reading', mode);
   if (row.unreported) return bars.dim('not reported yet, run /usage in Claude Code', mode);
@@ -408,6 +536,42 @@ function render(built, options) {
     });
   }
 
+  // The Codex block, in the same shapes and the same colours, counting the
+  // other way: Codex reports what is LEFT, so its bars drain as they are spent
+  // where Claude's fill. The mark is a plain hexagon rather than the Codex
+  // logo, which is OpenAI's Blossom and not ours to recolour.
+  if (built.codex && built.codex.rows.length) {
+    const block = built.codex;
+    const lines = [
+      bars.bold(bars.paint(block.title, bars.THEME.codex, mode), mode),
+    ];
+    // "85% left" is five characters wider than "85%", so the Codex bars get
+    // their own width. Sharing the Claude one clipped every Codex row.
+    const codexWidth = Math.max(6, Math.min(50, columns - CODEX_SUFFIX));
+    for (const row of block.rows) {
+      const percent =
+        row.level === 'fill' ? row.percentText : bars.paint(row.percentText, bars.levelColour(row.level), mode);
+      lines.push(bars.bold(columns < 34 ? shortCodexTitle(row) : row.title, mode));
+      lines.push(
+        (row.percentLeft === null
+          ? bars.paint((ascii ? '-' : '░').repeat(codexWidth), bars.THEME.empty, mode)
+          : // No ultracode or ultrathink styling here: those describe how this
+            // Claude is running and have nothing to do with the other agent.
+            bars.bar(row.percentLeft, codexWidth, { mode, level: row.level, ascii, tick, reduced })) +
+          ' ' +
+          percent
+      );
+      const sub = codexSubline(row, mode, { now, clock });
+      if (sub) lines.push(sub);
+    }
+    const tail = [];
+    if (block.plan) tail.push(block.plan);
+    if (block.note) tail.push(block.note);
+    else if (Number.isFinite(block.ageMs)) tail.push('reading from ' + since(block.ageMs) + ' ago');
+    if (tail.length) lines.push(bars.dim(tail.join(' · '), mode));
+    body.push({ lines });
+  }
+
   // The other Claudes. One row each: what it runs, where, and whether it is
   // working right now, with its own spinner when it is.
   const list = Array.isArray(built.sessionsList) ? built.sessionsList : [];
@@ -796,6 +960,7 @@ async function main(argv) {
 }
 
 module.exports = {
+  codexSessions,
   HELP,
   TITLE,
   MIN_COLUMNS,

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

@@ -22,6 +22,7 @@ const fs = require('fs');
 const path = require('path');
 
 const usage = require('./usage.js');
+const reading = require('./reading.js');
 const brief = require('./brief.js');
 const host = require('./host.js');
 const activity = require('./activity.js');
@@ -30,8 +31,15 @@ const live = require('./live.js');
 const SECOND = 1000;
 const DEFAULT_INTERVAL_SECONDS = 120;
 
+// Same reasoning as the brief: ten seconds for the hook, four for a live
+// reading, five for the scan, one of slack. This hook interrupts work in
+// progress, so being late is worse here than anywhere else.
+const SCAN_BUDGET_MS = 5000;
+
 // One slot per session, same shape and same trimming as the brief's cache.
-const KEEP_SESSIONS = 8;
+// Two keys per session now - the spoken pulse and the quiet subagent refresh -
+// so this is double what it was.
+const KEEP_SESSIONS = 16;
 
 function stateFile() {
   const dir = usage.isCodex()
@@ -58,14 +66,10 @@ function readState() {
 }
 
 function writeState(all) {
-  try {
-    const file = stateFile();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(all), 'utf8');
-  } catch (err) {
-    // Losing the throttle means one extra scan, which is survivable. Failing
-    // the tool call it runs after is not.
-  }
+  // Never throws. Losing the throttle means one extra scan, which is
+  // survivable; failing the tool call it runs after is not. Atomic because
+  // several sessions' tool calls land on this file within the same second.
+  usage.writeJsonAtomic(stateFile(), all);
 }
 
 function trim(all, sessionId, at) {
@@ -97,7 +101,18 @@ function pulseText(parts) {
   if (parts.sessions > 1) bits.push(parts.sessions + ' sessions sharing it');
   if (!bits.length) return '';
 
-  const head = '[usage-limits] ' + bits.join(', ') + '.';
+  const head = '[usage-limits] ' + (parts.fanout ? 'Before this fan-out: ' : '') + bits.join(', ') + '.';
+  if (parts.fanout) {
+    // Said before every Workflow or Agent call. The agents spend this same
+    // window, nothing can speak again until they stop, and a main-loop turn
+    // with a large context costs more than one whole fresh-context agent.
+    return (
+      head + ' Subagents spend this window too and nothing can warn you until they ' +
+      'stop, so size the fan-out to what is left' +
+      (parts.pressure === 'gone' ? ' - which is nothing: do not launch it' : parts.pressure === 'tight' ? ' - a handful, not dozens' : '') +
+      '. Fewer agents with a fresh context beat another turn of a long one.'
+    );
+  }
   if (parts.pressure === 'gone') {
     return head + ' The budget is gone. Stop adding work, save what exists and write the handoff.';
   }
@@ -118,18 +133,49 @@ async function run(now, hookInput) {
   usage.setHost(host.detect(process.argv.slice(2), process.env));
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
-  // A tool call just finished, so the turn is still running. A few bytes, so
-  // the panel beside the chat keeps animating through a long turn.
-  activity.mark('working', sessionId, null, now);
+  const event = hookInput && hookInput.hook_event_name ? String(hookInput.hook_event_name) : 'PostToolUse';
+
+  // A subagent finishing is the other reason to look, and on a busy afternoon
+  // it is the more important one.
+  //
+  // This hook exists because PostToolUse fires on the MAIN thread's tool calls,
+  // and a turn that hands its work to a workflow makes none for half an hour.
+  // On 2026-09-06 two workflows spent a whole five-hour window between one
+  // prompt and the next, and nothing ran in between to notice: the reading on
+  // disk aged eleven minutes while forty-three agents spent against it, and the
+  // session was cut off at a figure the plugin still believed was 3%.
+  //
+  // So it refreshes and says nothing. The mark is deliberately not written -
+  // a subagent is not a session, and marking one would put it in the list of
+  // windows sharing this budget and split the headroom with a ghost.
+  const quiet = event === 'SubagentStop';
+  // The call about to fan out. Everything it spawns spends this window with no
+  // main-thread tool call to pulse on, so this is the last word before the
+  // bill. On 2026-09-07 a 34-agent workflow took a five-hour window from 28%
+  // to 100% in sixteen minutes, and the session was cut off at a figure the
+  // pulse had last read as 24%.
+  const tool = hookInput && hookInput.tool_name ? String(hookInput.tool_name) : '';
+  const fanout = event === 'PreToolUse' && /^(Workflow|Agent|Task)$/.test(tool);
+  if (!quiet) {
+    // A tool call just finished, so the turn is still running. A few bytes, so
+    // the panel beside the chat keeps animating through a long turn.
+    activity.mark('working', sessionId, null, now);
+  }
 
   const all = readState();
   const every = intervalMs();
-  // The cheap path, and the one taken almost every time.
-  if (!due(all, sessionId, now, every)) return '';
+  // The quiet refresh keeps its own throttle. Sharing one with the spoken
+  // pulse would mean a workflow's subagents used up the interval and the tool
+  // call right after it, the first chance to actually tell Claude, said
+  // nothing because something had already "pulsed" two minutes ago.
+  const throttleKey = quiet ? (sessionId || '_') + '#subagent' : sessionId;
+  // The cheap path, and the one taken almost every time. A fan-out is never
+  // throttled: it is said every time, because every time it is about to cost.
+  if (!fanout && !due(all, throttleKey, now, every)) return '';
 
   // Claimed before the scan rather than after, so a slow scan cannot let a
   // second tool call start another one.
-  writeState(trim(all, sessionId, now));
+  writeState(trim(all, throttleKey, now));
 
   // A reading as old as the interval is replaced with the one Claude Code
   // would take for /usage, so a turn that runs for an hour is measured
@@ -151,9 +197,16 @@ async function run(now, hookInput) {
     // The reading on disk is still there.
   }
 
-  const data = await usage.report(now, { sessionId });
+  // Refreshing was the whole errand. The next prompt, or the next tool call on
+  // the main thread, reports the number this just brought up to date.
+  if (quiet) return '';
+
+  const data = await usage.report(now, { sessionId, budgetMs: SCAN_BUDGET_MS });
   const binding = data.binding;
   if (!binding) return '';
+  // This turn paid for the scan, so leave the corrected figure where the
+  // status line and --status can read it without paying for one.
+  reading.recordAll(data.windows || [binding], now, usage.isCodex() ? require('./codex.js').homeDir() : null);
 
   // The same count and the same split as the brief, so the two lines never
   // disagree about how many sessions there are or how much of the budget is
@@ -171,7 +224,7 @@ async function run(now, hookInput) {
 
   // Quiet when there is nothing to act on. A line every two minutes saying the
   // budget is fine is noise that costs the budget it is reporting on.
-  if (pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
+  if (!fanout && pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
     return '';
   }
 
@@ -186,15 +239,18 @@ async function run(now, hookInput) {
         : null,
     sessions: active,
     pressure,
+    fanout,
   });
 }
 
 // PostToolUse does not take plain stdout as context the way UserPromptSubmit
 // does, so the line is returned in the documented envelope instead.
-function envelope(text) {
+function envelope(text, event) {
+  // PreToolUse and PostToolUse both take additionalContext, each under its own
+  // event name; the wrong name is dropped without a word.
   return JSON.stringify({
     hookSpecificOutput: {
-      hookEventName: 'PostToolUse',
+      hookEventName: event === 'PreToolUse' ? 'PreToolUse' : 'PostToolUse',
       additionalContext: text,
     },
   });
@@ -226,11 +282,15 @@ function readHookInput() {
 }
 
 if (require.main === module) {
+  let hookEvent = null;
   readHookInput()
-    .then((input) => run(Date.now(), input))
+    .then((input) => {
+      hookEvent = input && input.hook_event_name ? String(input.hook_event_name) : null;
+      return run(Date.now(), input);
+    })
     .then(
       (text) => {
-        if (text) process.stdout.write(envelope(text) + '\n');
+        if (text) process.stdout.write(envelope(text, hookEvent) + '\n');
         process.exit(0);
       },
       () => {

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

@@ -0,0 +1,121 @@
+'use strict';
+
+// The freshest corrected percentage, left where the cheap readers can find it.
+//
+// There are two ways to know how much of a window is gone. The snapshot is what
+// the account last told us, and it is free to read. The correction is the spend
+// measured out of the transcripts since that snapshot was taken, and it costs a
+// scan of up to several seconds - far too much for something that redraws under
+// the prompt on every keystroke.
+//
+// So the fast readers used the snapshot alone, and during a heavy session that
+// is not a small error. Measured on a real session: the snapshot said 13 per
+// cent while the same codebase, given a scan, said 73. The status line is the
+// number a person actually looks at, and it was sixty points wrong, in the
+// flattering direction, for twenty minutes.
+//
+// The fix is not to make the cheap path expensive. It is to notice that
+// something already paid for the scan - the prompt hook before every turn, the
+// pulse hook during long ones - and to have it leave the answer here. One small
+// file, one object per window key, and the readers prefer it whenever it is
+// fresher than the snapshot it would otherwise trust.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Older than this and the spend it measured is history: turns have happened
+// since, and a stale correction that says 40 per cent is worse than an honest
+// snapshot that says 13, because it looks authoritative.
+const FRESH_MS = 8 * 60 * 1000;
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function readingFile(codexHome) {
+  return path.join(codexHome || configDir(), 'usage-limits-reading.json');
+}
+
+function read(codexHome) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(readingFile(codexHome), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch (err) {
+    return {};
+  }
+}
+
+// Every window that has a correction, not just the binding one.
+//
+// The status line prints all three, and only one of them can be binding. So
+// recording the binding window alone left the other two showing their raw
+// snapshots - which is the same bug, on two thirds of the line.
+function recordAll(windows, now, codexHome) {
+  let written = 0;
+  for (const window of Array.isArray(windows) ? windows : [windows]) {
+    if (record(window, now, codexHome)) written += 1;
+  }
+  return written;
+}
+
+// Never throws. This is written from inside hooks, and a hook that fails over a
+// cache file would be worse than the stale number it was trying to fix.
+function record(binding, now, codexHome) {
+  if (!binding || !binding.key) return false;
+  if (binding.percentUsed === null || binding.percentUsed === undefined) return false;
+  // A rebuilt or unreliable figure is not an improvement on the snapshot; it is
+  // a different kind of guess. Only a correction the report itself trusts is
+  // worth putting in front of the cheap readers.
+  if (binding.stale || binding.estimated || binding.correctionUnreliable) return false;
+  try {
+    const all = read(codexHome);
+    all[binding.key] = {
+      at: Number.isFinite(now) ? now : Date.now(),
+      percentUsed: binding.percentUsed,
+      pointsSinceSnapshot: binding.pointsSinceSnapshot || 0,
+      adjusted: Boolean(binding.adjusted),
+      resetsAt: Number.isFinite(binding.resetsAt) ? binding.resetsAt : null,
+      turnsLeft: Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
+    };
+    // One entry per window key, and there are only ever a handful of those, so
+    // this file cannot grow. Anything whose reset has passed describes a window
+    // that no longer exists.
+    const at = Number.isFinite(now) ? now : Date.now();
+    for (const key of Object.keys(all)) {
+      const entry = all[key];
+      if (!entry || !Number.isFinite(entry.at) || at - entry.at > 24 * 60 * 60 * 1000) delete all[key];
+      else if (Number.isFinite(entry.resetsAt) && entry.resetsAt <= at) delete all[key];
+    }
+    fs.mkdirSync(path.dirname(readingFile(codexHome)), { recursive: true });
+    fs.writeFileSync(readingFile(codexHome), JSON.stringify(all));
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// The corrected percentage for one window, or null when there is nothing better
+// than the snapshot. `snapshotAt` is when the snapshot being compared against
+// was fetched: a correction measured before it is already included in it, and
+// applying it again would double-count the same spend.
+function correctedFor(key, now, snapshotAt, codexHome) {
+  const entry = read(codexHome)[key];
+  if (!entry || !Number.isFinite(entry.at)) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  if (at - entry.at > FRESH_MS) return null;
+  if (Number.isFinite(snapshotAt) && entry.at < snapshotAt) return null;
+  if (Number.isFinite(entry.resetsAt) && entry.resetsAt <= at) return null;
+  return entry;
+}
+
+function clear(codexHome) {
+  try {
+    fs.unlinkSync(readingFile(codexHome));
+  } catch (err) {
+    // Already gone is the outcome that was asked for.
+  }
+}
+
+module.exports = { FRESH_MS, configDir, readingFile, read, record, recordAll, correctedFor, clear };

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

@@ -19,7 +19,7 @@
 // judgement in it costs more in rework than it saves; the ladder loses height
 // a step at a time and 'critical' is the only posture that goes straight to
 // the floor.
-const NEXT_LOWER = { max: 'high', xhigh: 'medium', high: 'medium', medium: 'low', low: 'low' };
+const NEXT_LOWER = { ultra: 'xhigh', none: 'none', minimal: 'minimal', max: 'high', xhigh: 'medium', high: 'medium', medium: 'low', low: 'low' };
 
 // Below this share of output, reasoning is not where the money is going, and
 // turning effort down would trade quality for a saving that is not there.
@@ -187,7 +187,7 @@ function decide(inputs) {
       'reasoning is only ' + Math.round(share * 100) +
       '% of output, so effort is not where the money is going';
   } else {
-    const target = base.posture === 'critical' ? 'low' : NEXT_LOWER[effortNow] || 'medium';
+    const target = base.posture === 'critical' ? (['none', 'minimal'].includes(effortNow) ? effortNow : 'low') : NEXT_LOWER[effortNow] || 'medium';
     if (target !== effortNow) {
       base.effort.target = target;
       base.effort.changes = true;
@@ -200,6 +200,19 @@ function decide(inputs) {
     }
   }
 
+  if (inputs.codex) {
+    // Claude's family ladder and slash commands do not describe Codex.
+    base.model.why = 'Keep the current Codex model; select another supported model in the host controls when needed.';
+    if (base.effort.changes) {
+      base.apply.now = 'use the Codex model and effort controls and select ' + base.effort.target;
+      base.apply.next = 'node scripts/lowpower.js on --host codex --effort ' + base.effort.target;
+    }
+    base.notes.push('Saved defaults affect new sessions, not the running task. Profiles and CLI overrides take precedence.');
+    if (Number.isFinite(inputs.sessions) && inputs.sessions > 1)
+      base.notes.push(inputs.sessions + ' sessions share this account budget.');
+    return base;
+  }
+
   // The main model is only worth flipping when things are critical, and even
   // then it lands in settings.json for the next session: switching the running
   // session's model mid-task invalidates the prompt cache, so the change
@@ -321,7 +334,7 @@ function renderRecommend(data, turns) {
     lines.push('            new sessions: ' + decision.apply.next);
   }
   lines.push('  Model     ' + decision.model.why);
-  lines.push('            ' + decision.apply.delegate);
+  if (decision.apply.delegate) lines.push('            ' + decision.apply.delegate);
   if (decision.model.nextSession) {
     lines.push('            new sessions: main model to ' + decision.model.nextSession + ' until the window resets');
   }