unsnooze 1.14.3 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.15.0 — 2026-08-15
+
+- **Two new multiplexer backends: herdr and cmux.** unsnooze now watches and
+  revives sessions in [herdr](https://herdr.dev) and [cmux](https://cmux.dev)
+  alongside tmux and Zellij, chosen automatically from the multiplexer you are
+  already inside or explicitly with `unsnooze config set multiplexer herdr`.
+  Both are terminals built for running coding agents, and both start a command
+  by *typing* it into a pane rather than exec'ing it, which is a materially
+  different contract from tmux and Zellij — a revival's arguments are now
+  shell-quoted for them, and an argument that cannot be typed at all (a
+  multi-line resume message, say) travels through the pane's environment
+  instead of being mangled or refused. herdr needs 0.8.0 or newer; Homebrew
+  still ships 0.7.3, so install the release binary. Original herdr backend by
+  Wave Consulting (@walt-verweij) with follow-up work by @gaoflow; cmux backend
+  by @echarrod.
+
+- **Per-model limits are no longer invisible.** Claude Code can stop with
+  *"You've reached your Fable 5 limit. Run /usage-credits to continue or switch
+  models with /model"* — a banner with no reset time, which the previous
+  detection (a limit phrase paired with a time) could never match, and which
+  fires no StopFailure hook. The session simply stopped, untracked and
+  unannounced. It is now detected and tracked. Because only a human clears it,
+  unsnooze never types at such a pane: it probes until the banner goes, and at
+  the ceiling records a visible failure naming both remedies rather than
+  pretending a wake is coming. Detection is deliberately conservative — an
+  agent *quoting* the banner in its own output is not a stop. (@gaoflow)
+
+- **Four reset-scheduling bugs found in production.** A banner left on screen
+  after its reset passed was re-parsed every few seconds as "now + margin", so
+  the wake slid forward forever and the resumer never fired. An undated
+  "resets 10:30pm" re-read after midnight resolved to *tomorrow*, 22 hours out.
+  Accumulated pane-snapshot records with no session id each revived their own
+  copy of the same conversation — 23 records produced roughly 8 clones in one
+  repo at a weekly reset; at most one now revives per agent and project. And a
+  stop arriving after an old record was abandoned is no longer held back by it.
+  (@gaoflow)
+
+- **New setting: `resumeExtraArgs.<agent>`.** A revival spawns the agent binary
+  directly, so flags that normally come from a shell alias or wrapper do not
+  apply — a user who always runs `claude --dangerously-skip-permissions` got a
+  permission-prompting revival, which is about as useful as none. Set them per
+  agent and they are appended to launches unsnooze performs itself. Quoting is
+  respected (`--append-system-prompt "stay in this repo"` is two arguments, not
+  five), and `config.json` accepts an array if you would rather not think about
+  quoting at all.
+
+- **A failed launch no longer leaves a monitor scraping forever.** The monitor
+  starts before the agent does, and when the agent failed to start at all there
+  was no lease to notice its absence — so the monitor watched an ordinary shell
+  prompt indefinitely, one more process per failed launch. It now writes the
+  lease unconditionally (it was previously skipped wherever process start times
+  are unavailable, including Windows) and gives up if none appears. Reported by
+  @echarrod.
+
+- **Node 20.12 is now the minimum.** `engines` promised `>=20` while a
+  dependency needed `styleText` from `node:util`, which arrived in 20.12 — so
+  installs on 20.0–20.11 succeeded and then crashed on startup. The floor is
+  honest now, and CI tests that exact version so it cannot drift again.
+
+## 1.14.4 — 2026-08-08
+
+- **Windows: the daemon PATH check split on the wrong separator.** The check
+  added in 1.14.3 split `PATH` on `:`, which is right on macOS and Linux and
+  wrong on Windows — there the separator is `;` and every absolute path
+  contains a colon (`C:\...`), so entries were shredded into fragments. The
+  predicate now uses the host's own delimiter. No behavior changed on macOS or
+  Linux, and Windows has no autostart unit for the check to reach, so this is a
+  correctness and test-portability fix rather than a user-visible one.
+
 ## 1.14.3 — 2026-08-08
 
 - **Upgrades now reach running watchers.** A per-pane monitor lives as long as

package/README.md

@@ -16,7 +16,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 or Zellij the moment the usage limit resets.**
+your projects and **wakes each one up in tmux, Zellij, or herdr the moment the usage limit resets.**
 
 ```sh
 npm install -g unsnooze && unsnooze setup
@@ -164,7 +164,7 @@ headroom install apply --scope provider --providers manual --target claude --tar
 
 ## GUI surfaces (VS Code extension, desktop apps)
 
-Terminal sessions are watched through the shell wrapper + tmux or Zellij. Sessions in
+Terminal sessions are watched through the shell wrapper + tmux, Zellij, or herdr. 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:
@@ -417,7 +417,8 @@ pressing **`R`** (uppercase — lowercase `r` refreshes) only marks it due — t
 remote's own daemon does the actual keystrokes, under the same
 ownership/liveness/menu gates as a local session.
 Resumed and stopped sessions print an attach hint
-(`ssh -t <host> 'tmux new -A -s <session>'` / `zellij attach <session>`) so
+(`ssh -t <host> 'tmux new -A -s <session>'` / `zellij attach <session>` /
+`ssh -t <host> 'herdr session attach <session>'`) so
 you can hop over and watch. An unreachable or out-of-date host shows
 `unreachable`/`skew` rather than blocking the rest of the fleet, and falls
 back to its last-known state (marked `stale`) for up to 24h.
@@ -508,7 +509,7 @@ password hosts on Windows; a plain `ssh <host>` prompt works with native
 
 | 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. |
+| `multiplexer` | `auto` | Backend to use: `auto`, `tmux`, `zellij`, `herdr`, or `cmux`. `auto` prefers the current multiplexer (tmux/zellij ambient env, then `CMUX_SOCKET_PATH`); with no ambient env it falls back to whichever of tmux/zellij is installed, tmux as the tie-breaker — cmux is only selected via its ambient env or an explicit setting, never by this installed-backend fallback, since it has no attach-from-outside path to wrap into. cmux support covers resume-in-place (detect, capture, send); it has no joinable named-session model, so idle-session reaping (`unsnooze reap`) does not cover cmux panes, and no attach hint is shown for cmux sessions. |
 | `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` | Master switch for all notifications (limit detected / session resumed / gave up). Off = silence every channel. |
@@ -516,6 +517,7 @@ password hosts on Windows; a plain `ssh <host>` prompt works with native
 | `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 ""`. |
+| `resumeExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Extra flags for launches unsnooze performs itself. A revival spawns the agent binary directly, so flags you normally get from a shell alias or wrapper (`--dangerously-skip-permissions`, `--model …`) do not apply unless you put them here. Quoting is respected: `--append-system-prompt "stay in this repo"` is two arguments, not five. `config.json` may also hold an array (`["--append-system-prompt", "stay in this repo"]`), which skips parsing entirely. |
 | `agents.claude` / `agents.codex` | `true` | Which CLIs are guarded. |
 | `agents.grok` / `agents.qwen` / `agents.kimi` / `agents.opencode` / `agents.agy` | `false` | Experimental adapters — off by default; enable in `unsnooze setup` or `unsnooze config set agents.qwen on`. |
 | `workspaceGuard` | `inform` | Repo changed while a session slept? `inform` wakes it with a heads-up in the message; `pause` holds it (desktop notification, diff shown on `resume-now`); `off` disables. |
@@ -613,26 +615,53 @@ watcher stops (no pane context) always use native.
 
 ## Requirements
 
-- Node ≥ 20 and tmux ≥ 3.2 **or** Zellij
+- Node ≥ 20.12 and tmux ≥ 3.2, Zellij, **or** herdr ≥ 0.8.0
 - macOS, Linux, or **Windows via WSL** (see below)
 - zsh or bash (the wrappers are installed into `~/.zshrc` / `~/.bashrc`)
 
 ### Windows / WSL
 
-tmux and Zellij are Unix tools, so on Windows unsnooze runs inside
+tmux, Zellij, and herdr 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             # or install Zellij: https://zellij.dev/documentation/installation
+# install herdr from https://herdr.dev (requires herdr >= 0.8.0)
 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`.
+`brew install zellij`; install herdr from [herdr.dev](https://herdr.dev).
+herdr >= 0.8.0, which is the version the backend is verified against; older 0.x
+releases are refused by available(). Homebrew currently ships 0.7.3, so install
+the release binary from herdr.dev or GitHub rather than `brew install herdr`.
+In `auto` mode unsnooze uses the multiplexer you are currently inside; choose one
+explicitly with `unsnooze config set multiplexer tmux`, `zellij`, or `herdr`.
+
+#### herdr specifics
+
+herdr differs from tmux and Zellij in three ways that are visible in use:
+
+- **unsnooze never restarts a stopped herdr session.** herdr restores saved
+  agent panes when a session restarts (`resume_agents_on_restore` is on by
+  default), so restarting one can bring your agent back by itself — and a
+  revival on top of that would resume the same conversation twice. Reviving
+  into a stopped session therefore creates `unsnooze-2` (and so on) rather than
+  reusing the name. If you restart a stopped session yourself and herdr brings
+  the agent back, unsnooze may still open a fresh pane for it; that case is not
+  yet detected.
+- **Multi-line resume messages are carried, not typed.** herdr starts a pane
+  command by typing it into the pane's shell, where a newline would submit half
+  a command and a tab would be a completion request. Any such argument is passed
+  through the workspace environment instead and referenced by the typed line, so
+  a multi-paragraph `resumeMessage` reaches the agent as one argument, byte for
+  byte. (A NUL byte is still refused — an environment value cannot hold one.)
+- **A custom `HERDR_SOCKET_PATH` that does not match the session being
+  addressed disables watching for that pane.** herdr pane ids are per-server,
+  so acting on one from the wrong server could type into an unrelated terminal.
+  The agent still runs; unsnooze says why it is not watching.
 
 Everything works as on Linux, including desktop notifications: inside WSL,
 unsnooze raises **native Windows toasts** through `powershell.exe` (no
@@ -711,6 +740,7 @@ 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
+node scripts/e2e-herdr.mjs    # drives src/multiplexers/herdr.js against a real herdr (not run by CI)
 vhs demo/demo.tape           # regenerate assets/demo.gif (brew install vhs)
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unsnooze",
-  "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.",
+  "version": "1.15.0",
+  "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, herdr, VS Code, and desktop apps.",
   "keywords": [
     "claude",
     "claude-code",
@@ -35,6 +35,7 @@
     "retry",
     "tmux",
     "zellij",
+    "herdr",
     "ai-agents",
     "agentic-coding",
     "cli",
@@ -65,7 +66,7 @@
     "test": "node --test"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",

package/src/agents/claude.js

@@ -31,6 +31,13 @@ export const patterns = {
     /limit.*(?:this|per)\s+week/i,
   ],
   fiveHourPatterns: [/\d+-hour limit/i, /session limit/i],
+  // Per-model limits carry NO reset time and are not cleared by waiting:
+  //   "You've reached your Fable 5 limit. Run /usage-credits to continue
+  //    or switch models with /model."
+  // The remedy hint is required, not optional — it is what separates a real
+  // banner from an agent discussing usage limits in its own output.
+  modelLimitPatterns: [/(?:reached|hit)\s+(?:your|the)\s+[\w.\s-]{0,24}?\blimit\b/i],
+  modelRemedyPatterns: [/\/usage-credits\b/i, /switch\s+models?\b/i, /\/model\b/i],
   // While Claude is streaming ("esc to interrupt") or running its own internal
   // retries ("Retrying in 5s · attempt 3/10"), never inject keys.
   busyPatterns: [

package/src/cli.js

@@ -349,6 +349,7 @@ export async function cmdPreview(rest = [], {
       'give-up': () => 'would GIVE UP (attempt cap reached)',
       verifying: () => 'verifying an in-flight resume',
       retry: () => 'would RETRY later (pane capture failed)',
+      superseded: p => `would SKIP — record ${p.target?.key} revives the same conversation`,
       none: () => 'nothing to do',
     };
     let actionable = false;

package/src/config.js

@@ -65,6 +65,20 @@ 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);
 export const WATCH_FRESHNESS_MS = envInt('UNSNOOZE_WATCH_FRESHNESS_MS', 15 * 60_000);
 
+// How long a monitor waits for its agent's lease to appear before concluding
+// the launch failed and exiting. The launcher writes the lease immediately
+// after spawn(), so this only ever elapses when no agent was started at all.
+export const LEASE_GRACE_MS = envInt('UNSNOOZE_LEASE_GRACE_MS', 60_000);
+
+// Multiplexer backends, in detection order. The single source of truth: the
+// factory, the `multiplexer` setting enum and reap's session sweep all read
+// this list. It lives here, in a module that imports nothing but node builtins,
+// because settings.js and multiplexer.js already import each other — declaring
+// it in either one puts the other in a temporal dead zone at import time.
+// cmux is last: an agent can run tmux inside a cmux surface, so tmux/zellij
+// must win detection when both are signalled (see multiplexer.js: detect()).
+export const MUX_NAMES = ['tmux', 'zellij', 'herdr', 'cmux'];
+
 // Pane scanning
 export const PANE_SCAN_LINES = envInt('UNSNOOZE_PANE_SCAN_LINES', 12);
 export const CAPTURE_LINES = envInt('UNSNOOZE_CAPTURE_LINES', 200);

package/src/fleet.js

@@ -845,7 +845,11 @@ export const MUX_SESSION_RE = /^[A-Za-z0-9_.-]{1,64}$/;
 // validation — callers must treat null as "omit the attach line".
 export function attachHintRemote(dest, muxName, muxSession) {
   if (!validHostToken(dest) || typeof muxSession !== 'string' || !MUX_SESSION_RE.test(muxSession)) return null;
-  const inner = muxName === 'zellij' ? `zellij attach ${muxSession}` : `tmux new -A -s ${muxSession}`;
+  // cmux has no joinable named-session model — there is no remote command
+  // that reattaches to a surface, so omit the hint (see attachHint).
+  if (muxName === 'cmux') return null;
+  const inner = muxName === 'herdr' ? `herdr session attach ${muxSession}`
+    : muxName === 'zellij' ? `zellij attach ${muxSession}` : `tmux new -A -s ${muxSession}`;
   return `ssh -t ${dest} '${inner}'`;
 }
 

package/src/hook.js

@@ -41,6 +41,21 @@ function classify(payload, raw) {
   return 'unknown';
 }
 
+export function hookContext(env = process.env, payload = {}) {
+  const managedMux = env.UNSNOOZE_MUX;
+  const muxName = managedMux || (env.HERDR_PANE_ID ? 'herdr' : env.ZELLIJ_PANE_ID ? 'zellij' : 'tmux');
+  const pane = managedMux
+    ? (env.UNSNOOZE_PANE || null)
+    : (muxName === 'herdr' ? env.HERDR_PANE_ID
+      : muxName === 'zellij' ? env.ZELLIJ_PANE_ID : env.TMUX_PANE || payload.tmux_pane) || null;
+  const paneOwner = muxName === 'herdr'
+    ? (managedMux ? env.UNSNOOZE_PANE_OWNER : (env.HERDR_SESSION || 'default'))
+    : muxName === 'zellij'
+      ? (managedMux ? env.UNSNOOZE_PANE_OWNER : env.ZELLIJ_SESSION_NAME) || null
+      : null;
+  return { muxName, pane, paneOwner };
+}
+
 export async function runHook(rest = []) {
   try {
     const agentIdx = rest.indexOf('--agent');
@@ -57,16 +72,16 @@ export async function runHook(rest = []) {
       return 0;
     }
 
-    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 { muxName, pane: rawPane, paneOwner } = hookContext(process.env, payload);
     const leaseId = process.env.UNSNOOZE_LEASE_ID || null;
     const mux = getMultiplexer(muxName, { owner: paneOwner });
+    // Same guard as the launcher: a pane we cannot prove we are addressing on
+    // the right server is worse than no pane, because every later action —
+    // capture, inject, close — would be aimed at whatever occupies that id
+    // elsewhere. Record the stop without a pane instead.
+    const pane = (typeof mux.paneAddressable !== 'function' || mux.paneAddressable())
+      ? rawPane : null;
+    if (rawPane && !pane) log(`StopFailure: ignoring pane ${rawPane} — not safely addressable`);
     const kind = classify(payload, raw);
     log(`StopFailure: kind=${kind} pane=${pane} session=${payload.session_id || '?'}`);
 

package/src/install.js

@@ -11,7 +11,7 @@
 import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir, userInfo } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, delimiter } from 'node:path';
 import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
 import { getConfig, configFileExists } from './settings.js';
 import { xmlEscape } from './notify.js';
@@ -187,9 +187,13 @@ export function autostartUnitPath({ platform = process.platform, dir = null } =
 // 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) {
+// `sep` defaults to the host's PATH delimiter, not a hardcoded ':'. On Windows
+// that is ';' AND every absolute path contains a colon (C:\...), so splitting
+// on ':' shreds the entries into nonsense. The units we inspect are always
+// POSIX, but this predicate has to give an honest answer wherever it runs.
+export function pathResolves(pathStr, bin, { sep = delimiter } = {}) {
   if (typeof pathStr !== 'string' || pathStr === '') return false;
-  return pathStr.split(':').some(d => d && existsSync(join(d, bin)));
+  return pathStr.split(sep).some(d => d && existsSync(join(d, bin)));
 }
 
 function xmlUnescape(s) {

package/src/launcher.js

@@ -11,7 +11,8 @@ import { getConfig } from './settings.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';
+import { recordOwnedSession } from './mux-sessions.js';
+import { AgentDispatchedError, SessionCreateError, attachHint } from './multiplexers/session-name.js';
 
 const log = makeLogger('launcher');
 
@@ -19,13 +20,25 @@ function isPrintMode(args) {
   return args.includes('-p') || args.includes('--print');
 }
 
+export function resolvePaneOwner(muxName, env = process.env) {
+  if (muxName === 'herdr') {
+    return (env.UNSNOOZE_MUX === 'herdr'
+      ? env.UNSNOOZE_PANE_OWNER : env.HERDR_SESSION || 'default') || null;
+  }
+  if (muxName === 'zellij') {
+    return (env.UNSNOOZE_MUX === 'zellij'
+      ? env.UNSNOOZE_PANE_OWNER : env.ZELLIJ_SESSION_NAME) || null;
+  }
+  return null;
+}
+
 function runUnwatched(agent, args, reason) {
   if (reason) process.stderr.write(`unsnooze: ${reason}\n`);
   const r = spawnSync(agent.bin, args, { stdio: 'inherit', env: { ...process.env, UNSNOOZE_ACTIVE: '1' } });
   return r.status ?? 1;
 }
 
-export function runLauncher(args, agentId = 'claude') {
+export function runLauncher(args, agentId = 'claude', { processBirthFn = processBirth } = {}) {
   const agent = getAgent(agentId);
 
   // Recursion / nested-launch guard: inside an unsnooze-managed session, a
@@ -55,10 +68,29 @@ export function runLauncher(args, agentId = 'claude') {
         file: process.execPath,
         args: [process.argv[1], '_run', agent.id, ...args],
         env: process.env,
+        // Written before the session is used, not after: a launch that dies
+        // halfway still leaves the evidence reap needs to clean up after it.
+        // Without this, reap has no proof of ownership and (correctly) refuses
+        // to delete anything.
+        onSessionCreated: name => recordOwnedSession({ mux: mux.name, name }),
       });
     } catch (err) {
-      // Session creation failed (tmux/zellij binary spawn, unexpected throw).
-      // Never brick the user's `claude`/`codex` — fall back unwatched.
+      // The agent may already be running inside the session: the multiplexer
+      // took the command that starts it and something after that failed. The
+      // unwatched fallback below would then start a SECOND agent — two live
+      // sessions, two sets of edits — from one `unsnooze claude`. Tell the user
+      // how to reach the one that exists instead.
+      if (err instanceof AgentDispatchedError) {
+        process.stderr.write(`unsnooze: ${err.message}\n`);
+        const hint = attachHint(err.mux || mux.name, err.session);
+        if (hint) process.stderr.write(`unsnooze: reattach with: ${hint}\n`);
+        process.stderr.write(`unsnooze: not starting ${agent.id} again — it may already be running.\n`);
+        log(`launchWrapped failed after dispatch: ${err.stack || err}`);
+        return 1;
+      }
+      // Session creation failed before anything could start (binary spawn,
+      // duplicate name, unexpected throw). Never brick the user's
+      // `claude`/`codex` — fall back unwatched.
       const msg = err instanceof SessionCreateError
         ? `${err.message} — running without limit-watch.`
         : `failed to wrap into ${mux.name} (${err.message}) — running without limit-watch.`;
@@ -67,17 +99,32 @@ export function runLauncher(args, agentId = 'claude') {
     }
   }
 
-  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 rawPane = mux.currentPaneId();
+  const paneOwner = resolvePaneOwner(mux.name, process.env);
+  // A backend may know it cannot safely address the pane it is sitting in —
+  // herdr's pane ids are per-server, and an ambient custom socket can point our
+  // commands at a different server's identically-numbered pane. Watching
+  // nothing beats typing into someone else's terminal, so drop to the same
+  // no-pane path a missing pane id already takes: the agent runs normally,
+  // just unwatched, and the user is told why.
+  const addressable = typeof mux.paneAddressable !== 'function' || mux.paneAddressable();
+  if (rawPane && !addressable) {
+    const why = typeof mux.addressabilityReason === 'function'
+      ? mux.addressabilityReason() : `${mux.name} pane ${rawPane} is not safely addressable`;
+    process.stderr.write(`unsnooze: ${why} — running ${agent.id} without limit-watch.\n`);
+    log(`pane ${rawPane} not addressable: ${why}`);
+  }
+  const pane = addressable ? rawPane : null;
   const leaseId = process.env.UNSNOOZE_LEASE_ID || createLeaseId();
   if (pane) {
     // Stamp our own pane (best-effort, tmux only): the identity every later
     // close/inject decision verifies against — pane ids get recycled.
-    if (typeof mux.stampPaneOwner === 'function') {
-      mux.stampPaneOwner(pane, leaseId).catch(() => { /* legacy tmux */ });
+    // Bind to the pane's session first: herdr addresses panes through
+    // `--session`, so an unbound driver cannot write the stamp at all. tmux
+    // ignores the binding.
+    const owner = typeof mux.bind === 'function' ? mux.bind(paneOwner) : mux;
+    if (typeof owner.stampPaneOwner === 'function') {
+      Promise.resolve(owner.stampPaneOwner(pane, leaseId)).catch(() => { /* legacy tmux */ });
     }
     spawnDetached(
       monitorSpawnArgs({ muxName: mux.name, paneOwner, pane, agentId: agent.id, leaseId }),
@@ -98,9 +145,15 @@ export function runLauncher(args, agentId = 'claude') {
   });
   const lease = pane && child.pid ? {
     leaseId, mux: mux.name, paneOwner, pane, agent: agent.id,
-    pid: child.pid, pidBirth: processBirth(child.pid),
+    pid: child.pid, pidBirth: processBirthFn(child.pid),
   } : null;
-  if (lease?.pidBirth) writeLease(lease);
+  // Write it even when the birth timestamp is unavailable. processBirth only
+  // reads /proc on linux and `ps` on darwin, so it is null on Windows and on
+  // any ps failure — and gating the write on it meant a perfectly healthy
+  // agent there got no lease at all. The monitor reads presence to know its
+  // agent is alive; ownership checks stay exactly as strict, because
+  // leaseMatches() still refuses to match a lease with a null birth.
+  if (lease) writeLease(lease);
   const cleanup = () => { if (lease) removeLease(lease, leaseId); };
   return new Promise(resolve => {
     child.on('exit', code => { cleanup(); resolve(code ?? 1); });

package/src/lease.js

@@ -81,8 +81,22 @@ export async function leaseMatches(rec, {
   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;
+  // The birth time is what makes a recycled pid detectable: same number, later
+  // start, different process. Where it is available on both sides it must
+  // match exactly.
+  //
+  // It is not available everywhere. processBirth() reads /proc on linux and
+  // `ps` on darwin and returns null otherwise — on Windows, and on any host
+  // where that call fails. Treating "this host cannot tell me" the same as
+  // "the process is an impostor" meant unsnooze silently refused to resume its
+  // own session there, forever. When neither the lease nor the host can supply
+  // a birth time, fall back to the identity that is still verifiable: the
+  // lease's own fields matched above, the pid is alive, and the pane is alive.
+  // That leaves pid reuse as the only false positive, which is the exposure
+  // every pre-birth-time version of this code already carried.
   const birth = processBirthFn(stored.pid);
-  if (!birth || birth !== stored.pidBirth) return false;
+  const unavailable = birth == null && stored.pidBirth == null;
+  if (!unavailable && (!birth || birth !== stored.pidBirth)) return false;
   try { return await mux.paneAlive(rec.pane); } catch { return false; }
 }
 

package/src/monitor.js

@@ -14,7 +14,7 @@ import { getMultiplexer } from './multiplexer.js';
 import {
   SCRAPE_INTERVAL_MS, PANE_SCAN_LINES, CAPTURE_LINES, EVENTS_DIR,
   EVENT_MARKER_TTL_MS, OVERLOAD_BACKOFF_S, OVERLOAD_JITTER,
-  PROBE_INTERVAL_MS, RESET_MARGIN_MS,
+  PROBE_INTERVAL_MS, RESET_MARGIN_MS, LEASE_GRACE_MS,
 } from './config.js';
 import { detectLimit, isBusy, overloadMatch } from './patterns.js';
 import { getAgent } from './agents/index.js';
@@ -34,11 +34,44 @@ const log = makeLogger('monitor');
 
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
+// When to wake, from a banner's reset line.
+//
+// Exported because the stale-banner clamp below is a policy decision with a
+// boundary, and a boundary that cannot be tested directly gets tested by
+// accident. Pure: everything it depends on is an argument.
+export function resolveResetAt({
+  resetLine, bannerAt, detectedAt, limitType,
+  marginMs = RESET_MARGIN_MS, fallbackMs = PROBE_INTERVAL_MS,
+} = {}) {
+  let { at, source } = resetAtMs(parseResetTime(resetLine), {
+    marginMs,
+    fallbackMs,
+    now: new Date(detectedAt),
+    bannerAt,
+  });
+  // A 5h rolling window can never reset more than ~5h out. A parse far beyond
+  // that means the banner text is stale — e.g. scraped from pane history after
+  // midnight, where an undated clock time resolves to tomorrow. The announced
+  // reset already passed; wake now instead.
+  //
+  // Judge the announced reset itself, not the scheduled wake: resetAtMs adds
+  // the margin to an absolute parse, and counting that margin as part of the
+  // distance condemns legitimate resets near the edge of the window. With a
+  // 60-minute margin a real midnight reset seen at 19:00 is 5h away, but its
+  // wake is 6h away — stale by that test, and wrongly dragged back to 20:00.
+  if (limitType === '5h' && source === 'absolute'
+    && (at - marginMs) > detectedAt + 5.5 * 3_600_000) {
+    at = detectedAt + marginMs;
+  }
+  return { at, source };
+}
+
 export function createMonitor({
   muxName = 'tmux', paneOwner = null, pane, leaseId = null, cwd,
   agent = getAgent('claude'), mux = getMultiplexer(muxName, { owner: paneOwner }),
   scrapeInterval = SCRAPE_INTERVAL_MS, notifier = notify,
   spawner = spawnDetached, versionSkewed = hasVersionSkew, handoffBin = UNSNOOZE_BIN,
+  leaseGraceMs = LEASE_GRACE_MS, startedAt = Date.now(),
 }) {
   const notifyCtx = { mux: muxName, pane, paneOwner };
   let trackedKey = null;      // state key of the record we created
@@ -88,13 +121,8 @@ export function createMonitor({
     };
   }
 
-  function computeReset(resetLine, bannerAt, detectedAt) {
-    return resetAtMs(parseResetTime(resetLine), {
-      marginMs: RESET_MARGIN_MS,
-      fallbackMs: PROBE_INTERVAL_MS,
-      now: new Date(detectedAt),
-      bannerAt,
-    });
+  function computeReset(resetLine, bannerAt, detectedAt, limitType) {
+    return resolveResetAt({ resetLine, bannerAt, detectedAt, limitType });
   }
 
   // §6 first-tick corroboration: only record if a fresh transcript backs it,
@@ -103,6 +131,10 @@ export function createMonitor({
   function isCorroborated(resolved, at, source) {
     if (resolved.via === 'transcript' && resolved.bannerAt != null) return true;
     if (source === 'absolute' && at - RESET_MARGIN_MS > Date.now()) return true;
+    // A model limit carries no time to corroborate — its own remedy hint is
+    // the evidence, and the record only ever probes (never blind-wakes), so
+    // recording it cannot cause a premature resume.
+    if (resolved.limitType === 'model') return true;
     return false;
   }
 
@@ -135,7 +167,7 @@ export function createMonitor({
   async function recordLimit(resetLine, limitType, via) {
     const resolved = resolveBanner(resetLine, limitType);
     const detectedVia = resolved.via || via;
-    const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt);
+    const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt, resolved.limitType);
     let muxSession = null;
     if (typeof mux.sessionForPane === 'function') {
       try { muxSession = await mux.sessionForPane(pane); } catch { muxSession = null; }
@@ -174,7 +206,13 @@ export function createMonitor({
     // is ambiguous when historical records exist for the same address.
     trackedKey = appliedKey;
     log(`pane ${pane}: limit recorded (${resolved.limitType}, via ${detectedVia}), resets ${new Date(at).toISOString()} (${source})`);
-    notifier(`${agent.name} hit a usage limit`, `${cwd} — auto-resume at ${new Date(at).toLocaleTimeString()}`, { context: notifyCtx });
+    if (resolved.limitType === 'model') {
+      notifier(`${agent.name} hit a model limit — needs you`,
+        `${cwd} — switch models (/model) or add credits (/usage-credits); unsnooze wakes it once the banner clears`,
+        { context: notifyCtx });
+    } else {
+      notifier(`${agent.name} hit a usage limit`, `${cwd} — auto-resume at ${new Date(at).toLocaleTimeString()}`, { context: notifyCtx });
+    }
     spawnResumerIfNeeded();
     return { at, source, resolved };
   }
@@ -238,6 +276,18 @@ export function createMonitor({
         log(`pane ${pane}: lease ${leaseId} gone — agent exited, monitor exiting`);
         running = false;
         return;
+      } else if (Date.now() - startedAt > leaseGraceMs) {
+        // No lease has EVER appeared. The launcher spawns us before it spawns
+        // the agent, so an agent that failed to spawn at all (bad bin, instant
+        // crash) leaves us watching a pane that is just the user's shell, with
+        // no lease-gone edge to ever fire. Without this the monitor scrapes
+        // that pane forever, and they pile up one per failed launch.
+        // Deliberately a deadline rather than a tick count: scrapeInterval is
+        // injected as 0 in tests and tunable in production, so N ticks is not
+        // a duration.
+        log(`pane ${pane}: lease ${leaseId} never appeared within ${leaseGraceMs}ms — agent never launched, monitor exiting`);
+        running = false;
+        return;
       }
     }
 
@@ -305,7 +355,7 @@ export function createMonitor({
       if (existing && existing.status === 'stopped') {
         const resolved = resolveBanner(d.resetLine, d.limitType);
         const via = resolved.via || (marker ? 'hook' : 'scrape');
-        const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt);
+        const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt, resolved.limitType);
         maybeUpgrade(existing, at, source, resolved.bannerAt, resolved.limitType, via);
         firstTick = false;
         return;
@@ -317,7 +367,7 @@ export function createMonitor({
         if (firstTick) {
           const resolved = resolveBanner(d.resetLine, d.limitType);
           const detectedVia = resolved.via || via;
-          const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt);
+          const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt, resolved.limitType);
           if (!isCorroborated({ ...resolved, via: detectedVia }, at, source)) {
             log(`pane ${pane}: first tick banner uncorroborated (${source}) — skipping`);
             firstTick = false;