claude-usage-limits 1.39.4 → 1.39.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.39.4",
+  "version": "1.39.6",
   "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.6",
   "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.6",
   "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/activity.js

@@ -14,6 +14,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
+
 const KEEP_SESSIONS = 8;
 // A session that has said nothing for this long is not working, whatever its
 // last word was: a crash never sends Stop.
@@ -68,22 +70,8 @@ function mark(state, sessionId, extra, now) {
     if (extra && extra.model) entry.model = String(extra.model);
     else if (previous.model) entry.model = previous.model;
     all[sessionId || '_'] = entry;
-    const file = activityFile();
-    const temp = file + '.' + process.pid + '.usage-limits-tmp';
-    try {
-      fs.mkdirSync(path.dirname(file), { recursive: true });
-      fs.writeFileSync(temp, JSON.stringify(trim(all)), 'utf8');
-      fs.renameSync(temp, file);
-    } catch (err) {
-      // A rename Windows refused leaves nothing behind.
-      try {
-        fs.unlinkSync(temp);
-      } catch (gone) {
-        // Nothing to clean up.
-      }
-      return false;
-    }
-    return true;
+    // A rename Windows refused leaves nothing behind: see atomic.js.
+    return atomic.tryWriteFileAtomic(activityFile(), JSON.stringify(trim(all)));
   } catch (err) {
     return false;
   }

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/atomic.js

