claude-usage-limits 1.39.5 → 1.40.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.39.5",
+  "version": "1.40.1",
   "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.5",
+  "version": "1.40.1",
   "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/README.md

@@ -350,6 +350,106 @@ The skill also requires Claude to say up front when a job will not fit in what
 is left, name what it is doing now, what it is leaving, and when the rest can
 happen, rather than starting and stopping halfway through an edit.
 
+## /low-priority, and Claude Code's own features at the wall
+
+Claude Code has grown its own machinery for the moment the 5-hour limit is hit.
+Some of it a hook can read and some of it cannot, and the whole of this
+section is about keeping that line straight — a plugin that guesses at the half
+it cannot see is worse at this than one that says nothing.
+
+**`/low-priority`** is a hidden toggle the CLI offers when the session (5-hour)
+limit is reached. It keeps the session working at reduced priority and spends
+your **weekly** limit, plus a separate weekly lower-priority allowance. Replies
+can pause while it waits for spare capacity. It appears in no changelog and in
+no documentation — there are zero mentions across all 405 versions of the
+bundled changelog back to 0.2.21 — and it is declared `isHidden: true`, so the
+only way anyone learns of it is the offer line at the wall.
+
+What the plugin can read is whether **your account is provisioned** for it, from
+one field in the same `~/.claude.json` it already parses for the meter:
+`cachedGrowthBookFeatures.tengu_toasty_breeze`. That costs no extra I/O, and it
+is re-read on every prompt rather than remembered, because the grant can be
+withdrawn mid-week.
+
+What the plugin **cannot** read is whether it is on right now. That state lives
+in the CLI's process memory and is written to no file — not `~/.claude.json`,
+not `~/.claude/state`, and no hook payload or status-line field carries it. So
+there are three states and never a fourth:
+
+| state | how it is known |
+| --- | --- |
+| **absent** | the account is not provisioned, and the plugin never mentions the command |
+| **offered** | provisioned, so the brief says it exists at the wall — as a possibility |
+| **acknowledged** | **you** said you switched it on: `mode --low-priority on` |
+
+Two further gates sit in front of the offer that nothing here will ever see: the
+experiment arm arrives in a response header, and the CLI withholds the offer
+during a cooloff and once the weekly allowance is spent. So the brief says "if
+the wall offers it", never "you can run it". And it never says the plugin or the
+model can switch it on: Claude cannot type a slash command, and the command is
+declared `supportsNonInteractive: false`, so it is unusable in a headless or
+relayed run either.
+
+At the wall with weekly headroom, the line looks like this:
+
+```
+If the wall offers it, /low-priority carries this session past the 5-hour limit
+at lower priority instead of stopping: it spends the weekly limit, which is at
+45% and so has room, and replies may pause while it waits for spare capacity -
+the wait and its ceiling are set by the server per request. It is a toggle: you
+type it yourself and run it again to stop, and nothing here can switch it on
+for you.
+```
+
+**The recommendation has a number behind it.** It is offered only while the
+weekly is at or below **80 per cent** and the 5-hour window is the binding wall.
+Above that the brief actively says not to, and cites the figure: low-priority
+spends the weekly *and* draws on a weekly allowance whose size is exposed to no
+hook and no file, and a real user measured it emptying most of a week in a
+couple of hours. No wait time is ever printed, because the retry and the ceiling
+come from `lowPriorityRetryAfterSeconds` and `lowPriorityMaxWaitSeconds` on each
+response — any fixed "20 seconds, 20 minutes" would be invented.
+
+Once you acknowledge it, three things change. The brief brakes on the **weekly**
+window instead of the 5-hour one, because that is the only brake left. It stops
+telling you to wind down at the 5-hour wall. And the relay **will not book a
+wake for the 5-hour reset** — this session carries straight past it, so a wake
+would fire into a session that never stopped. A weekly wall still arms. The
+acknowledgement lapses by itself when the 5-hour window it was made against
+resets.
+
+**The graceful wrap-up note.** Claude Code can inject its own "finish up"
+instruction at the wall. The mechanism is real, and the gate is
+`tengu_lantern_wick_mode` — the bundle's own normalizer keeps only `"wrap-up"`
+and `"next-steps"` and maps everything else to `"off"`. When it is on, this
+plugin stands down and says who is speaking, because two agents telling the
+model to wind down in different words is worse than one. When it is off, the
+plugin's own instruction stands. It is read, not assumed, so the right thing
+happens whichever way the flag is set. (The near-limit variant is a separate
+flag, `tengu_vellum_anchor`.)
+
+**`autoContinueAtUsageLimit`.** Since 2.1.234 Claude Code waits out the reset
+and continues the same open session by itself, and the setting is **on by
+default**. In place, with the context intact, that is better than any scheduled
+wake. So when a resume relay is armed and this is on, the brief says so: the
+wake is the route for a session that will be **closed** at the reset, and both
+firing for the same reset would start the work twice and spend the weekly twice.
+
+**`/limit-reset`**, the once-weekly manual session reset, is detected but not
+built on: this account holds no grant (`tengu_cedar_ember` absent,
+`cachedUsageUtilization.cedar_ember` null), so a feature resting on it would be
+untestable. If a grant appears, the brief names it at the wall, says it only
+works while you are actually at a limit, and says the work it unlocks still
+spends the weekly. It never reports how many are left — `resets_left` comes from
+a live endpoint and appears in no file a hook can read.
+
+**Grace is not weekly spend.** The allowance the wall gives you is metered in
+its own per-window meters (`anthropic-ratelimit-unified-grace-5h-utilization`
+and `-grace-7d-utilization`, with a `rateLimitGraceZone` naming which window it
+belongs to), not billed to the 7-day window. Its size arrives in response
+headers and appears in no hook payload, no status-line field and no file, so the
+plugin says nothing about how much of it is left rather than estimating.
+
 ## The relay: carrying a project across the reset
 
 The handoff has always had the same flaw. It gets written, and then it sits in
