claude-usage-limits 1.5.3 → 1.5.5

package/.claude-plugin/plugin.json

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

@@ -325,6 +325,13 @@ explaining is pace: two days into a week you should be near 29 percent spent, so
 60 percent means you will not last the week, and that is worth hearing at 60
 rather than at 85.
 
+One limit worth knowing: the hook fires when a prompt is submitted, so a
+message sent while Claude is already working does not refresh it. Claude Code
+delivers those into the running turn without re-running hooks, which no plugin
+can intercept. The skill handles it by telling Claude the figures age during a
+turn, and to re-read them before claiming a job fits rather than trusting a
+number from several tool calls ago.
+
 It has to be cheap, because it runs on every prompt. The percentages come from
 one small file. The transcript scan behind "turns of headroom" is cached for a
 minute, so it costs about 400ms cold and 120ms warm.
@@ -502,7 +509,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-179 tests over the pricing, the window arithmetic, plan and credit detection,
+181 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.3",
+  "version": "1.5.5",
   "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

@@ -78,6 +78,29 @@ abandoned mid-edit.
 **The window resets first.** If the reset lands before the budget runs out,
 the limit is not the constraint. Say that and stop optimising for it.
 
+## The budget line ages during a turn
+
+The hook runs when a prompt is submitted, so the figures you were given are
+from the start of the turn. A message sent while you are already working does
+not fire it again: it arrives without a budget line, and the numbers you are
+holding are now older than they look.
+
+That matters most when it is the one thing you are about to assert. Re-check
+before saying a job fits, if any of these are true:
+
+- the turn has run long, or through many tool calls
+- more requests arrived while you were working
+- other sessions are active, so the budget is draining without you
+
+```
+node scripts/usage.js --status
+```
+
+That is one cheap read of a small file, no transcript scan, and it costs far
+less than promising to finish something and stopping halfway. If you have no
+budget line at all this turn, you are mid-turn: use the last one you were given
+and treat it as a ceiling, not a reading.
+
 ## When messages stack up
 
 Every message sent while work is already running starts another turn, and every

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';
@@ -180,17 +179,8 @@ function readHookInput() {
   });
 }
 
