claude-usage-limits 1.5.5 → 1.6.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.5.5",
+  "version": "1.6.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/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
@@ -467,6 +473,11 @@ Good enough to plan with, not a bill. The honest caveats:
   to the meter rather than from an assumption about the clock.
 - The turn cost behind "turns of headroom" is a median over at least five
   turns, so one compaction cannot define your pace.
+- What a point of a window costs is learned once from the best sample seen and
+  remembered, rather than re-derived each time from whatever slice is to hand.
+  A thin baseline prices a point badly and every correction built on it
+  inherits the error, which is how a window truly at 70 percent once came out
+  at 82.
 - The cache only refreshes when Claude Code talks to the API, so after a gap it
   can be hours old and its 5-hour window long since rolled over. Dropping that
   window would hide the limit that actually stops short work, so it gets rebuilt
@@ -509,7 +520,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-181 tests over the pricing, the window arithmetic, plan and credit detection,
+190 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.5",
+  "version": "1.6.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

@@ -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

@@ -242,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, ' +
@@ -295,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
         ? {
@@ -334,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

@@ -532,6 +532,43 @@ function shareOf(sessions, sessionId) {
   return mine.share > 0 ? mine.share : 1 / sessions.length;
 }
 
+// What a point of a window costs is a property of the plan, not of the moment,
+// so it should be learned once from a good sample rather than re-derived from
+// whatever slice happens to be to hand. A thin baseline prices a point badly
+// and every correction built on it inherits the error: a 24 minute old
+// snapshot once turned a window truly at 70 per cent into a confident 82.
+function calibrationFile() {
+  return path.join(configDir(), 'usage-limits-calibration.json');
+}
+
+function readCalibration() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(calibrationFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    return {};
+  }
+}
+
+function writeCalibration(all) {
+  try {
+    fs.mkdirSync(path.dirname(calibrationFile()), { recursive: true });
+    fs.writeFileSync(calibrationFile(), JSON.stringify(all), 'utf8');
+  } catch (err) {
+    // Losing it costs accuracy on the next thin baseline, nothing more.
+  }
+}
+
+// A sample is better when it rests on more turns. Percentages read in whole
+// numbers, so a bigger percentage also divides more precisely.
+function betterCalibration(current, candidate) {
+  if (!candidate || !Number.isFinite(candidate.usdPerPercent) || candidate.usdPerPercent <= 0) {
+    return current || null;
+  }
+  if (!current || !Number.isFinite(current.turns)) return candidate;
+  return candidate.turns > current.turns ? candidate : current;
+}
+
 // Everything the report needs about one limit window.
 function buildWindow(spec, snapshot, events, now, options) {
   const extra = options || {};
@@ -584,6 +621,8 @@ function buildWindow(spec, snapshot, events, now, options) {
     pointsSinceSnapshot: 0,
     // Set when spend since the snapshot could not be priced sensibly.
     correctionUnreliable: false,
+    // The price-per-point this window derived from its own baseline.
+    calibration: null,
     verdict: 'unknown',
   };
 
@@ -618,7 +657,13 @@ function buildWindow(spec, snapshot, events, now, options) {
     // 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;
+      const mine = { usdPerPercent: upTo.cost / rawPercent, turns: upTo.turns, percent: rawPercent };
+      const known = extra.knownCalibration;
+      // Trust the better-sampled of the two, whichever that is.
+      const chosen =
+        known && Number.isFinite(known.turns) && known.turns > upTo.turns ? known : mine;
+      window.calibration = mine;
+      const pricePerPoint = chosen.usdPerPercent;
       sinceSnapshot = after.cost / pricePerPoint;
 
       // Same rule as a rebuild: past this it is the calibration that is full,
@@ -685,6 +730,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);
@@ -869,14 +932,17 @@ function reconstructWindow(spec, snapshot, events, now) {
 
 // No snapshot at all means no windows, which is what tells the report to
 // explain itself rather than print a table of dashes.
-function buildWindows(utilization, events, now, fetchedAt) {
+function buildWindows(utilization, events, now, fetchedAt, learned) {
   if (!utilization) return [];
   return WINDOWS.map((spec) => {
     const snapshot = utilization[spec.key];
     // The per-model weekly windows only exist on some plans.
     if (spec.key !== 'five_hour' && spec.key !== 'seven_day' && !snapshot) return null;
 
-    const window = buildWindow(spec, snapshot, events, now, { fetchedAt });
+    const window = buildWindow(spec, snapshot, events, now, {
+      fetchedAt,
+      knownCalibration: learned ? learned[spec.key] : null,
+    });
     if (!window.stale) return window;
 
     // Rolled over. Rebuild from local history rather than going blind on it.
@@ -916,7 +982,27 @@ async function report(now, options) {
   const earliest = now - 8 * DAY;
   const events = await readEvents(earliest);
 
-  const windows = buildWindows(base.utilization, events, now, base.snapshotFetchedAt);
+  const learned = readCalibration();
+  const windows = buildWindows(
+    base.utilization,
+    events,
+    now,
+    base.snapshotFetchedAt,
+    learned
+  );
+
+  // Keep the best sample seen so far, so a thin baseline never has to guess.
+  const updated = Object.assign({}, learned);
+  let changed = false;
+  for (const window of windows) {
+    if (!window.calibration) continue;
+    const best = betterCalibration(learned[window.key], window.calibration);
+    if (best && best !== learned[window.key]) {
+      updated[window.key] = best;
+      changed = true;
+    }
+  }
+  if (changed) writeCalibration(updated);
 
   const recentEvents = events.filter((event) => event.at >= now - HOUR);
   const recent = totals(recentEvents);
@@ -1340,6 +1426,10 @@ module.exports = {
   MIN_BASELINE_TURNS,
   buildWindows,
   bindingWindow,
+  criticalOthers,
+  betterCalibration,
+  calibrationFile,
+  CRITICAL_PERCENT,
   dominantEffort,
   typicalTurnCost,
   activeSessions,