claude-usage-limits 1.39.4 → 1.39.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.39.4",
+  "version": "1.39.5",
   "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.39.4",
+  "version": "1.39.5",
   "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.39.4",
+  "version": "1.39.5",
   "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

@@ -157,9 +157,14 @@ async function run(now, input, argv) {
   return {};
 }
 
-if (require.main === module) {
-  readInput()
-    .then((input) => run(Date.now(), input, process.argv.slice(2)))
+// Read stdin, answer, exit zero. A function rather than a bare block because
+// the installer's launcher calls it: see install-antigravity.js, which writes a
+// two-line launcher beside hooks.json so the hook command carries no path and
+// therefore no quotes for `cmd /c` to mangle.
+function main(argv) {
+  const args = argv || [];
+  return readInput()
+    .then((input) => run(Date.now(), input, args))
     .then(
       (result) => {
         process.stdout.write(JSON.stringify(result || {}) + '\n');
@@ -169,11 +174,13 @@ if (require.main === module) {
         // Hooks block the agent loop here, so a failure has to be silent and
         // well formed rather than loud - and on PreToolUse, well formed means
         // an explicit allow, never a bare {} that reads as a refusal.
-        const pre = process.argv.slice(2).join(' ').includes('--event PreToolUse');
+        const pre = args.join(' ').includes('--event PreToolUse');
         process.stdout.write(JSON.stringify(pre ? ALLOW : {}) + '\n');
         process.exit(0);
       }
     );
 }
 
-module.exports = { EVENTS, ALLOW, eventFrom, toolNameOf, percentNow, run };
+if (require.main === module) main(process.argv.slice(2));
+
+module.exports = { EVENTS, ALLOW, eventFrom, toolNameOf, percentNow, run, main };

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

@@ -64,6 +64,10 @@ const DEFAULTS = {
 // A hook has ten seconds; the reading gets four of them at most.
 const REFRESH_TIMEOUT_MS = 4000;
 
+// What the hook is actually given before it is killed. Claude Code and Codex
+// both use ten seconds (hooks/hooks.json, install-codex-hook.js).
+const HOOK_BUDGET_MS = 10000;
+
 // The hook is given ten seconds, and a live reading may take four of them, so
 // the transcript scan gets five and the last second is slack. A warm scan
 // takes about a quarter of a second; this is the guard for the first run on a
@@ -71,6 +75,28 @@ const REFRESH_TIMEOUT_MS = 4000;
 // killed and Claude being told nothing at all.
 const SCAN_BUDGET_MS = 5000;
 
+// How long the live reading may actually wait, given how much of the hook's ten
+// seconds is already gone.
+//
+// Four seconds for the reading plus five for the scan plus a second of slack
+// only adds up if the hook starts at zero, and it never does: node's own
+// start-up, the requires, and reading the hook payload all come out of the same
+// budget, and on a loaded machine that is most of a second before this line is
+// reached. `process.uptime()` is the honest elapsed figure. Past the point
+// where the scan would no longer fit, the reading on disk is used as it is
+// rather than the hook being killed with nothing to say.
+function refreshBudgetMs(options) {
+  const opts = options || {};
+  const configured = Number(
+    opts.hookBudgetMs !== undefined ? opts.hookBudgetMs : process.env.USAGE_LIMITS_HOOK_BUDGET_MS
+  );
+  const total = Number.isFinite(configured) && configured > 0 ? configured : HOOK_BUDGET_MS;
+  const elapsed = Number.isFinite(opts.elapsedMs) ? opts.elapsedMs : process.uptime() * 1000;
+  const reserve = Number.isFinite(opts.reserveMs) ? opts.reserveMs : SCAN_BUDGET_MS + 1000;
+  const most = Number.isFinite(opts.maxMs) ? opts.maxMs : REFRESH_TIMEOUT_MS;
+  return Math.max(0, Math.min(most, Math.round(total - elapsed - reserve)));
+}
+
 // How far into the hook arming may still start. See relayState: the task
 // registration is about a second and the hook is allowed ten.
 const ARM_DEADLINE_MS = 5000;
@@ -1495,21 +1521,29 @@ async function run(now, hookInput, opts) {
     } else if (usage.isCodex()) {
       // Codex only writes its meter when it makes a request, so between turns
       // the newest figure can be half an hour old. Ask it, the way /status
-      // does, when the reading has aged.
+      // does, when the reading has aged - but never inside this hook. The
+      // reading means starting `codex app-server`, whose cold start alone has
+      // been measured past four seconds, and Codex kills a hook at ten. So the
+      // refresh is started detached and the next hook reads what it wrote.
       await require('./codex.js').refreshIfStale({
         now,
         maxAgeMs: refreshSeconds * SECOND,
-        timeoutMs: REFRESH_TIMEOUT_MS,
+        detach: true,
       });
     } else {
       const cached = usage.collect(now);
-      await live.refreshIfStale({
-        now,
-        maxAgeMs: refreshSeconds * SECOND,
-        cacheFetchedAtMs: cached.snapshotFetchedAt,
-        accountUuid: usage.accountUuid(),
-        timeoutMs: REFRESH_TIMEOUT_MS,
-      });
+      const waitMs = refreshBudgetMs();
+      // No room left in the hook for a network call: the figure on disk stands
+      // and the next prompt tries again.
+      if (waitMs > 0) {
+        await live.refreshIfStale({
+          now,
+          maxAgeMs: refreshSeconds * SECOND,
+          cacheFetchedAtMs: cached.snapshotFetchedAt,
+          accountUuid: usage.accountUuid(),
+          timeoutMs: waitMs,
+        });
+      }
     }
   } catch (err) {
     // The reading on disk is still there.
@@ -1773,6 +1807,10 @@ function withBugcheck(text) {
 module.exports = { withBugcheck, sayOnce, shapeOf, saidFile, REPEAT_MS, staleVersionFor, relayNewsFor, installedVersion, runningVersion,
   readSaid, standingSaid, markStanding, standingShortFor, STANDING_SHORT, cacheMissWhyFor, missReason, MISS_RECENT_MS,
   DEFAULTS,
+  HOOK_BUDGET_MS,
+  REFRESH_TIMEOUT_MS,
+  SCAN_BUDGET_MS,
+  refreshBudgetMs,
   aheadOfPace,
   pacingMatters,
   PACE_MIN_SPAN_MS,

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

@@ -830,6 +830,72 @@ function attemptFile() {
   return path.join(homeDir(), 'usage-limits-codex-fetch.json');
 }
 
+// How long a detached refresh is given before another hook may start one. The
+// child is not waited on, so this claim is the only thing stopping every hook
+// in a burst from launching its own app-server.
+const DETACHED_GUARD_MS = 45 * 1000;
+
+// A detached refresh sits outside everybody's hook budget, so it can afford to
+// wait out a cold start instead of giving up at four seconds.
+const DETACHED_TIMEOUT_MS = 25 * 1000;
+
+// Start the refresh in a child nobody waits for.
+//
+// This is the answer to the hook timeout. Codex kills a hook at ten seconds,
+// and `codex app-server` can take more than four to answer cold - so a hook
+// that waits for the reading is a hook that gets killed, and a killed hook
+// says nothing at all. Here the hook returns immediately and the reading lands
+// in liveFile() a second or two later, where the NEXT hook reads it. One turn
+// of latency for a figure that is refreshed every few minutes anyway.
+function spawnRefresh(options) {
+  const opts = options || {};
+  const spawn = opts.spawn || require('child_process').spawn;
+  const args = [__filename, '--refresh-meter'];
+  if (opts.codexPath) args.push('--codex-path', String(opts.codexPath));
+  const child = spawn(opts.execPath || process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    // The child reads CODEX_HOME to find the same home directory this process
+    // is using, so a test or a non-default install refreshes the right file.
+    env: Object.assign({}, opts.env || process.env, { CODEX_HOME: homeDir() }),
+  });
+  if (child && typeof child.unref === 'function') child.unref();
+  return child;
+}
+
+// Take the reading and record it, with no staleness or backoff check. This is
+// the half of refreshIfStale() that actually costs something, split out so the
+// detached child can run it without tripping over the in-flight claim the
+// parent just wrote.
+async function fetchAndRecord(options) {
+  const opts = options || {};
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const maxAgeMs = Number.isFinite(opts.maxAgeMs) ? opts.maxAgeMs : 3 * MINUTE;
+  const claim = (delayMs, kind) => {
+    try {
+      fs.writeFileSync(attemptFile(), JSON.stringify({ attemptedAtMs: now, delayMs, kind }), 'utf8');
+    } catch (err) {
+      // One extra attempt is survivable.
+    }
+  };
+  try {
+    const reading = await refresh({ codexPath: opts.codexPath, timeoutMs: opts.timeoutMs });
+    if (!reading || !reading.meter) {
+      claim(maxAgeMs, 'empty');
+      return { reading: null, error: 'no meter' };
+    }
+    writeLiveMeter(reading);
+    claim(maxAgeMs, 'ok');
+    return { reading, error: null };
+  } catch (err) {
+    // Codex missing or not answering: back off rather than pay for it again on
+    // every prompt.
+    claim(Math.min(10 * MINUTE, Math.max(2 * MINUTE, maxAgeMs * 2)), (err && err.code) || 'error');
+    return { reading: null, error: (err && err.code) || 'error' };
+  }
+}
+
 // Ask Codex for the meter, but only when the newest reading on disk has aged,
 // and never twice in quick succession. Codex writes its meter into a rollout
 // only when it makes a request, so between turns the newest reading can be
@@ -869,23 +935,32 @@ async function refreshIfStale(options) {
       // One extra attempt is survivable.
     }
   };
-  claim(Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000, 'inflight');
-
-  try {
-    const reading = await refresh({ codexPath: opts.codexPath, timeoutMs: opts.timeoutMs });
-    if (!reading || !reading.meter) {
-      claim(maxAgeMs, 'empty');
-      return { reading: live, skipped: null, error: 'no meter' };
+  // The hook's own path: start the reading and get out of the way. Waiting for
+  // `codex app-server` inside a hook is what overran Codex's ten-second limit
+  // under load - the cold start alone has been measured past four seconds, and
+  // the brief still has a transcript scan to do after it. The child writes the
+  // meter file; the next hook reads it.
+  if (opts.detach) {
+    claim(DETACHED_GUARD_MS, 'detached');
+    try {
+      spawnRefresh({ codexPath: opts.codexPath, spawn: opts.spawn, execPath: opts.execPath, env: env });
+    } catch (err) {
+      claim(Math.max(2 * MINUTE, maxAgeMs), 'spawn-failed');
+      return { reading: live, skipped: null, error: 'spawn failed' };
     }
-    writeLiveMeter(reading);
-    claim(maxAgeMs, 'ok');
-    return { reading, skipped: null };
-  } catch (err) {
-    // Codex missing or not answering: back off rather than pay for it again on
-    // every prompt.
-    claim(Math.min(10 * MINUTE, Math.max(2 * MINUTE, maxAgeMs * 2)), (err && err.code) || 'error');
-    return { reading: live, skipped: null, error: (err && err.code) || 'error' };
+    return { reading: live, skipped: 'detached' };
   }
+
+  claim(Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000, 'inflight');
+
+  const done = await fetchAndRecord({
+    now,
+    maxAgeMs,
+    timeoutMs: opts.timeoutMs,
+    codexPath: opts.codexPath,
+  });
+  if (done.error) return { reading: live, skipped: null, error: done.error };
+  return { reading: done.reading, skipped: null };
 }
 
 function collect(now, options) {
@@ -1093,10 +1168,39 @@ function refresh(options) {
   });
 }
 
+// The detached refresh, run as `node codex.js --refresh-meter`. Nothing waits
+// for this process, so it can spend the cold start a hook cannot.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (argv[0] !== '--refresh-meter') {
+    process.stderr.write('codex.js: only --refresh-meter is runnable\n');
+    process.exitCode = 2;
+  } else {
+    const at = argv.indexOf('--codex-path');
+    fetchAndRecord({
+      now: Date.now(),
+      timeoutMs: DETACHED_TIMEOUT_MS,
+      codexPath: at !== -1 ? argv[at + 1] : null,
+    })
+      .catch(() => null)
+      .then(() => {
+        // The app-server is asked to stop by having its stdin closed, which
+        // refresh() has already done. This timer is deliberately not unref'd:
+        // it is the one thing that ends this process if the child it started
+        // does not exit on its own.
+        setTimeout(() => process.exit(0), 2000);
+      });
+  }
+}
+
 module.exports = {
   SLOTS,
   WEIGHTS,
   PLANS,
+  DETACHED_GUARD_MS,
+  DETACHED_TIMEOUT_MS,
+  spawnRefresh,
+  fetchAndRecord,
   normalizeMeter,
   homeDir,
   sessionsDir,

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

@@ -44,20 +44,66 @@ function pluginDir() {
 }
 
 // Forward slashes on every platform. They work in Windows paths and keep the
-// command free of escapes in both JSON and the shell that runs it. Antigravity
-// runs hook commands through `cmd /c` on Windows and `sh -c` elsewhere, so the
-// quoting has to survive both.
-function quote(file) {
-  const normalized = String(file).replace(/\\/g, '/');
-  return normalized.includes(' ') ? '"' + normalized + '"' : normalized;
+// command free of escapes in both JSON and the shell that runs it.
+function slashes(file) {
+  return String(file).replace(/\\/g, '/');
 }
 
 function scriptPath(name) {
   return path.join(__dirname, name);
 }
 
-function hookCommand(event) {
-  return 'node ' + quote(scriptPath('agy-hook.js')) + ' --event ' + event;
+// The name of the launcher written beside hooks.json.
+const LAUNCHER = 'agy-hook.js';
+
+// A hook command a shell cannot mangle.
+//
+// Antigravity runs hook commands through `cmd /c` on Windows. It does not pass
+// /s, so cmd applies its own quote rule: the outer quotes are stripped only
+// when the string carries exactly one pair. A path with a space in it needs a
+// pair of its own, which makes three, and cmd then keeps them all - the command
+// name becomes the whole quoted string and node is handed `C:/Users/Some` as
+// its script. That is not a theory: a checkout under a directory with a space
+// in its name installed cleanly and every hook then failed silently, because
+// Antigravity reports nothing when a hook cannot start.
+//
+// So the command carries no quotes at all, which means it must carry no spaces
+// either. Two ways to get there, and the one used depends on the path:
+//
+//   - the plugin directory has no space: name the launcher absolutely, exactly
+//     as before, and nothing depends on the working directory
+//   - it does: name it relatively. Hooks run with their working directory set
+//     to the folder holding hooks.json, which is where the launcher is written
+//
+// Either way the real path into this checkout lives inside the launcher, as
+// JavaScript, where no shell ever sees it.
+function launcherPath() {
+  return path.join(pluginDir(), LAUNCHER);
+}
+
+function hookCommand(event, dir) {
+  const absolute = slashes(dir === undefined ? launcherPath() : path.join(dir, LAUNCHER));
+  const target = absolute.includes(' ') ? LAUNCHER : absolute;
+  return 'node ' + target + ' --event ' + event;
+}
+
+// The launcher itself. It exists so the command above needs no path: requiring
+// the real script by absolute path is a string in a JS file, which survives any
+// amount of shell quoting, and calling main() is what `node agy-hook.js` would
+// have done.
+function launcherText() {
+  return [
+    "'use strict';",
+    '',
+    '// Written by install-antigravity.js. Do not edit: `on` rewrites it.',
+    '//',
+    '// The hook command that runs this file carries no path and no quotes,',
+    "// because Antigravity's `cmd /c` keeps the quotes around a path with a",
+    '// space in it and node is then handed a truncated script name. The path',
+    '// lives here instead, where only node reads it.',
+    'require(' + JSON.stringify(slashes(scriptPath('agy-hook.js'))) + ').main(process.argv.slice(2));',
+    '',
+  ].join('\n');
 }
 
 function manifest() {
@@ -155,6 +201,9 @@ function enable() {
   }
   const dir = pluginDir();
   writeFile(path.join(dir, 'plugin.json'), JSON.stringify(manifest(), null, 2) + '\n');
+  // Before hooks.json, so the file the commands name is never missing while
+  // they are readable.
+  writeFile(path.join(dir, LAUNCHER), launcherText());
   writeFile(path.join(dir, 'hooks.json'), JSON.stringify(hooks(), null, 2) + '\n');
   const rules = rulesText();
   if (rules) writeFile(path.join(dir, 'rules', 'AGENTS.md'), rules);
@@ -178,7 +227,7 @@ function disable() {
   const dir = pluginDir();
   if (!installed()) return 'Not installed. Nothing to remove.';
   const removed = [];
-  for (const relative of ['plugin.json', 'hooks.json', path.join('rules', 'AGENTS.md')]) {
+  for (const relative of ['plugin.json', 'hooks.json', LAUNCHER, path.join('rules', 'AGENTS.md')]) {
     const file = path.join(dir, relative);
     try {
       fs.unlinkSync(file);

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

@@ -312,16 +312,26 @@ async function run(now, hookInput) {
   // against the account rather than against a guess from its own transcript.
   try {
     if (usage.isCodex()) {
-      await require('./codex.js').refreshIfStale({ now, maxAgeMs: every, timeoutMs: 4000 });
+      // Never waited on inside the hook. `codex app-server` can take longer to
+      // answer cold than this hook is allowed to live, and a killed PostToolUse
+      // hook is a tool call that stalls. The child writes the meter file and
+      // the next pulse reads it.
+      await require('./codex.js').refreshIfStale({ now, maxAgeMs: every, detach: true });
     } else {
       const cached = usage.collect(now);
-      await live.refreshIfStale({
-        now,
-        maxAgeMs: every,
-        cacheFetchedAtMs: cached.snapshotFetchedAt,
-        accountUuid: usage.accountUuid(),
-        timeoutMs: 4000,
-      });
+      // Sized from what is left of the hook's ten seconds, not from a constant:
+      // this hook interrupts work in progress, so being late is worse here than
+      // anywhere else.
+      const waitMs = brief.refreshBudgetMs({ reserveMs: SCAN_BUDGET_MS + 1000 });
+      if (waitMs > 0) {
+        await live.refreshIfStale({
+          now,
+          maxAgeMs: every,
+          cacheFetchedAtMs: cached.snapshotFetchedAt,
+          accountUuid: usage.accountUuid(),
+          timeoutMs: waitMs,
+        });
+      }
     }
   } catch (err) {
     // The reading on disk is still there.