-function sessionSpend(events, sessionId) {
-  if (!sessionId) return null;
-  let cost = 0;
-  let turns = 0;
-  for (const event of events) {
-    if (event.sessionId !== sessionId) continue;
-    cost += event.cost;
-    turns += 1;
-  }
-  return turns ? { turns, cost } : null;
-}
+// Kept as a re-export so there is exactly one implementation.
+const sessionSpend = usage.sessionSpend;
 
 function describeWindow(window) {
   if (!window) return null;
@@ -294,16 +284,18 @@ async function run(now, hookInput) {
   // full scan and the binding window from somewhere cheaper is how the two
   // end up describing different windows.
   if (!view || !view.binding) {
-    const events = await usage.readEvents(now - 8 * DAY);
-    const windows = usage.buildWindows(base.utilization, events, now);
-    const binding = usage.bindingWindow(windows);
+    // One call, shared with the report. Building the view twice is how the
+    // snapshot correction reached the report and never reached the hook.
+    const data = await usage.report(now, { sessionId });
+    const binding = data.binding;
     view = {
       at: now,
       turnsLeft: binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
-      session: sessionSpend(events, sessionId),
-      othersSummary: summariseOthers(windows, binding && binding.key),
-      sessions: usage.activeSessions(events, now, usage.CONCURRENT_WINDOW_MS),
-      staleWindows: windows.filter((w) => w.stale).length,
+      session: data.session,
+      othersSummary: summariseOthers(data.windows, binding && binding.key),
+      sessions: data.sessions,
+      staleWindows: data.staleWindows,
+      snapshotAge: usage.formatDuration(data.snapshotAgeMs),
       binding: binding
         ? {
             key: binding.key,
@@ -313,6 +305,7 @@ async function run(now, hookInput) {
             estimated: binding.estimated,
             adjusted: binding.adjusted,
             pointsSinceSnapshot: binding.pointsSinceSnapshot,
+            correctionUnreliable: binding.correctionUnreliable,
             resetsAt: binding.resetsAt,
             verdict: binding.verdict,
             windowStart: binding.windowStart,
@@ -342,7 +335,7 @@ async function run(now, hookInput) {
     rebuilt: Boolean(binding && binding.estimated),
     staleWindows: view.staleWindows || 0,
     pointsSinceSnapshot: (binding && binding.pointsSinceSnapshot) || 0,
-    snapshotAge: usage.formatDuration(base.snapshotAgeMs),
+    snapshotAge: view.snapshotAge,
     pressure: pressure(binding, now, config, view.turnsLeft),
   });
 }

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

@@ -582,6 +582,8 @@ function buildWindow(spec, snapshot, events, now, options) {
     // True when spend since the snapshot was added to its reading.
     adjusted: false,
     pointsSinceSnapshot: 0,
+    // Set when spend since the snapshot could not be priced sensibly.
+    correctionUnreliable: false,
     verdict: 'unknown',
   };
 
@@ -610,10 +612,22 @@ function buildWindow(spec, snapshot, events, now, options) {
   ) {
     const upTo = totals(inWindow.filter((e) => e.at <= extra.fetchedAt));
     const after = totals(inWindow.filter((e) => e.at > extra.fetchedAt));
-    if (upTo.cost > 0 && after.cost > 0) {
+
+    // The baseline has to be worth something. Pricing a point off two or three
+    // turns makes it far too cheap, and every dollar spent since then is then
+    // divided by that, which is how a window truly at 55% got corrected all the
+    // way to a confident 100.
+    if (upTo.cost > 0 && after.cost > 0 && upTo.turns >= MIN_BASELINE_TURNS) {
       const pricePerPoint = upTo.cost / rawPercent;
       sinceSnapshot = after.cost / pricePerPoint;
-      if (sinceSnapshot >= 1) {
+
+      // Same rule as a rebuild: past this it is the calibration that is full,
+      // not the window. Better to leave the reading uncorrected and say the
+      // snapshot is old than to assert a budget that is gone.
+      if (rawPercent + sinceSnapshot > SATURATION_LIMIT) {
+        sinceSnapshot = 0;
+        window.correctionUnreliable = true;
+      } else if (sinceSnapshot >= 1) {
         percent = Math.min(100, Math.round(rawPercent + sinceSnapshot));
         window.adjusted = true;
         window.pointsSinceSnapshot = Math.round(sinceSnapshot);
@@ -812,6 +826,9 @@ function collect(now) {
 // Anything above this and the calibration, not the budget, is what is full.
 const SATURATION_LIMIT = 105;
 
+// Fewer turns than this before the snapshot and a point cannot be priced.
+const MIN_BASELINE_TURNS = 5;
+
 function reconstructWindow(spec, snapshot, events, now) {
   if (!snapshot || typeof snapshot.utilization !== 'number') return null;
   if (snapshot.utilization <= 0) return null;
@@ -879,7 +896,20 @@ function buildWindows(utilization, events, now, fetchedAt) {
   }).filter(Boolean);
 }
 
-async function report(now) {
+// What one session has spent, out of everything on record.
+function sessionSpend(events, sessionId) {
+  if (!sessionId) return null;
+  let cost = 0;
+  let turns = 0;
+  for (const event of events) {
+    if (event.sessionId !== sessionId) continue;
+    cost += event.cost;
+    turns += 1;
+  }
+  return turns ? { turns, cost } : null;
+}
+
+async function report(now, options) {
   const base = collect(now);
   // A stale snapshot can put a window's start slightly further back than
   // seven days, so give the scan a day of slack.
@@ -901,6 +931,8 @@ async function report(now) {
     binding,
     credits: creditsFrom(base.utilization),
     sessions: activeSessions(events, now, CONCURRENT_WINDOW_MS),
+    session: sessionSpend(events, options && options.sessionId),
+    staleWindows: windows.filter((w) => w.stale).length,
     rates: costPercentiles(recentEvents.length >= 5 ? recentEvents : scoped),
     resumeAt: binding ? binding.resetsAt : null,
     models: byModel(scoped),
@@ -1182,13 +1214,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.');
@@ -1300,11 +1337,13 @@ module.exports = {
   buildWindow,
   reconstructWindow,
   SATURATION_LIMIT,
+  MIN_BASELINE_TURNS,
   buildWindows,
   bindingWindow,
   dominantEffort,
   typicalTurnCost,
   activeSessions,
+  sessionSpend,
   shareOf,
   CONCURRENT_WINDOW_MS,
   MIN_PACE_SAMPLE,