unsnooze 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 1.19.0 — 2026-09-10
+
+Fish shell support, direct help/version commands, and a fix for Codex sessions
+that stop at a reported 99% usage.
+
+### Fish shell support
+
+`unsnooze setup` and `unsnooze install` now install fish wrappers when fish is
+your login shell or its config file already exists. The default location is
+`~/.config/fish/config.fish`; an absolute `XDG_CONFIG_HOME` is respected.
+`unsnooze doctor` checks this file, and `unsnooze uninstall` removes the wrappers.
+Re-running setup replaces the existing block and preserves your other settings.
+Use `--fishrc <path>` with install or uninstall to choose another config file.
+
+After upgrading, run `unsnooze setup` once to add the fish wrappers, then open
+a new shell. Thanks to [@duncanmcqueen](https://github.com/duncanmcqueen) for
+[PR #21](https://github.com/saaranshM/unsnooze/pull/21).
+
+### Help and version commands run directly
+
+Commands such as `claude --help` and `codex --version` now pass straight to
+the agent. They do not open a multiplexer session, start a pane monitor,
+prepend `launchExtraArgs`, or append an unsnooze update notice. The existing
+print-mode passthrough is unchanged. Thanks to [@chid](https://github.com/chid)
+for [PR #23](https://github.com/saaranshM/unsnooze/pull/23).
+
+### Codex can be detected as stopped at a reported 99%
+
+The GUI watcher now recognizes the sequence reported in
+[issue #20](https://github.com/saaranshM/unsnooze/issues/20): a five-hour Codex
+window reaches 99%, then the next rate-limit snapshot switches to an empty
+`premium` bucket with no credits. It records the stop and schedules the session
+using the previous reset time, plus the normal safety margin.
+
+This fallback requires snapshots from the same rollout no more than a minute
+apart, no available credits, and a future reset time. It works across watcher
+polls and daemon restarts. An already-exhausted weekly window still takes
+precedence if it resets later. A 99% reading alone does not trigger a resume.
+
+The separate report of stale 64% usage was not reproduced; this release fixes
+the missed stop detection. Thanks to [@mio-tsuki](https://github.com/mio-tsuki)
+for the sample. Fixed in [PR #24](https://github.com/saaranshM/unsnooze/pull/24).
+
+### Test fixes
+
+- Permission tests now set their required file mode explicitly, so they pass
+  with different system umasks. Thanks to
+  [@Chang-Jin-Lee](https://github.com/Chang-Jin-Lee) for
+  [PR #22](https://github.com/saaranshM/unsnooze/pull/22).
+- Fish install/uninstall tests use temporary profiles and leave existing user
+  settings, wrappers, and daemon state untouched.
+- Help/version tests use a portable test executable instead of relying on
+  platform-specific `echo` behavior.
+
 ## 1.18.0 — 2026-09-02
 
 **Cursor CLI support**, a wrapper change that keeps `cursor .` working, and a

package/README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/saaranshM/unsnooze/actions/workflows/ci.yml/badge.svg)](https://github.com/saaranshM/unsnooze/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/unsnooze?color=f59e0b)](https://www.npmjs.com/package/unsnooze)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3fb950)](package.json)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2020.12-3fb950)](package.json)
 [![license](https://img.shields.io/badge/license-MIT-8b949e)](LICENSE)
 
 **Automatically resume every limit-stopped AI coding session when its usage limit resets.**
@@ -223,7 +223,8 @@ Two things worth knowing:
 
 ## GUI surfaces (VS Code extension, desktop apps)
 
-Terminal sessions are watched through the shell wrapper + tmux, Zellij, or herdr. Sessions in
+Terminal sessions are watched through the shell wrapper and tmux, Zellij, herdr,
+or cmux, with headless watching when no multiplexer is available. Sessions in
 **Claude Code's VS Code extension / desktop app** and **Codex's IDE
 extension / desktop app** have no pane to scrape — so `unsnooze daemon` tails
 the session files those surfaces already write:
@@ -239,6 +240,10 @@ the session files those surfaces already write:
   where Codex lives only inside ChatGPT.app (no `codex` on PATH), unsnooze
   automatically resumes through the app-bundled binary
   (`/Applications/ChatGPT.app/Contents/Resources/codex`).
+  The watcher also recognizes a reported 99% five-hour window followed within
+  one minute by an empty `premium` bucket with no credits, using the previous
+  future reset time. The snapshots must come from the same rollout; 99% alone
+  is not a stop signal. This works across watcher polls and daemon restarts.
 - **Claude desktop (cowork) sessions** *(experimental, macOS)* run in
   sandboxes under `~/Library/Application Support/Claude`; unsnooze watches
   those too and revives with the session's isolated `CLAUDE_CONFIG_DIR`
@@ -289,11 +294,11 @@ StopFailure hook (claude, grok) ──────────────┤
 
 </details>
 
-Limit events are never persisted by the CLIs themselves; the reset time is
-parsed from the banner text, DST-safe. Unparseable banners are never guessed
-at — unsnooze probes the pane on a backoff schedule until a real reset time
-appears. Every resume is verified afterwards (banner came back → reschedule
-from the fresh banner, capped at 5 attempts).
+Detection uses agent hooks, saved session files, and terminal banners. Reset
+times come from the agent's saved timestamp or the banner text, parsed DST-safe.
+When no reset time is available, unsnooze probes on a backoff schedule. Every
+resume is verified afterwards (banner came back → reschedule from the fresh
+banner, capped at 5 attempts).
 
 ## Know the wall before you hit it
 
@@ -680,9 +685,20 @@ watcher stops (no pane context) always use native.
   [Watching without a multiplexer](#watching-without-a-multiplexer))
 - tmux ≥ 3.2, Zellij, **or** herdr ≥ 0.8.0 for pane-level watching. Optional:
   without one, unsnooze runs `headless` and still catches and resumes stops.
-- zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), or PowerShell
+- zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), fish (wrappers go
+  into `~/.config/fish/config.fish`), or PowerShell
   (wrappers go into `$PROFILE.CurrentUserAllHosts`)
 
+Fish wrappers are installed when fish is the login shell or its config already
+exists. An absolute `XDG_CONFIG_HOME` changes the config location to
+`$XDG_CONFIG_HOME/fish/config.fish`; `unsnooze install --fishrc <path>` and
+`unsnooze uninstall --fishrc <path>` override it explicitly. After upgrading an
+existing install, run `unsnooze setup` and open a new shell to load the wrappers.
+
+Agent help/version commands, such as `claude --help` and `codex --version`, run
+directly without a multiplexer session, pane monitor, `launchExtraArgs`, or an
+unsnooze update notice. `unsnooze help` still shows unsnooze's own commands.
+
 ### Supported terminals
 
 unsnooze drives four terminal multiplexers, and works without one.

package/bin/unsnooze.js

@@ -69,7 +69,7 @@ async function maybeLaunchExitNotice(args) {
   try {
     if (process.env.TMUX || process.env.ZELLIJ || process.env.UNSNOOZE_ACTIVE === '1') return;
     if (!process.stderr.isTTY) return;                            // pipes, CI, scripts
-    if (args.includes('-p') || args.includes('--print')) return;  // non-interactive runs
+    if (args.some(a => a === '-p' || a === '--print' || a === '-h' || a === '--help' || a === '-v' || a === '-V' || a === '--version')) return;  // non-interactive runs
     const mod = await safeImport('../src/update-check.js');
     if (!mod) return;
     const notice = mod.launchExitNotice();
@@ -340,17 +340,23 @@ Usage:
   unsnooze usage [--json]          account burn rate & time-to-limit forecast
                                    (--install-statusline for exact Claude %,
                                     --uninstall-statusline to remove it)
+  unsnooze design [setup]          Claude Design from the terminal: check whether
+                                   the claude-design MCP server is registered and
+                                   signed in, or register it with setup
   unsnooze logs [-f]               show (or follow) the unsnooze log
   unsnooze update                  update unsnooze itself to the latest version
   unsnooze daemon                  persistent watcher for GUI sessions (VS Code
                                    extension, desktop apps) — no live pane needed
-                                   to detect; revival opens in tmux or Zellij
+                                   to detect; revival opens in your multiplexer,
+                                   or headless where there is none
   unsnooze config [list|get|set]   view or change settings (toggles, global +
                                    per-agent resume messages, notifyChannel
                                    auto|native|osc|bell, updateCheck)
   unsnooze setup                   interactive setup wizard (agents + toggles)
   unsnooze install [--yes]         wire up shell wrappers + hooks (non-interactive)
+                                   (--fishrc <path> overrides the fish config)
   unsnooze uninstall [--purge]     remove wrappers + hooks (and state with --purge)
+                                   (--fishrc <path> overrides the fish config)
   unsnooze report [agent] [pane]   capture a pane to report an undetected banner
   unsnooze help                    show this help (also -h / --help)`);
       return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, Antigravity, and Cursor CLI sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",

package/src/doctor.js

@@ -16,6 +16,7 @@ import { makeLogger } from './logger.js';
 import { shouldUseTui, formatDoctorTui } from './tui.js';
 import { designRegisteredOffline } from './design.js';
 import { powershellProfilePath } from './powershell.js';
+import { fishConfigPath } from './fish.js';
 
 const log = makeLogger('doctor');
 
@@ -116,13 +117,14 @@ function readOrEmpty(path) {
 // wrappers installed" is a health question — but it has to be asked of the
 // right file. A PowerShell user has no ~/.zshrc, so checking only the POSIX rc
 // files made every native-Windows `unsnooze doctor` report the wrappers
-// missing and point the user at an install they had already run.
+// missing and point the user at an install they had already run. A fish user
+// has no POSIX rc wrapper either — their block lives in the fish config.
 function defaultWrappersInstalled({
   platform = process.platform,
   rcContent = readOrEmpty,
   profileContent = null,
 } = {}) {
-  const rcs = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc')];
+  const rcs = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc'), fishConfigPath()];
   if (rcs.some(rc => rcContent(rc).includes(WRAPPER_MARK))) return true;
   if (platform !== 'win32') return false;
   const readProfile = profileContent

package/src/fish.js

@@ -0,0 +1,22 @@
+// Where the fish shell looks for its config.
+//
+// A leaf module (node builtins only) on purpose — the same reason
+// powershell.js exists: install.js already imports doctor.js, and doctor.js
+// needs this to answer "are the wrappers installed?" for fish users.
+// Declaring it in install.js would close that loop (see
+// test/module-graph.test.js for what that breaks).
+//
+// fish reads its config from <config-home>/fish/config.fish, where
+// <config-home> honors XDG_CONFIG_HOME (absolute paths only — the XDG spec
+// says a relative value must be ignored, and fish follows that).
+
+import { homedir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+
+export function fishConfigPath({ env = process.env, home = homedir() } = {}) {
+  // Test/CI override, matching UNSNOOZE_QWEN_DIR and the autostart dir vars.
+  if (env.UNSNOOZE_FISH_CONFIG) return env.UNSNOOZE_FISH_CONFIG;
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg && isAbsolute(xdg)) return join(xdg, 'fish', 'config.fish');
+  return join(home, '.config', 'fish', 'config.fish');
+}

package/src/install.js

@@ -5,8 +5,11 @@
 //     atomic write)
 //   - ~/.zshrc + ~/.bashrc: one fence-marked block with a wrapper function per
 //     enabled agent (claude/codex/grok), routed through `unsnooze _run`
+//   - ~/.config/fish/config.fish: the same block in fish syntax (fish shares
+//     no syntax with POSIX rc files — a bash function there is a parse error)
 //   - ~/.grok/hooks/unsnooze.json when the grok agent is enabled
-// --settings <path> / --zshrc <path> override targets (used by tests).
+// --settings <path> / --zshrc <path> / --fishrc <path> override targets (used
+// by tests).
 
 import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
@@ -21,6 +24,7 @@ import { findCsgProcesses, findCsgAutostarts } from './doctor.js';
 import { UNSNOOZE_BIN, stopResumer } from './spawn.js';
 import { uninstallStatuslineShim } from './usage.js';
 import { powershellProfilePath } from './powershell.js';
+import { fishConfigPath } from './fish.js';
 
 const FENCE_OPEN = '# >>> unsnooze >>>';
 const FENCE_CLOSE = '# <<< unsnooze <<<';
@@ -33,13 +37,17 @@ const LEGACY_FENCES = [
 const OLD_FENCE_OPEN = LEGACY_FENCES[0].open;
 
 function parseArgs(rest) {
-  const opts = { yes: false, settings: CLAUDE_SETTINGS, zshrc: join(homedir(), '.zshrc'), purge: false, daemon: false };
+  const opts = {
+    yes: false, settings: CLAUDE_SETTINGS, zshrc: join(homedir(), '.zshrc'),
+    fishrc: fishConfigPath(), purge: false, daemon: false,
+  };
   for (let i = 0; i < rest.length; i++) {
     if (rest[i] === '--yes' || rest[i] === '-y') opts.yes = true;
     else if (rest[i] === '--purge') opts.purge = true;
     else if (rest[i] === '--daemon') opts.daemon = true;
     else if (rest[i] === '--settings') opts.settings = rest[++i];
     else if (rest[i] === '--zshrc') opts.zshrc = rest[++i];
+    else if (rest[i] === '--fishrc') opts.fishrc = rest[++i];
   }
   return opts;
 }
@@ -204,6 +212,38 @@ export function installZshrcBlock(content, agents = ['claude']) {
   return { content: result, oldRemoved };
 }
 
+// The fish twin of wrapperBlock(). Fish shares no syntax with the POSIX block:
+// `name() { … }` is a parse error there, `$?` is `$status`, and `"${X}"` is
+// `"${X}"` verbatim text — so the wrapper gets its own body. Same semantics as
+// the zsh/bash wrapper: a recursion guard (UNSNOOZE_ACTIVE), the load-bearing
+// missing-file fallback to the real CLI, and `_run <id>` routing.
+//
+// Redefining a function replaces any earlier one, which covers fish "aliases"
+// (they are functions too) — no `unalias` analogue is needed. Fish comments
+// are `#`, so the same fence markers work and stripFencedBlock() removes it
+// unchanged.
+export function fishWrapperBlock(agents = ['claude'], bin = UNSNOOZE_BIN) {
+  const fns = agents.flatMap(id => wrapperNamesFor(id).map(name => `function ${name} --description 'unsnooze-wrapped ${name}'
+  if test "$UNSNOOZE_ACTIVE" = "1"; or not test -f '${bin}'
+    command ${name} $argv
+    return $status
+  end
+  node '${bin}' _run ${id} $argv
+end`)).join('\n');
+  return `${FENCE_OPEN}
+# unsnooze wrappers: route every interactive launch of the CLIs below through
+# unsnooze so limit stops are recorded and auto-resumed.
+${fns}
+${FENCE_CLOSE}`;
+}
+
+// installZshrcBlock's fish twin. Same fence, same replace-don't-append
+// behaviour, so re-running setup never stacks a second copy of the wrappers.
+export function installFishBlock(content, agents = ['claude'], bin = UNSNOOZE_BIN) {
+  const { content: cleaned } = stripFencedBlock(content, FENCE_OPEN, FENCE_CLOSE);
+  return cleaned.replace(/\n+$/, '\n') + '\n' + fishWrapperBlock(agents, bin) + '\n';
+}
+
 // --- daemon autostart ---
 // GUI sessions (VS Code extension, desktop apps) never pass through the shell
 // wrappers, so their limit stops are only caught while `unsnooze daemon` is
@@ -555,6 +595,22 @@ function rcTargets(opts, explicit) {
   return existing.length > 0 ? existing : [opts.zshrc];
 }
 
+// The fish config is a separate target from the POSIX rc loop: fish syntax
+// shares nothing with bash, so it gets its own block, and fish reads only
+// <config-home>/fish/config.fish. Touch it when the file already exists (the
+// same any-rc rule as zsh/bash), or when fish is the login shell — a fish
+// user may not have created config.fish yet, and a wrapper that would never
+// load is the same silent-miss as a profile written to a guessed path. Empty
+// list = no evidence of fish on this machine; leave it alone.
+function fishTargets(opts, explicit) {
+  if (explicit) return [opts.fishrc];
+  const cfg = fishConfigPath();
+  if (existsSync(cfg)) return [cfg];
+  const loginShell = process.env.SHELL || userInfo().shell;
+  if (typeof loginShell === 'string' && /(^|\/|\\)fish$/.test(loginShell)) return [cfg];
+  return [];
+}
+
 export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
   const opts = parseArgs(rest);
   const explicitRc = rest.includes('--zshrc');
@@ -623,6 +679,21 @@ export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
     }
   }
 
+  // 3c. Fish config. The POSIX loop above is a parse error in fish, and the
+  //     PowerShell profile never loads there — fish needs its own block or a
+  //     fish user's `claude` never routes through unsnooze at all.
+  for (const cfg of fishTargets(opts, rest.includes('--fishrc'))) {
+    try {
+      mkdirSync(dirname(cfg), { recursive: true });
+      const before = existsSync(cfg) ? readFileSync(cfg, 'utf-8') : '';
+      if (existsSync(cfg)) backupOnce(cfg);
+      atomicWrite(cfg, installFishBlock(before, agents, UNSNOOZE_BIN));
+      console.log(`unsnooze: fish wrappers (${agents.join(', ')}) installed in ${cfg}`);
+    } catch (err) {
+      console.log(`unsnooze: could not write the fish config (${err.message})`);
+    }
+  }
+
   // 4. Daemon autostart (GUI-session watching), opt-in via --daemon / wizard.
   if (opts.daemon) {
     const target = installDaemonAutostart();
@@ -698,6 +769,17 @@ export function cmdUninstall(rest) {
     console.log(`unsnooze: could not clean the PowerShell profile (${err.message})`);
   }
 
+  // The fish config is a wrapper site too, same reason as the PowerShell
+  // profile above: a stale block would keep shadowing the real CLI.
+  for (const cfg of fishTargets(opts, rest.includes('--fishrc'))) {
+    if (!existsSync(cfg)) continue;
+    const { content, found } = stripFencedBlock(readFileSync(cfg, 'utf-8'), FENCE_OPEN, FENCE_CLOSE);
+    if (found) {
+      atomicWrite(cfg, content);
+      console.log(`unsnooze: fish wrappers removed from ${cfg}`);
+    }
+  }
+
   const autostart = uninstallDaemonAutostart();
   if (autostart) console.log(`unsnooze: daemon autostart removed (${autostart})`);
 

package/src/launcher.js

@@ -2,7 +2,7 @@
 //   - outside a multiplexer: re-exec through its launchWrapped operation
 //   - inside one: spawn a detached per-pane monitor, then run the CLI,
 //     propagating its exit code
-//   - -p/--print: pure pass-through, no monitor (nothing interactive to scrape)
+//   - -p/--print, -h/--help, -v/-V/--version: pure pass-through, no monitor (nothing interactive to scrape)
 
 import { spawn, spawnSync } from 'node:child_process';
 import { getMultiplexer } from './multiplexer.js';
@@ -16,8 +16,12 @@ import { AgentDispatchedError, SessionCreateError, attachHint } from './multiple
 
 const log = makeLogger('launcher');
 
-function isPrintMode(args) {
-  return args.includes('-p') || args.includes('--print');
+export function isPassthrough(args = []) {
+  return args.some(a =>
+    a === '-p' || a === '--print'
+    || a === '-h' || a === '--help'
+    || a === '-v' || a === '-V' || a === '--version'
+  );
 }
 
 export function resolvePaneOwner(muxName, env = process.env) {
@@ -44,7 +48,12 @@ export function runLauncher(args, agentId = 'claude', { processBirthFn = process
   // Recursion / nested-launch guard: inside an unsnooze-managed session, a
   // plain `claude`/`codex`/`unsnooze` call goes straight through. Same for an
   // agent the user disabled in settings — run it, don't watch it.
-  if (process.env.UNSNOOZE_ACTIVE === '1' || isPrintMode(args) || !getConfig(`agents.${agent.id}`)) {
+  //
+  // Non-interactive / informational invocations (-p/--print, -h/--help, -v/--version)
+  // also bypass multiplexer wrapping and monitoring — running a new tmux session
+  // or spawning a watcher for `claude --help` flashes the screen and slows down
+  // simple queries.
+  if (process.env.UNSNOOZE_ACTIVE === '1' || isPassthrough(args) || !getConfig(`agents.${agent.id}`)) {
     const r = spawnSync(agent.bin, args, { stdio: 'inherit', env: { ...process.env, UNSNOOZE_ACTIVE: '1' } });
     return r.status ?? 1;
   }

package/src/watcher.js

@@ -22,7 +22,7 @@ import {
 } from './config.js';
 import { getMultiplexer } from './multiplexer.js';
 import { parseTranscriptLine } from './watchers/claude.js';
-import { parseRolloutLine, rolloutMeta } from './watchers/codex.js';
+import { parseRolloutLines, rolloutMeta } from './watchers/codex.js';
 import { ROLLOUT_RE } from './agents/codex.js';
 import { parseResetTime, resetAtMs } from './time-parser.js';
 import { upsertSession, readState, updateState } from './state.js';
@@ -85,8 +85,8 @@ export function codexSource({ roots }) {
     roots,
     enabled: () => getConfig('agents.codex'),
     match: p => ROLLOUT_RE.test(basename(p)),
-    parse(lines, path) {
-      const hits = lines.map(parseRolloutLine).filter(Boolean);
+    parse(lines, path, { offset } = {}) {
+      const hits = parseRolloutLines(lines, { path, offset });
       if (hits.length === 0) return [];
       const last = hits[hits.length - 1];   // the latest snapshot governs
       const meta = rolloutMeta(path);
@@ -322,7 +322,10 @@ export function createWatcher({
     const lastNl = buf.lastIndexOf(0x0a);
     if (lastNl === -1) { setOffset(path, offset); return null; }  // partial line — wait
     setOffset(path, offset + lastNl + 1);
-    return buf.subarray(0, lastNl + 1).toString('utf-8').split('\n').filter(l => l.trim());
+    return {
+      offset,
+      lines: buf.subarray(0, lastNl + 1).toString('utf-8').split('\n').filter(l => l.trim()),
+    };
   }
 
   function walk(dir, depth, cb) {
@@ -353,11 +356,12 @@ export function createWatcher({
             const usageMatch = source.usageMatch ? source.usageMatch(path) : stopMatch;
             if (!stopMatch && !usageMatch) return;
             seen.add(path);
-            const lines = readAppended(path);
-            if (!lines || lines.length === 0) return;
+            const appended = readAppended(path);
+            if (!appended || appended.lines.length === 0) return;
+            const { lines, offset } = appended;
             if (stopMatch) {
               try {
-                candidates.push(...source.parse(lines, path));
+                candidates.push(...source.parse(lines, path, { offset }));
               } catch (err) {
                 log(`parse error in ${path}: ${err.message}`);
               }

package/src/watchers/codex.js

@@ -23,17 +23,29 @@ export { extractCodexUsage } from '../usage.js';
 // must not conflate it with the weekly bucket.
 import { labelWindow } from '../usage.js';
 
-// One rollout JSONL line → limit-stop candidate or null. A window binds when
-// its used_percent hits 100 (or rate_limit_reached_type says the model was
-// actually blocked); with several exhausted windows the LATEST reset governs —
-// resuming at the earlier one would immediately re-hit the other limit.
-export function parseRolloutLine(line) {
+function rolloutSnapshot(line) {
   if (!line || !line.trim()) return null;
   let entry;
   try { entry = JSON.parse(line); } catch { return null; }
   if (entry?.type !== 'event_msg' || entry.payload?.type !== 'token_count') return null;
   const rl = entry.payload.rate_limits;
   if (!rl || typeof rl !== 'object') return null;
+  return entry;
+}
+
+function emptyPremium(rl) {
+  return rl.limit_id === 'premium' && rl.primary === null && rl.secondary === null
+    && rl.credits?.has_credits === false && rl.credits?.unlimited === false
+    && rl.credits?.balance != null && rl.credits.balance !== ''
+    && Number(rl.credits.balance) === 0;
+}
+
+// With several exhausted windows, the latest reset governs: resuming at an
+// earlier one would immediately hit the other limit again.
+function parseSnapshot(entry, previous = null) {
+  if (!entry) return null;
+  const rl = entry.payload.rate_limits;
+  const ts = entry.timestamp ? Date.parse(entry.timestamp) : NaN;
 
   const windows = ['primary', 'secondary']
     .map(k => rl[k])
@@ -48,9 +60,28 @@ export function parseRolloutLine(line) {
       ? named
       : windows.reduce((a, b) => ((b.resets_at || 0) > (a?.resets_at || 0) ? b : a), null);
   }
+  // #20: Codex can stop at a reported 99%, then emit an empty premium bucket
+  // instead of a 100% snapshot. Infer a stop only for that transition,
+  // in the same rollout, within a minute, with no credits and a future reset.
+  // A lone 99% snapshot or an unrelated premium bucket is not a stop.
+  if (!binding && emptyPremium(rl) && previous) {
+    const prior = previous.payload.rate_limits;
+    const elapsed = ts - Date.parse(previous.timestamp);
+    const primary = prior.primary;
+    if (prior.limit_id === 'codex' && elapsed >= 0 && elapsed <= 60_000
+        && primary?.window_minutes === 300
+        && Number.isFinite(primary.used_percent) && primary.used_percent >= 99
+        && Number.isFinite(primary.resets_at) && primary.resets_at * 1000 > ts) {
+      binding = primary;
+      const secondary = prior.secondary;
+      if (Number.isFinite(secondary?.used_percent) && secondary.used_percent >= 100
+          && Number.isFinite(secondary.resets_at) && secondary.resets_at > binding.resets_at) {
+        binding = secondary;
+      }
+    }
+  }
   if (!binding) return null;
 
-  const ts = entry.timestamp ? Date.parse(entry.timestamp) : NaN;
   return {
     limitType: labelWindow(binding.window_minutes),
     resetAt: binding.resets_at ? binding.resets_at * 1000 : null,
@@ -59,6 +90,48 @@ export function parseRolloutLine(line) {
   };
 }
 
+export function parseRolloutLine(line) {
+  return parseSnapshot(rolloutSnapshot(line));
+}
+
+// Look immediately before the appended batch, not at the file's current EOF:
+// it may have grown since the watcher read it. This also works after restart
+// without persisting another cache alongside the watcher's byte offsets.
+function previousSnapshot(path, offset) {
+  if (!path || !Number.isSafeInteger(offset) || offset <= 0) return null;
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const length = Math.min(offset, 4 * 1024 * 1024);
+    const buf = Buffer.alloc(length);
+    const count = readSync(fd, buf, 0, length, offset - length);
+    const lines = buf.subarray(0, count).toString('utf-8').split('\n');
+    if (offset > length) lines.shift(); // the first line may be truncated
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const snapshot = rolloutSnapshot(lines[i]);
+      if (snapshot) return snapshot;
+    }
+  } catch { /* missing context means no inferred stop */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  return null;
+}
+
+export function parseRolloutLines(lines, { path, offset } = {}) {
+  let previous;
+  const hits = [];
+  for (const line of lines) {
+    const snapshot = rolloutSnapshot(line);
+    if (!snapshot) continue;
+    if (previous === undefined && emptyPremium(snapshot.payload.rate_limits)) {
+      previous = previousSnapshot(path, offset);
+    }
+    const hit = parseSnapshot(snapshot, previous);
+    if (hit) hits.push(hit);
+    previous = snapshot;
+  }
+  return hits;
+}
+
 // The session_meta head line can be very long (it embeds the full base
 // instructions) — read in chunks until the first newline.
 function readFirstLine(path, maxBytes = 256 * 1024) {