unsnooze 1.20.1 → 1.21.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 1.21.1 — 2026-10-26
+
+A herdr session that is still open is now resumed in its own pane instead of a
+new tab.
+
+### herdr
+
+- When a stopped session has no pane on record (it was detected from its
+  transcript), or its recorded pane is gone, unsnooze now finds the herdr pane
+  already holding that conversation by its session id and resumes there,
+  instead of opening a new tab that duplicated the conversation. If herdr
+  reports the agent there as working, unsnooze waits (#47, #48).
+- unsnooze never guesses. If two panes claim the session, or the pane holding
+  it isn't safe to type into, the stop is marked failed with the reason and
+  one notification. If another unsnooze owns the pane, or herdr can't be
+  read, it counts as a failed attempt, so the stop still ends normally.
+
+## 1.21.0 — 2026-10-24
+
+Codex sub-agents no longer show up as a second, unresumable session, a thread
+Codex Desktop still holds fails once with a reason instead of five times,
+`unsnooze update` works on Windows, and the dashboard can stay out of the way.
+
+### Codex
+
+- A Codex session that spawns multi-agent sub-agents was tracked twice per
+  limit stop: once for the conversation, and once for the sub-agent's own
+  rollout, which Codex refuses to resume. That second record burned five
+  attempts and sent a "gave up" notification on every stop. A sub-agent's stop
+  is now recorded under its parent thread, so one stop is one record (#50).
+- A headless revive of a thread that Codex Desktop still has open fails with
+  "already has an active writer" no matter how often it is retried. unsnooze
+  now stops after the first attempt and tells you to continue the thread in
+  Codex Desktop, or close it there so unsnooze can take over (#49).
+- "Selected model is at capacity" is retried as an overload, like a stream
+  error, instead of leaving the session sitting at the prompt (#46).
+
+### Dashboard
+
+- `unsnooze config set autoDashboard off` (or `UNSNOOZE_AUTO_DASHBOARD=off`)
+  keeps `status`, `usage` and `sessions` in their plain terminal view on a
+  TTY. `unsnooze dashboard` still opens the full dashboard (#54).
+- The daemon and watchers no longer load React and Ink unless the dashboard
+  actually opens, roughly halving their memory use.
+
+### Install and update
+
+- A shell rc file that is a symlink into a dotfiles repository stays a symlink:
+  install, update and uninstall edit the file it points to, and the backups
+  sit next to that file. This also fixes `EPERM` on a link with macOS `uchg`
+  set (#51, #53).
+- `unsnooze update` and `unsnooze doctor` failed on Windows with
+  `spawnSync npm ENOENT`. They now run npm in a way Windows accepts (#49).
+
 ## 1.20.1 — 2026-10-08
 
 `unsnooze help` lists the usage flags in the right place again, and the docs'

package/README.md

@@ -62,6 +62,10 @@ unsnooze usage                # burn rate and time-to-limit, before you hit the
 unsnooze doctor [--fix]       # install health check
 ```
 
+Prefer a text view? Run `unsnooze config set autoDashboard off` to make
+`status`, `usage`, and `sessions` print their terminal view without opening the
+full-screen dashboard. `unsnooze dashboard` still opens it explicitly.
+
 Needs Node ≥ 20.12 on macOS, Linux or Windows. tmux ≥ 3.2, Zellij, herdr ≥ 0.8
 or cmux give pane-level watching; without one, unsnooze runs headless and still
 catches and resumes stops. Every command: [command reference](https://unsnooze.dev/docs/commands/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.20.1",
+  "version": "1.21.1",
   "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, Antigravity, and Cursor CLI sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",

package/src/agents/codex.js

@@ -7,8 +7,9 @@
 // Reset-time tails vary by plan: "try again at 3:51 PM." (same day),
 // "try again at Feb 23rd, 2026 9:01 PM." (cross-day), "Try again in 4 days
 // 20 hours 9 minutes." (older builds), or "Try again later." (no timestamp).
-// Transient errors render "stream error: … retrying 4/5 in 1.4s" and must take
-// the overload path, never the ledger.
+// Transient errors render "stream error: … retrying 4/5 in 1.4s" or "Selected
+// model is at capacity. Please try a different model." (ServerOverloaded, which
+// Codex does not retry itself) and must take the overload path, never the ledger.
 
 import { openSync, readSync, closeSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
@@ -104,8 +105,8 @@ export const patterns = {
     /retrying\s+\d+\/\d+/i,        // internal stream-error retry — don't inject
   ],
   idleRegex: /›/,                  // composer: "› Ask Codex to do anything"
-  overloadPatterns: [/stream error/i, /exceeded retry limit/i],
-  transientPatterns: [/stream error/i, /exceeded retry limit/i],
+  overloadPatterns: [/stream error/i, /exceeded retry limit/i, /model is at capacity/i],
+  transientPatterns: [/stream error/i, /exceeded retry limit/i, /model is at capacity/i],
 };
 
 // A submitted user turn uses the same › glyph as the composer. Only accept
@@ -151,6 +152,19 @@ export function rolloutId(path) {
   return m ? m[1].toLowerCase() : null;
 }
 
+// A multi-agent v2 sub-agent writes its own rollout, in the same cwd, whose
+// session_meta names the thread that spawned it (top-level parent_thread_id,
+// and source.subagent.thread_spawn.parent_thread_id). Codex refuses to resume
+// a sub-agent on its own ("resume the parent first"), so the conversation's
+// resumable id is the parent's (#49, #50).
+export function subagentParent(payload) {
+  const id = payload?.parent_thread_id
+    ?? payload?.source?.subagent?.thread_spawn?.parent_thread_id;
+  return typeof id === 'string' && id ? id : null;
+}
+
+const PARENT_IN_HEAD_RE = new RegExp(`"parent_thread_id"\\s*:\\s*"(${UUID})"`, 'i');
+
 function fileHead(path, bytes = 4096) {
   let fd;
   try {
@@ -186,7 +200,11 @@ export function latestSessionId(cwd, aroundTs = null, sessionsRoot = join(CODEX_
   // JSON-escape the cwd the way it appears inside the meta line.
   const needle = cwd ? JSON.stringify(cwd).slice(1, -1) : null;
   for (const f of files.slice(0, 20)) {
-    if (!needle || fileHead(f.path).includes(needle)) return f.id;
+    const head = fileHead(f.path);
+    if (needle && !head.includes(needle)) continue;
+    // A sub-agent's rollout is usually the newest in the cwd; it names the
+    // pane's conversation through its parent.
+    return head.match(PARENT_IN_HEAD_RE)?.[1] ?? f.id;
   }
   return null;
 }
@@ -228,6 +246,16 @@ export default {
   // resume-now only wakes stopped ones — it would answer "no matching stopped
   // sessions" to the one command the notification told the user to run.
   modelRemedy: 'add credits or raise the spend cap in the ChatGPT workspace (or ask its owner to), then continue the session in Codex',
+  // Revival refusals no retry can fix (codex-cli 0.158–0.163 wording, #49):
+  // another Codex process, usually the Desktop app's app-server, owns the
+  // thread; or the id is a multi-agent v2 sub-agent, resumable only through
+  // its parent.
+  reviveRefusals: [
+    { pattern: /already has an active writer/i,
+      reason: 'the thread is still open in another Codex process (usually Codex Desktop) — continue it there, or close it there so unsnooze can resume it' },
+    { pattern: /cannot resume an unloaded multi-agent v2 sub-agent/i,
+      reason: 'this is a Codex sub-agent thread; it continues when its parent session does' },
+  ],
   // Resume takes the prompt in argv — `codex resume <id> "msg"` starts the turn
   // immediately, nothing to type into the TUI.
   //

package/src/cli.js

@@ -16,7 +16,7 @@ import { queueList } from './prompt-queue.js';
 import {
   shouldUseTui, formatStatusTui, formatSessionsTui, formatPreviewTui, logoBlock,
 } from './tui.js';
-import { shouldUseDashboard, runDashboard } from './dashboard/run.js';
+import { shouldUseDashboard } from './dashboard/gate.js';
 
 function fmtCountdown(ms) {
   if (ms <= 0) return 'due now';
@@ -109,7 +109,10 @@ export async function cmdStatus(args = []) {
     return 0;
   }
   // Interactive TTY → live dashboard (until q). Pipes stay plain.
-  if (shouldUseDashboard()) return runDashboard({ tab: 'status' });
+  if (shouldUseDashboard()) {
+    const { runDashboard } = await import('./dashboard/run.js');
+    return runDashboard({ tab: 'status' });
+  }
 
   const state = readState();
   const sessions = Object.values(state.sessions);
@@ -411,7 +414,10 @@ export async function cmdPreview(rest = [], {
 
 // `unsnooze sessions` — list unsnooze-owned mux sessions with panes + records.
 export async function cmdSessions() {
-  if (shouldUseDashboard()) return runDashboard({ tab: 'sessions' });
+  if (shouldUseDashboard()) {
+    const { runDashboard } = await import('./dashboard/run.js');
+    return runDashboard({ tab: 'sessions' });
+  }
   const owned = await listOwnedSessions();
   if (shouldUseTui()) {
     console.log(formatSessionsTui(owned, { color: true }));

package/src/dashboard/gate.js

@@ -0,0 +1,20 @@
+// Keep the dashboard decision separate from React/Ink. Watchers import CLI and
+// usage helpers, so they must be able to check this without loading the UI.
+import { getConfig } from '../settings.js';
+
+export function shouldUseDashboard({
+  force = null,
+  json = false,
+  isTTY = process.stdout?.isTTY && process.stdin?.isTTY,
+  env = process.env,
+  automatic = true,
+} = {}) {
+  if (force === true) return true;
+  if (force === false) return false;
+  if (automatic && !getConfig('autoDashboard')) return false;
+  if (json) return false;
+  if (env.NO_COLOR != null && env.NO_COLOR !== '') return false;
+  if (env.CI === 'true' || env.CI === '1') return false;
+  if (env.TERM === 'dumb') return false;
+  return !!isTTY;
+}

package/src/dashboard/run.js

@@ -4,6 +4,9 @@ import { render } from 'ink';
 import { App } from './App.js';
 import { MOUSE_DISABLE_ALL } from './mouse-protocol.js';
 import { getConfig } from '../settings.js';
+import { shouldUseDashboard } from './gate.js';
+
+export { shouldUseDashboard } from './gate.js';
 
 const h = React.createElement;
 
@@ -97,23 +100,8 @@ export function startTimingSweep({ intervalMs = TIMING_SWEEP_MS, perf } = {}) {
   };
 }
 
-export function shouldUseDashboard({
-  force = null,
-  json = false,
-  isTTY = process.stdout?.isTTY && process.stdin?.isTTY,
-  env = process.env,
-} = {}) {
-  if (force === true) return true;
-  if (force === false) return false;
-  if (json) return false;
-  if (env.NO_COLOR != null && env.NO_COLOR !== '') return false;
-  if (env.CI === 'true' || env.CI === '1') return false;
-  if (env.TERM === 'dumb') return false;
-  return !!isTTY;
-}
-
 export async function runDashboard({ tab = 'status' } = {}) {
-  if (!shouldUseDashboard()) {
+  if (!shouldUseDashboard({ automatic: false })) {
     console.error('unsnooze dashboard: requires an interactive TTY (not a pipe/CI).');
     // Still show the brand so users see the logo even when falling back
     const { logoPlainText } = await import('./Logo.js');

package/src/dashboard/tabs/PromptsTab.js

@@ -19,10 +19,7 @@ const h = React.createElement;
 
 // -- small local helpers ---------------------------------------------------
 
-// Duplicated from cli.js's shortenHome rather than imported: cli.js pulls in
-// this dashboard module transitively (cli.js -> dashboard/run.js -> App.js),
-// so importing it back here would be a real import cycle, not just a scary
-// one. Five lines is cheaper than untangling that.
+// Keep this local so the dashboard does not import the full CLI command graph.
 function shortenCwd(p) {
   if (typeof p !== 'string' || !p) return p;
   const home = homedir();

package/src/doctor.js

@@ -20,6 +20,7 @@ import { fishConfigPath } from './fish.js';
 import { listAgents } from './agents/index.js';
 import { getConfig } from './settings.js';
 import { resolveBin } from './which.js';
+import { runNpm } from './update-check.js';
 import { CLAUDE_DIR, CODEX_DIR } from './config.js';
 
 const log = makeLogger('doctor');
@@ -35,9 +36,9 @@ function isCsgUnit(content) {
   return /claude-session-guard/.test(content) && !/unsnooze\.js|com\.unsnooze/.test(content);
 }
 
-function defaultRunner(cmd, args) {
+function defaultRunner(cmd, args, opts = {}) {
   try {
-    return spawnSync(cmd, args, { encoding: 'utf-8' });
+    return spawnSync(cmd, args, { encoding: 'utf-8', ...opts });
   } catch (err) {
     return { status: 1, stdout: '', error: err };
   }
@@ -90,7 +91,7 @@ export function defaultCsgPackagePath({
   execPathRoots = [join(dirname(dirname(process.execPath)), 'lib', 'node_modules')],
 } = {}) {
   const roots = [];
-  const r = runner('npm', ['root', '-g']);
+  const r = runNpm(['root', '-g'], {}, { runner });
   if (!r.error && r.status === 0 && r.stdout) roots.push(String(r.stdout).trim());
   roots.push(...execPathRoots);   // nvm/unix prefix layout fallback when npm is slow/absent
   for (const root of roots) {

package/src/install.js

@@ -11,7 +11,7 @@
 // --settings <path> / --zshrc <path> / --fishrc <path> override targets (used
 // by tests).
 
-import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync, unlinkSync, lstatSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir, userInfo } from 'node:os';
 import { join, dirname, basename, delimiter } from 'node:path';
@@ -52,20 +52,37 @@ function parseArgs(rest) {
   return opts;
 }
 
+function resolveWriteTarget(path) {
+  let target = path;
+  try {
+    if (lstatSync(path).isSymbolicLink()) target = realpathSync(path);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  return target;
+}
+
 function atomicWrite(path, content) {
-  mkdirSync(dirname(path), { recursive: true });   // e.g. ~/.claude may not exist yet
-  const tmp = join(dirname(path), `.${Date.now()}.tmp`);
+  // Shell rc files are sometimes symlinks into a dotfiles repository. Rename
+  // over the link would replace it (and fails when the link has macOS uchg),
+  // so atomically replace the real file while leaving the link itself intact.
+  const target = resolveWriteTarget(path);
+  mkdirSync(dirname(target), { recursive: true });   // e.g. ~/.claude may not exist yet
+  const tmp = join(dirname(target), `.${Date.now()}.tmp`);
   writeFileSync(tmp, content);
-  renameSync(tmp, path);
+  renameSync(tmp, target);
 }
 
 // Two backup tiers: `.unsnooze-orig` is the pristine pre-unsnooze snapshot,
 // written exactly once (a re-run must never overwrite it with an already-
 // modified file); `.unsnooze-bak` rolls forward on every run.
 function backupOnce(path) {
-  const orig = `${path}.unsnooze-orig`;
-  if (!existsSync(orig)) copyFileSync(path, orig);
-  copyFileSync(path, `${path}.unsnooze-bak`);
+  const target = resolveWriteTarget(path);
+  const orig = `${target}.unsnooze-orig`;
+  const backup = `${target}.unsnooze-bak`;
+  if (!existsSync(orig)) copyFileSync(target, orig);
+  copyFileSync(target, backup);
+  return backup;
 }
 
 // --- settings.json hook management ---
@@ -621,7 +638,7 @@ function qwenSettingsPath() {
 export function installQwenHooks() {
   const path = qwenSettingsPath();
   if (existsSync(path)) {
-    copyFileSync(path, `${path}.unsnooze-bak`);
+    copyFileSync(path, `${resolveWriteTarget(path)}.unsnooze-bak`);   // beside the file a symlink points at, like backupOnce
     atomicWrite(path, mergeHookIntoSettings(readFileSync(path, 'utf-8'), QWEN_HOOK_OPTS));
   } else {
     atomicWrite(path, mergeHookIntoSettings('{}', QWEN_HOOK_OPTS));
@@ -675,10 +692,10 @@ export function cmdInstall(rest, { agents = enabledAgents() } = {}) {
   //    when installed below).
   if (agents.includes('claude')) {
     if (existsSync(opts.settings)) {
-      backupOnce(opts.settings);
+      const backup = backupOnce(opts.settings);
       const before = readFileSync(opts.settings, 'utf-8');
       atomicWrite(opts.settings, mergeHookIntoSettings(before));
-      console.log(`unsnooze: StopFailure hook installed in ${opts.settings} (backup: ${opts.settings}.unsnooze-bak)`);
+      console.log(`unsnooze: StopFailure hook installed in ${opts.settings} (backup: ${backup})`);
     } else {
       atomicWrite(opts.settings, mergeHookIntoSettings('{}'));
       console.log(`unsnooze: created ${opts.settings} with StopFailure hook`);

package/src/multiplexers/herdr.js

@@ -524,15 +524,17 @@ export function createHerdr({ spawner = defaultSpawner, env = process.env } = {}
       },
 
       async listSessions() {
-        try {
-          const result = parseResult(await run(['session', 'list', '--json']));
-          const rows = Array.isArray(result?.sessions) ? result.sessions : [];
-          return rows
-            .filter(row => typeof row?.name === 'string' && row.name)
-            .map(row => ({ name: row.name, exited: row.running === false }));
-        } catch {
-          return [];
-        }
+        try { return await backend.readSessions(); } catch { return []; }
+      },
+
+      // listSessions, but a failed `session list` throws instead of reading as
+      // "no sessions".
+      async readSessions() {
+        const result = parseResult(await run(['session', 'list', '--json']));
+        const rows = Array.isArray(result?.sessions) ? result.sessions : [];
+        return rows
+          .filter(row => typeof row?.name === 'string' && row.name)
+          .map(row => ({ name: row.name, exited: row.running === false }));
       },
 
       async listSessionPanes(sessionName) {
@@ -544,6 +546,37 @@ export function createHerdr({ spawner = defaultSpawner, env = process.env } = {}
         }
       },
 
+      // Every live pane, in every running session, whose agent reports this
+      // conversation id. herdr tracks `agent_session` per pane, so this finds a
+      // session that is still open somewhere even when unsnooze never recorded
+      // its pane (transcript-only detection) or recorded a stale id. The cwd is
+      // deliberately not consulted: several conversations share a repository.
+      async findSessionPanes(sessionId, { agent = null } = {}) {
+        if (!sessionId) return [];
+        const found = [];
+        let failure = null;
+        for (const row of await backend.readSessions()) {
+          if (row.exited) continue;
+          let panes;
+          try { panes = await listPaneRows(row.name); } catch (err) { failure ??= err; continue; }
+          for (const entry of panes) {
+            const identity = entry?.agent_session;
+            if (!identity || identity.value !== sessionId || !entry.pane_id) continue;
+            if (agent && identity.agent !== agent) continue;
+            found.push({
+              pane: String(entry.pane_id),
+              paneOwner: row.name,
+              status: entry.agent_status ?? null,
+              stamp: entry.tokens?.unsnooze_owner ?? null,
+            });
+          }
+        }
+        // An unreadable session may hold the conversation (or a second pane
+        // for it): a partial answer must not read as "no other pane".
+        if (failure) throw failure;
+        return found;
+      },
+
       async closePane(pane) {
         await owned('pane', 'close', String(pane));
       },

package/src/resumer.js

@@ -598,6 +598,28 @@ export async function planFor(rec, {
       + ' knows its session id — reviving both would clone the conversation');
     return { ...base, action: 'superseded', target: { key: superseded.key } };
   }
+  const { matches, failed } = await lookupExistingPane(rec, agent, mux);
+  if (failed) {
+    gates.push('existing-pane lookup failed — dispatch counts it as a failed attempt');
+    return { ...base, action: 'retry', target: { pane: rec.pane } };
+  }
+  if (matches.length > 1) {
+    gates.push(`${matches.length} panes claim this session — would mark failed and notify rather than guess`);
+    return { ...base, action: 'give-up' };
+  }
+  if (matches.length === 1) {
+    const [hit] = matches;
+    if (foreignStamp(hit, rec)) {
+      gates.push(`existing pane ${hit.paneOwner}:${hit.pane} is owned by another unsnooze — left to it, dispatch counts it as a failed attempt`);
+      return { ...base, action: 'retry', target: { pane: hit.pane } };
+    }
+    if (hit.status === 'working') {
+      gates.push(`existing pane ${hit.paneOwner}:${hit.pane} holds this session and herdr reports it working — deferring`);
+      return { ...base, action: 'busy', target: { pane: hit.pane } };
+    }
+    gates.push(`found existing pane ${hit.paneOwner}:${hit.pane} by session id — would resume there if idle (no new tab)`);
+    return { ...base, action: 'inject', target: { pane: hit.pane, session: hit.paneOwner }, message };
+  }
   const target = await reviveTarget(mux, rec);
   // The same argv reopen() builds: on a backend with no pane the prompt rides
   // in argv, and for codex the command itself changes (`exec resume`).
@@ -609,12 +631,113 @@ export async function planFor(rec, {
   };
 }
 
+// An existing pane that already holds this conversation, found by agent
+// session id (never by cwd). Only multiplexers that expose findSessionPanes
+// (herdr) can answer; a record with no recorded mux is also tried against herdr
+// when it is installed, since transcript detection never learns the pane —
+// unless its origin is a GUI app, which herdr cannot be hosting.
+const GUI_ORIGIN = /desktop|vscode|jetbrains|ide/i;
+
+function existingPaneFinder(rec, mux) {
+  if (!rec.sessionId) return null;
+  if (typeof mux?.findSessionPanes === 'function') return mux;
+  // Transcript records carry the default backend's name but no pane.
+  if (rec.mux && rec.mux !== 'herdr' && rec.pane) return null;
+  if (rec.origin && GUI_ORIGIN.test(rec.origin)) return null;
+  try {
+    const herdr = getMultiplexer('herdr');
+    return herdr.available() ? herdr : null;
+  } catch { return null; }
+}
+
+async function lookupExistingPane(rec, agent, mux) {
+  const finder = existingPaneFinder(rec, mux);
+  if (!finder) return { finder: null, matches: [] };
+  try {
+    return { finder, matches: await finder.findSessionPanes(rec.sessionId, { agent: agent.id }) };
+  } catch (err) {
+    log(`${rec.key}: existing-pane lookup failed: ${err.message}`);
+    return { finder, matches: [], failed: err };
+  }
+}
+
+// A pane stamped by a different unsnooze owner is tracked (and will be
+// resumed) by that owner: another launcher on this box, or a fleet host.
+function foreignStamp(hit, rec) {
+  return Boolean(hit.stamp) && hit.stamp !== rec.leaseId;
+}
+
+function giveUpOnExistingPane(rec, reason, notifier = notify) {
+  if (!transitionStopEpisode(rec, 'failed', {
+    lastError: reason, verifyRetries: 0, resumeEpisodeAt: null,
+  }, { expect: ['stopped'] })) return 'stale';
+  log(`${rec.key}: ${reason}`);
+  notifier('unsnooze needs you ⚠️', `${rec.cwd}: ${reason}`, { context: ctxOf(rec), priority: 4 });
+  return 'skipped';
+}
+
+// Point the stop at the pane that already holds the conversation so the normal
+// live-pane gates (busy, menu, idle prompt, ownership) decide what happens.
+// Adopted only when the pane carries no unsnooze stamp or this record's own;
+// identity is then the exact agent session id plus the agent still running in
+// the pane (a shell is refused downstream). Returns { rec, mux } to resume
+// into, a dispatch outcome when this stop ends here, or null to reopen.
+async function adoptExistingPane(rec, agent, mux, notifier) {
+  const { finder, matches, failed } = await lookupExistingPane(rec, agent, mux);
+  if (failed) {
+    // Charged as an attempt, so a herdr that keeps failing reaches the normal
+    // give-up path instead of silently holding the record.
+    if (!transitionStopEpisode(rec, 'stopped', {
+      lastError: `existing-pane lookup: ${failed.message}`,
+    }, { expect: ['stopped'] })) return { outcome: 'stale' };
+    return { outcome: 'retry' };
+  }
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    const panes = matches.map(m => `${m.paneOwner}:${m.pane}`).join(', ');
+    return { outcome: giveUpOnExistingPane(rec,
+      `found ${matches.length} herdr panes for this session (${panes}) — not guessing, resume it by hand`, notifier) };
+  }
+  const [hit] = matches;
+  if (foreignStamp(hit, rec)) {
+    // Not typed into, and charged as an attempt: if that owner never resumes
+    // it, the normal give-up path still ends the stop.
+    if (!transitionStopEpisode(rec, 'stopped', {
+      lastError: `existing pane ${hit.paneOwner}:${hit.pane} is owned by another unsnooze — left to it`,
+    }, { expect: ['stopped'] })) return { outcome: 'stale' };
+    return { outcome: 'retry' };
+  }
+  // herdr's own agent status catches a busy agent the screen scrape can miss.
+  if (hit.status === 'working') return { outcome: 'busy' };
+  // Already pointed at it and it was not safe to resume: a new tab would clone it.
+  if (hit.pane === rec.pane && hit.paneOwner === rec.paneOwner) {
+    return { outcome: giveUpOnExistingPane(rec,
+      `herdr pane ${hit.paneOwner}:${hit.pane} holds this session but is not safe to type into — resume it there by hand`, notifier) };
+  }
+  const cutoff = stopEpisodeAt(rec);
+  let adopted = null;
+  updateState(state => {
+    const current = state.sessions[rec.key];
+    if (current?.status !== 'stopped' || stopEpisodeAt(current) !== cutoff) return state;
+    Object.assign(current, {
+      mux: 'herdr', pane: hit.pane, paneOwner: hit.paneOwner, muxSession: hit.paneOwner,
+      leaseId: hit.stamp,
+    });
+    adopted = { ...current };
+    return state;
+  });
+  if (!adopted) return null;
+  log(`${rec.key}: found existing herdr pane ${hit.paneOwner}:${hit.pane} by session id — resuming there`);
+  return { rec: adopted, mux: finder.bind ? finder.bind(hit.paneOwner) : finder };
+}
+
 // Ordered safety decision. Returns: already-resumed | busy | retry | progress |
 // held | injected | reopen | probe.
 export async function dispatchOne(rec, {
   mux = resolveRecordMux(rec), resolveMux = null,
   resumeMessage, selfCmd = selfCommand(), fingerprint = workspaceFingerprint,
   notifier = notify, matchesLease = leaseMatches, contextTokens = null,
+  adoptExisting = true, adopted = false,
 } = {}) {
   resolveMux ||= () => mux;
   const key = rec.key;
@@ -626,6 +749,8 @@ export async function dispatchOne(rec, {
   // explicit option → per-agent (`resumeMessages.<id>`) → global. Applies to
   // both the live-pane sendText and the argv reopen path.
   resumeMessage = rec.resumeMessage ?? resumeMessage ?? resolveResumeMessage(agent.id);
+  // Guards below suffix the message; an adopted-pane retry re-runs them from the original.
+  const baseMessage = resumeMessage;
 
   // §4: fallback records probe cheaply before a real resume attempt.
   if (rec.resetSource === 'fallback' && !rec.manual) {
@@ -677,12 +802,40 @@ export async function dispatchOne(rec, {
   const notifyContext = () => {
     if (contextNote) notifier('unsnooze: big-context wake', contextNote, { context: ctxOf(rec) });
   };
-  const reopenGuarded = () =>
-    reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onDelivered: notifyContext });
+  let a = null;
+  // Before opening a new tab, look for the conversation's own pane. The
+  // retry re-enters with adoptExisting off so it cannot loop.
+  const reopenGuarded = async () => {
+    // An adopted pane that is not safe to type into (a shell, a refused menu)
+    // still holds the conversation: a new tab would clone it.
+    if (adopted) {
+      if (!a?.alive) {
+        // Closed between lookup and assessment: retry, the next lookup decides.
+        if (!transitionStopEpisode(rec, 'stopped', {
+          lastError: `existing pane ${rec.paneOwner}:${rec.pane} closed before resume`,
+        }, { expect: ['stopped'] })) return 'stale';
+        return 'retry';
+      }
+      const why = agent.isForegroundCommand(a.cmd) ? 'is not safe to type into' : 'no longer runs the agent';
+      return giveUpOnExistingPane(rec,
+        `herdr pane ${rec.paneOwner}:${rec.pane} holds this session but ${why} — resume it there by hand`, notifier);
+    }
+    if (adoptExisting) {
+      const found = await adoptExistingPane(rec, agent, mux, notifier);
+      if (found?.outcome) return found.outcome;
+      if (found) {
+        return dispatchOne(found.rec, {
+          mux: found.mux, resolveMux, resumeMessage: baseMessage, selfCmd,
+          fingerprint, notifier, matchesLease, contextTokens, adoptExisting: false, adopted: true,
+        });
+      }
+    }
+    return reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onDelivered: notifyContext });
+  };
 
   // Live-pane path: classification comes from the shared assessPane (planFor
   // narrates the identical assessment); dispatch owns every side effect.
-  const a = await assessPane(rec, agent, { mux, matchesLease });
+  a = await assessPane(rec, agent, { mux, matchesLease });
   if (a.alive) {
     if (a.captureError) {
       if (!transitionStopEpisode(rec, 'stopped', {
@@ -999,6 +1152,22 @@ export async function verifyOne(key, { resolveMux = resolveRecordMux } = {}) {
         : outcome.signal ? `killed by ${outcome.signal}` : 'failed to start';
       const why = outcome.output || outcome.error || '';
       const lastError = `revive died before it could resume (${how}${why ? `: ${why}` : ''})`;
+      // Some refusals are structural: the same launch fails the same way on
+      // every attempt (Codex Desktop still holding the thread, #49). Retrying
+      // them only burns the attempts and ends in a vague give-up, so stop now
+      // and say what the user has to do.
+      const refusal = (agent.reviveRefusals || []).find(r => r.pattern.test(why));
+      if (refusal) {
+        if (!transitionStopEpisode(rec, 'failed', {
+          attempts, lastError: `${refusal.reason} (${how})`, verifyRetries: 0, resumeEpisodeAt: null,
+        }, { expect: ['resuming'] })) {
+          releaseSupersededResume(key);
+          return 'stale';
+        }
+        log(`${key}: ${lastError} — not retrying: ${refusal.reason}`);
+        notify('unsnooze can\'t resume this one ⚠️', `${rec.cwd}: ${refusal.reason}`, { context: ctxOf(rec), priority: 4 });
+        return 'held';
+      }
       const applied = transitionStopEpisode(rec, 'stopped', {
         attempts,
         // Same backoff (and same manual exemption) as every other retry.

package/src/settings.js

@@ -34,6 +34,7 @@ export const DEFAULTS = {
   // Pre-wall usage warnings (1.13): daemon notifies at % bands + ETA tiers.
   usageWarn: 'notify',     // off | notify
   usageWarnAt: '80,95',    // % thresholds (comma-separated); garbage → default
+  autoDashboard: true,    // status/usage/sessions open dashboard on a TTY
   mouse: true,             // dashboard mouse support (click tabs/rows, wheel scroll)
   // Opt-in: auto-close `resumed` panes idle longer than reapIdleAfter (ms).
   // Off by default — an idle revived TUI is indistinguishable from one the
@@ -84,6 +85,7 @@ const ENV_NAMES = {
   contextGuardTokens: 'UNSNOOZE_CONTEXT_GUARD_TOKENS',
   usageWarn: 'UNSNOOZE_USAGE_WARN',
   usageWarnAt: 'UNSNOOZE_USAGE_WARN_AT',
+  autoDashboard: 'UNSNOOZE_AUTO_DASHBOARD',
   mouse: 'UNSNOOZE_MOUSE',
   reapResumed: 'UNSNOOZE_REAP_RESUMED',
   reapIdleAfter: 'UNSNOOZE_REAP_IDLE_AFTER',

package/src/update-check.js

@@ -247,16 +247,33 @@ export function installPrefix({ root = ROOT, platform = process.platform, exists
   return exists(path.join(prefix, 'bin', 'unsnooze')) ? prefix : null;
 }
 
+// How to run npm. On Windows `npm` is `npm.cmd`, which spawnSync cannot run
+// without a shell (bare `npm` is ENOENT, `npm.cmd` is EINVAL since Node's
+// CVE-2024-27980 fix, #49). Run the npm-cli.js that ships beside node.exe
+// directly instead: no shell, so a prefix with spaces needs no quoting. A
+// node without a bundled npm falls back to `npm.cmd` through the shell.
+export function npmCommand({ platform = process.platform, execPath = process.execPath, exists = existsSync } = {}) {
+  if (platform !== 'win32') return { file: 'npm', pre: [], opts: {} };
+  const cli = win32.join(win32.dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  if (exists(cli)) return { file: execPath, pre: [cli], opts: {} };
+  return { file: 'npm.cmd', pre: [], opts: { shell: true }, quote: true };
+}
+
+export function runNpm(args, opts = {}, { runner = spawnSync, npm = npmCommand() } = {}) {
+  const argv = npm.quote ? args.map(a => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)) : args;
+  return runner(npm.file, [...npm.pre, ...argv], { ...npm.opts, ...opts });
+}
+
 // `unsnooze update` — self-update via npm, then show what changed. With
 // --prefix pointed at this copy's own prefix, npm -g overwrites this install
 // in place, so re-reading package.json/CHANGELOG.md after a successful
 // install yields the NEW version's info.
-export function runSelfUpdate({ runner = spawnSync, print = console.log, root = ROOT, current = PKG_VERSION } = {}) {
+export function runSelfUpdate({ runner = spawnSync, print = console.log, root = ROOT, current = PKG_VERSION, npm = npmCommand() } = {}) {
   const prefix = installPrefix({ root });
   const args = ['install', '-g', ...(prefix ? ['--prefix', prefix] : []), 'unsnooze@latest'];
   const command = ['npm', ...args].map(a => (/\s/.test(a) ? `"${a}"` : a)).join(' ');
   print(`unsnooze ${current} — updating via ${command} …`);
-  const r = runner('npm', args, { stdio: 'inherit' });
+  const r = runNpm(args, { stdio: 'inherit' }, { runner, npm });
   if (r.error || r.status !== 0) {
     print(`unsnooze: update failed (${r.error ? r.error.message : `npm exited ${r.status}`}).`);
     print(`unsnooze: try it manually: ${command}`);

package/src/usage.js

@@ -17,7 +17,7 @@ import { readState, updateState } from './state.js';
 import { getConfig } from './settings.js';
 import { ROLLOUT_RE, rolloutId } from './agents/codex.js';
 import { shouldUseTui, formatUsageTui, bar as tuiBar } from './tui.js';
-import { shouldUseDashboard, runDashboard } from './dashboard/run.js';
+import { shouldUseDashboard } from './dashboard/gate.js';
 
 // ---------------------------------------------------------------------------
 // Constants & pure math
@@ -1441,7 +1441,10 @@ export async function cmdUsage(args = []) {
 
   const asJson = args.includes('--json');
   // Interactive TTY (human path) → live dashboard Usage tab
-  if (!asJson && shouldUseDashboard()) return runDashboard({ tab: 'usage' });
+  if (!asJson && shouldUseDashboard()) {
+    const { runDashboard } = await import('./dashboard/run.js');
+    return runDashboard({ tab: 'usage' });
+  }
   try {
     const now = Date.now();
     const state = readState();

package/src/watchers/codex.js

@@ -32,7 +32,7 @@
 
 import { openSync, readSync, closeSync, statSync } from 'node:fs';
 import { basename } from 'node:path';
-import { ROLLOUT_RE, rolloutPathFor, patterns as codexPatterns } from '../agents/codex.js';
+import { ROLLOUT_RE, rolloutPathFor, subagentParent, patterns as codexPatterns } from '../agents/codex.js';
 import { detectLimit } from '../patterns.js';
 // Usage extractor lives in usage.js (shared cold path + daemon); re-exported
 // here so the plan's watcher surface is the documented import site.
@@ -332,7 +332,9 @@ function readFirstLine(path, maxBytes = 256 * 1024) {
 }
 
 // Session identity for a rollout file: the session_meta head line when
-// parseable, else the uuid embedded in the filename.
+// parseable, else the uuid embedded in the filename. A sub-agent's rollout
+// resolves to its parent thread, so its stop merges with the conversation's
+// own record instead of tracking a second, unresumable one (#50).
 export function rolloutMeta(path) {
   let sessionId = null;
   let cwd = null;
@@ -340,7 +342,7 @@ export function rolloutMeta(path) {
   try {
     const meta = JSON.parse(readFirstLine(path));
     if (meta?.type === 'session_meta') {
-      sessionId = meta.payload?.id || null;
+      sessionId = subagentParent(meta.payload) || meta.payload?.id || null;
       cwd = meta.payload?.cwd || null;
       originator = meta.payload?.originator || null;
     }