@@ -0,0 +1,173 @@
+'use strict';
+
+// Every file this plugin replaces goes through here: written beside the target
+// under a name that is this process's own, then renamed into place, so a
+// reader sees either the old whole file or the new whole file.
+//
+// On Windows that rename is the step that fails. Two processes renaming onto
+// the same target at the same moment - the prompt hook, the pulse and the
+// status line do exactly that - get EPERM back from MoveFileEx for the one
+// that loses. Measured on 2026-09-25 with four processes writing one file for
+// three seconds: 2109 renames refused with EPERM against 469 that went
+// through. The writers that did not delete their temporary file on that
+// failure left one behind every time, and about seventy of them had piled up
+// in ~/.claude by then. The same retry on EPERM, EACCES and EBUSY is what
+// graceful-fs does for npm on Windows; here it is bounded tightly, because
+// the hooks that call this have ten seconds between them and the prompt.
+//
+// What no code path can clean is a process killed between creating its
+// temporary file and renaming it - a hook that ran into its timeout. sweep()
+// removes those at the next prompt, once they are old enough that no live
+// writer can still own them.
+
+const fs = require('fs');
+const path = require('path');
+
+// One suffix for every temporary file, and nobody else's: anything ending in
+// it is this plugin's, so the sweep never has to guess.
+const SUFFIX = '.usage-limits-tmp';
+
+// The codes Windows returns while another process has the target, or is
+// replacing it. Anything else - ENOSPC, ENOENT, EISDIR - will not change on a
+// second try.
+const RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+// About a third of a second in all. Contention clears in milliseconds; a
+// target that is still held after this is held by something that will not let
+// go soon, and the caller carries on with what is on disk.
+const RETRY_DELAYS_MS = [5, 10, 20, 40, 60, 80, 100];
+
+// A write takes milliseconds and the longest hook is killed at ten seconds, so
+// nothing alive owns a temporary file this old.
+const STALE_MS = 10 * 60 * 1000;
+
+// Temporary names this plugin has used. The first is the one written now; the
+// second is what reading.js, drift.js, mode.js and relay.js wrote before
+// 1.39.6 - `usage-limits-<name>.json.<pid>.tmp` - and is matched only with the
+// usage-limits- prefix and the pid, because a bare .tmp could be anyone's.
+const OWN_TEMP = [
+  /^.+\.usage-limits-tmp$/,
+  /^usage-limits-[A-Za-z0-9_-]+\.json\.\d+\.tmp$/,
+];
+
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch (err) {
+    // No shared memory here: spin for the same time instead.
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      // Waiting.
+    }
+  }
+}
+
+function tempFor(file) {
+  return file + '.' + process.pid + SUFFIX;
+}
+
+function renameWithRetry(from, to) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      fs.renameSync(from, to);
+      return;
+    } catch (err) {
+      if (!RETRY_CODES.has(err && err.code) || attempt >= RETRY_DELAYS_MS.length) throw err;
+      sleepSync(RETRY_DELAYS_MS[attempt]);
+    }
+  }
+}
+
+// Never throws. True when the file is gone, whoever removed it.
+function removeQuietly(file) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      fs.unlinkSync(file);
+      return true;
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return true;
+      if (!RETRY_CODES.has(err && err.code) || attempt >= 3) return false;
+      sleepSync(RETRY_DELAYS_MS[attempt]);
+    }
+  }
+}
+
+// Throws what the write or the last rename threw, after removing the
+// temporary file. `options` is passed to writeFileSync (encoding, mode).
+function writeFileAtomic(file, text, options) {
+  const temp = tempFor(file);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(temp, text, options === undefined ? 'utf8' : options);
+    renameWithRetry(temp, file);
+  } catch (err) {
+    removeQuietly(temp);
+    throw err;
+  }
+}
+
+// The same, for callers that carry on either way.
+function tryWriteFileAtomic(file, text, options) {
+  try {
+    writeFileAtomic(file, text, options);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function isOwnTemp(name) {
+  return OWN_TEMP.some((pattern) => pattern.test(name));
+}
+
+// Removes this plugin's temporary files older than STALE_MS from each
+// directory. Only names isOwnTemp() accepts are ever looked at. Never throws;
+// returns how many were removed.
+function sweep(dirs, now, staleMs) {
+  const at = Number.isFinite(now) ? now : Date.now();
+  const age = Number.isFinite(staleMs) ? staleMs : STALE_MS;
+  let removed = 0;
+  const seen = new Set();
+  for (const dir of [].concat(dirs || [])) {
+    if (!dir || seen.has(path.resolve(dir))) continue;
+    seen.add(path.resolve(dir));
+    let names;
+    try {
+      names = fs.readdirSync(dir);
+    } catch (err) {
+      continue;
+    }
+    for (const name of names) {
+      if (!isOwnTemp(name)) continue;
+      const file = path.join(dir, name);
+      try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile() || at - stat.mtimeMs < age) continue;
+      } catch (err) {
+        continue;
+      }
+      try {
+        fs.unlinkSync(file);
+        removed += 1;
+      } catch (err) {
+        // Gone already is someone else's sweep; held is worth one more try.
+        if (err && err.code !== 'ENOENT' && removeQuietly(file)) removed += 1;
+      }
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  SUFFIX,
+  STALE_MS,
+  RETRY_CODES,
+  RETRY_DELAYS_MS,
+  tempFor,
+  renameWithRetry,
+  removeQuietly,
+  writeFileAtomic,
+  tryWriteFileAtomic,
+  isOwnTemp,
+  sweep,
+};

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

@@ -13,6 +13,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
 const usage = require('./usage.js');
 const host = require('./host.js');
 const tally = require('./tally.js');
@@ -64,6 +65,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 +76,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;
@@ -1424,6 +1451,20 @@ const GEMINI_UNREADABLE =
 const LIMIT_REACHED =
   '[usage-limits] The meter says the usage limit is reached. Start nothing new: save the work, write the hand-off note in this turn, and end the turn.';
 
+// Temporary files a killed process left behind: a hook that ran into its
+// timeout between writing one and renaming it. Nothing else can clean them,
+// and on 2026-09-25 about seventy had piled up in ~/.claude. Once per prompt
+// is often enough and costs one directory listing per home. The clock here
+// is always the real one, never the run's `now`: a stale file is judged by
+// its mtime, which is real time too. Never throws.
+function sweepDebris() {
+  try {
+    return atomic.sweep([configDir(), host.codexHome()], Date.now());
+  } catch (err) {
+    return 0;
+  }
+}
+
 async function run(now, hookInput, opts) {
   if (String(process.env.USAGE_LIMITS_BRIEF || '').toLowerCase() === 'off') return '';
 
@@ -1437,6 +1478,8 @@ async function run(now, hookInput, opts) {
   const budget = mode.forSession({ sessionId });
   if (budget.policy.briefStyle === 'none') return guardLine(now, budget);
 
+  sweepDebris();
+
   // Settle host here, before any file is read. A caller that already knows the
   // host (agy-hook runs only inside Antigravity) says so, and that wins over
   // detection: an empty or unparseable payload used to fall through to
@@ -1495,21 +1538,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.
@@ -1770,9 +1821,13 @@ function withBugcheck(text) {
   return text;
 }
 
-module.exports = { withBugcheck, sayOnce, shapeOf, saidFile, REPEAT_MS, staleVersionFor, relayNewsFor, installedVersion, runningVersion,
+module.exports = { sweepDebris, 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-lowpower.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const atomicWrite = require('./atomic.js');
 const KEYS = ['model', 'model_reasoning_effort'];
 const EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
 
@@ -118,9 +119,8 @@ function read(file, fallback) {
   try { return fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return fallback; throw e; }
 }
 function atomic(file, text) {
-  const temp = file + '.' + process.pid + '.tmp';
-  try { fs.writeFileSync(temp, text, { encoding: 'utf8', mode: 0o600 }); fs.renameSync(temp, file); }
-  finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+  // Throws on failure, as before, with the temporary file already removed.
+  atomicWrite.writeFileAtomic(file, text, { encoding: 'utf8', mode: 0o600 });
 }
 function checkState(state) {
   if (!state) return;

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

@@ -23,6 +23,7 @@ const os = require('os');
 const path = require('path');
 const readline = require('readline');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 
 const MINUTE = 60 * 1000;
@@ -815,13 +816,9 @@ function readLiveMeter() {
 
 function writeLiveMeter(reading) {
   try {
-    const file = liveFile();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const temp = file + '.' + process.pid + '.usage-limits-tmp';
-    fs.writeFileSync(temp, JSON.stringify(reading), 'utf8');
-    fs.renameSync(temp, file);
-    return true;
+    return atomic.tryWriteFileAtomic(liveFile(), JSON.stringify(reading));
   } catch (err) {
+    // A reading that will not serialise is not written either.
     return false;
   }
 }
@@ -830,6 +827,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 +932,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 +1165,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/drift.js

@@ -19,6 +19,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 const codex = require('./codex.js');
 
@@ -102,13 +103,11 @@ function modeSummary(codexHome) {
     .sort((a, b) => b.turns - a.turns);
 }
 
+// Same beside-and-rename as reading.js: the pulse and the prompt hook can both
+// land here in the same second. A refused rename is retried, and on failure
+// the temporary file is removed before this throws: see atomic.js.
 function writeAtomic(file, data) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  // Same beside-and-rename as reading.js: the pulse and the prompt hook can
-  // both land here in the same second.
-  const tmp = file + '.' + process.pid + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(data));
-  fs.renameSync(tmp, file);
+  atomic.writeFileAtomic(file, JSON.stringify(data));
 }
 
 // `previous` and `next` are both entries in reading.js's own shape - see

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

@@ -31,6 +31,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 
 const PLUGIN = 'usage-limits';
@@ -44,20 +45,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() {
@@ -98,10 +145,7 @@ function rulesText() {
 }
 
 function writeFile(file, text) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = file + '.' + process.pid + '.tmp';
-  fs.writeFileSync(tmp, text, 'utf8');
-  fs.renameSync(tmp, file);
+  atomic.writeFileAtomic(file, text);
 }
 
 function installed() {
@@ -155,6 +199,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 +225,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/live.js

@@ -26,6 +26,8 @@ const http = require('http');
 const https = require('https');
 const { execFileSync } = require('child_process');
 
+const atomic = require('./atomic.js');
+
 const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const BETA = 'oauth-2025-04-20';
 // Claude Code gives the call five seconds; so does this.
@@ -328,22 +330,10 @@ function readLive() {
 
 // Through a temporary file named for this process, so a reader never sees
 // half a reading and two writers never share a temp file. A rename that fails
-// (Windows, with the target held open) leaves nothing behind.
+// (Windows, with the target held open) is retried, and one that still fails
+// leaves nothing behind: see atomic.js.
 function writeAtomic(file, text) {
-  const temp = file + '.' + process.pid + '.usage-limits-tmp';
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(temp, text, 'utf8');
-    fs.renameSync(temp, file);
-    return true;
-  } catch (err) {
-    try {
-      fs.unlinkSync(temp);
-    } catch (gone) {
-      // Nothing to clean up.
-    }
-    return false;
-  }
+  return atomic.tryWriteFileAtomic(file, text);
 }
 
 function writeLive(snapshot) {

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

@@ -22,6 +22,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
+
 const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
 const MANAGED_KEYS = ['effortLevel', 'model'];
 const DEFAULTS = { effortLevel: 'low' };
@@ -50,10 +52,7 @@ function readJson(file) {
 // Replace through a temporary file so an interrupted run cannot leave
 // settings.json half written.
 function writeJson(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temp = file + '.usage-limits-tmp';
-  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
-  fs.renameSync(temp, file);
+  atomic.writeFileAtomic(file, JSON.stringify(value, null, 2) + '\n');
 }
 
 function parseArgs(argv) {

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

@@ -31,6 +31,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 const codex = require('./codex.js');
 
@@ -480,10 +481,7 @@ function read() {
 }
 
 function writeAtomic(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = file + '.' + process.pid + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n');
-  fs.renameSync(tmp, file);
+  atomic.writeFileAtomic(file, JSON.stringify(value, null, 2) + '\n');
 }
 
 // Never throws for the same reason read() does not.

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.

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

@@ -24,6 +24,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
 const drift = require('./drift.js');
 
 // Older than this and the spend it measured is history: turns have happened
@@ -102,10 +103,9 @@ function record(binding, now, codexHome) {
     // 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;
+    // A refused rename is retried and a failed one leaves nothing behind: see
+    // atomic.js. The caller only ever needed to know whether it landed.
+    return atomic.tryWriteFileAtomic(file, JSON.stringify(all));
   } catch (err) {
     return false;
   }

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

@@ -34,6 +34,7 @@ const os = require('os');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 const voice = require('./voice.js');
 
@@ -353,9 +354,7 @@ function preflightPrompts(cwd, config, options) {
 // 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);
+  atomic.writeFileAtomic(file, text);
 }
 
 function write(state) {

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

@@ -21,6 +21,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const atomic = require('./atomic.js');
+
 function configDir() {
   return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 }
@@ -62,10 +64,7 @@ function readState() {
 // Replace through a temporary file so an interrupted run cannot leave
 // settings.json half written.
 function writeJson(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temp = file + '.usage-limits-tmp';
-  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
-  fs.renameSync(temp, file);
+  atomic.writeFileAtomic(file, JSON.stringify(value, null, 2) + '\n');
 }
 
 // The launcher. It is deliberately dumb: find feed.js, hand over, and if that

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

@@ -21,6 +21,7 @@ const os = require('os');
 const path = require('path');
 const readline = require('readline');
 
+const atomic = require('./atomic.js');
 const host = require('./host.js');
 const codex = require('./codex.js');
 const live = require('./live.js');
@@ -836,18 +837,10 @@ function readScanCache() {
 // sees either the old whole or the new whole. A rename Windows refuses leaves
 // nothing behind, and the caller carries on with what is on disk.
 function writeJsonAtomic(file, value) {
-  const temp = file + '.' + process.pid + '.usage-limits-tmp';
   try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(temp, JSON.stringify(value), 'utf8');
-    fs.renameSync(temp, file);
-    return true;
+    return atomic.tryWriteFileAtomic(file, JSON.stringify(value));
   } catch (err) {
-    try {
-      fs.unlinkSync(temp);
-    } catch (gone) {
-      // Nothing to clean up.
-    }
+    // A value that will not serialise is not written either.
     return false;
   }
 }