unsnooze 1.19.0 → 1.19.2

package/src/spawn.js

@@ -1,22 +1,78 @@
 // Detached-process helpers shared by launcher, hook, and monitor.
 
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import {
+  existsSync, readFileSync, unlinkSync, writeFileSync, statSync, utimesSync, openSync, closeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { join, dirname } from 'node:path';
-import { RESUMER_LOCK } from './config.js';
+import { RESUMER_LOCK, DAEMON_ON_DEMAND, DAEMON_PIDFILE, STATE_DIR, ensureStateDir } from './config.js';
 import { makeLogger } from './logger.js';
 
 const log = makeLogger('spawn');
 
 export const UNSNOOZE_BIN = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin', 'unsnooze.js');
 
-export function spawnDetached(args, env = {}) {
-  const child = spawn(process.execPath, [UNSNOOZE_BIN, ...args], {
+// Variables that describe one agent session rather than the user. Claude Code
+// sets the first group for every command and hook it runs, and CLAUDECODE is
+// its nested-session guard: a claude started with it set refuses to run
+// ("cannot be launched inside another Claude Code session"). The launcher sets
+// the second group for the agent it wraps. A process that outlives the session
+// that started it must carry neither, because every revival it launches
+// inherits its environment. User configuration — CLAUDE_CONFIG_DIR,
+// CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_GIT_BASH_PATH, TMUX — is kept.
+const SESSION_ENV = new Set([
+  'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CLAUDE_CODE_CHILD_SESSION', 'CLAUDE_CODE_SSE_PORT',
+  'CLAUDE_CODE_SESSION_ID', 'CLAUDE_SESSION_ID', 'CLAUDE_PROJECT_DIR', 'CLAUDE_ENV_FILE',
+  'UNSNOOZE_ACTIVE', 'UNSNOOZE_MUX', 'UNSNOOZE_PANE', 'UNSNOOZE_PANE_OWNER', 'UNSNOOZE_LEASE_ID',
+  'UNSNOOZE_CWD',
+]);
+
+// Windows environment names are case-insensitive, and a copied process.env
+// keeps whatever case the variable was set with.
+export function standaloneEnv(env = process.env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!SESSION_ENV.has(key.toUpperCase())) out[key] = value;
+  }
+  return out;
+}
+
+// spawnDetached's options, apart so they can be tested without a child.
+// `standalone` is for processes that outlive the session that started them —
+// the daemon and a transient resumer: no session markers, and the home
+// directory rather than the project the session happened to be in (on Windows
+// a live process's working directory cannot be deleted or renamed, so a
+// daemon started from a project would pin that folder until sign-out).
+export function detachedSpawnOptions({ env = {}, standalone = false, logFd = null } = {}) {
+  return {
     detached: true,
-    stdio: 'ignore',
-    env: { ...process.env, ...env },
-  });
+    stdio: logFd == null ? 'ignore' : ['ignore', logFd, logFd],
+    env: { ...(standalone ? standaloneEnv() : process.env), ...env },
+    ...(standalone ? { cwd: homedir() } : {}),
+  };
+}
+
+// `logFile` appends the child's stdout/stderr to a file instead of discarding
+// them: a daemon with no supervisor to capture its output would otherwise leave
+// no trace of a crash.
+export function spawnDetached(args, env = {}, { standalone = false, logFile = null, execPath = process.execPath } = {}) {
+  let logFd = null;
+  if (logFile) {
+    try { logFd = openSync(logFile, 'a', 0o600); } catch { /* no log, not no child */ }
+  }
+  let child;
+  try {
+    child = spawn(execPath, [UNSNOOZE_BIN, ...args], detachedSpawnOptions({ env, standalone, logFd }));
+  } finally {
+    // The child has its own copy of the descriptor.
+    if (logFd != null) { try { closeSync(logFd); } catch { /* already closed */ } }
+  }
+  // spawn() reports ENOENT, EACCES, EAGAIN and EMFILE as an 'error' event after
+  // it has returned. Unheard, that is an uncaught exception in the caller —
+  // the launcher, with the user's agent already running.
+  child.on('error', err => log(`could not start ${args[0]}: ${err.message}`));
   child.unref();
   return child.pid;
 }
