claude-usage-limits 1.5.4 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "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/README.md

@@ -207,6 +207,12 @@ A window with no recent spend to measure is ranked by how full it is rather
 than being skipped, so a 5-hour window sitting at 95 percent is never passed
 over just because nothing has gone through it in the last few minutes.
 
+Binding is about what stops you soonest, though, not what stopping costs, and
+those are different: a 5-hour window returns in hours, the weekly one in days.
+So a window above 85 percent gets called out even when something shorter binds,
+with its own reset time, because spending the weekly window to save a few turns
+of the 5-hour one is a bad trade.
+
 ## When you keep typing
 
 Every message sent while work is already running starts another turn, and each
@@ -509,7 +515,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-181 tests over the pricing, the window arithmetic, plan and credit detection,
+186 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, job forecasting, per-project
 attribution, the CLI, packaging, and the settings save/restore.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "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

@@ -171,6 +171,12 @@ Keep it to one line unless the work genuinely does not fit. The budget note is
 a header, not a section, and it must never push the actual answer down the
 page.
 
+Which window binds is about what stops you soonest, not what stopping costs.
+Those differ: a 5-hour window comes back in hours, the weekly one in days. So
+when a window that is not binding sits near its wall, say so and weigh it. The
+hook flags those. Running the weekly out to save a few turns of the 5-hour
+window is a bad trade even though the 5-hour is what runs out first.
+
 One thing to get right: **quote the binding window, not the roomiest one.**
 Two windows run at once and they are rarely in the same place. The turns of
 headroom and the reset time belong to whichever runs out first. Putting the

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

@@ -119,7 +119,6 @@ function aheadOfPace(window, now) {
   return window.percentUsed - Math.min(100, Math.max(0, elapsed));
 }
 
-// Not whether to speak, which is always, but how hard to lean on it.
 // Not whether to speak, which is always, but how hard to lean on it.
 function pressure(window, now, config, turnsLeft) {
   if (!window || window.percentUsed === null || window.stale) return 'unknown';
@@ -243,6 +242,17 @@ function briefText(parts) {
     );
   }
   if (parts.othersSummary) sentences.push('Other windows: ' + parts.othersSummary + '.');
+
+  // 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) {
+      sentences.push(
+        'Note that ' + other.label + ' is at ' + other.percentUsed + '% and resets in ' +
+          other.resetsIn + ', so running that one out stops work for far longer than the ' +
+          'binding window would. Weigh it even though it is not what runs out first.'
+      );
+    }
+  }
   if (parts.session) {
     sentences.push(
       'This session: ' + parts.session.turns + ' turns, ' +
@@ -296,6 +306,11 @@ async function run(now, hookInput) {
       othersSummary: summariseOthers(data.windows, binding && binding.key),
       sessions: data.sessions,
       staleWindows: data.staleWindows,
+      critical: usage.criticalOthers(data.windows, binding && binding.key).map((w) => ({
+        label: w.label,
+        percentUsed: w.percentUsed,
+        resetsIn: Number.isFinite(w.msToReset) ? usage.formatDuration(w.msToReset) : 'an unknown time',
+      })),
       snapshotAge: usage.formatDuration(data.snapshotAgeMs),
       binding: binding
         ? {
@@ -335,6 +350,7 @@ async function run(now, hookInput) {
     session: view.session,
     rebuilt: Boolean(binding && binding.estimated),
     staleWindows: view.staleWindows || 0,
+    critical: view.critical || [],
     pointsSinceSnapshot: (binding && binding.pointsSinceSnapshot) || 0,
     snapshotAge: view.snapshotAge,
     pressure: pressure(binding, now, config, view.turnsLeft),

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

@@ -685,6 +685,24 @@ function buildWindow(spec, snapshot, events, now, options) {
   return window;
 }
 
+// Which window binds is about what stops you soonest. It says nothing about
+// what stopping costs. Running out of a 5-hour window waits hours; running out
+// of the weekly one waits days. So a weekly window near the wall is worth
+// hearing about even while a shorter window binds.
+const CRITICAL_PERCENT = 85;
+
+function criticalOthers(windows, bindingKey, threshold) {
+  const limit = Number.isFinite(threshold) ? threshold : CRITICAL_PERCENT;
+  return (windows || []).filter(
+    (w) =>
+      w &&
+      w.key !== bindingKey &&
+      !w.stale &&
+      w.percentUsed !== null &&
+      w.percentUsed >= limit
+  );
+}
+
 // The window that will stop the work first.
 function bindingWindow(windows) {
   const known = windows.filter((w) => w.percentUsed !== null);
@@ -1214,13 +1232,18 @@ function formatPercent(value) {
 
 function renderForecast(data, turns) {
   const lines = [];
-  lines.push('Forecast for ' + turns + ' turns');
-  lines.push('');
 
+  // Checked before the heading is built, or a bad argument prints straight
+  // into it: "Forecast for NaN turns".
   if (!Number.isFinite(turns) || turns <= 0) {
+    lines.push('Forecast');
+    lines.push('');
     lines.push('  Give a number of turns, for example --forecast 15.');
     return lines.join('\n');
   }
+
+  lines.push('Forecast for ' + turns + ' turns');
+  lines.push('');
   if (!data.rates) {
     lines.push('  Nothing recent to price this against yet. Do some work in this');
     lines.push('  session first, then ask again.');
@@ -1335,6 +1358,8 @@ module.exports = {
   MIN_BASELINE_TURNS,
   buildWindows,
   bindingWindow,
+  criticalOthers,
+  CRITICAL_PERCENT,
   dominantEffort,
   typicalTurnCost,
   activeSessions,