unsnooze 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+## 1.8.0 — 2026-07-13
+
+- **Notification channels** (`notifyChannel`: `auto` | `native` | `osc` |
+  `bell`, env `UNSNOOZE_NOTIFY_CHANNEL`): terminal-branded alerts via OSC 9
+  (iTerm2, kitty, WezTerm, Ghostty, Warp) or OSC 777 (rxvt), plus BEL on the
+  pane tty. `auto` sends OSC+BEL when tmux can reach client/pane ttys and
+  falls back to the OS toast only if OSC delivered nothing; denylisted
+  terminals (Apple Terminal, VS Code, Alacritty, Zed) skip OSC in auto.
+  OSC/BEL require tmux — Zellij and GUI-watcher stops use native. Existing
+  `notifications` remains the master off-switch.
+- **Unified ChatGPT desktop app support** (July 2026: the Codex app became the
+  ChatGPT app). Verified against a real install: the app's bundled
+  `codex app-server` still writes rollouts to `~/.codex/sessions/` in the same
+  format (now with additive `limit_id`/`credits`/`plan_type` fields and
+  reason-string `rate_limit_reached_type` values — both handled), and
+  `codex resume <uuid>` works for app-originated sessions. New: when `codex`
+  is not on PATH but ChatGPT.app is installed, unsnooze resolves the
+  app-bundled binary (`ChatGPT.app/Contents/Resources/codex`) for wrappers,
+  wizard detection, and revival. Rollouts older than 7 days are now
+  zstd-compressed by codex; irrelevant for detection (freshness window is
+  minutes) but noted for `unsnooze report` archaeology.
+- Added a dual tmux/Zellij multiplexer backend. The new `multiplexer` setting
+  accepts `auto`, `tmux`, or `zellij`; status output identifies the backend,
+  qualified pane address, and revival session. Zellij revival uses structured
+  pane ownership and a reserved-session smoke test without adding a statusline
+  notification path.
+
 ## 1.7.0 — 2026-07-12
 
 - **Four new agent adapters** (all ⚠️ experimental, off by default — enable in

package/README.md

@@ -12,7 +12,7 @@
 **Claude Code · Codex CLI · Grok · Qwen · Kimi · OpenCode · Antigravity** — when they hit the 5-hour or weekly usage limit
 ("You've hit your usage limit"), your session just… stops.<br/>
 unsnooze auto-resumes them: it tracks **every** limit-stopped session across all
-your projects and **wakes each one up in tmux the moment the usage limit resets.**
+your projects and **wakes each one up in tmux or Zellij the moment the usage limit resets.**
 
 ```sh
 npm install -g unsnooze && unsnooze setup
@@ -40,7 +40,7 @@ existing tool solves only a slice of it:
 ## Supported CLIs
 
 - **Claude Code** — dual-channel detection: the `StopFailure` hook (authoritative,
-  carries `session_id`) plus tmux pane scraping for banners and the interactive
+  carries `session_id`) plus multiplexer pane scraping for banners and the interactive
   limit menu (always answered with *"Stop and wait for limit to reset"*, never a
   blind Enter). Dead sessions revive via `claude --resume <id>`.
 - **OpenAI Codex CLI** — scrape-based (Codex fires no event on limits). Detects
@@ -92,7 +92,7 @@ surfaced as a notification — there's no reset to wait for, only a top-up.
 
 ## GUI surfaces (VS Code extension, desktop apps)
 
-Terminal sessions are watched through the shell wrapper + tmux. Sessions in
+Terminal sessions are watched through the shell wrapper + tmux or Zellij. Sessions in
 **Claude Code's VS Code extension / desktop app** and **Codex's IDE
 extension / desktop app** have no pane to scrape — so `unsnooze daemon` tails
 the session files those surfaces already write:
@@ -102,14 +102,19 @@ the session files those surfaces already write:
   shared by the CLI and the VS Code extension.
 - **Codex** writes a `rate_limits` snapshot (usage %, **exact epoch reset
   time**) into every rollout under `~/.codex/sessions/` — shared by the CLI,
-  IDE extension, and desktop app.
+  IDE extension, and the **unified ChatGPT desktop app** (July 2026: the Codex
+  app became the ChatGPT app; its bundled `codex app-server` writes the same
+  rollouts to the same store — verified against a real install). On machines
+  where Codex lives only inside ChatGPT.app (no `codex` on PATH), unsnooze
+  automatically resumes through the app-bundled binary
+  (`/Applications/ChatGPT.app/Contents/Resources/codex`).
 - **Claude desktop (cowork) sessions** *(experimental, macOS)* run in
   sandboxes under `~/Library/Application Support/Claude`; unsnooze watches
   those too and revives with the session's isolated `CLAUDE_CONFIG_DIR`
   (plus the keychain-scope override that keeps auth working — verified
   against a real desktop session).
 
-When the limit resets, the session is revived **in a tmux window** with
+When the limit resets, the session is revived **in a multiplexer pane** with
 `claude --resume <id>` / `codex resume <id>` — it's the same session file, so
 the continued conversation stays visible in the GUI's own history. (Resuming
 *inside* the GUI panel isn't possible today: no extension/app exposes an
@@ -129,7 +134,7 @@ anytime with `unsnooze config set guiWatch off`.
 <summary>text version</summary>
 
 ```
-claude / codex / grok (shell wrapper) ──► unsnooze _run <agent> ──► CLI in tmux pane
+claude / codex / grok (shell wrapper) ──► unsnooze _run <agent> ──► CLI in mux pane
                                               │
                                               ├─ per-pane monitor (scrapes for limit
                                               │  banners, drives Claude's limit menu,
@@ -146,7 +151,7 @@ StopFailure hook (claude, grok) ──────────────┤
                                               │
                           ┌───────────────────┴────────────────────┐
                  pane still alive?                          pane gone?
-                 send resume message into it                tmux new-window,
+                 send resume message into it                new multiplexer pane,
                  (only if the CLI is foreground             `unsnooze _run <agent>
                  and not mid-stream)                        --resume <id>`, verify
 ```
@@ -184,9 +189,11 @@ unsnooze help                   # full command list (also -h / --help)
 
 | key | default | meaning |
 |---|---|---|
+| `multiplexer` | `auto` | Backend to use: `auto`, `tmux`, or `zellij`. `auto` prefers the current multiplexer, then the only installed backend, with tmux as the tie-breaker. |
 | `autoResume` | `true` | Master switch. Off = stops are still tracked, but nothing is resumed until you run `unsnooze resume-now` or turn it back on. |
 | `menuAutoAnswer` | `true` | May unsnooze answer Claude's limit menu (send keys in your pane)? Off = watch-only. |
-| `notifications` | `true` | Desktop notification on limit detected / session resumed / gave up. |
+| `notifications` | `true` | Master switch for all notifications (limit detected / session resumed / gave up). Off = silence every channel. |
+| `notifyChannel` | `auto` | How to deliver: `auto`, `native`, `osc`, or `bell` (see [Notification channels](#notification-channels)). Env: `UNSNOOZE_NOTIFY_CHANNEL`. |
 | `guiWatch` | `true` | May the daemon watch session files for GUI-surface stops (VS Code extension, desktop apps)? Needs the daemon running (`unsnooze install --daemon`). |
 | `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. Override it for a single session with `unsnooze message <id> "…"` — visible in `unsnooze status`. |
 | `resumeMessages.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
@@ -198,6 +205,36 @@ unsnooze help                   # full command list (also -h / --help)
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
 all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
 
+### Notification channels
+
+When a limit is hit, a session resumes, or unsnooze gives up, it can alert you
+via an OS toast, a terminal OSC sequence, a BEL, or a mix — controlled by
+`notifyChannel` (default `auto`). `notifications=false` (or
+`UNSNOOZE_NOTIFICATIONS=off`) turns every channel off.
+
+| channel | what it does |
+|---|---|
+| `auto` | OSC (when the terminal supports it) **plus** BEL on the pane tty; falls back to native only if OSC delivered nothing (avoids double banners). No pane / non-tmux mux → native. |
+| `native` | OS toast (macOS `osascript`, Linux `notify-send`, WSL/Windows PowerShell toast); tmux `display-message` as a last-resort statusline fallback on other platforms. |
+| `osc` | Force OSC to attached client ttys; native if zero deliveries. |
+| `bell` | BEL to the pane tty; native if undeliverable. |
+
+**Terminal support (OSC)** — detection uses `TERM_PROGRAM` / termname / known
+env markers:
+
+| terminals | sequence |
+|---|---|
+| iTerm2, kitty, WezTerm, Ghostty, Warp | OSC 9 (`\x1b]9;title: body\x07`) |
+| rxvt / urxvt | OSC 777 (`\x1b]777;notify;title;body\x07`) |
+| Apple Terminal, VS Code, Alacritty, Zed | denylisted — OSC skipped (prefer `native`; force `osc` does not unlock these) |
+| unknown | skipped in `auto`; OSC 9 when `notifyChannel=osc` |
+
+**tmux only for OSC/BEL.** Those paths write to the client's tty (OSC) or the
+pane's tty (BEL), which requires tmux's client/pane tty APIs. **Zellij has no
+equivalent**, so OSC/BEL are not attempted under Zellij — notifications fall
+back to native (and Zellij has no statusline-inject equivalent either). GUI
+watcher stops (no pane context) always use native.
+
 ## Safety properties
 
 - **Never injects blind**: keys are only sent when the pane's foreground
@@ -224,26 +261,31 @@ all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
 
 ## Requirements
 
-- Node ≥ 20 and tmux
+- Node ≥ 20 and tmux ≥ 3.2 **or** Zellij
 - macOS, Linux, or **Windows via WSL** (see below)
 - zsh or bash (the wrappers are installed into `~/.zshrc` / `~/.bashrc`)
 
 ### Windows / WSL
 
-unsnooze is built on tmux, so on Windows it runs inside
+tmux and Zellij are Unix tools, so on Windows unsnooze runs inside
 [WSL](https://learn.microsoft.com/windows/wsl/install) — which is where the
 agent CLIs live on Windows anyway:
 
 ```sh
 # inside your WSL distro (Ubuntu etc.)
-sudo apt install tmux
+sudo apt install tmux             # or install Zellij: https://zellij.dev/documentation/installation
 npm install -g unsnooze && unsnooze setup
 ```
 
+On macOS, install either backend with `brew install tmux` or
+`brew install zellij`. In `auto` mode unsnooze uses the multiplexer you are
+currently inside; choose one explicitly with
+`unsnooze config set multiplexer tmux` or `zellij`.
+
 Everything works as on Linux, including desktop notifications: inside WSL,
 unsnooze raises **native Windows toasts** through `powershell.exe` (no
 `notify-send` or X server needed). Native Windows (PowerShell/cmd, no WSL) is
-not supported — without tmux there is nothing to watch; unsnooze will tell you
+not supported — without tmux or Zellij there is no terminal pane to watch; unsnooze will tell you
 so and run your CLI unwatched instead of breaking it.
 
 ## FAQ
@@ -289,7 +331,7 @@ disable the check.
 
 Yes — reset times are stored as absolute timestamps and checked every 30
 seconds, so a laptop that slept through the reset resumes on the next tick,
-and dead panes are reopened by session id in a fresh tmux window.
+and dead panes are reopened by session id in a fresh multiplexer pane.
 
 ## Development
 
@@ -297,6 +339,7 @@ and dead panes are reopened by session id in a fresh tmux window.
 npm test                     # unit tests (node:test)
 ./scripts/e2e-simulate.sh    # full detect → wait → re-open cycle in a
                              # scratch tmux session (no real limits needed)
+bash -n scripts/e2e-zellij.sh # syntax-check the reserved-session Zellij smoke test
 ```
 
 ## License

package/bin/unsnooze.js

@@ -69,9 +69,9 @@ async function main() {
       return runHook(rest);
     }
     case '_monitor': {
-      if (!rest[0]) { console.error('unsnooze _monitor: pane id required'); return 2; }
+      if (!rest[0] || !rest[2]) { console.error('unsnooze _monitor: mux owner pane required'); return 2; }
       const { runMonitor } = await import('../src/monitor.js');
-      return runMonitor(rest[0], rest[1]);
+      return runMonitor(rest[0], rest[1], rest[2], rest[3], rest[4]);
     }
     case '_run': {
       if (!rest[0]) { console.error('unsnooze _run: agent id required'); return 2; }
@@ -93,7 +93,7 @@ async function main() {
     case 'daemon': {
       // Persistent resumer + transcript watcher: detects and revives limit
       // stops from GUI surfaces (VS Code extension, desktop apps) where no
-      // shell wrapper or tmux pane exists. Run via launchd/systemd or a shell.
+      // shell wrapper or multiplexer pane exists. Run via launchd/systemd or a shell.
       const { runResumer } = await import('../src/resumer.js');
       const { createWatcher } = await import('../src/watcher.js');
       const controller = new AbortController();
@@ -122,10 +122,11 @@ Usage:
   unsnooze logs [-f]               show (or follow) the unsnooze log
   unsnooze update                  update unsnooze itself to the latest version
   unsnooze daemon                  persistent watcher for GUI sessions (VS Code
-                                   extension, desktop apps) — no tmux needed to
-                                   detect; revival still opens in tmux
+                                   extension, desktop apps) — no live pane needed
+                                   to detect; revival opens in tmux or Zellij
   unsnooze config [list|get|set]   view or change settings (toggles, global +
-                                   per-agent resume messages, updateCheck)
+                                   per-agent resume messages, notifyChannel
+                                   auto|native|osc|bell, updateCheck)
   unsnooze setup                   interactive setup wizard (agents + toggles)
   unsnooze install [--yes]         wire up shell wrappers + hooks (non-interactive)
   unsnooze uninstall [--purge]     remove wrappers + hooks (and state with --purge)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unsnooze",
-  "version": "1.7.0",
-  "description": "Auto-resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode & Antigravity CLI sessions in tmux when the usage limit (5-hour or weekly) resets. Wakes every limit-stopped AI coding session automatically.",
+  "version": "1.8.0",
+  "description": "Auto-resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode & Antigravity CLI sessions in tmux or Zellij when the usage limit (5-hour or weekly) resets. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
     "claude",
     "claude-code",
@@ -28,6 +28,7 @@
     "resume",
     "retry",
     "tmux",
+    "zellij",
     "ai-agents",
     "agentic-coding",
     "cli"

package/src/agents/codex.js

@@ -10,10 +10,30 @@
 // Transient errors render "stream error: … retrying 4/5 in 1.4s" and must take
 // the overload path, never the ledger.
 
-import { openSync, readSync, closeSync, readdirSync, statSync } from 'node:fs';
+import { openSync, readSync, closeSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { CODEX_DIR } from '../config.js';
 
+// Since the 2026 unified ChatGPT desktop app absorbed the Codex app, the codex
+// binary ships INSIDE the app bundle and many machines have no standalone
+// `codex` on PATH at all — yet ~/.codex/sessions rollouts (and the resume
+// command) work identically through the bundled binary (verified live against
+// codex-cli 0.144 from ChatGPT.app).
+export const CHATGPT_CODEX_BIN = '/Applications/ChatGPT.app/Contents/Resources/codex';
+
+function codexOnPath(env = process.env) {
+  return (env.PATH || '').split(':').some(dir => {
+    try { return dir && existsSync(join(dir, 'codex')); } catch { return false; }
+  });
+}
+
+export function resolveCodexBin({ env = process.env, onPath = () => codexOnPath(env), exists = existsSync } = {}) {
+  if (env.UNSNOOZE_CODEX_BIN) return env.UNSNOOZE_CODEX_BIN;
+  if (onPath()) return 'codex';
+  if (exists(CHATGPT_CODEX_BIN)) return CHATGPT_CODEX_BIN;
+  return 'codex';   // neither — the launcher degrades gracefully on spawn error
+}
+
 const LIMIT_ANCHORS = [
   /You've hit your usage limit/i,
   /Your workspace is out of credits/i,
@@ -91,7 +111,7 @@ export function latestSessionId(cwd, aroundTs = null, sessionsRoot = join(CODEX_
 export default {
   id: 'codex',
   name: 'OpenAI Codex CLI',
-  bin: process.env.UNSNOOZE_CODEX_BIN || 'codex',
+  bin: resolveCodexBin(),
   experimental: false,
   patterns,
   menu: null,                      // no interactive limit menu

package/src/cli.js

@@ -30,6 +30,7 @@ export function cmdStatus() {
     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 origin = s.origin ?? (s.pane ? 'cli' : '?');
+    const pane = s.paneOwner ? `${s.paneOwner}:${s.pane ?? '-'}` : (s.pane ?? '-');
     const msg = s.resumeMessage
       ? ` · msg: "${s.resumeMessage.length > 44 ? s.resumeMessage.slice(0, 44) + '…' : s.resumeMessage}"`
       : '';
@@ -37,7 +38,7 @@ export function cmdStatus() {
       ? ` · workspace changed (${s.holdReason ?? '?'}) — resume-now to wake`
       : '';
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              pane ${s.pane ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${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}${hold}`);
   }
   return 0;
 }

package/src/config.js

@@ -20,7 +20,9 @@ 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');
 
-export const TMUX_SESSION_NAME = process.env.UNSNOOZE_TMUX_SESSION || 'unsnooze';
+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
 
 // Timing (ms unless noted)
 export const RESET_MARGIN_MS = envInt('UNSNOOZE_RESET_MARGIN_MS', 60_000);
@@ -48,4 +50,3 @@ 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

@@ -6,15 +6,16 @@
 
 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 { EVENTS_DIR, FALLBACK_RESET_MS, RESET_MARGIN_MS, CAPTURE_LINES, PANE_SCAN_LINES, MUX_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 { getMultiplexer } from './multiplexer.js';
 import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
+import { addressHash } from './lease.js';
 
 const log = makeLogger('hook');
 
@@ -44,7 +45,16 @@ export async function runHook(rest = []) {
     let payload = {};
     try { payload = JSON.parse(raw); } catch { /* tolerate non-JSON */ }
 
-    const pane = process.env.TMUX_PANE || payload.tmux_pane || null;
+    const managedMux = process.env.UNSNOOZE_MUX;
+    const muxName = managedMux || (process.env.ZELLIJ_PANE_ID ? 'zellij' : 'tmux');
+    const pane = managedMux
+      ? (process.env.UNSNOOZE_PANE || null)
+      : (muxName === 'zellij' ? process.env.ZELLIJ_PANE_ID : process.env.TMUX_PANE || payload.tmux_pane) || null;
+    const paneOwner = muxName === 'zellij'
+      ? (managedMux ? process.env.UNSNOOZE_PANE_OWNER : process.env.ZELLIJ_SESSION_NAME) || null
+      : null;
+    const leaseId = process.env.UNSNOOZE_LEASE_ID || null;
+    const mux = getMultiplexer(muxName, { owner: paneOwner });
     const kind = classify(payload, raw);
     log(`StopFailure: kind=${kind} pane=${pane} session=${payload.session_id || '?'}`);
 
@@ -53,8 +63,8 @@ export async function runHook(rest = []) {
       // 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 } }));
+        writeFileSync(join(EVENTS_DIR, `${addressHash({ mux: muxName, paneOwner, pane })}.json`),
+          JSON.stringify({ mux: muxName, paneOwner, pane, kind, at: Date.now(), payload: { error: payload.error ?? null } }));
       }
       return 0;
     }
@@ -66,7 +76,7 @@ export async function runHook(rest = []) {
     let limitType = 'unknown';
     if (pane) {
       try {
-        const text = await capturePane(pane, CAPTURE_LINES);
+        const text = await mux.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 */ }
@@ -83,9 +93,12 @@ export async function runHook(rest = []) {
       sessionId: sessionId || null,
       cwd,
       pane,
+      mux: muxName,
+      paneOwner,
+      leaseId,
       agent: agent.id,
       origin: 'cli',   // the hook only fires for CLI launches we can see
-      tmuxSession: TMUX_SESSION_NAME,
+      muxSession: MUX_SESSION_NAME,
       status: 'stopped',
       limitType,
       detectedVia: 'hook',

package/src/install.js

@@ -208,7 +208,7 @@ export function installDaemonAutostart({ platform = process.platform, dir = null
     activate('systemctl', ['--user', 'enable', '--now', 'unsnooze.service']);
     return target;
   }
-  return null;   // native Windows: no tmux to revive into — daemon unsupported
+  return null;   // native Windows: no supported multiplexer to revive into
 }
 
 export function uninstallDaemonAutostart({ platform = process.platform, dir = null, activate = defaultActivate } = {}) {

package/src/launcher.js

@@ -1,16 +1,16 @@
 // 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,
+//   - outside a multiplexer: re-exec through its launchWrapped operation
+//   - inside one: 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 { getMultiplexer } from './multiplexer.js';
 import { getAgent } from './agents/index.js';
 import { getConfig } from './settings.js';
 import { spawnDetached } from './spawn.js';
 import { makeLogger } from './logger.js';
+import { createLeaseId, processBirth, writeLease, removeLease } from './lease.js';
 
 const log = makeLogger('launcher');
 
@@ -29,41 +29,60 @@ export function runLauncher(args, agentId = 'claude') {
     return r.status ?? 1;
   }
 
-  if (!insideTmux()) {
-    if (!tmuxAvailable()) {
+  const mux = getMultiplexer();
+  if (!mux.inside()) {
+    if (!mux.available()) {
       // Degrade gracefully: run the CLI unwatched rather than dying.
-      process.stderr.write('unsnooze: tmux not found — running without limit-watch.\n');
+      process.stderr.write(`unsnooze: ${mux.name} 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');
+        process.stderr.write('unsnooze: native Windows is not supported; run inside WSL.\n');
       } else {
-        process.stderr.write('unsnooze: install tmux to enable auto-resume (brew install tmux / apt install tmux).\n');
+        process.stderr.write(`unsnooze: install ${mux.name} to enable auto-resume.\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;
+    log(`not in ${mux.name} — wrapping into a managed session`);
+    return mux.launchWrapped({
+      file: process.execPath,
+      args: [process.argv[1], '_run', agent.id, ...args],
+      env: process.env,
+    });
   }
 
-  const pane = currentPaneId();
+  const pane = mux.currentPaneId();
+  const paneOwner = mux.name === 'zellij'
+    ? (process.env.UNSNOOZE_MUX === 'zellij'
+      ? process.env.UNSNOOZE_PANE_OWNER : process.env.ZELLIJ_SESSION_NAME) || null
+    : null;
+  const leaseId = process.env.UNSNOOZE_LEASE_ID || createLeaseId();
   if (pane) {
-    spawnDetached(['_monitor', pane, agent.id], { UNSNOOZE_CWD: process.cwd() });
-    log(`launching ${agent.id} in pane ${pane}, monitor spawned`);
+    spawnDetached(['_monitor', mux.name, paneOwner || '', pane, agent.id, leaseId],
+      { UNSNOOZE_CWD: process.cwd() });
+    log(`launching ${agent.id} in ${mux.name} ${paneOwner ?? '-'}:${pane}, monitor spawned`);
   } else {
-    log(`inside tmux but TMUX_PANE unset — launching ${agent.id} without monitor`);
+    log(`inside ${mux.name} but pane id unset — launching ${agent.id} without monitor`);
   }
 
+  const childEnv = {
+    ...process.env, UNSNOOZE_ACTIVE: '1', UNSNOOZE_MUX: mux.name,
+    UNSNOOZE_PANE: pane || '', UNSNOOZE_PANE_OWNER: paneOwner || '',
+    UNSNOOZE_LEASE_ID: leaseId,
+  };
   const child = spawn(agent.bin, args, {
     stdio: 'inherit',
-    env: { ...process.env, UNSNOOZE_ACTIVE: '1', UNSNOOZE_PANE: pane || '' },
+    env: childEnv,
   });
+  const lease = pane && child.pid ? {
+    leaseId, mux: mux.name, paneOwner, pane, agent: agent.id,
+    pid: child.pid, pidBirth: processBirth(child.pid),
+  } : null;
+  if (lease?.pidBirth) writeLease(lease);
+  const cleanup = () => { if (lease) removeLease(lease, leaseId); };
   return new Promise(resolve => {
-    child.on('exit', code => resolve(code ?? 1));
+    child.on('exit', code => { cleanup(); resolve(code ?? 1); });
     child.on('error', err => {
+      cleanup();
       process.stderr.write(`unsnooze: failed to launch ${agent.bin}: ${err.message}\n`);
       resolve(127);
     });

package/src/lease.js

@@ -0,0 +1,87 @@
+import {
+  mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync,
+} from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { randomUUID, createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { STATE_DIR } from './config.js';
+
+const LEASES_DIR = join(STATE_DIR, 'leases');
+
+export function addressHash({ mux, paneOwner, pane }) {
+  return createHash('sha256')
+    .update(`${mux ?? ''}\0${paneOwner ?? ''}\0${pane ?? ''}`)
+    .digest('hex');
+}
+
+export function createLeaseId() {
+  return randomUUID();
+}
+
+export function processBirth(pid, {
+  platform = process.platform,
+  readFile = path => readFileSync(path, 'utf-8'),
+  execFile = (file, args) => execFileSync(file, args, { encoding: 'utf-8' }),
+} = {}) {
+  try {
+    if (platform === 'linux') {
+      const stat = readFile(`/proc/${pid}/stat`);
+      const close = stat.lastIndexOf(')');
+      if (close === -1) return null;
+      // The tail begins at field 3 (state); starttime is field 22.
+      return stat.slice(close + 1).trim().split(/\s+/)[19] || null;
+    }
+    if (platform === 'darwin') {
+      return execFile('ps', ['-o', 'lstart=', '-p', String(pid)]).trim() || null;
+    }
+  } catch { /* fail closed */ }
+  return null;
+}
+
+function leasePath(address, leaseId) {
+  return join(LEASES_DIR, `${addressHash(address)}.${leaseId}.json`);
+}
+
+export function writeLease(lease) {
+  mkdirSync(LEASES_DIR, { recursive: true });
+  const path = leasePath(lease, lease.leaseId);
+  const tmp = `${path}.tmp.${process.pid}.${randomUUID()}`;
+  writeFileSync(tmp, JSON.stringify(lease));
+  renameSync(tmp, path);
+  return lease;
+}
+
+export function readLease(address, leaseId) {
+  try {
+    const lease = JSON.parse(readFileSync(leasePath(address, leaseId), 'utf-8'));
+    return lease.leaseId === leaseId ? lease : null;
+  } catch {
+    return null;
+  }
+}
+
+export function removeLease(address, leaseId) {
+  const path = leasePath(address, leaseId);
+  const lease = readLease(address, leaseId);
+  if (!lease || lease.leaseId !== leaseId) return false;
+  try { unlinkSync(path); return true; } catch { return false; }
+}
+
+function defaultPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export async function leaseMatches(rec, {
+  mux,
+  pidAlive = defaultPidAlive,
+  processBirthFn = processBirth,
+} = {}) {
+  if (!rec?.leaseId || !rec?.pane || !mux) return false;
+  const stored = readLease(rec, rec.leaseId);
+  if (!stored || stored.leaseId !== rec.leaseId || stored.agent !== rec.agent) return false;
+  if (stored.mux !== rec.mux || stored.paneOwner !== rec.paneOwner || stored.pane !== rec.pane) return false;
+  if (!pidAlive(stored.pid)) return false;
+  const birth = processBirthFn(stored.pid);
+  if (!birth || birth !== stored.pidBirth) return false;
+  try { return await mux.paneAlive(rec.pane); } catch { return false; }
+}