claude-usage-limits 1.26.0 → 1.39.2

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

@@ -22,6 +22,7 @@ const relay = require('./relay.js');
 const reading = require('./reading.js');
 const voice = require('./voice.js');
 const mode = require('./mode.js');
+const feed = require('./feed.js');
 
 const SECOND = 1000;
 const DAY = 24 * 60 * 60 * 1000;
@@ -107,6 +108,169 @@ function cacheFile() {
   return path.join(dir, 'usage-limits-brief.json');
 }
 
+// The same brief seconds apart is what a burst of task notifications makes:
+// each one arrives as a prompt and each one got the whole line - ten copies in
+// a row on 2026-09-20. Nothing has moved in ninety seconds, so the second copy
+// carries nothing and is not said. Only the hook path uses this; run() still
+// returns the text. USAGE_LIMITS_BRIEF_REPEAT=1 turns it off.
+const REPEAT_MS = 90 * 1000;
+function saidFile() {
+  return path.join(path.dirname(cacheFile()), 'usage-limits-brief-said.json');
+}
+function shapeOf(text) {
+  return String(text || '').replace(/\d+/g, '#');
+}
+// The said file holds three kinds of memo, told apart by key: the plain
+// session key is the ninety-second shape, and the two suffixed keys below
+// are per-session facts that have to outlive an hour's silence.
+function readSaid() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(saidFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    return {};
+  }
+}
+function keepSaidFor(key) {
+  return /#(standing|cachemiss|stale|relaylast)$/.test(key) ? 24 * 60 * 60 * 1000 : 60 * 60 * 1000;
+}
+
+// A plugin update takes effect when Claude Code restarts, so a session that
+// began before one keeps running the old code for as long as it lives. On
+// 2026-09-20 that put a session on 1.34.1 beside one on 1.36.0: the older one
+// saw the single relay slot its version still had, judged it taken, wrote its
+// own scheduled task by hand, and that task failed the way 1.34.1's always
+// did, while the newer session's relay worked. Nothing in the plugin can
+// upgrade a running session, but it can say so, once, with the two numbers.
+function installedVersion(configDir) {
+  try {
+    const file = path.join(configDir, 'plugins', 'installed_plugins.json');
+    const rows = JSON.parse(fs.readFileSync(file, 'utf8')).plugins['usage-limits@usage-limits'];
+    if (!Array.isArray(rows) || !rows.length) return null;
+    const user = rows.find((r) => r && r.scope === 'user') || rows[rows.length - 1];
+    return user && typeof user.version === 'string' ? user.version : null;
+  } catch (err) {
+    return null;
+  }
+}
+function runningVersion() {
+  try {
+    return require('../../../package.json').version;
+  } catch (err) {
+    return null;
+  }
+}
+function staleVersionFor(sessionId, now, dir) {
+  const installed = installedVersion(dir || configDir());
+  const running = runningVersion();
+  if (!installed || !running || installed === running) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  const key = String(sessionId || '_') + '#stale';
+  const all = readSaid();
+  const entry = all[key];
+  if (entry && Number.isFinite(entry.at) && at - entry.at < keepSaidFor(key) && entry.seen === installed) return null;
+  all[key] = { at, seen: installed };
+  writeSaid(all, at);
+  return 'usage-limits ' + installed + ' is installed but this session still runs ' + running +
+    ', because a plugin update applies at the next start; a relay or cap set here follows the older rules until then.';
+}
+// How the last relay ended is news once. It used to ride along for six hours
+// after any relay ended, on every prompt of every session: on 2026-09-22 a wake
+// lost at 5:53 AM was repeated in two sessions' briefs all afternoon, about
+// work neither of them was doing. Each session now hears about a given ended
+// relay once, keyed on when it ended and how.
+function relayNewsFor(sessionId, last, now) {
+  if (!last) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  const key = String(sessionId || '_') + '#relaylast';
+  const seen = String(last.endedAt) + ':' + String(last.outcome);
+  const all = readSaid();
+  const entry = all[key];
+  if (entry && entry.seen === seen && Number.isFinite(entry.at) && at - entry.at < keepSaidFor(key)) return null;
+  all[key] = { at, seen };
+  writeSaid(all, at);
+  return last;
+}
+function writeSaid(all, at) {
+  const next = {};
+  for (const [k, v] of Object.entries(all)) if (v && Number.isFinite(v.at) && at - v.at < keepSaidFor(k)) next[k] = v;
+  try {
+    usage.writeJsonAtomic(saidFile(), next);
+  } catch (err) {
+  }
+}
+function sayOnce(sessionId, text, now) {
+  if (!text || process.env.USAGE_LIMITS_BRIEF_REPEAT === '1') return text;
+  const at = Number.isFinite(now) ? now : Date.now();
+  const key = String(sessionId || '_');
+  const shape = shapeOf(text);
+  const all = readSaid();
+  const last = all[key];
+  if (last && Number.isFinite(last.at) && at - last.at < REPEAT_MS && last.shape === shape) return '';
+  all[key] = { at, shape };
+  writeSaid(all, at);
+  return text;
+}
+
+// The standing instruction - open with the fit line, quote the binding
+// window, close finished work with the total - reads the same on every prompt,
+// and at 93 words it was the largest fixed cost in the line. It is said in
+// full once per session and as twelve words after that. A session that has
+// heard it has heard it; USAGE_LIMITS_BRIEF_FULL=1 says the full form every
+// time for anyone who wants that.
+const STANDING_SHORT = 'Open with the fit line; close finished work with the session total.';
+function standingSaid(sessionId, now) {
+  const entry = readSaid()[String(sessionId || '_') + '#standing'];
+  return Boolean(entry && Number.isFinite(entry.at) && (Number.isFinite(now) ? now : Date.now()) - entry.at < keepSaidFor('#standing'));
+}
+function markStanding(sessionId, now) {
+  const at = Number.isFinite(now) ? now : Date.now();
+  const all = readSaid();
+  all[String(sessionId || '_') + '#standing'] = { at };
+  writeSaid(all, at);
+}
+function standingShortFor(sessionId, now, env) {
+  if ((env || process.env).USAGE_LIMITS_BRIEF_FULL === '1') return false;
+  return standingSaid(sessionId, now);
+}
+
+// The prompt right after a cache miss the user can do something about.
+//
+// The status line JSON carries prompt_cache.last_miss_at (epoch seconds) and
+// last_miss_cause.causes (Claude Code 2.1.260 and later; documented values
+// tools_changed, system_prompt_changed, ttl_expired_5m, likely_server_side),
+// and feed.js keeps the last one in this session's feed slot. Only the two
+// causes a person can act on are named: a TTL expiry is time passing and a
+// server-side miss is nobody's. It is said on the first brief after the miss
+// and not again for that miss, and never for a miss older than half an hour,
+// because "right after" is the whole point.
+const MISS_RECENT_MS = 30 * 60 * 1000;
+function missReason(causes) {
+  const set = new Set(Array.isArray(causes) ? causes : []);
+  if (set.has('system_prompt_changed')) return 'the system prompt changed';
+  if (set.has('tools_changed')) return 'the tool list changed';
+  return null;
+}
+function cacheMissWhyFor(sessionId, now) {
+  if (!sessionId) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  let miss = null;
+  try {
+    const slot = feed.readFeed()[sessionId];
+    miss = slot && slot.cacheMiss;
+  } catch (err) {
+    return null;
+  }
+  if (!miss || !Number.isFinite(miss.at) || at - miss.at > MISS_RECENT_MS) return null;
+  const why = missReason(miss.causes);
+  if (!why) return null;
+  const all = readSaid();
+  const key = String(sessionId) + '#cachemiss';
+  if (all[key] && all[key].at === miss.at) return null;
+  all[key] = { at: miss.at };
+  writeSaid(all, at);
+  return why;
+}
 // One slot per session. A single shared slot meant that alternating between
 // two Claude Code windows invalidated the cache on every prompt, so neither
 // ever got a hit and both paid for a full scan each time.