@@ -1170,7 +1270,8 @@ skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, stop.js,
                                   recommend.js, panel.js, feed.js,
                                   statusline.js, live.js, view.js, bars.js,
                                   activity.js, reading.js, drift.js,
-                                  mode.js, voice.js, relay.js, wake.js
+                                  mode.js, voice.js, relay.js, wake.js,
+                                  lowpri.js
 skills/usage-limits/references/   the longer notes
 hooks/hooks.json                  runs brief.js before each prompt, pulse.js
                                   during long turns, stop.js after each reply
@@ -1182,6 +1283,7 @@ commands/statusline.md            the /usage-limits:statusline command
 commands/usage-mode.md            the /usage-mode command
 bin/cli.js                        the npx entry point
 tools/sync-version.js             keeps the manifest version in step
+tools/test-tempdirs.js            temp directories the suite deletes on exit
 vscode/                           the VS Code extension; build.js copies the
                                   scripts into vscode/lib and makes the vsix
 test/                             node --test, no dependencies
@@ -1193,10 +1295,11 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-712 tests over the pricing, the window arithmetic, plan and credit detection,
+895 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, the mid-turn pulse, the after-reply tally and the session history, job forecasting,
 per-project attribution, the Codex reader and its installer, the CLI,
-packaging, and the settings save/restore.
+packaging, the settings save/restore, and what Claude Code's own wall-time
+features are readable as (/low-priority, the wrap-up note, autoContinueAtUsageLimit).
 
 The budget modes are checked as rules rather than examples: the whole stopping
 matrix is walked in every mode (640 lines), `off` must inject nothing at any

package/commands/usage-mode.md

@@ -55,6 +55,29 @@ Commands:
   the last one, naming it first.
 - `--ledger` - measured turns and cost per turn, per mode, from what replies
   actually cost.
+- `--low-priority` / `--low-priority on` / `--low-priority off` - whether YOU
+  have switched Claude Code's `/low-priority` on. With no argument it reports
+  what is recorded, whether this account is provisioned for the command at all,
+  whether Claude Code will inject its own wrap-up note at the wall on this
+  machine, and whether the CLI's own continue-after-reset is on.
+
+  **This is a record of something the user did, never a reading.** Claude Code
+  keeps the live low-priority state in process memory and writes it to no file:
+  not `~/.claude.json`, not `~/.claude/state`, and no hook payload or
+  status-line field carries it. So the plugin knows three things and not a
+  fourth - the account is provisioned (`tengu_toasty_breeze.enabled`), the user
+  has said it is on, or neither. It never claims it is running.
+
+  `on` changes three behaviours: the brief brakes on the **weekly** window
+  instead of the 5-hour one, it stops telling you to wind down at the 5-hour
+  wall, and the relay will not book a wake for the 5-hour reset - that reset is
+  no longer a wall this session stops at. The record lapses on its own when the
+  5-hour window it was made against resets, because that is when low-priority
+  ends. Say `off` if it ends sooner.
+
+  The model cannot type a slash command, and `/low-priority` is declared
+  `supportsNonInteractive: false`, so it is also unusable in a headless or
+  relayed run. Nothing here can switch it on.
 
 Two rules that hold in every mode:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.39.5",
+  "version": "1.40.1",
   "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/SKILL.md

