unsnooze 1.18.0 → 1.19.1

package/CHANGELOG.md

@@ -1,5 +1,188 @@
 # Changelog
 
+## 1.19.1 — 2026-09-21
+
+A Codex usage reading that was averaged down, a headless Codex revival
+that could never have worked — reported as a success — and Codex stops that
+were never seen at all behind a proxy or in a reverted thread.
+
+### `unsnooze usage` reports Codex's exact percentage as read
+
+The 64% in [issue #20](https://github.com/saaranshM/unsnooze/issues/20) was
+`(29 + 99) / 2`: a jump of more than 15 points was averaged with the reading
+before it and still labelled `exact`. The averaging was meant to soften a
+one-tick spike, but at the moment a session is blocked no further reading
+arrives, so the low number stayed for the rest of the window — and 64 is
+below the 80/95 warning thresholds, so the usage-wall notification never
+fired. Codex's `used_percent` is the server's own number and is now shown
+unchanged (still clamped to 0–100).
+
+Two things could put a much lower reading in front of the latest one: Codex
+writes one snapshot per rate-limit bucket per response, and `unsnooze usage`
+read every bucket (`premium`, `codex_other`, …) as the account window; and
+Codex Desktop tabs and sub-agents each write their own rollout, so "the
+previous reading" could be another thread's minutes-old snapshot. Only the
+account bucket feeds the 5h/weekly lines now, and burn is measured between
+readings of the same rollout. Thanks to
+[@mio-tsuki](https://github.com/mio-tsuki) for working out the arithmetic.
+
+### Headless Codex revivals run, and a revival that dies says so
+
+[Issue #25](https://github.com/saaranshM/unsnooze/issues/25): on Windows the
+daemon's Scheduled Task could not find `codex`, every revival died with
+`spawn codex ENOENT`, and unsnooze logged `verified resumed` anyway.
+
+- **`codex exec resume`.** Under the headless backend a revival ran the Codex
+  TUI, which exits before touching the session when stdin is not a terminal —
+  on every OS, since the backend shipped in 1.16.0. Headless Codex revivals
+  now run `codex exec resume <id> "<prompt>"`, which continues the same
+  conversation non-interactively, the way Claude's headless revival already
+  passed its prompt in argv. It is given `--skip-git-repo-check`: `exec`
+  refuses any directory that is not a git repository, which the TUI never
+  did, and the session being revived already ran there. `resumeExtraArgs.codex`
+  goes right after `exec`, where `-s`, `-p` and `--add-dir` parse; after
+  `resume` they were rejected outright.
+- **A dead revival is a failed attempt.** With no pane to capture, an empty
+  capture used to count as a cleared banner. The headless backend now records
+  each revival's exit, and a non-zero one puts the stop back on the ledger
+  with backoff and a `last error` that carries the child's own words — visible
+  in `unsnooze status`, and kept when unsnooze finally gives up on the session.
+  A revival still running at the 20-second check is watched for up to two
+  minutes before it counts as resumed, long enough to catch the failures that
+  take a while (an auth refresh giving up, a retry loop); exit 0 counts as
+  resumed. A revival started by a resumer the Claude hook spawned no longer
+  inherits Claude's nested-launch marker, which had made it drop
+  `launchExtraArgs` and fail with a bare "exit 1".
+- **A revival into a deleted directory no longer takes the daemon down.** When
+  a session's directory was gone (a removed worktree, say), the headless
+  launch failed with an error nothing was listening for, and the daemon
+  crashed. It is now an ordinary failed attempt that names the reason.
+- **`unsnooze preview` shows the headless command.** It described a typed
+  resume and the Codex TUI for sessions that dispatch revives through argv
+  and `codex exec resume`.
+- **Windows finds the Codex runtime.** The Desktop/Store install keeps
+  `codex.exe` under a versioned directory that changes on update, and a daemon
+  started at logon keeps the PATH it was born with. Codex is now resolved at
+  launch: `UNSNOOZE_CODEX_BIN`, then `codex.exe` on PATH, then the newest
+  runtime under `%LOCALAPPDATA%\OpenAI\Codex\bin`. A `.cmd`/`.bat` shim
+  cannot be launched directly by Node; the launcher now says so and names the
+  variable to point at the `.exe` instead of failing with `EINVAL`.
+- **`unsnooze doctor` names each agent's binary** as the launcher would resolve
+  it, and reports an agent that cannot be launched as a health problem — on
+  Windows with the note that the daemon's environment can lag the shell's and
+  how to refresh it. Only for agents that have run on the machine: Claude and
+  Codex are both on by default, and a Claude-only machine is not unhealthy for
+  having no `codex`. The lookup follows spawn's own Windows rules: an `.exe`
+  anywhere on PATH wins over an npm shim earlier on it, quoted PATH entries
+  count, and a path given without its extension finds the `.exe`.
+- **Codex stops bind to the right reset.** A `rate_limit_reached` at a reported
+  99.x% was scheduled for the *weekly* reset (the latest one), days out; it now
+  binds the window nearest exhaustion. A workspace wall — credits depleted or
+  a spend cap, with no window spent — has no reset to wait for: it is announced
+  as needing you rather than "resumes when the limit resets", probed, and then
+  held with the remedy (add credits or raise the cap, then continue the
+  session in Codex) instead of a blind wake. A spent window (99% or more)
+  still governs when a workspace reason rides along, since its reset is what
+  brings the plan allowance back. `unsnooze status --json` shows the reason as
+  `limitReason`.
+- **A weaker reading no longer undoes an exact reset.** A re-detected stop
+  whose only evidence is a banner ("Try again later.") used to replace the
+  exact reset the rollout snapshot had given, turning a known wake into a
+  15-minute probe; the stronger schedule now stands until it passes, the rule
+  pane detection already followed. `unsnooze usage` in the dashboard also
+  stops reading Codex burn as idle whenever the daemon is running.
+
+The Windows resolution follows the layout in the report and wants a Windows
+run before it is trusted; continuing an open Codex Desktop thread in place
+(`codex queue`) is a separate follow-up. Thanks to
+[@nwn900](https://github.com/nwn900) for the precise report.
+
+### Codex stops behind a proxy, and in reverted threads
+
+[Issue #27](https://github.com/saaranshM/unsnooze/issues/27) found two ways
+a Codex desktop-app or IDE session went untracked:
+
+- **Reverted threads are watched.** An edited, regenerated or `/undo`-ed
+  thread continues in `rollout-<ts>-<thread id>_<rollout id>.jsonl`, a name
+  the rollout watcher never opened. Those files are now watched, counted by
+  `unsnooze usage`, and resumed by the stable thread id.
+- **A stop recorded only as an error is a stop.** Behind an OpenAI-compatible
+  proxy the rate-limit headers never reach Codex, every snapshot has empty
+  windows, and no stop was ever detected. Since codex-cli 0.145 the failed
+  turn's `task_complete` carries the limit error itself; unsnooze now reads
+  it and dates it from the banner the way a scraped pane is dated ("Try again
+  later." is probed). When the same turn also wrote an exhausted snapshot,
+  its exact reset still wins, and a workspace wall — in the snapshot or in
+  the banner's own words — stays a wall. Only the banner counts: Codex marks
+  billing and plan errors ("Quota exceeded…", "upgrade to Plus…") with the
+  same `usage_limit_exceeded` code, and those are not stops, nor is a bare 429,
+  which carries no reset time.
+- **Codex's current banner is recognized.** Codex now writes "You’ve hit your
+  usage limit" with a typographic apostrophe; the anchor accepts both, in
+  rollouts and in panes.
+- **A reset in the banner's own minute is not tomorrow.** Codex prints the
+  reset time without seconds, so a limit hit at 7:36:15 that resets at
+  7:36:40 says "try again at 7:36 AM" — which was read as 7:36 the next
+  morning, a day late. It now wakes at 7:37.
+
+Thanks to [@d-jiao](https://github.com/d-jiao) for the report, the fix in
+[PR #28](https://github.com/saaranshM/unsnooze/pull/28), and checking it
+against 523 real rollouts.
+
+## 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,19 @@ 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.
+  Since codex-cli 0.145 the failed turn's `task_complete` also carries the
+  limit error itself (`codex_error_info: "usage_limit_exceeded"` plus the
+  banner text), and unsnooze reads that too — it is the only signal when
+  Codex runs behind an OpenAI-compatible proxy (`model_providers.<x>.base_url`),
+  where the rate-limit headers never reach Codex and every snapshot has empty
+  windows. The banner's time is parsed like a scraped pane; "Try again later."
+  takes the probe path. Reverted threads (the desktop app's edit/regenerate,
+  `/undo`) continue in `rollout-<ts>-<thread id>_<rollout id>.jsonl`; those
+  files are watched and resumed by the stable thread id.
 - **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 +303,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 +694,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.
@@ -703,7 +728,10 @@ herdr restores saved agent panes itself, so a revival on top would resume the
 same conversation twice.
 ² Into a fresh workspace; cmux has no joinable named-session model.
 ³ As a detached process. Its output goes to `~/.unsnooze/headless/<session>.log`,
-since there is no scrollback to read it out of later.
+since there is no scrollback to read it out of later; the prompt rides in argv
+(`claude --resume <id> "…"`, `codex exec resume <id> "…"`), and a revival that
+exits non-zero is retried, with its last output as the `last error` in
+`unsnooze status`.
 ⁴ Nothing to wrap into — your own terminal is the session.
 
 Pick one explicitly with `unsnooze config set multiplexer tmux|zellij|herdr|cmux|headless`.
@@ -742,12 +770,18 @@ Native Windows works: PowerShell wrappers, a cmd-safe StopFailure hook, and a
 logon-triggered Scheduled Task for the daemon. Install as usual and run
 `unsnooze doctor` to confirm.
 
-Two honest caveats. The daemon is started at logon but not restarted if it
+Three honest caveats. The daemon is started at logon but not restarted if it
 dies — Task Scheduler is not a supervisor the way launchd and systemd are — so
 after upgrading unsnooze, log out and back in (or run `unsnooze daemon`
-yourself). And stored-password fleet hosts still need Git-for-Windows or WSL
-`ssh`; native `ssh.exe` requires an `.exe` askpass helper unsnooze does not yet
-ship.
+yourself). The daemon also keeps the `PATH` it was born with: an agent whose
+install directory changes on update (the Codex Desktop/Store runtime lives
+under `%LOCALAPPDATA%\OpenAI\Codex\bin\<hash>`) can vanish from the daemon's
+view while your shell still finds it — unsnooze looks that directory up at
+launch time, `unsnooze doctor` prints what each agent resolves to, and
+`UNSNOOZE_CODEX_BIN` (or `UNSNOOZE_CLAUDE_BIN`, …) pins a path; point it at an
+`.exe`, since Node cannot launch a `.cmd` shim directly. And stored-password
+fleet hosts still need Git-for-Windows or WSL `ssh`; native `ssh.exe` requires
+an `.exe` askpass helper unsnooze does not yet ship.
 
 WSL remains the richer option, because that is where the Unix multiplexers live
 — and where the agent CLIs often already are:

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.1",
   "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/agents/codex.js

@@ -11,8 +11,9 @@
 // the overload path, never the ledger.
 
 import { openSync, readSync, closeSync, readdirSync, statSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 import { CODEX_DIR } from '../config.js';
+import { findOnPath } from '../which.js';
 
 // Since the 2026 unified ChatGPT desktop app absorbed the Codex app, the codex
 // binary ships INSIDE the app bundle and many machines have no standalone
@@ -21,21 +22,59 @@ import { CODEX_DIR } from '../config.js';
 // codex-cli 0.144 from ChatGPT.app).
 export const CHATGPT_CODEX_BIN = '/Applications/ChatGPT.app/Contents/Resources/codex';
 
-function codexOnPath(env = process.env) {
-  return (env.PATH || '').split(':').some(dir => {
-    try { return dir && existsSync(join(dir, 'codex')); } catch { return false; }
-  });
+// Windows keeps the Desktop/Store install's CLI under a versioned runtime
+// directory — %LOCALAPPDATA%\OpenAI\Codex\bin\<hash>\codex.exe — whose name
+// changes on every update. The interactive shell finds it through a PATH the
+// app rewrote; a daemon started at logon keeps the PATH it was born with,
+// which after an update names a directory that no longer exists (#25). So
+// look the directory up at launch time and take the newest runtime, the way
+// CHATGPT_CODEX_BIN covers the macOS bundle. Layout as reported by the
+// issue's Microsoft Store install; a machine without it just gets null.
+export function windowsBundledCodex({ env = process.env, readdir = readdirSync, stat = statSync } = {}) {
+  if (!env.LOCALAPPDATA) return null;
+  const base = join(env.LOCALAPPDATA, 'OpenAI', 'Codex', 'bin');
+  let entries;
+  try { entries = readdir(base, { withFileTypes: true }); } catch { return null; }
+  let best = null;
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const exe = join(base, e.name, 'codex.exe');
+    let mtime;
+    try { mtime = stat(exe).mtimeMs; } catch { continue; }
+    if (!best || mtime > best.mtime) best = { exe, mtime };
+  }
+  return best ? best.exe : null;
 }
 
-export function resolveCodexBin({ env = process.env, onPath = () => codexOnPath(env), exists = existsSync } = {}) {
+// What to spawn for codex. Order, on Windows: an explicit UNSNOOZE_CODEX_BIN,
+// a codex.exe on PATH (spawn resolves the bare name itself), the newest
+// Desktop/Store runtime, then a .cmd/.bat shim on PATH by full path — Node
+// refuses to spawn those without a shell, and a full path makes the launcher's
+// error say which file it was. Elsewhere: PATH, then the macOS app bundle.
+export function resolveCodexBin({
+  env = process.env,
+  platform = process.platform,
+  exists = existsSync,
+  onPath = null,
+  bundled = () => windowsBundledCodex({ env }),
+} = {}) {
   if (env.UNSNOOZE_CODEX_BIN) return env.UNSNOOZE_CODEX_BIN;
-  if (onPath()) return 'codex';
+  if (platform === 'win32') {
+    if (findOnPath(['codex.exe'], { env, exists, platform })) return 'codex';
+    const runtime = bundled();
+    if (runtime) return runtime;
+    const shim = findOnPath(['codex.cmd', 'codex.bat'], { env, exists, platform });
+    if (shim) return shim.path;
+    return 'codex';
+  }
+  const found = onPath ? onPath() : !!findOnPath(['codex'], { env, exists, platform });
+  if (found) return 'codex';
   if (exists(CHATGPT_CODEX_BIN)) return CHATGPT_CODEX_BIN;
   return 'codex';   // neither — the launcher degrades gracefully on spawn error
 }
 
 const LIMIT_ANCHORS = [
-  /You've hit your usage limit/i,
+  /You['’]ve hit your usage limit/i,   // the desktop app also emits a curly apostrophe
   /Your workspace is out of credits/i,
   /hit your spend cap/i,
 ];
@@ -62,11 +101,28 @@ export const patterns = {
   transientPatterns: [/stream error/i, /exceeded retry limit/i],
 };
 
-// Sessions live in ~/.codex/sessions/YYYY/MM/DD/rollout-{ts}-{UUID}.jsonl;
+// Sessions live in ~/.codex/sessions/YYYY/MM/DD/rollout-{ts}-{THREAD}.jsonl;
 // the first JSONL line carries the session cwd. Conservative: no cwd match →
 // null (the resumer then uses `codex resume --last`, which codex itself scopes
 // to the launch cwd).
-export const ROLLOUT_RE = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+//
+// A reverted thread (the desktop app's edit/regenerate, `/undo`) continues in
+// rollout-{ts}-{THREAD}_{ROLLOUT}.jsonl — codex-rs/rollout/src/rollout_file_name.rs:
+// "filenames for reverted threads append an underscore and a distinct rollout
+// ID after the stable thread ID". Group 1 is always the thread id, which is
+// the id `codex resume` takes; the rollout id after the underscore is not.
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+export const ROLLOUT_RE = new RegExp(`^rollout-.*-(${UUID})(?:_${UUID})?\\.jsonl$`, 'i');
+
+// The thread uuid a rollout path names, or null for anything else. Cheaper than
+// rolloutMeta() (no read) and the same id in every rollout seen so far. A
+// reverted thread's `…_<rollout id>` file names the same thread, so usage
+// readings compare across the two files of one conversation.
+export function rolloutId(path) {
+  if (typeof path !== 'string') return null;
+  const m = basename(path).match(ROLLOUT_RE);
+  return m ? m[1].toLowerCase() : null;
+}
 
 function fileHead(path, bytes = 4096) {
   let fd;
@@ -115,12 +171,40 @@ export default {
   experimental: false,
   patterns,
   menu: null,                      // no interactive limit menu
+  // What to do about a workspace wall (credits depleted, a spend cap): no
+  // window reset clears it, so the resumer's ceiling notification names this.
+  // Not `unsnooze resume-now`: the hold leaves the record failed, and
+  // resume-now only wakes stopped ones — it would answer "no matching stopped
+  // sessions" to the one command the notification told the user to run.
+  modelRemedy: 'add credits or raise the spend cap in the ChatGPT workspace (or ask its owner to), then continue the session in Codex',
   // Resume takes the prompt in argv — `codex resume <id> "msg"` starts the turn
   // immediately, nothing to type into the TUI.
-  resumeArgs(sessionId, message) {
+  //
+  // canType: false (headless — no pane): the TUI cannot run there at all. It
+  // refuses a non-TTY stdin before it looks at the session ("Error: stdin is
+  // not a terminal", exit 1 — reproduced against codex-cli 0.150 with the
+  // headless backend's exact stdio), so `codex exec resume <id> "msg"` carries
+  // the same conversation forward non-interactively instead (#25). With
+  // --last, codex reads a lone positional as the prompt, not a session id.
+  //
+  // `exec` also refuses any directory that is not a git repository unless
+  // told --skip-git-repo-check ("Not inside a trusted directory…", exit 1),
+  // a guard the TUI never had: without the flag, a session that ran in a
+  // plain folder could never be revived headless. It is the user's own
+  // session, resumed where it already ran, so the flag goes on.
+  //
+  // extraArgsAt: resumeExtraArgs go right after `exec`, not at the end. The
+  // `resume` subcommand rejects -s/--sandbox, -p/--profile and --add-dir
+  // ("unexpected argument", exit 2) — exactly what a user sets to match
+  // their normal launch — while `exec` takes them. (TUI-only flags such as
+  // -a or --search have no exec equivalent and still fail, visibly.)
+  resumeArgs(sessionId, message, { canType = true } = {}) {
+    const tail = sessionId ? [sessionId, message] : ['--last', message];
+    if (canType) return { args: ['resume', ...tail], messageViaPane: false };
     return {
-      args: sessionId ? ['resume', sessionId, message] : ['resume', '--last', message],
+      args: ['exec', '--skip-git-repo-check', 'resume', ...tail],
       messageViaPane: false,
+      extraArgsAt: 1,
     };
   },
   // v1: every agent launches the bare TUI and gets the prompt typed once idle.

package/src/cli.js

@@ -90,6 +90,10 @@ export async function cmdStatus(args = []) {
       sessions: Object.values(state.sessions).map(s => ({
         key: s.key, sessionId: s.sessionId ?? null, agent: s.agent ?? 'claude',
         cwd: s.cwd ?? null, status: s.status, limitType: s.limitType ?? null,
+        // Why the provider refused, when it said (Codex's rate_limit_reached_type,
+        // e.g. workspace_member_credits_depleted) — the reason a stop is probed
+        // and held rather than scheduled.
+        limitReason: s.limitReason ?? null,
         resetAt: s.resetAt ?? null, resetSource: s.resetSource ?? null,
         mux: s.mux ?? null, pane: s.pane ?? null, muxSession: s.muxSession ?? null,
         attempts: s.attempts ?? 0, lastError: s.lastError ?? null,

package/src/config.js

@@ -229,6 +229,10 @@ export const PROBE_INTERVAL_MS = envInt('UNSNOOZE_PROBE_INTERVAL_MS', 15 * 60_00
 export const PROBE_MAX_MS = envInt('UNSNOOZE_PROBE_MAX_MS', 60 * 60_000);
 export const STAGGER_MS = envInt('UNSNOOZE_STAGGER_MS', 8_000);
 export const VERIFY_DELAY_MS = envInt('UNSNOOZE_VERIFY_DELAY_MS', 20_000);
+// A headless revival still running at verify time is watched this long before
+// it counts as resumed: the failures worth catching (an auth refresh that gives
+// up, a retry loop on a bad network) take longer than VERIFY_DELAY_MS to exit.
+export const HEADLESS_SETTLE_MS = envInt('UNSNOOZE_HEADLESS_SETTLE_MS', 2 * 60_000);
 export const BUSY_DEFER_MS = envInt('UNSNOOZE_BUSY_DEFER_MS', 60_000);
 export const READY_TIMEOUT_MS = envInt('UNSNOOZE_READY_TIMEOUT_MS', 60_000);
 export const EVENT_MARKER_TTL_MS = envInt('UNSNOOZE_EVENT_MARKER_TTL_MS', 120_000);
@@ -254,6 +258,8 @@ export const MUX_NAMES = ['tmux', 'zellij', 'herdr', 'cmux', 'headless'];
 // Where a headless revive tees the agent's output. There is no pane to scroll
 // back through, so the log is the only record of what an unattended run did.
 export const HEADLESS_LOG_DIR = join(STATE_DIR, 'headless');
+// The daemon's Windows Task Scheduler entry (install.js creates it; doctor names it).
+export const WINDOWS_TASK_NAME = 'unsnooze';
 
 // Pane scanning
 export const PANE_SCAN_LINES = envInt('UNSNOOZE_PANE_SCAN_LINES', 12);

package/src/doctor.js

@@ -16,6 +16,11 @@ 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';
+import { listAgents } from './agents/index.js';
+import { getConfig } from './settings.js';
+import { resolveBin } from './which.js';
+import { WINDOWS_TASK_NAME, CLAUDE_DIR, CODEX_DIR } from './config.js';
 
 const log = makeLogger('doctor');
 
@@ -116,13 +121,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
@@ -185,6 +191,11 @@ export async function runDoctor({
   profileContent = undefined,
   autostartDir = null,
   stateDir = STATE_DIR,
+  env = process.env,
+  exists = existsSync,
+  agents = listAgents(),
+  enabled = id => !!getConfig(`agents.${id}`),
+  inUse = agentInUse,
 } = {}) {
   const findings = [];
 
@@ -286,6 +297,14 @@ export async function runDoctor({
     }
   } catch { /* best-effort: a PATH check must never break doctor */ }
 
+  // What each enabled agent would actually be launched as — resolved the way
+  // the launcher resolves it, from this environment. #25 was a daemon whose
+  // logon-time PATH no longer named the Codex runtime directory; every revival
+  // died with ENOENT and nothing said so until the headless log was read.
+  // Doctor cannot see the daemon's environment, only its own, so on Windows
+  // it also says how the two can differ.
+  for (const f of agentBinFindings({ platform, env, exists, agents, enabled, inUse })) findings.push(f);
+
   findings.push({
     id: 'daemon', kind: 'info',
     title: daemonRunning() ? 'resumer/daemon: running' : 'resumer/daemon: not running (starts on the next limit stop)',
@@ -308,6 +327,66 @@ export async function runDoctor({
   return { findings, healthy };
 }
 
+// claude and codex are enabled by default, so "enabled" does not mean "used
+// here": a machine that has only ever run one of them has nothing of the
+// other's to revive, and must not be reported unhealthy for lacking its
+// binary. Their own data directories say whether they have run here. The
+// other agents are opt-in; the user switching one on is evidence enough.
+const AGENT_HOMES = { claude: CLAUDE_DIR, codex: CODEX_DIR };
+export function agentInUse(id, { exists = existsSync } = {}) {
+  const home = AGENT_HOMES[id];
+  return home ? exists(home) : true;
+}
+
+export function agentBinFindings({
+  platform = process.platform, env = process.env, exists = existsSync,
+  agents = listAgents(), enabled = id => !!getConfig(`agents.${id}`),
+  inUse = agentInUse,
+} = {}) {
+  const findings = [];
+  const envVar = id => `UNSNOOZE_${String(id).toUpperCase()}_BIN`;
+  // Two commands, not `a && b`: && only exists from PowerShell 7, and the
+  // Windows PowerShell 5.1 that ships with the OS is a supported shell.
+  const windowsNote = platform === 'win32'
+    ? `\n  the daemon's Scheduled Task keeps the PATH it had at logon; after an agent update, run\n`
+      + `  schtasks /end /tn ${WINDOWS_TASK_NAME}\n`
+      + `  schtasks /run /tn ${WINDOWS_TASK_NAME}   (or sign out and in)`
+    : '';
+  for (const agent of agents) {
+    if (!agent?.id || !enabled(agent.id)) continue;
+    const bin = agent.bin;
+    let resolved = null;
+    try { resolved = resolveBin(bin, { env, exists, platform }); } catch { resolved = null; }
+    if (resolved?.launchable) {
+      findings.push({
+        id: `agent-bin-${agent.id}`, kind: 'info',
+        title: `${agent.id}: ${resolved.path}`,
+        detail: '',
+      });
+    } else if (resolved) {
+      findings.push({
+        id: `agent-bin-${agent.id}`, kind: 'health',
+        title: `${agent.id} resolves to ${resolved.path}, a .cmd/.bat shim that cannot be launched directly`,
+        detail: `  set ${envVar(agent.id)} to the agent's .exe`,
+      });
+    } else if (!inUse(agent.id)) {
+      findings.push({
+        id: `agent-bin-${agent.id}`, kind: 'info',
+        title: `${agent.id}: not installed (no ${agent.id} sessions here to revive)`,
+        detail: '',
+      });
+    } else {
+      findings.push({
+        id: `agent-bin-${agent.id}`, kind: 'health',
+        title: `${agent.id} is not launchable from this environment (${bin} not found)`,
+        detail: `  every revival of a ${agent.id} session will fail with ENOENT\n`
+          + `  install it, put it on PATH, or set ${envVar(agent.id)}${windowsNote}`,
+      });
+    }
+  }
+  return findings;
+}
+
 // --- fixes ------------------------------------------------------------------------
 
 function defaultKill(pid) {