claude-usage-limits 1.13.2 → 1.14.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.13.2",
+  "version": "1.14.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.13.2",
+  "version": "1.14.1",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/README.md

@@ -1010,3 +1010,33 @@ licence is there for. Do not wait on me to add something for you.
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+## The wall is not the end of the budget
+
+A full window is not always a reason to stop, and the plugin now says which.
+
+A **per-model weekly** counts turns by that model only. It is not your budget,
+it is that model's: lowering effort frees nothing, and switching model retires
+the window outright while every other window carries on. A **shared window**
+follows the account wherever the model goes, so a switch buys nothing and
+effort is the lever instead.
+
+Once the binding window is half gone the budget line names the lever that
+applies, which window would bind after the switch and how full it is, and the
+command:
+
+```
+This window is scoped to one model, so it is not the account's budget:
+switching model retires it. After a switch the binding window would be weekly
+at 77 per cent. Use /model opus.
+```
+
+At the wall it goes further and says outright that you are not out of budget
+and must not stop as though you were. It refuses to claim an escape it cannot
+evidence: trading an 89 for an 87 is a lateral move, not a way out, and with no
+other readable window there is nothing behind the claim, so it says nothing.
+
+This exists because of a real session. The Fable weekly hit 89 per cent, the
+line said the budget was nearly gone, and the work stopped - with the 5-hour
+window at 46 and every other model untouched. One command would have carried it
+on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.13.2",
+  "version": "1.14.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -370,7 +370,39 @@ effort setting does not control any of it:
 `references/tactics.md` has the full list and the billing reasons behind each
 one.
 
-## 5. Checkpoint before the wall
+## 5. The wall is not the end of the budget: switch, do not stop
+
+Before treating a full window as a reason to stop, check what kind of window it
+is. There are two, and only one of them is the account's budget.
+
+- **A per-model weekly** (`weekly (Fable)`, `weekly (Opus)`, `weekly (Sonnet)`)
+  counts turns by *that model only*. It is not your budget, it is that model's.
+  Lowering effort does not free a single point of it. **Switching model retires
+  it outright** - `/model opus`, `/model sonnet`, or
+  `node scripts/lowpower.js on --model <id>`. Every other window carries on
+  exactly as before.
+- **A shared window** (the 5-hour, the all-models weekly) follows the account
+  wherever the model goes, so a switch buys nothing. Here the lever is
+  **effort**: `/effort medium` measured six times cheaper a turn than ultra on
+  this account. `node scripts/usage.js --recommend` names both levers with the
+  commands.
+
+The budget line does this arithmetic for you. Once the binding window is half
+gone it says which lever applies, and at the wall it says outright that you are
+not out of budget and must not stop as though you were. When it does, the
+sequence is: switch, say in one line that you switched and why, carry on with
+the whole request at full quality.
+
+This is written down because it was got wrong. A session ended with the Fable
+weekly at 89 per cent and the line saying the budget was nearly gone - while the
+5-hour sat at 46 and every other model on the account was untouched. One command
+would have carried it on. Stopping there was not caution; it was quitting with a
+reason that sounded like one.
+
+Only when the switch is genuinely unavailable - no other window has room, or the
+user has ruled it out - does the checkpoint below apply.
+
+## 6. Checkpoint before the wall
 
 When the binding window is under roughly 10 percent, or under about ten turns
 of headroom, keep working and start keeping the work landable:
@@ -389,7 +421,7 @@ afternoon, so there is no longer anything to buy by winding down.
 The one thing not to economise on is the handoff itself. Everything else can be
 picked up next session; a session that ends without one cannot.
 
-## 6. The relay: when the handoff picks itself up
+## 7. The relay: when the handoff picks itself up
 
 If a relay is armed, the budget line says so, and the shape of the last hour
 changes. The handoff stops being a note for a person to find and becomes the

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

