claude-usage-limits 1.19.0 → 1.24.0

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+'use strict';
+
+// Is the network actually usable, and if a run just failed, was the network
+// the reason?
+//
+// This exists because of a real failure. A relay armed overnight woke on time,
+// found nothing wrong with itself, started the CLI, and got back
+//
+//     API Error: Unable to connect to API: SSL certificate hostname mismatch
+//
+// which is what a laptop says when the wifi is off and something - a captive
+// portal, a VPN, a corporate proxy - is answering the TLS handshake in the
+// endpoint's place. The relay treated that as a failed run, recorded "failed",
+// cleared itself and deleted its own scheduled task. The work was not done, the
+// window it had waited for was wide open, and nothing was left to try again.
+//
+// The rule that follows from it: **a machine that cannot reach the API has not
+// failed, it is waiting.** Being offline is a normal state for a laptop at
+// three in the morning and it must cost a retry, never the relay.
+//
+// Nothing here uses a package. `fetch` is in Node 18+, and the only thing that
+// matters is telling three cases apart:
+//
+//   online      the endpoint answered, with anything at all including a 401
+//   offline     nothing answered - no DNS, no route, no socket
+//   intercepted something answered but it was not the endpoint. This is the
+//               nasty one, because a captive portal returns a valid HTTP
+//               response and a working TLS session for the wrong certificate,
+//               so a naive "did I get bytes back" check says yes.
+
+const MINUTE = 60 * 1000;
+
+// 401 is the correct, healthy answer from an authenticated endpoint hit without
+// a key: it proves DNS, routing, TLS and the service. Anything in the 2xx-5xx
+// range proves the same thing more loosely. Only a thrown error is offline.
+const PROBES = [
+  { name: 'api.anthropic.com', url: 'https://api.anthropic.com/v1/models' },
+  { name: 'claude.ai', url: 'https://claude.ai/robots.txt' },
+  { name: 'github.com', url: 'https://github.com/robots.txt' },
+];
+
+// The strings a TLS interception actually produces, across Node, curl and the
+// CLIs. Matched case-insensitively against the whole error chain because Node
+// buries the real reason in err.cause.
+const TLS_INTERCEPTION = /(certificate|self.signed|self_signed|hostname\/ip does not match|hostname mismatch|altname|unable to verify|cert_authority|ERR_TLS|DEPTH_ZERO|CERT_HAS_EXPIRED|UNABLE_TO_GET_ISSUER)/i;
+
+const OFFLINE = /(ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|ENETDOWN|EPIPE|ETIMEDOUT|ECONNABORTED|socket hang up|network is unreachable|getaddrinfo|fetch failed|Unable to connect|Connection (?:error|closed|reset)|dns)/i;
+
+// Failures that are the service's, not ours, and are worth waiting out rather
+// than burning the relay on. A 529 is Anthropic's own overload code.
+const TRANSIENT_SERVICE = /(\b429\b|\b500\b|\b502\b|\b503\b|\b504\b|\b529\b|overloaded|rate.?limit|too many requests|temporarily unavailable|service unavailable|internal server error|upstream|gateway|try again|timed? ?out|timeout)/i;
+
+// Failures that will still be failures in five hours. Retrying these is how a
+// relay spends a whole window re-running the same refusal.
+const PERMANENT = /(\b401\b|\b403\b|invalid.?api.?key|authentication|unauthorized|forbidden|no conversation found|not logged in|please run .?claude .?login|credit balance|billing|quota exceeded|permission denied|ENOENT|command not found|is not recognized)/i;
+
+function chain(err) {
+  const seen = [];
+  let node = err;
+  for (let depth = 0; node && depth < 6; depth++) {
+    if (node.message) seen.push(String(node.message));
+    if (node.code) seen.push(String(node.code));
+    if (node.errno) seen.push(String(node.errno));
+    node = node.cause;
+  }
+  return seen.join(' | ');
+}
+
+// One probe. Resolves rather than rejects: a probe that throws is a result.
+async function probe(target, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1000, timeoutMs || 8000));
+  const started = Date.now();
+  try {
+    const response = await fetch(target.url, {
+      method: 'GET',
+      signal: controller.signal,
+      redirect: 'manual',
+      headers: { 'user-agent': 'usage-limits-relay/1 (connectivity probe)' },
+    });
+    return { name: target.name, ok: true, status: response.status, ms: Date.now() - started };
+  } catch (err) {
+    const text = chain(err);
+    return {
+      name: target.name,
+      ok: false,
+      ms: Date.now() - started,
+      intercepted: TLS_INTERCEPTION.test(text),
+      aborted: /abort/i.test(text),
+      detail: text.split(' | ')[0] || 'unknown',
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// The question the wake asks: can this machine reach the service right now.
+//
+// Probes run together and the first success wins, because one endpoint being
+// down is not the same as having no network, and waiting for three timeouts in
+// series burns half a minute for an answer the first probe already had.
+async function reachable(options) {
+  const opts = options || {};
+  const timeoutMs = opts.timeoutMs || 8000;
+  const targets = opts.targets || PROBES;
+  let results = [];
+  try {
+    results = await Promise.all(targets.map((target) => probe(target, timeoutMs)));
+  } catch (err) {
+    return { online: false, reason: 'offline', detail: err.message, results: [] };
+  }
+  const good = results.filter((r) => r.ok);
+  if (good.length) {
+    return {
+      online: true,
+      reason: 'ok',
+      detail: good.map((r) => r.name + ' ' + r.status + ' in ' + r.ms + 'ms').join(', '),
+      results,
+    };
+  }
+  // Nothing answered. Interception is worth naming separately: the fix is not
+  // "wait for the network", it is "sign in to the wifi" or "turn the VPN off",
+  // and a message that says so saves somebody a morning.
+  if (results.some((r) => r.intercepted)) {
+    return {
+      online: false,
+      reason: 'intercepted',
+      detail: 'something answered in the endpoint\'s place - a captive portal, a VPN or a TLS-inspecting proxy. ' +
+        (results.find((r) => r.intercepted) || {}).detail,
+      results,
+    };
+  }
+  return {
+    online: false,
+    reason: 'offline',
+    detail: results.map((r) => r.name + ': ' + (r.aborted ? 'timed out' : r.detail)).join('; '),
+    results,
+  };
+}
+
+// Given the text of a failed run, decide whether trying again later is sensible.
+//
+//   wait      the network or the service. Retry; do not consume the relay.
+//   permanent a key, a login, a missing binary. Retrying wastes the window.
+//   unknown   treated as wait once and permanent after that, because an
+//             unrecognised error that repeats is not going to fix itself.
+function classify(text) {
+  const message = String(text || '');
+  if (!message.trim()) return { kind: 'unknown', why: 'the run failed without saying why' };
+  if (PERMANENT.test(message)) return { kind: 'permanent', why: 'this will still be true after the next reset' };
+  if (TLS_INTERCEPTION.test(message)) {
+    return {
+      kind: 'wait',
+      why: 'the TLS handshake did not reach the endpoint - offline, a captive portal, or a VPN in the way',
+    };
+  }
+  if (OFFLINE.test(message)) return { kind: 'wait', why: 'the machine could not reach the network' };
+  if (TRANSIENT_SERVICE.test(message)) return { kind: 'wait', why: 'the service was busy or unavailable' };
+  return { kind: 'unknown', why: 'an error this has not seen before' };
+}
+
+// How long to wait before looking again, given how many times it has already
+// looked. Gentle at first because most outages are a router restarting, then
+// backing off so an overnight outage is not a thousand wake-ups.
+function backoffMinutes(attempt, base) {
+  const start = Number.isFinite(base) ? base : 10;
+  const steps = [start, start, start * 2, start * 3, start * 6, start * 6];
+  return steps[Math.min(Math.max(0, attempt), steps.length - 1)];
+}
+
+module.exports = { reachable, probe, classify, backoffMinutes, PROBES, MINUTE };
+
+if (require.main === module) {
+  reachable({ timeoutMs: 8000 }).then((result) => {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(result.online ? 0 : 1);
+  });
+}

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

@@ -27,6 +27,8 @@ const brief = require('./brief.js');
 const host = require('./host.js');
 const activity = require('./activity.js');
 const live = require('./live.js');
+const mode = require('./mode.js');
+const ceiling = require('./ceiling.js');
 
 const SECOND = 1000;
 const DEFAULT_INTERVAL_SECONDS = 120;
@@ -37,9 +39,11 @@ const DEFAULT_INTERVAL_SECONDS = 120;
 const SCAN_BUDGET_MS = 5000;
 
 // One slot per session, same shape and same trimming as the brief's cache.
-// Two keys per session now - the spoken pulse and the quiet subagent refresh -
-// so this is double what it was.
-const KEEP_SESSIONS = 16;
+// Three keys per session now - the spoken pulse, the quiet subagent refresh,
+// and the reading taken before a long call - so this is three times what it
+// started at. Evicting a key only costs one extra scan, but evicting them as
+// fast as they are written would mean nothing is ever throttled.
+const KEEP_SESSIONS = 24;
 
 function stateFile() {
   const dir = usage.isCodex()
@@ -48,12 +52,15 @@ function stateFile() {
   return path.join(dir, 'usage-limits-pulse.json');
 }
 
-function intervalMs() {
+// How often this hook is allowed to do real work. The budget mode owns this
+// number - a mode that says the reading itself costs too much has to be able
+// to take fewer of them - but an explicit environment setting is the user
+// saying it outright, and that still wins.
+function intervalMs(policy) {
   const configured = Number(process.env.USAGE_LIMITS_PULSE_SECONDS);
-  const seconds = Number.isFinite(configured) && configured > 0
-    ? configured
-    : DEFAULT_INTERVAL_SECONDS;
-  return seconds * SECOND;
+  if (Number.isFinite(configured) && configured > 0) return configured * SECOND;
+  const fromMode = policy && Number.isFinite(policy.pulseSeconds) ? policy.pulseSeconds : null;
+  return (fromMode > 0 ? fromMode : DEFAULT_INTERVAL_SECONDS) * SECOND;
 }
 
 function readState() {
@@ -72,15 +79,42 @@ function writeState(all) {
   usage.writeJsonAtomic(stateFile(), all);
 }
 
-function trim(all, sessionId, at) {
+// `extra` carries whatever else the slot has to remember, and it exists for
+// one reason: the re-cost has to know what it said last time. A slot that is
+// only a timestamp can throttle, but it cannot tell "two minutes have passed"
+// from "two minutes have passed and nothing has changed", and those are
+// different questions.
+function trim(all, sessionId, at, extra) {
   const next = Object.assign({}, all);
-  next[sessionId || '_'] = { at };
+  next[sessionId || '_'] = Object.assign({ at }, extra || null);
   const ordered = Object.keys(next).sort((a, b) => (next[b].at || 0) - (next[a].at || 0));
   const kept = {};
   for (const key of ordered.slice(0, KEEP_SESSIONS)) kept[key] = next[key];
   return kept;
 }
 
+// A tool call the agent itself said would run long.
+//
+// PreToolUse now matches Bash, so a build or a test suite can be measured
+// before it starts rather than only after. But sharing the spoken pulse's one
+// throttle slot makes that almost never happen: a tool call finished seconds
+// ago, that PostToolUse pulse claimed the slot, and the one moment that
+// matters - just before the turn goes blind for ten minutes - says nothing.
+// Measured: a PostToolUse pulse at t, then `npm test` with a ten-minute
+// timeout at t+5s, and the pre-call pulse returned empty.
+//
+// The declaration is the agent's own: a Bash call carries the timeout it was
+// given, and anything above the pulse interval is a call that will outlast the
+// next scheduled reading. Nothing is inferred from the command text. A
+// backgrounded call is not this: it returns at once and PostToolUse fires
+// normally, so the turn never goes blind.
+function longCall(toolInput, every) {
+  if (!toolInput || typeof toolInput !== 'object') return false;
+  if (toolInput.run_in_background === true) return false;
+  const declared = Number(toolInput.timeout);
+  return Number.isFinite(declared) && declared > every;
+}
+
 function due(all, sessionId, now, every) {
   const entry = all ? all[sessionId || '_'] : null;
   if (!entry || !Number.isFinite(entry.at)) return true;
@@ -128,13 +162,62 @@ function pulseText(parts) {
   return head + ' Still room; carry on.';
 }
 
+// The two-minute re-cost. The distinguishing feature of `high`, and the reason
+// it is not simply `standard` with a shorter interval.
+//
+// A PostToolUse hook CAN put text in front of the model mid-turn: the hook
+// output contract takes additionalContext on this event, and it has been seen
+// arriving mid-turn in a running session. So this is a real nudge, not a note
+// filed for the next prompt.
+//
+// What it must not do is claim a lever nobody has. Nothing a hook emits can
+// change the running session's own model or effort - there is no such field in
+// the whole hook output contract, and PreModelSwitch is a veto on a switch
+// someone else started rather than a way to start one. So for the main loop
+// this names the command and leaves it with the person, and for what the turn
+// SPAWNS it says the thing that is genuinely the agent's to decide.
+//
+// It is built every two minutes and SAID only when it differs from the last
+// thing said in this session. See the caller: a re-cost that repeats itself is
+// not a re-cost, it is a bill for advice already given.
+function recheckText(parts) {
+  const bits = [];
+  if (parts.fit) {
+    bits.push(
+      'this turn is at ' + parts.fit.effort + ', measured ' + parts.fit.multiple + ' times the cost of ' +
+        parts.fit.cheaper + ' a turn on this account'
+    );
+  }
+  if (parts.escape && parts.escape.kind === 'effort' && parts.escape.to) {
+    bits.push(parts.escape.to + ' would free the window that binds');
+  }
+  if (!bits.length) return '';
+  const command = (parts.fit && parts.fit.command) || (parts.escape && parts.escape.command) || null;
+  return (
+    '[usage-limits] Re-costed: ' + bits.join(', and ') + '. If the stretch in front of you is ' +
+    'mechanical, the tier is bigger than the work' + (command ? ' - the change is ' + command + ', and it is the ' +
+    "user's to make, so say it in one line rather than waiting for it" : '') +
+    (parts.pin
+      ? '. Self-switching is pinned, so this is a report: change nothing on the strength of it.'
+      : '. Size what you spawn the same way: low effort for mechanical stages. Step back up when the work turns hard again.')
+  );
+}
+
 async function run(now, hookInput) {
   if (String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() === 'off') return '';
-  usage.setHost(host.detect(process.argv.slice(2), process.env));
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
   const event = hookInput && hookInput.hook_event_name ? String(hookInput.hook_event_name) : 'PostToolUse';
 
+  // The budget mode, settled before anything is read, marked or scanned. In
+  // `off` the hook stops here: no reading, no activity mark, no state write.
+  // That mode's whole promise is that the plugin costs nothing, and a hook
+  // that "returns immediately" after a transcript scan has already broken it.
+  const budget = mode.forSession({ sessionId });
+  if (budget.policy.refreshSeconds === 0) return '';
+
+  usage.setHost(host.detect(process.argv.slice(2), process.env));
+
   // A subagent finishing is the other reason to look, and on a busy afternoon
   // it is the more important one.
   //
@@ -156,6 +239,30 @@ async function run(now, hookInput) {
   // pulse had last read as 24%.
   const tool = hookInput && hookInput.tool_name ? String(hookInput.tool_name) : '';
   const fanout = event === 'PreToolUse' && /^(Workflow|Agent|Task)$/.test(tool);
+
+  // The ceiling, checked before the throttle and before any scan.
+  //
+  // Everything else in this hook is advice, and advice is throttled so it does
+  // not become noise. A refusal that only arrives when the pulse happens to be
+  // due is not a refusal, so this runs on every fan-out regardless, off the two
+  // readings that are already on disk. It is the one thing here that does not
+  // ask the model to agree with it.
+  if (event === 'PreToolUse' && ceiling.isMultiplier(tool)) {
+    try {
+      const at = ceiling.assess({
+        percent: ceilingPercent(now),
+        state: budget.state,
+        env: process.env,
+      });
+      const call = ceiling.verdict(at, tool);
+      if (call.decision === 'deny') return { deny: true, reason: call.reason };
+    } catch (err) {
+      // A ceiling that throws must not block the call it was asked to judge.
+    }
+  }
+  // The other way a turn goes quiet for a long time: one foreground tool call
+  // that runs for minutes. See longCall().
+  const long = event === 'PreToolUse' && !fanout && longCall(hookInput && hookInput.tool_input, intervalMs(budget.policy));
   if (!quiet) {
     // A tool call just finished, so the turn is still running. A few bytes, so
     // the panel beside the chat keeps animating through a long turn.
@@ -163,12 +270,20 @@ async function run(now, hookInput) {
   }
 
   const all = readState();
-  const every = intervalMs();
+  const every = intervalMs(budget.policy);
   // The quiet refresh keeps its own throttle. Sharing one with the spoken
   // pulse would mean a workflow's subagents used up the interval and the tool
   // call right after it, the first chance to actually tell Claude, said
   // nothing because something had already "pulsed" two minutes ago.
-  const throttleKey = quiet ? (sessionId || '_') + '#subagent' : sessionId;
+  // Same reasoning for the call about to run long: its own slot, so it is
+  // still throttled to one reading per interval and a run of long calls does
+  // not scan before every one of them, but the post-tool pulses cannot use up
+  // the interval and leave the blind stretch unmeasured.
+  const throttleKey = quiet
+    ? (sessionId || '_') + '#subagent'
+    : long
+      ? (sessionId || '_') + '#long'
+      : sessionId;
   // The cheap path, and the one taken almost every time. A fan-out is never
   // throttled: it is said every time, because every time it is about to cost.
   if (!fanout && !due(all, throttleKey, now, every)) return '';
@@ -222,13 +337,66 @@ async function run(now, hookInput) {
   const runwayMs = brief.RUNWAY_MENTION_MS;
   const pressure = brief.pressure(binding, now, config, turnsLeft);
 
+  // The mode's own mid-turn re-cost, on its own throttle slot.
+  //
+  // Its own slot because the "quiet when roomy" rule below would otherwise
+  // swallow it exactly when it matters most: a turn running a tier far bigger
+  // than the work needs is precisely the case where the budget still looks
+  // roomy and nothing else would say a word.
+  let recheck = '';
+  const recheckMs = (budget.policy.recheckSeconds || 0) * SECOND;
+  const recheckKey = (sessionId || '_') + '#recheck';
+  if (recheckMs > 0 && due(readState(), recheckKey, now, recheckMs)) {
+    // From the per-effort TABLE, which is what report() returns. It was asked
+    // for from `data.events`, a field report() has never had, so the measured
+    // half of the re-cost was null on every call on every machine and `high`
+    // was left emitting its escape clause alone.
+    const fit = usage.fitFromRates(data.effortRates || [], data.effortNow || null, usage.currentHost());
+    // The user's bounds are the user's, and `pin` is one of them: it lives on
+    // bounds, not on the mode's policy, so it has to be handed over here or
+    // the route comes back unable to say it is a report.
+    const route = usage.escapeRoute(data.windows || [binding], binding, data.effortWarning || null, usage.currentHost(), budget.policy, budget.bounds);
+    const allowed = (suggestion) => mode.allows(budget.bounds, suggestion);
+    // The measured half is a recommendation about the user's own setting, so
+    // it goes out through the advice rules rather than around them: never once
+    // muted, never once declined, never below a bound, and not a second time
+    // in a session where the brief has already made it. Filtering only on the
+    // bounds here meant `mode --no-advice` and `mode --decline` were both
+    // routed around every two minutes, in the one mode that speaks mid-turn.
+    const advice = mode.advicePending({ decided: budget, fit, sessionId });
+    const offerFit = advice.ok && !advice.alreadyOffered ? fit : null;
+    const text = recheckText({
+      fit: offerFit,
+      escape: route && route.kind === 'effort' && allowed({ effort: route.to }) ? route : null,
+      pin: budget.bounds && budget.bounds.pin,
+    });
+    // Say it once.
+    //
+    // Nothing this line is built from moves within a turn, so on the throttle
+    // alone it repeated itself verbatim every two minutes: measured, fifteen
+    // identical injections in one half-hour turn at 20 per cent used. That is
+    // the failure this whole feature exists to avoid, arriving in the mode
+    // named for efficiency. `high` re-costs continuously - it takes the
+    // measurement every two minutes - and speaks when the answer CHANGES.
+    const state = readState();
+    const before = state[recheckKey] && state[recheckKey].said;
+    recheck = text && text !== before ? text : '';
+    // Recorded only when it is actually said, and only for the half that is a
+    // recommendation, so that "no, leave it" has something to refuse: without
+    // this, `mode --decline` after a mid-turn re-cost had no id to act on.
+    if (recheck && offerFit && advice.id) mode.adviceOffer(advice.id, sessionId, now, advice.text);
+    // Claimed whether or not it produced a line: the measurement was taken,
+    // and taking it again in ten seconds would cost the same and say the same.
+    writeState(trim(state, recheckKey, now, text ? { said: text } : null));
+  }
+
   // Quiet when there is nothing to act on. A line every two minutes saying the
   // budget is fine is noise that costs the budget it is reporting on.
   if (!fanout && pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
-    return '';
+    return recheck;
   }
 
-  return pulseText({
+  const spoken = pulseText({
     label: binding.label,
     percentUsed: binding.percentUsed,
     approximate: Boolean(binding.estimated || binding.adjusted),
@@ -241,6 +409,49 @@ async function run(now, hookInput) {
     pressure,
     fanout,
   });
+  return recheck ? (spoken ? spoken + ' ' + recheck : recheck) : spoken;
+}
+
+// The cheapest percentage good enough to enforce a ceiling against.
+//
+// The ceiling is checked before every fan-out, which is far too often to scan
+// transcripts for. Two sources are already paid for: the corrected reading the
+// last scan left behind, and the account snapshot, which is one small file
+// read. The highest of them wins, because a ceiling means "no window past
+// here" - taking the emptiest window would be a ceiling that never binds.
+//
+// Returns null when neither source has anything, and a ceiling with no reading
+// behind it never refuses. Guessing high would block work over a number nobody
+// measured; guessing low would not be a ceiling at all.
+function ceilingPercent(now) {
+  let worst = null;
+  const consider = (value) => {
+    if (!Number.isFinite(value)) return;
+    if (worst === null || value > worst) worst = value;
+  };
+  const codexHome = usage.isCodex() ? require('./codex.js').homeDir() : null;
+  try {
+    const entries = reading.read(codexHome);
+    for (const key of Object.keys(entries)) {
+      const entry = reading.correctedFor(key, now, null, codexHome);
+      if (entry) consider(entry.percentUsed);
+    }
+  } catch (err) {
+    // A missing or unreadable correction just means the snapshot decides.
+  }
+  try {
+    const snapshot = usage.collect(now);
+    const utilization = snapshot && snapshot.utilization;
+    if (utilization && typeof utilization === 'object') {
+      for (const key of Object.keys(utilization)) {
+        const window = utilization[key];
+        if (window && typeof window === 'object') consider(Number(window.utilization));
+      }
+    }
+  } catch (err) {
+    // Same: no snapshot is a reason not to enforce, not a reason to throw.
+  }
+  return worst;
 }
 
 // PostToolUse does not take plain stdout as context the way UserPromptSubmit
@@ -256,6 +467,22 @@ function envelope(text, event) {
   });
 }
 
+// The refusal envelope.
+//
+// Claude Code and Codex document the same PreToolUse shape: a permissionDecision
+// of "deny" with a reason, which is shown to the model in place of the tool
+// result. Exit code stays 0 - exit 2 also blocks, but routes the reason through
+// stderr, and a reason the model can read is the entire point of refusing.
+function refusal(reason) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
 function readHookInput() {
   return new Promise((resolve) => {
     if (process.stdin.isTTY) return resolve(null);
@@ -289,8 +516,14 @@ if (require.main === module) {
       return run(Date.now(), input);
     })
     .then(
-      (text) => {
-        if (text) process.stdout.write(envelope(text, hookEvent) + '\n');
+      (result) => {
+        // A refusal, not a line. Claude Code and Codex take the same shape
+        // here; Antigravity's differs and is handled by its own entry point.
+        if (result && typeof result === 'object' && result.deny) {
+          process.stdout.write(refusal(result.reason) + '\n');
+          process.exit(0);
+        }
+        if (result) process.stdout.write(envelope(result, hookEvent) + '\n');
         process.exit(0);
       },
       () => {
@@ -301,6 +534,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  recheckText,
   DEFAULT_INTERVAL_SECONDS,
   KEEP_SESSIONS,
   stateFile,
@@ -309,7 +543,10 @@ module.exports = {
   writeState,
   trim,
   due,
+  longCall,
   pulseText,
   envelope,
+  refusal,
+  ceilingPercent,
   run,
 };

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

@@ -24,6 +24,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const drift = require('./drift.js');
+
 // Older than this and the spend it measured is history: turns have happened
 // since, and a stale correction that says 40 per cent is worse than an honest
 // snapshot that says 13, because it looks authoritative.
@@ -71,18 +73,25 @@ function record(binding, now, codexHome) {
   if (binding.stale || binding.estimated || binding.correctionUnreliable) return false;
   try {
     const all = read(codexHome);
-    all[binding.key] = {
-      at: Number.isFinite(now) ? now : Date.now(),
+    const at = Number.isFinite(now) ? now : Date.now();
+    // Whatever was sitting here before is what the cheap readers had been
+    // trusting; this fresh, checked correction is what the meter actually
+    // said. The gap between them is real drift a session just lived through,
+    // and it is worth keeping regardless of what happens to this record next.
+    const previous = all[binding.key];
+    const next = {
+      at,
       percentUsed: binding.percentUsed,
       pointsSinceSnapshot: binding.pointsSinceSnapshot || 0,
       adjusted: Boolean(binding.adjusted),
       resetsAt: Number.isFinite(binding.resetsAt) ? binding.resetsAt : null,
       turnsLeft: Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
     };
+    if (previous) drift.record(binding.key, previous, next, at, codexHome);
+    all[binding.key] = next;
     // One entry per window key, and there are only ever a handful of those, so
     // this file cannot grow. Anything whose reset has passed describes a window
     // that no longer exists.
-    const at = Number.isFinite(now) ? now : Date.now();
     for (const key of Object.keys(all)) {
       const entry = all[key];
       if (!entry || !Number.isFinite(entry.at) || at - entry.at > 24 * 60 * 60 * 1000) delete all[key];