unsnooze 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.6.0 — 2026-07-12
+
+- **Stale-workspace guard** (`workspaceGuard`: `off` | `inform` | `pause`,
+  default `inform`): the repo's HEAD + dirty state are fingerprinted when a
+  session stops and re-checked at wake. `inform` resumes with a "workspace
+  changed while you slept — re-read before acting" note in the wake message;
+  `pause` holds the session (desktop notification, `workspace changed` marker
+  in status) until `unsnooze resume-now`, which prints the diff stat first.
+  Non-git directories are unaffected. Suggested by r/codex feedback.
+
+## 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

package/README.md

@@ -133,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
@@ -154,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. |
+| `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. |
 | `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
@@ -177,6 +179,11 @@ all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
   block the CLI).
 - **Overload ≠ limit**: 5xx/529/429 transient errors take a seconds-scale
   backoff path ([30,60,120,240,300]s ± jitter) and never enter the ledger.
+- **Stale-workspace guard**: the repo's HEAD + dirty state are fingerprinted
+  when a session stops. If another session (or you) changed the repo before
+  the wake, the resumed agent is told to re-read before acting — or, with
+  `workspaceGuard=pause`, the session is held and `unsnooze resume-now`
+  shows the diff first.
 
 ## Requirements
 
@@ -226,12 +233,21 @@ verifies the limit actually lifted. It replaces the 4am alarm, not the limit.
 
 ### How do I update, and how do I know when to?
 
-`npm i -g unsnooze`. unsnooze checks the npm registry at most once a day and
+`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`.
 