@@ -556,7 +556,12 @@ function briefText(parts) {
   // do more cheaply on this model frees it; only running a different model
   // does, and that has to be said, because the obvious move at 90 percent is
   // to drop the effort and keep going, which spends the same window slower.
-  if (parts.family) {
+  // Suppressed when the escape line below fires: that one says the same thing
+  // and names the model to switch to, where this one only ever managed
+  // "Use /model (or ...". Two sentences making one point is a cost paid on
+  // every prompt.
+  const namesTheSwitch = parts.escape && parts.escape.kind === 'model';
+  if (parts.family && !namesTheSwitch) {
     sentences.push(
       'That window counts ' + parts.family + ' turns only, so lowering effort does not free it: ' +
         'switching model does. Use /model (or scripts/lowpower.js on --model <other>) for work ' +
@@ -565,6 +570,26 @@ function briefText(parts) {
   }
   if (parts.othersSummary) sentences.push('Other windows: ' + parts.othersSummary + '.');
 
+  // Being at the wall and being out of budget are different things, and the
+  // difference is a command. Said as soon as the window is half gone, so it is
+  // already known by the time it matters.
+  const escape = parts.escape;
+  const escapeText =
+    escape && escape.kind === 'model'
+      ? 'This window is scoped to one model, so it is not the account\'s budget: switching model retires it. ' +
+        (escape.nextLabel
+          ? 'After a switch the binding window would be ' + escape.nextLabel + ' at ' + escape.nextPercent + ' per cent. '
+          : '') +
+        'Use /model ' + (escape.suggest || '<another model>') + ' (or scripts/lowpower.js on --model <id>).'
+      : escape && escape.kind === 'effort'
+        ? 'A model switch does not free this window - it follows the account - but effort does: ' +
+          escape.to + ' measured ' + (escape.multiple ? escape.multiple + 'x ' : '') + 'cheaper a turn than ' +
+          (escape.from || 'the current effort') + '. Use /effort ' + escape.to + '.'
+        : null;
+  if (escapeText && parts.binding && Number.isFinite(parts.binding.percentUsed) && parts.binding.percentUsed >= HALF_SPENT) {
+    sentences.push(escapeText);
+  }
+
   // A window that is not binding can still be the expensive one to exhaust.
   if (parts.critical && parts.critical.length) {
     for (const other of parts.critical) {
@@ -668,7 +693,18 @@ function briefText(parts) {
   // go, keep a note of where things stand - not to shrink the work until it is
   // guaranteed to fit.
   const instruction =
-    parts.pressure === 'gone'
+    // The escape outranks everything below it. A session that stops while a
+    // command would have carried it on has not been careful, it has quit - and
+    // that is a real session: the Fable weekly hit 89 per cent, the line said
+    // the budget was nearly gone, and the work ended with the five-hour window
+    // at 46 and every other model untouched.
+    escapeText && (parts.pressure === 'tight' || parts.pressure === 'gone')
+      ? 'This window is nearly gone, but you are not out of budget and you must ' +
+        'not stop as though you were. ' + escapeText + ' Do that, say in one ' +
+        'line that you switched and why, and carry on with the whole request at ' +
+        'full quality. Only if the switch is impossible or the user has ruled it ' +
+        'out: save the work, write the handoff, and say what is left.'
+      : parts.pressure === 'gone'
       ? 'The budget is gone, so nothing further will run. Save what exists and ' +
         'write the handoff: what is finished, what is next and in what order, ' +
         'which files are mid-change, and when the window resets.' +
@@ -917,6 +953,9 @@ async function run(now, hookInput) {
       turnsLeft: binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
       session: data.session,
       othersSummary: summariseOthers(data.windows, binding && binding.key),
+      // The way out that is not stopping. Cached with the rest of the view
+      // because it is derived from the same one pass over the windows.
+      escape: usage.escapeRoute(data.windows, binding, data.effortWarning || null),
       // Every window, trimmed to the cacheable fields, so the corrected reading
       // can be recorded for all three columns of the status line on a cache
       // hit too. Recording the binding window alone left the other two at
@@ -996,6 +1035,7 @@ async function run(now, hookInput) {
         ? familyLabel(binding.family)
         : null,
     othersSummary: view.othersSummary,
+    escape: view.escape || null,
     turnsLeft: view.turnsLeft,
     effortWarning: view.effortWarning || null,
     // Outside the cache: it is cheap, and it belongs to the other agent's

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

@@ -2091,6 +2091,64 @@ function criticalOthers(windows, bindingKey, threshold) {
   );
 }
 
+// The way out that is not stopping.
+//
+// This exists because of a session that ended for no reason. The Fable weekly
+// was at 89 per cent and binding, the line said the budget was nearly gone, and
+// the work stopped - while the five-hour window sat at 46 and every other model
+// on the account was untouched. A per-model weekly is not the account's budget.
+// It is one model's, and switching model retires it outright.
+//
+// So: when the window that binds is scoped to a model, say which window would
+// bind after a switch and how full it is. When it is shared, a model switch
+// changes nothing and the lever is effort instead. Either way the point is the
+// same - being at the wall is not the same as being out of budget, and an agent
+// that cannot tell the difference stops early and calls it caution.
+function escapeRoute(windows, binding, effortNote) {
+  if (!binding || binding.percentUsed === null || binding.percentUsed === undefined) return null;
+  const live = (windows || []).filter(
+    (w) => w && w.percentUsed !== null && w.percentUsed !== undefined && !w.stale && w.key !== binding.key
+  );
+
+  if (binding.family) {
+    // Everything that would still apply once this model is no longer the one
+    // running: the shared windows, plus any other model's weekly.
+    const after = live.filter((w) => w.family !== binding.family);
+    const next = after.length
+      ? after.reduce((worst, w) => (w.percentUsed > worst.percentUsed ? w : worst))
+      : null;
+    // Only worth calling an escape if what replaces it is meaningfully emptier.
+    // Trading an 89 for an 87 is not a way out, it is a lateral move. And with
+    // no other readable window there is no evidence a switch helps at all: it
+    // is true that the scoped window would retire, but "you have room" is a
+    // claim, and a claim with nothing behind it is the thing not to make.
+    if (!next || next.percentUsed >= binding.percentUsed - 10) return null;
+    const roomier = after
+      .filter((w) => w.family && w.family !== binding.family)
+      .sort((a, b) => a.percentUsed - b.percentUsed)[0] || null;
+    return {
+      kind: 'model',
+      frees: binding.label || binding.key,
+      family: binding.family,
+      nextLabel: next ? next.label || next.key : null,
+      nextPercent: next ? Math.round(next.percentUsed) : null,
+      suggest: roomier && roomier.family ? roomier.family : null,
+    };
+  }
+
+  // A shared window follows the account wherever the model goes, so the only
+  // lever left is how dear a turn is.
+  if (effortNote && effortNote.cheaper && effortNote.cheaper.effort) {
+    return {
+      kind: 'effort',
+      from: effortNote.effort || null,
+      to: effortNote.cheaper.effort,
+      multiple: Number.isFinite(effortNote.cheaper.multiple) ? effortNote.cheaper.multiple : null,
+    };
+  }
+  return null;
+}
+
 // The window that will stop the work first.
 function bindingWindow(windows) {
   // A per-model weekly for a model that is not running cannot be the window
@@ -3681,6 +3739,7 @@ module.exports = {
   lastRejections,
   bindingWindow,
   criticalOthers,
+  escapeRoute,
   betterCalibration,
   calibrationForPlan,
   stampPlan,