unsnooze 1.16.3 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # Changelog
 
+## 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
+  forever.** The lock around `~/.unsnooze/state.json` treated every `mkdir`
+  failure as contention. `EEXIST` really is contention — someone else holds the
+  lock — but `EACCES` on an unwritable state directory, `EROFS` on a read-only
+  filesystem and `ENOSPC` on a full one are not, and that branch retried with
+  neither a sleep nor a deadline check. Since `mkdir -p` on a directory that
+  already exists succeeds as a no-op, there was nothing to break the cycle:
+  the loop spun at around 70% of a core, ignored `UNSNOOZE_LOCK_TIMEOUT_MS`
+  entirely, and never returned. It took every writer with it — the daemon, any
+  CLI command, and the StopFailure hook that runs *inside* your agent. unsnooze
+  now repairs a state directory it owns and otherwise fails on the deadline with
+  the errno that caused it.
+
+- **Everything under `~/.unsnooze` is now owner-only (0700 / 0600).** The
+  directory was 0755 and every file inside it 0644, so on a shared machine any
+  other local user could read them. That directory holds your ntfy bearer token
+  (`config.json`), the text of queued prompts and the paths they run in
+  (`state.json`), your fleet's ssh destinations and the commands that fetch
+  their passwords (`hosts.json`), a mirror of every remote host's sessions
+  (`fleet-cache.json`), a lease file per pane carrying its working directory
+  (`leases/`), and — for a headless revival — the entire stdout and stderr of
+  an unattended agent run (`headless/*.log`). Every writer now creates its file
+  owner-only and its directory 0700.
+
+  Upgrading an existing install needed more than that, because none of it is
+  something a writer can fix: `mkdir`'s mode is ignored for a directory that
+  already exists, appending to a log reuses the file's inode, and
+  `config.json` and `hosts.json` are written only by `config set` and
+  `hosts add`, so an install that never touches them again would have kept
+  their old mode — and the token in one of them — indefinitely. So a state
+  write repairs the modes directly, walking the `events/`, `leases/`,
+  `mux-sessions/` and `headless/` subdirectories as well as the top-level
+  files. It re-checks on an interval rather than once per process, because
+  `daemon.log` is created by launchd/systemd redirecting the daemon's stdout
+  and can appear after a first pass has already run — in a process that then
+  lives for days. It strips group and other access without touching the
+  owner's own bits, so an executable in there stays executable; it never
+  follows a symlink or a hardlink into a file it is about to change; and it
+  only ever touches unsnooze's own state directory. `unsnooze doctor` reports
+  from the same walk the repair acts on, so the two cannot disagree about what
+  counts as exposed. It is inert on Windows, which has no POSIX mode bits —
+  libuv synthesises them by mirroring the owner's, so every file there reads
+  as world-readable and no `chmod` can change it; access is governed by the
+  profile ACL instead. The same is true of a state directory on a filesystem
+  that does not implement permissions at all — a CIFS or vfat mount, WSL's
+  `drvfs`, a bind mount from a Windows host — and the platform name does not
+  identify those, so unsnooze finds out by attempting the change and looking:
+  a `chmod` that succeeds while the bits stay put means the filesystem has
+  nothing to set, and the directory is left alone rather than rewritten every
+  minute forever. `unsnooze doctor --fix` reports those three outcomes
+  separately, so "could not" is never printed as "did".
+
+  The statusline shim's own drop directory, `~/.claude/unsnooze`, gets the
+  same treatment: it holds your live rate-limit numbers and was created 0755.
+  It is repaired on the shim's next run rather than only for new installs.
+
+  `unsnooze doctor` now also reports anything under the state directory that
+  other users can read, and `doctor --fix` narrows it. That check exists
+  because the repair deliberately ignores a failed `chmod` — crashing every
+  state write on a filesystem that has no usable one would be the worse bug —
+  so something has to be able to tell you it did not take.
+
+  No credential was ever stored in plaintext: a password source is a
+  *reference* to your keychain, environment or secret tool, never the secret.
+  On a single-user machine nothing here was reachable by anyone new.
+
+- **A hostile `session_id` can no longer steer where unsnooze reads or
+  writes.** Three places took that value — which arrives in a payload from the
+  agent — and used it directly as a filename. The opt-in Claude Code statusline
+  shim built its drop filename by concatenating it, so a `/` or a `..` walked
+  the write out of `~/.claude/unsnooze` and over any `.json` file you can
+  write. `transcriptPath`, on the StopFailure hook path that everyone has
+  enabled, composed a transcript path the same way, turning a read of your own
+  transcript into a read of any `.jsonl` you name. And the Kimi adapter probed
+  for a session directory by the same concatenation, which leaked whether an
+  arbitrary path exists. Claude Code sends a uuid, so all three needed a
+  malicious or compromised agent to reach, and the two reads are only ever
+  mined for a timestamp or a boolean — never echoed back. None of them was in
+  a position to know that. All three now require a filename-shaped id and fall
+  back to `unknown` / no-transcript / not-found. If you have the statusline
+  shim installed, re-run `unsnooze usage --install-statusline` to pick up the
+  fix; the other two need nothing.
+
+- **A corrupt `state.json` no longer prints its own first bytes into the log.**
+  The quarantine message included V8's `JSON.parse` error, and V8 embeds a
+  snippet of the input it choked on — so a state file that had been replaced
+  with something else echoed that file's opening characters into
+  `unsnooze.log`. The quarantined file is still kept on disk, and the log still
+  names it and says why.
+
+- **Three narrower lock fixes.** A writer whose stale-lock steal was itself
+  stolen no longer deletes the thief's lock on the way out — it only removes a
+  lock still stamped with its own pid. The steal itself now re-checks that the
+  directory it is about to remove is still the one it judged stale, narrowing
+  a window where two contenders could both decide to steal and the slower one
+  would delete the winner's fresh lock. And a lock is now stolen on age alone
+  once it is very old: liveness was decided by signalling the recorded pid,
+  which cannot tell "unsnooze is still working" from "that number now belongs
+  to some unrelated long-lived process", so a leaked lock whose pid was later
+  recycled wedged every writer permanently, with no recovery but deleting the
+  directory by hand.
+
+  That last one is a trade rather than a free win — stealing from a holder that
+  really is still working puts two writers in the critical section, and one
+  overwrites the other. It is chosen because a permanent wedge is the worse
+  failure, and the exposure is kept small by making sure the lock is only ever
+  held for in-memory work plus a single write: `upsertSession` used to compute
+  its workspace fingerprint inside the lock, which shells out to git, and
+  `execFileSync`'s timeout is a soft bound — it signals the child and then
+  waits for it to actually exit, which a git wedged on a hung network mount
+  never does. That call now happens before the lock is taken, so nothing
+  unbounded runs inside it.
+
+  *Raised in [#17](https://github.com/saaranshM/unsnooze/issues/17). The report
+  also flagged the askpass `command` source as command injection and reading
+  `state.json` as a symlink-following bug; neither is a vulnerability. A
+  `command` source is your own configured command, in the shape git's
+  `credential.helper = !cmd` has always taken, and it can only be set by
+  someone who can already write to your home directory. As for the symlink:
+  reads do follow one — point `state.json` at a file holding valid JSON and
+  its contents are read as state — but planting that link needs write access
+  to a directory that is now 0700, which is not a boundary anyone crosses
+  without already owning the account. The write side is genuinely safe: the
+  quarantine renames the link rather than the file it points at, and a state
+  write replaces the link with a real file, so the target is never truncated
+  or overwritten.*
+
 ## 1.16.3 — 2026-08-22
 
 - **A dashboard left open overnight no longer runs the machine out of memory.**

package/README.md

@@ -13,7 +13,7 @@
 
 [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
@@ -557,11 +575,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. |

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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unsnooze",
-  "version": "1.16.3",
-  "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.18.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/agents/kimi.js

@@ -54,7 +54,15 @@ function sessionsDirFor(cwd, kimiDir) {
   return join(kimiDir, 'sessions', createHash('md5').update(cwd).digest('hex'));
 }
 
+// sessionId comes from a hook payload and is used as a path component here.
+// The result only picks `-r <id>` over `--continue` and the id travels as
+// argv with no shell, so the exposure is an existence oracle rather than a
+// traversal — but it is the same shape as transcriptPath's, and the same
+// filename-shape gate closes it.
+const SAFE_SESSION_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
 function sessionExists(sessionId, kimiDir) {
+  if (!SAFE_SESSION_ID_RE.test(String(sessionId ?? ''))) return false;
   let hashes;
   try { hashes = readdirSync(join(kimiDir, 'sessions')); } catch { return false; }
   return hashes.some(h => existsSync(join(kimiDir, 'sessions', h, sessionId)));

package/src/askpass.js

@@ -3,7 +3,8 @@
 // anywhere. The SERVICE/ACCOUNT/VAR *names* may appear on argv; the secret
 // itself never does — it only ever comes back on stdout/stdin.
 import { execFileSync, spawnSync } from 'node:child_process';
-import { writeFileSync, chmodSync, mkdirSync, renameSync } from 'node:fs';
+import { writeFileSync, chmodSync, renameSync } from 'node:fs';
+import { ensureStateDir } from './config.js';
 import { join } from 'node:path';
 
 export class AuthError extends Error {
@@ -163,7 +164,7 @@ export async function cmdAskpass(args = []) {
 // by Task 5) because ssh controls the helper's argv — it passes only the
 // prompt text, never the host.
 export function ensureAskpassHelper({ platform = process.platform, stateDir, nodePath = process.execPath, scriptPath }) {
-  mkdirSync(stateDir, { recursive: true });
+  ensureStateDir(stateDir);
   if (platform === 'win32') {
     // Native ssh.exe needs a real exe; unix-like win ssh (Git/WSL) accepts a script.
     // The resolution ladder (design §5c) is finalized in Task 7's cross-platform pass;