unsnooze 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.5.0 — 2026-07-12
+
+- **`unsnooze update`**: one command to update unsnooze itself — runs
+  `npm install -g unsnooze@latest` and immediately prints the new version's
+  changelog. Update notices and the daemon toast now say `run: unsnooze
+  update` instead of the raw npm command.
+
+## 1.4.0 — 2026-07-12
+
+- **Update notices**: unsnooze now checks the npm registry (at most once a
+  day, a plain GET with nothing identifying) and tells you when a new version
+  is out — a one-line notice after CLI commands, and a single desktop toast
+  per version from the daemon. After you update, the next command shows a
+  short "what's new" straight from the bundled changelog. Turn it all off
+  with `unsnooze config set updateCheck off`.
+
 ## 1.3.0 — 2026-07-11
 
 - **Per-session wake messages**: `unsnooze message <id|--all> "<text>"` sets a

package/README.md

@@ -9,9 +9,10 @@
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3fb950)](package.json)
 [![license](https://img.shields.io/badge/license-MIT-8b949e)](LICENSE)
 
-**Claude Code · Codex CLI · Grok** — when they hit a usage limit, your session just… stops.<br/>
-unsnooze tracks **every** limit-stopped session across all your projects and
-**wakes each one up in tmux the moment the limit resets.**
+**Claude Code · Codex CLI · Grok** — 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 in tmux the moment the usage limit resets.**
 
 ```sh
 npm install -g unsnooze && unsnooze setup
@@ -132,6 +133,7 @@ unsnooze message <id> "text"    # per-session wake message (--clear to reset)
 unsnooze config list            # settings (see below)
 unsnooze config set <k> <v>     # e.g. autoResume off
 unsnooze logs [-f]              # what unsnooze has been doing
+unsnooze update                 # update unsnooze itself
 unsnooze daemon                 # persistent GUI-session watcher (usually run
                                 # by launchd/systemd via `install --daemon`)
 unsnooze report [agent]         # capture a pane to report an undetected banner
@@ -153,6 +155,7 @@ unsnooze help                   # full command list (also -h / --help)
 | `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` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
 | `agents.claude` / `agents.codex` / `agents.grok` | `true` / `true` / `false` | Which CLIs are guarded. |
+| `updateCheck` | `true` | Daily new-version check (a plain GET to the npm registry, nothing identifying is sent). Notices after commands + one desktop toast per version. |
 
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
 all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
@@ -200,6 +203,42 @@ unsnooze raises **native Windows toasts** through `powershell.exe` (no
 not supported — without tmux there is nothing to watch; unsnooze will tell you
 so and run your CLI unwatched instead of breaking it.
 
+## FAQ
+
+### What does "You've hit your usage limit" mean in Claude Code?
+
+Claude subscription plans meter usage in a rolling 5-hour window plus a weekly
+cap. When either runs out, Claude Code stops mid-task and shows the banner with
+a reset time ("resets 3pm"). Nothing is lost — the session can be resumed with
+`claude --resume <id>` once the limit resets. unsnooze does exactly that,
+automatically, for every stopped session.
+
+### What about Codex — "You've hit your usage limit. Try again at …"?
+
+Same idea: ChatGPT-plan Codex has 5-hour and weekly windows. The Codex TUI
+stays open at the composer after the banner, so unsnooze either types into the
+live pane or reopens the session with `codex resume <id>` at the reset time it
+parsed from the banner.
+
+### Does this get around the rate limit?
+
+No. unsnooze waits for the reset exactly like you would, resumes once, and
+verifies the limit actually lifted. It replaces the 4am alarm, not the limit.
+
+### How do I update, and how do I know when to?
+
+`unsnooze update` (or `npm i -g unsnooze`). unsnooze checks the npm registry at most once a day and
+tells you when a newer version exists (a line after CLI commands, plus one
+desktop notification per version); after updating, the next command shows a
+short "what's new" from the changelog. It's a plain registry GET with nothing
+identifying — turn it off with `unsnooze config set updateCheck off`.
+
+### Does it work if my laptop was asleep or the terminal was closed?
+
+Yes — reset times are stored as absolute timestamps and checked every 30
+seconds, so a laptop that slept through the reset resumes on the next tick,
+and dead panes are reopened by session id in a fresh tmux window.
+
 ## Development
 
 ```sh

package/bin/unsnooze.js

@@ -4,6 +4,24 @@
 
 const [, , cmd, ...rest] = process.argv;
 
+// Only human-facing commands may print update notices — never the wrapper
+// passthrough, hooks, or daemons (their output lands in agent panes/logs).
+const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'help', '-h', '--help', '--help-unsnooze']);
+
+async function maybeUpdateNotices() {
+  try {
+    const { whatsNewNotice, updateNotice, isCacheStale } = await import('../src/update-check.js');
+    const whatsNew = whatsNewNotice();
+    if (whatsNew) console.error(`\n${whatsNew}`);
+    const notice = updateNotice();
+    if (notice) console.error(`\n${notice}`);
+    if (isCacheStale()) {
+      const { spawnDetached } = await import('../src/spawn.js');
+      spawnDetached(['_update-check']);
+    }
+  } catch { /* update UX must never break a command */ }
+}
+
 async function main() {
   switch (cmd) {
     case 'status': {
@@ -64,6 +82,14 @@ async function main() {
       const { runResumer } = await import('../src/resumer.js');
       return runResumer();
     }
+    case 'update': {
+      const { runSelfUpdate } = await import('../src/update-check.js');
+      return runSelfUpdate();
+    }
+    case '_update-check': {
+      const { runUpdateCheck } = await import('../src/update-check.js');
+      return runUpdateCheck();
+    }
     case 'daemon': {
       // Persistent resumer + transcript watcher: detects and revives limit
       // stops from GUI surfaces (VS Code extension, desktop apps) where no
@@ -73,6 +99,11 @@ async function main() {
       const controller = new AbortController();
       process.on('SIGTERM', () => controller.abort());
       process.on('SIGINT', () => controller.abort());
+      // Daily update check from the daemon: GUI-only users never run CLI
+      // commands, so this is what gets them the "new version" desktop toast.
+      const { spawnDetached } = await import('../src/spawn.js');
+      spawnDetached(['_update-check']);
+      setInterval(() => spawnDetached(['_update-check']), 24 * 3_600_000).unref();
       return runResumer({ persistent: true, watcher: createWatcher(), signal: controller.signal });
     }
     case 'help':
@@ -89,11 +120,12 @@ Usage:
   unsnooze cancel [id|--all]       stop tracking session(s)
   unsnooze message <id|--all> <t>  set a per-session wake message (--clear to reset)
   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 tmux needed to
                                    detect; revival still opens in tmux
   unsnooze config [list|get|set]   view or change settings (toggles, global +
-                                   per-agent resume messages)
+                                   per-agent resume messages, updateCheck)
   unsnooze setup                   interactive setup wizard (agents + toggles)
   unsnooze install [--yes]         wire up shell wrappers + hooks (non-interactive)
   unsnooze uninstall [--purge]     remove wrappers + hooks (and state with --purge)
@@ -111,5 +143,7 @@ Usage:
   }
 }
 
-main().then(code => { process.exitCode = typeof code === 'number' ? code : 0; })
-  .catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });
+main().then(async code => {
+  if (USER_FACING.has(cmd)) await maybeUpdateNotices();
+  process.exitCode = typeof code === 'number' ? code : 0;
+}).catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "unsnooze",
-  "version": "1.3.0",
-  "description": "Wakes every limit-stopped AI coding session (Claude Code, Codex CLI, Grok) in tmux the moment the usage limit resets.",
+  "version": "1.5.0",
+  "description": "Auto-resume Claude Code, Codex CLI & Grok sessions in tmux when the usage limit (5-hour or weekly) resets. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
+    "claude",
     "claude-code",
     "codex",
     "codex-cli",
