claude-usage-limits 1.1.3 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.1.3",
+  "version": "1.2.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,28 @@ node skills/usage-limits/scripts/usage.js
 node skills/usage-limits/scripts/usage.js --json
 ```
 
+## When you keep typing
+
+Every message sent while work is already running starts another turn, and each
+turn re-sends the whole conversation. Three follow-ups during one task can cost
+more than the task did.
+
+So when several additions arrive mid-task and the binding window is tight,
+Claude says so once and keeps working:
+
+> I have got all three. While the weekly window is this tight, sending them
+> together costs a good deal less than one at a time, so I will fold these in
+> and carry on.
+
+It asks once, never repeatedly, and only when the budget is actually tight.
+Asking someone to hold their thoughts when there is room to spare is rude for
+no gain.
+
+The important exclusion: it never discourages a correction, a stop, or a bug
+report. Those are the messages that save the most work, and a rule that trains
+people out of interrupting to say "that is wrong" costs far more than the turns
+it saves. Only additive scope is worth batching.
+
 ## Credits, and what happens at the wall
 
 The report says which of two things happens when the plan allowance runs out,
@@ -390,10 +412,17 @@ Good enough to plan with, not a bill. The honest caveats:
 - A model released after this table was written is priced at its family's
   average rate, and the report marks those rows with an asterisk rather than
   passing the guess off as a published price.
-- The cache only refreshes when Claude Code talks to the API, so after an idle
-  spell a window can sit past its own reset time. When that happens the report
-  says `stale` and the status line says `rolling` rather than reporting a
-  percentage for a window that has already turned over.
+- 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
+  from your transcripts instead: whatever was spent inside the window the stale
+  reading describes equalled its percentage, and that price per point still
+  values the window running now. Rebuilt figures are written `~41%` in the
+  report and "about 41%" in the before-prompt line, and they say how old the
+  snapshot is so you can run `/usage` and replace the estimate with a reading.
+- A rebuilt figure only counts what this machine did. If you also worked on
+  another device it reads low, which is the dangerous direction, so treat it as
+  a floor until you refresh.
 
 [how-it-works.md](skills/usage-limits/references/how-it-works.md) has the field
 names, the formulas, and the rest of it.
@@ -419,7 +448,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-119 tests over the pricing, the window arithmetic, plan and credit detection,
+130 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.1.3",
+  "version": "1.2.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

@@ -78,6 +78,37 @@ 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.
 
+## When messages stack up
+
+Every message sent while work is already running starts another turn, and every
+turn re-sends the whole conversation. Three follow-ups during one task can cost
+more than the task did.
+
+So when several additions arrive while you are still working and the binding
+window is tight, say it once, then keep going:
+
+> I have got all three. While the weekly window is this tight, sending them
+> together costs a good deal less than one at a time, so I will fold these in
+> and carry on. Send the rest in one go if you can.
+
+Four rules keep that from being obnoxious, and they matter more than the saving.
+
+**Ask once per stretch of work.** A second reminder costs more goodwill than
+the tokens it saves.
+
+**Only when the budget is actually tight.** With room to spare, asking someone
+to hold their thoughts is rude for no gain. Say nothing.
+
+**Never discourage a correction, a stop, or a bug report.** Those are the
+messages that save the most work. Someone interrupting to say the approach is
+wrong has just paid for their own interruption many times over, and a rule that
+trains people out of that is far more expensive than the turns it saves. Only
+additive scope, the "also do X" and "and can you Y", is worth batching.
+
+**Never make it about you.** The cost lands on their limit, not yours. Frame it
+as their budget, offer the saving, and let them decide. Then work. Do not stop
+to negotiate about whether to stop.
+
 ## Credits
 
 The `Credits` line in the report says what actually happens at the limit, and

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

@@ -43,10 +43,25 @@ function cacheFile() {
 // ever got a hit and both paid for a full scan each time.
 const KEEP_SESSIONS = 5;
 
+// A cache written before slots were keyed by session keeps its fields at the
+// top level, so upgrading would carry "at", "turnsLeft", "session" and
+// "sessionId" forward as if each were a session, crowding out real slots and
+// quietly undoing the per-session caching. Anything that is not a slot goes.
+function keepSlots(parsed) {
+  if (!parsed || typeof parsed !== 'object') return {};
+  const slots = {};
+  for (const key of Object.keys(parsed)) {
+    const value = parsed[key];
+    if (value && typeof value === 'object' && Number.isFinite(value.at)) {
+      slots[key] = value;
+    }
+  }
+  return slots;
+}
+
 function readCache() {
   try {
-    const parsed = JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
-    return parsed && typeof parsed === 'object' ? parsed : {};
+    return keepSlots(JSON.parse(fs.readFileSync(cacheFile(), 'utf8')));
   } catch (err) {
     return {};
   }
@@ -160,9 +175,9 @@ function sessionSpend(events, sessionId) {
 
 function describeWindow(window) {
   if (!window) return null;
-  return window.stale
-    ? window.label + ' rolling over'
-    : window.label + ' ' + window.percentUsed + '%';
+  if (window.stale) return window.label + ' rolling over';
+  const about = window.estimated ? ' about ' : ' ';
+  return window.label + about + window.percentUsed + '%';
 }
 
 // Everything except the window that will actually stop the work.
@@ -191,6 +206,12 @@ function briefText(parts) {
       ? '[usage-limits] binding window is ' + bound.join(', ') + '.'
       : '[usage-limits] no usable window reading.'
   );
+  if (parts.rebuilt) {
+    sentences.push(
+      'That figure was rebuilt from local history because the ' +
+        'snapshot is ' + parts.snapshotAge + ' old; run /usage to refresh it.'
+    );
+  }
   if (parts.othersSummary) sentences.push('Other windows: ' + parts.othersSummary + '.');
   if (parts.session) {
     sentences.push(
@@ -203,7 +224,9 @@ function briefText(parts) {
     parts.pressure === 'tight' || parts.pressure === 'gone'
       ? 'Open your reply with one line on where this leaves the budget, then say ' +
         'what you will do now and what you will leave for after the reset. ' +
-        'Do not start work that clearly will not finish.'
+        'Do not start work that clearly will not finish. If several additions ' +
+        'arrive while you are working, say once that sending them together ' +
+        'costs less, then carry on; never say it about a correction or a stop.'
       : 'Open your reply with one short line stating this and confirming the ' +
         'request fits, then get on with the work. Keep it to a single line.';
 
@@ -225,38 +248,50 @@ async function run(now, hookInput) {
   if (!base.utilization) return '';
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
-
-  // The percentages are cheap: one small file, no transcripts.
-  const cheap = usage.buildWindows(base.utilization, [], now);
-  if (!cheap.length) return '';
-
   const all = readCache();
-  const cached = pickCached(all, sessionId, now, config.cacheSeconds * SECOND);
-
-  let turnsLeft = cached ? cached.turnsLeft : null;
-  let session = cached ? cached.session : null;
-  let windows = cheap;
+  let view = pickCached(all, sessionId, now, config.cacheSeconds * SECOND);
 
-  if (!cached) {
+  // Everything shown has to come from one pass. Deriving the turns from a
+  // 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);
-    windows = usage.buildWindows(base.utilization, events, now);
+    const windows = usage.buildWindows(base.utilization, events, now);
     const binding = usage.bindingWindow(windows);
-    turnsLeft = binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null;
-    session = sessionSpend(events, sessionId);
-    writeCache(mergeCache(all, sessionId, { at: now, turnsLeft, session }, KEEP_SESSIONS));
+    view = {
+      at: now,
+      turnsLeft: binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
+      session: sessionSpend(events, sessionId),
+      othersSummary: summariseOthers(windows, binding && binding.key),
+      binding: binding
+        ? {
+            key: binding.key,
+            label: binding.label,
+            percentUsed: binding.percentUsed,
+            stale: binding.stale,
+            estimated: binding.estimated,
+            resetsAt: binding.resetsAt,
+            verdict: binding.verdict,
+            windowStart: binding.windowStart,
+            spanMs: binding.spanMs,
+          }
+        : null,
+    };
+    writeCache(mergeCache(all, sessionId, view, KEEP_SESSIONS));
   }
 
-  const binding = usage.bindingWindow(windows) || windows[0];
-
+  const binding = view.binding;
   return briefText({
     binding,
-    othersSummary: summariseOthers(windows, binding && binding.key),
-    turnsLeft,
+    othersSummary: view.othersSummary,
+    turnsLeft: view.turnsLeft,
     resetsIn:
-      binding && !binding.stale && binding.msToReset !== null
-        ? usage.formatDuration(binding.msToReset)
+      binding && !binding.stale && Number.isFinite(binding.resetsAt)
+        ? usage.formatDuration(binding.resetsAt - now)
         : null,
-    session,
+    session: view.session,
+    rebuilt: Boolean(binding && binding.estimated),
+    snapshotAge: usage.formatDuration(base.snapshotAgeMs),
     pressure: pressure(binding, now, config),
   });
 }
@@ -285,6 +320,7 @@ module.exports = {
   summariseOthers,
   briefText,
   settings,
+  keepSlots,
   pickCached,
   mergeCache,
   KEEP_SESSIONS,

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

@@ -470,12 +470,17 @@ function forecastWindow(window, turns, rates) {
 }
 
 // Everything the report needs about one limit window.
-function buildWindow(spec, snapshot, events, now) {
+function buildWindow(spec, snapshot, events, now, options) {
+  const extra = options || {};
   const percent =
     snapshot && typeof snapshot.utilization === 'number' ? snapshot.utilization : null;
   const resetsAt = snapshot && snapshot.resets_at ? Date.parse(snapshot.resets_at) : null;
   const hasReset = Number.isFinite(resetsAt);
-  const start = hasReset ? resetsAt - spec.span : now - spec.span;
+  const start = Number.isFinite(extra.windowStart)
+    ? extra.windowStart
+    : hasReset
+      ? resetsAt - spec.span
+      : now - spec.span;
 
   const inWindow = events.filter((event) => event.at >= start && event.at <= now);
   const spent = totals(inWindow);
@@ -508,6 +513,9 @@ function buildWindow(spec, snapshot, events, now) {
     headroomMs: null,
     coarse: false,
     stale: false,
+    // True when the percentage was rebuilt from local history because the
+    // snapshot had gone stale, rather than read from the snapshot itself.
+    estimated: Boolean(extra.estimated),
     verdict: 'unknown',
   };
 
@@ -667,6 +675,39 @@ function collect(now) {
   };
 }
 
+// A snapshot 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 loses the limit that actually stops short work, so
+// rebuild it from the transcripts instead.
+//
+// The trick is that the stale reading is still a usable calibration: whatever
+// was spent inside the window it describes equalled its percentage. That
+// dollars-per-point figure is a property of the plan, not of the moment, so it
+// still prices the window running now.
+function reconstructWindow(spec, snapshot, events, now) {
+  if (!snapshot || typeof snapshot.utilization !== 'number') return null;
+  if (snapshot.utilization <= 0) return null;
+
+  const resetsAt = snapshot.resets_at ? Date.parse(snapshot.resets_at) : null;
+  if (!Number.isFinite(resetsAt) || resetsAt > now) return null;
+
+  const pastStart = resetsAt - spec.span;
+  const past = totals(events.filter((e) => e.at >= pastStart && e.at <= resetsAt));
+  if (past.cost <= 0) return null;
+
+  const usdPerPercent = past.cost / snapshot.utilization;
+  const liveStart = now - spec.span;
+  const live = totals(events.filter((e) => e.at >= liveStart && e.at <= now));
+
+  return {
+    percentUsed: Math.min(100, Math.round(live.cost / usdPerPercent)),
+    usdPerPercent,
+    spentUSD: live.cost,
+    turns: live.turns,
+    windowStart: liveStart,
+  };
+}
+
 // 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) {
@@ -675,7 +716,20 @@ function buildWindows(utilization, events, now) {
     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;
-    return buildWindow(spec, snapshot, events, now);
+
+    const window = buildWindow(spec, snapshot, events, now);
+    if (!window.stale) return window;
+
+    // Rolled over. Rebuild from local history rather than going blind on it.
+    const rebuilt = reconstructWindow(spec, snapshot, events, now);
+    if (!rebuilt) return window;
+    return buildWindow(
+      spec,
+      { utilization: rebuilt.percentUsed, resets_at: null },
+      events,
+      now,
+      { estimated: true, windowStart: rebuilt.windowStart }
+    );
   }).filter(Boolean);
 }
 
@@ -842,7 +896,11 @@ function render(data) {
     lines.push(
       '  ' + pad(window.label, 15) +
         padLeft(
-          window.stale ? 'stale' : window.percentUsed === null ? '-' : window.percentUsed + '%',
+          window.stale
+            ? 'stale'
+            : window.percentUsed === null
+              ? '-'
+              : (window.estimated ? '~' : '') + window.percentUsed + '%',
           6
         ) +
         padLeft(formatDuration(window.msToReset), 12) +
@@ -909,6 +967,15 @@ function render(data) {
   }
   lines.push('  Measured      ' + formatCount(data.measuredTurns) + ' turns of local transcript');
 
+  if (data.windows.some((window) => window.estimated)) {
+    lines.push(
+      '  Note          ~ means the snapshot had gone stale and that window was rebuilt'
+    );
+    lines.push(
+      '                from local history. Run /usage to replace it with a real reading.'
+    );
+  }
+
   if (data.binding && data.binding.coarse) {
     lines.push('  Note          the meter reads in whole percent, so a low reading is a wide bracket');
   }
@@ -1064,6 +1131,7 @@ module.exports = {
   eventFrom,
   readEvents,
   buildWindow,
+  reconstructWindow,
   buildWindows,
   bindingWindow,
   dominantEffort,