@@ -51,7 +107,9 @@ export function spawnResumerIfNeeded() {
       if (Number.isFinite(pid) && pidAlive(pid)) return null;
     }
   } catch { /* unreadable lock — let the daemon sort it out */ }
-  const pid = spawnDetached(['_resumer']);
+  // Standalone: it is spawned from inside a session (the hook, a pane's
+  // monitor) and outlives it, and a headless revival inherits its environment.
+  const pid = spawnDetached(['_resumer'], {}, { standalone: true });
   log(`spawned resumer pid ${pid}`);
   return pid;
 }
@@ -63,7 +121,8 @@ export function stopResumer() {
   try {
     if (!existsSync(RESUMER_LOCK)) return { stopped: false, pid: null, reason: 'no-lock' };
     pid = parseInt(readFileSync(RESUMER_LOCK, 'utf-8'), 10);
-    if (Number.isFinite(pid) && pidAlive(pid)) {
+    // A stale lock can name a recycled pid — this very process included.
+    if (Number.isFinite(pid) && pid !== process.pid && pidAlive(pid)) {
       try { process.kill(pid, 'SIGTERM'); } catch { /* raced with exit */ }
       log(`stopped resumer pid ${pid}`);
       try { unlinkSync(RESUMER_LOCK); } catch { /* gone */ }
@@ -77,3 +136,197 @@ export function stopResumer() {
     return { stopped: false, pid, reason: err.message };
   }
 }
+
+// --- the on-demand daemon (native Windows) ----------------------------------
+// launchd and systemd keep the daemon alive on macOS and Linux. Windows gets no
+// equivalent, on purpose — see DAEMON_ON_DEMAND in config.js — so there the
+// daemon is an ordinary background process that the wrappers and the
+// StopFailure hook start whenever it is not running.
+
+// How often a running daemon refreshes its pidfile, and how old the refresh may
+// be before the file stops counting as proof of life. Five missed beats, so a
+// busy moment is never mistaken for death. A machine waking from a long sleep
+// can briefly look daemon-less; the worst that does is start a second daemon,
+// which the first yields to on its next beat (claimDaemon).
+export const DAEMON_HEARTBEAT_MS = 60_000;
+export const DAEMON_STALE_MS = 5 * DAEMON_HEARTBEAT_MS;
+
+function readPidfile(path) {
+  try { return parseInt(readFileSync(path, 'utf-8'), 10); } catch { return NaN; }
+}
+
+// The pid of the daemon that is demonstrably running, else null. A live pid
+// alone proves nothing on Windows: pids are recycled quickly, and a sign-out or
+// a crash leaves the file behind to name whichever process gets that pid next.
+// The daemon touches the file every minute, so a stale one is ignored whoever
+// its pid belongs to now.
+export function runningDaemonPid({ path = DAEMON_PIDFILE, now = Date.now(), alive = pidAlive } = {}) {
+  const pid = readPidfile(path);
+  if (!alive(pid)) return null;
+  try {
+    return now - statSync(path).mtimeMs <= DAEMON_STALE_MS ? pid : null;
+  } catch {
+    return null;   // vanished between the read and the stat
+  }
+}
+
+// `wx` creates the file a moment before the claimant's pid is written into it.
+// A file that young with no pid yet is somebody mid-claim, not a leftover.
+const CLAIM_GRACE_MS = 2_000;
+
+function midClaim(path, now = Date.now()) {
+  try {
+    return readFileSync(path, 'utf-8').trim() === '' && now - statSync(path).mtimeMs < CLAIM_GRACE_MS;
+  } catch {
+    return false;
+  }
+}
+
+// The daemon's half of the pidfile. Starters race — a wrapper and the hook can
+// both find no daemon and both start one — so each new daemon claims the file,
+// and a daemon that finds a live one already there stands down before doing
+// anything. `wx` like the resumer lock; a stale file is replaced. Returns a
+// release() for shutdown, or null when this daemon must not run.
+//
+// While held, the heartbeat keeps the claim fresh, and calls onLost() — the
+// daemon should exit — once the file names another pid (this daemon looked
+// dead through a long sleep and a newer one took over, or two claims raced:
+// one daemon, whichever claimed last), once the file has been missing on two
+// beats in a row (one unreadable moment, say an antivirus scan, is not proof),
+// or once wanted() says the daemon is no longer asked for.
+export function claimDaemon({
+  path = DAEMON_PIDFILE, pid = process.pid, running = runningDaemonPid,
+  heartbeatMs = DAEMON_HEARTBEAT_MS, onLost = () => {}, wanted = () => true,
+  lock = RESUMER_LOCK,
+} = {}) {
+  ensureStateDir(dirname(path));
+  let claimed = false;
+  for (let attempt = 0; attempt < 2 && !claimed; attempt++) {
+    try {
+      writeFileSync(path, String(pid), { flag: 'wx', mode: 0o600 });
+      claimed = true;
+    } catch {
+      const previous = readPidfile(path);
+      const holder = running({ path });
+      if (holder === pid) claimed = true;
+      else if (holder) {
+        log(`daemon pid ${holder} is already running — pid ${pid} not starting another`);
+        return null;
+      } else if (midClaim(path)) {
+        log(`another daemon is claiming ${path} — pid ${pid} not starting another`);
+        return null;
+      } else {
+        // The previous daemon is gone: dead, or its pid now someone else's.
+        // TerminateProcess and sign-out skip its cleanup, so the resumer lock
+        // it held still names that pid — and on Windows, where the holder
+        // cannot be checked with ps, a recycled pid there would be honored
+        // forever and no resume would ever run again.
+        if (Number.isFinite(previous) && readPidfile(path) === previous && readPidfile(lock) === previous) {
+          try { unlinkSync(lock); } catch { /* released meanwhile */ }
+          log(`cleared the resumer lock left by daemon pid ${previous}`);
+        }
+        try { unlinkSync(path); } catch { /* raced with another claimant */ }
+      }
+    }
+  }
+  if (!claimed) {
+    log(`could not claim ${path} — pid ${pid} not starting`);
+    return null;
+  }
+  let misses = 0;
+  const beat = setInterval(() => {
+    const named = readPidfile(path);
+    let why = null;
+    if (!wanted()) why = 'it is no longer wanted';
+    else if (Number.isFinite(named) && named !== pid) why = `${path} now names pid ${named}`;
+    else if (!Number.isFinite(named) && ++misses >= 2) why = `${path} is gone`;
+    if (why) {
+      clearInterval(beat);
+      log(`daemon pid ${pid} standing down: ${why}`);
+      onLost();
+      return;
+    }
+    if (Number.isFinite(named)) {
+      misses = 0;
+      try { const t = new Date(); utimesSync(path, t, t); } catch { /* the next beat retries */ }
+    }
+  }, heartbeatMs);
+  beat.unref();
+  return () => {
+    clearInterval(beat);
+    if (readPidfile(path) === pid) {
+      try { unlinkSync(path); } catch { /* already gone */ }
+    }
+  };
+}
+
+// Is the on-demand daemon still asked for? `install --daemon` writes the
+// marker and `uninstall` removes it.
+export function onDemandWanted(marker = DAEMON_ON_DEMAND) {
+  return existsSync(marker);
+}
+
+// Where the on-demand daemon's own stdout/stderr go — the file launchd writes
+// them to elsewhere, which bin/unsnooze.js rotates when the daemon starts.
+const DAEMON_LOG = join(STATE_DIR, 'daemon.log');
+
+function spawnOnDemandDaemon(args) {
+  return spawnDetached(args, {}, { standalone: true, logFile: DAEMON_LOG });
+}
+
+// Start the daemon unless it is already running — native Windows only, and
+// only once `unsnooze install --daemon` has asked for it (the marker). The
+// wrappers and the StopFailure hook call this, and between them they run
+// whenever an agent does, so the daemon is back soon after a sign-in without
+// anything registered to start at logon. Never throws: it sits on the launch
+// path, where a failure must cost the daemon and nothing else.
+//
+// --on-demand ties the daemon to the marker: it exits when the marker goes
+// (uninstall), where a daemon somebody runs by hand keeps running.
+export function ensureDaemon({
+  platform = process.platform, marker = DAEMON_ON_DEMAND,
+  running = runningDaemonPid, spawner = spawnOnDemandDaemon,
+} = {}) {
+  try {
+    if (platform !== 'win32' || !existsSync(marker) || running()) return null;
+    const pid = spawner(['daemon', '--on-demand']);
+    log(`daemon not running — started it on demand (pid ${pid})`);
+    return pid;
+  } catch (err) {
+    log(`could not start the daemon on demand: ${err.message}`);
+    return null;
+  }
+}
+
+// Stop the on-demand daemon (uninstall, and the restart `install --daemon`
+// does). Only a daemon proven live by its heartbeat is signalled — a stale
+// file's pid may be anybody's by now — and never this process, which a pid
+// recycled inside the heartbeat window could be. The file goes either way, so
+// a live daemon too stale to prove itself stands down at its next beats.
+// Returns the pid that was signalled, or null.
+export function stopDaemon({
+  path = DAEMON_PIDFILE, running = runningDaemonPid, lock = RESUMER_LOCK,
+  kill = (pid, signal) => process.kill(pid, signal),
+} = {}) {
+  const found = running({ path });
+  const pid = found === process.pid ? null : found;
+  if (pid) {
+    try { kill(pid, 'SIGTERM'); } catch { /* raced with its exit */ }
+    log(`stopped daemon pid ${pid}`);
+    // On Windows that was TerminateProcess: nothing of the daemon's own ran,
+    // so a resumer lock it held still names it (see claimDaemon).
+    if (readPidfile(lock) === pid) {
+      try { unlinkSync(lock); } catch { /* already gone */ }
+    }
+  }
+  try { unlinkSync(path); } catch { /* none to remove */ }
+  return pid;
+}
+
+// What `install --daemon` does on Windows, as launchctl unload+load does on
+// macOS: a daemon already running keeps the code and PATH it started with, so
+// re-running setup is how a user hands it new ones.
+export function restartDaemon() {
+  stopDaemon();
+  return ensureDaemon();
+}

package/src/time-parser.js

@@ -278,7 +278,12 @@ export function resetAtMs(parsed, {
       }
       return t;   // unreachable in practice — 9 steps cover a week + DST repeat
     }
-    if (t <= anchor) {
+    // A clock time names a whole minute. Codex prints the reset as %-I:%M and
+    // drops the seconds, so a dated banner written at 7:36:15 that says "try
+    // again at 7:36 AM" means a reset later in that same minute — not 7:36
+    // tomorrow, a day late. Only a minute that had fully passed rolls.
+    const past = bannerAt != null ? t + 60_000 <= anchor : t <= anchor;
+    if (past) {
       // Dated banner, or ambiguous (need both am/pm candidates as real
       // next-occurrences): roll to the next day. Undated non-ambiguous
       // past clock times stay past so the outer guard returns due-now

package/src/usage.js

@@ -15,7 +15,7 @@ import {
 } from './config.js';
 import { readState, updateState } from './state.js';
 import { getConfig } from './settings.js';
-import { ROLLOUT_RE } from './agents/codex.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';
 
@@ -343,18 +343,17 @@ export function calibrationStopCount(calibration, agent, limitType, pool = null)
   return n;
 }
 
-// Clamp spikes (>100) and one-tick stale regressions that jump >15pp upward
-// without intermediate samples (Codex can briefly report stale/overshoot %).
-export function smoothUsedPercent(current, previous) {
+// Clamp an exact reading to [0, 100]; fall back to the previous one when the
+// current is unparseable. Nothing else: the value is the server's own number
+// (Codex copies it out of a response header, the Claude statusline hands it
+// over verbatim), and there is no client-side estimate in it to smooth. This
+// used to average a >15pp jump with the previous sample "for one tick" — but
+// the report recomputes from the last two samples, and at the moment a user is
+// blocked no further sample ever arrives, so a real 99% sat at 64% for the rest
+// of the window and never crossed the 80/95 warn thresholds (#20 follow-up).
+export function clampUsedPercent(current, previous) {
   if (!Number.isFinite(current)) return Number.isFinite(previous) ? previous : null;
-  let v = current;
-  if (v > 100) v = 100;
-  if (v < 0) v = 0;
-  if (Number.isFinite(previous) && v > previous + 15 && previous < 95) {
-    // Soft-cap upward spike: average with previous for one tick
-    v = (v + previous) / 2;
-  }
-  return v;
+  return Math.min(100, Math.max(0, current));
 }
 
 // Dominant model-pool among samples (for Max per-bucket calibration).
@@ -428,7 +427,7 @@ export function recordExactPctSample(store, exactClaude, { now = Date.now(), kee
   if (last && last.pct === pct && now - last.at < 30_000) return store;
   arr.push({
     at: now,
-    pct: smoothUsedPercent(pct, last?.pct),
+    pct: clampUsedPercent(pct, last?.pct),
     resetsAtMs: normalizeResetsAtMs(exactClaude.fiveHour.resets_at),
   });
   store.exactPct.claude5h = arr
@@ -475,13 +474,23 @@ export function pctSpaceEta(history, {
   };
 }
 
-export function extractCodexUsage(line) {
+// `rollout` is the uuid of the file the line came from (rolloutId()). A
+// snapshot is only comparable with the previous snapshot of the SAME thread:
+// Codex emits one token_count line per response per rate-limit bucket, every
+// line carries the thread's last-known snapshot, and threads (Desktop tabs,
+// sub-agents) interleave on disk — so "the machine's second-newest line" can be
+// another thread's minutes-old reading, or another bucket entirely.
+export function extractCodexUsage(line, { rollout = null } = {}) {
   if (!line || !line.trim()) return null;
   let entry;
   try { entry = JSON.parse(line); } catch { return null; }
   if (entry?.type !== 'event_msg' || entry.payload?.type !== 'token_count') return null;
   const rl = entry.payload.rate_limits;
   if (!rl || typeof rl !== 'object') return null;
+  // Only the account bucket feeds the 5h/weekly lines. Codex defaults a missing
+  // limit_id to "codex"; `premium`, `codex_other` and friends are separate
+  // meters with their own windows and must not be read as this one moving.
+  if (rl.limit_id != null && rl.limit_id !== 'codex') return null;
 
   function win(w) {
     if (!w || typeof w !== 'object') return null;
@@ -501,12 +510,29 @@ export function extractCodexUsage(line) {
   return {
     agent: 'codex',
     at: ts,
+    rollout: rollout || null,
     primary,
     secondary: win(rl.secondary),
     planType: rl.plan_type || null,
   };
 }
 
+// The reading to measure `latest` against: the newest earlier sample from the
+// same rollout. Samples recorded before the rollout was carried (an older
+// daemon's store) fall back to the newest earlier sample of any origin.
+// Strictly earlier: the dashboard hands over the daemon's store and a cold
+// scan of the same files, so `latest`'s own copy sits right before it — and a
+// zero-length interval read as "idle" for as long as the daemon ran.
+export function previousCodexSample(sorted, latest) {
+  const idx = sorted.lastIndexOf(latest);
+  for (let i = (idx === -1 ? sorted.length : idx) - 1; i >= 0; i--) {
+    const s = sorted[i];
+    if (s.at >= latest.at) continue;
+    if (latest.rollout == null || s.rollout == null || s.rollout === latest.rollout) return s;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Storage
 // ---------------------------------------------------------------------------
@@ -821,17 +847,19 @@ export function buildUsageReport({
 
   // --- Codex ---
   {
-    const latest = [...codexSamples].sort((a, b) => a.at - b.at).at(-1);
-    const prev = codexSamples.length >= 2
-      ? [...codexSamples].sort((a, b) => a.at - b.at).at(-2)
-      : null;
+    const sorted = [...codexSamples].sort((a, b) => a.at - b.at);
+    const latest = sorted.at(-1);
+    const prev = latest ? previousCodexSample(sorted, latest) : null;
     if (latest?.primary) {
       const windows = [];
       for (const key of ['primary', 'secondary']) {
         const w = latest[key];
         if (!w) continue;
-        const prevW = prev?.[key];
-        const pct = smoothUsedPercent(w.usedPercent, prevW?.usedPercent);
+        // A window that changed size between the two readings is not the same
+        // window; its old reading says nothing about this one's movement.
+        const candidate = prev?.[key];
+        const prevW = candidate && candidate.windowMinutes === w.windowMinutes ? candidate : null;
+        const pct = clampUsedPercent(w.usedPercent, prevW?.usedPercent);
         const label = w.label || labelWindow(w.windowMinutes);
         // %-space burn for ETA on the primary/short window only
         let burn = { idle: true, burnPerMin: 0, activeMin: 0, warmingUp: false };
@@ -1107,8 +1135,9 @@ export function collectCodexSamples({
       match,
       onCandidate(path) {
         onFile?.(path);
+        const rollout = rolloutId(path);
         for (const line of tailLines(path)) {
-          const s = extractCodexUsage(line);
+          const s = extractCodexUsage(line, { rollout });
           if (s && s.at >= cut) samples.push(s);
         }
       },

package/src/watcher.js

@@ -23,8 +23,10 @@ import {
 import { getMultiplexer } from './multiplexer.js';
 import { parseTranscriptLine } from './watchers/claude.js';
 import { parseRolloutLines, rolloutMeta } from './watchers/codex.js';
-import { ROLLOUT_RE } from './agents/codex.js';
-import { parseResetTime, resetAtMs } from './time-parser.js';
+import { ROLLOUT_RE, rolloutId } from './agents/codex.js';
+import { parseResetTime, resetAtMs, sourceRank } from './time-parser.js';
+import { getAgent } from './agents/index.js';
+import { modelRemedy } from './patterns.js';
 import { upsertSession, readState, updateState } from './state.js';
 import { getConfig } from './settings.js';
 import { notify } from './notify.js';
@@ -88,21 +90,25 @@ export function codexSource({ roots }) {
     parse(lines, path, { offset } = {}) {
       const hits = parseRolloutLines(lines, { path, offset });
       if (hits.length === 0) return [];
-      const last = hits[hits.length - 1];   // the latest snapshot governs
+      const last = hits[hits.length - 1];   // the latest snapshot or limit error governs
       const meta = rolloutMeta(path);
       return [{
         agent: 'codex',
         sessionId: meta.sessionId,
         cwd: meta.cwd,
         limitType: last.limitType,
-        resetLine: null,
+        // Banner text from a persisted task_complete error; parsed by
+        // dispatchCandidate exactly like a scraped pane when no epoch is known.
+        resetLine: last.resetLine || null,
         resetAt: last.resetAt,
+        reason: last.reachedType || null,
         origin: meta.originator,
         timestampMs: last.timestampMs,
       }];
     },
-    usage(lines) {
-      return lines.map(extractCodexUsage).filter(Boolean);
+    usage(lines, path) {
+      const rollout = rolloutId(path);
+      return lines.map(line => extractCodexUsage(line, { rollout })).filter(Boolean);
     },
   };
 }
@@ -184,16 +190,31 @@ export function dispatchCandidate(c) {
     : null;
   if (existing && existing.status === 'cancelled') return;
   if (existing && (existing.status === 'stopped' || existing.status === 'resuming')) {
+    let kept = false;
     updateState(state => {
       const s = state.sessions[existing.key];
       if (s && (s.status === 'stopped' || s.status === 'resuming')) {
-        s.resetAt = at;
-        s.resetSource = source;
+        // A weaker estimate never replaces a stronger one that still stands —
+        // the rule monitor.js §7 and upsertSession's merge already apply. One
+        // Codex stop's token_count line and its task_complete error can land
+        // in different ticks, and a "Try again later." banner must not turn
+        // the exact epoch the snapshot gave into a 15-minute probe.
+        kept = sourceRank(source) < sourceRank(s.resetSource) && s.resetAt > Date.now();
+        if (!kept) {
+          s.resetAt = at;
+          s.resetSource = source;
+          if (c.limitType && c.limitType !== 'unknown') s.limitType = c.limitType;
+          // The reason belongs to the stop it came with: a later plain stop
+          // must not keep reporting an earlier workspace wall.
+          if (c.reason) s.limitReason = c.reason;
+          else delete s.limitReason;
+        }
         if (bannerAt != null) s.bannerAt = bannerAt;
-        if (c.limitType && c.limitType !== 'unknown') s.limitType = c.limitType;
       }
     });
-    log(`refreshed reset for tracked stop: session=${c.sessionId} resetAt=${new Date(at).toISOString()}`);
+    log(kept
+      ? `kept the stronger reset for tracked stop: session=${c.sessionId} (${source} would have replaced it)`
+      : `refreshed reset for tracked stop: session=${c.sessionId} resetAt=${new Date(at).toISOString()}`);
     return;
   }
 
@@ -217,6 +238,10 @@ export function dispatchCandidate(c) {
     lastError: null,
   };
   if (c.env) record.env = c.env;   // e.g. CLAUDE_CONFIG_DIR for sandboxed desktop sessions
+  // e.g. Codex's rate_limit_reached_type. Cleared explicitly when absent:
+  // upsertSession merges into an older record of the same session.
+  if (c.reason) record.limitReason = c.reason;
+  else if (existing?.limitReason) record.limitReason = null;
   // Raw reset without margin for calibration window math.
   const rawResetMs = c.resetAt != null
     ? c.resetAt
@@ -235,8 +260,16 @@ export function dispatchCandidate(c) {
   upsertSession(record, {
     after: calSample ? (state) => applyCalibrationToState(state, calSample) : null,
   });
-  log(`limit stop via transcript: agent=${c.agent} session=${c.sessionId || '?'} origin=${c.origin || '?'} resetAt=${new Date(at).toISOString()} (${source})`);
-  notify('limit hit 😴', `${c.cwd || c.agent}: tracked — resumes when the limit resets`);
+  log(`limit stop via transcript: agent=${c.agent} session=${c.sessionId || '?'} origin=${c.origin || '?'} resetAt=${new Date(at).toISOString()} (${source})${c.reason ? ` reason=${c.reason}` : ''}`);
+  // A model limit (a Codex workspace wall, say) is not lifted by waiting, so
+  // "resumes when the limit resets" would be a promise nothing keeps — say
+  // what it needs instead, as the pane monitor does.
+  if (record.limitType === 'model') {
+    const agent = getAgent(c.agent);
+    notify(`${agent.name} hit a model limit — needs you`, `${c.cwd || c.agent}: ${modelRemedy(agent)}`);
+  } else {
+    notify('limit hit 😴', `${c.cwd || c.agent}: tracked — resumes when the limit resets`);
+  }
 }
 
 function loadOffsets(path) {