unsnooze 1.14.1 → 1.14.3

package/CHANGELOG.md

@@ -1,6 +1,66 @@
 # 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
+
+- **Resume lifecycle:** a limit banner scrolling out of the pane no longer
+  marks a Claude session resumed without a wake. Unsnooze now requires a
+  newer non-error parent-assistant usage record, rechecks that evidence
+  immediately before dispatch, ignores subagent `StopFailure` records, follows
+  the canonical key retained by state dedupe, and never treats a persistently
+  busy pane as proof of completion.
+- **Usage diagnostics:** estimated usage now says that its percentage is
+  unavailable, rather than claiming no stop was observed. Proxy
+  launcher documentation explains that `headroom wrap` bypasses Unsnooze's
+  shell launcher and same-pane monitor while hook detection and enabled daemon
+  file watching remain available.
 
 ## 1.14.1 — 2026-08-04
 

package/README.md

@@ -147,6 +147,21 @@ risks, and vulnerability reporting: **[SECURITY.md](SECURITY.md)**.
 the CLIs that use it (OpenCode, Qwen Code), and credit exhaustion (402) is
 surfaced as a notification — there's no reset to wait for, only a top-up.
 
+### Proxy launchers such as Headroom
+
+`headroom wrap claude` and `headroom wrap codex` resolve and launch the real
+agent executable directly. That bypasses Unsnooze's shell-function launcher,
+so no same-pane monitor is attached. Claude's installed `StopFailure` hook can
+still record stops, as can the transcript/rollout watcher while the daemon,
+`guiWatch`, and that agent are enabled. For full pane monitoring too, configure
+Headroom's provider-scope persistent routing, then start `claude` / `codex`
+normally so Unsnooze remains the outer launcher. With Headroom v0.34, one
+explicit setup is:
+
+```bash
+headroom install apply --scope provider --providers manual --target claude --target codex
+```
+
 ## GUI surfaces (VS Code extension, desktop apps)
 
 Terminal sessions are watched through the shell wrapper + tmux or Zellij. Sessions in
