unsnooze 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 1.10.0 — 2026-07-14
+
+- **Session-name ownership** (fix: interactive `claude` dying with
+  `duplicate session: unsnooze`): the interactive launcher owns the base name
+  `unsnooze` (and `unsnooze-2`… on collision); the resumer daemon may join a
+  live session but only ever **creates** `unsnooze-resumed`. Records now
+  discover the live mux session via `sessionForPane` instead of freezing the
+  load-time `MUX_SESSION_NAME` constant. tmux `newWindow` returns
+  `paneOwner: null` (pane ids are server-global). Uninstall stops the resumer.
+  Failed session creation degrades to an unwatched agent CLI instead of
+  bricking `claude`/`codex`. New: `unsnooze sessions`, `unsnooze reap
+  [--dry-run|--yes]`; optional `reapResumed` / `reapIdleAfter`. Zellij revival
+  uses `--close-on-exit` and closes the default shell pane left by
+  `attach -b -c`. Env: `UNSNOOZE_SESSION_NAME`, `UNSNOOZE_RESUME_SESSION`.
+- **Reset-time accuracy** (fix: blind `now + 5h` fallback and +24h rollover
+  of already-past clock times): reset times are anchored to the banner's own
+  timestamp (`bannerAt`), not the scrape moment. Claude stops prefer the dated
+  transcript entry over an undated pane scrape. An absolute clock time already
+  past relative to wall clock means the limit already reset (due now), not
+  tomorrow. Compact durations like `1h 30m` sum all tokens. Unparseable banners
+  probe cheaply (`PROBE_INTERVAL_MS`, backoff to `PROBE_MAX_MS`) instead of
+  sleeping five hours; hard ceiling remains `FALLBACK_RESET_MS`. Monitor first
+  tick requires corroboration; later ticks can upgrade a weak estimate.
+  `unsnooze status` shows provenance (`absolute, from transcript` vs
+  `guessed: no reset time found — probing`).
+- **Upgrade-safe state migration** for existing installs: `tmuxSession` →
+  `muxSession` (unchanged), bogus tmux `paneOwner` values cleared so leases
+  match again, old blind `fallback` waits beyond the probe ladder are pulled
+  into the first probe window (absolute/relative schedules untouched),
+  `TMUX_SESSION_NAME` alias kept, `reapResumed` defaults off, new config keys
+  only add defaults (existing `config.json` keeps working without edits).
+
 ## 1.9.0 — 2026-07-13
 
 - **Context-size guard** (`contextGuard`: `off` | `inform` | `pause`, default

package/README.md

@@ -171,6 +171,8 @@ unsnooze status                 # tracked sessions + reset countdowns
 unsnooze resume-now [id|--all]  # don't wait for the reset time
 unsnooze cancel [id|--all]      # stop tracking a session
 unsnooze message <id> "text"    # per-session wake message (--clear to reset)
+unsnooze sessions               # list unsnooze-owned mux sessions + panes
+unsnooze reap [--dry-run|--yes] # close finished panes / empty sessions (default dry-run)
 unsnooze config list            # settings (see below)
 unsnooze config set <k> <v>     # e.g. autoResume off
 unsnooze logs [-f]              # what unsnooze has been doing
@@ -202,11 +204,28 @@ unsnooze help                   # full command list (also -h / --help)
 | `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. |
 | `contextGuard` | `inform` | Big cold context at wake? Waking a session re-reads its **entire context at full uncached price** ([why](#why-did-resuming-a-big-session-eat-so-much-of-my-quota)). `inform` resumes and notifies you of the size; `pause` holds sessions above the threshold for `unsnooze resume-now`; `off` disables. Claude Code only for now. |
 | `contextGuardTokens` | `100000` | Context-size threshold (tokens) at which `contextGuard` notifies or holds. |
+| `reapResumed` | `false` | Opt-in: auto-close `resumed` panes idle longer than `reapIdleAfter`. Off by default — use `unsnooze reap --yes` for explicit cleanup. |
+| `reapIdleAfter` | `604800000` (7d) | Idle age (ms) before an opt-in auto-reap closes a `resumed` pane. |
 | `updateCheck` | `true` | Daily new-version check (a plain GET to the npm registry, nothing identifying is sent). Notices after commands + one desktop toast per version. |
 
 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`).
 
