claude-usage-limits 1.2.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.2.0",
+  "version": "1.3.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

@@ -167,6 +167,21 @@ node skills/usage-limits/scripts/usage.js
 node skills/usage-limits/scripts/usage.js --json
 ```
 
+## Which limit it watches
+
+Two windows run at once and the 5-hour one is usually what actually stops you,
+so it gets picked whenever it is tighter, and it wins a tie against the weekly
+window because the shorter window is the one hit first in practice.
+
+It is not forced, though. When the weekly window is genuinely the wall, at 99
+percent with minutes left, that is what gets reported. Forcing the 5-hour there
+would hide the limit about to stop the work, which is the same failure as
+ignoring it.
+
+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.
+
 ## When you keep typing
 
 Every message sent while work is already running starts another turn, and each
@@ -296,6 +311,7 @@ minute, so it costs about 400ms cold and 120ms warm.
 | `USAGE_LIMITS_FLOOR` | 40 | Below this, pace is ignored. |
 | `USAGE_LIMITS_AHEAD` | 15 | Points ahead of pace that count as burning fast. |
 | `USAGE_LIMITS_CACHE` | 60 | Seconds the measured half stays good for. |
+| `USAGE_LIMITS_FEW_TURNS` | 20 | Turn count at or below which the budget counts as tight. |
 
 ## What would this job cost
 
@@ -448,7 +464,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-130 tests over the pricing, the window arithmetic, plan and credit detection,
+142 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.2.0",
+  "version": "1.3.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/scripts/brief.js

@@ -28,6 +28,8 @@ const DEFAULTS = {
   // How long the measured part stays good for. Prompts often arrive in
   // bursts, and a transcript scan per prompt would be wasteful.
   cacheSeconds: 60,
+  // Few enough turns that the count itself is the warning.
+  fewTurns: 20,
 };
 
 function configDir() {
@@ -104,6 +106,7 @@ function settings() {
     floor: number(env.USAGE_LIMITS_FLOOR, DEFAULTS.floor),
     ahead: number(env.USAGE_LIMITS_AHEAD, DEFAULTS.ahead),
     cacheSeconds: number(env.USAGE_LIMITS_CACHE, DEFAULTS.cacheSeconds),
+    fewTurns: number(env.USAGE_LIMITS_FEW_TURNS, DEFAULTS.fewTurns),
   };
 }
 
@@ -117,16 +120,32 @@ function aheadOfPace(window, now) {
 }
 
 // Not whether to speak, which is always, but how hard to lean on it.
-function pressure(window, now, config) {
+// 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';
-  if (window.verdict === 'exhausted') return 'gone';
+  if (window.verdict === 'exhausted' || window.percentUsed >= 100) return 'gone';
   if (window.verdict === 'runs-out') return 'tight';
-  if (window.percentUsed >= config.near) return 'tight';
 
-  const lead = aheadOfPace(window, now);
-  if (window.percentUsed >= config.floor && lead !== null && lead >= config.ahead) {
+  // A rebuilt figure only counts this machine, so it reads low. React to it
+  // sooner than to a figure the API actually reported.
+  const near = window.estimated ? Math.min(config.near, 70) : config.near;
+  if (window.percentUsed >= near) return 'tight';
+
+  // Turns are the number the work is planned in, so a short count is tight
+  // whatever the percentage says.
+  if (Number.isFinite(turnsLeft) && turnsLeft <= config.fewTurns) {
     return 'tight';
   }
+
+  // Pace only means something for a window with a real start. A rebuilt one
+  // is anchored at now minus its span, so it is always "fully elapsed" and
+  // the comparison can never fire.
+  if (!window.estimated) {
+    const lead = aheadOfPace(window, now);
+    if (window.percentUsed >= config.floor && lead !== null && lead >= config.ahead) {
+      return 'tight';
+    }
+  }
   return 'roomy';
 }
 
@@ -292,7 +311,7 @@ async function run(now, hookInput) {
     session: view.session,
     rebuilt: Boolean(binding && binding.estimated),
     snapshotAge: usage.formatDuration(base.snapshotAgeMs),
-    pressure: pressure(binding, now, config),
+    pressure: pressure(binding, now, config, view.turnsLeft),
   });
 }
 

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

@@ -571,11 +571,27 @@ function bindingWindow(windows) {
   const live = fresh.length ? fresh : known;
   if (!live.length) return null;
 
-  const measured = live.filter((w) => w.headroomMs !== null);
-  if (measured.length) {
-    return measured.reduce((worst, w) => (w.headroomMs < worst.headroomMs ? w : worst));
-  }
-  return live.reduce((worst, w) => (w.percentUsed > worst.percentUsed ? w : worst));
+  // How soon this window stops the work. A window with no pace estimate is
+  // ranked by how full it is instead, because a nearly full window must never
+  // be passed over merely because nothing has been spent in it lately.
+  const soonest = (w) => {
+    if (Number.isFinite(w.headroomMs)) return w.headroomMs;
+    return w.percentUsed >= 90 ? 0 : Infinity;
+  };
+
+  return live.reduce((best, w) => {
+    const mine = soonest(w);
+    const theirs = soonest(best);
+    if (mine !== theirs) return mine < theirs ? w : best;
+
+    // Equally urgent: the shorter window is the one hit first in practice, so
+    // the 5-hour limit wins a tie against the weekly one.
+    const myspan = Number.isFinite(w.spanMs) ? w.spanMs : Infinity;
+    const theirspan = Number.isFinite(best.spanMs) ? best.spanMs : Infinity;
+    if (myspan !== theirspan) return myspan < theirspan ? w : best;
+
+    return w.percentUsed > best.percentUsed ? w : best;
+  });
 }
 
 function formatDuration(ms) {