unsnooze 1.0.0

package/src/agents/grok.js

@@ -0,0 +1,98 @@
+// xAI Grok Build adapter — EXPERIMENTAL.
+//
+// Grok Build is closed source and its usage-limit banner text has no public
+// documentation, so limit detection uses generic patterns and leans on the
+// 5-hour fallback when no reset time parses. What IS documented (docs.x.ai):
+//   - hooks are Claude-Code-compatible JSON, events include StopFailure,
+//     read from ~/.grok/hooks/*.json — so the hook channel works
+//   - sessions live in ~/.grok/sessions/, resume via `grok --resume [<id>]`
+//     or `grok -c` (most recent, keyed by cwd)
+// Users can improve the patterns by sending real captures: `unsnooze report`.
+//
+// NOTE: the community superagent-ai/grok-cli also installs a `grok` binary and
+// also uses ~/.grok — that one is API-key-only (no usage windows) and is NOT
+// the target; isCommunityGrokCli() tells them apart for the setup wizard.
+
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const GROK_DIR = () => process.env.UNSNOOZE_GROK_DIR || join(homedir(), '.grok');
+
+const LIMIT_ANCHORS = [
+  /usage (?:limit|quota)/i,
+  /rate limit exceeded/i,
+  /reached your .*(?:limit|quota)/i,
+  /out of credits/i,
+];
+
+export const patterns = {
+  limitPatterns: LIMIT_ANCHORS,
+  // Anchors double as reset lines (single-line banners): unparseable reset
+  // text falls back to the 5h default and self-corrects on verify.
+  resetPatterns: [
+    /try again/i,
+    /resets?\s/i,
+    ...LIMIT_ANCHORS,
+  ],
+  weeklyPatterns: [/week(?:ly)?\s+(?:limit|quota)/i],
+  fiveHourPatterns: [],
+  // The shortcuts bar is contextual; cancel/interject hints mean a turn is running.
+  busyPatterns: [
+    /cancel the running turn/i,
+    /interject/i,
+    /esc to interrupt/i,
+  ],
+  idleRegex: /[›❯>]/,
+  overloadPatterns: [/API error/i, /5\d\d\b.*error/i],
+  transientPatterns: [/API error/i],
+};
+
+export function isCommunityGrokCli({ grokDir = GROK_DIR() } = {}) {
+  // Official Grok Build: ~/.grok/config.toml. Community grok-cli: user-settings.json.
+  return existsSync(join(grokDir, 'user-settings.json')) && !existsSync(join(grokDir, 'config.toml'));
+}
+
+// Grok reads Claude-Code-format hook JSON from ~/.grok/hooks/*.json — install
+// our StopFailure handler in a file we own outright (trivial uninstall, no
+// merging with user config).
+export function installGrokHooks({ grokDir = GROK_DIR(), unsnoozeBin } = {}) {
+  const hooksDir = join(grokDir, 'hooks');
+  mkdirSync(hooksDir, { recursive: true });
+  const bin = unsnoozeBin || process.argv[1] || 'unsnooze';
+  const config = {
+    hooks: {
+      StopFailure: [{
+        matcher: 'overloaded|server_error|rate_limit',
+        hooks: [{ type: 'command', command: `test -f "${bin}" && node "${bin}" _hook-stopfailure --agent grok || exit 0`, timeout: 5 }],
+      }],
+    },
+  };
+  const file = join(hooksDir, 'unsnooze.json');
+  writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+  return file;
+}
+
+export function uninstallGrokHooks({ grokDir = GROK_DIR() } = {}) {
+  rmSync(join(grokDir, 'hooks', 'unsnooze.json'), { force: true });
+}
+
+export default {
+  id: 'grok',
+  name: 'Grok Build (xAI)',
+  bin: process.env.UNSNOOZE_GROK_BIN || 'grok',
+  experimental: true,
+  patterns,
+  menu: null,
+  resumeArgs(sessionId) {
+    return { args: sessionId ? ['--resume', sessionId] : ['-c'], messageViaPane: true };
+  },
+  // Session file format is undocumented; null keeps it conservative — the
+  // reopen path then uses `grok -c`, which Grok itself scopes to the cwd.
+  latestSessionId() {
+    return null;
+  },
+  isForegroundCommand(cmd) {
+    return cmd === 'grok' || cmd === 'node' || cmd === 'unsnooze';
+  },
+};

