unsnooze 1.14.2 → 1.14.3

package/CHANGELOG.md

@@ -1,6 +1,52 @@
 # Changelog
 
-## Unreleased
+## 1.14.3 — 2026-08-08
+
+- **Upgrades now reach running watchers.** A per-pane monitor lives as long as
+  the agent and a transient resumer lives until the reset; neither has a
+  supervisor, and `npm i -g unsnooze` cannot change code a running process has
+  already loaded. A session started before an upgrade therefore kept applying
+  the old rules indefinitely — which is why 1.14.2's resume-lifecycle fix could
+  be installed and still change nothing on a long-lived pane. Both processes now
+  notice that the package changed underneath them, hand off to a replacement on
+  the fresh code, and stand down. Sessions launched under 1.14.2 or earlier need
+  one restart to pick this up; after that, upgrades propagate on their own.
+- **Hand-offs are verified, never assumed.** `spawn` resolves the node binary,
+  which exists regardless of the package, so a tree caught mid-swap returns a
+  healthy-looking pid for a child that is already dead. The hand-off now checks
+  that the entry point exists before starting anything, and that the replacement
+  survived startup before standing down. Either check failing keeps the old
+  process watching — a stale watcher beats no watcher.
+- **A manually run daemon no longer dies on upgrade.** `unsnooze daemon` started
+  from a shell has nothing to restart it, so exiting on version skew ended GUI
+  watching silently. It now detects whether launchd/systemd is actually
+  supervising it: supervised, it exits and returns on fresh code; unsupervised,
+  it warns once and keeps watching. The 15-minute detection interval is
+  unchanged — a tighter loop raises the odds of restarting into a half-installed
+  package.
+- **The daemon PATH self-heal actually heals.** The 1.12 repair regenerated the
+  autostart unit from the PATH of whichever process called it, and the only
+  caller is the daemon itself — whose PATH is the minimal one launchd and
+  systemd provide. It wrote the broken PATH straight back, then, because the
+  check only asked whether a PATH block was *present*, treated the job as done
+  forever. Observed live: a daemon running with `PATH=/usr/bin:/bin:/usr/sbin:/sbin`
+  while tmux sat in `/opt/homebrew/bin`, so every GUI revival failed with ENOENT.
+  The heal now asks the login shell for a usable PATH and rewrites the unit only
+  when the result can actually find the multiplexer *and* differs from what is
+  already there — rewriting reloads the unit, which kills the calling daemon, so
+  a heal that cannot improve anything must do nothing.
+- **`unsnooze doctor` reports a daemon that cannot reach its multiplexer**, and
+  `--fix` repairs it. This was previously invisible, because doctor probes tmux
+  from your shell's PATH rather than the daemon's.
+- **Version stamps in the log.** The monitor and resumer record which build they
+  are running as they start, so a pasted log answers "is this process even on
+  the new code" without further diagnosis.
+- Internal: one shared `pidAlive` now backs the resumer's lock hygiene, the
+  dashboard, and the hand-off. It rejects pid 0, which `kill(0, 0)` reports as
+  alive because that signals the caller's own process group — a lock file
+  holding `0` could otherwise be honored forever. Writing an autostart unit
+  outside the live location no longer activates it: every unit carries the same
+  label, so loading a copy hijacks the real job instead of adding a second one.
 
 ## 1.14.2 — 2026-08-06
 

package/bin/unsnooze.js

@@ -256,10 +256,33 @@ async function main() {
       }
       // Version-skew guard: when npm swaps the package underneath us, exit
       // cleanly so launchd/systemd restart the daemon on the fresh code.
+      // Interval stays at 15 minutes on purpose — a tighter loop raises the
+      // odds of restarting INTO a half-installed package, which is the
+      // crash-loop the unit throttles exist to survive.
+      // Exiting is only safe under a supervisor. `unsnooze daemon` run from a
+      // shell has nothing to restart it, so there it warns and keeps watching
+      // rather than ending GUI watching silently.
       const updMod = await safeImport('../src/update-check.js');