@@ -251,7 +266,7 @@ unsnooze usage — account burn & time-to-limit  (daemon: running · warnings at
 
 | What you get | How |
 |---|---|
-| **Honest labels** | Every figure is tagged `(exact)`, `(calibrated from N stops)`, or `(estimated — calibrating…)`. Never a bare %. |
+| **Honest labels** | Every figure is tagged `(exact)`, `(calibrated from N stops)`, or `(estimated — percentage unavailable)`. Never a bare %. |
 | **Account-wide burn** | Sums all active sessions **and** subagents (the limit is per-account, not per-pane). Idle gaps >5 min are excluded so a quiet hour doesn't hide a fast burn. |
 | **Time-to-wall** | ETA as a band (not a false-precision minute), cross-checked against known reset times. Weekly shown info-only — no unstable weekly ETA. |
 | **Pre-wall warnings** | Daemon notifies at `%` bands (`usageWarnAt`, default `80,95`) **and** time tiers (30 / 10 min). Deduped once per window. |
@@ -259,9 +274,9 @@ unsnooze usage — account burn & time-to-limit  (daemon: running · warnings at
 
 **Provenance ladder** (why this isn't another guessed-quota dashboard):
 
-1. **`(exact)`** — Codex always (local `used_percent` + epoch reset). Claude only with the opt-in statusline shim (server-authoritative `rate_limits` from [Claude Code's statusline JSON](https://code.claude.com/docs/en/statusline)).
-2. **`(calibrated from N stops)`** — Claude token burn vs a ceiling learned from **your** limit-stop ledger (the same stops unsnooze already records for resume). Not plan presets, not circular P90-of-history.
-3. **`(estimated)`** — used tokens + burn shown; ceiling unknown until the first observed stop.
+1. **`(exact)`** — Codex when a recent local rollout contains `token_count.rate_limits` (`used_percent` + epoch reset). Claude only with the opt-in statusline shim (server-authoritative `rate_limits` from [Claude Code's statusline JSON](https://code.claude.com/docs/en/statusline)).
+2. **`(calibrated from N stops)`** — Claude 5-hour token burn vs a ceiling learned from **your matching usable calibration samples**: a stop classified as `5h`, with a nonzero local token sample from the same model pool when known, otherwise an unpooled fallback sample. A stop can still be valid for revival without meeting those calibration requirements. Not plan presets, not circular P90-of-history.
+3. **`(estimated — percentage unavailable)`** — used tokens + burn are shown when available, but there is no exact percentage (and a Claude 5-hour row has no matching usable calibration ceiling yet).
 
 **Honest limits:** Claude transcript sums are a **lower bound** — subscription quotas are account-pooled with claude.ai and the Desktop app. Without the statusline shim, Claude tops out at calibrated/estimated. Exact Claude % needs Pro/Max after the first API response of a session (absent after `/clear` and on API auth).
 

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.1",
+  "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/agents/claude.js

@@ -100,7 +100,9 @@ export default {
   // method are unguarded.
   contextTokens(rec) {
     if (!rec?.cwd || !rec?.sessionId) return null;   // watcher/scrape records may lack either
-    return lastUsageTokens(transcriptPath(rec.cwd, rec.sessionId));
+    return lastUsageTokens(transcriptPath(rec.cwd, rec.sessionId, {
+      claudeDir: rec.env?.CLAUDE_CONFIG_DIR || process.env.CLAUDE_CONFIG_DIR,
+    }));
   },
   // The foreground process for a claude session is `node` (nvm shim) or `claude`.
   isForegroundCommand(cmd) {

package/src/config.js

@@ -15,7 +15,8 @@ export const RESUMER_LOCK = join(STATE_DIR, 'resumer.lock');
 // High-frequency burn accumulator + warn-dedup (daemon single-writer).
 export const USAGE_FILE = join(STATE_DIR, 'usage.json');
 
-export const CLAUDE_DIR = process.env.UNSNOOZE_CLAUDE_DIR || join(homedir(), '.claude');
+export const CLAUDE_DIR = process.env.UNSNOOZE_CLAUDE_DIR
+  || process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 export const CLAUDE_SETTINGS = join(CLAUDE_DIR, 'settings.json');
 export const CODEX_DIR = process.env.UNSNOOZE_CODEX_DIR || join(homedir(), '.codex');
 // Opt-in statusline shim drop dir for exact Claude rate_limits.

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/hook.js

@@ -20,6 +20,7 @@ import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { addressHash } from './lease.js';
 import { prepareCalibrationSample, applyCalibrationToState } from './usage.js';
+import { claudeRecordEnv } from './sessions.js';
 
 const log = makeLogger('hook');
 
@@ -48,6 +49,13 @@ export async function runHook(rest = []) {
     const raw = await readStdin();
     let payload = {};
     try { payload = JSON.parse(raw); } catch { /* tolerate non-JSON */ }
+    // Claude includes agent_id when a hook fires inside a subagent. The parent
+    // transcript owns revival; recording the child would create a second stop
+    // with no independently resumable pane.
+    if (agent.id === 'claude' && payload.agent_id) {
+      log(`StopFailure: ignoring subagent ${payload.agent_id}; parent session owns resume`);
+      return 0;
+    }
 
     const managedMux = process.env.UNSNOOZE_MUX;
     const muxName = managedMux || (process.env.ZELLIJ_PANE_ID ? 'zellij' : 'tmux');
@@ -129,6 +137,7 @@ export async function runHook(rest = []) {
       log(`calibration prepare failed: ${err.message}`);
     }
     // Stop record + calibration sample in ONE locked update (plan §6).
+    const recordEnv = agent.id === 'claude' ? claudeRecordEnv() : null;
     upsertSession({
       sessionId: sessionId || null,
       cwd,
@@ -149,6 +158,7 @@ export async function runHook(rest = []) {
       attempts: 0,
       lastAttemptAt: null,
       lastError: null,
+      ...(recordEnv ? { env: recordEnv } : {}),
       ...(source === 'fallback' ? { probeCount: 0 } : {}),
     }, {
       after: calSample

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 {