package/src/agents/index.js

@@ -0,0 +1,16 @@
+// Agent registry. Every supported CLI gets an adapter; unknown ids fall back
+// to claude (pre-adapter state records have no agent field).
+
+import claude from './claude.js';
+import codex from './codex.js';
+import grok from './grok.js';
+
+const REGISTRY = { claude, codex, grok };
+
+export function getAgent(id) {
+  return REGISTRY[id] || claude;
+}
+
+export function listAgents() {
+  return Object.values(REGISTRY);
+}

package/src/cli.js

@@ -0,0 +1,114 @@
+// User-facing subcommands: status, resume-now, cancel, logs, config.
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { LOG_FILE, MAX_RESUME_ATTEMPTS } from './config.js';
+import { readState, setStatus, updateState } from './state.js';
+import { getConfig, setConfigValue, listConfig, CONFIG_FILE } from './settings.js';
+import { spawnResumerIfNeeded } from './spawn.js';
+
+function fmtCountdown(ms) {
+  if (ms <= 0) return 'due now';
+  const m = Math.round(ms / 60_000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m`;
+}
+
+export function cmdStatus() {
+  const state = readState();
+  const sessions = Object.values(state.sessions);
+  const paused = !getConfig('autoResume');
+  if (sessions.length === 0) {
+    console.log(`unsnooze: no tracked sessions.${paused ? '  (PAUSED — auto-resume off)' : ''}`);
+    return 0;
+  }
+  const now = Date.now();
+  const pausedNote = paused ? '  PAUSED — auto-resume off (`unsnooze config set autoResume on`)' : '';
+  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)})` : '?';
+    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 ?? '-'} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}`);
+  }
+  return 0;
+}
+
+function selectKeys(state, idOrAll) {
+  const stopped = Object.values(state.sessions).filter(s => s.status === 'stopped');
+  if (idOrAll === '--all' || idOrAll === undefined) return stopped.map(s => s.key);
+  const match = stopped.filter(s => s.key.startsWith(idOrAll) || (s.sessionId || '').startsWith(idOrAll));
+  return match.map(s => s.key);
+}
+
+export function cmdResumeNow(idOrAll) {
+  const state = readState();
+  const keys = selectKeys(state, idOrAll);
+  if (keys.length === 0) { console.log('unsnooze: no matching stopped sessions.'); return 1; }
+  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
+      }
+    }
+  });
+  spawnResumerIfNeeded();
+  console.log(`unsnooze: marked ${keys.length} session(s) due now; resumer dispatched.`);
+  return 0;
+}
+
+export function cmdCancel(idOrAll) {
+  const state = readState();
+  const keys = selectKeys(state, idOrAll);
+  if (keys.length === 0) { console.log('unsnooze: no matching stopped sessions.'); return 1; }
+  for (const key of keys) setStatus(key, 'cancelled');
+  console.log(`unsnooze: cancelled ${keys.length} session(s).`);
+  return 0;
+}
+
+export function cmdLogs(follow) {
+  if (follow) {
+    const r = spawnSync('tail', ['-f', LOG_FILE], { stdio: 'inherit' });
+    return r.status ?? 0;
+  }
+  try {
+    process.stdout.write(readFileSync(LOG_FILE, 'utf-8'));
+  } catch {
+    console.log('unsnooze: no log file yet.');
+  }
+  return 0;
+}
+
+// `unsnooze config list | get <key> | set <key> <value>`
+export function cmdConfig(rest) {
+  const [action, key, ...valueParts] = rest;
+  try {
+    if (!action || action === 'list') {
+      const listed = listConfig();
+      console.log(`unsnooze settings (${CONFIG_FILE()}):\n`);
+      for (const [k, v] of Object.entries(listed)) {
+        console.log(`  ${k.padEnd(16)} ${JSON.stringify(v)}`);
+      }
+      return 0;
+    }
+    if (action === 'get') {
+      if (!key) { console.error('unsnooze config get <key>'); return 2; }
+      console.log(JSON.stringify(getConfig(key)));
+      return 0;
+    }
+    if (action === 'set') {
+      const value = valueParts.join(' ');
+      if (!key || value === '') { console.error('unsnooze config set <key> <value>'); return 2; }
+      const applied = setConfigValue(key, value);
+      console.log(`unsnooze: ${key} = ${JSON.stringify(applied)}`);
+      return 0;
+    }
+    console.error(`unsnooze config: unknown action "${action}" (list | get | set)`);
+    return 2;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}

package/src/config.js

@@ -0,0 +1,46 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function envInt(name, def) {
+  const v = parseInt(process.env[name] ?? '', 10);
+  return Number.isFinite(v) ? v : def;
+}
+
+export const STATE_DIR = process.env.UNSNOOZE_STATE_DIR || join(homedir(), '.unsnooze');
+export const STATE_FILE = join(STATE_DIR, 'state.json');
+export const LOCK_DIR = join(STATE_DIR, 'state.lock');
+export const LOG_FILE = join(STATE_DIR, 'unsnooze.log');
+export const EVENTS_DIR = join(STATE_DIR, 'events');
+export const RESUMER_LOCK = join(STATE_DIR, 'resumer.lock');
+
+export const CLAUDE_DIR = process.env.UNSNOOZE_CLAUDE_DIR || join(homedir(), '.claude');
+export const CLAUDE_SETTINGS = join(CLAUDE_DIR, 'settings.json');
+
+export const TMUX_SESSION_NAME = process.env.UNSNOOZE_TMUX_SESSION || 'unsnooze';
+
+// 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);
+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);
+export const READY_TIMEOUT_MS = envInt('UNSNOOZE_READY_TIMEOUT_MS', 60_000);
+export const EVENT_MARKER_TTL_MS = envInt('UNSNOOZE_EVENT_MARKER_TTL_MS', 120_000);
+
+// Pane scanning
+export const PANE_SCAN_LINES = envInt('UNSNOOZE_PANE_SCAN_LINES', 12);
+export const CAPTURE_LINES = envInt('UNSNOOZE_CAPTURE_LINES', 200);
+
+// Limits & retries
+export const MAX_RESUME_ATTEMPTS = envInt('UNSNOOZE_MAX_RESUME_ATTEMPTS', 5);
+export const MAX_BUSY_DEFERS = envInt('UNSNOOZE_MAX_BUSY_DEFERS', 10);
+export const OVERLOAD_BACKOFF_S = (process.env.UNSNOOZE_OVERLOAD_BACKOFF_S || '30,60,120,240,300')
+  .split(',').map(Number).filter(Number.isFinite);
+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);
+export const STALE_LOCK_MS = envInt('UNSNOOZE_STALE_LOCK_MS', 10_000);
+
+

package/src/hook.js

@@ -0,0 +1,105 @@
+// StopFailure hook handler (`unsnooze _hook-stopfailure [--agent <id>]`).
+// The agent CLI (Claude Code, or Grok Build via its Claude-compatible hooks)
+// invokes this with JSON on stdin when a turn ends in failure matching the
+// configured matcher (overloaded|server_error|rate_limit).
+// Must exit 0 quickly and never block or crash the calling CLI.
+
+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, TMUX_SESSION_NAME } 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 { capturePane } from './tmux.js';
+import { spawnResumerIfNeeded } from './spawn.js';
+import { makeLogger } from './logger.js';
+
+const log = makeLogger('hook');
+
+function readStdin(timeoutMs = 2000) {
+  return new Promise(resolve => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.on('data', c => { data += c; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+  });
+}
+
+function classify(payload, raw) {
+  const hay = JSON.stringify(payload) + raw;
+  if (/rate.?limit|usage.?limit/i.test(hay)) return 'rate_limit';
+  if (/overloaded|server_error|529|503/i.test(hay)) return 'overload';
+  return 'unknown';
+}
+
+export async function runHook(rest = []) {
+  try {
+    const agentIdx = rest.indexOf('--agent');
+    const agent = getAgent(agentIdx !== -1 ? rest[agentIdx + 1] : 'claude');
+    if (!getConfig(`agents.${agent.id}`)) return 0;   // agent disabled in settings
+    const raw = await readStdin();
+    let payload = {};
+    try { payload = JSON.parse(raw); } catch { /* tolerate non-JSON */ }
+
+    const pane = process.env.TMUX_PANE || payload.tmux_pane || null;
+    const kind = classify(payload, raw);
+    log(`StopFailure: kind=${kind} pane=${pane} session=${payload.session_id || '?'}`);
+
+    if (kind === 'overload') {
+      // Seconds-scale problem — leave a marker for the pane's monitor, do NOT
+      // record in state.json.
+      if (pane) {
+        mkdirSync(EVENTS_DIR, { recursive: true });
+        writeFileSync(join(EVENTS_DIR, `${pane.replace(/[^%\w]/g, '_')}.json`),
+          JSON.stringify({ pane, kind, at: Date.now(), payload: { error: payload.error ?? null } }));
+      }
+      return 0;
+    }
+
+    // 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();
+    let resetLine = null;
+    let limitType = 'unknown';
+    if (pane) {
+      try {
+        const text = await capturePane(pane, CAPTURE_LINES);
+        const d = detectLimit(text, PANE_SCAN_LINES, agent.patterns);
+        if (d.hit) { resetLine = d.resetLine; limitType = d.limitType; }
+      } catch { /* pane not capturable (no tmux) — fall back below */ }
+    }
+
+    if (kind === 'unknown' && !resetLine) return 0;   // nothing actionable
+
+    const { at, source } = resetAtMs(parseResetTime(resetLine), {
+      marginMs: RESET_MARGIN_MS, fallbackMs: FALLBACK_RESET_MS,
+    });
+    const sessionId = payload.session_id || agent.latestSessionId(cwd, detectedAt);
+
+    upsertSession({
+      sessionId: sessionId || null,
+      cwd,
+      pane,
+      agent: agent.id,
+      tmuxSession: TMUX_SESSION_NAME,
+      status: 'stopped',
+      limitType,
+      detectedVia: 'hook',
+      detectedAt,
+      resetAt: at,
+      resetSource: source,
+      attempts: 0,
+      lastAttemptAt: null,
+      lastError: null,
+    });
+    log(`recorded limit stop: session=${sessionId} resetAt=${new Date(at).toISOString()} (${source})`);
+    spawnResumerIfNeeded();
+    return 0;
+  } catch (err) {
+    log(`hook error (swallowed): ${err.stack || err}`);
+    return 0;   // never fail the hook
+  }
+}

package/src/install.js

@@ -0,0 +1,218 @@
+// Install / uninstall: wires unsnooze into the shell and the agent CLIs, and
+// migrates off claude-auto-retry / the pre-release csg.
+//   - ~/.claude/settings.json: StopFailure hook → unsnooze _hook-stopfailure
+//     (removes legacy hook entries; preserves everything else; backs up first;
+//     atomic write)
+//   - ~/.zshrc + ~/.bashrc: one fence-marked block with a wrapper function per
+//     enabled agent (claude/codex/grok), routed through `unsnooze _run`
+//   - ~/.grok/hooks/unsnooze.json when the grok agent is enabled
+// --settings <path> / --zshrc <path> override targets (used by tests).
+
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
+import { getConfig, configFileExists } from './settings.js';
+import { installGrokHooks, uninstallGrokHooks } from './agents/grok.js';
+import { UNSNOOZE_BIN } from './spawn.js';
+
+const FENCE_OPEN = '# >>> unsnooze >>>';
+const FENCE_CLOSE = '# <<< unsnooze <<<';
+// Fenced blocks left by tools this one replaces: claude-auto-retry, and the
+// pre-release "claude-session-guard" (csg) incarnation of unsnooze itself.
+const LEGACY_FENCES = [
+  { open: '# >>> claude-auto-retry >>>', close: '# <<< claude-auto-retry <<<' },
+  { open: '# >>> claude-session-guard >>>', close: '# <<< claude-session-guard <<<' },
+];
+const OLD_FENCE_OPEN = LEGACY_FENCES[0].open;
+
+function parseArgs(rest) {
+  const opts = { yes: false, settings: CLAUDE_SETTINGS, zshrc: join(homedir(), '.zshrc'), purge: false };
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--yes' || rest[i] === '-y') opts.yes = true;
+    else if (rest[i] === '--purge') opts.purge = true;
+    else if (rest[i] === '--settings') opts.settings = rest[++i];
+    else if (rest[i] === '--zshrc') opts.zshrc = rest[++i];
+  }
+  return opts;
+}
+
+function atomicWrite(path, content) {
+  const tmp = join(dirname(path), `.${Date.now()}.tmp`);
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+// --- settings.json hook management ---
+
+function isOurs(entry) {
+  return (entry.hooks || []).some(h => /unsnooze\.js"? _hook-stopfailure/.test(h.command || ''));
+}
+function isLegacy(entry) {
+  return (entry.hooks || []).some(h => /claude-auto-retry|csg\.js _hook-stopfailure/.test(h.command || ''));
+}
+
+export function mergeHookIntoSettings(settingsJson) {
+  const settings = JSON.parse(settingsJson);
+  settings.hooks = settings.hooks || {};
+  const list = (settings.hooks.StopFailure || []).filter(e => !isLegacy(e) && !isOurs(e));
+  list.push({
+    matcher: 'overloaded|server_error|rate_limit',
+    // Guarded like the shell wrapper: a vanished entry point must exit 0, not
+    // spray MODULE_NOT_FOUND errors into every Claude Code turn.
+    hooks: [{ type: 'command', command: `test -f "${UNSNOOZE_BIN}" && node "${UNSNOOZE_BIN}" _hook-stopfailure || exit 0`, timeout: 5 }],
+  });
+  settings.hooks.StopFailure = list;
+  return JSON.stringify(settings, null, 2) + '\n';
+}
+
+export function removeHookFromSettings(settingsJson) {
+  const settings = JSON.parse(settingsJson);
+  if (settings.hooks?.StopFailure) {
+    settings.hooks.StopFailure = settings.hooks.StopFailure.filter(e => !isOurs(e));
+    if (settings.hooks.StopFailure.length === 0) delete settings.hooks.StopFailure;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+  return JSON.stringify(settings, null, 2) + '\n';
+}
+
+// --- zshrc block management ---
+
+export function wrapperBlock(agents = ['claude']) {
+  // The missing-file guard is load-bearing: if unsnooze is ever uninstalled,
+  // moved, or renamed without cleaning the rc file, the wrapper must degrade
+  // to the plain CLI — never brick the user's `claude`/`codex` command.
+  const fns = agents.map(id => `unalias ${id} 2>/dev/null || true
+${id}() {
+  if [ "\${UNSNOOZE_ACTIVE}" = "1" ] || [ ! -f "${UNSNOOZE_BIN}" ]; then
+    command ${id} "$@"
+    return $?
+  fi
+  node "${UNSNOOZE_BIN}" _run ${id} "$@"
+}`).join('\n');
+  return `${FENCE_OPEN}
+# unsnooze wrappers: route every interactive launch of the CLIs below through
+# unsnooze so limit stops are recorded and auto-resumed.
+${fns}
+${FENCE_CLOSE}`;
+}
+
+export function stripFencedBlock(content, open, close) {
+  const lines = content.split('\n');
+  const out = [];
+  let inside = false;
+  let found = false;
+  for (const line of lines) {
+    if (!inside && line.trim() === open) { inside = true; found = true; continue; }
+    if (inside && line.trim() === close) { inside = false; continue; }
+    if (!inside) out.push(line);
+  }
+  return { content: out.join('\n'), found };
+}
+
+export function installZshrcBlock(content, agents = ['claude']) {
+  let cleaned = content;
+  let oldRemoved = false;
+  for (const { open, close } of LEGACY_FENCES) {
+    const r = stripFencedBlock(cleaned, open, close);
+    cleaned = r.content;
+    oldRemoved = oldRemoved || r.found;
+  }
+  ({ content: cleaned } = stripFencedBlock(cleaned, FENCE_OPEN, FENCE_CLOSE));
+  const result = cleaned.replace(/\n+$/, '\n') + '\n' + wrapperBlock(agents) + '\n';
+  return { content: result, oldRemoved };
+}
+
+// --- commands ---
+
+export function enabledAgents() {
+  return ['claude', 'codex', 'grok'].filter(id => getConfig(`agents.${id}`));
+}
+
+// rc files to touch: the explicit --zshrc target, or every rc file that exists
+// (zsh + bash) so the wrappers work regardless of the user's shell.
+function rcTargets(opts, explicit) {
+  if (explicit) return [opts.zshrc];
+  const candidates = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc')];
+  const existing = candidates.filter(p => existsSync(p));
+  return existing.length > 0 ? existing : [opts.zshrc];
+}
+
+export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
+  const opts = parseArgs(rest);
+  const explicitRc = rest.includes('--zshrc');
+
+  // First run in a real terminal with no saved settings → hand over to the
+  // interactive setup wizard (it calls back here with --yes afterwards).
+  if (!opts.yes && !configFileExists() && process.stdout.isTTY && process.stdin.isTTY) {
+    return import('./wizard.js').then(({ runWizard }) => runWizard());
+  }
+
+  // 1. Claude Code hook (also consumed by Grok Build's Claude-compatible hooks
+  //    when installed below).
+  if (agents.includes('claude')) {
+    if (existsSync(opts.settings)) {
+      copyFileSync(opts.settings, `${opts.settings}.unsnooze-bak`);
+      const before = readFileSync(opts.settings, 'utf-8');
+      atomicWrite(opts.settings, mergeHookIntoSettings(before));
+      console.log(`unsnooze: StopFailure hook installed in ${opts.settings} (backup: ${opts.settings}.unsnooze-bak)`);
+    } else {
+      atomicWrite(opts.settings, mergeHookIntoSettings('{}'));
+      console.log(`unsnooze: created ${opts.settings} with StopFailure hook`);
+    }
+  }
+
+  // 2. Grok Build hook file.
+  if (agents.includes('grok')) {
+    const file = installGrokHooks({ unsnoozeBin: UNSNOOZE_BIN });
+    console.log(`unsnooze: Grok StopFailure hook installed at ${file}`);
+  }
+
+  // 3. Shell wrappers (zsh + bash).
+  for (const rc of rcTargets(opts, explicitRc)) {
+    const rcContent = existsSync(rc) ? readFileSync(rc, 'utf-8') : '';
+    const hasOld = rcContent.includes(OLD_FENCE_OPEN) || rcContent.includes('CLAUDE_AUTO_RETRY_ACTIVE');
+    if (hasOld && !opts.yes) {
+      console.log(`unsnooze: found the old claude-auto-retry wrapper in ${rc}.`);
+      console.log('unsnooze: re-run with --yes to replace it, or remove the fenced');
+      console.log(`unsnooze: "${OLD_FENCE_OPEN}" block manually first.`);
+      return 1;
+    }
+    if (existsSync(rc)) copyFileSync(rc, `${rc}.unsnooze-bak`);
+    const { content, oldRemoved } = installZshrcBlock(rcContent, agents);
+    atomicWrite(rc, content);
+    console.log(`unsnooze: wrappers (${agents.join(', ')}) installed in ${rc}${oldRemoved ? ' (legacy wrapper block removed)' : ''}`);
+  }
+
+  console.log('\nunsnooze: done. Reload your shell:');
+  console.log('  exec $SHELL');
+  return 0;
+}
+
+export function cmdUninstall(rest) {
+  const opts = parseArgs(rest);
+  const explicitRc = rest.includes('--zshrc');
+
+  if (existsSync(opts.settings)) {
+    const before = readFileSync(opts.settings, 'utf-8');
+    atomicWrite(opts.settings, removeHookFromSettings(before));
+    console.log(`unsnooze: StopFailure hook removed from ${opts.settings}`);
+  }
+
+  uninstallGrokHooks();
+
+  for (const rc of rcTargets(opts, explicitRc)) {
+    if (!existsSync(rc)) continue;
+    const { content, found } = stripFencedBlock(readFileSync(rc, 'utf-8'), FENCE_OPEN, FENCE_CLOSE);
+    if (found) {
+      atomicWrite(rc, content);
+      console.log(`unsnooze: wrappers removed from ${rc}`);
+    }
+  }
+
+  if (opts.purge) {
+    rmSync(STATE_DIR, { recursive: true, force: true });
+    console.log(`unsnooze: state dir ${STATE_DIR} removed`);
+  }
+  return 0;
+}

package/src/launcher.js

@@ -0,0 +1,71 @@
+// Default `unsnooze _run <agent> [args...]` path: run the agent CLI under watch.
+//   - outside tmux: re-exec inside a new tmux session (the monitor needs a pane
+//     to scrape) — guarded by UNSNOOZE_ACTIVE to prevent recursion
+//   - inside tmux: spawn a detached per-pane monitor, then run the CLI,
+//     propagating its exit code
+//   - -p/--print: pure pass-through, no monitor (nothing interactive to scrape)
+
+import { spawn, spawnSync } from 'node:child_process';
+import { insideTmux, currentPaneId, tmuxAvailable } from './tmux.js';
+import { getAgent } from './agents/index.js';
+import { getConfig } from './settings.js';
+import { spawnDetached } from './spawn.js';
+import { makeLogger } from './logger.js';
+
+const log = makeLogger('launcher');
+
+function isPrintMode(args) {
+  return args.includes('-p') || args.includes('--print');
+}
+
+export function runLauncher(args, agentId = 'claude') {
+  const agent = getAgent(agentId);
+
+  // Recursion / nested-launch guard: inside an unsnooze-managed session, a
+  // plain `claude`/`codex`/`unsnooze` call goes straight through. Same for an
+  // agent the user disabled in settings — run it, don't watch it.
+  if (process.env.UNSNOOZE_ACTIVE === '1' || isPrintMode(args) || !getConfig(`agents.${agent.id}`)) {
+    const r = spawnSync(agent.bin, args, { stdio: 'inherit', env: { ...process.env, UNSNOOZE_ACTIVE: '1' } });
+    return r.status ?? 1;
+  }
+
+  if (!insideTmux()) {
+    if (!tmuxAvailable()) {
+      // Degrade gracefully: run the CLI unwatched rather than dying.
+      process.stderr.write('unsnooze: tmux not found — running without limit-watch.\n');
+      if (process.platform === 'win32') {
+        process.stderr.write('unsnooze: native Windows is not supported; run inside WSL (https://learn.microsoft.com/windows/wsl/install) where tmux works.\n');
+      } else {
+        process.stderr.write('unsnooze: install tmux to enable auto-resume (brew install tmux / apt install tmux).\n');
+      }
+      const r = spawnSync(agent.bin, args, { stdio: 'inherit', env: { ...process.env, UNSNOOZE_ACTIVE: '1' } });
+      return r.status ?? 1;
+    }
+    // Re-enter under tmux: `tmux new-session unsnooze _run <agent> <args...>` —
+    // the inner unsnooze lands in the insideTmux() branch below.
+    log(`not in tmux — wrapping into a tmux session`);
+    const inner = ['new-session', process.execPath, process.argv[1], '_run', agent.id, ...args];
+    const r = spawnSync('tmux', inner, { stdio: 'inherit' });
+    return r.status ?? 1;
+  }
+
+  const pane = currentPaneId();
+  if (pane) {
+    spawnDetached(['_monitor', pane, agent.id], { UNSNOOZE_CWD: process.cwd() });
+    log(`launching ${agent.id} in pane ${pane}, monitor spawned`);
+  } else {
+    log(`inside tmux but TMUX_PANE unset — launching ${agent.id} without monitor`);
+  }
+
+  const child = spawn(agent.bin, args, {
+    stdio: 'inherit',
+    env: { ...process.env, UNSNOOZE_ACTIVE: '1', UNSNOOZE_PANE: pane || '' },
+  });
+  return new Promise(resolve => {
+    child.on('exit', code => resolve(code ?? 1));
+    child.on('error', err => {
+      process.stderr.write(`unsnooze: failed to launch ${agent.bin}: ${err.message}\n`);
+      resolve(127);
+    });
+  });
+}