unsnooze 1.20.1 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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.0",
   "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/resumer.js

@@ -999,6 +999,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;
     }