claude-usage-limits 1.25.0 → 1.26.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.25.0",
+  "version": "1.26.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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.25.0",
+  "version": "1.26.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/agy-hook.js

@@ -124,7 +124,7 @@ async function run(now, input, argv) {
   if (event === 'PreToolUse') {
     const tool = toolNameOf(input);
     if (!ceiling.isMultiplier(tool)) return {};
-    const at = ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env });
+    const at = ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env, sessionId });
     const call = ceiling.verdict(at, tool);
     if (call.decision !== 'deny') return {};
     return { decision: 'deny', reason: call.reason };
@@ -141,7 +141,7 @@ async function run(now, input, argv) {
       text = '';
     }
     const warning = ceiling.warning(
-      ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env })
+      ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env, sessionId })
     );
     const message = [text, warning].filter(Boolean).join(' ');
     return message ? { injectSteps: [{ ephemeralMessage: message }] } : { injectSteps: [] };

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

@@ -64,10 +64,22 @@ function isMultiplier(tool) {
   return MULTIPLIER_PATTERN.test(name);
 }
 
-// The number, and who set it. An explicit environment value is the user saying
-// it outright for this one session and beats the file, the same precedence the
-// mode uses.
-function ceilingFrom(state, env) {
+// The number, and who set it.
+//
+// A cap belongs to THE SESSION THAT SET IT, and this is the whole of the fix
+// for it outliving one. "Do not spend past 65 per cent" is a thing somebody
+// says about the work in front of them; carrying it into tomorrow's session
+// means refusing fan-outs on a fresh window for a reason nobody remembers
+// giving. It was reported exactly that way: the session restarted and the cap
+// was still being enforced.
+//
+// So the stored cap carries the session id it was set in, and applies only
+// there. A cap with no session recorded is a cap from before this rule existed
+// - it is ignored rather than honoured, because honouring it is the bug.
+//
+// An explicit environment value is different: it is the user saying it outright
+// for this one process, so it beats the file and needs no session.
+function ceilingFrom(state, env, sessionId) {
   const environment = env || process.env;
   const raw = environment.USAGE_LIMITS_CEILING;
   if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
@@ -81,8 +93,16 @@ function ceilingFrom(state, env) {
     // the file rather than enforcing a number nobody typed.
   }
   const stored = state && Number.isFinite(state.ceilingPercent) ? state.ceilingPercent : null;
-  if (stored !== null && stored > 0 && stored <= 100) return { percent: stored, source: 'the file' };
-  return { percent: null, source: null };
+  if (stored === null || stored <= 0 || stored > 100) return { percent: null, source: null };
+  const owner = state && state.ceilingSession ? String(state.ceilingSession) : null;
+  if (!owner) {
+    // Set before caps were session-scoped. Not this session's instruction.
+    return { percent: null, source: null, staleCap: stored };
+  }
+  if (!sessionId || String(sessionId) !== owner) {
+    return { percent: null, source: null, otherSessionCap: stored };
+  }
+  return { percent: stored, source: 'this session' };
 }
 
 // Where the binding window stands against the ceiling.
@@ -92,7 +112,7 @@ function ceilingFrom(state, env) {
 // the same mistake the brief was corrected for.
 function assess(options) {
   const opts = options || {};
-  const ceiling = ceilingFrom(opts.state, opts.env);
+  const ceiling = ceilingFrom(opts.state, opts.env, opts.sessionId);
   const percent = Number.isFinite(opts.percent) ? opts.percent : null;
   if (ceiling.percent === null || percent === null) {
     return {
@@ -103,6 +123,8 @@ function assess(options) {
       over: false,
       near: false,
       headroomPoints: null,
+      staleCap: ceiling.staleCap || null,
+      otherSessionCap: ceiling.otherSessionCap || null,
     };
   }
   const headroomPoints = ceiling.percent - percent;

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

@@ -175,7 +175,7 @@ function bindingReset(now) {
 function sessionId(argv, env) {
   const at = argv.indexOf('--session-id');
   if (at !== -1 && argv[at + 1]) return argv[at + 1];
-  return env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || 'defer-' + Date.now().toString(36);
+  return env.CLAUDE_CODE_SESSION_ID || env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || 'defer-' + Date.now().toString(36);
 }
 
 function argOf(argv, name) {

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

@@ -192,7 +192,7 @@ function describe(settings, state) {
 function logSettingsChange(changes, direction, env) {
   if (!changes || !changes.length) return;
   const e = env || process.env;
-  const by = e.CLAUDE_SESSION_ID || e.CODEX_SESSION_ID ? 'claude' : 'user';
+  const by = e.CLAUDE_CODE_SESSION_ID || e.CLAUDE_SESSION_ID || e.CODEX_SESSION_ID ? 'claude' : 'user';
   try {
     const mode = require('./mode.js');
     for (const change of changes) {

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

@@ -388,6 +388,11 @@ function empty() {
     // reported: past it, fan-out calls are refused at the hook. Null means no
     // ceiling, and a ceiling nobody set never refuses anything. See ceiling.js.
     ceilingPercent: null,
+    // WHOSE cap it is. A cap is said about the work in front of someone, so
+    // it binds only in the session that set it; carrying it into the next one
+    // means refusing fan-outs on a fresh window for a reason nobody gave. A
+    // stored cap with no session here predates this rule and is ignored.
+    ceilingSession: null,
     setAt: null,
     setBy: null,
     session: null,
@@ -431,6 +436,7 @@ function read() {
   base.guardPercent = Number.isFinite(parsed.guardPercent) ? parsed.guardPercent : null;
   // Anything outside 1-100 is not a ceiling, and enforcing a number that was
   // never a percentage would refuse work over a typo.
+  base.ceilingSession = typeof parsed.ceilingSession === 'string' ? parsed.ceilingSession : null;
   base.ceilingPercent =
     Number.isFinite(parsed.ceilingPercent) && parsed.ceilingPercent > 0 && parsed.ceilingPercent <= 100
       ? parsed.ceilingPercent
@@ -1240,7 +1246,10 @@ function setMode(name, opts, now) {
   state.setAt = at;
   state.setBy = 'user';
   if (opts && Number.isFinite(opts.guard)) state.guardPercent = opts.guard;
-  if (opts && Number.isFinite(opts.ceiling)) state.ceilingPercent = opts.ceiling;
+  if (opts && Number.isFinite(opts.ceiling)) {
+    state.ceilingPercent = opts.ceiling;
+    state.ceilingSession = opts.sessionId || null;
+  }
   write(state);
   logChange({ plane: 'mode', key: 'mode', from: before, to: name, by: 'user', reason: null }, at);
 
@@ -1288,7 +1297,10 @@ function main(argv) {
     const next = args[at + 1];
     return next && next.indexOf('--') !== 0 ? next : null;
   };
-  const sessionId = value('--session-id') || process.env.CLAUDE_SESSION_ID || null;
+  // CLAUDE_CODE_SESSION_ID is the one Claude Code actually exports;
+  // CLAUDE_SESSION_ID never existed, so this read null and a cap set from the
+  // command line could record no owner and therefore never bind.
+  const sessionId = value('--session-id') || process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || null;
   const decided = resolve({ sessionId });
 
   if (flag('--list')) return list(decided);
@@ -1465,6 +1477,7 @@ function main(argv) {
     const state = read();
     const previous = state.ceilingPercent;
     state.ceilingPercent = ceilingArg.clear ? null : ceilingArg.percent;
+    state.ceilingSession = ceilingArg.clear ? null : sessionId;
     write(state);
     logChange(
       { plane: 'mode', key: 'ceiling', from: previous, to: state.ceilingPercent, by: 'user', reason: null },
@@ -1481,6 +1494,7 @@ function clearCeiling(now) {
   const state = read();
   const previous = state.ceilingPercent;
   state.ceilingPercent = null;
+  state.ceilingSession = null;
   write(state);
   logChange({ plane: 'mode', key: 'ceiling', from: previous, to: null, by: 'user', reason: null }, now);
 }
@@ -1493,10 +1507,11 @@ function ceilingLine() {
     return 'Ceiling off. Nothing is refused; the plugin reports and does not intervene.';
   }
   return (
-    'Ceiling ' + state.ceilingPercent + '%. Past that, fan-out calls (Agent, Task, Workflow and ' +
-    'their equivalents) are refused at the hook, in every session on this machine. Nothing else ' +
+    'Cap ' + state.ceilingPercent + '%' + (state.ceilingSession ? ', for THIS session only' : ' (stored against no session, so it is ignored - set it again to apply it here)') +
+    '. Past that, fan-out calls (Agent, Task, Workflow and ' +
+    'their equivalents) are refused at the hook. Nothing else ' +
     'is blocked, so the work still finishes - sequentially, in one session, which is where the ' +
-    'saving comes from. "mode --cap off" removes it.'
+    'saving comes from. It lapses when this session ends; "mode --cap off" removes it now.'
   );
 }
 

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

@@ -253,6 +253,8 @@ async function run(now, hookInput) {
         percent: ceilingPercent(now),
         state: budget.state,
         env: process.env,
+        // The cap only binds in the session that set it.
+        sessionId,
       });
       const call = ceiling.verdict(at, tool);
       if (call.decision === 'deny') return { deny: true, reason: call.reason };

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

@@ -521,8 +521,27 @@ function wakeAt(resetsAt, graceMinutes, now) {
   return Math.max(at, floor);
 }
 
-function taskName(id) {
-  return 'UsageLimitsRelay-' + String(id).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40);
+// One name per WAKE, not one per session.
+//
+// Reusing a name entangles every registration with the previous one's fate,
+// and all of it is undocumented: whether -Force truly replaces a stale
+// definition, what happens when a name is re-registered while its predecessor
+// is pending expiry-deletion, and whether an old EndBoundary survives the
+// update. On top of that MultipleInstances defaults to IgnoreNew, so a
+// previous run still held open by the four-hour execution limit silently
+// swallows the next launch.
+//
+// A unique suffix removes all of it at once, and lets DeleteExpiredTaskAfter
+// do what it should: each fired wake garbage-collects itself. cancelSchedule
+// works off the stored name, so nothing downstream changes.
+function taskName(id, at) {
+  const stamp = Number.isFinite(at) ? at : Date.now();
+  return (
+    'UsageLimitsRelay-' +
+    String(id).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40) +
+    '-' +
+    stamp.toString(36)
+  );
 }
 
 function psQuote(value) {
@@ -574,7 +593,45 @@ function remainingMs(deadline, ceiling) {
   return Math.max(0, Math.min(ceiling, left));
 }
 
+// Does Windows agree that this task will run?
+//
+// `state` and `next` come straight from Get-ScheduledTask and
+// Get-ScheduledTaskInfo. A task can register cleanly and still never fire,
+// and each of these has been seen: Disabled by policy or by an earlier
+// failure; NextRunTime empty because the trigger time had already passed by
+// the time it was written; NextRunTime set to something other than what was
+// asked for, meaning the trigger did not take. None of them raised an error
+// before, so the relay reported an armed wake and nothing happened.
+function verifyRegistration(state, next, wanted, now) {
+  const said = String(state || '').trim();
+  if (/disabled/i.test(said)) {
+    return { ok: false, error: 'the scheduled task registered but is Disabled, so it will not run' };
+  }
+  const text = String(next || '').trim();
+  if (!text) {
+    return { ok: false, error: 'the scheduled task registered but Windows reports no next run time, so it will not fire' };
+  }
+  const at = Date.parse(text);
+  if (!Number.isFinite(at)) {
+    return { ok: false, error: 'could not read the next run time Windows reported: ' + text };
+  }
+  if (at <= now) {
+    return { ok: false, error: 'the scheduled task next run time is already in the past' };
+  }
+  // Five minutes of slack: Task Scheduler rounds to the minute and a trigger
+  // can be nudged. Anything further out is a different time from the one asked
+  // for, which means the trigger did not take.
+  if (Number.isFinite(wanted) && Math.abs(at - wanted) > 5 * 60 * 1000) {
+    return {
+      ok: false,
+      error: 'the scheduled task is set for ' + new Date(at).toISOString() + ', not the requested ' + new Date(wanted).toISOString(),
+    };
+  }
+  return { ok: true, nextRun: at };
+}
+
 function scheduleWindows(when, argv, name, cwd, deadline) {
+  let lastVerifyError = null;
   const date = new Date(when);
   const stamp =
     date.getFullYear() + '-' + two(date.getMonth() + 1) + '-' + two(date.getDate()) + ' ' +
@@ -589,12 +646,33 @@ function scheduleWindows(when, argv, name, cwd, deadline) {
     // leaves a dead entry in Task Scheduler forever; the wake also unregisters
     // itself when it finishes, and this is what catches the wakes that never
     // get to run at all.
-    '$trigger.EndBoundary = (Get-Date ' + psQuote(stamp) + ').AddHours(12).ToString("s")',
+    // "zzz" is load-bearing. EndBoundary is documented as
+    // YYYY-MM-DDTHH:MM:SS(+-)HH:MM, and .ToString("s") emits no offset at
+    // all. A boundary written without one can be read as UTC, which west of
+    // Greenwich puts it HOURS IN THE PAST - so the task is born expired,
+    // never fires, and DeleteExpiredTaskAfter quietly reaps it. None of that
+    // raises an error: registration returns SCHED_S_SOME_TRIGGERS_FAILED
+    // (0x0004131B), which is a SUCCESS code, so PowerShell never throws and
+    // the relay reported a wake that could not happen.
+    '$trigger.EndBoundary = (Get-Date ' + psQuote(stamp) + ').AddHours(12).ToString("yyyy-MM-ddTHH:mm:sszzz")',
     '$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -WakeToRun -AllowStartIfOnBatteries ' +
       '-DontStopIfGoingOnBatteries -ExecutionTimeLimit (New-TimeSpan -Hours 4) ' +
       '-DeleteExpiredTaskAfter (New-TimeSpan -Minutes 10)',
     'Register-ScheduledTask -TaskName ' + psQuote(name) + ' -Action $action -Trigger $trigger -Settings $settings -Force | Out-Null',
-    'Write-Output "registered"',
+    // Ask Windows whether it will actually fire, rather than trusting that a
+    // registration which did not throw is a wake that will happen.
+    //
+    // This is the difference between "it said it would restart at 4:30 and
+    // nothing happened" and an error at arming time. Register-ScheduledTask
+    // reports success for a task that will never run: a trigger already in the
+    // past, a task left Disabled, a name whose previous registration is still
+    // being torn down. NextRunTime is the only field that answers the question
+    // actually being asked.
+    '$info = Get-ScheduledTaskInfo -TaskName ' + psQuote(name) + ' -ErrorAction SilentlyContinue',
+    '$state = (Get-ScheduledTask -TaskName ' + psQuote(name) + ' -ErrorAction SilentlyContinue).State',
+    '$next = ""',
+    'if ($info -and $info.NextRunTime) { $next = $info.NextRunTime.ToString("s") }',
+    'Write-Output ("registered|" + $state + "|" + $next)',
   ].join('\n');
   const file = path.join(os.tmpdir(), name + '.ps1');
   try {
@@ -604,7 +682,14 @@ function scheduleWindows(when, argv, name, cwd, deadline) {
       windowsHide: true,
       timeout: Math.max(500, remainingMs(deadline, 8000)),
     });
-    if (run.status === 0 && /registered/.test(run.stdout || '')) return { ok: true, how: 'ScheduledTasks' };
+    const registered = (run.stdout || '').match(/registered\|([^|\r\n]*)\|([^\r\n]*)/);
+    if (run.status === 0 && registered) {
+      const verdict = verifyRegistration(registered[1], registered[2], when, Date.now());
+      if (verdict.ok) return { ok: true, how: 'ScheduledTasks', nextRun: verdict.nextRun };
+      // Registered but it will not fire. Fall through to schtasks rather than
+      // reporting a wake that is not going to happen.
+      lastVerifyError = verdict.error;
+    }
     // No time left for a second attempt is a plain refusal, not a hung hook.
     if (remainingMs(deadline, 8000) < 1500) return { ok: false, error: 'no time left in this hook to register the wake; it will arm on the next prompt' };
     // schtasks cannot express StartWhenAvailable, so this path is a worse
@@ -618,7 +703,7 @@ function scheduleWindows(when, argv, name, cwd, deadline) {
       { encoding: 'utf8', windowsHide: true, timeout: Math.max(500, remainingMs(deadline, 8000)) }
     );
     if (fallback.status === 0) return { ok: true, how: 'schtasks', warning: 'a sleeping machine will miss this wake' };
-    return { ok: false, error: (run.stderr || fallback.stderr || 'could not register a scheduled task').trim().split('\n')[0] };
+    return { ok: false, error: (lastVerifyError || run.stderr || fallback.stderr || 'could not register a scheduled task').trim().split('\n')[0] };
   } catch (err) {
     return { ok: false, error: err.message };
   } finally {
@@ -725,7 +810,17 @@ function arm(input) {
 
   const state = read();
   const id = options.sessionId;
-  const name = taskName(id);
+  const name = taskName(id, when);
+  // Names are unique per wake now, so re-arming no longer replaces the old
+  // registration by name. Retire it explicitly, or every re-arm leaves a live
+  // task behind that would fire on its own.
+  if (state.armed && state.armed.task && state.armed.task !== name) {
+    try {
+      cancelSchedule(state.armed.task);
+    } catch (err) {
+      // The expiry removes it eventually either way.
+    }
+  }
   // Re-arming the same session for the same reset would register the task
   // twice; -Force replaces it, and the record is rewritten either way.
   const argv = [path.join(__dirname, 'wake.js'), '--id', id];
@@ -1234,6 +1329,7 @@ module.exports = {
   remainingMs,
   armByHand,
   schedule,
+  verifyRegistration,
   scheduleWindows,
   schedulePosix,
   cancelSchedule,