claude-usage-limits 1.1.4 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.1.4",
+  "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,43 @@ 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
+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,
@@ -274,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
 
@@ -390,10 +428,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 +464,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-119 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.1.4",
+  "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/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

@@ -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';
 }
 
@@ -175,9 +194,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.
@@ -206,6 +225,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(
@@ -218,7 +243,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.';
 
@@ -240,39 +267,51 @@ 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,
-    pressure: pressure(binding, now, config),
+    session: view.session,
+    rebuilt: Boolean(binding && binding.estimated),
+    snapshotAge: usage.formatDuration(base.snapshotAgeMs),
+    pressure: pressure(binding, now, config, view.turnsLeft),
   });
 }
 

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',
   };
 
@@ -563,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) {
@@ -667,6 +691,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 +732,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 +912,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 +983,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 +1147,7 @@ module.exports = {
   eventFrom,
   readEvents,
   buildWindow,
+  reconstructWindow,
   buildWindows,
   bindingWindow,
   dominantEffort,