+### Multiplexer session names
+
+Interactive launches own the base session name (default **`unsnooze`**); a second
+concurrent terminal takes `unsnooze-2`, etc. The resumer daemon may **join** a
+live session but only ever **creates** `unsnooze-resumed`, so a revived agent
+never steals the interactive name.
+
+| env | default | meaning |
+|---|---|---|
+| `UNSNOOZE_SESSION_NAME` | `unsnooze` | Interactive base session name (also accepts legacy `UNSNOOZE_TMUX_SESSION`). |
+| `UNSNOOZE_RESUME_SESSION` | `<base>-resumed` | Session the daemon creates when the pane's original session is gone. |
+
+Find revived agents with `unsnooze status` (prints an attach hint when the
+session is live), `unsnooze sessions`, or e.g. `tmux attach -t unsnooze-resumed`.
+
 ### Notification channels
 
 When a limit is hit, a session resumes, or unsnooze gives up, it can alert you

package/bin/unsnooze.js

@@ -6,7 +6,7 @@ const [, , cmd, ...rest] = process.argv;
 
 // Only human-facing commands may print update notices — never the wrapper
 // passthrough, hooks, or daemons (their output lands in agent panes/logs).
-const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'help', '-h', '--help', '--help-unsnooze']);
+const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'sessions', 'reap', 'help', '-h', '--help', '--help-unsnooze']);
 
 async function maybeUpdateNotices() {
   try {
@@ -56,6 +56,14 @@ async function main() {
       const { cmdConfig } = await import('../src/cli.js');
       return cmdConfig(rest);
     }
+    case 'sessions': {
+      const { cmdSessions } = await import('../src/cli.js');
+      return cmdSessions();
+    }
+    case 'reap': {
+      const { cmdReap } = await import('../src/cli.js');
+      return cmdReap(rest);
+    }
     case 'install': {
       const { cmdInstall } = await import('../src/install.js');
       return cmdInstall(rest);
@@ -119,6 +127,9 @@ Usage:
   unsnooze resume-now [id|--all]   resume stopped session(s) immediately
   unsnooze cancel [id|--all]       stop tracking session(s)
   unsnooze message <id|--all> <t>  set a per-session wake message (--clear to reset)
+  unsnooze sessions                list unsnooze-owned mux sessions + panes
+  unsnooze reap [--dry-run|--yes]  close terminal-record panes / empty sessions
+                                   (default: dry-run; pass --yes to apply)
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Auto-resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode & Antigravity when the 5-hour/weekly usage limit resets — tmux, Zellij, VS Code & desktop apps. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -1,4 +1,4 @@
-// User-facing subcommands: status, resume-now, cancel, logs, config.
+// User-facing subcommands: status, resume-now, cancel, logs, config, sessions, reap.
 
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -8,6 +8,8 @@ import { getAgent } from './agents/index.js';
 import { approxTokens } from './sessions.js';
 import { getConfig, setConfigValue, listConfig, CONFIG_FILE } from './settings.js';
 import { spawnResumerIfNeeded } from './spawn.js';
+import { getMultiplexer } from './multiplexer.js';
+import { listOwnedSessions, reap, attachHint } from './reap.js';
 
 function fmtCountdown(ms) {
   if (ms <= 0) return 'due now';
@@ -17,7 +19,20 @@ function fmtCountdown(ms) {
   return `${h}h ${m % 60}m`;
 }
 
-export function cmdStatus() {
+
+// Surface how the reset estimate was derived so a silent wrong guess can't hide.
+export function fmtResetProvenance(s) {
+  if (s.resetSource === 'fallback' || !s.resetSource) {
+    return 'guessed: no reset time found — probing';
+  }
+  const via = s.detectedVia === 'transcript' ? 'transcript'
+    : s.detectedVia === 'hook' ? 'hook'
+    : s.detectedVia === 'scrape' ? 'scrape'
+    : null;
+  return via ? `${s.resetSource}, from ${via}` : s.resetSource;
+}
+
+export async function cmdStatus() {
   const state = readState();
   const sessions = Object.values(state.sessions);
   const paused = !getConfig('autoResume');
@@ -30,7 +45,10 @@ export function cmdStatus() {
   console.log(`unsnooze: ${sessions.length} tracked session(s)  (resumer pid: ${state.resumerPid ?? 'not running'})${pausedNote}\n`);
   for (const s of sessions.sort((a, b) => (a.resetAt || 0) - (b.resetAt || 0))) {
     const id = s.sessionId ? s.sessionId.slice(0, 8) : '(no id)';
-    const reset = s.resetAt ? `${new Date(s.resetAt).toLocaleString()} (${fmtCountdown(s.resetAt - now)})` : '?';
+    const when = s.resetAt
+      ? `${new Date(s.resetAt).toLocaleString()} (${fmtCountdown(s.resetAt - now)})`
+      : '?';
+    const reset = `${when} (${fmtResetProvenance(s)})`;
     const origin = s.origin ?? (s.pane ? 'cli' : '?');
     const pane = s.paneOwner ? `${s.paneOwner}:${s.pane ?? '-'}` : (s.pane ?? '-');
     const msg = s.resumeMessage
@@ -47,8 +65,19 @@ export function cmdStatus() {
         if (t != null) ctx = ` · ctx ${approxTokens(t)} tok`;
       } catch { /* estimate unavailable — omit */ }
     }
+    // Attach hint when the mux session the record points at is still live.
+    let attach = '';
+    if (s.muxSession) {
+      try {
+        const mux = getMultiplexer(s.mux || 'tmux');
+        if (typeof mux.sessionExists === 'function' && await mux.sessionExists(s.muxSession)) {
+          const hint = attachHint(s.mux, s.muxSession);
+          if (hint) attach = ` · attach: ${hint}`;
+        }
+      } catch { /* mux unavailable — omit */ }
+    }
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}`);
+    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}${attach}`);
   }
   return 0;
 }
@@ -174,3 +203,56 @@ export function cmdConfig(rest) {
     return 1;
   }
 }
+
+// `unsnooze sessions` — list unsnooze-owned mux sessions with panes + records.
+export async function cmdSessions() {
+  const owned = await listOwnedSessions();
+  if (owned.length === 0) {
+    console.log('unsnooze: no unsnooze-owned mux sessions found.');
+    return 0;
+  }
+  console.log(`unsnooze: ${owned.length} mux session(s)\n`);
+  for (const s of owned) {
+    const flag = s.exited ? 'EXITED' : 'live';
+    const panes = s.panes.length ? s.panes.join(', ') : '(none)';
+    console.log(`  [${flag.padEnd(6)}] ${s.mux}  ${s.name}  panes: ${panes}`);
+    if (s.attach) console.log(`              attach: ${s.attach}`);
+    for (const r of s.records) {
+      console.log(`              · ${r.status} ${(r.agent || '?').padEnd(6)} ${r.cwd || '?'} pane ${r.pane ?? '-'}`);
+    }
+  }
+  return 0;
+}
+
+// `unsnooze reap [--dry-run|--yes]` — close terminal-record panes and empty/
+// EXITED unsnooze sessions. Default is dry-run.
+export async function cmdReap(rest = []) {
+  // Default dry-run unless --yes.
+  const yes = rest.includes('--yes');
+  const result = await reap({ dryRun: !yes, yes });
+  if (result.actions.length === 0) {
+    console.log(result.dryRun
+      ? 'unsnooze reap (dry-run): nothing to do.'
+      : 'unsnooze reap: nothing to do.');
+    return 0;
+  }
+  const prefix = result.dryRun ? 'unsnooze reap (dry-run)' : 'unsnooze reap';
+  console.log(`${prefix}: ${result.actions.length} action(s)\n`);
+  for (const a of result.actions) {
+    if (a.kind === 'close-pane') {
+      console.log(`  close pane ${a.mux} ${a.paneOwner ? `${a.paneOwner}:` : ''}${a.pane} (record ${a.key})`);
+    } else if (a.kind === 'delete-session') {
+      console.log(`  delete session ${a.mux} ${a.name} (${a.reason})`);
+    } else if (a.kind === 'drop-record') {
+      console.log(`  drop record ${a.key} (${a.reason})`);
+    } else if (a.kind === 'error') {
+      console.log(`  error: ${a.key || a.name}: ${a.message}`);
+    } else {
+      console.log(`  ${a.kind}: ${JSON.stringify(a)}`);
+    }
+  }
+  if (result.dryRun) {
+    console.log('\nRe-run with --yes to apply.');
+  }
+  return 0;
+}

package/src/config.js

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

package/src/hook.js

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

package/src/install.js

@@ -16,7 +16,7 @@ import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
 import { getConfig, configFileExists } from './settings.js';
 import { xmlEscape } from './notify.js';
 import { installGrokHooks, uninstallGrokHooks } from './agents/grok.js';
-import { UNSNOOZE_BIN } from './spawn.js';
+import { UNSNOOZE_BIN, stopResumer } from './spawn.js';
 
 const FENCE_OPEN = '# >>> unsnooze >>>';
 const FENCE_CLOSE = '# <<< unsnooze <<<';
@@ -341,6 +341,16 @@ export function cmdUninstall(rest) {
   const opts = parseArgs(rest);
   const explicitRc = rest.includes('--zshrc');
 
+  // Stop the resumer/daemon first so it cannot keep writing state after hooks
+  // are gone (zombie-daemon-running-deleted-code failure mode).
+  try {
+    const result = stopResumer();
+    if (result.stopped) console.log(`unsnooze: resumer stopped (pid ${result.pid})`);
+    else if (result.reason === 'stale') console.log('unsnooze: stale resumer lock cleared');
+  } catch (err) {
+    console.log(`unsnooze: could not stop resumer (${err.message})`);
+  }
+
   if (existsSync(opts.settings)) {
     const before = readFileSync(opts.settings, 'utf-8');
     atomicWrite(opts.settings, removeHookFromSettings(before));

package/src/launcher.js

@@ -11,6 +11,7 @@ import { getConfig } from './settings.js';
 import { spawnDetached } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { createLeaseId, processBirth, writeLease, removeLease } from './lease.js';
+import { SessionCreateError } from './multiplexers/session-name.js';
 
 const log = makeLogger('launcher');
 
@@ -18,6 +19,12 @@ function isPrintMode(args) {
   return args.includes('-p') || args.includes('--print');
 }
 
+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') {
   const agent = getAgent(agentId);
 
@@ -39,15 +46,25 @@ export function runLauncher(args, agentId = 'claude') {
       } else {
         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;
+      return runUnwatched(agent, args);
     }
     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,
-    });
+    try {
+      // A returned status is the agent's (or session's) exit — never re-run.
+      return mux.launchWrapped({
+        file: process.execPath,
+        args: [process.argv[1], '_run', agent.id, ...args],
+        env: process.env,
+      });
+    } catch (err) {
+      // Session creation failed (tmux/zellij binary spawn, 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.`;
+      log(`launchWrapped failed: ${err.stack || err}`);
+      return runUnwatched(agent, args, msg);
+    }
   }
 
   const pane = mux.currentPaneId();

package/src/monitor.js

@@ -14,14 +14,15 @@ 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,
-  FALLBACK_RESET_MS, RESET_MARGIN_MS, MUX_SESSION_NAME,
+  PROBE_INTERVAL_MS, RESET_MARGIN_MS,
 } from './config.js';
 import { detectLimit, isBusy, overloadMatch } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { getConfig } from './settings.js';
 import { notify } from './notify.js';
