unsnooze 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 1.19.0 — 2026-09-10
+
+Fish shell support, direct help/version commands, and a fix for Codex sessions
+that stop at a reported 99% usage.
+
+### Fish shell support
+
+`unsnooze setup` and `unsnooze install` now install fish wrappers when fish is
+your login shell or its config file already exists. The default location is
+`~/.config/fish/config.fish`; an absolute `XDG_CONFIG_HOME` is respected.
+`unsnooze doctor` checks this file, and `unsnooze uninstall` removes the wrappers.
+Re-running setup replaces the existing block and preserves your other settings.
+Use `--fishrc <path>` with install or uninstall to choose another config file.
+
+After upgrading, run `unsnooze setup` once to add the fish wrappers, then open
+a new shell. Thanks to [@duncanmcqueen](https://github.com/duncanmcqueen) for
+[PR #21](https://github.com/saaranshM/unsnooze/pull/21).
+
+### Help and version commands run directly
+
+Commands such as `claude --help` and `codex --version` now pass straight to
+the agent. They do not open a multiplexer session, start a pane monitor,
+prepend `launchExtraArgs`, or append an unsnooze update notice. The existing
+print-mode passthrough is unchanged. Thanks to [@chid](https://github.com/chid)
+for [PR #23](https://github.com/saaranshM/unsnooze/pull/23).
+
+### Codex can be detected as stopped at a reported 99%
+
+The GUI watcher now recognizes the sequence reported in
+[issue #20](https://github.com/saaranshM/unsnooze/issues/20): a five-hour Codex
+window reaches 99%, then the next rate-limit snapshot switches to an empty
+`premium` bucket with no credits. It records the stop and schedules the session
+using the previous reset time, plus the normal safety margin.
+
+This fallback requires snapshots from the same rollout no more than a minute
+apart, no available credits, and a future reset time. It works across watcher
+polls and daemon restarts. An already-exhausted weekly window still takes
+precedence if it resets later. A 99% reading alone does not trigger a resume.
+
+The separate report of stale 64% usage was not reproduced; this release fixes
+the missed stop detection. Thanks to [@mio-tsuki](https://github.com/mio-tsuki)
+for the sample. Fixed in [PR #24](https://github.com/saaranshM/unsnooze/pull/24).
+
+### Test fixes
+
+- Permission tests now set their required file mode explicitly, so they pass
+  with different system umasks. Thanks to
+  [@Chang-Jin-Lee](https://github.com/Chang-Jin-Lee) for
+  [PR #22](https://github.com/saaranshM/unsnooze/pull/22).
+- Fish install/uninstall tests use temporary profiles and leave existing user
+  settings, wrappers, and daemon state untouched.
+- Help/version tests use a portable test executable instead of relying on
+  platform-specific `echo` behavior.
+
+## 1.18.0 — 2026-09-02
+
+**Cursor CLI support**, a wrapper change that keeps `cursor .` working, and a
+model-limit notification that finally names a remedy the CLI actually has.
+
+### Cursor CLI (`cursor-agent`)
+
+⚠️ Experimental, off by default — turn it on in `unsnooze setup`, or:
+
+```sh
+unsnooze config set agents.cursor on && unsnooze setup
+```
+
+| | |
+|---|---|
+| **Detection** | pane scrape |
+| **Limit type** | `model` — probed, never a scheduled wake |
+| **Revive** | `cursor-agent --resume=<id>`, else `--continue` |
+| **Chat ids** | `~/.cursor/chats/<md5 of cwd>/<id>/meta.json`, verified against the cwd |
+| **Wraps** | `cursor-agent` only |
+
+**Cursor's limit is the first one not worth waiting for.** Its usage resets on
+your monthly *billing cycle*, not a rolling window. From a real limit:
+
+```
+Error: You've hit your usage limit
+Get Cursor Pro for more Agent usage, unlimited Tab, and more.
+fallbackModel:
+spendLimitHit: false
+chatMessage: *…Your usage limits will reset when your monthly cycle ends on 10/2/2026.*
+spendLimits: [50,100,200]
+```
+
+A month out. Sleeping on that would mean a monitor waking in October to type
+into a wall that never moved. So unsnooze treats it as a **model limit**:
+
+- records the stop and tells you it needs a decision
+- probes at 15/30/60 min, resuming the moment the banner clears — you change
+  plan, or the cycle rolls
+- marks the record `failed` at the probe ceiling instead of sending a futile wake
+
+`resetPatterns` is empty on purpose (a test pins it): any reset pattern there
+would silently re-route Cursor onto the 5-hour fallback ladder.
+
+Transport errors take the transient-overload ladder and `Authentication
+required` is notify-only — neither reaches the ledger. Banner text is
+server-provided and plan-dependent, so `unsnooze report cursor` is how it
+improves.
+
+### `cursor .` still opens the IDE
+
+Cursor ships its CLI as both `cursor-agent` and `agent`, while the bare
+`cursor` is the *editor* launcher. Adapters can now declare `wrapperNames`, so
+unsnooze wraps `cursor-agent` and leaves the other two alone — `agent` is far
+too generic to shadow safely. Wrapper output for the existing seven adapters is
+unchanged, byte for byte.
+
+### Model limits now suggest something you can actually do
+
+Both the "needs you" and probe-ceiling notifications hardcoded Claude's
+wording, so a Cursor user was told to run `/usage-credits` — a command Cursor
+does not have. The hint moves onto the adapter, and since a model limit has no
+reset time to wait for, that one sentence is the whole remedy.
+
 ## 1.17.0 — 2026-08-23
 
 - **A state directory unsnooze cannot write to no longer pins a CPU core

package/README.md

@@ -6,14 +6,14 @@
 
 [![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.**
 
 [Website](https://unsnooze.dev) · [Documentation](https://unsnooze.dev/docs/) · [Changelog](https://unsnooze.dev/changelog/) · [Feedback](https://unsnooze.dev/feedback/)
 
-**Claude Code · Codex CLI · Grok · Qwen · Kimi · OpenCode · Antigravity** — when they hit the 5-hour or weekly usage limit
+**Claude Code · Codex CLI · Grok · Qwen · Kimi · OpenCode · Antigravity · Cursor** — when they hit the 5-hour or weekly usage limit
 ("You've hit your usage limit"), your session just… stops.<br/>
 unsnooze auto-resumes them: it tracks **every** limit-stopped session across all
 your projects and **wakes each one up the moment the usage limit resets** — in
@@ -35,7 +35,7 @@ existing tool solves only a slice of it:
 
 | | **unsnooze** | claude-auto-retry | autoclaude | hydra |
 |---|:---:|:---:|:---:|:---:|
-| Multi-CLI (Claude · Codex · Grok · Qwen · Kimi · OpenCode · Antigravity) | ✅ | ❌ Claude only | ❌ Claude only | partial |
+| Multi-CLI (Claude · Codex · Grok · Qwen · Kimi · OpenCode · Antigravity · Cursor) | ✅ | ❌ Claude only | ❌ Claude only | partial |
 | GUI sessions (VS Code ext, desktop apps) | ✅ watcher daemon | ❌ | ❌ | ❌ |
 | Waits for reset & resumes the **same** session | ✅ | ✅ | ✅ | ❌ switches provider |
 | All sessions at once (shared ledger + one daemon) | ✅ | ❌ one pane | ✅ | ✅ |
@@ -143,6 +143,24 @@ risks, and vulnerability reporting: **[SECURITY.md](SECURITY.md)**.
   overload, not a limit. Dead sessions revive via `agy --conversation=<id>`
   (ids from `~/.gemini/antigravity-cli/history.jsonl`). Like Grok: closed
   source, so `unsnooze report` captures make this adapter better.
+- **Cursor CLI (`cursor-agent`)** — ⚠️ *experimental*, and the only adapter
+  whose limit is **not waitable**. Cursor's included usage resets on your
+  monthly *billing cycle*, not a rolling window, so unsnooze deliberately never
+  schedules a wake for it: the banner is classified as a model limit, which
+  probes every 15/30/60 min and resumes the moment it clears (you switch to
+  Auto, enable on-demand, or the cycle rolls) instead of sleeping for weeks.
+  The banner text is server-provided — the CLI renders `Error: <title>` plus a
+  detail line and `key: value` extras — and the patterns are pinned against a
+  real captured limit (whose own reset date was a month out, which is the point).
+  `unsnooze report cursor` is how the rest gets better. Transport errors take the transient-overload ladder and
+  `Authentication required` is notify-only. Dead sessions revive via
+  `cursor-agent --resume=<id>` — ids come from `~/.cursor/chats/<md5 of the
+  cwd>/<chatId>/meta.json`, which records the `cwd` so every candidate is
+  verified before use — and `--continue` otherwise, which is workspace-scoped.
+
+  The wrapper shadows **`cursor-agent`** only. The bare `cursor` command is the
+  IDE launcher (`cursor .`) and is never touched; the newer `agent` alias is
+  left alone too, being too generic a name to shadow safely.
 
 **OpenRouter** (the API gateway) isn't a separate agent: its 429 bodies
 (`Rate limit exceeded: limit_rpd/…`, free-models-per-day) are detected inside
@@ -205,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:
@@ -221,6 +240,10 @@ the session files those surfaces already write:
   where Codex lives only inside ChatGPT.app (no `codex` on PATH), unsnooze
   automatically resumes through the app-bundled binary
   (`/Applications/ChatGPT.app/Contents/Resources/codex`).
+  The watcher also recognizes a reported 99% five-hour window followed within
+  one minute by an empty `premium` bucket with no credits, using the previous
+  future reset time. The snapshots must come from the same rollout; 99% alone
+  is not a stop signal. This works across watcher polls and daemon restarts.
 - **Claude desktop (cowork) sessions** *(experimental, macOS)* run in
   sandboxes under `~/Library/Application Support/Claude`; unsnooze watches
   those too and revives with the session's isolated `CLAUDE_CONFIG_DIR`
@@ -271,11 +294,11 @@ StopFailure hook (claude, grok) ──────────────┤
 
 </details>
 
-Limit events are never persisted by the CLIs themselves; the reset time is
-parsed from the banner text, DST-safe. Unparseable banners are never guessed
-at — unsnooze probes the pane on a backoff schedule until a real reset time
-appears. Every resume is verified afterwards (banner came back → reschedule
-from the fresh banner, capped at 5 attempts).
+Detection uses agent hooks, saved session files, and terminal banners. Reset
+times come from the agent's saved timestamp or the banner text, parsed DST-safe.
+When no reset time is available, unsnooze probes on a backoff schedule. Every
+resume is verified afterwards (banner came back → reschedule from the fresh
+banner, capped at 5 attempts).
 
 ## Know the wall before you hit it
 
@@ -557,11 +580,11 @@ password hosts on Windows; a plain `ssh <host>` prompt works with native
 | `notifyChannel` | `auto` | How to deliver: `auto`, `native`, `osc`, or `bell` (see [Notification channels](#notification-channels)). Env: `UNSNOOZE_NOTIFY_CHANNEL`. |
 | `guiWatch` | `true` | May the daemon watch session files for GUI-surface stops (VS Code extension, desktop apps)? Needs the daemon running (`unsnooze install --daemon`). |
 | `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. Override it for a single session with `unsnooze message <id> "…"` — visible in `unsnooze status`. |
-| `resumeMessages.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
-| `resumeExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Extra flags for launches unsnooze performs itself. A revival spawns the agent binary directly, so flags you normally get from a shell alias or wrapper (`--dangerously-skip-permissions`, `--model …`) do not apply unless you put them here. Quoting is respected: `--append-system-prompt "stay in this repo"` is two arguments, not five. `config.json` may also hold an array (`["--append-system-prompt", "stay in this repo"]`), which skips parsing entirely. |
-| `launchExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Extra flags for the sessions **you** start through the shell wrapper — the launch-side twin of `resumeExtraArgs`. Use it for flags that have to hold for the whole session: `unsnooze config set launchExtraArgs.claude "--autocompact 400000"` keeps a long, context-heavy run compacting instead of stalling. Flags are placed before your own arguments, since `claude "do the thing"` puts a positional prompt there. Revivals inherit them too, so a flag survives the wake. |
+| `resumeMessages.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` / `.cursor` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
+| `resumeExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` / `.cursor` | `""` | Extra flags for launches unsnooze performs itself. A revival spawns the agent binary directly, so flags you normally get from a shell alias or wrapper (`--dangerously-skip-permissions`, `--model …`) do not apply unless you put them here. Quoting is respected: `--append-system-prompt "stay in this repo"` is two arguments, not five. `config.json` may also hold an array (`["--append-system-prompt", "stay in this repo"]`), which skips parsing entirely. |
+| `launchExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` / `.cursor` | `""` | Extra flags for the sessions **you** start through the shell wrapper — the launch-side twin of `resumeExtraArgs`. Use it for flags that have to hold for the whole session: `unsnooze config set launchExtraArgs.claude "--autocompact 400000"` keeps a long, context-heavy run compacting instead of stalling. Flags are placed before your own arguments, since `claude "do the thing"` puts a positional prompt there. Revivals inherit them too, so a flag survives the wake. |
 | `agents.claude` / `agents.codex` | `true` | Which CLIs are guarded. |
-| `agents.grok` / `agents.qwen` / `agents.kimi` / `agents.opencode` / `agents.agy` | `false` | Experimental adapters — off by default; enable in `unsnooze setup` or `unsnooze config set agents.qwen on`. |
+| `agents.grok` / `agents.qwen` / `agents.kimi` / `agents.opencode` / `agents.agy` / `agents.cursor` | `false` | Experimental adapters — off by default; enable in `unsnooze setup` or `unsnooze config set agents.qwen on`. |
 | `workspaceGuard` | `inform` | Repo changed while a session slept? `inform` wakes it with a heads-up in the message; `pause` holds it (desktop notification, diff shown on `resume-now`); `off` disables. |
 | `contextGuard` | `inform` | Big cold context at wake? Waking a session re-reads its **entire context at full uncached price** ([why](#why-did-resuming-a-big-session-eat-so-much-of-my-quota)). `inform` resumes and notifies you of the size; `pause` holds sessions above the threshold for `unsnooze resume-now`; `off` disables. Claude Code only for now. |
 | `contextGuardTokens` | `100000` | Context-size threshold (tokens) at which `contextGuard` notifies or holds. |
@@ -662,9 +685,20 @@ watcher stops (no pane context) always use native.
   [Watching without a multiplexer](#watching-without-a-multiplexer))
 - tmux ≥ 3.2, Zellij, **or** herdr ≥ 0.8.0 for pane-level watching. Optional:
   without one, unsnooze runs `headless` and still catches and resumes stops.
-- zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), or PowerShell
+- zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), fish (wrappers go
+  into `~/.config/fish/config.fish`), or PowerShell
   (wrappers go into `$PROFILE.CurrentUserAllHosts`)
 
+Fish wrappers are installed when fish is the login shell or its config already
+exists. An absolute `XDG_CONFIG_HOME` changes the config location to
+`$XDG_CONFIG_HOME/fish/config.fish`; `unsnooze install --fishrc <path>` and
+`unsnooze uninstall --fishrc <path>` override it explicitly. After upgrading an
+existing install, run `unsnooze setup` and open a new shell to load the wrappers.
+
+Agent help/version commands, such as `claude --help` and `codex --version`, run
+directly without a multiplexer session, pane monitor, `launchExtraArgs`, or an
+unsnooze update notice. `unsnooze help` still shows unsnooze's own commands.
+
 ### Supported terminals
 
 unsnooze drives four terminal multiplexers, and works without one.

package/bin/unsnooze.js

@@ -26,6 +26,7 @@ const AGENT_FALLBACK_BINS = {
   kimi: () => process.env.UNSNOOZE_KIMI_BIN || 'kimi',
   opencode: () => process.env.UNSNOOZE_OPENCODE_BIN || 'opencode',
   agy: () => process.env.UNSNOOZE_AGY_BIN || 'agy',
+  cursor: () => process.env.UNSNOOZE_CURSOR_BIN || 'cursor-agent',
 };
 
 async function safeImport(specifier) {
@@ -68,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();
@@ -339,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,7 +1,7 @@
 {
   "name": "unsnooze",
-  "version": "1.17.0",
-  "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, and Antigravity sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
+  "version": "1.19.0",
+  "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, Antigravity, and Cursor CLI sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",
     "claude-code",
@@ -18,6 +18,9 @@
     "moonshot",
     "opencode",
     "antigravity",
+    "cursor",
+    "cursor-cli",
+    "cursor-agent",
     "antigravity-cli",
     "gemini",
     "google",

package/src/agents/claude.js

@@ -114,6 +114,9 @@ export default {
   bin: process.env.UNSNOOZE_CLAUDE_BIN || 'claude',
   experimental: false,
   patterns,
+  // Remedy hint for a model limit — no reset time to wait for, so the
+  // notification has to say what the user can actually do about it.
+  modelRemedy: 'switch models (/model) or add credits (/usage-credits)',
   menu: { isPrompt: isRateLimitOptionsPrompt, stepsToWait: menuStepsToWaitOption },
   // How to reopen a dead session.
   //

package/src/agents/cursor.js

@@ -0,0 +1,225 @@
+// Cursor CLI adapter (`cursor-agent`) — EXPERIMENTAL.
+//
+// Cursor ships its terminal agent as ~/.local/bin/{agent,cursor-agent}, both
+// symlinks to ~/.local/share/cursor-agent/versions/<v>/cursor-agent. That file
+// is a bash shim that runs `exec -a "$0" <bundled node> index.js`, so the
+// binary is Node and tmux reports `node` as pane_current_command (verified on
+// darwin/arm64, 2026.08.31-4057e58).
+//
+// The id is `cursor` but the wrapped command is `cursor-agent` (see
+// `wrapperNames` below): the bare `cursor` is the IDE launcher (`cursor .`)
+// and must never be shadowed. The other name, `agent`, is deliberately NOT
+// wrapped — too generic to shadow safely.
+//
+// WHY resetPatterns IS EMPTY — do not "fix" this.
+// Cursor's included usage resets on the monthly BILLING CYCLE ("Your usage
+// limits will reset when your monthly cycle ends on 8/14/2025"), not on a
+// rolling window. detectLimit() runs the waitable-limit loop before the
+// model-limit branch, so a reset pattern here would pair with the banner and
+// produce a `limitType: 'unknown'` record whose unparseable date falls back to
+// 5h — i.e. a blind resume into a wall that is still standing. An empty
+// resetPatterns routes the banner down the model-limit path instead, which
+// probes until the banner clears and never schedules a blind wake. There is a
+// test pinning this.
+//
+// Banner provenance: the limit text is SERVER-provided. The CLI bundle
+// contains no limit strings — it renders `Error: ${details.title}`, then
+// `details.detail`, then one `key: value` line per `details.additionalInfo`
+// entry, with persistUntilInput so the banner stays on screen. CAPTURED FROM A
+// REAL LIMIT (free plan, 2026-09-02):
+//
+//   Error: You've hit your usage limit
+//   Get Cursor Pro for more Agent usage, unlimited Tab, and more.
+//   fallbackModel:
+//   spendLimitHit: false
+//   chatMessage: *You've hit your free requests limit. [Upgrade to
+//   Pro](https://www.cursor.com/...) for more usage, frontier models, Cloud
+//   Agents, and more. Your usage limits will reset when your monthly cycle
+//   ends on 10/2/2026.*
+//   spendLimits: [50,100,200]
+//
+// Note the reset is a MONTH out — exactly why this is not a waitable stop. A
+// `-p` run prints the same thing to stderr with the error class as the prefix
+// (`ActionRequiredError: ...`) and exits 1. Pro-plan wording differs ("Switch
+// to Auto…", "set a Spend Limit") and is covered from user reports; improve
+// the rest from real hits with `unsnooze report cursor`.
+//
+// Verified live against 2026.08.31-4057e58 (logged in, real tmux):
+//   idle      ` → Plan, search, build anything` / ` → Add a follow-up`
+//   busy      `⠘⠤ Working` (braille spinner + label) and the input box's
+//             right placeholder `ctrl+c to stop`
+//   resume    `--continue` is WORKSPACE-scoped — run from project A it resumed
+//             A's chat, not the globally-newest one in B. That is what the
+//             resumer's one-anonymous-record-per-agent+cwd rule assumes, so no
+//             --workspace flag is needed.
+//   submit    the wake message lands with tmux's `send-keys -l` + a separate
+//             `send-keys Enter`, which is exactly what mux.sendText already does.
+//
+// A first launch in an untrusted directory shows a modal "⚠ Workspace Trust
+// Required" screen instead of the prompt. It carries no `→`, so idleRegex
+// already refuses to type into it; busyPatterns names it as well so the refusal
+// does not depend on that. unsnooze deliberately does NOT pass `--trust` on
+// revival — granting execution trust is the user's call, not a side effect of
+// waking a session.
+//
+// Deferred: Cursor writes a status into the TERMINAL TITLE (idle/generating/
+// planning/shell-running/waiting-for-user...), which is a far cleaner
+// busy/idle signal than scraping — but the adapter contract only sees
+// capture-pane text. See the adapter notes in the changelog.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CURSOR_DIR = () => process.env.UNSNOOZE_CURSOR_DIR || join(homedir(), '.cursor');
+const SCAN_LIMIT = 50;   // project dirs walked by the fallback scan
+
+const LIMIT_ANCHORS = [
+  /You[’']ve hit your (?:usage|free requests?|monthly) limit/i,
+  /You[’']ve hit your limit/i,
+  /(?:usage|spend) limit reached/i,
+];
+
+export const patterns = {
+  limitPatterns: LIMIT_ANCHORS,
+  resetPatterns: [],          // deliberate — see the header
+  weeklyPatterns: [],
+  fiveHourPatterns: [],
+  // The monthly cap is lifted by a human choice (switch to Auto, enable
+  // on-demand, wait for the billing date), never by a short wait — the same
+  // shape as claude's per-model limit, so it takes the same path.
+  modelLimitPatterns: LIMIT_ANCHORS,
+  // The detail line is plan-dependent — a free account is told to upgrade, a Pro
+  // account to switch models or raise a spend limit — so cover both rather than
+  // leaning on the additionalInfo keys alone, which Cursor could drop.
+  modelRemedyPatterns: [
+    /Get Cursor Pro for more Agent usage/i,        // free tier (captured live)
+    /\[?Upgrade to\s+Pro\]?/i,
+    /Switch to Auto for more usage/i,              // Pro tier (reported)
+    /set a Spend Limit/i,
+    /usage limits will reset when your monthly cycle ends/i,
+    /enable (?:on-demand|usage-based)/i,
+    // additionalInfo entries render as bare `key: value` lines under the detail.
+    /^\s*(?:spendLimitHit|fallbackModel|spendLimits|chatMessage):/,
+  ],
+  busyPatterns: [
+    /ctrl\+c to stop/i,                          // input box's right placeholder while generating
+    /[\u2800-\u28ff]\s*(?:Working|Composing)\b/,  // braille spinner + label, e.g. `⠘⠤ Working`
+    // Not "busy" in the streaming sense, but equally un-typeable: the modal
+    // trust gate on a first launch in a directory.
+    /Workspace Trust Required/i,
+    /Do you trust the contents of this directory/i,
+  ],
+  idleRegex: /→/,           // the input box prompt glyph
+  overloadPatterns: [
+    /Can[’']t (?:resolve the Cursor API host|reach the Cursor API)/i,
+    /\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|ENOTFOUND|EAI_AGAIN|NGHTTP2|ERR_HTTP2_SESSION_ERROR)\b/,
+    /socket hang up|Premature close|connection aborted/i,
+    /Agent stopped retrying/i,
+  ],
+  transientPatterns: [
+    /\b(?:ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/,
+  ],
+  // Auth is not a quota — notify once and record nothing. `-p` runs print the
+  // error class instead of the `Error:` prefix the TUI uses, so match the text
+  // rather than either prefix.
+  terminalPatterns: [
+    /Authentication required\b/i,
+    /Please run '(?:cursor-)?agent login'/i,
+  ],
+};
+
+// Cursor stores each CLI chat as ~/.cursor/chats/<md5(cwd)>/<chatId>/, where
+// <chatId> is the directory name and is exactly what `--resume=<id>` takes
+// (verified live). Its meta.json carries `{ cwd, updatedAtMs, title }`, so the
+// mapping needs no SQLite and no dependency — and every candidate is checked
+// against the cwd before it is used. If Cursor ever changes the hash, the
+// bounded fallback scan below still finds it; if it changes meta.json too,
+// this returns null and the resumer falls back to `--continue`, which is
+// workspace-scoped anyway. A wrong id would resume someone else's
+// conversation, so null is always preferred to a guess.
+//
+// aroundTs is accepted and ignored (as in agy): the chat that just stopped is
+// the most recently updated one for the cwd, which is what we return.
+function readChatMeta(chatDir) {
+  try {
+    const meta = JSON.parse(readFileSync(join(chatDir, 'meta.json'), 'utf-8'));
+    if (!meta || typeof meta.cwd !== 'string') return null;
+    return { cwd: meta.cwd, updatedAtMs: Number(meta.updatedAtMs) || 0 };
+  } catch {
+    return null;
+  }
+}
+
+// Newest chat under `dir` whose meta.json cwd equals `cwd`.
+function newestChatIn(dir, cwd) {
+  let best = null;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return null; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = readChatMeta(join(dir, entry.name));
+    if (!meta || meta.cwd !== cwd) continue;
+    if (!best || meta.updatedAtMs > best.updatedAtMs) best = { id: entry.name, updatedAtMs: meta.updatedAtMs };
+  }
+  return best;
+}
+
+export function latestSessionId(cwd, aroundTs = null, cursorDir = CURSOR_DIR()) {
+  if (!cwd) return null;
+  const chats = join(cursorDir, 'chats');
+  // Fast path: the project directory is md5 of the cwd (verified live).
+  const direct = newestChatIn(join(chats, createHash('md5').update(cwd).digest('hex')), cwd);
+  if (direct) return direct.id;
+  // Fallback: the hash scheme changed. Scan the most recently touched project
+  // directories only — bounded so a long-lived install never walks hundreds.
+  let projects;
+  try {
+    projects = readdirSync(chats, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => {
+        const full = join(chats, e.name);
+        let mtimeMs = 0;
+        try { mtimeMs = statSync(full).mtimeMs; } catch { /* skip */ }
+        return { full, mtimeMs };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+      .slice(0, SCAN_LIMIT);
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const project of projects) {
+    const found = newestChatIn(project.full, cwd);
+    if (found && (!best || found.updatedAtMs > best.updatedAtMs)) best = found;
+  }
+  return best ? best.id : null;
+}
+
+export default {
+  id: 'cursor',
+  name: 'Cursor CLI',
+  bin: process.env.UNSNOOZE_CURSOR_BIN || 'cursor-agent',
+  // `cursor` is the IDE launcher — wrap the agent command only.
+  wrapperNames: ['cursor-agent'],
+  experimental: true,
+  patterns,
+  // Cursor has /model, but no /usage-credits — on-demand usage is a dashboard
+  // setting. Telling a Cursor user to run a command that does not exist is
+  // worse than saying nothing.
+  modelRemedy: 'switch to Auto (/model) or enable on-demand usage in your Cursor dashboard',
+  menu: null,
+  // `--resume [chatId]` and `--continue` both verified in `cursor-agent --help`
+  // (2026.08.31). --resume takes an optional value, so use the equals form.
+  resumeArgs(sessionId) {
+    return { args: sessionId ? [`--resume=${sessionId}`] : ['--continue'], messageViaPane: true };
+  },
+  // v1: every agent launches the bare TUI and gets the prompt typed once idle.
+  launchArgs(message) { return { args: [], messageViaPane: true }; },
+  latestSessionId,
+  // The bash shim execs the bundled node, so tmux reports `node`.
+  isForegroundCommand(cmd) {
+    return cmd === 'cursor-agent' || cmd === 'agent' || cmd === 'node' || cmd === 'unsnooze';
+  },
+};

package/src/agents/index.js

@@ -8,8 +8,9 @@ import qwen from './qwen.js';
 import kimi from './kimi.js';
 import opencode from './opencode.js';
 import agy from './agy.js';
+import cursor from './cursor.js';
 
-const REGISTRY = { claude, codex, grok, qwen, kimi, opencode, agy };
+const REGISTRY = { claude, codex, grok, qwen, kimi, opencode, agy, cursor };
 
 // v1: every agent launches the bare TUI and gets the prompt typed once idle.
 function defaultLaunchArgs(message) { return { args: [], messageViaPane: true }; }

package/src/doctor.js

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

package/src/fish.js

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

package/src/install.js

@@ -5,8 +5,11 @@
 //     atomic write)
 //   - ~/.zshrc + ~/.bashrc: one fence-marked block with a wrapper function per
 //     enabled agent (claude/codex/grok), routed through `unsnooze _run`
+//   - ~/.config/fish/config.fish: the same block in fish syntax (fish shares
+//     no syntax with POSIX rc files — a bash function there is a parse error)
 //   - ~/.grok/hooks/unsnooze.json when the grok agent is enabled
-// --settings <path> / --zshrc <path> override targets (used by tests).
+// --settings <path> / --zshrc <path> / --fishrc <path> override targets (used
+// by tests).
 
 import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
@@ -16,10 +19,12 @@ import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
 import { getConfig, configFileExists } from './settings.js';
 import { xmlEscape } from './notify.js';
 import { installGrokHooks, uninstallGrokHooks } from './agents/grok.js';
+import { getAgent } from './agents/index.js';
 import { findCsgProcesses, findCsgAutostarts } from './doctor.js';
 import { UNSNOOZE_BIN, stopResumer } from './spawn.js';
 import { uninstallStatuslineShim } from './usage.js';
 import { powershellProfilePath } from './powershell.js';
+import { fishConfigPath } from './fish.js';
 
 const FENCE_OPEN = '# >>> unsnooze >>>';
 const FENCE_CLOSE = '# <<< unsnooze <<<';
@@ -32,13 +37,17 @@ const LEGACY_FENCES = [
 const OLD_FENCE_OPEN = LEGACY_FENCES[0].open;
 
 function parseArgs(rest) {
-  const opts = { yes: false, settings: CLAUDE_SETTINGS, zshrc: join(homedir(), '.zshrc'), purge: false, daemon: false };
+  const opts = {
+    yes: false, settings: CLAUDE_SETTINGS, zshrc: join(homedir(), '.zshrc'),
+    fishrc: fishConfigPath(), purge: false, daemon: false,
+  };
   for (let i = 0; i < rest.length; i++) {
     if (rest[i] === '--yes' || rest[i] === '-y') opts.yes = true;
     else if (rest[i] === '--purge') opts.purge = true;
     else if (rest[i] === '--daemon') opts.daemon = true;
     else if (rest[i] === '--settings') opts.settings = rest[++i];
     else if (rest[i] === '--zshrc') opts.zshrc = rest[++i];
+    else if (rest[i] === '--fishrc') opts.fishrc = rest[++i];
   }
   return opts;
 }
@@ -115,18 +124,29 @@ export function removeHookFromSettings(settingsJson) {
 
 // --- zshrc block management ---
 
+// Which shell commands an agent's wrappers shadow. Normally exactly the id,
+// because the id IS the command users type. Cursor breaks that: its id is
+// `cursor` but its command is `cursor-agent`, and the bare `cursor` belongs to
+// the IDE launcher (`cursor .`) which must never be shadowed. An adapter names
+// the commands to wrap via `wrapperNames`; the `_run` argument stays the id.
+export function wrapperNamesFor(id) {
+  const agent = getAgent(id);
+  // getAgent falls back to claude for unknown ids — never borrow its names.
+  return agent.id === id && agent.wrapperNames?.length ? agent.wrapperNames : [id];
+}
+
 export function wrapperBlock(agents = ['claude']) {
   // The missing-file guard is load-bearing: if unsnooze is ever uninstalled,
   // moved, or renamed without cleaning the rc file, the wrapper must degrade
   // to the plain CLI — never brick the user's `claude`/`codex` command.
-  const fns = agents.map(id => `unalias ${id} 2>/dev/null || true
-${id}() {
+  const fns = agents.flatMap(id => wrapperNamesFor(id).map(name => `unalias ${name} 2>/dev/null || true
+${name}() {
   if [ "\${UNSNOOZE_ACTIVE}" = "1" ] || [ ! -f "${UNSNOOZE_BIN}" ]; then
-    command ${id} "$@"
+    command ${name} "$@"
     return $?
   fi
   node "${UNSNOOZE_BIN}" _run ${id} "$@"
-}`).join('\n');
+}`)).join('\n');
   return `${FENCE_OPEN}
 # unsnooze wrappers: route every interactive launch of the CLIs below through
 # unsnooze so limit stops are recorded and auto-resumed.
@@ -142,16 +162,16 @@ ${FENCE_CLOSE}`;
 // PowerShell comments are `#`, so the same fence markers work and
 // stripFencedBlock() removes it unchanged.
 export function powershellWrapperBlock(agents = ['claude'], bin = UNSNOOZE_BIN) {
-  const fns = agents.map(id => `Remove-Item -Path Alias:${id} -Force -ErrorAction SilentlyContinue
-function ${id} {
+  const fns = agents.flatMap(id => wrapperNamesFor(id).map(name => `Remove-Item -Path Alias:${name} -Force -ErrorAction SilentlyContinue
+function ${name} {
   if ($env:UNSNOOZE_ACTIVE -eq '1' -or -not (Test-Path -LiteralPath '${bin}')) {
-    $real = Get-Command ${id} -CommandType Application -ErrorAction SilentlyContinue |
+    $real = Get-Command ${name} -CommandType Application -ErrorAction SilentlyContinue |
       Select-Object -First 1
-    if ($real) { & $real.Source @args } else { Write-Error '${id}: not found' }
+    if ($real) { & $real.Source @args } else { Write-Error '${name}: not found' }
     return
   }
   & node '${bin}' _run ${id} @args
-}`).join('\n');
+}`)).join('\n');
   return `${FENCE_OPEN}
 # unsnooze wrappers: route every interactive launch of the CLIs below through
 # unsnooze so limit stops are recorded and auto-resumed.
@@ -192,6 +212,38 @@ export function installZshrcBlock(content, agents = ['claude']) {
   return { content: result, oldRemoved };
 }
 
+// The fish twin of wrapperBlock(). Fish shares no syntax with the POSIX block:
+// `name() { … }` is a parse error there, `$?` is `$status`, and `"${X}"` is
+// `"${X}"` verbatim text — so the wrapper gets its own body. Same semantics as
+// the zsh/bash wrapper: a recursion guard (UNSNOOZE_ACTIVE), the load-bearing
+// missing-file fallback to the real CLI, and `_run <id>` routing.
+//
+// Redefining a function replaces any earlier one, which covers fish "aliases"
+// (they are functions too) — no `unalias` analogue is needed. Fish comments
+// are `#`, so the same fence markers work and stripFencedBlock() removes it
+// unchanged.
+export function fishWrapperBlock(agents = ['claude'], bin = UNSNOOZE_BIN) {
+  const fns = agents.flatMap(id => wrapperNamesFor(id).map(name => `function ${name} --description 'unsnooze-wrapped ${name}'
+  if test "$UNSNOOZE_ACTIVE" = "1"; or not test -f '${bin}'
+    command ${name} $argv
+    return $status
+  end
+  node '${bin}' _run ${id} $argv
+end`)).join('\n');
+  return `${FENCE_OPEN}
+# unsnooze wrappers: route every interactive launch of the CLIs below through
+# unsnooze so limit stops are recorded and auto-resumed.
+${fns}
+${FENCE_CLOSE}`;
+}
+
+// installZshrcBlock's fish twin. Same fence, same replace-don't-append
+// behaviour, so re-running setup never stacks a second copy of the wrappers.
+export function installFishBlock(content, agents = ['claude'], bin = UNSNOOZE_BIN) {
+  const { content: cleaned } = stripFencedBlock(content, FENCE_OPEN, FENCE_CLOSE);
+  return cleaned.replace(/\n+$/, '\n') + '\n' + fishWrapperBlock(agents, bin) + '\n';
+}
+
 // --- daemon autostart ---
 // GUI sessions (VS Code extension, desktop apps) never pass through the shell
 // wrappers, so their limit stops are only caught while `unsnooze daemon` is
@@ -502,7 +554,7 @@ export function uninstallDaemonAutostart({ platform = process.platform, dir = nu
 // --- commands ---
 
 export function enabledAgents() {
-  return ['claude', 'codex', 'grok', 'qwen', 'kimi', 'opencode', 'agy'].filter(id => getConfig(`agents.${id}`));
+  return ['claude', 'codex', 'grok', 'qwen', 'kimi', 'opencode', 'agy', 'cursor'].filter(id => getConfig(`agents.${id}`));
 }
 
 // Qwen keeps Claude-shaped hooks in its own settings.json — reuse the same
@@ -543,6 +595,22 @@ function rcTargets(opts, explicit) {
   return existing.length > 0 ? existing : [opts.zshrc];
 }
 
+// The fish config is a separate target from the POSIX rc loop: fish syntax
+// shares nothing with bash, so it gets its own block, and fish reads only
+// <config-home>/fish/config.fish. Touch it when the file already exists (the
+// same any-rc rule as zsh/bash), or when fish is the login shell — a fish
+// user may not have created config.fish yet, and a wrapper that would never
+// load is the same silent-miss as a profile written to a guessed path. Empty
+// list = no evidence of fish on this machine; leave it alone.
+function fishTargets(opts, explicit) {
+  if (explicit) return [opts.fishrc];
+  const cfg = fishConfigPath();
+  if (existsSync(cfg)) return [cfg];
+  const loginShell = process.env.SHELL || userInfo().shell;
+  if (typeof loginShell === 'string' && /(^|\/|\\)fish$/.test(loginShell)) return [cfg];
+  return [];
+}
+
 export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
   const opts = parseArgs(rest);
   const explicitRc = rest.includes('--zshrc');
@@ -611,6 +679,21 @@ export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
     }
   }
 
+  // 3c. Fish config. The POSIX loop above is a parse error in fish, and the
+  //     PowerShell profile never loads there — fish needs its own block or a
+  //     fish user's `claude` never routes through unsnooze at all.
+  for (const cfg of fishTargets(opts, rest.includes('--fishrc'))) {
+    try {
+      mkdirSync(dirname(cfg), { recursive: true });
+      const before = existsSync(cfg) ? readFileSync(cfg, 'utf-8') : '';
+      if (existsSync(cfg)) backupOnce(cfg);
+      atomicWrite(cfg, installFishBlock(before, agents, UNSNOOZE_BIN));
+      console.log(`unsnooze: fish wrappers (${agents.join(', ')}) installed in ${cfg}`);
+    } catch (err) {
+      console.log(`unsnooze: could not write the fish config (${err.message})`);
+    }
+  }
+
   // 4. Daemon autostart (GUI-session watching), opt-in via --daemon / wizard.
   if (opts.daemon) {
     const target = installDaemonAutostart();
@@ -686,6 +769,17 @@ export function cmdUninstall(rest) {
     console.log(`unsnooze: could not clean the PowerShell profile (${err.message})`);
   }
 
+  // The fish config is a wrapper site too, same reason as the PowerShell
+  // profile above: a stale block would keep shadowing the real CLI.
+  for (const cfg of fishTargets(opts, rest.includes('--fishrc'))) {
+    if (!existsSync(cfg)) continue;
+    const { content, found } = stripFencedBlock(readFileSync(cfg, 'utf-8'), FENCE_OPEN, FENCE_CLOSE);
+    if (found) {
+      atomicWrite(cfg, content);
+      console.log(`unsnooze: fish wrappers removed from ${cfg}`);
+    }
+  }
+
   const autostart = uninstallDaemonAutostart();
   if (autostart) console.log(`unsnooze: daemon autostart removed (${autostart})`);
 

package/src/launcher.js

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

package/src/monitor.js

@@ -16,7 +16,7 @@ import {
   EVENT_MARKER_TTL_MS, OVERLOAD_BACKOFF_S, OVERLOAD_JITTER,
   PROBE_INTERVAL_MS, RESET_MARGIN_MS, LEASE_GRACE_MS,
 } from './config.js';
-import { detectLimit, isBusy, overloadMatch } from './patterns.js';
+import { detectLimit, isBusy, overloadMatch, modelRemedy } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { getConfig } from './settings.js';
 import { notify } from './notify.js';
@@ -208,7 +208,7 @@ export function createMonitor({
     log(`pane ${pane}: limit recorded (${resolved.limitType}, via ${detectedVia}), resets ${new Date(at).toISOString()} (${source})`);
     if (resolved.limitType === 'model') {
       notifier(`${agent.name} hit a model limit — needs you`,
-        `${cwd} — switch models (/model) or add credits (/usage-credits); unsnooze wakes it once the banner clears`,
+        `${cwd} — ${modelRemedy(agent)}; unsnooze wakes it once the banner clears`,
         { context: notifyCtx });
     } else {
       notifier(`${agent.name} hit a usage limit`, `${cwd} — auto-resume at ${new Date(at).toLocaleTimeString()}`, { context: notifyCtx });

package/src/patterns.js

@@ -148,6 +148,13 @@ export function detectLimit(text, tailLines = 12, sets = claudePatterns) {
   return { hit: true, limitType, resetLine };
 }
 
+// What a user can actually do about a model limit. There is no reset time to
+// wait for, so the notification must name a real remedy — and the remedy is
+// per-CLI (claude has /usage-credits, cursor does not).
+export function modelRemedy(agent) {
+  return agent?.modelRemedy || 'switch models or add credits';
+}
+
 function tail(text, n = 12) {
   return contentLines(text, n);
 }

package/src/resumer.js

@@ -14,7 +14,7 @@ import {
   CAPTURE_LINES, PANE_SCAN_LINES, RESUME_SESSION_NAME,
   RESET_MARGIN_MS, FALLBACK_RESET_MS, PROBE_INTERVAL_MS, PROBE_MAX_MS,
 } from './config.js';
-import { detectLimit, isBusy } from './patterns.js';
+import { detectLimit, isBusy, modelRemedy } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { parseResetTime, resetAtMs, nextProbeDelayMs } from './time-parser.js';
 import {
@@ -372,7 +372,7 @@ function rescheduleProbe(rec, now = Date.now()) {
       }, { expect: ['stopped'] });
       log(`${key}: model limit still active at probe ceiling — needs a human`);
       notify('unsnooze: model limit needs you ⚠️',
-        `${rec.cwd}: still limited after probing — /model to switch or /usage-credits`,
+        `${rec.cwd}: still limited after probing — ${modelRemedy(getAgent(rec.agent))}`,
         { context: ctxOf(rec), priority: 4 });
       return 'held';
     }

package/src/settings.js

@@ -45,19 +45,19 @@ export const DEFAULTS = {
   // command that answers 'disabled' still returns a valid framed envelope.
   remoteQueue: true,
   resumeMessage: 'Continue where you left off. The session was interrupted by a usage limit which has now reset — pick up the task you were working on and finish it.',
-  resumeMessages: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '' },  // per-agent override; '' = use resumeMessage
+  resumeMessages: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '', cursor: '' },  // per-agent override; '' = use resumeMessage
   // Extra argv appended when unsnooze itself launches the agent binary (dead-pane
   // reopen, queued prompts). Space-separated. Lets a revived session match the
   // user's normal launch mode — shell aliases don't apply to direct spawns
   // (e.g. claude users who always launch with --dangerously-skip-permissions).
-  resumeExtraArgs: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '' },
+  resumeExtraArgs: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '', cursor: '' },
   // Extra argv for launches the USER performs through the shell wrapper — the
   // launch-side twin of resumeExtraArgs. A flag that has to hold for the whole
   // session (claude's --autocompact, which decides when the context window is
   // compacted) is useless if it only applies to revives, because the session
   // that runs out of context is the one the user started.
-  launchExtraArgs: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '' },
-  agents: { claude: true, codex: true, grok: false, qwen: false, kimi: false, opencode: false, agy: false },   // experimental agents default off
+  launchExtraArgs: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '', cursor: '' },
+  agents: { claude: true, codex: true, grok: false, qwen: false, kimi: false, opencode: false, agy: false, cursor: false },   // experimental agents default off
 };
 
 // Env override per key. Booleans accept 1/0, true/false, on/off, yes/no.
@@ -90,6 +90,7 @@ const ENV_NAMES = {
   'resumeMessages.kimi': 'UNSNOOZE_RESUME_MESSAGE_KIMI',
   'resumeMessages.opencode': 'UNSNOOZE_RESUME_MESSAGE_OPENCODE',
   'resumeMessages.agy': 'UNSNOOZE_RESUME_MESSAGE_AGY',
+  'resumeMessages.cursor': 'UNSNOOZE_RESUME_MESSAGE_CURSOR',
   'resumeExtraArgs.claude': 'UNSNOOZE_RESUME_EXTRA_ARGS_CLAUDE',
   'resumeExtraArgs.codex': 'UNSNOOZE_RESUME_EXTRA_ARGS_CODEX',
   'resumeExtraArgs.grok': 'UNSNOOZE_RESUME_EXTRA_ARGS_GROK',
@@ -97,6 +98,7 @@ const ENV_NAMES = {
   'resumeExtraArgs.kimi': 'UNSNOOZE_RESUME_EXTRA_ARGS_KIMI',
   'resumeExtraArgs.opencode': 'UNSNOOZE_RESUME_EXTRA_ARGS_OPENCODE',
   'resumeExtraArgs.agy': 'UNSNOOZE_RESUME_EXTRA_ARGS_AGY',
+  'resumeExtraArgs.cursor': 'UNSNOOZE_RESUME_EXTRA_ARGS_CURSOR',
   'launchExtraArgs.claude': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_CLAUDE',
   'launchExtraArgs.codex': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_CODEX',
   'launchExtraArgs.grok': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_GROK',
@@ -104,6 +106,7 @@ const ENV_NAMES = {
   'launchExtraArgs.kimi': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_KIMI',
   'launchExtraArgs.opencode': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_OPENCODE',
   'launchExtraArgs.agy': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_AGY',
+  'launchExtraArgs.cursor': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_CURSOR',
   'agents.claude': 'UNSNOOZE_AGENT_CLAUDE',
   'agents.codex': 'UNSNOOZE_AGENT_CODEX',
   'agents.grok': 'UNSNOOZE_AGENT_GROK',
@@ -111,6 +114,7 @@ const ENV_NAMES = {
   'agents.kimi': 'UNSNOOZE_AGENT_KIMI',
   'agents.opencode': 'UNSNOOZE_AGENT_OPENCODE',
   'agents.agy': 'UNSNOOZE_AGENT_AGY',
+  'agents.cursor': 'UNSNOOZE_AGENT_CURSOR',
 };
 
 const KNOWN_KEYS = Object.keys(ENV_NAMES);

package/src/watcher.js

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

package/src/watchers/codex.js

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