unsnooze 1.9.0 → 1.12.1

package/src/cli.js

@@ -1,4 +1,4 @@
-// User-facing subcommands: status, resume-now, cancel, logs, config.
+// User-facing subcommands: status, resume-now, cancel, logs, config, sessions, reap.
 
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -8,6 +8,9 @@ import { getAgent } from './agents/index.js';
 import { approxTokens } from './sessions.js';
 import { getConfig, setConfigValue, listConfig, CONFIG_FILE } from './settings.js';
 import { spawnResumerIfNeeded } from './spawn.js';
+import { getMultiplexer } from './multiplexer.js';
+import { listOwnedSessions, reap, attachHint } from './reap.js';
+import { planFor } from './resumer.js';
 
 function fmtCountdown(ms) {
   if (ms <= 0) return 'due now';
@@ -17,7 +20,20 @@ function fmtCountdown(ms) {
   return `${h}h ${m % 60}m`;
 }
 
-export function cmdStatus() {
+
+// Surface how the reset estimate was derived so a silent wrong guess can't hide.
+export function fmtResetProvenance(s) {
+  if (s.resetSource === 'fallback' || !s.resetSource) {
+    return 'guessed: no reset time found — probing';
+  }
+  const via = s.detectedVia === 'transcript' ? 'transcript'
+    : s.detectedVia === 'hook' ? 'hook'
+    : s.detectedVia === 'scrape' ? 'scrape'
+    : null;
+  return via ? `${s.resetSource}, from ${via}` : s.resetSource;
+}
+
+export async function cmdStatus() {
   const state = readState();
   const sessions = Object.values(state.sessions);
   const paused = !getConfig('autoResume');
@@ -30,7 +46,10 @@ export function cmdStatus() {
   console.log(`unsnooze: ${sessions.length} tracked session(s)  (resumer pid: ${state.resumerPid ?? 'not running'})${pausedNote}\n`);
   for (const s of sessions.sort((a, b) => (a.resetAt || 0) - (b.resetAt || 0))) {
     const id = s.sessionId ? s.sessionId.slice(0, 8) : '(no id)';
-    const reset = s.resetAt ? `${new Date(s.resetAt).toLocaleString()} (${fmtCountdown(s.resetAt - now)})` : '?';
+    const when = s.resetAt
+      ? `${new Date(s.resetAt).toLocaleString()} (${fmtCountdown(s.resetAt - now)})`
+      : '?';
+    const reset = `${when} (${fmtResetProvenance(s)})`;
     const origin = s.origin ?? (s.pane ? 'cli' : '?');
     const pane = s.paneOwner ? `${s.paneOwner}:${s.pane ?? '-'}` : (s.pane ?? '-');
     const msg = s.resumeMessage
@@ -47,8 +66,19 @@ export function cmdStatus() {
         if (t != null) ctx = ` · ctx ${approxTokens(t)} tok`;
       } catch { /* estimate unavailable — omit */ }
     }
+    // Attach hint when the mux session the record points at is still live.
+    let attach = '';
+    if (s.muxSession) {
+      try {
+        const mux = getMultiplexer(s.mux || 'tmux');
+        if (typeof mux.sessionExists === 'function' && await mux.sessionExists(s.muxSession)) {
+          const hint = attachHint(s.mux, s.muxSession);
+          if (hint) attach = ` · attach: ${hint}`;
+        }
+      } catch { /* mux unavailable — omit */ }
+    }
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}`);
+    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}${attach}`);
   }
   return 0;
 }
@@ -174,3 +204,126 @@ export function cmdConfig(rest) {
     return 1;
   }
 }
