unsnooze 1.19.0 → 1.19.1

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # 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

package/README.md

@@ -244,6 +244,15 @@ the session files those surfaces already write:
   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`
@@ -719,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`.
@@ -758,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.19.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

@@ -17,6 +17,10 @@ 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');
 
@@ -187,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 = [];
 
@@ -288,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)',
@@ -310,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) {

package/src/install.js

@@ -15,7 +15,7 @@ import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSy
 import { execFileSync } from 'node:child_process';
 import { homedir, userInfo } from 'node:os';
 import { join, dirname, delimiter } from 'node:path';
-import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
+import { CLAUDE_SETTINGS, STATE_DIR, WINDOWS_TASK_NAME } from './config.js';
 import { getConfig, configFileExists } from './settings.js';
 import { xmlEscape } from './notify.js';
 import { installGrokHooks, uninstallGrokHooks } from './agents/grok.js';
@@ -253,7 +253,7 @@ export function installFishBlock(content, agents = ['claude'], bin = UNSNOOZE_BI
 export const DAEMON_LABEL = 'com.unsnooze.daemon';
 // Task Scheduler has no reverse-DNS convention and shows this name to the user
 // in taskschd.msc, so it is a plain word rather than the launchd label.
-export const WINDOWS_TASK_NAME = 'unsnooze';
+export { WINDOWS_TASK_NAME };
 
 // Is this process running under the supervisor we install, rather than from
 // somebody's shell? It decides whether exiting is safe: a supervised daemon

package/src/launcher.js

@@ -38,7 +38,14 @@ export function resolvePaneOwner(muxName, env = process.env) {
 
 function runUnwatched(agent, args, reason) {
   if (reason) process.stderr.write(`unsnooze: ${reason}\n`);
+  return runPassthrough(agent, args);
+}
+
+// spawnSync reports a binary it could not start as r.error with no status;
+// `r.status ?? 1` alone turned `spawn codex ENOENT` into a silent exit 1.
+function runPassthrough(agent, args) {
   const r = spawnSync(agent.bin, args, { stdio: 'inherit', env: { ...process.env, UNSNOOZE_ACTIVE: '1' } });
+  if (r.error) return launchFailed(agent, r.error);
   return r.status ?? 1;
 }
 
@@ -54,8 +61,7 @@ export function runLauncher(args, agentId = 'claude', { processBirthFn = process
   // 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;
+    return runPassthrough(agent, args);
   }
 
   // Flags the user wants on every session they start (claude's --autocompact
@@ -166,10 +172,17 @@ export function runLauncher(args, agentId = 'claude', { processBirthFn = process
     UNSNOOZE_PANE: pane || '', UNSNOOZE_PANE_OWNER: paneOwner || '',
     UNSNOOZE_LEASE_ID: leaseId,
   };
-  const child = spawn(agent.bin, args, {
-    stdio: 'inherit',
-    env: childEnv,
-  });
+  // The bin can be a path we resolved ourselves (a Windows .cmd shim, say).
+  // Node ≥ 20.12 refuses to spawn .bat/.cmd without a shell, and depending on
+  // the version that is a synchronous throw rather than an 'error' event —
+  // either way it has to come out as the same "failed to launch" line, with
+  // the reason, never as a crash with no exit code for the resumer to read.
+  let child;
+  try {
+    child = spawn(agent.bin, args, { stdio: 'inherit', env: childEnv });
+  } catch (err) {
+    return launchFailed(agent, err);
+  }
   const lease = pane && child.pid ? {
     leaseId, mux: mux.name, paneOwner, pane, agent: agent.id,
     pid: child.pid, pidBirth: processBirthFn(child.pid),
@@ -186,8 +199,19 @@ export function runLauncher(args, agentId = 'claude', { processBirthFn = process
     child.on('exit', code => { cleanup(); resolve(code ?? 1); });
     child.on('error', err => {
       cleanup();
-      process.stderr.write(`unsnooze: failed to launch ${agent.bin}: ${err.message}\n`);
-      resolve(127);
+      resolve(launchFailed(agent, err));
     });
   });
 }
+
+// One place for the message, because the resumer reads it back out of the
+// headless log when a revival dies (#25). 127 like a shell's "command not
+// found"; the hint names the one misconfiguration that produces EINVAL here.
+function launchFailed(agent, err) {
+  process.stderr.write(`unsnooze: failed to launch ${agent.bin}: ${err.message}\n`);
+  if (/\.(cmd|bat)$/i.test(String(agent.bin))) {
+    process.stderr.write(`unsnooze: ${agent.bin} is a .cmd/.bat shim, which cannot be launched directly — `
+      + `point UNSNOOZE_${agent.id.toUpperCase()}_BIN at the .exe\n`);
+  }
+  return 127;
+}