+      const notifyMod = await safeImport('../src/notify.js');
       if (updMod?.hasVersionSkew) {
+        let warnedSkew = false;
         setInterval(() => {
-          if (updMod.hasVersionSkew()) controller.abort();
+          const action = updMod.daemonSkewAction({
+            skewed: updMod.hasVersionSkew(),
+            // Unknown means assume supervised: that is how the daemon is
+            // installed for all but a handful of users, and it preserves the
+            // long-standing behavior when install.js could not be loaded.
+            supervised: installMod?.isSupervised ? installMod.isSupervised() : true,
+            alreadyWarned: warnedSkew,
+          });
+          if (action === 'restart') controller.abort();
+          else if (action === 'warn') {
+            warnedSkew = true;
+            const msg = 'package was upgraded on disk but this daemon is not supervised — '
+              + 'still running the old code; restart it to pick up the new version';
+            loggerMod?.log('daemon', msg);
+            notifyMod?.notify('unsnooze needs a restart', msg, { priority: 4 });
+          }
         }, 15 * 60_000).unref();
       }
       // Daily update check from the daemon: GUI-only users never run CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.14.2",
+  "version": "1.14.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—across tmux, Zellij, VS Code, and desktop apps.",
   "keywords": [
     "claude",

package/src/dashboard/data.js

@@ -14,11 +14,7 @@ import {
 import { listOwnedSessions } from '../reap.js';
 import { runDoctor } from '../doctor.js';
 import { fetchFleet, readHosts } from '../fleet.js';
-
-function pidAlive(pid) {
-  if (!pid) return false;
-  try { process.kill(pid, 0); return true; } catch { return false; }
-}
+import { pidAlive } from '../spawn.js';
 
 export function loadStatusSnapshot() {
   const state = readState();

package/src/doctor.js

@@ -138,6 +138,7 @@ export async function runDoctor({
   mux = getMultiplexer(),
   hookInstalled = defaultHookInstalled,
   wrappersInstalled = defaultWrappersInstalled,
+  autostartDir = null,
 } = {}) {
   const findings = [];
 
@@ -204,6 +205,25 @@ export async function runDoctor({
     });
   }
 
+  // The daemon reaches tmux through PATH, and launchd/systemd hand it a
+  // minimal one — so a unit that bakes the wrong PATH revives nothing while
+  // looking perfectly healthy from here. Lazy import: install.js imports this
+  // module, so a static import would cycle (same reason resumer.js defers
+  // prompt-queue.js).
+  try {
+    const { daemonPathBroken } = await import('./install.js');
+    const broken = daemonPathBroken({ platform, dir: autostartDir, muxBin: mux.name || 'tmux' });
+    if (broken) {
+      findings.push({
+        id: 'daemon-path', kind: 'health',
+        title: `daemon autostart cannot find ${broken.muxBin} — every revival will fail`,
+        detail: `  ${broken.unit}\n  baked PATH: ${broken.path}\n`
+          + `  run: unsnooze doctor --fix   (or: unsnooze install --daemon from your shell)`,
+        fix: { action: 'heal-daemon-path', platform, dir: autostartDir },
+      });
+    }
+  } catch { /* best-effort: a PATH check must never break doctor */ }
+
   findings.push({
     id: 'daemon', kind: 'info',
     title: daemonRunning() ? 'resumer/daemon: running' : 'resumer/daemon: not running (starts on the next limit stop)',
@@ -225,6 +245,9 @@ export async function applyFixes(report, {
   kill = defaultKill,
   runner = defaultRunner,
   now = Date.now(),
+  resolvePath = undefined,
+  currentPath = undefined,
+  activate = undefined,
 } = {}) {
   const actions = [];
   for (const finding of report.findings) {
@@ -244,6 +267,23 @@ export async function applyFixes(report, {
         actions.push({ action: 'removed-unit', unit });
         log(`doctor: removed csg autostart ${unit}`);
       }
+    } else if (fix.action === 'heal-daemon-path') {
+      const { healDaemonAutostart } = await import('./install.js');
+      const healed = healDaemonAutostart({
+        platform: fix.platform, dir: fix.dir,
+        ...(resolvePath ? { resolvePath } : {}),
+        ...(currentPath !== undefined ? { currentPath } : {}),
+        ...(activate ? { activate } : {}),
+      });
+      // healDaemonAutostart declines when it has no better PATH to offer —
+      // that refusal is the crash-loop guard, so surface it rather than
+      // claiming a repair that did not happen.
+      if (healed) {
+        actions.push({ action: 'healed-daemon-path', unit: healed });
+        log(`doctor: rewrote ${healed} with a working PATH`);
+      } else {
+        actions.push({ action: 'error', detail: 'could not determine a PATH that finds the multiplexer — run `unsnooze install --daemon` from your shell' });
+      }
     } else if (fix.action === 'archive-dir') {
       let target = `${fix.dir}.bak`;
       if (existsSync(target)) target = `${fix.dir}.bak.${now}`;

package/src/install.js

@@ -10,7 +10,7 @@
 
 import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
-import { homedir } from 'node:os';
+import { homedir, userInfo } from 'node:os';
 import { join, dirname } from 'node:path';
 import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
 import { getConfig, configFileExists } from './settings.js';
@@ -149,6 +149,23 @@ export function installZshrcBlock(content, agents = ['claude']) {
 
 export const DAEMON_LABEL = 'com.unsnooze.daemon';
 
+// Is this process running under the supervisor we install, rather than from
+// somebody's shell? It decides whether exiting is safe: a supervised daemon
+// that exits on version skew comes straight back on fresh code, while an
+// unsupervised one exits into nothing and GUI watching stops silently.
+//
+// Both markers are injected by the supervisor itself and were read off real
+// processes rather than inferred: launchd sets XPC_SERVICE_NAME to the job
+// label for its jobs (an interactive shell reports the literal '0'), and
+// systemd sets a per-invocation INVOCATION_ID for every unit it starts.
+// Matching the exact label, not merely "some launchd job", keeps an unrelated
+// XPC service from being mistaken for our supervisor.
+export function isSupervised({ platform = process.platform, env = process.env } = {}) {
+  if (platform === 'darwin') return env.XPC_SERVICE_NAME === DAEMON_LABEL;
+  if (platform === 'linux') return typeof env.INVOCATION_ID === 'string' && env.INVOCATION_ID !== '';
+  return false;   // nowhere else do we install a supervisor to be run by
+}
+
 // Env overrides keep tests/e2e away from the real LaunchAgents / systemd dirs.
 function autostartDir(platform) {
   if (platform === 'darwin') {
@@ -157,6 +174,78 @@ function autostartDir(platform) {
   return process.env.UNSNOOZE_SYSTEMD_USER_DIR || join(homedir(), '.config', 'systemd', 'user');
 }
 
+// The one place that knows what our unit file is called on each platform.
+export function autostartUnitPath({ platform = process.platform, dir = null } = {}) {
+  const base = dir || autostartDir(platform);
+  if (platform === 'darwin') return join(base, `${DAEMON_LABEL}.plist`);
+  if (platform === 'linux') return join(base, 'unsnooze.service');
+  return null;
+}
+
+// Can this PATH string actually find `bin`? The daemon reaches tmux through
+// PATH (`execFile('tmux', …)`), so a unit whose baked PATH fails this test
+// cannot revive anything — every call dies with ENOENT. Pure and synchronous
+// on purpose: this decides whether to rewrite-and-reload a unit, and that
+// decision must be deterministic.
+export function pathResolves(pathStr, bin) {
+  if (typeof pathStr !== 'string' || pathStr === '') return false;
+  return pathStr.split(':').some(d => d && existsSync(join(d, bin)));
+}
+
+function xmlUnescape(s) {
+  return s.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+}
+
+// The PATH a unit currently bakes in, or null when it bakes none.
+function bakedUnitPath(content, platform) {
+  if (platform === 'darwin') {
+    const m = content.match(/<key>PATH<\/key>\s*<string>([^<]*)<\/string>/);
+    return m ? xmlUnescape(m[1]) : null;
+  }
+  const m = content.match(/^Environment="PATH=(.*)"$/m);
+  return m ? m[1].replace(/%%/g, '%') : null;
+}
+
+function defaultLoginPathRunner(cmd, args, opts) {
+  return execFileSync(cmd, args, opts);
+}
+
+// Ask the user's login shell what PATH it builds. This exists because the only
+// caller of the self-heal is the daemon itself, and a daemon's PATH is the
+// launchd/systemd minimal one — the very thing being repaired. Reading
+// process.env.PATH there just writes the breakage back.
+//
+// PATH is stripped from the child env so the login files construct it fresh
+// rather than appending to the broken value we inherited. Failure returns null:
+// a bad guess is worse than leaving the unit alone.
+export function resolveLoginPath({
+  shell = process.env.SHELL || userInfo().shell,
+  runner = defaultLoginPathRunner,
+  timeoutMs = 3000,
+} = {}) {
+  if (!shell) return null;
+  try {
+    const { PATH, ...env } = process.env;   // eslint-disable-line no-unused-vars
+    const out = runner(shell, ['-lc', 'echo $PATH'], {
+      encoding: 'utf-8', timeout: timeoutMs, env, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const path = String(out || '').trim();
+    return path || null;
+  } catch {
+    return null;   // no shell, slow rc files, non-zero exit — all "no answer"
+  }
+}
+
+// The best PATH we can offer a unit: the caller's own if it already finds the
+// binary (the `unsnooze setup`-from-a-shell case), otherwise whatever the login
+// shell reports. null means we have nothing better to write.
+function bestUnitPath({ currentPath, resolvePath, muxBin }) {
+  if (pathResolves(currentPath, muxBin)) return currentPath;
+  const fresh = resolvePath();
+  return fresh && pathResolves(fresh, muxBin) ? fresh : null;
+}
+
 export function launchdPlist({
   nodeBin = process.execPath, unsnoozeBin = UNSNOOZE_BIN,
   logFile = join(STATE_DIR, 'daemon.log'),
@@ -227,22 +316,31 @@ function defaultActivate(cmd, args) {
   }
 }
 
-export function installDaemonAutostart({ platform = process.platform, dir = null, activate = defaultActivate } = {}) {
+export function installDaemonAutostart({
+  platform = process.platform, dir = null, activate = defaultActivate, path = undefined,
+} = {}) {
+  const target = autostartUnitPath({ platform, dir });
+  if (!target) return null;   // native Windows: no supported multiplexer to revive into
+  // Safety interlock. Every unit we generate carries the SAME label, so running
+  // the real launchctl/systemctl against a unit written somewhere else (a test
+  // fixture, a staging copy) does not create a second job — it HIJACKS the
+  // user's live one, leaving it pointed at a directory that may not outlive the
+  // caller. So the real activator only ever runs for the unit path this
+  // platform actually uses; an injected activator is always honored, since a
+  // caller that supplied one has said what it wants to happen.
+  const act = (activate === defaultActivate && target !== autostartUnitPath({ platform }))
+    ? () => true
+    : activate;
   if (platform === 'darwin') {
-    const target = join(dir || autostartDir(platform), `${DAEMON_LABEL}.plist`);
-    atomicWrite(target, launchdPlist());
-    activate('launchctl', ['unload', target]);   // reload cleanly if already loaded
-    activate('launchctl', ['load', '-w', target]);
+    atomicWrite(target, launchdPlist(path ? { path } : {}));
+    act('launchctl', ['unload', target]);   // reload cleanly if already loaded
+    act('launchctl', ['load', '-w', target]);
     return target;
   }
-  if (platform === 'linux') {
-    const target = join(dir || autostartDir(platform), 'unsnooze.service');
-    atomicWrite(target, systemdUnit());
-    activate('systemctl', ['--user', 'daemon-reload']);
-    activate('systemctl', ['--user', 'enable', '--now', 'unsnooze.service']);
-    return target;
-  }
-  return null;   // native Windows: no supported multiplexer to revive into
+  atomicWrite(target, systemdUnit(path ? { path } : {}));
+  act('systemctl', ['--user', 'daemon-reload']);
+  act('systemctl', ['--user', 'enable', '--now', 'unsnooze.service']);
+  return target;
 }
 
 // One-time self-heal for units written before 1.12.0: they carry no PATH, so
@@ -251,20 +349,53 @@ export function installDaemonAutostart({ platform = process.platform, dir = null
 // so the daemon repairs it on startup: regenerate + reload. Reloading kills
 // the calling daemon — by design; the supervisor restarts it under the fixed
 // unit. Returns the healed target, or null when nothing needed healing.
-export function healDaemonAutostart({ platform = process.platform, dir = null, activate = defaultActivate } = {}) {
-  const marker = platform === 'darwin' ? 'EnvironmentVariables' : 'Environment="PATH=';
-  const target = platform === 'darwin'
-    ? join(dir || autostartDir(platform), `${DAEMON_LABEL}.plist`)
-    : platform === 'linux'
-      ? join(dir || autostartDir(platform), 'unsnooze.service')
-      : null;
+// Does an installed unit bake a PATH that cannot reach the multiplexer? This
+// is invisible from a user's shell — `doctor` finds tmux on the rich PATH it
+// inherited and calls the install healthy — so the daemon's OWN baked PATH has
+// to be inspected directly. Returns null when there is nothing to report
+// (no unit, no baked PATH, or a PATH that works).
+export function daemonPathBroken({ platform = process.platform, dir = null, muxBin = 'tmux' } = {}) {
+  const unit = autostartUnitPath({ platform, dir });
+  if (!unit || !existsSync(unit)) return null;   // not a daemon-autostart user
+  let content;
+  try { content = readFileSync(unit, 'utf-8'); } catch { return null; }
+  const baked = bakedUnitPath(content, platform);
+  if (baked == null || pathResolves(baked, muxBin)) return null;
+  return { unit, path: baked, muxBin };
+}
+
+export function healDaemonAutostart({
+  platform = process.platform, dir = null, activate = defaultActivate,
+  resolvePath = resolveLoginPath, muxBin = 'tmux',
+  currentPath = process.env.PATH || '',
+} = {}) {
+  const target = autostartUnitPath({ platform, dir });
   if (!target || !existsSync(target)) return null;   // not a daemon-autostart user
-  try {
-    if (readFileSync(target, 'utf-8').includes(marker)) return null;   // already current
-  } catch {
-    return null;   // unreadable — leave it alone
+  let content;
+  try { content = readFileSync(target, 'utf-8'); } catch { return null; }
+
+  const marker = platform === 'darwin' ? 'EnvironmentVariables' : 'Environment="PATH=';
+  const better = bestUnitPath({ currentPath, resolvePath, muxBin });
+
+  // Pre-1.12 unit: no PATH at all. Always worth healing — but prefer a PATH
+  // that actually works over the caller's, which is minimal when (as always)
+  // the caller is the daemon.
+  if (!content.includes(marker)) {
+    return installDaemonAutostart({ platform, dir, activate, path: better || currentPath });
   }
-  return installDaemonAutostart({ platform, dir, activate });
+
+  // Present but useless. This is the trap the original heal fell into: run
+  // from the daemon, it baked the daemon's own tmux-less PATH back in, and the
+  // marker being present then made it "already current" forever.
+  const baked = bakedUnitPath(content, platform);
+  if (baked == null || pathResolves(baked, muxBin)) return null;   // genuinely fine
+
+  // CRASH-LOOP GUARD. Healing reloads the unit, which kills this daemon; the
+  // supervisor restarts it and we arrive here again. Rewriting without a
+  // strictly better PATH would repeat every 30s forever, which is worse than
+  // the bug. No improvement available → leave it exactly as it is.
+  if (!better || better === baked) return null;
+  return installDaemonAutostart({ platform, dir, activate, path: better });
 }
 
 export function uninstallDaemonAutostart({ platform = process.platform, dir = null, activate = defaultActivate } = {}) {

package/src/launcher.js

@@ -8,7 +8,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { getMultiplexer } from './multiplexer.js';
 import { getAgent } from './agents/index.js';
 import { getConfig } from './settings.js';
-import { spawnDetached } from './spawn.js';
+import { spawnDetached, monitorSpawnArgs } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { createLeaseId, processBirth, writeLease, removeLease } from './lease.js';
 import { SessionCreateError } from './multiplexers/session-name.js';
@@ -79,7 +79,8 @@ export function runLauncher(args, agentId = 'claude') {
     if (typeof mux.stampPaneOwner === 'function') {
       mux.stampPaneOwner(pane, leaseId).catch(() => { /* legacy tmux */ });
     }
-    spawnDetached(['_monitor', mux.name, paneOwner || '', pane, agent.id, leaseId],
+    spawnDetached(
+      monitorSpawnArgs({ muxName: mux.name, paneOwner, pane, agentId: agent.id, leaseId }),
       { UNSNOOZE_CWD: process.cwd() });
     log(`launching ${agent.id} in ${mux.name} ${paneOwner ?? '-'}:${pane}, monitor spawned`);
   } else {

package/src/monitor.js

@@ -24,7 +24,8 @@ import { parseResetTime, resetAtMs, sourceRank } from './time-parser.js';
 import { upsertSession, setStatus, readState, updateState } from './state.js';
 import { prepareCalibrationSample, applyCalibrationToState } from './usage.js';
 import { latestRateLimitFromTranscript } from './watchers/claude.js';
-import { spawnResumerIfNeeded } from './spawn.js';
+import { spawnResumerIfNeeded, spawnDetached, monitorSpawnArgs, UNSNOOZE_BIN } from './spawn.js';
+import { restartOnVersionSkew, hasVersionSkew, PKG_VERSION } from './update-check.js';
 import { makeLogger } from './logger.js';
 import { addressHash, readLease } from './lease.js';
 import { claudeRecordEnv, hasClaudeParentUsageAfter } from './sessions.js';
@@ -37,6 +38,7 @@ export function createMonitor({
   muxName = 'tmux', paneOwner = null, pane, leaseId = null, cwd,
   agent = getAgent('claude'), mux = getMultiplexer(muxName, { owner: paneOwner }),
   scrapeInterval = SCRAPE_INTERVAL_MS, notifier = notify,
+  spawner = spawnDetached, versionSkewed = hasVersionSkew, handoffBin = UNSNOOZE_BIN,
 }) {
   const notifyCtx = { mux: muxName, pane, paneOwner };
   let trackedKey = null;      // state key of the record we created
@@ -239,6 +241,28 @@ export function createMonitor({
       }
     }
 
+    // A monitor is spawned once per pane and lives as long as the agent, so it
+    // routinely outlives an `npm i -g unsnooze`: the package on disk changes,
+    // this process keeps the modules it loaded at launch, and no supervisor
+    // exists to restart it. That is how 1.14.2's stop-completion fix reached a
+    // user's disk without ever reaching the process that completes stops — a
+    // pane launched five days earlier went on applying the deleted rule.
+    // Hand off to a replacement on fresh code and stand down.
+    //
+    // Ordering matters twice over. It runs AFTER the pane/lease checks, so an
+    // upgrade landing as the agent exits does not respawn a watcher onto the
+    // user's bare shell; and BEFORE consumeMarker(), which unlinks the event
+    // file — handing off after that would swallow the pending overload event.
+    if (await restartOnVersionSkew({
+      args: monitorSpawnArgs({ muxName, paneOwner, pane, agentId: agent.id, leaseId }),
+      env: { UNSNOOZE_CWD: cwd },
+      spawner, skewed: versionSkewed, binPath: handoffBin,
+      log: msg => log(`pane ${pane}: ${msg}`),
+    })) {
+      running = false;
+      return;
+    }
+
     const marker = consumeMarker();
     let text;
     try {
@@ -366,7 +390,10 @@ export function createMonitor({
 
   return {
     async run() {
-      log(`monitor started for pane ${pane} (cwd ${cwd})`);
+      // Stamp the build: a monitor can outlive several upgrades, so "which
+      // version is this process actually running" is the first question any
+      // log attachment has to answer.
+      log(`monitor started for pane ${pane} (cwd ${cwd}) — unsnooze ${PKG_VERSION}`);
       while (running) {
         await tick();
         if (!running) break;

package/src/resumer.js

@@ -26,7 +26,8 @@ import { latestRateLimitFromTranscript } from './watchers/claude.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 { UNSNOOZE_BIN, spawnDetached, pidAlive } from './spawn.js';
+import { restartOnVersionSkew, hasVersionSkew, PKG_VERSION } from './update-check.js';
 import { makeLogger } from './logger.js';
 import { createLeaseId, leaseMatches, paneOwnedByRecord } from './lease.js';
 import { autoReapIfEnabled, attachHint } from './reap.js';
@@ -37,10 +38,6 @@ const sleep = ms => new Promise(r => setTimeout(r, ms));
 const MAX_VERIFY_RETRIES = 3;
 const ctxOf = rec => ({ mux: rec.mux, pane: rec.pane, paneOwner: rec.paneOwner });
 
-function pidAlive(pid) {
-  try { process.kill(pid, 0); return true; } catch { return false; }
-}
-
 // Is the lock-holder pid actually an unsnooze resumer? Pids get recycled: a
 // lock naming a live-but-unrelated program would otherwise be honored forever
 // and stops would never dispatch. Lock acquirers are only ever `_resumer` or
@@ -932,6 +929,7 @@ export function routeDispatchOutcome(result, rec, deferCounts, { maxBusyDefers =
 export async function runResumer({
   resolveMux = resolveRecordMux, pollInterval = POLL_INTERVAL_MS,
   persistent = false, watcher = null, signal = null, queueMux = null,
+  spawner = spawnDetached, versionSkewed = hasVersionSkew, handoffBin = UNSNOOZE_BIN,
 } = {}) {
   // A transient hook-spawned resumer may hold the lock right now; a daemon
   // outlives it, so wait for the lock instead of dying. The watcher MUST keep
@@ -951,12 +949,43 @@ export async function runResumer({
     await sleep(pollInterval);
   }
   updateState(state => { state.resumerPid = process.pid; });
-  log(`resumer started (pid ${process.pid}${persistent ? ', persistent' : ''})`);
+  // Stamp the build — a transient resumer waits out the whole reset and can
+  // easily be older than the package on disk. See the monitor's start line.
+  log(`resumer started (pid ${process.pid}${persistent ? ', persistent' : ''}, unsnooze ${PKG_VERSION})`);
   const deferCounts = new Map();
 
   try {
     for (;;) {
       if (signal?.aborted) { log('shutdown requested — resumer exiting'); return 0; }
+
+      // Version-skew hand-off. A transient resumer is spawned at the stop and
+      // waits out the whole reset — hours — so an `npm i -g` landing mid-wait
+      // leaves the process that SENDS THE WAKE running deleted code. Nothing
+      // supervises it, so it replaces itself. The daemon is exempt: launchd/
+      // systemd own its restart and bin/unsnooze.js already aborts it on skew;
+      // forking a rival from under a supervisor would just fight the unit.
+      //
+      // Release the singleton BEFORE the replacement starts. acquireSingleton
+      // honors a live holder, so a child that starts while we still hold the
+      // lock exits on sight and we would end up with no resumer at all.
+      if (!persistent && versionSkewed()) {
+        const handed = await restartOnVersionSkew({
+          args: ['_resumer'], spawner, skewed: () => true, log, binPath: handoffBin,
+          // Released only once the hand-off is actually going ahead — never
+          // for one the pre-flight already ruled out.
+          beforeSpawn: () => {
+            releaseSingleton();
+            updateState(state => { if (state.resumerPid === process.pid) state.resumerPid = null; });
+          },
+        });
+        if (handed) return 0;
+        // Hand-off refused or failed: take the lock back rather than keep
+        // resuming unlocked, where a second resumer could dispatch the same
+        // record. Idempotent when beforeSpawn never ran — we still hold it.
+        acquireSingleton();
+        updateState(state => { state.resumerPid = process.pid; });
+      }
+
       await tickWatcher();
 
       // Pre-wall usage warnings (1.13) — after watcher so samples are fresh.

package/src/spawn.js

@@ -21,7 +21,23 @@ export function spawnDetached(args, env = {}) {
   return child.pid;
 }
 
-function pidAlive(pid) {
+// The one definition of how a per-pane monitor is launched. The launcher uses
+// it to start one; a version-skewed monitor uses it to hand off to its own
+// replacement. Keeping a single builder is what stops the two from drifting —
+// a mismatched respawn would silently watch the wrong pane or, with a null
+// hole in the argv, throw inside child_process and take the watcher with it.
+export function monitorSpawnArgs({ muxName, paneOwner, pane, agentId, leaseId }) {
+  return ['_monitor', muxName, paneOwner || '', pane, agentId, leaseId || ''];
+}
+
+// Signal 0 probes for existence without delivering anything. Shared: the
+// resumer's lock hygiene, the dashboard's liveness column, and the version-skew
+// hand-off all need the same answer.
+export function pidAlive(pid) {
+  // Reject 0 before probing: kill(0, 0) targets our OWN process group and
+  // succeeds, so a garbage lock file holding "0" would read as a live holder
+  // forever. Number.isFinite alone does not catch it.
+  if (!Number.isFinite(pid) || pid <= 0) return false;
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
 

package/src/update-check.js

@@ -7,16 +7,19 @@
 // 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 { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } 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';
+import { UNSNOOZE_BIN, pidAlive } from './spawn.js';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 export const PKG_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version;
 
+const defaultSleep = ms => new Promise(r => setTimeout(r, ms));
+
 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';
@@ -70,6 +73,72 @@ export function hasVersionSkew({ root = ROOT, current = PKG_VERSION } = {}) {
   }
 }
 
+// Skew hand-off for long-lived processes that have NO supervisor: per-pane
+// monitors (spawned once by the launcher, alive as long as the agent) and
+// transient resumers (alive until resetAt — routinely hours). The daemon can
+// simply exit on skew because launchd/systemd bring it back; these cannot, so
+// they must spawn their own replacement on the fresh code and only then stand
+// down. Without this a pane launched before an upgrade keeps deciding with the
+// code it loaded at launch — how 1.14.2's stop-completion fix reached disk on
+// a user's host without ever reaching the process that makes the decision.
+//
+// Returns true only when a replacement is confirmed spawned; the caller stands
+// down on true and keeps running on false. A failed spawn must never take the
+// old process with it — a stale watcher beats no watcher.
+export async function restartOnVersionSkew({
+  args, env = {}, spawner, skewed = hasVersionSkew, log = () => {},
+  binPath = UNSNOOZE_BIN, beforeSpawn = null,
+  confirmDelayMs = 400, alive = pidAlive, sleep = defaultSleep,
+} = {}) {
+  if (!skewed()) return false;
+  // Pre-flight. `npm i -g` can be observed mid-swap: a new, readable
+  // package.json over a tree whose bin/ has not landed yet. Spawning into that
+  // hands off to nothing, so treat it as "not ready" and try again next tick.
+  if (!existsSync(binPath)) {
+    log(`version skew detected but ${binPath} is missing (upgrade in flight) — continuing on old code`);
+    return false;
+  }
+  // Only now may the caller give anything up (the resumer releases its
+  // singleton here) — never for a hand-off that was already impossible.
+  beforeSpawn?.();
+  let pid = null;
+  try {
+    pid = spawner(args, env);
+  } catch (err) {
+    log(`version skew detected but respawn failed (${err.message}) — continuing on old code`);
+    return false;
+  }
+  if (!Number.isFinite(pid) || pid <= 0) {
+    log('version skew detected but respawn returned no pid — continuing on old code');
+    return false;
+  }
+  // Post-flight. A pid is not proof of a running replacement: spawn() resolves
+  // the NODE BINARY, which exists no matter what, so a missing or broken script
+  // still returns a pid and fires no 'error' event — the child is simply dead
+  // by the time we look. Confirm it survived startup before standing down.
+  await sleep(confirmDelayMs);
+  if (!alive(pid)) {
+    log(`version skew: replacement pid ${pid} died on startup — continuing on old code`);
+    return false;
+  }
+  log(`version skew: package replaced on disk — handed off to pid ${pid}, exiting`);
+  return true;
+}
+
+// What a daemon should do when it notices the package changed underneath it.
+// Supervised (launchd/systemd): exit — the supervisor brings it back on fresh
+// code, which is why the unit files use KeepAlive / Restart=always. Anything
+// else — `unsnooze daemon` run straight from a shell — has nothing to restart
+// it, so exiting would silently end GUI watching. There it keeps running on
+// the old code and says so, once: the same "stale beats none" trade the
+// monitor makes. Kept as a pure decision so the policy is testable without
+// standing up a daemon.
+export function daemonSkewAction({ skewed, supervised, alreadyWarned = false } = {}) {
+  if (!skewed) return 'none';
+  if (supervised) return 'restart';
+  return alreadyWarned ? 'none' : 'warn';
+}
+
 export async function fetchLatest({ fetcher = globalThis.fetch, timeoutMs = 3000 } = {}) {
   try {
     const ctrl = new AbortController();