+### What if another session changed the repo while one was stopped?
+
+unsnooze fingerprints the workspace (HEAD + uncommitted state) at stop time
+and re-checks at wake. By default the session still resumes, but the wake
+message includes what changed ("HEAD abc1234 → def5678 — re-read before
+continuing"). Set `workspaceGuard` to `pause` to hold such sessions for a
+manual `unsnooze resume-now` (which prints the diff stat), or `off` to
+disable the check.
+
 ### 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

package/bin/unsnooze.js

@@ -82,6 +82,10 @@ 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();
@@ -116,6 +120,7 @@ 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

package/package.json

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

package/src/cli.js

@@ -33,8 +33,11 @@ export function cmdStatus() {
     const msg = s.resumeMessage
       ? ` · msg: "${s.resumeMessage.length > 44 ? s.resumeMessage.slice(0, 44) + '…' : s.resumeMessage}"`
       : '';
+    const hold = s.workspaceHold
+      ? ` · workspace changed (${s.holdReason ?? '?'}) — resume-now to wake`
+      : '';
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              pane ${s.pane ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}`);
+    console.log(`              pane ${s.pane ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${hold}`);
   }
   return 0;
 }
@@ -46,15 +49,30 @@ function selectKeys(state, idOrAll, statuses = ['stopped']) {
   return match.map(s => s.key);
 }
 
-export function cmdResumeNow(idOrAll) {
+export async function cmdResumeNow(idOrAll) {
   const state = readState();
   const keys = selectKeys(state, idOrAll);
   if (keys.length === 0) { console.log('unsnooze: no matching stopped sessions.'); return 1; }
+  // The commenter's "show me the diff": held records print what moved since
+  // the stop-time baseline before we wake them. Best-effort, never blocking.
+  for (const key of keys) {
+    const rec = state.sessions[key];
+    if (rec?.workspaceHold && rec.workspace?.head && rec.cwd) {
+      try {
+        const { execFileSync } = await import('node:child_process');
+        const stat = execFileSync('git', ['-C', rec.cwd, 'diff', '--stat', `${rec.workspace.head}..HEAD`],
+          { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).toString().trim();
+        if (stat) console.log(`unsnooze: workspace changes since ${key.slice(0, 12)} stopped:\n${stat}`);
+      } catch { /* repo gone or git unhappy — proceed anyway */ }
+    }
+  }
   updateState(s => {
     for (const key of keys) {
       if (s.sessions[key]) {
         s.sessions[key].resetAt = Date.now();
-        s.sessions[key].manual = true;   // explicit user action beats autoResume=off
+        s.sessions[key].manual = true;   // explicit user action beats autoResume=off + workspaceGuard
+        delete s.sessions[key].workspaceHold;
+        delete s.sessions[key].holdReason;
       }
     }
   });

package/src/resumer.js

@@ -18,6 +18,7 @@ import { getAgent } from './agents/index.js';
 import { parseResetTime, resetAtMs } from './time-parser.js';
 import { readState, updateState, setStatus, dueSessions, activeStopped } from './state.js';
 import { getConfig, resolveResumeMessage } from './settings.js';
+import { workspaceFingerprint, workspaceChanged, describeChange } from './workspace.js';
 import { notify } from './notify.js';
 import { UNSNOOZE_BIN } from './spawn.js';
 import { makeLogger } from './logger.js';
@@ -51,7 +52,8 @@ export function releaseSingleton() {
 // it's off. Stops stay tracked either way.
 export function dueForDispatch(now = Date.now()) {
   const auto = getConfig('autoResume');
-  return dueSessions(now).filter(s => auto || s.manual);
+  // workspaceHold: guarded sessions wait for an explicit resume-now (manual).
+  return dueSessions(now).filter(s => (auto || s.manual) && (!s.workspaceHold || s.manual));
 }
 
 function shellQuote(arg) {
@@ -69,7 +71,7 @@ function selfCommand() {
 
 // Decide how to act on one due record. Pure-ish; tmux injectable.
 // Returns: 'sent' | 'reopened' | 'deferred' | 'skip' | 'failed'
-export async function dispatchOne(rec, { tmux = realTmux, resumeMessage, selfCmd = selfCommand() } = {}) {
+export async function dispatchOne(rec, { tmux = realTmux, resumeMessage, selfCmd = selfCommand(), fingerprint = workspaceFingerprint, notifier = notify } = {}) {
   const key = rec.key;
   const agent = getAgent(rec.agent);
   // Wake-message precedence: per-session (`unsnooze message <id> "..."`) →
@@ -77,6 +79,24 @@ export async function dispatchOne(rec, { tmux = realTmux, resumeMessage, selfCmd
   // both the live-pane sendText and the argv reopen path.
   resumeMessage = rec.resumeMessage ?? resumeMessage ?? resolveResumeMessage(agent.id);
 
+  // Stale-workspace guard: another session (or a human) may have moved the
+  // repo while this one slept. Manual resumes (resume-now) always proceed.
+  const guardMode = getConfig('workspaceGuard');
+  if (rec.workspace && guardMode !== 'off' && !rec.manual) {
+    const change = workspaceChanged(rec, fingerprint(rec.cwd));
+    if (change) {
+      const desc = describeChange(change);
+      if (guardMode === 'pause') {
+        setStatus(key, 'stopped', { workspaceHold: true, holdReason: desc });
+        notifier('unsnooze: session held', `${rec.cwd}: workspace changed while stopped (${desc}) — run: unsnooze resume-now`);
+        log(`${key}: workspace changed (${desc}) — held (workspaceGuard=pause)`);
+        return 'held';
+      }
+      resumeMessage += `\n\nHeads up: this workspace changed while the session was stopped (${desc}). Re-read the current state of the repo before continuing.`;
+      log(`${key}: workspace changed (${desc}) — informing agent in the wake message`);
+    }
+  }
+
   // Live-pane path: only if the pane still exists AND the agent CLI is its
   // foreground command (pane ids get recycled — never inject into a random
   // program).

package/src/settings.js

@@ -18,6 +18,7 @@ export const DEFAULTS = {
   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
+  workspaceGuard: 'inform', // repo changed while stopped: off | inform | pause
   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
@@ -30,6 +31,7 @@ const ENV_NAMES = {
   notifications: 'UNSNOOZE_NOTIFICATIONS',
   guiWatch: 'UNSNOOZE_GUI_WATCH',
   updateCheck: 'UNSNOOZE_UPDATE_CHECK',
+  workspaceGuard: 'UNSNOOZE_WORKSPACE_GUARD',
   resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
   'resumeMessages.claude': 'UNSNOOZE_RESUME_MESSAGE_CLAUDE',
   'resumeMessages.codex': 'UNSNOOZE_RESUME_MESSAGE_CODEX',
@@ -41,6 +43,11 @@ const ENV_NAMES = {
 
 const KNOWN_KEYS = Object.keys(ENV_NAMES);
 
+// String settings restricted to a fixed set of values.
+const ENUMS = {
+  workspaceGuard: ['off', 'inform', 'pause'],
+};
+
 function parseBool(raw) {
   if (/^(1|true|on|yes)$/i.test(raw)) return true;
   if (/^(0|false|off|no)$/i.test(raw)) return false;
@@ -98,6 +105,9 @@ export function setConfigValue(key, rawValue) {
     value = b;
   } else {
     value = String(rawValue);
+    if (ENUMS[key] && !ENUMS[key].includes(value)) {
+      throw new Error(`unsnooze: "${key}" must be one of: ${ENUMS[key].join(', ')}`);
+    }
   }
   const config = readFileConfig();
   const parts = key.split('.');

package/src/state.js

@@ -13,6 +13,7 @@ import {
   STATE_DIR, STATE_FILE, LOCK_DIR, STALE_LOCK_MS, PRUNE_AFTER_MS,
   DEDUPE_WINDOW_MS,
 } from './config.js';
+import { workspaceFingerprint } from './workspace.js';
 import { makeLogger } from './logger.js';
 
 const log = makeLogger('state');
@@ -105,6 +106,11 @@ export function upsertSession(record) {
       log(`merged duplicate detection for pane ${record.pane} into ${existingKey}`);
       return state;
     }
+    // Baseline for the stale-workspace guard, captured once at stop time.
+    // (Merged duplicates above keep the ORIGINAL baseline — spread semantics.)
+    if (record.status === 'stopped' && record.workspace === undefined) {
+      record.workspace = workspaceFingerprint(record.cwd);
+    }
     const key = record.sessionId || `pane:${record.pane}:${record.detectedAt}`;
     state.sessions[key] = { ...record, key };
     return state;

package/src/update-check.js

@@ -8,6 +8,7 @@
 // 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';
@@ -75,7 +76,7 @@ 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}) — npm i -g unsnooze · ${RELEASES_URL}`;
+  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.
@@ -113,8 +114,35 @@ export async function runUpdateCheck({ fetcher, notifier = notify, now = Date.no
   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}) — npm i -g unsnooze`);
+    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;
+}

package/src/workspace.js

@@ -0,0 +1,44 @@
+// Stale-workspace guard: fingerprint a repo when a session stops, compare at
+// wake time. If another session (or a human) moved the repo meanwhile, the
+// resumer either warns the agent in the wake message or holds the session,
+// per the `workspaceGuard` setting. Non-git directories fingerprint to null
+// and are never guarded.
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+function git(cwd, args) {
+  return execFileSync('git', ['-C', cwd, ...args], {
+    stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500,
+  }).toString().trim();
+}
+
+export function workspaceFingerprint(cwd) {
+  if (!cwd) return null;
+  try {
+    const head = git(cwd, ['rev-parse', 'HEAD']);
+    const dirty = git(cwd, ['status', '--porcelain']);
+    return { head, dirtyHash: createHash('sha1').update(dirty).digest('hex') };
+  } catch {
+    return null;   // not a git repo / git missing / unreadable — skip the guard
+  }
+}
+
+// null → nothing to report (no baseline, no current, or identical).
+export function workspaceChanged(rec, current) {
+  const before = rec?.workspace;
+  if (!before || !current) return null;
+  if (before.head === current.head && before.dirtyHash === current.dirtyHash) return null;
+  return {
+    oldHead: before.head,
+    newHead: current.head,
+    dirtyChanged: before.dirtyHash !== current.dirtyHash,
+  };
+}
+
+export function describeChange(d) {
+  const parts = [];
+  if (d.oldHead !== d.newHead) parts.push(`HEAD ${d.oldHead.slice(0, 7)} → ${d.newHead.slice(0, 7)}`);
+  if (d.dirtyChanged) parts.push('uncommitted changes differ');
+  return parts.join('; ');
+}