unsnooze 1.10.0 → 1.12.2

package/CHANGELOG.md

@@ -2,6 +2,149 @@
 
 ## Unreleased
 
+## 1.12.2 — 2026-07-16
+
+- **Daemon autostart self-heal**: updating via npm never touches the
+  launchd/systemd unit file, so pre-1.12 users would keep the PATH-less unit
+  (daemon can't find tmux → every revival dies) until they manually re-ran
+  `unsnooze install --daemon`. The daemon now detects a PATH-less unit on
+  startup, regenerates it, and reloads itself — every affected user is fixed
+  automatically on their first daemon restart after updating (at the latest,
+  the next reboot). Manual `unsnooze install --daemon` still works and is no
+  longer required.
+
+## 1.12.1 — 2026-07-16
+
+- CI-only: pin the platform in a doctor test whose `launchctl` assertion
+  failed on Linux runners. No runtime changes — this is 1.12.0 plus a green
+  release pipeline (1.12.0 was tagged but never published).
+
+## 1.12.0 — 2026-07-16
+
+- **Daemon PATH fix** (fix: every launchd-daemon revival on Homebrew Macs died
+  silently with `spawn tmux ENOENT` — launchd gives daemons a bare
+  `/usr/bin:/bin:/usr/sbin:/sbin` and tmux lives in `/opt/homebrew/bin`): the
+  launchd plist and systemd unit now bake the install-time `PATH`. Re-run
+  `unsnooze install --daemon` once after updating to regenerate the unit.
+  Revival `new-window` failures are now logged (they were silent), and
+  `failed` records survive the sweeper so `unsnooze status` can show *why* a
+  session gave up (age-based prune still expires them).
+- **`unsnooze preview [id]`** — a true dry-run: per session, exactly what the
+  resumer WOULD do right now (type into which pane, drive the menu, reopen in
+  which session, probe, defer) and why — every gate (paused, not due, held by
+  workspace/context guard, backoff, attempt cap) spelled out, including the
+  final wake message with any guard suffix. Sends nothing, mutates nothing.
+  Preview shares its decision code (`planFor`/`assessPane`/guard evaluators)
+  with the real dispatcher, so it cannot drift. Exit codes: `0` nothing would
+  wake now, `2` at least one actionable wake, `1` error.
+- **ntfy push notifications** (`ntfyTopic` / `ntfyServer` / `ntfyToken` /
+  `ntfyPrivacy`) — off until a topic is set; fires *alongside* the local
+  channel on limit-hit / resumed / gave-up (gave-up pushes at high priority).
+  JSON-to-root publishing (emoji-safe titles), Bearer-token support for authed
+  or self-hosted servers, bodies capped, fire-and-forget with a 5s timeout.
+  `ntfyPrivacy=terse` keeps directory paths out of pushed bodies — ntfy.sh
+  topics are a public namespace, so the docs push unguessable topic names.
+- **Trust & security docs**: a "Trust & security" section at the top of the
+  README (what unsnooze types and never types, grounded in the actual
+  mechanisms) and a full `SECURITY.md` (threat model, honest residual risks,
+  private vulnerability reporting, supported versions). Enable GitHub Private
+  Vulnerability Reporting in the repo settings to activate the report button.
+- **Release provenance**: `.github/workflows/release.yml` publishes to npm on
+  `v*` tags via trusted publishing (OIDC, token-less) with
+  `--provenance` — after a one-time trusted-publisher setup on npmjs.com
+  (repo `saaranshM/unsnooze`, workflow `release.yml`).
+- **Reproducible demo**: `demo/demo.tape` (VHS) renders `assets/demo.gif` —
+  staged fixture ledger + stub agent, but the `unsnooze status` beat is real.
+- Note: the pre-release name `claude-session-guard` was never published to
+  npm, so there is nothing to deprecate on the registry; `unsnooze doctor
+  --fix` remains the migration path for local installs.
+
+## 1.11.0 — 2026-07-16
+
+- **`unsnooze doctor [--fix]`** — install health check + migration sweep for
+  the pre-release claude-session-guard (csg) install. Detects zombie csg
+  monitors/resumers, old launchd/systemd units, the orphaned
+  `~/.claude-session-guard` state dir, and the stale global package (even when
+  its `csg` bin symlink dangles). `--fix` stops the processes, unloads and
+  removes the units, and archives the state dir (never deletes data, never
+  runs npm — the `npm rm -g claude-session-guard` step stays yours).
+  `unsnooze install` now runs the detection and points at doctor when
+  leftovers exist.
+- **Pane identity & ownership** (fix: tmux pane ids are server-global and
+  recycled — a stale monitor or reap could type into or close somebody
+  else's pane): managed panes are stamped with a `@unsnooze_owner` pane
+  option at launch and revival; every message-injection, menu-drive, reap,
+  and auto-reap decision now answers two independent questions first —
+  *is this pane ours* (stamp/lease; a mismatched stamp vetoes even a
+  matching foreground command) and *is our agent still running in it*
+  (lease pid+birth or foreground command; the stamp alone never counts,
+  since it outlives the agent and the pane may now be the user's shell).
+  Monitors exit once their lease disappears instead of scraping whatever the
+  pane becomes. Legacy records without leases are never force-closed.
+- **Launch failures degrade instead of dying** (fix: a tmux-level
+  session-start failure — `duplicate session`, `open terminal failed`, dead
+  socket, nesting refusal, socket permission errors — used to exit with
+  tmux's status and no agent): launchWrapped now reads tmux's stderr,
+  distinguishes "session never started" from "session ran and ended", and
+  falls back to the unwatched agent CLI with a message.
+- **Zellij detection fix**: `capturePane` now dumps scrollback
+  (`dump-screen --full`) — a limit banner that scrolled between polls was
+  previously invisible on Zellij. Pre-0.35 zellij rejects the flag; capture
+  learns that once and degrades to the viewport-only form instead of
+  failing every poll.
+- **Reset-time correctness**: weekly "resets Tuesday 9am" wakes land on the
+  exact wall-clock time across DST boundaries (day-stepping used to drift
+  ±1h); a mangled banner clock ("resets 45:99") is rejected instead of
+  throwing; "wait <duration>" only parses when a duration actually follows
+  (no more summing stray durations out of prose).
+- **State safety**: sweepers use compare-and-set so `markStaleAbandoned` can
+  no longer clobber a record that resumed mid-sweep; the state lock records
+  its holder pid and is only ever stolen from a dead process; user-invoked
+  `reap` skips `resumed` panes that were active within `reapIdleAfter`
+  (closing a live working agent contradicted its own contract).
+- **Install backups**: the first-ever run snapshots your pristine
+  settings/rc as `.unsnooze-orig` (kept forever); `.unsnooze-bak` keeps
+  rolling per run.
+
+## 1.10.1 — 2026-07-16
+
+- **Upgrade-window fail-safe** (fix: `npm install -g` briefly leaves `bin/`
+  present with `src/` missing; the router then died with `MODULE_NOT_FOUND`
+  *inside* the freshly-wrapped tmux session — a visible open/close flash with
+  terminal-probe garbage — and the launchd daemon crash-looped thousands of
+  times into `daemon.log`): agent-launch paths (`_run`, bare `claude` args)
+  now degrade to the plain agent CLI when the package can't load; background
+  paths (hook, monitor, resumer, daemon, update-check) exit 0 quietly. Only
+  module *load* failures are caught — runtime errors still surface, and an
+  agent that already ran is never re-run.
+- **Daemon crash-loop guards**: launchd plist gains `ThrottleInterval 30`;
+  the systemd unit moves to `Restart=always` + `RestartSec=30` (a clean
+  exit-0 must also respawn — `on-failure` would leave the daemon dead after
+  an intentional exit) with the start rate-limit disabled so a long broken
+  install can never trip the unit into a permanent `failed` state. A
+  version-skew watch makes a long-lived daemon exit cleanly (and get
+  restarted on fresh code) when `npm -g` swaps the package underneath it —
+  no more zombie daemons running deleted code.
+- **Log rotation**: `unsnooze.log` and `daemon.log` are capped at 5 MB with
+  one rotated generation (`.1`) — a crash-loop can no longer grow a log
+  without bound. `daemon.log` is rotated copy-truncate style because launchd
+  holds its fd open for the daemon's whole lifetime.
+- **Resume-retry backoff** (fix: five resume attempts burned in ~2 minutes
+  when a revival kept failing): failed attempts now back off exponentially
+  (1m, 2m, 4m… capped at 30m). Manual `resume-now` records are exempt — an
+  explicit immediate wake is never silently deferred. After `unsnooze` gives
+  up, a session re-arms only on a fresh limit detection.
+- **Singleton-lock hygiene**: the resumer lock is acquired atomically
+  (`wx`), a lock held by a recycled pid that is not actually an unsnooze
+  process is taken over instead of honored forever, and the daemon's
+  "another resumer holds the lock" log line is throttled to ~once per 15
+  minutes instead of every 30 s tick.
+- **Update notice on the launch path**: wrapper-only users (who never run
+  `unsnooze status`) now get the one-line "new version available" notice on
+  stderr right after their agent session ends — outer terminal only, TTY
+  only, never in `-p/--print` runs, at most once per day. The launch path
+  also refreshes the daily version-check cache.
+
 ## 1.10.0 — 2026-07-14
 
 - **Session-name ownership** (fix: interactive `claude` dying with

package/README.md

@@ -37,6 +37,43 @@ existing tool solves only a slice of it:
 | Survives laptop sleep & weekly-scale waits | ✅ epoch polling | partial | partial | n/a |
 | Settings + first-run wizard | ✅ | ❌ | ❌ | ❌ |
 
+## Trust & security
+
+unsnooze is a **scheduler that presses your keys — not an auto-approver.** It waits
+for your usage limit to reset, then resumes the *same* session. It never changes how
+your agent handles permissions.
+
+- **Types only after proving the pane is yours.** Every keystroke requires both
+  *identity* (a tmux `@unsnooze_owner` stamp, else a lease = process id + birth
+  time — a mismatch vetoes, because pane ids get recycled) and *liveness* (your
+  agent is still running there). Pane closes require proven identity (idle
+  threshold too for `resumed` panes). Ownership unprovable → it reopens a fresh
+  session instead of typing.
+- **See before you trust: `unsnooze preview`.** A true dry-run — it prints exactly
+  what would be typed, where, and why (or what's holding it back), and sends
+  nothing. Preview shares its decision code with the real dispatcher, so it cannot
+  drift from what dispatch actually does.
+- **Answers Claude's limit menu safely — never a blind Enter.** It locates the
+  cursor and the **"Stop and wait for limit to reset"** option and computes the
+  exact moves. Unreadable menu → it presses nothing. It will never select
+  "Upgrade your plan." Toggle with `menuAutoAnswer`.
+- **No `--dangerously-skip-permissions`, no auto-trust, no auto-approve.** unsnooze
+  never passes bypass flags, never presses "Yes, I trust this folder," and never
+  touches MCP config. Whatever your agent does *after* resuming is governed by
+  **its own** permission model — the same as if you'd typed the message yourself.
+- **Nearly zero network, zero telemetry.** One version check to
+  `registry.npmjs.org` (nothing identifying; `updateCheck=false` turns it off), and
+  push notifications only if *you* configure an ntfy topic. State stays local under
+  `~/.unsnooze`.
+- **Reversible install.** The settings hook and rc-file wrappers are backed up
+  first (`*.unsnooze-orig` pristine + `*.unsnooze-bak` rolling); `unsnooze
+  uninstall` removes every change. Releases are published with npm provenance.
+
+**Honest limits:** unsnooze *does* inject keystrokes into your live terminal on
+your behalf, and it does not sandbox your agent or defend against prompt
+injection / malicious repos — that's your agent's job. Full threat model, residual
+risks, and vulnerability reporting: **[SECURITY.md](SECURITY.md)**.
+
 ## Supported CLIs
 
 - **Claude Code** — dual-channel detection: the `StopFailure` hook (authoritative,
@@ -171,8 +208,11 @@ unsnooze status                 # tracked sessions + reset countdowns
 unsnooze resume-now [id|--all]  # don't wait for the reset time
 unsnooze cancel [id|--all]      # stop tracking a session
 unsnooze message <id> "text"    # per-session wake message (--clear to reset)
+unsnooze preview [id]           # dry-run: what WOULD happen right now, and why —
+                                # nothing is typed or opened
 unsnooze sessions               # list unsnooze-owned mux sessions + panes
 unsnooze reap [--dry-run|--yes] # close finished panes / empty sessions (default dry-run)
+unsnooze doctor [--fix]         # install health check + retire old csg leftovers
 unsnooze config list            # settings (see below)
 unsnooze config set <k> <v>     # e.g. autoResume off
 unsnooze logs [-f]              # what unsnooze has been doing
@@ -207,6 +247,10 @@ unsnooze help                   # full command list (also -h / --help)
 | `reapResumed` | `false` | Opt-in: auto-close `resumed` panes idle longer than `reapIdleAfter`. Off by default — use `unsnooze reap --yes` for explicit cleanup. |
 | `reapIdleAfter` | `604800000` (7d) | Idle age (ms) before an opt-in auto-reap closes a `resumed` pane. |
 | `updateCheck` | `true` | Daily new-version check (a plain GET to the npm registry, nothing identifying is sent). Notices after commands + one desktop toast per version. |
+| `ntfyTopic` | `""` | [ntfy](https://ntfy.sh) push notifications — **off until set**. Fires *alongside* the local channel on limit-hit / resumed / gave-up. ⚠️ ntfy.sh topics are public — the name is the password. Use an unguessable one, e.g. `unsnooze-$(openssl rand -hex 8)`, a token, or a self-hosted server. |
+| `ntfyServer` | `https://ntfy.sh` | ntfy server base URL (self-hosted servers welcome). |
+| `ntfyToken` | `""` | Optional `tk_…` access token (`Authorization: Bearer`) for reserved topics / authed servers. |
+| `ntfyPrivacy` | `full` | `terse` keeps directory paths out of pushed bodies (titles only) — recommended on public ntfy.sh topics. |
 
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
 all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
@@ -386,8 +430,13 @@ npm test                     # unit tests (node:test)
 ./scripts/e2e-simulate.sh    # full detect → wait → re-open cycle in a
                              # scratch tmux session (no real limits needed)
 bash -n scripts/e2e-zellij.sh # syntax-check the reserved-session Zellij smoke test
+vhs demo/demo.tape           # regenerate assets/demo.gif (brew install vhs)
 ```
 
+Releases are tagged (`git tag v<version> && git push origin v<version>`) and
+published to npm by CI with [provenance](https://docs.npmjs.com/generating-provenance-statements)
+via trusted publishing — see `.github/workflows/release.yml`.
+
 ## License
 
 [MIT](LICENSE)

package/bin/unsnooze.js

@@ -2,11 +2,85 @@
 // unsnooze — subcommand router; anything unrecognized is treated as claude
 // args and passed through the launcher (back-compat with the zsh wrapper).
 
+import { spawnSync } from 'node:child_process';
+
 const [, , cmd, ...rest] = process.argv;
 
+// --- upgrade-window fail-safe -----------------------------------------------
+// During `npm install -g` the package dir is briefly half-written: bin/ can
+// exist while src/ is missing, so the zsh wrapper's file guard passes but the
+// dynamic imports below throw ERR_MODULE_NOT_FOUND. That window once produced
+// an instantly-dying wrapped tmux session for every `claude` (and 12,989
+// launchd daemon crash-loops). Rules: agent-launch paths degrade to the plain
+// CLI; background paths (hook/monitor/resumer/daemon) exit 0 quietly. Only
+// module LOAD failures are caught — a runtime error after the module loaded
+// must not re-run an agent that may already have run.
+
+// Mirrors each adapter's bin resolution without importing src/. Codex loses
+// its PATH walk here — plain `codex` is the correct degraded answer.
+const AGENT_FALLBACK_BINS = {
+  claude: () => process.env.UNSNOOZE_CLAUDE_BIN || 'claude',
+  codex: () => process.env.UNSNOOZE_CODEX_BIN || 'codex',
+  grok: () => process.env.UNSNOOZE_GROK_BIN || 'grok',
+  qwen: () => process.env.UNSNOOZE_QWEN_BIN || 'qwen',
+  kimi: () => process.env.UNSNOOZE_KIMI_BIN || 'kimi',
+  opencode: () => process.env.UNSNOOZE_OPENCODE_BIN || 'opencode',
+  agy: () => process.env.UNSNOOZE_AGY_BIN || 'agy',
+};
+
+async function safeImport(specifier) {
+  try {
+    return await import(specifier);
+  } catch {
+    return null;   // missing/half-written module — caller picks the degraded path
+  }
+}
+
+function runAgentFallback(agentId, args) {
+  const bin = (AGENT_FALLBACK_BINS[agentId] || AGENT_FALLBACK_BINS.claude)();
+  process.stderr.write('unsnooze: install incomplete (upgrade in progress?) — running without limit-watch.\n');
+  const r = spawnSync(bin, args, {
+    stdio: 'inherit',
+    env: { ...process.env, UNSNOOZE_ACTIVE: '1' },
+  });
+  return r.status ?? 1;
+}
+
 // Only human-facing commands may print update notices — never the wrapper
 // passthrough, hooks, or daemons (their output lands in agent panes/logs).
-const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'sessions', 'reap', 'help', '-h', '--help', '--help-unsnooze']);
+const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'sessions', 'reap', 'doctor', 'preview', 'help', '-h', '--help', '--help-unsnooze']);
+
+// Every named subcommand; anything else (or no args) is an agent launch.
+const NAMED_COMMANDS = new Set([
+  ...USER_FACING, 'setup', 'install', 'uninstall', 'update', 'daemon',
+  '_hook-stopfailure', '_monitor', '_run', '_resumer', '_update-check',
+]);
+const isLaunchPath = cmd === '_run' || cmd === undefined || !NAMED_COMMANDS.has(cmd);
+const launchArgs = cmd === '_run' ? rest.slice(1) : (cmd === undefined ? [] : [cmd, ...rest]);
+
+// Post-session update notice (update-notifier pattern): wrapper-only users
+// never run `unsnooze status`, so the moment the agent exits — screen
+// restored, user at their prompt — is where a notice reliably reaches them.
+// Outer process only: inside any multiplexer our stderr is a pane that may be
+// about to close (wrapped sessions die with the agent); the outer wrapper
+// prints on the real terminal after tmux/zellij hands the screen back.
+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
+    const mod = await safeImport('../src/update-check.js');
+    if (!mod) return;
+    const notice = mod.launchExitNotice();
+    if (notice) process.stderr.write(`\n${notice}\n`);
+    // Keep the cache fresh for users who only ever launch agents — without
+    // this, no daemon and no user-facing command means no check ever runs.
+    if (mod.isCacheStale()) {
+      const spawnMod = await safeImport('../src/spawn.js');
+      spawnMod?.spawnDetached(['_update-check']);
+    }
+  } catch { /* notices must never break the launch path */ }
+}
 
 async function maybeUpdateNotices() {
   try {
@@ -64,6 +138,14 @@ async function main() {
       const { cmdReap } = await import('../src/cli.js');
       return cmdReap(rest);
     }
+    case 'doctor': {
+      const { cmdDoctor } = await import('../src/doctor.js');
+      return cmdDoctor(rest);
+    }
+    case 'preview': {
+      const { cmdPreview } = await import('../src/cli.js');
+      return cmdPreview(rest);
+    }
     case 'install': {
       const { cmdInstall } = await import('../src/install.js');
       return cmdInstall(rest);
@@ -73,43 +155,88 @@ async function main() {
       return cmdUninstall(rest);
     }
     case '_hook-stopfailure': {
-      const { runHook } = await import('../src/hook.js');
-      return runHook(rest);
+      const mod = await safeImport('../src/hook.js');
+      if (!mod) return 0;   // never fail (or pollute) an agent turn
+      return mod.runHook(rest);
     }
     case '_monitor': {
       if (!rest[0] || !rest[2]) { console.error('unsnooze _monitor: mux owner pane required'); return 2; }
-      const { runMonitor } = await import('../src/monitor.js');
-      return runMonitor(rest[0], rest[1], rest[2], rest[3], rest[4]);
+      const mod = await safeImport('../src/monitor.js');
+      if (!mod) return 0;   // detached — nothing useful to report
+      return mod.runMonitor(rest[0], rest[1], rest[2], rest[3], rest[4]);
     }
     case '_run': {
       if (!rest[0]) { console.error('unsnooze _run: agent id required'); return 2; }
-      const { runLauncher } = await import('../src/launcher.js');
-      return runLauncher(rest.slice(1), rest[0]);
+      const mod = await safeImport('../src/launcher.js');
+      if (!mod) return runAgentFallback(rest[0], rest.slice(1));
+      return mod.runLauncher(rest.slice(1), rest[0]);
     }
     case '_resumer': {
-      const { runResumer } = await import('../src/resumer.js');
-      return runResumer();
+      const mod = await safeImport('../src/resumer.js');
+      if (!mod) return 0;
+      return mod.runResumer();
     }
     case 'update': {
       const { runSelfUpdate } = await import('../src/update-check.js');
       return runSelfUpdate();
     }
     case '_update-check': {
-      const { runUpdateCheck } = await import('../src/update-check.js');
-      return runUpdateCheck();
+      const mod = await safeImport('../src/update-check.js');
+      if (!mod) return 0;
+      return mod.runUpdateCheck();
     }
     case 'daemon': {
       // Persistent resumer + transcript watcher: detects and revives limit
       // stops from GUI surfaces (VS Code extension, desktop apps) where no
       // shell wrapper or multiplexer pane exists. Run via launchd/systemd or a shell.
-      const { runResumer } = await import('../src/resumer.js');
-      const { createWatcher } = await import('../src/watcher.js');
+      // Exit 0 on load failure: with launchd KeepAlive a crash here means an
+      // instant-respawn crash-loop for the whole upgrade window.
+      const resumerMod = await safeImport('../src/resumer.js');
+      const watcherMod = await safeImport('../src/watcher.js');
+      if (!resumerMod || !watcherMod) return 0;
+      const { runResumer } = resumerMod;
+      const { createWatcher } = watcherMod;
       const controller = new AbortController();
       process.on('SIGTERM', () => controller.abort());
       process.on('SIGINT', () => controller.abort());
+      // Self-heal pre-1.12 autostart units: they lack PATH, so this daemon
+      // cannot find tmux and every revival dies. Healing rewrites the unit
+      // and reloads it — which intentionally kills THIS process; the
+      // supervisor restarts us under the fixed unit. One-time: healed units
+      // pass the check forever after.
+      const installMod = await safeImport('../src/install.js');
+      if (installMod?.healDaemonAutostart) {
+        try {
+          const healed = installMod.healDaemonAutostart();
+          if (healed) {
+            const lm = await safeImport('../src/logger.js');
+            lm?.log('daemon', `autostart unit lacked PATH — regenerated ${healed}, reloading (self-heal)`);
+          }
+        } catch { /* heal is best-effort — a broken unit must not block the daemon */ }
+      }
+      // daemon.log is launchd/systemd-captured stdout+stderr. launchd holds
+      // an open fd on it for our whole lifetime, so rotation must be
+      // copy-truncate: renaming would leave launchd appending to the renamed
+      // inode forever, with no fresh daemon.log until the next respawn.
+      const loggerMod = await safeImport('../src/logger.js');
+      const configMod = await safeImport('../src/config.js');
+      if (loggerMod && configMod) {
+        const { join } = await import('node:path');
+        loggerMod.copyTruncateIfLarge(join(configMod.STATE_DIR, 'daemon.log'));
+      }
+      // Version-skew guard: when npm swaps the package underneath us, exit
+      // cleanly so launchd/systemd restart the daemon on the fresh code.
+      const updMod = await safeImport('../src/update-check.js');
+      if (updMod?.hasVersionSkew) {
+        setInterval(() => {
+          if (updMod.hasVersionSkew()) controller.abort();
+        }, 15 * 60_000).unref();
+      }
       // Daily update check from the daemon: GUI-only users never run CLI
       // commands, so this is what gets them the "new version" desktop toast.
-      const { spawnDetached } = await import('../src/spawn.js');
+      const spawnMod = await safeImport('../src/spawn.js');
+      if (!spawnMod) return 0;
+      const { spawnDetached } = spawnMod;
       spawnDetached(['_update-check']);
       setInterval(() => spawnDetached(['_update-check']), 24 * 3_600_000).unref();
       return runResumer({ persistent: true, watcher: createWatcher(), signal: controller.signal });
@@ -130,6 +257,12 @@ Usage:
   unsnooze sessions                list unsnooze-owned mux sessions + panes
   unsnooze reap [--dry-run|--yes]  close terminal-record panes / empty sessions
                                    (default: dry-run; pass --yes to apply)
+  unsnooze doctor [--fix]          check install health; find (and with --fix
+                                   retire) leftovers of the old
+                                   claude-session-guard install
+  unsnooze preview [id]            dry-run: what WOULD happen right now, and
+                                   why — nothing is typed or opened (exit 2
+                                   when a wake is actionable, else 0)
   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
@@ -148,14 +281,16 @@ Usage:
     default: {
       // Everything else (including no args, --resume, -c, plain prompts) is a
       // claude invocation — back-compat for the plain wrapper.
-      const { runLauncher } = await import('../src/launcher.js');
       const args = cmd === undefined ? [] : [cmd, ...rest];
-      return runLauncher(args, 'claude');
+      const mod = await safeImport('../src/launcher.js');
+      if (!mod) return runAgentFallback('claude', args);
+      return mod.runLauncher(args, 'claude');
     }
   }
 }
 
 main().then(async code => {
   if (USER_FACING.has(cmd)) await maybeUpdateNotices();
+  else if (isLaunchPath) await maybeLaunchExitNotice(launchArgs);
   process.exitCode = typeof code === 'number' ? code : 0;
 }).catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.10.0",
+  "version": "1.12.2",
   "description": "Auto-resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode & Antigravity when the 5-hour/weekly usage limit resets — tmux, Zellij, VS Code & desktop apps. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -10,6 +10,7 @@ import { getConfig, setConfigValue, listConfig, CONFIG_FILE } from './settings.j
 import { spawnResumerIfNeeded } from './spawn.js';
 import { getMultiplexer } from './multiplexer.js';
 import { listOwnedSessions, reap, attachHint } from './reap.js';
+import { planFor } from './resumer.js';
 
 function fmtCountdown(ms) {
   if (ms <= 0) return 'due now';
@@ -204,6 +205,76 @@ export function cmdConfig(rest) {
   }
 }
 
+// `unsnooze preview [id]` — dry-run: what WOULD the resumer do right now,
+// and why? Shares planFor/assessPane/evaluate*Guard with the real dispatch,
+// so this can never drift from what dispatch actually does. Read-only pane
+// captures only — nothing is typed, opened, or modified.
+// Exit codes (terraform -detailed-exitcode style): 0 = nothing would wake
+// right now, 2 = at least one actionable wake, 1 = internal error.
+export async function cmdPreview(rest = [], {
+  resolveMux = rec => getMultiplexer(rec.mux, { owner: rec.paneOwner }),
+  matchesLease = undefined,
+  print = console.log,
+  now = Date.now(),
+} = {}) {
+  try {
+    const idOrAll = rest.find(a => !a.startsWith('-'));
+    const state = readState();
+    let records = Object.values(state.sessions);
+    if (idOrAll) {
+      records = records.filter(s => s.key.startsWith(idOrAll) || (s.sessionId || '').startsWith(idOrAll));
+    }
+    if (records.length === 0) {
+      print(idOrAll ? `unsnooze preview: no session matching "${idOrAll}".` : 'unsnooze preview: no tracked sessions.');
+      return 0;
+    }
+    print('unsnooze preview — what WOULD happen right now (nothing is sent)\n');
+    const VERBS = {
+      inject: p => `would TYPE the wake message into pane ${p.target?.pane}`,
+      'drive-menu': p => `would SELECT "Stop and wait for limit to reset" in pane ${p.target?.pane}`,
+      reopen: p => `would REOPEN in session "${p.target?.session}"${p.messageViaPane ? ' and type the message once the TUI shows an idle prompt' : ' (message travels in argv)'}`,
+      busy: () => 'would DEFER — agent is busy',
+      'menu-held': () => 'limit menu on screen — would WAIT (menuAutoAnswer off)',
+      probe: () => 'would PROBE (reset time unknown) — not a resume',
+      waiting: () => 'waiting for the reset',
+      paused: () => 'paused — would do nothing',
+      held: () => 'held — would do nothing until resume-now',
+      'give-up': () => 'would GIVE UP (attempt cap reached)',
+      verifying: () => 'verifying an in-flight resume',
+      retry: () => 'would RETRY later (pane capture failed)',
+      none: () => 'nothing to do',
+    };
+    let actionable = false;
+    for (const rec of records.sort((x, y) => (x.resetAt || 0) - (y.resetAt || 0))) {
+      let plan;
+      try {
+        plan = await planFor(rec, {
+          mux: resolveMux(rec),
+          ...(matchesLease ? { matchesLease } : {}),
+          now,
+        });
+      } catch (err) {
+        print(`  ${rec.key.slice(0, 12)}: preview failed: ${err.message}`);
+        continue;
+      }
+      const id = rec.sessionId ? rec.sessionId.slice(0, 8) : '(no id)';
+      print(`  [${(rec.status || '?').toUpperCase().padEnd(9)}] ${id}  ${(rec.agent || 'claude').padEnd(6)} ${rec.cwd || ''}`);
+      print(`              ${(VERBS[plan.action] || (() => plan.action))(plan)}`);
+      for (const g of plan.gates) print(`              · ${g}`);
+      if (plan.message && ['inject', 'reopen'].includes(plan.action)) {
+        const m = plan.message.length > 140 ? `${plan.message.slice(0, 140)}…` : plan.message;
+        print(`              message: "${m.replace(/\n+/g, ' ⏎ ')}"`);
+      }
+      if (['inject', 'drive-menu', 'reopen'].includes(plan.action)) actionable = true;
+    }
+    print('\nNothing was typed, opened, or modified. `unsnooze resume-now <id>` wakes a session immediately.');
+    return actionable ? 2 : 0;
+  } catch (err) {
+    console.error(`unsnooze preview: ${err.message}`);
+    return 1;
+  }
+}
+
 // `unsnooze sessions` — list unsnooze-owned mux sessions with panes + records.
 export async function cmdSessions() {
   const owned = await listOwnedSessions();