-import { parseResetTime, resetAtMs } from './time-parser.js';
-import { upsertSession, setStatus, readState } from './state.js';
+import { parseResetTime, resetAtMs, sourceRank } from './time-parser.js';
+import { upsertSession, setStatus, readState, updateState } from './state.js';
+import { latestRateLimitFromTranscript } from './watchers/claude.js';
 import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { addressHash } from './lease.js';
@@ -40,6 +41,7 @@ export function createMonitor({
   let overloadAttempt = 0;
   let terminalNotified = false;   // one notification per terminal-error appearance
   let running = true;
+  let firstTick = true;           // §6: don't inherit a previous session's banner
 
   function markerPath() {
     return join(EVENTS_DIR, `${addressHash({ mux: muxName, paneOwner, pane })}.json`);
@@ -56,27 +58,102 @@ export function createMonitor({
     }
   }
 
-  async function recordLimit(resetLine, limitType, via) {
+  // Prefer a dated transcript entry when the agent keeps one (claude).
+  function resolveBanner(paneResetLine, paneLimitType) {
     const detectedAt = Date.now();
-    const { at, source } = resetAtMs(parseResetTime(resetLine), {
-      marginMs: RESET_MARGIN_MS, fallbackMs: FALLBACK_RESET_MS,
+    const sessionId = agent.latestSessionId?.(cwd, detectedAt) || null;
+    const fromTx = latestRateLimitFromTranscript(cwd, sessionId, { now: detectedAt });
+    if (fromTx) {
+      return {
+        resetLine: fromTx.resetLine ?? paneResetLine,
+        limitType: fromTx.limitType && fromTx.limitType !== 'unknown' ? fromTx.limitType : paneLimitType,
+        bannerAt: fromTx.timestampMs,
+        sessionId: fromTx.sessionId || sessionId,
+        via: 'transcript',
+        detectedAt,
+      };
+    }
+    return {
+      resetLine: paneResetLine,
+      limitType: paneLimitType,
+      bannerAt: null,
+      sessionId,
+      via: null,   // filled by caller (scrape/hook)
+      detectedAt,
+    };
+  }
+
+  function computeReset(resetLine, bannerAt, detectedAt) {
+    return resetAtMs(parseResetTime(resetLine), {
+      marginMs: RESET_MARGIN_MS,
+      fallbackMs: PROBE_INTERVAL_MS,
+      now: new Date(detectedAt),
+      bannerAt,
+    });
+  }
+
+  // §6 first-tick corroboration: only record if a fresh transcript backs it,
+  // or an absolute clock time resolves to a still-future instant (not the
+  // "already past → due now" path, which is margin above wall clock only).
+  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;
+    return false;
+  }
+
+  // §7: upgrade a weak estimate (fallback/relative) when a better value
+  // becomes available. A strictly better source (e.g. fallback→absolute)
+  // always wins — absolute is truth even if later than a probe guess.
+  // Same-or-worse source may only pull the wake earlier, never push it later.
+  function maybeUpgrade(existing, at, source, bannerAt, limitType, via) {
+    if (!existing || existing.status !== 'stopped') return false;
+    const oldRank = sourceRank(existing.resetSource);
+    const newRank = sourceRank(source);
+    const betterSource = newRank > oldRank;
+    const earlier = at < existing.resetAt;
+    if (!betterSource && !earlier) return false;
+    if (!betterSource && at > existing.resetAt) return false;
+    updateState(state => {
+      const s = state.sessions[existing.key];
+      if (!s || s.status !== 'stopped') return;
+      s.resetAt = at;
+      s.resetSource = source;
+      if (bannerAt != null) s.bannerAt = bannerAt;
+      if (limitType && limitType !== 'unknown') s.limitType = limitType;
+      if (via) s.detectedVia = via;
+      if (source !== 'fallback') delete s.probeCount;
     });
-    const sessionId = agent.latestSessionId(cwd, detectedAt);
+    log(`pane ${pane}: upgraded reset ${existing.resetSource}→${source} at ${new Date(at).toISOString()}`);
+    return true;
+  }
+
+  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);
+    let muxSession = null;
+    if (typeof mux.sessionForPane === 'function') {
+      try { muxSession = await mux.sessionForPane(pane); } catch { muxSession = null; }
+    }
     const state = upsertSession({
-      sessionId, cwd, pane, mux: muxName, paneOwner, leaseId,
-      agent: agent.id, muxSession: MUX_SESSION_NAME,
-      status: 'stopped', limitType, detectedVia: via, detectedAt,
+      sessionId: resolved.sessionId, cwd, pane, mux: muxName, paneOwner, leaseId,
+      agent: agent.id, muxSession,
+      status: 'stopped', limitType: resolved.limitType, detectedVia,
+      detectedAt: resolved.detectedAt,
+      bannerAt: resolved.bannerAt,
       resetAt: at, resetSource: source,
       attempts: 0, lastAttemptAt: null, lastError: null,
+      ...(source === 'fallback' ? { probeCount: 0 } : {}),
     });
-    trackedKey = sessionId
+    trackedKey = resolved.sessionId
       || Object.values(state.sessions).find(s => s.mux === muxName
         && s.paneOwner === paneOwner && s.pane === pane
         && ['stopped', 'resuming', 'resumed'].includes(s.status))?.key
       || null;
-    log(`pane ${pane}: limit recorded (${limitType}, via ${via}), resets ${new Date(at).toISOString()}`);
+    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 });
     spawnResumerIfNeeded();
+    return { at, source, resolved };
   }
 
   async function driveMenu(text) {
@@ -150,9 +227,11 @@ export function createMonitor({
           log(`pane ${pane}: limit menu detected but menuAutoAnswer is off — recording only`);
           await recordLimit(d.hit ? d.resetLine : null, d.hit ? d.limitType : 'unknown', 'scrape');
         }
+        firstTick = false;
         return;
       }
       await driveMenu(visible);
+      firstTick = false;
       return;
     }
 
@@ -160,9 +239,37 @@ export function createMonitor({
     if (d.hit) {
       const state = readState();
       const existing = trackedKey && state.sessions[trackedKey];
+
+      // §7: still-stopped records can upgrade a weak estimate.
+      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);
+        maybeUpgrade(existing, at, source, resolved.bannerAt, resolved.limitType, via);
+        firstTick = false;
+        return;
+      }
+
       if (!existing || existing.status !== 'stopped') {
-        await recordLimit(d.resetLine, d.limitType, marker ? 'hook' : 'scrape');
+        const via = marker ? 'hook' : 'scrape';
+        // §6: first tick needs corroboration so we don't inherit a leftover banner.
+        if (firstTick) {
+          const resolved = resolveBanner(d.resetLine, d.limitType);
+          const detectedVia = resolved.via || via;
+          const { at, source } = computeReset(resolved.resetLine, resolved.bannerAt, resolved.detectedAt);
+          if (!isCorroborated({ ...resolved, via: detectedVia }, at, source)) {
+            log(`pane ${pane}: first tick banner uncorroborated (${source}) — skipping`);
+            firstTick = false;
+            return;
+          }
+          // Reuse recordLimit path; resolveBanner is idempotent enough.
+          await recordLimit(d.resetLine, d.limitType, via);
+          firstTick = false;
+          return;
+        }
+        await recordLimit(d.resetLine, d.limitType, via);
       }
+      firstTick = false;
       return;
     }
 
@@ -202,6 +309,8 @@ export function createMonitor({
     } else if (!marker && overloadMatch(text, agent.patterns.overloadPatterns) && !isBusy(text, agent.patterns.busyPatterns)) {
       await handleOverload();
     }
+
+    firstTick = false;
   }
 
   return {
@@ -216,6 +325,7 @@ export function createMonitor({
     stop() { running = false; },
     _tick: tick,   // exposed for tests
     get trackedKey() { return trackedKey; },
+    get _firstTick() { return firstTick; },
   };
 }