claude-usage-limits 1.40.5 → 1.41.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.40.5",
+  "version": "1.41.0",
   "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.40.5",
+  "version": "1.41.0",
   "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

@@ -19,6 +19,21 @@ opens with the answer instead:
 
 Nobody read a chart to get that. The numbers reached the model, not you.
 
+![The usage report: the 5-hour window is binding with about 44 turns left, and at the current pace it runs out 38 minutes before the reset.](docs/img/usage-report.png)
+
+<sub>Real output of `npx claude-usage-limits` on the author's machine, 2026-09-26: the Claude Code windows and the closing verdict, with the Codex and per-model sections left out. The plugin puts the same reading into Claude's context, as the budget line, before every prompt.</sub>
+
+Install it as a Claude Code plugin:
+
+```
+/plugin marketplace add ridelink0/claude-code-usage-limits
+/plugin install usage-limits@usage-limits
+```
+
+Or see the report without installing anything: `npx claude-usage-limits`.
+Codex, the plain-skill route and keeping it updated are under
+[Install](#install).
+
 ## What it runs on your machine, and what it never does
 
 Installing this plugin registers six Claude Code hooks, which means Node runs on
@@ -1337,18 +1352,6 @@ percentage and any pressure, the `max` line must never be longer than the
 worse, and every mode path, alias, bound and guard is exercised before
 `settings.json` is compared byte for byte.
 
-## Status
-
-It works and I use it daily.
-
-What I am not doing is fielding feature requests or support questions. If you
-want it to behave differently, fork it and change it, which is what the MIT
-licence is there for. Do not wait on me to add something for you.
-
-## License
-
-MIT. See [LICENSE](LICENSE).
-
 ## The wall is not the end of the budget
 
 A full window is not always a reason to stop, and the plugin now says which.
@@ -1379,119 +1382,20 @@ line said the budget was nearly gone, and the work stopped - with the 5-hour
 window at 46 and every other model untouched. One command would have carried it
 on.
 
-## 1.23.0 - the ceiling, and three hosts that can be told no
-
-Everything before this release reported. This one intervenes.
-
-### The Codex meter was going blind about a third of the time
-
-Codex writes more than one meter into its rollouts, and they are not successive
-readings of one thing. A ChatGPT Plus session carries `limit_id: "codex"`, which
-holds the 5-hour and weekly windows, interleaved with `limit_id: "premium"`,
-which holds the credit balance and has `primary` and `secondary` set to `null`.
-The reader took whichever was written last.
-
-On the machine this was found on, two of every six rollouts ended on a `premium`
-payload - and when one did, the plugin reported no windows at all. Measured on a
-real session: the final line was a `premium` payload two lines after a `codex`
-payload reading **99 per cent of the 5-hour window**, and what reached the agent
-was a meter with nothing in it.
-
-That is the whole of "Codex does not slow down when the limit is close": nothing
-ever told it the limit was close. The reader now keeps the newest reading of each
-meter and prefers the one that actually describes a window. Nothing is merged or
-synthesised - the payload returned is one Codex really wrote.
-
-### An old snapshot is an estimate, not a reading
-
-There was already a warning for a reading spent past its own remainder. It could
-never fire for a snapshot taken at the start of a window, because everything
-spent since is still inside the remainder.
-
-So a session ran for most of an hour being told **7 per cent** while the account
-was at **41**: Claude Code's own cache had not moved in fifty minutes, the
-plugin's live reading was rate-limited into backoff, and the correction was
-quietly carrying the entire difference on its own. A correction is a good
-adjustment to a recent snapshot and a bad substitute for an old one, because the
-pricing error compounds with every point it has to bridge. Past fifteen minutes
-the brief now says the figure is an estimate that can run high or low and points
-at `/usage`. It is only called a floor when the correction has been refused
-outright and the raw snapshot is all that is shown, since that really is a
-lower bound; a snapshot plus a correction is not, and on 2026-09-20 it ran 13
-to 17 points high.
-
-### The ceiling
-
-    node bin/cli.js mode --cap 60
-    node bin/cli.js mode --cap off
-
-Past the ceiling, **fan-out calls are refused at the hook** - `Agent`, `Task`,
-`Workflow` and their equivalents on each host. Everything else keeps working at
-any percentage: reads, edits, tests, commands. The work still finishes, just
-sequentially, in one session, which is where the saving is. A measured fan-out
-costs between 2.6x and 5.9x the same work done in sequence, because every agent
-warms its own cache from cold and none can report back until they all stop.
-
-It is off until you set a number, it never fires without a reading behind it, and
-the refusal says what to do instead - a denial that only says "over budget" gets
-retried.
-
-It is judged on the fullest window this session can spend into, and the refusal
-names that window. A weekly scoped to one model counts only while that model
-runs - by the setting, or by the model the session's last reply came from, so a
-`/model` switch is seen - and a window whose reset has passed does not count.
-Until 1.39.0 it took the highest number on disk, and an Opus session was refused
-on the Fable weekly with a message calling it "the binding window".
-
-**Why a refusal rather than a sentence.** On Codex the reported figure
-demonstrably does not change behaviour, and the reason is not stubbornness.
-`gpt-6-astra`'s own system prompt, shipped in `models_cache.json`, says: *"Do not
-settle for a partial or 'helpful enough' solution that does not fully satisfy the
-user's task to save time, effort or tokens"* - and ranks the live user
-instruction above anything an `AGENTS.md` or a skill says. A line asking it to
-economise is arguing with its own instructions, and losing.
-
-### The Codex subagent clamp
-
-`lowpower on --host codex` now also bounds `[agents]`. Two facts read out of the
-model catalog Codex itself caches, not out of documentation:
-
-    gpt-6-astra: default_reasoning_level    = "low"
-                 multi_agent_reasoning_effort = "xhigh"
-
-Astra's own default effort is the cheapest one, and its subagents run at the
-dearest one **no matter what the session is set to**. Lowering effort without
-bounding them leaves the most expensive path in the product untouched. The clamp
-is a marked block, removed exactly by `lowpower off`, and it refuses outright
-rather than writing a second `[agents]` table over one you wrote yourself.
-`--no-agents` declines just that half.
-
-### Antigravity
-
-    node skills/usage-limits/scripts/install-antigravity.js on
-
-Installs into `~/.gemini/config/plugins/usage-limits/`. `PreInvocation` carries
-the budget line as an injected ephemeral message; `PreToolUse` carries the
-ceiling, which Antigravity implements as a real `decision: "deny"`.
-
-One thing is said plainly rather than papered over: **Antigravity publishes no
-remaining quota anywhere readable on disk.** It refreshes quota - its own log
-says so - and keeps it in memory. A previous version filled that gap by reporting
-*Claude's* meter under a `cross-agent-claude` source, next to a hardcoded plan
-and a model name invented for a settings file that has no model key in it. All of
-that is gone. Where there is nothing to read, the report says the quota is
-unreadable.
-
-### Caveman, and why it is not here
-
-It was on the list for this release and it is not in it. JetBrains ran a
-controlled A/B of the caveman skill - 86 tasks, paired, ~240 billed trials - and
-measured output tokens down **8.5 per cent** against an advertised 65, with
-quality differences indistinguishable from noise (p=0.82). An independent
-benchmark found the literal instruction `be brief.` matched or beat it, and
-because agentic cost is input-dominated, the skill's own rules riding along every
-turn can cost more than they save. Its engine is also BSL-licensed, not open.
-
-Claude Code already ships a built-in **Concise** output style that does the same
-job in the cached system-prompt layer at no marginal cost. Use that. This plugin
-will not ship a measured 8 per cent as a 65 per cent saving.
+## Release notes
+
+What changed in each version is in the [GitHub Releases](https://github.com/ridelink0/claude-code-usage-limits/releases).
+The long notes for 1.23.0, the release that started intervening rather than
+only reporting, are in [docs/1.23.0.md](docs/1.23.0.md).
+
+## Status
+
+It works and I use it daily.
+
+What I am not doing is fielding feature requests or support questions. If you
+want it to behave differently, fork it and change it, which is what the MIT
+licence is there for. Do not wait on me to add something for you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.40.5",
+  "version": "1.41.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

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

@@ -1253,15 +1253,20 @@ function briefText(input) {
   // (autoContinueAtUsageLimit, code.claude.com/docs/en/settings-reference). In
   // place, with the context intact, that is strictly better than a wake: no
   // hand-off file to re-read and nothing lost. So the wake is the route for a
-  // session that will be CLOSED, and saying so is what stops both firing for the
-  // same reset - which would run the work twice and spend the weekly twice.
+  // session that will be CLOSED. Both firing for the same reset would run the
+  // work twice and spend the weekly twice, so since 1.41.0 the wake looks for
+  // this session's process first and stands down when it is open and working
+  // again (wake.js, liveSession). What the CLI does NOT do is continue a session
+  // that stopped short of the wall, at a cap, so that case is said too.
   if (carry && carry.armed && carry.armed.mode === 'resume' && parts.autoContinue && parts.autoContinue.value) {
     relaySentences.push(
       'Claude Code\'s own "Continue automatically at usage limit" is on (' + parts.autoContinue.source +
-        '), so if this terminal is still open at the reset the CLI carries THIS session across by ' +
-        'itself, in place, with its context intact - better than any wake. The wake is the route for a ' +
-        'session that is closed by then. Both firing for the same reset would start the work twice and ' +
-        'spend the weekly twice, so if the terminal is staying open, one of the two is worth standing down.'
+        '), so if this terminal is still open when the limit is hit, the CLI carries THIS session across ' +
+        'the reset by itself, in place, with its context intact - better than any wake. The wake is the ' +
+        'route for a session that is closed by then. Both firing for the same reset would start the work ' +
+        'twice and spend the weekly twice, so the wake checks for this session first and opens no second ' +
+        'window while it is open and working again. The CLI does not continue a session that stopped short ' +
+        'of the limit (at a cap); the wake gives such a session a few minutes, then opens it in one window.'
     );
   }
   if (carry && carry.last) {

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

@@ -904,19 +904,50 @@ function verifyRegistration(state, next, wanted, now) {
   return { ok: true, nextRun: at };
 }
 
-const HIDDEN_HOST = path.join(process.env.SystemRoot || 'C:' + path.sep + 'Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+const SYSTEM32 = path.join(process.env.SystemRoot || 'C:' + path.sep + 'Windows', 'System32');
+const HIDDEN_HOST = path.join(SYSTEM32, 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+const HEADLESS_HOST = path.join(SYSTEM32, 'conhost.exe');
+
+// conhost --headless arrived with the pseudoconsole in Windows 10 1809 (build
+// 17763). Older builds, and anything that is not Windows, keep the PowerShell
+// route alone.
+function headlessAvailable() {
+  if (process.platform !== 'win32') return false;
+  const build = Number(String(os.release()).split('.')[2]);
+  return Number.isFinite(build) && build >= 17763 && fs.existsSync(HEADLESS_HOST);
+}
 
 // The task used to run node.exe directly, and node.exe is a console program:
 // under the scheduler, in an interactive session, it gets a console window
 // of its own. That was the "blank terminal that says Claude" - the wake's own
 // console, shared by its headless child - and closing it killed both (task
-// result 0xC000013A), so the wake never wrote its outcome. PowerShell can
-// start hidden and node inherits that; the session the wake opens for the
-// user is a new window (cmd /c start) and stays visible.
-function hiddenAction(launcher, cwd) {
+// result 0xC000013A), so the wake never wrote its outcome.
+//
+// PowerShell's -WindowStyle Hidden was the first fix, and it only works where
+// the old console host draws the window. Windows 11 hands every new console to
+// Windows Terminal by default, and Terminal ignores the flag: measured
+// 2026-09-27, the task opened a "powershell.exe" Terminal window beside the
+// Claude window the wake started, so the user saw two terminals for one relay
+// and closing the wrong one killed the wake again (0xC000013A the same
+// evening). conhost --headless gives the console no window at all, so there
+// is nothing to hand to Terminal; measured the same evening, the same task
+// under it opened no window, and the session window the wake opens (cmd /c
+// start) still appeared, alone.
+function hiddenAction(launcher, cwd, headless) {
+  const useHeadless = headless === undefined ? headlessAvailable() : headless;
+  const run = '-Command "& ' + psQuote(launcher) + '"';
+  if (useHeadless) {
+    // No -WindowStyle here: there is no window to style, and the 20 characters
+    // matter to the schtasks fallback, which refuses a /TR over 261.
+    return {
+      execute: HEADLESS_HOST,
+      argument: '--headless "' + HIDDEN_HOST + '" -NoProfile -NonInteractive ' + run,
+      cwd: cwd || os.homedir(),
+    };
+  }
   return {
     execute: HIDDEN_HOST,
-    argument: '-NoProfile -NonInteractive -WindowStyle Hidden -Command "& ' + psQuote(launcher) + '"',
+    argument: '-NoProfile -NonInteractive -WindowStyle Hidden ' + run,
     cwd: cwd || os.homedir(),
   };
 }
@@ -1884,7 +1915,7 @@ if (require.main === module) {
     );
 }
 
-module.exports = { workWithContinuation, reapLost, hiddenAction, BUGCHECK_LINE,
+module.exports = { workWithContinuation, reapLost, hiddenAction, headlessAvailable, HEADLESS_HOST, HIDDEN_HOST, BUGCHECK_LINE,
   taskAction, wakeLauncherFile, wakeLauncherScript, writeWakeLauncher, sweepWakeLaunchers, batchArg, describeSpawn, PS_ROUTE_MS, SCHTASKS_MS,
   records, armedFor, putRecord, dropRecord, preflightPrompts, claudeJsonFile, projectKeys, isHome, launchDirFor, applySetting, settingIs,
   DEFAULTS,

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

@@ -308,6 +308,106 @@ function transcriptExists(id) {
   return false;
 }
 
+function transcriptFile(id) {
+  const root = path.join(relay.configDir(), 'projects');
+  try {
+    for (const dir of fs.readdirSync(root)) {
+      const file = path.join(root, dir, id + '.jsonl');
+      if (fs.existsSync(file)) return file;
+    }
+  } catch (err) {
+    // No projects folder at all.
+  }
+  return null;
+}
+
+// ONE TERMINAL.
+//
+// The session a relay was armed for is often still open. Claude Code's own
+// autoContinueAtUsageLimit (on by default) carries an open session across the
+// reset in place, and a wake that opened `claude --resume` beside it put two
+// terminals on the screen running the same conversation - the same work
+// started twice and the weekly spent twice. Gev, 2026-09-27: "fix it to where
+// it makes 1 terminal and not 2".
+//
+// Claude Code keeps one file per running process in <config>/sessions,
+// named for the pid: { pid, sessionId, procStart, kind, cwd, ... }. procStart
+// is the process creation time (a Windows FILETIME, read against
+// Get-Process on 2026-09-27: 134350239768728478 on both sides), which is what
+// tells a live session from a dead one whose pid Windows has handed to
+// something else. A file whose process is gone is left where it is: it is
+// Claude Code's, not the relay's.
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+function processStart(pid) {
+  if (process.platform !== 'win32') return null;
+  const shell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  const run = spawnSync(shell, ['-NoProfile', '-NonInteractive', '-Command', '(Get-Process -Id ' + Number(pid) + ' -ErrorAction Stop).StartTime.ToFileTimeUtc()'], {
+    encoding: 'utf8',
+    timeout: 30000,
+    windowsHide: true,
+  });
+  const said = String(run.stdout || '').trim();
+  return run.status === 0 && /^\d+$/.test(said) ? said : null;
+}
+
+function liveSession(id, io) {
+  const ops = Object.assign({ alive: pidAlive, started: processStart }, io || null);
+  const dir = path.join(relay.configDir(), 'sessions');
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    return null;
+  }
+  for (const name of names) {
+    if (!/^\d+\.json$/.test(name)) continue;
+    let held;
+    try {
+      held = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+    } catch (err) {
+      continue;
+    }
+    if (!held || held.sessionId !== id) continue;
+    const pid = Number(held.pid);
+    if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+    if (!ops.alive(pid)) continue;
+    // A start time that can be read and does not match is a recycled pid.
+    // One that cannot be read (not Windows, or the query failed) leaves the
+    // pid's word as the answer.
+    if (held.procStart) {
+      const started = ops.started(pid);
+      if (started !== null && String(started) !== String(held.procStart)) continue;
+    }
+    return { pid, kind: held.kind || null, cwd: held.cwd || null };
+  }
+  return null;
+}
+
+// Written to since `since`: the open session is working again, which is what
+// the CLI's own continue looks like from outside.
+function transcriptActiveSince(id, since) {
+  const file = transcriptFile(id);
+  if (!file) return false;
+  try {
+    return fs.statSync(file).mtimeMs >= since;
+  } catch (err) {
+    return false;
+  }
+}
+
+// How long a wake that finds the session open but quiet waits for it to start
+// working by itself before opening the one window it would have opened anyway.
+const LIVE_WAIT_MS = 3 * MINUTE;
+const LIVE_POLL_MS = 15 * 1000;
+
 function readExit(file) {
   try {
     const code = parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
@@ -569,6 +669,7 @@ async function run(now, argv, overrides) {
     {
       windowReopened, deliverClaude, deliverCodex, toast, userIsPresent,
       arm: relay.arm, capabilities: relay.capabilities, reachable: net.reachable,
+      liveSession, transcriptActiveSince, sleep: sleepMs, now: Date.now,
     },
     overrides || null
   );
@@ -615,6 +716,35 @@ async function run(now, argv, overrides) {
     return { outcome: 'rescheduled', attempt };
   }
 
+  // ONE TERMINAL (see liveSession). An open session that is working again -
+  // written to since the window reset - has been carried across by the CLI,
+  // and a second window would run the same work twice, so the wake stands
+  // down. One that is open but quiet gets LIVE_WAIT_MS to start by itself
+  // (the CLI's continue, or the session's own timer); if it is closed in that
+  // time, or stays quiet, the wake opens its one window, because nothing
+  // outside a session can type into it and the plan still has to run.
+  if (record.host !== host.CODEX) {
+    const since = Number.isFinite(record.wakeAt) ? record.wakeAt - (config.graceMinutes || 0) * MINUTE : now - 5 * MINUTE;
+    const started = deps.now();
+    let open = deps.liveSession(record.id);
+    while (open) {
+      if (deps.transcriptActiveSince(record.id, since)) {
+        deps.toast(
+          'Usage limits: carried on in place',
+          (record.project || path.basename(record.cwd)) + ' is still open and working again in its own terminal, so no second window was opened.'
+        );
+        finish(state, record, 'live', 'the session is open in process ' + open.pid + ' and working again; no second window', now);
+        return { outcome: 'live', pid: open.pid };
+      }
+      if (deps.now() - started >= LIVE_WAIT_MS) break;
+      deps.sleep(LIVE_POLL_MS);
+      open = deps.liveSession(record.id);
+    }
+    if (open) {
+      relay.note('wake ' + record.id + ': the session is open in process ' + open.pid + ' but idle since the reset; opening it in a window', now);
+    }
+  }
+
   // THE PREFLIGHT.
   //
   // The retry above is the right shape but the wrong budget for the failure it
@@ -848,4 +978,4 @@ if (require.main === module) {
   );
 }
 
-module.exports = { launcherScriptPosix, shQuote, visibleArgs, launcherScript, pointerPrompt, transcriptExists, wakePromptFile, LAUNCH_GRACE_MS, run, toast, userIsPresent, claudeArgs, deliverClaude, deliverCodex, windowReopened, argOf, appendRun, spawnOptionsFor };
+module.exports = { liveSession, transcriptActiveSince, pidAlive, LIVE_WAIT_MS, LIVE_POLL_MS, launcherScriptPosix, shQuote, visibleArgs, launcherScript, pointerPrompt, transcriptExists, wakePromptFile, LAUNCH_GRACE_MS, run, toast, userIsPresent, claudeArgs, deliverClaude, deliverCodex, windowReopened, argOf, appendRun, spawnOptionsFor };