@@ -310,6 +474,8 @@ const CACHED_BINDING_FIELDS = [
   'pointsSinceSnapshot',
   'correctionUnreliable',
   'pointsBeyondSnapshot',
+  // Both account readings, when there are two, so the line can name them.
+  'sources',
   'resetsAt',
   'verdict',
   'windowStart',
@@ -419,7 +585,20 @@ function describeWindow(window) {
   // in hand, and the reply that follows sizes the work down for a limit not one
   // turn here can move.
   const idle = window.applies === false ? " (not this session's model)" : '';
-  return window.label + about + window.percentUsed + '%' + idle;
+  // Two account readings that disagree are named, not averaged and not
+  // silently picked between. On 2026-09-20 one window read 14, 30 and 20 per
+  // cent within three minutes as Claude Code's cache and the plugin's own
+  // live reading took turns being the newer; a reader who sees one number
+  // cannot tell that from the budget moving. Five points is the line: under
+  // that the two are the same reading at different moments.
+  const s = window.sources;
+  const split =
+    s && Number.isFinite(s.cache) && Number.isFinite(s.live) && Math.abs(s.cache - s.live) > 5
+      ? s.used === 'live'
+        ? " (the live reading; Claude Code's cache says " + s.cache + '%)'
+        : " (Claude Code's cache; the live reading says " + s.live + '%)'
+      : '';
+  return window.label + about + window.percentUsed + '%' + split + idle;
 }
 
 // Everything except the window that will actually stop the work.
@@ -491,6 +670,9 @@ function briefText(input) {
   const bounds = (input.mode && input.mode.bounds) || null;
   const pinned = Boolean(bounds && bounds.pin);
   const parts = applyBounds(input, bounds);
+  // The short standing form only where the three standing strings would
+  // otherwise appear: the tight and gone instructions are their own words.
+  const shortStanding = parts.standingShort === true && parts.pressure !== 'tight' && parts.pressure !== 'gone';
 
   // The turns and the reset time belong to one specific window. Listing every
   // window and then the numbers invites reading them against the wrong one, so
@@ -529,10 +711,26 @@ function briefText(input) {
   // first character; anywhere else the reader is owed the reason the line
   // looks different from the one they are used to.
   const token = parts.mode && parts.mode.name !== 'standard' ? '(' + (parts.mode.label || parts.mode.name) + ') ' : '';
+  // Fast mode changes what the figures above mean, so it is said in the same
+  // sentence. Per the Claude Code docs (code.claude.com/docs/en/fast-mode and
+  // /prompt-caching): on a subscription it is billed from usage credits and
+  // "not included in the subscription rate limits", so the window's turns are
+  // not what it spends; and the first request sent with it on "reads the
+  // entire conversation history with no cache hits", once per conversation.
+  // Only while the status line has said it is on; nothing is assumed.
+  const fast = parts.fastMode
+    ? '; fast mode on, billed from usage credits rather than this window, and its first turn re-reads the whole context uncached'
+    : '';
+  // One clause, on the prompt right after a cache miss the user caused, and
+  // nothing otherwise. The cause comes from the status line's prompt_cache
+  // object through feed.js; see cacheMissWhyFor.
+  const missed = parts.cacheMissWhy
+    ? '; the prompt cache missed on the last call because ' + parts.cacheMissWhy + ', so that call re-read the whole context'
+    : '';
   sentences.push(
     bound.length
-      ? '[usage-limits] ' + token + 'binding window is ' + bound.join(', ') + '.'
-      : '[usage-limits] ' + token + 'no usable window reading.'
+      ? '[usage-limits] ' + token + 'binding window is ' + bound.join(', ') + fast + missed + '.'
+      : '[usage-limits] ' + token + 'no usable window reading' + fast + missed + '.'
   );
   // What tier is producing this turn.
   //
@@ -543,6 +741,8 @@ function briefText(input) {
   // well as what it is, because the source is the whole point: settings.json
   // said xhigh for an entire session that was running something else.
   if (parts.tier) sentences.push(parts.tier);
+  // Once per session, and only when the installed version is not this one.
+  if (parts.staleVersion) sentences.push(parts.staleVersion);
   const bounded = mode.boundsNote(bounds);
   if (bounded) sentences.push(bounded);
   if (parts.planChanged) {
@@ -594,11 +794,14 @@ function briefText(input) {
     // A correction is a measurement of local transcripts priced by a learned
     // rate. It is a good adjustment to a recent snapshot and a bad substitute
     // for an old one, because the pricing error compounds with every point it
-    // has to bridge. So an old snapshot makes the figure a floor, whether or
-    // not it has overrun anything, and that is said rather than assumed.
+    // has to bridge. The figure here is snapshot plus correction: a point
+    // estimate that can land on either side of the account - on 2026-09-20 it
+    // ran 13 to 17 points HIGH - so it is called an estimate. "Floor" is kept
+    // for the branch above, where the correction is refused and the raw
+    // snapshot is all that is shown, which really is a lower bound.
     sentences.push(
-      'Treat that percentage as a floor rather than a reading: the account snapshot ' +
-        'behind it is ' + parts.snapshotAge + ' old, so most of the figure is measured ' +
+      'Treat that percentage as an estimate rather than a reading, high or low: the account ' +
+        'snapshot behind it is ' + parts.snapshotAge + ' old, so most of the figure is measured ' +
         'from local history at a learned price rather than read from the account, and ' +
         'that gap widens the longer the snapshot stands. Run /usage to refresh it before ' +
         'making a decision that depends on the exact number.'
@@ -930,34 +1133,30 @@ function briefText(input) {
           'read. Say in one line what will land after the reset instead of ' +
           'before it, then keep working until the window actually ends.'
       : parts.pressure === 'tight'
-        ? 'The budget is nearly gone, so make being cut off cheap rather than ' +
-          'doing less. Carry on with the whole request at full quality: this is ' +
-          'not a reason to narrow the work, drop parts of it, or stop to ask ' +
-          'whether to go on. Order it so the most valuable part lands first, ' +
-          'save at clean boundaries as you go, and keep a short running note of ' +
-          'what is done, what is next, and which files are mid-change, so that ' +
-          'stopping at any moment loses nothing. Say in one line what may not ' +
-          'land before the reset, then keep working. If part of what remains is ' +
-          'mechanical, node scripts/usage.js --recommend (from the skill directory) ' +
-          'names the effort and model it should run at.'
-        : 'Open your reply with one short line stating this and confirming the ' +
-          'request fits, then get on with the work. Keep it to a single line. ' +
-          'There is room, so use it: work at full quality, take on the whole ' +
-          'request, and do not hold budget back or economise, as anything left ' +
-          'unspent is lost at the reset rather than saved.';
+        ? 'The budget is nearly gone, so make being cut off cheap rather than doing ' +
+          'less. Carry on with the whole request at full quality; do not narrow ' +
+          'it or stop to ask. The most valuable part lands first, save at clean ' +
+          'boundaries, with a running note of what is done, what is next and ' +
+          'which files are mid-change. Say in one line what may not land before ' +
+          'the reset, then keep working; for a mechanical remainder, node ' +
+          'scripts/usage.js --recommend (skill directory) names the effort and model.'
+        : shortStanding
+          ? STANDING_SHORT
+          : 'Open with one short line stating this and that the request fits, then ' +
+            'get on with the work. There is room: full quality, the whole request, nothing held ' +
+            'back, since unspent budget is lost at the reset.';
 
   // The mistake this guards against: quoting the roomiest window and pinning
   // the binding window figures to it.
-  const care =
-    ' Quote the binding window, not whichever one has the most left. The turns ' +
-    'and reset time above belong to the binding window alone; do not read them ' +
-    'against another window percentage.';
+  const care = shortStanding
+    ? ''
+    : ' Quote the binding window; its turns and reset time belong to it alone.';
 
   // Finished work closes with what it cost. Not every reply: a progress note
   // mid-task is not the moment, and once the budget is gone nothing further
   // runs, so there is no reply to close.
   const closing =
-    parts.pressure === 'gone'
+    parts.pressure === 'gone' || shortStanding
       ? ''
       : ' When this reply completes what was asked, or wraps up the session, end it ' +
         'with one plain line giving the session total above (turns, tokens and cost). ' +
@@ -1096,15 +1295,18 @@ function tallyContext(all, sessionId, now) {
 // about.
 function relayState(now, hookInput, binding, sessionId) {
   try {
-    const state = relay.read();
+    const state = (relay.reapLost(Date.now()), relay.read());
     const config = relay.settings(state);
     const last = state.history[state.history.length - 1];
-    const recent = last && Number.isFinite(last.endedAt) && now - last.endedAt < 6 * 60 * 60 * 1000 ? last : null;
+    const ended = last && Number.isFinite(last.endedAt) && now - last.endedAt < 6 * 60 * 60 * 1000 ? last : null;
+    // Said once per session per ended relay, not on every prompt for six hours.
+    const recent = ended ? relayNewsFor(sessionId, ended, now) : null;
     if (!config.enabled) return recent ? { enabled: false, last: recent } : null;
 
     // Already armed for this session: nothing to decide, just say so.
-    if (state.armed && state.armed.id === sessionId) {
-      return { enabled: true, armed: state.armed, config, last: recent };
+    const mine = relay.armedFor(state, sessionId);
+    if (mine) {
+      return { enabled: true, armed: mine, config, last: recent };
     }
     const work = relay.detectWork(hookInput && hookInput.transcript_path, {});
     const able = relay.armable({ config, binding, sessionId, work });
@@ -1195,6 +1397,20 @@ function guardLine(now, budget) {
   }
 }
 
+// Whether this session has fast mode on. No hook input carries it; the status
+// line JSON does, as `fast_mode`, and feed.js keeps that in this session's
+// feed slot. A session with no slot - no status line installed - reads as off,
+// so the clause is never said on a guess.
+function fastModeFor(sessionId) {
+  if (!sessionId) return false;
+  try {
+    const slot = feed.readFeed()[sessionId];
+    return Boolean(slot && slot.fastMode === true);
+  } catch (err) {
+    return false;
+  }
+}
+
 async function run(now, hookInput) {
   if (String(process.env.USAGE_LIMITS_BRIEF || '').toLowerCase() === 'off') return '';
 
@@ -1386,6 +1602,9 @@ async function run(now, hookInput) {
   if (offering) mode.adviceOffer(advice.id, sessionId, now);
 
   const pressureNow = pressure(binding, now, config, Number.isFinite(yourTurnsLeft) ? yourTurnsLeft : view.turnsLeft);
+  // Fast mode changes what the window's figures mean, so a toggle is a change
+  // worth saying even when nothing else has moved.
+  const fastMode = fastModeFor(sessionId);
 
   // Say nothing when nothing a decision depends on has moved.
   //
@@ -1402,6 +1621,7 @@ async function run(now, hookInput) {
     active > 1 ? 'shared' : 'solo',
     carry && carry.armed ? 'relay' : '-',
     offering ? 'advice' : '-',
+    fastMode ? 'fast' : '-',
   ].join('|');
   if (!budget.policy.briefWhenUnchanged && pressureNow === 'roomy') {
     const slots = readCache();
@@ -1410,9 +1630,15 @@ async function run(now, hookInput) {
     writeCache(mergeCache(slots, sessionId, Object.assign({}, slot || { at: now }, { said: digest }), KEEP_SESSIONS));
   }
 
-  return briefText({
+  // The standing text in full the first time, twelve words after. Decided
+  // here, and marked below only when the full form actually went out.
+  const standingShort = standingShortFor(sessionId, now);
+  const text = briefText({
     mode: budget,
     tier,
+    standingShort,
+    cacheMissWhy: cacheMissWhyFor(sessionId, now),
+    staleVersion: staleVersionFor(sessionId, now),
     adviceText: terse && offering ? advice.text : null,
     relay: carry,
     voiceNote,
@@ -1460,12 +1686,17 @@ async function run(now, hookInput) {
     pointsBeyondSnapshot: (binding && binding.pointsBeyondSnapshot) || 0,
     snapshotAge: view.snapshotAge,
     snapshotStale: Number.isFinite(view.snapshotAgeMs) && view.snapshotAgeMs >= SNAPSHOT_TRUST_MS,
+    fastMode,
     // The turn count that matters for this session is its share of a shared
     // budget, not the whole window's. Escalating on the whole window meant a
     // count that looked comfortable while the part actually available here was
     // a third of it.
     pressure: pressureNow,
   });
+  // Only the roomy form carries the three standing strings; the terse style
+  // drops them and the tight and gone instructions are their own words.
+  if (text && !standingShort && !terse && pressureNow !== 'tight' && pressureNow !== 'gone') markStanding(sessionId, now);
+  return text;
 }
 
 if (require.main === module) {
@@ -1476,18 +1707,18 @@ if (require.main === module) {
         (process.argv.includes('--host') && process.argv[process.argv.indexOf('--host') + 1] === 'gemini') ||
         process.argv.includes('--gemini-hook')
       );
-      const text = await run(Date.now(), input);
+      const text = sayOnce(input && input.session_id, await run(Date.now(), input), Date.now());
       return { text, isGeminiHook };
     })
     .then(
       ({ text, isGeminiHook }) => {
         if (isGeminiHook) {
           const payload = {
-            injectSteps: text ? [{ ephemeralMessage: text }] : []
+            injectSteps: text ? [{ ephemeralMessage: withBugcheck(text) }] : []
           };
           process.stdout.write(JSON.stringify(payload) + '\n');
         } else {
-          if (text) process.stdout.write(text + '\n');
+          if (text) process.stdout.write(withBugcheck(text) + '\n');
         }
         process.exit(0);
       },
@@ -1498,7 +1729,20 @@ if (require.main === module) {
     );
 }
 
-module.exports = {
+// relay bugcheck always: the two passes the user asks for on nearly every
+// request, asked for on every prompt. on and off touch the hand-off only.
+function withBugcheck(text) {
+  try {
+    const relayModule = require('./relay.js');
+    if (relayModule.settings(relayModule.read()).bugcheck === 'always') return text + ' ' + relayModule.BUGCHECK_LINE;
+  } catch (err) {
+    // The relay module is optional here.
+  }
+  return text;
+}
+
+module.exports = { withBugcheck, sayOnce, shapeOf, saidFile, REPEAT_MS, staleVersionFor, relayNewsFor, installedVersion, runningVersion,
+  readSaid, standingSaid, markStanding, standingShortFor, STANDING_SHORT, cacheMissWhyFor, missReason, MISS_RECENT_MS,
   DEFAULTS,
   aheadOfPace,
   pacingMatters,
@@ -1514,6 +1758,7 @@ module.exports = {
   LARGE_CONTEXT_TOKENS,
   SNAPSHOT_TRUST_MS,
   settings,
+  fastModeFor,
   keepSlots,
   pickCached,
   mergeCache,

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

@@ -92,28 +92,57 @@ function ceilingFrom(state, env, sessionId) {
     // A ceiling that cannot be read is not a ceiling of zero. Fall through to
     // the file rather than enforcing a number nobody typed.
   }
+  // A STANDING cap applies to every session on this machine, including ones
+  // that start after a limit reset. It is the answer to "keep 60 per cent for
+  // next session too": a session-owned cap deliberately lapses, so something
+  // that outlives a session has to be stored as its own thing rather than by
+  // weakening the ownership rule.
+  const always =
+    state && Number.isFinite(state.ceilingAlways) && state.ceilingAlways > 0 && state.ceilingAlways <= 100
+      ? state.ceilingAlways
+      : null;
+  const standing = always === null ? null : { percent: always, source: 'the standing cap' };
   const stored = state && Number.isFinite(state.ceilingPercent) ? state.ceilingPercent : null;
-  if (stored === null || stored <= 0 || stored > 100) return { percent: null, source: null };
+  if (stored === null || stored <= 0 || stored > 100) return standing || { percent: null, source: null };
   const owner = state && state.ceilingSession ? String(state.ceilingSession) : null;
   if (!owner) {
     // Set before caps were session-scoped. Not this session's instruction.
-    return { percent: null, source: null, staleCap: stored };
+    return standing || { percent: null, source: null, staleCap: stored };
   }
   if (!sessionId || String(sessionId) !== owner) {
-    return { percent: null, source: null, otherSessionCap: stored };
+    return standing || { percent: null, source: null, otherSessionCap: stored };
   }
   return { percent: stored, source: 'this session' };
 }
 
-// Where the binding window stands against the ceiling.
+// The window a ceiling is judged against: the fullest one this agent can spend
+// into.
 //
-// `percent` is the BINDING window's, not the emptiest one's. A ceiling read
-// against whichever window has the most left would never bind at all, which is
-// the same mistake the brief was corrected for.
+// Not the emptiest - a ceiling read against whichever window has the most left
+// would never bind. And not simply the fullest either: a weekly scoped to one
+// model is only this agent's limit while that model runs. On 2026-09-22 the
+// Fable weekly at 89 per cent refused an Opus session's fan-out and the refusal
+// called it "the binding window", while the brief beside it said 5-hour 15.
+// `windows` is usage.snapshotWindows(), which already carries `applies` and
+// `stale`; a window whose reset has passed describes a window that is over.
+function worstWindow(windows) {
+  let worst = null;
+  for (const window of Array.isArray(windows) ? windows : []) {
+    if (!window || window.applies === false || window.stale) continue;
+    if (!Number.isFinite(window.percentUsed)) continue;
+    if (!worst || window.percentUsed > worst.percent) {
+      worst = { percent: window.percentUsed, label: window.label || window.key || null };
+    }
+  }
+  return worst;
+}
+
+// Where that window stands against the ceiling.
 function assess(options) {
   const opts = options || {};
   const ceiling = ceilingFrom(opts.state, opts.env, opts.sessionId);
   const percent = Number.isFinite(opts.percent) ? opts.percent : null;
+  const label = opts.label ? String(opts.label) : null;
   if (ceiling.percent === null || percent === null) {
     return {
       set: ceiling.percent !== null,
@@ -123,6 +152,7 @@ function assess(options) {
       over: false,
       near: false,
       headroomPoints: null,
+      label,
       staleCap: ceiling.staleCap || null,
       otherSessionCap: ceiling.otherSessionCap || null,
     };
@@ -133,6 +163,7 @@ function assess(options) {
     source: ceiling.source,
     ceiling: ceiling.percent,
     percent,
+    label,
     over: percent >= ceiling.percent,
     near: headroomPoints > 0 && headroomPoints <= NEAR_POINTS,
     headroomPoints,
@@ -143,6 +174,12 @@ function round(value) {
   return Math.round(value * 10) / 10;
 }
 
+// Names the window the number belongs to. A caller that passed no label gets
+// the plain truth rather than a claim that it is the binding one.
+function which(state) {
+  return state && state.label ? 'the ' + state.label + ' window' : 'the fullest window';
+}
+
 // What to do about one tool call.
 //
 // Returns `allow` for everything the ceiling does not cover, which is almost
@@ -154,7 +191,7 @@ function verdict(state, tool) {
   return {
     decision: 'deny',
     reason:
-      'Usage ceiling reached: the binding window is ' +
+      'Usage ceiling reached: ' + which(state) + ' is ' +
       round(state.percent) +
       '% used and the ceiling is ' +
       state.ceiling +
@@ -174,7 +211,7 @@ function warning(state) {
   return (
     'Usage ceiling in ' +
     round(state.headroomPoints) +
-    ' points: the binding window is ' +
+    ' points: ' + which(state) + ' is ' +
     round(state.percent) +
     '% used against a ceiling of ' +
     state.ceiling +
@@ -206,6 +243,7 @@ module.exports = {
   NEAR_POINTS,
   isMultiplier,
   ceilingFrom,
+  worstWindow,
   assess,
   verdict,
   warning,

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

@@ -210,7 +210,7 @@ function plan(options) {
 
 function status(now) {
   const state = relay.read();
-  const armed = state.armed;
+  const armed = relay.armedFor(state, process.env.CLAUDE_CODE_SESSION_ID) || state.armed;
   if (!armed) return 'Nothing is deferred.';
   const when = Number(armed.wakeAt);
   const deferred = armed.deferred === true;
@@ -230,9 +230,10 @@ function status(now) {
 
 function cancel() {
   const state = relay.read();
-  if (!state.armed) return 'Nothing was deferred.';
-  const label = formatClock(Number(state.armed.wakeAt));
-  const result = relay.disarm('cancelled by hand', Date.now());
+  const own = relay.armedFor(state, process.env.CLAUDE_CODE_SESSION_ID) || state.armed;
+  if (!own) return 'Nothing was deferred.';
+  const label = formatClock(Number(own.wakeAt));
+  const result = relay.disarm('cancelled by hand', Date.now(), own.id);
   return result && result.ok === false
     ? 'Could not cancel: ' + result.error
     : 'Cancelled the run booked for ' + label + '.';
@@ -286,9 +287,10 @@ function main(argv, now) {
   // session can tell the two apart - they read the same record.
   try {
     const held = relay.read();
-    if (held.armed) {
-      held.armed.deferred = true;
-      held.armed.continuation = Boolean(work);
+    const mine = (typeof sessionId !== 'undefined' && relay.armedFor(held, sessionId)) || held.armed;
+    if (mine) {
+      mine.deferred = true;
+      mine.continuation = Boolean(work);
       relay.write(held);
     }
   } catch (err) {