+
+// `unsnooze preview [id]` — dry-run: what WOULD the resumer do right now,
+// and why? Shares planFor/assessPane/evaluate*Guard with the real dispatch,
+// so this can never drift from what dispatch actually does. Read-only pane
+// captures only — nothing is typed, opened, or modified.
+// Exit codes (terraform -detailed-exitcode style): 0 = nothing would wake
+// right now, 2 = at least one actionable wake, 1 = internal error.
+export async function cmdPreview(rest = [], {
+  resolveMux = rec => getMultiplexer(rec.mux, { owner: rec.paneOwner }),
+  matchesLease = undefined,
+  print = console.log,
+  now = Date.now(),
+} = {}) {
+  try {
+    const idOrAll = rest.find(a => !a.startsWith('-'));
+    const state = readState();
+    let records = Object.values(state.sessions);
+    if (idOrAll) {
+      records = records.filter(s => s.key.startsWith(idOrAll) || (s.sessionId || '').startsWith(idOrAll));
+    }
+    if (records.length === 0) {
+      print(idOrAll ? `unsnooze preview: no session matching "${idOrAll}".` : 'unsnooze preview: no tracked sessions.');
+      return 0;
+    }
+    print('unsnooze preview — what WOULD happen right now (nothing is sent)\n');
+    const VERBS = {
+      inject: p => `would TYPE the wake message into pane ${p.target?.pane}`,
+      'drive-menu': p => `would SELECT "Stop and wait for limit to reset" in pane ${p.target?.pane}`,
+      reopen: p => `would REOPEN in session "${p.target?.session}"${p.messageViaPane ? ' and type the message once the TUI shows an idle prompt' : ' (message travels in argv)'}`,
+      busy: () => 'would DEFER — agent is busy',
+      'menu-held': () => 'limit menu on screen — would WAIT (menuAutoAnswer off)',
+      probe: () => 'would PROBE (reset time unknown) — not a resume',
+      waiting: () => 'waiting for the reset',
+      paused: () => 'paused — would do nothing',
+      held: () => 'held — would do nothing until resume-now',
+      'give-up': () => 'would GIVE UP (attempt cap reached)',
+      verifying: () => 'verifying an in-flight resume',
+      retry: () => 'would RETRY later (pane capture failed)',
+      none: () => 'nothing to do',
+    };
+    let actionable = false;
+    for (const rec of records.sort((x, y) => (x.resetAt || 0) - (y.resetAt || 0))) {
+      let plan;
+      try {
+        plan = await planFor(rec, {
+          mux: resolveMux(rec),
+          ...(matchesLease ? { matchesLease } : {}),
+          now,
+        });
+      } catch (err) {
+        print(`  ${rec.key.slice(0, 12)}: preview failed: ${err.message}`);
+        continue;
+      }
+      const id = rec.sessionId ? rec.sessionId.slice(0, 8) : '(no id)';
+      print(`  [${(rec.status || '?').toUpperCase().padEnd(9)}] ${id}  ${(rec.agent || 'claude').padEnd(6)} ${rec.cwd || ''}`);
+      print(`              ${(VERBS[plan.action] || (() => plan.action))(plan)}`);
+      for (const g of plan.gates) print(`              · ${g}`);
+      if (plan.message && ['inject', 'reopen'].includes(plan.action)) {
+        const m = plan.message.length > 140 ? `${plan.message.slice(0, 140)}…` : plan.message;
+        print(`              message: "${m.replace(/\n+/g, ' ⏎ ')}"`);
+      }
+      if (['inject', 'drive-menu', 'reopen'].includes(plan.action)) actionable = true;
+    }
+    print('\nNothing was typed, opened, or modified. `unsnooze resume-now <id>` wakes a session immediately.');
+    return actionable ? 2 : 0;
+  } catch (err) {
+    console.error(`unsnooze preview: ${err.message}`);
+    return 1;
+  }
+}
+
+// `unsnooze sessions` — list unsnooze-owned mux sessions with panes + records.
+export async function cmdSessions() {
+  const owned = await listOwnedSessions();
+  if (owned.length === 0) {
+    console.log('unsnooze: no unsnooze-owned mux sessions found.');
+    return 0;
+  }
+  console.log(`unsnooze: ${owned.length} mux session(s)\n`);
+  for (const s of owned) {
+    const flag = s.exited ? 'EXITED' : 'live';
+    const panes = s.panes.length ? s.panes.join(', ') : '(none)';
+    console.log(`  [${flag.padEnd(6)}] ${s.mux}  ${s.name}  panes: ${panes}`);
+    if (s.attach) console.log(`              attach: ${s.attach}`);
+    for (const r of s.records) {
+      console.log(`              · ${r.status} ${(r.agent || '?').padEnd(6)} ${r.cwd || '?'} pane ${r.pane ?? '-'}`);
+    }
+  }
+  return 0;
+}
+
+// `unsnooze reap [--dry-run|--yes]` — close terminal-record panes and empty/
+// EXITED unsnooze sessions. Default is dry-run.
+export async function cmdReap(rest = []) {
+  // Default dry-run unless --yes.
+  const yes = rest.includes('--yes');
+  const result = await reap({ dryRun: !yes, yes });
+  if (result.actions.length === 0) {
+    console.log(result.dryRun
+      ? 'unsnooze reap (dry-run): nothing to do.'
+      : 'unsnooze reap: nothing to do.');
+    return 0;
+  }
+  const prefix = result.dryRun ? 'unsnooze reap (dry-run)' : 'unsnooze reap';
+  console.log(`${prefix}: ${result.actions.length} action(s)\n`);
+  for (const a of result.actions) {
+    if (a.kind === 'close-pane') {
+      console.log(`  close pane ${a.mux} ${a.paneOwner ? `${a.paneOwner}:` : ''}${a.pane} (record ${a.key})`);
+    } else if (a.kind === 'delete-session') {
+      console.log(`  delete session ${a.mux} ${a.name} (${a.reason})`);
+    } else if (a.kind === 'drop-record') {
+      console.log(`  drop record ${a.key} (${a.reason})`);
+    } else if (a.kind === 'error') {
+      console.log(`  error: ${a.key || a.name}: ${a.message}`);
+    } else {
+      console.log(`  ${a.kind}: ${JSON.stringify(a)}`);
+    }
+  }
+  if (result.dryRun) {
+    console.log('\nRe-run with --yes to apply.');
+  }
+  return 0;
+}