@@ -591,6 +591,49 @@ was not caution; it was quitting with a reason that sounded like one.
 Only when the switch is genuinely unavailable - no other window has room, or the
 user has ruled it out - does the checkpoint below apply.
 
+### /low-priority: the user's lever, never yours
+
+Claude Code has a hidden toggle, `/low-priority`, offered when the 5-hour session
+limit is reached. It keeps the session working at reduced priority and spends the
+**weekly** limit, plus a separate weekly lower-priority allowance; replies can
+pause while it waits for spare capacity.
+
+**You cannot switch it on.** You cannot type a slash command, and the command is
+declared `supportsNonInteractive: false`, so it does not work in a headless or
+relayed run either. What you may do is say, in one line, that it exists and what
+it costs - and only when the budget line has already said so, because the line is
+the only thing that knows whether this account is provisioned for it at all.
+Never volunteer it otherwise: telling a user to run a command their account does
+not have is worse than saying nothing.
+
+Three rules when the line does mention it:
+
+- **Word it as a possibility.** The offer is gated on an experiment arm that
+  arrives in a response header, and the CLI also withholds it during a cooloff
+  and once the weekly allowance is spent. "If the wall offers it", not "run it".
+- **Never invent a wait time.** The retry interval and its ceiling come from the
+  server on each response. There is no fixed number.
+- **If the line says not to, say not to, and why.** Above 80 per cent weekly it
+  is the wrong move: it spends the window that takes days to come back in order
+  to save one that comes back in hours.
+
+If the user tells you they have switched it on, the honest answer is to record
+it: `node scripts/mode.js --low-priority on`. From then the budget line brakes on
+the weekly instead of the 5-hour window, stops telling you to wind down at the
+5-hour wall, and the relay stops booking a wake for a reset this session no
+longer stops at. **Record it only when they said so.** Whether it is running is
+in the CLI's process memory and readable nowhere, so nothing here may infer it,
+and `mode --low-priority off` is how it is taken back.
+
+The same applies to `/limit-reset`, the once-weekly manual session reset: the
+line names it only if a grant is actually readable, it only works while you are
+at a limit, the work it unlocks still spends the weekly, and how many are left is
+not knowable from here.
+
+And if the budget line says Claude Code is injecting its own wrap-up note at this
+wall, follow that note: it is more specific than anything here, and two
+instructions to wind down in different words is worse than one.
+
 ## 6. Checkpoint before the wall
 
 When the binding window is under roughly 10 percent, or under about ten turns
@@ -865,7 +908,7 @@ stop.
 | `scripts/host.js` | Works out which agent this is running inside, so one host's percentages are never reported against the other's turns. |
 | `scripts/codex.js` | The Codex reader: the meter and the pace out of `~/.codex/sessions`, plus the live `--refresh` call. |
 | `scripts/install-codex-hook.js` | `status`, `on`, `off`. Installs the Codex-side instruction, which Claude Code does not need. |
-| `scripts/mode.js` | The budget mode: no arguments to report it, `max`/`high`/`standard`/`off` to set it, `auto`, `off --guard 95`, `--list`, `--explain <name>`, `--floor`/`--ceiling`/`--pin`, `--baseline`, `--advice`/`--no-advice`, `--history`, `undo`, `--ledger`. Reads settings.json and never writes it. |
+| `scripts/mode.js` | The budget mode: no arguments to report it, `max`/`high`/`standard`/`off` to set it, `auto`, `off --guard 95`, `--list`, `--explain <name>`, `--floor`/`--ceiling`/`--pin`, `--baseline`, `--advice`/`--no-advice`, `--history`, `undo`, `--ledger`, `--low-priority [on|off]`. Reads settings.json and never writes it. |
 | `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. Claude Code only. |
 | `scripts/recommend.js` | The chooser behind `usage.js --recommend`: posture, then the effort and model commands for each lever. Not meant to be called by hand. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
@@ -879,6 +922,7 @@ stop.
 | `scripts/net.js` | Can this machine reach the API, and was a failed run the network's fault. Three probes, TLS-interception detection, and the backoff the offline retries use. |
 | `scripts/wake.js` | What the scheduler runs after the reset: re-checks the meter, then notifies or resumes. Never called by hand. |
 | `scripts/voice.js` | The local writing profile: `show`, `card`, `set "<instruction>"`, `clear`, `off`/`on`, `forget`. |
+| `scripts/lowpri.js` | What Claude Code's own features at the wall are readable as: whether this account is provisioned for `/low-priority`, whether a manual session reset grant exists, whether the CLI injects its own wrap-up note here, whether usage credits are available, whether `autoContinueAtUsageLimit` is on, and the record of the user saying they switched low-priority on. Reads only; never writes anything but that one record. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |
 
 ## Codex controls

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/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,
+};