+    "openai",
+    "anthropic",
     "grok",
     "usage-limit",
+    "usage limit",
     "rate-limit",
+    "rate limit",
+    "5-hour limit",
     "auto-resume",
+    "auto-retry",
+    "resume",
+    "retry",
     "tmux",
     "ai-agents",
+    "agentic-coding",
     "cli"
   ],
   "author": "Saaransh Menon <saaransh.dev2811@gmail.com>",

package/src/settings.js

@@ -17,6 +17,7 @@ export const DEFAULTS = {
   menuAutoAnswer: true,    // may unsnooze drive Claude's limit menu (send keys)?
   notifications: true,     // desktop notifications on detect/resume
   guiWatch: true,          // daemon watches transcripts/rollouts for GUI-session stops
+  updateCheck: true,       // daily registry version check + update notices/toast
   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: '' },  // per-agent override; '' = use resumeMessage
   agents: { claude: true, codex: true, grok: false },   // grok is experimental
@@ -28,6 +29,7 @@ const ENV_NAMES = {
   menuAutoAnswer: 'UNSNOOZE_MENU_AUTO_ANSWER',
   notifications: 'UNSNOOZE_NOTIFICATIONS',
   guiWatch: 'UNSNOOZE_GUI_WATCH',
+  updateCheck: 'UNSNOOZE_UPDATE_CHECK',
   resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
   'resumeMessages.claude': 'UNSNOOZE_RESUME_MESSAGE_CLAUDE',
   'resumeMessages.codex': 'UNSNOOZE_RESUME_MESSAGE_CODEX',

package/src/state.js

@@ -96,6 +96,9 @@ export function upsertSession(record) {
         ...record,
         // Never downgrade a known sessionId to null.
         sessionId: record.sessionId || existing.sessionId,
+        // A detection that races an in-flight resume must not flip the record
+        // back to 'stopped' — the post-resume verify pass owns that outcome.
+        status: existing.status === 'resuming' ? existing.status : record.status,
         key: existingKey,
       };
       state.sessions[existingKey] = merged;
@@ -114,8 +117,11 @@ function findDuplicate(state, record) {
     // Same sessionId living under a pane-based key (a scrape record that later
     // learned its id through a merge).
     if (record.sessionId && s.sessionId === record.sessionId) return key;
+    // 'resuming' counts too: while the resumer types into a pane, a scrape can
+    // still see the banner for a few hundred ms — that must not fork a second
+    // record (it would double-resume the session).
     if (s.pane && s.pane === record.pane
-      && s.status === 'stopped'
+      && (s.status === 'stopped' || s.status === 'resuming')
       && Math.abs((s.detectedAt || 0) - record.detectedAt) < DEDUPE_WINDOW_MS) {
       return key;
     }

package/src/update-check.js

@@ -0,0 +1,148 @@
+// Update notifications. npm can't push updates, so the CLI nudges:
+//   - user-facing commands print a one-line notice (from CACHE only — the
+//     registry fetch happens in a detached `_update-check`, never inline)
+//   - the daemon fires ONE desktop toast per new version
+//   - after the user updates, the next command shows "what's new" straight
+//     from the CHANGELOG.md bundled in the npm tarball (zero network)
+// All of it is gated on the `updateCheck` setting / UNSNOOZE_UPDATE_CHECK.
+// The check is a plain GET to registry.npmjs.org — nothing identifying.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfig } from './settings.js';
+import { notify } from './notify.js';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+export const PKG_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version;
+
+const CACHE_FILE = () => join(process.env.UNSNOOZE_STATE_DIR || join(process.env.HOME || '', '.unsnooze'), 'update-check.json');
+const CHECK_INTERVAL_MS = 24 * 3_600_000;
+const RELEASES_URL = 'https://github.com/saaranshM/unsnooze/releases';
+
+export function readCache() {
+  try { return JSON.parse(readFileSync(CACHE_FILE(), 'utf-8')); } catch { return {}; }
+}
+
+export function writeCache(patch) {
+  const merged = { ...readCache(), ...patch };
+  const path = CACHE_FILE();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.update-check.tmp.${process.pid}`);
+  writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n');
+  renameSync(tmp, path);
+  return merged;
+}
+
+// Plain x.y.z compare. We never publish prereleases; anything that isn't
+// three numbers loses (a garbage registry response must never nag).
+export function isNewer(candidate, current) {
+  const parse = v => (typeof v === 'string' && /^\d+\.\d+\.\d+$/.test(v)) ? v.split('.').map(Number) : null;
+  const a = parse(candidate);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+export function isCacheStale(now = Date.now()) {
+  return now - (readCache().lastCheckedAt || 0) > CHECK_INTERVAL_MS;
+}
+
+export async function fetchLatest({ fetcher = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetcher('https://registry.npmjs.org/unsnooze/latest', {
+        signal: ctrl.signal, headers: { accept: 'application/json' },
+      });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return typeof body?.version === 'string' ? body.version : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;   // offline, timeout, bad JSON — never the CLI's problem
+  }
+}
+
+// Cache-only, instant. Printed to stderr after user-facing commands.
+export function updateNotice(pkgVersion = PKG_VERSION) {
+  if (!getConfig('updateCheck')) return null;
+  const { latest } = readCache();
+  if (!latest || !isNewer(latest, pkgVersion)) return null;
+  return `unsnooze ${latest} is available (you have ${pkgVersion}) — run: unsnooze update · ${RELEASES_URL}`;
+}
+
+// The "## <version>" block from the CHANGELOG.md that ships in the tarball.
+export function changelogSection(version, maxLines = 6) {
+  try {
+    const lines = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf-8').split('\n');
+    const start = lines.findIndex(l => l.startsWith(`## ${version}`));
+    if (start === -1) return null;
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex(l => l.startsWith('## '));
+    const section = rest.slice(0, end === -1 ? undefined : end)
+      .filter(l => l.trim() !== '')
+      .slice(0, maxLines);
+    return section.length ? section.join('\n') : null;
+  } catch {
+    return null;
+  }
+}
+
+// Once after an update: "you're now on X, here's what changed."
+export function whatsNewNotice(pkgVersion = PKG_VERSION) {
+  if (!getConfig('updateCheck')) return null;
+  const { lastRunVersion } = readCache();
+  if (lastRunVersion === pkgVersion) return null;
+  writeCache({ lastRunVersion: pkgVersion });
+  if (!lastRunVersion) return null;   // first ever run — nothing to announce
+  const section = changelogSection(pkgVersion);
+  return `Updated to ${pkgVersion}.` + (section ? ` What's new:\n${section}` : ` ${RELEASES_URL}/tag/v${pkgVersion}`);
+}
+
+// The detached `_update-check`: fetch, cache, toast once per new version.
+export async function runUpdateCheck({ fetcher, notifier = notify, now = Date.now() } = {}) {
+  if (!getConfig('updateCheck')) return 0;
+  const latest = await fetchLatest({ fetcher });
+  if (!latest) return 0;
+  const cache = writeCache({ lastCheckedAt: now, latest });
+  if (isNewer(latest, PKG_VERSION) && cache.notifiedVersion !== latest) {
+    notifier('unsnooze update available', `${latest} is out (you have ${PKG_VERSION}) — run: unsnooze update`);
+    writeCache({ notifiedVersion: latest });
+  }
+  return 0;
+}
+
+// `unsnooze update` — self-update via npm, then show what changed. npm -g
+// overwrites this install in place, so re-reading package.json/CHANGELOG.md
+// after a successful install yields the NEW version's info.
+export function runSelfUpdate({ runner = spawnSync, print = console.log } = {}) {
+  print(`unsnooze ${PKG_VERSION} — updating via npm install -g unsnooze@latest …`);
+  const r = runner('npm', ['install', '-g', 'unsnooze@latest'], { stdio: 'inherit' });
+  if (r.error || r.status !== 0) {
+    print(`unsnooze: update failed (${r.error ? r.error.message : `npm exited ${r.status}`}).`);
+    print('unsnooze: try it manually: npm install -g unsnooze@latest');
+    print('unsnooze: (permission errors usually mean your npm prefix needs sudo or a user-writable prefix)');
+    return r.status || 1;
+  }
+  let newVersion = PKG_VERSION;
+  try {
+    newVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version;
+  } catch { /* moved install dir — the generic message below still holds */ }
+  if (newVersion === PKG_VERSION) {
+    print(`unsnooze: already up to date (${PKG_VERSION}).`);
+  } else {
+    const section = changelogSection(newVersion);
+    print(`unsnooze: updated to ${newVersion}.${section ? ` What's new:\n${section}` : ''}`);
+  }
+  // Don't repeat "what's new" on the next command.
+  writeCache({ lastRunVersion: newVersion });
+  return 0;
+}