package/src/config.js

@@ -20,15 +20,28 @@ export const CODEX_DIR = process.env.UNSNOOZE_CODEX_DIR || join(homedir(), '.cod
 // Transcript/rollout watcher (GUI detection channel)
 export const WATCH_OFFSETS_FILE = join(STATE_DIR, 'watch-offsets.json');
 
+// Interactive launcher base session name. The daemon never CREATES this name
+// (see RESUME_SESSION_NAME); it may only join it when already live.
 export const MUX_SESSION_NAME = process.env.UNSNOOZE_SESSION_NAME
   || process.env.UNSNOOZE_TMUX_SESSION || 'unsnooze';
-export const TMUX_SESSION_NAME = MUX_SESSION_NAME; // read compatibility
+// Legacy alias — older docs/scripts and any external importers used this name.
+export const TMUX_SESSION_NAME = MUX_SESSION_NAME;
+
+// Session the daemon creates for revivals when the pane's original session is
+// gone. Must never collide with the interactive base name.
+export const RESUME_SESSION_NAME = process.env.UNSNOOZE_RESUME_SESSION
+  || `${MUX_SESSION_NAME}-resumed`;
 
 // Timing (ms unless noted)
 export const RESET_MARGIN_MS = envInt('UNSNOOZE_RESET_MARGIN_MS', 60_000);
 export const POLL_INTERVAL_MS = envInt('UNSNOOZE_POLL_INTERVAL_MS', 30_000);       // resumer epoch polling
 export const SCRAPE_INTERVAL_MS = envInt('UNSNOOZE_SCRAPE_INTERVAL_MS', 5_000);    // monitor pane scraping
 export const FALLBACK_RESET_MS = envInt('UNSNOOZE_FALLBACK_RESET_MS', 5 * 3_600_000);
+// When no reset time parses: cheap pane probes instead of sleeping for 5h.
+// Backoff 15 → 30 → 60 min (capped at PROBE_MAX_MS); hard ceiling remains
+// FALLBACK_RESET_MS from detectedAt.
+export const PROBE_INTERVAL_MS = envInt('UNSNOOZE_PROBE_INTERVAL_MS', 15 * 60_000);
+export const PROBE_MAX_MS = envInt('UNSNOOZE_PROBE_MAX_MS', 60 * 60_000);
 export const STAGGER_MS = envInt('UNSNOOZE_STAGGER_MS', 8_000);
 export const VERIFY_DELAY_MS = envInt('UNSNOOZE_VERIFY_DELAY_MS', 20_000);
 export const BUSY_DEFER_MS = envInt('UNSNOOZE_BUSY_DEFER_MS', 60_000);
@@ -48,5 +61,7 @@ export const OVERLOAD_BACKOFF_S = (process.env.UNSNOOZE_OVERLOAD_BACKOFF_S || '3
 export const OVERLOAD_JITTER = 0.15;
 export const DEDUPE_WINDOW_MS = envInt('UNSNOOZE_DEDUPE_WINDOW_MS', 120_000);
 export const PRUNE_AFTER_MS = envInt('UNSNOOZE_PRUNE_AFTER_MS', 7 * 86_400_000);
+// Non-terminal records with a dead/absent pane older than this are marked
+// failed instead of being revived forever (ghost-pane multiplier).
+export const STALE_AFTER_MS = envInt('UNSNOOZE_STALE_AFTER_MS', 7 * 86_400_000);
 export const STALE_LOCK_MS = envInt('UNSNOOZE_STALE_LOCK_MS', 10_000);
-

package/src/doctor.js

@@ -0,0 +1,310 @@
+// `unsnooze doctor [--fix]` — health check + csg (claude-session-guard)
+// migration sweep. npm has no successor mechanism and `-g` uninstall hooks are
+// unreliable, so the ONLY robust cleanup of the pre-release csg install is
+// unsnooze itself finding and retiring its leftovers: zombie csg monitors/
+// resumers, an old launchd/systemd unit, the orphaned state dir, the stale
+// global package. Everything is injectable for tests; --fix never deletes
+// data (the state dir is archived) and never runs npm (hint only).
+
+import { readFileSync, readdirSync, renameSync, existsSync, unlinkSync, lstatSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { CLAUDE_SETTINGS, RESUMER_LOCK } from './config.js';
+import { getMultiplexer } from './multiplexer.js';
+import { makeLogger } from './logger.js';
+
+const log = makeLogger('doctor');
+
+const CSG_PROCESS_RE = /\bcsg\.js\s+_?(?:monitor|resumer|run|daemon|hook)/;
+// A unit is csg-legacy when it execs csg.js, or mentions claude-session-guard
+// WITHOUT execing unsnooze — the dev repo kept the old folder name after the
+// rename, so a live unsnooze daemon plist can legitimately have
+// .../claude-session-guard/bin/unsnooze.js in its path. Flagging that would
+// let --fix destroy the running daemon.
+function isCsgUnit(content) {
+  if (/csg\.js/.test(content)) return true;
+  return /claude-session-guard/.test(content) && !/unsnooze\.js|com\.unsnooze/.test(content);
+}
+
+function defaultRunner(cmd, args) {
+  try {
+    return spawnSync(cmd, args, { encoding: 'utf-8' });
+  } catch (err) {
+    return { status: 1, stdout: '', error: err };
+  }
+}
+
+// --- detections ---------------------------------------------------------------
+
+/** Live csg-era processes (monitors/resumers/daemons). */
+export function findCsgProcesses({ runner = defaultRunner } = {}) {
+  const r = runner('ps', ['-axo', 'pid=,command=']);
+  if (r.error || r.status !== 0) return [];
+  return String(r.stdout || '').split('\n')
+    .map(line => line.trim())
+    .filter(line => CSG_PROCESS_RE.test(line))
+    .map(line => {
+      const m = line.match(/^(\d+)\s+(.*)$/);
+      return m ? { pid: Number(m[1]), command: m[2] } : null;
+    })
+    .filter(Boolean);
+}
+
+/** launchd plists / systemd units that exec csg (never the unsnooze one). */
+export function findCsgAutostarts({ dir = defaultLaunchAgentsDir() } = {}) {
+  try {
+    return readdirSync(dir)
+      .filter(name => name.endsWith('.plist') || name.endsWith('.service'))
+      .map(name => join(dir, name))
+      .filter(path => {
+        try { return isCsgUnit(readFileSync(path, 'utf-8')); }
+        catch { return false; }
+      });
+  } catch {
+    return [];   // dir missing — nothing installed
+  }
+}
+
+function defaultLaunchAgentsDir(platform = process.platform) {
+  if (platform === 'darwin') {
+    return process.env.UNSNOOZE_LAUNCH_AGENTS_DIR || join(homedir(), 'Library', 'LaunchAgents');
+  }
+  return process.env.UNSNOOZE_SYSTEMD_USER_DIR || join(homedir(), '.config', 'systemd', 'user');
+}
+
+// The stale global package. `command -v csg` is NOT enough: after the rename
+// the repo has no bin/csg.js, so the global `csg` symlink dangles and shells
+// skip it — but the package entry in node_modules is still there (often as an
+// npm-link). lstat sees the entry even when the symlink target is gone.
+export function defaultCsgPackagePath({
+  runner = defaultRunner,
+  execPathRoots = [join(dirname(dirname(process.execPath)), 'lib', 'node_modules')],
+} = {}) {
+  const roots = [];
+  const r = runner('npm', ['root', '-g']);
+  if (!r.error && r.status === 0 && r.stdout) roots.push(String(r.stdout).trim());
+  roots.push(...execPathRoots);   // nvm/unix prefix layout fallback when npm is slow/absent
+  for (const root of roots) {
+    if (!root) continue;
+    const candidate = join(root, 'claude-session-guard');
+    try { lstatSync(candidate); return candidate; } catch { /* not here */ }
+  }
+  return null;
+}
+
+function defaultHookInstalled(settingsPath = CLAUDE_SETTINGS) {
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    return (settings.hooks?.StopFailure || []).some(entry =>
+      (entry.hooks || []).some(h => /unsnooze\.js"? _hook-stopfailure/.test(h.command || '')));
+  } catch {
+    return false;
+  }
+}
+
+function defaultWrappersInstalled() {
+  return [join(homedir(), '.zshrc'), join(homedir(), '.bashrc')].some(rc => {
+    try { return readFileSync(rc, 'utf-8').includes('# >>> unsnooze >>>'); }
+    catch { return false; }
+  });
+}
+
+function daemonRunning() {
+  try {
+    const pid = parseInt(readFileSync(RESUMER_LOCK, 'utf-8'), 10);
+    if (!Number.isFinite(pid)) return false;
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- report ---------------------------------------------------------------------
+
+/**
+ * Run every check. Findings: { id, kind: 'legacy'|'health'|'info', title,
+ * detail, fix? } — `fix` is a machine-actionable descriptor consumed by
+ * applyFixes. healthy === no legacy and no health findings.
+ */
+export async function runDoctor({
+  runner = defaultRunner,
+  platform = process.platform,
+  launchAgentsDir = defaultLaunchAgentsDir(platform),
+  csgStateDir = join(homedir(), '.claude-session-guard'),
+  csgBinPath = defaultCsgPackagePath({ runner }),
+  mux = getMultiplexer(),
+  hookInstalled = defaultHookInstalled,
+  wrappersInstalled = defaultWrappersInstalled,
+} = {}) {
+  const findings = [];
+
+  const procs = findCsgProcesses({ runner });
+  if (procs.length) {
+    findings.push({
+      id: 'csg-processes', kind: 'legacy',
+      title: `${procs.length} old csg process(es) still running`,
+      detail: procs.map(p => `  pid ${p.pid}: ${p.command}`).join('\n'),
+      fix: { action: 'kill-processes', pids: procs.map(p => p.pid) },
+    });
+  }
+
+  const units = findCsgAutostarts({ dir: launchAgentsDir });
+  if (units.length) {
+    findings.push({
+      id: 'csg-autostart', kind: 'legacy',
+      title: 'old csg daemon autostart unit(s) present',
+      detail: units.map(u => `  ${u}`).join('\n'),
+      fix: { action: 'remove-units', units, platform },
+    });
+  }
+
+  if (existsSync(csgStateDir)) {
+    findings.push({
+      id: 'csg-state-dir', kind: 'legacy',
+      title: `old csg state dir at ${csgStateDir}`,
+      detail: '  contains the pre-rename ledger/logs; superseded by ~/.unsnooze',
+      fix: { action: 'archive-dir', dir: csgStateDir },
+    });
+  }
+
+  if (csgBinPath) {
+    findings.push({
+      id: 'csg-package', kind: 'legacy',
+      title: `old claude-session-guard package still installed (${csgBinPath})`,
+      detail: '  run: npm rm -g claude-session-guard',
+      // npm owns the package (it may even be an npm-link to a dev repo) —
+      // doctor only ever hints, never runs npm.
+    });
+  }
+
+  if (!hookInstalled()) {
+    findings.push({
+      id: 'hook-missing', kind: 'health',
+      title: 'Claude StopFailure hook is not installed',
+      detail: '  run: unsnooze install --yes',
+    });
+  }
+  if (!wrappersInstalled()) {
+    findings.push({
+      id: 'wrappers-missing', kind: 'health',
+      title: 'shell wrappers are not installed',
+      detail: '  run: unsnooze install --yes  (then: exec $SHELL)',
+    });
+  }
+  let muxOk = false;
+  try { muxOk = !!mux.available(); } catch { muxOk = false; }
+  if (!muxOk) {
+    findings.push({
+      id: 'mux-missing', kind: 'health',
+      title: `${mux.name || 'tmux'} is not installed — limit-watch and revival are off`,
+      detail: `  install ${mux.name || 'tmux'} to enable auto-resume`,
+    });
+  }
+
+  findings.push({
+    id: 'daemon', kind: 'info',
+    title: daemonRunning() ? 'resumer/daemon: running' : 'resumer/daemon: not running (starts on the next limit stop)',
+    detail: '',
+  });
+
+  const healthy = findings.every(f => f.kind === 'info');
+  return { findings, healthy };
+}
+
+// --- fixes ------------------------------------------------------------------------
+
+function defaultKill(pid) {
+  try { process.kill(pid, 'SIGTERM'); return true; } catch { return false; }
+}
+
+/** Apply the machine-actionable fixes from a runDoctor report. */
+export async function applyFixes(report, {
+  kill = defaultKill,
+  runner = defaultRunner,
+  now = Date.now(),
+} = {}) {
+  const actions = [];
+  for (const finding of report.findings) {
+    const fix = finding.fix;
+    if (!fix) continue;
+    if (fix.action === 'kill-processes') {
+      for (const pid of fix.pids) {
+        kill(pid);
+        actions.push({ action: 'killed', pid });
+        log(`doctor: SIGTERM csg process ${pid}`);
+      }
+    } else if (fix.action === 'remove-units') {
+      for (const unit of fix.units) {
+        if (fix.platform === 'darwin') runner('launchctl', ['unload', unit]);
+        else runner('systemctl', ['--user', 'disable', '--now', unit]);
+        try { unlinkSync(unit); } catch { /* already gone */ }
+        actions.push({ action: 'removed-unit', unit });
+        log(`doctor: removed csg autostart ${unit}`);
+      }
+    } else if (fix.action === 'archive-dir') {
+      let target = `${fix.dir}.bak`;
+      if (existsSync(target)) target = `${fix.dir}.bak.${now}`;
+      try {
+        renameSync(fix.dir, target);
+        actions.push({ action: 'archived', from: fix.dir, to: target });
+        log(`doctor: archived ${fix.dir} → ${target}`);
+      } catch (err) {
+        actions.push({ action: 'error', detail: `archive ${fix.dir}: ${err.message}` });
+      }
+    }
+  }
+  return actions;
+}
+
+// --- CLI --------------------------------------------------------------------------
+
+export async function cmdDoctor(rest = [], deps = {}) {
+  const { print = console.log, ...checkDeps } = deps;
+  const wantFix = rest.includes('--fix');
+  const report = await runDoctor(checkDeps);
+
+  const legacy = report.findings.filter(f => f.kind === 'legacy');
+  const health = report.findings.filter(f => f.kind === 'health');
+  const info = report.findings.filter(f => f.kind === 'info');
+
+  if (legacy.length) {
+    print('unsnooze doctor — leftovers from the old claude-session-guard (csg) install:');
+    for (const f of legacy) {
+      print(`  ✗ ${f.title}`);
+      if (f.detail) print(f.detail);
+    }
+  }
+  if (health.length) {
+    print('unsnooze doctor — install health:');
+    for (const f of health) {
+      print(`  ✗ ${f.title}`);
+      if (f.detail) print(f.detail);
+    }
+  }
+  for (const f of info) print(`  · ${f.title}`);
+
+  if (report.healthy) {
+    print('unsnooze doctor: all clear — install is healthy.');
+    return 0;
+  }
+
+  if (wantFix) {
+    const actions = await applyFixes(report, deps);
+    for (const a of actions) {
+      if (a.action === 'killed') print(`  ✓ stopped csg process ${a.pid}`);
+      else if (a.action === 'removed-unit') print(`  ✓ removed ${a.unit}`);
+      else if (a.action === 'archived') print(`  ✓ archived ${a.from} → ${a.to}`);
+      else if (a.action === 'error') print(`  ! ${a.detail}`);
+    }
+    const pkg = legacy.find(f => f.id === 'csg-package');
+    if (pkg) print('  → finish up manually: npm rm -g claude-session-guard');
+    return 0;
+  }
+
+  print(legacy.length
+    ? '\nRun `unsnooze doctor --fix` to stop csg processes, remove its autostart, and archive its state.'
+    : '\nSee the hints above to finish the install.');
+  return 1;
+}

package/src/hook.js

@@ -6,12 +6,15 @@
 
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { EVENTS_DIR, FALLBACK_RESET_MS, RESET_MARGIN_MS, CAPTURE_LINES, PANE_SCAN_LINES, MUX_SESSION_NAME } from './config.js';
+import {
+  EVENTS_DIR, PROBE_INTERVAL_MS, RESET_MARGIN_MS, CAPTURE_LINES, PANE_SCAN_LINES,
+} from './config.js';
 import { detectLimit } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { getConfig } from './settings.js';
 import { parseResetTime, resetAtMs } from './time-parser.js';
 import { upsertSession } from './state.js';
+import { latestRateLimitFromTranscript } from './watchers/claude.js';
 import { getMultiplexer } from './multiplexer.js';
 import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
@@ -72,9 +75,22 @@ export async function runHook(rest = []) {
     // rate_limit (or unknown — treat conservatively as a limit if we can see a banner)
     const cwd = payload.cwd || process.cwd();
     const detectedAt = Date.now();
+    const sessionId = payload.session_id || agent.latestSessionId?.(cwd, detectedAt) || null;
+
+    // Prefer the dated transcript entry over an undated pane scrape when the
+    // agent keeps transcripts (claude). Yields both banner text and bannerAt.
     let resetLine = null;
     let limitType = 'unknown';
-    if (pane) {
+    let bannerAt = null;
+    let detectedVia = 'hook';
+    const fromTx = latestRateLimitFromTranscript(cwd, sessionId, { now: detectedAt });
+    if (fromTx) {
+      resetLine = fromTx.resetLine;
+      limitType = fromTx.limitType || 'unknown';
+      bannerAt = fromTx.timestampMs;
+      detectedVia = 'transcript';
+      log(`StopFailure: rate-limit banner from transcript (ts=${bannerAt ? new Date(bannerAt).toISOString() : '?'})`);
+    } else if (pane) {
       try {
         const text = await mux.capturePane(pane, CAPTURE_LINES);
         const d = detectLimit(text, PANE_SCAN_LINES, agent.patterns);
@@ -85,9 +101,18 @@ export async function runHook(rest = []) {
     if (kind === 'unknown' && !resetLine) return 0;   // nothing actionable
 
     const { at, source } = resetAtMs(parseResetTime(resetLine), {
-      marginMs: RESET_MARGIN_MS, fallbackMs: FALLBACK_RESET_MS,
+      marginMs: RESET_MARGIN_MS,
+      fallbackMs: PROBE_INTERVAL_MS,
+      now: new Date(detectedAt),
+      bannerAt,
     });
-    const sessionId = payload.session_id || agent.latestSessionId(cwd, detectedAt);
+
+    // Discover the live session name from the pane — never freeze the module
+    // load-time MUX_SESSION_NAME constant onto the record.
+    let muxSession = null;
+    if (pane && typeof mux.sessionForPane === 'function') {
+      try { muxSession = await mux.sessionForPane(pane); } catch { muxSession = null; }
+    }
 
     upsertSession({
       sessionId: sessionId || null,
@@ -98,16 +123,18 @@ export async function runHook(rest = []) {
       leaseId,
       agent: agent.id,
       origin: 'cli',   // the hook only fires for CLI launches we can see
-      muxSession: MUX_SESSION_NAME,
+      muxSession,
       status: 'stopped',
       limitType,
-      detectedVia: 'hook',
+      detectedVia,
       detectedAt,
+      bannerAt,
       resetAt: at,
       resetSource: source,
       attempts: 0,
       lastAttemptAt: null,
       lastError: null,
+      ...(source === 'fallback' ? { probeCount: 0 } : {}),
     });
     log(`recorded limit stop: session=${sessionId} resetAt=${new Date(at).toISOString()} (${source})`);
     spawnResumerIfNeeded();