unsnooze 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

package/README.md

@@ -155,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
@@ -178,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
 
@@ -233,6 +239,15 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.5.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/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('; ');
+}