claude-usage-limits 1.13.0 → 1.13.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "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.13.0",
+  "version": "1.13.2",
   "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/commands/relay.md

@@ -31,6 +31,11 @@ The rest:
 - `thinking off|resume|always` - `resume` puts the word ultrathink into the
   prompt the relay delivers. `always` sets `alwaysThinkingEnabled` in your
   settings, backs the file up first, and applies to new sessions.
+- `arm [--session <id>] ["<text>"]` - arm by hand, against the binding
+  window's reset, without waiting for the hook to see a todo list. This is the
+  way under Codex, which writes no plan tool into its rollouts for the hook to
+  read, and for any project that lives in your head rather than a list. Any
+  text given is stored as the continuation.
 - `note "<text>"` (or `note --file <path>`) - store the continuation. This is
   the text that gets delivered, so write it to be acted on: what is done, what
   is next in order, which files are mid-change, what to verify first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "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/brief.js

@@ -815,6 +815,9 @@ function relayState(now, hookInput, binding, sessionId) {
     const armed = relay.arm({
       now,
       config,
+      // Registration must be finished, not merely started, inside the hook's
+      // ten seconds; the scheduler trims its own waits to this.
+      deadline: now + ARM_DEADLINE_MS + 4000,
       sessionId,
       binding,
       work,
@@ -914,6 +917,11 @@ async function run(now, hookInput) {
       turnsLeft: binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
       session: data.session,
       othersSummary: summariseOthers(data.windows, binding && binding.key),
+      // Every window, trimmed to the cacheable fields, so the corrected reading
+      // can be recorded for all three columns of the status line on a cache
+      // hit too. Recording the binding window alone left the other two at
+      // their raw snapshots on every short turn, where the pulse never runs.
+      windows: (data.windows || []).map(cacheableBinding),
       sessions: data.sessions,
       staleWindows: data.staleWindows,
       planChanged: data.planChanged,
@@ -954,7 +962,7 @@ async function run(now, hookInput) {
   // too often to scan for itself, and without this it shows the raw snapshot,
   // which during a heavy session is wrong by tens of points in the flattering
   // direction.
-  reading.record(binding, now, usage.isCodex() ? require('./codex.js').homeDir() : null);
+  reading.recordAll(view.windows && view.windows.length ? view.windows : [binding], now, usage.isCodex() ? require('./codex.js').homeDir() : null);
   const carry = relayState(now, hookInput, binding, sessionId);
   // An instruction the user typed at /usage-limits:voice set. The learned
   // traits are for writing AS them and stay out of the way; this is them

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

@@ -89,7 +89,13 @@ function record(binding, now, codexHome) {
       else if (Number.isFinite(entry.resetsAt) && entry.resetsAt <= at) delete all[key];
     }
     fs.mkdirSync(path.dirname(readingFile(codexHome)), { recursive: true });
-    fs.writeFileSync(readingFile(codexHome), JSON.stringify(all));
+    // Write beside and rename: the prompt hook and the pulse can both land
+    // here in the same second, and a reader between a truncate and a write
+    // would see half a file.
+    const file = readingFile(codexHome);
+    const tmp = file + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(all));
+    fs.renameSync(tmp, file);
     return true;
   } catch (err) {
     return false;

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

@@ -114,10 +114,19 @@ function read() {
   };
 }
 
+// Written to a sibling and renamed into place. Two hooks can run at once, and a
+// reader that lands between the truncate and the write of a plain writeFileSync
+// sees half a file; the rename is the only step another process can observe.
+function writeAtomic(file, text) {
+  const tmp = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, file);
+}
+
 function write(state) {
   try {
     fs.mkdirSync(configDir(), { recursive: true });
-    fs.writeFileSync(relayFile(), JSON.stringify(state, null, 2) + '\n');
+    writeAtomic(relayFile(), JSON.stringify(state, null, 2) + '\n');
     return true;
   } catch (err) {
     return false;
@@ -432,6 +441,31 @@ function psQuote(value) {
   return "'" + String(value).replace(/'/g, "''") + "'";
 }
 
+// One argument, quoted the way CommandLineToArgvW will unquote it. The rule
+// that matters and that a naive version misses: a backslash is only an escape
+// when it precedes a quote, so a run of backslashes before the closing quote
+// has to be doubled or the quote is eaten - which is exactly what a config
+// directory ending in a backslash did to the wake's command line.
+function winArg(value) {
+  const text = String(value);
+  if (!/[\s"]/.test(text)) return text;
+  let out = '"';
+  let slashes = 0;
+  for (const ch of text) {
+    if (ch === '\\') {
+      slashes += 1;
+      continue;
+    }
+    if (ch === '"') {
+      out += '\\'.repeat(slashes * 2 + 1) + '"';
+    } else {
+      out += '\\'.repeat(slashes) + ch;
+    }
+    slashes = 0;
+  }
+  return out + '\\'.repeat(slashes * 2) + '"';
+}
+
 function two(value) {
   return String(value).padStart(2, '0');
 }
@@ -442,12 +476,22 @@ function two(value) {
 // silently and forever. -StartWhenAvailable makes it fire on wake instead,
 // which is the whole difference between a relay and a coin toss. schtasks is
 // still the fallback for a box where the module is missing.
-function scheduleWindows(when, argv, name, cwd) {
+// The two registrations below are bounded by the caller's deadline, not by a
+// fixed figure: from inside a hook there may be a few seconds left, from the
+// command line there are as many as it takes. Measured once at 38 seconds
+// worst case when both spawns waited their full fixed timeouts, inside a hook
+// that is killed at ten.
+function remainingMs(deadline, ceiling) {
+  const left = Number.isFinite(deadline) ? deadline - Date.now() : ceiling;
+  return Math.max(0, Math.min(ceiling, left));
+}
+
+function scheduleWindows(when, argv, name, cwd, deadline) {
   const date = new Date(when);
   const stamp =
     date.getFullYear() + '-' + two(date.getMonth() + 1) + '-' + two(date.getDate()) + ' ' +
     two(date.getHours()) + ':' + two(date.getMinutes()) + ':' + two(date.getSeconds());
-  const argument = argv.map((value) => (/[\s"]/.test(value) ? '"' + value.replace(/"/g, '\\"') + '"' : value)).join(' ');
+  const argument = argv.map(winArg).join(' ');
   const script = [
     '$ErrorActionPreference = "Stop"',
     '$action = New-ScheduledTaskAction -Execute ' + psQuote(process.execPath) +
@@ -470,9 +514,11 @@ function scheduleWindows(when, argv, name, cwd) {
     const run = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', file], {
       encoding: 'utf8',
       windowsHide: true,
-      timeout: 8000,
+      timeout: Math.max(500, remainingMs(deadline, 8000)),
     });
     if (run.status === 0 && /registered/.test(run.stdout || '')) return { ok: true, how: 'ScheduledTasks' };
+    // 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
     // guarantee and says so rather than pretending the two are the same.
     const fallback = spawnSync(
@@ -481,7 +527,7 @@ function scheduleWindows(when, argv, name, cwd) {
         '/ST', two(date.getHours()) + ':' + two(date.getMinutes()),
         '/SD', two(date.getMonth() + 1) + '/' + two(date.getDate()) + '/' + date.getFullYear(),
         '/IT', '/Z', '/F'],
-      { encoding: 'utf8', windowsHide: true, timeout: 30000 }
+      { 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] };
@@ -524,8 +570,8 @@ function schedulePosix(when, argv, name, cwd) {
   }
 }
 
-function schedule(when, argv, name, cwd) {
-  if (process.platform === 'win32') return scheduleWindows(when, argv, name, cwd);
+function schedule(when, argv, name, cwd, deadline) {
+  if (process.platform === 'win32') return scheduleWindows(when, argv, name, cwd, deadline);
   return schedulePosix(when, argv, name, cwd);
 }
 
@@ -579,7 +625,7 @@ function arm(input) {
   // pointed at the same one or it reads somebody else's relay - which in
   // testing meant it read the real one and found nothing armed.
   if (process.env.CLAUDE_CONFIG_DIR) argv.push('--config-dir', process.env.CLAUDE_CONFIG_DIR);
-  const scheduled = options.schedule === false ? { ok: true, how: 'none' } : schedule(when, argv, name, options.cwd);
+  const scheduled = options.schedule === false ? { ok: true, how: 'none' } : schedule(when, argv, name, options.cwd, options.deadline);
   if (!scheduled.ok) {
     note('arm failed for ' + id + ': ' + scheduled.error, now);
     return { ok: false, error: scheduled.error };
@@ -698,7 +744,10 @@ function applyAlwaysThinking(on) {
   try {
     const raw = fs.readFileSync(file, 'utf8');
     existed = true;
-    parsed = JSON.parse(raw);
+    // Editors on Windows save JSON with a byte order mark often enough that
+    // refusing it would read as "your settings file is broken" to somebody
+    // whose settings file is fine.
+    parsed = JSON.parse(raw.replace(/^/, ''));
     fs.writeFileSync(file + '.bak-usage-limits', raw);
   } catch (err) {
     if (existed) return { ok: false, error: 'settings.json is not readable JSON; left untouched' };
@@ -715,6 +764,42 @@ function applyAlwaysThinking(on) {
   return { ok: true, file, backup: existed ? file + '.bak-usage-limits' : null };
 }
 
+// `relay arm [--session <id>] [note text]`: take the current reading, book the
+// wake against the binding window's reset, and store any text given as the
+// continuation. Uses the report rather than the hook's cache, so it costs a
+// scan; that is fine from a command line.
+async function armByHand(rest) {
+  const usage = require('./usage.js');
+  usage.setHost(host.detect(process.argv.slice(2), process.env));
+  const config = configure({ enabled: true });
+  const now = Date.now();
+  const data = await usage.report(now, {});
+  const binding = data && data.binding;
+  if (!binding || !Number.isFinite(binding.resetsAt)) return 'No window with a known reset time to arm against; run /usage and try again.';
+  const at = rest.indexOf('--session');
+  const sessionId = at !== -1 && rest[at + 1] ? rest[at + 1] : (data.session && data.session.id) || null;
+  if (!sessionId) return 'No session id: pass --session <id> (from usage.js --sessions).';
+  const text = rest.filter((item, i) => item !== '--session' && !(at !== -1 && i === at + 1)).join(' ').trim();
+  const result = arm({
+    now,
+    config,
+    sessionId,
+    binding,
+    resetsAt: binding.resetsAt,
+    cwd: process.cwd(),
+    project: path.basename(process.cwd()),
+    hostName: usage.currentHost(),
+    work: { hasWork: true, pending: 1, source: 'manual', todos: [], plan: text || null },
+  });
+  if (!result.ok) return 'Could not arm: ' + result.error;
+  if (text) saveContinuation(sessionId, text);
+  return (
+    'Armed by hand for session ' + sessionId.slice(0, 8) + ': wake at ' +
+      new Date(result.record.wakeAt).toLocaleString() + ' via ' + result.record.how + '.' +
+      (text ? ' Continuation saved.' : ' No continuation yet - add one with: relay note "<text>"')
+  );
+}
+
 /* ----------------------------------------------------------------- cli ---- */
 
 function main(argv) {
@@ -796,6 +881,10 @@ function main(argv) {
     const result = disarm('cancelled by hand', Date.now());
     return result.changed ? 'Relay cancelled and the scheduled wake removed.' : 'Nothing was armed.';
   }
+  // Arming by hand, for the cases the hook cannot see: Codex writes no plan
+  // tool into its rollouts, so nothing there ever reads as work to carry; and
+  // a person can have a project in their head that is in no todo list.
+  if (command === 'arm') return armByHand(rest);
   if (command === 'log') {
     try {
       return fs.readFileSync(logFile(), 'utf8').split('\n').slice(-20).join('\n');
@@ -804,19 +893,25 @@ function main(argv) {
     }
   }
   return [
-    'usage: relay.js [status|on|off|at N|grace N|mode notify|resume|permission MODE|model NAME|thinking off|resume|always|note TEXT|cancel|log]',
+    'usage: relay.js [status|on|off|at N|grace N|mode notify|resume|permission MODE|model NAME|thinking off|resume|always|arm [--session ID] [TEXT]|note TEXT|cancel|log]',
     '',
     status(Date.now()),
   ].join('\n');
 }
 
 if (require.main === module) {
-  try {
-    process.stdout.write(main(process.argv.slice(2)) + '\n');
-  } catch (err) {
-    process.stdout.write('relay: ' + err.message + '\n');
-  }
-  process.exit(0);
+  Promise.resolve()
+    .then(() => main(process.argv.slice(2)))
+    .then(
+      (text) => {
+        process.stdout.write(text + '\n');
+        process.exit(0);
+      },
+      (err) => {
+        process.stdout.write('relay: ' + err.message + '\n');
+        process.exit(0);
+      }
+    );
 }
 
 module.exports = {
@@ -847,6 +942,9 @@ module.exports = {
   wakeAt,
   taskName,
   psQuote,
+  winArg,
+  remainingMs,
+  armByHand,
   schedule,
   scheduleWindows,
   schedulePosix,

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

@@ -144,13 +144,14 @@ function planOn(settings, state, options) {
   const opts = options || {};
   const launcher = opts.launcher || launcherFile();
   const existing = current.statusLine === undefined ? null : current.statusLine;
-  // A second "on" must not record our own launcher as the thing to restore.
-  const previous =
-    state && Object.prototype.hasOwnProperty.call(state, 'previous')
-      ? state.previous
-      : isOurs(existing, launcher)
-        ? null
-        : existing;
+  // What "off" must put back is whatever is in the settings right now that is
+  // not ours. A second "on" must not record our own launcher as that thing -
+  // but it must not keep an old memory either: a status line the user set
+  // between two "on" runs was being overwritten and lost, because the first
+  // run's record was trusted over the file in front of us.
+  const remembered =
+    state && Object.prototype.hasOwnProperty.call(state, 'previous') ? state.previous : null;
+  const previous = isOurs(existing, launcher) ? remembered : existing;
   const command = 'node ' + JSON.stringify(launcher);
   const statusLine = { type: 'command', command };
   if (Number.isFinite(opts.refresh) && opts.refresh >= 1) statusLine.refreshInterval = Math.floor(opts.refresh);

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

@@ -1272,7 +1272,12 @@ function codexBlock(now) {
 // The warning that would have caught that incident: what the window holds at
 // the effort actually set, rather than at the average of everything ever run.
 function effortWarning(events, current, window) {
-  if (!current || !window || window.stale) return null;
+  // Once spending has outrun the snapshot, percentLeft and usdPerPercent are
+  // a floor and a stale price. buildWindow nulls the turn count for that
+  // reason, and this function was quietly recomputing one from the two fields
+  // it left behind - printing "at ultra effort this window holds about 104
+  // turns" beside the warning that the window may already be exhausted.
+  if (!current || !window || window.stale || window.correctionUnreliable) return null;
   const rates = effortRates(events);
   const here = rates.find((row) => row.effort === current);
   if (!here || here.turns < MIN_EFFORT_SAMPLE || !here.perTurn || here.perTurn <= 0) return null;
@@ -2080,7 +2085,9 @@ function criticalOthers(windows, bindingKey, threshold) {
       // do about it is less work, against a limit its work never touches.
       w.applies !== false &&
       w.percentUsed !== null &&
-      w.percentUsed >= limit
+      // A window whose spend has outrun its snapshot reads as its old floor;
+      // it belongs in this list whatever that floor says.
+      (w.percentUsed >= limit || w.correctionUnreliable)
   );
 }
 
@@ -2107,6 +2114,11 @@ function bindingWindow(windows) {
   // 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) => {
+    // Spend that has outrun the snapshot leaves percentUsed at the old floor
+    // and headroomMs empty, so on those two numbers alone the fullest window
+    // on the account ranked as the least urgent one. It is the most urgent:
+    // the budget it describes may already be gone.
+    if (w.correctionUnreliable) return 0;
     if (Number.isFinite(w.headroomMs)) return w.headroomMs;
     return w.percentUsed >= 90 ? 0 : Infinity;
   };

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

@@ -89,8 +89,12 @@ async function windowReopened(record, now) {
       const codex = require('./codex.js');
       await codex.refresh({ now, timeoutMs: 8000 }).catch(() => null);
       const collected = codex.collect(now);
-      const percent = collected && collected.utilization ? Number(collected.utilization.primary) : null;
-      return { known: Number.isFinite(percent), percent };
+      // Same shape as the Claude side: keyed by window, each { utilization }.
+      // Reading a flat "primary" that codex.collect never writes answered
+      // "cannot tell" every time and disabled this check under Codex.
+      const bucket = collected && collected.utilization ? collected.utilization[record.windowKey || 'five_hour'] : null;
+      const value = bucket && typeof bucket.utilization === 'number' ? bucket.utilization : null;
+      return { known: value !== null, percent: value };
     }
     const live = require('./live.js');
     const usage = require('./usage.js');