unsnooze 1.19.0 → 1.19.1

package/src/multiplexers/headless.js

@@ -18,7 +18,10 @@
 //     session sweep skips headless rather than claiming to own anything.
 
 import { spawn } from 'node:child_process';
-import { mkdirSync, openSync } from 'node:fs';
+import {
+  mkdirSync, openSync, closeSync, readSync, statSync, readFileSync, writeFileSync,
+  renameSync, unlinkSync, readdirSync,
+} from 'node:fs';
 import { join } from 'node:path';
 
 import { HEADLESS_LOG_DIR } from '../config.js';
@@ -27,6 +30,12 @@ export const SUBMIT_DELAY_MS = 0;   // nothing is ever typed
 
 const PID_PREFIX = 'pid:';
 
+// How long a recorded exit stays on disk. A revival is verified ~20s after
+// launch and retried within the hour; a day covers a daemon that was asleep.
+const EXIT_TTL_MS = 24 * 3_600_000;
+// Enough of the child's own output to say why it died, never the whole log.
+const EXIT_OUTPUT_BYTES = 4096;
+
 export function parsePidAddress(pane) {
   if (typeof pane !== 'string' || !pane.startsWith(PID_PREFIX)) return null;
   const pid = Number.parseInt(pane.slice(PID_PREFIX.length), 10);
@@ -60,6 +69,64 @@ export function createHeadless({
   env = process.env,
   platform = process.platform,
 } = {}) {
+  const exitsDir = join(logDir, 'exits');
+  const exitPath = pid => join(exitsDir, `${pid}.json`);
+
+  function writeExit(pid, record) {
+    try {
+      mkdirSync(exitsDir, { recursive: true, mode: 0o700 });
+      const tmp = join(exitsDir, `.${pid}.${process.pid}.tmp`);
+      writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+      renameSync(tmp, exitPath(pid));
+    } catch { /* evidence only — a revival must never fail on bookkeeping */ }
+  }
+
+  function readExit(pid) {
+    try {
+      const parsed = JSON.parse(readFileSync(exitPath(pid), 'utf-8'));
+      return parsed && typeof parsed === 'object' && parsed.pid === pid ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function pruneExits(now = Date.now()) {
+    let names;
+    try { names = readdirSync(exitsDir); } catch { return; }
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      const path = join(exitsDir, name);
+      try {
+        if (now - statSync(path).mtimeMs > EXIT_TTL_MS) unlinkSync(path);
+      } catch { /* raced or gone */ }
+    }
+  }
+
+  // The last lines the child wrote to the shared log, read between the offsets
+  // recorded at its launch and at its exit. The upper bound matters: the
+  // resumer staggers revivals 8s apart and verifies 20s later, so a revival
+  // that died at once is read back after the next one has written its own
+  // lines into the same log. (One running alongside it can still interleave.)
+  function childOutput(exit) {
+    if (!exit.log || !Number.isFinite(exit.from)) return null;
+    let fd;
+    try {
+      const { size } = statSync(exit.log);
+      const end = Number.isFinite(exit.to) ? Math.min(exit.to, size) : size;
+      const start = Math.max(exit.from, end - EXIT_OUTPUT_BYTES);
+      if (end <= start) return null;
+      fd = openSync(exit.log, 'r');
+      const buf = Buffer.alloc(end - start);
+      const n = readSync(fd, buf, 0, buf.length, start);
+      const lines = buf.toString('utf-8', 0, n).split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+      return lines.length ? lines.slice(-3).join(' | ') : null;
+    } catch {
+      return null;
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  }
+
   const backend = {
     name: 'headless',
     SUBMIT_DELAY_MS,
@@ -95,24 +162,105 @@ export function createHeadless({
 
     // A revive is just a detached child. Its output goes to a per-session log
     // because there is no scrollback to read it out of later.
+    //
+    // The child's exit is recorded next to that log (exits/<pid>.json). With no
+    // pane to capture, an empty capture proves nothing — verifyOne used to read
+    // it as a cleared banner and mark a launcher that had died with `spawn
+    // codex ENOENT` as resumed (#25). The exit record, plus the slice of the
+    // log the child wrote, is what paneOutcome() answers with instead.
     async newWindow(sessionName, cwd, launchSpec) {
       // 0700/0600: this log is the entire stdout+stderr of an unattended
       // agent run — the most revealing thing under the state dir.
       mkdirSync(logDir, { recursive: true, mode: 0o700 });
       const logPath = join(logDir, `${sessionName}.log`);
       const fd = openSync(logPath, 'a', 0o600);
-      const child = spawner(launchSpec.file, launchSpec.args || [], {
-        cwd,
-        detached: true,
-        stdio: ['ignore', fd, fd],
-        env: { ...env, ...launchSpec.env },
-        windowsHide: true,
-      });
+      // The log is shared by every revival into this session name, so remember
+      // where this child's output starts.
+      let from = 0;
+      try { from = statSync(logPath).size; } catch { /* just created */ }
+      // The child gets this process's environment — the one backend that
+      // passes it through. A resumer spawned by the StopFailure hook runs in
+      // claude's, which carries UNSNOOZE_ACTIVE=1: the launcher's "nested
+      // call, pass straight through" marker. A revival is a fresh top-level
+      // launch; with the marker it dropped launchExtraArgs and, on a spawn
+      // failure, exited 1 without saying why.
+      const childEnv = { ...env, ...launchSpec.env };
+      delete childEnv.UNSNOOZE_ACTIVE;
+      let child;
+      try {
+        child = spawner(launchSpec.file, launchSpec.args || [], {
+          cwd,
+          detached: true,
+          stdio: ['ignore', fd, fd],
+          env: childEnv,
+          windowsHide: true,
+        });
+      } finally {
+        // The child has its own copy; the daemon's would otherwise stay open
+        // for the life of the process, one descriptor per revival.
+        try { closeSync(fd); } catch { /* already closed */ }
+      }
+      const pid = child?.pid;
+      const startedAt = Date.now();
+      let spawnError = null;
+      // Listen before anything below can throw. A spawn that fails — the
+      // session's cwd was a worktree that has since been deleted, say — says
+      // so with an 'error' event after spawn() has returned, and an 'error'
+      // nobody listens for is an uncaught exception: the daemon dies with it.
+      if (typeof child?.on === 'function') {
+        const record = (code, signal, error) => {
+          if (!pid) return;
+          // Where this child's output ends in the shared log (childOutput).
+          let to = null;
+          try { to = statSync(logPath).size; } catch { /* gone */ }
+          writeExit(pid, {
+            pid, code, signal: signal ?? null, error: error ?? null,
+            startedAt, at: Date.now(), log: logPath, from, to,
+          });
+        };
+        child.on('exit', (code, signal) => record(code, signal, null));
+        child.on('error', err => {
+          spawnError = err;
+          record(null, null, err?.message || String(err));
+        });
+      }
       if (typeof child?.unref === 'function') child.unref();
-      if (!child?.pid) {
-        throw new Error(`unsnooze: headless launch of ${launchSpec.file} produced no pid`);
+      if (!pid) {
+        // The reason arrives on the next tick; wait for it so the record's
+        // lastError says why, not just that there was no pid.
+        await new Promise(resolve => setImmediate(resolve));
+        throw new Error(`unsnooze: headless launch of ${launchSpec.file} produced no pid`
+          + (spawnError ? ` (${spawnError.message})` : ''));
       }
-      return { pane: `${PID_PREFIX}${child.pid}`, paneOwner: null, session: sessionName };
+      // A recycled pid must not inherit an old exit. Best-effort, like the
+      // pruning: an exit record is evidence, never something a launch needs.
+      // (No event can have fired yet — nothing above has yielded since spawn.)
+      try { unlinkSync(exitPath(pid)); } catch { /* none */ }
+      pruneExits();
+      return { pane: `${PID_PREFIX}${pid}`, paneOwner: null, session: sessionName };
+    },
+
+    // What became of a revival: { exited: false } while it runs, and once it is
+    // gone { exited: true, code, signal, output } from the recorded exit, where
+    // output is the tail of what the child itself wrote. null when the process
+    // is gone and nothing was recorded (a resumer that was not the parent) —
+    // the caller then knows exactly as much as it did before.
+    async paneOutcome(pane) {
+      const pid = parsePidAddress(pane);
+      if (pid === null) return null;
+      // The record first: newWindow clears any old one for this pid at spawn,
+      // so a record here is our child's exit — even if the pid has since been
+      // handed to another process (Windows recycles them quickly), which a
+      // liveness check alone would read as our revival still running.
+      const exit = readExit(pid);
+      if (!exit) return alive(pid) ? { exited: false } : null;
+      return {
+        exited: true,
+        code: exit.code ?? null,
+        signal: exit.signal ?? null,
+        error: exit.error ?? null,
+        output: childOutput(exit),
+      };
     },
 
     // Nothing to wrap into: the user's own terminal is the session. Returning

package/src/resumer.js

@@ -9,7 +9,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { getMultiplexer, backendCanType } from './multiplexer.js';
 import {
-  RESUMER_LOCK, POLL_INTERVAL_MS, STAGGER_MS, VERIFY_DELAY_MS, ensureStateDir,
+  RESUMER_LOCK, POLL_INTERVAL_MS, STAGGER_MS, VERIFY_DELAY_MS, HEADLESS_SETTLE_MS, ensureStateDir,
   BUSY_DEFER_MS, MAX_BUSY_DEFERS, MAX_RESUME_ATTEMPTS, READY_TIMEOUT_MS,
   CAPTURE_LINES, PANE_SCAN_LINES, RESUME_SESSION_NAME,
   RESET_MARGIN_MS, FALLBACK_RESET_MS, PROBE_INTERVAL_MS, PROBE_MAX_MS,
@@ -123,6 +123,15 @@ export function resolveRecordMux(rec) {
   return getMultiplexer(rec.mux, { owner: rec.paneOwner });
 }
 
+// The user's resumeExtraArgs, placed where the adapter's command parses them:
+// appended, unless the adapter names an index (codex's `exec resume` takes
+// its options after `exec`, not after the prompt).
+function withResumeExtraArgs(resume, agentId) {
+  const extra = resolveResumeExtraArgs(agentId);
+  const at = Number.isInteger(resume.extraArgsAt) ? resume.extraArgsAt : resume.args.length;
+  return [...resume.args.slice(0, at), ...extra, ...resume.args.slice(at)];
+}
+
 const stopEpisodeAt = rec => rec?.bannerAt ?? rec?.detectedAt;
 
 // Newer non-error parent-context Claude usage proves that a user/provider retry
@@ -366,13 +375,16 @@ function rescheduleProbe(rec, now = Date.now()) {
     // never by waiting it out. Typing a wake into it would hit the same wall,
     // so make the stall a visible terminal state instead of a futile resume.
     if (rec.limitType === 'model') {
+      // The agent's own remedy: `unsnooze status` shows this line, and
+      // Claude's slash commands mean nothing to a Codex workspace wall.
+      const remedy = modelRemedy(getAgent(rec.agent));
       setStatus(key, 'failed', {
-        lastError: 'model limit still active — switch models (/model) or add credits',
+        lastError: `model limit still active — ${remedy}`,
         probeCount: probeCount + 1,
       }, { expect: ['stopped'] });
       log(`${key}: model limit still active at probe ceiling — needs a human`);
       notify('unsnooze: model limit needs you ⚠️',
-        `${rec.cwd}: still limited after probing — ${modelRemedy(getAgent(rec.agent))}`,
+        `${rec.cwd}: still limited after probing — ${remedy}`,
         { context: ctxOf(rec), priority: 4 });
       return 'held';
     }
@@ -585,10 +597,12 @@ export async function planFor(rec, {
     return { ...base, action: 'superseded', target: { key: superseded.key } };
   }
   const target = await reviveTarget(mux, rec);
-  const resume = agent.resumeArgs(rec.sessionId, message);
+  // 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`).
+  const resume = agent.resumeArgs(rec.sessionId, message, { canType: backendCanType(mux) });
   return {
     ...base, action: 'reopen', target: { session: target }, message,
-    argv: [agent.id, ...resume.args, ...resolveResumeExtraArgs(agent.id)],
+    argv: [agent.id, ...withResumeExtraArgs(resume, agent.id)],
     messageViaPane: !!resume.messageViaPane,
   };
 }
@@ -758,7 +772,7 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onD
   const leaseId = createLeaseId();
   const target = await reviveTarget(mux, rec);
   const launchSpec = {
-    file: selfCmd[0], args: [...selfCmd.slice(1), '_run', agent.id, ...resume.args, ...resolveResumeExtraArgs(agent.id)],
+    file: selfCmd[0], args: [...selfCmd.slice(1), '_run', agent.id, ...withResumeExtraArgs(resume, agent.id)],
     env: reopenEnv(rec, leaseId, target),
   };
   // reviveTarget can await a multiplexer query. Recheck after it and claim the
@@ -936,6 +950,44 @@ export async function verifyOne(key, { resolveMux = resolveRecordMux } = {}) {
     log(`${key}: limit still active, rescheduled to ${new Date(at).toISOString()} (${source})`);
     return;
   }
+  // A pane-less backend answers every capture with '', so "no banner" is not
+  // evidence there. Headless records what became of the launcher it spawned;
+  // a child that already died non-zero (`spawn codex ENOENT`, the Codex TUI's
+  // "stdin is not a terminal") resumed nothing, and marking it resumed would
+  // drop a retryable stop from the ledger and announce a wake that never
+  // happened (#25). Exit 0 is fine — `claude --resume … "prompt"` runs to
+  // completion and exits before the verify delay — and so is running on
+  // past HEADLESS_SETTLE_MS. A revival that is still young stays in flight:
+  // the loop verifies every resuming record each tick, and once it counts as
+  // resumed nothing reads its exit again (the sweep drops the record when
+  // the pid goes), so a death at 25s would have been announced as a wake.
+  if (typeof mux.paneOutcome === 'function') {
+    let outcome = null;
+    try { outcome = await mux.paneOutcome(rec.pane); } catch { outcome = null; }
+    if (outcome && outcome.exited === false
+        && Date.now() - (rec.lastAttemptAt || 0) < HEADLESS_SETTLE_MS) {
+      return 'pending';
+    }
+    if (outcome?.exited && outcome.code !== 0) {
+      const attempts = (rec.attempts || 0) + 1;
+      const how = outcome.code != null ? `exit ${outcome.code}`
+        : 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}` : ''})`;
+      const applied = transitionStopEpisode(rec, 'stopped', {
+        attempts,
+        // Same backoff (and same manual exemption) as every other retry.
+        resetAt: rec.manual ? Date.now() : Date.now() + retryBackoffMs(attempts),
+        lastError, verifyRetries: 0, resumeEpisodeAt: null,
+      }, { expect: ['resuming'] });
+      if (!applied) {
+        releaseSupersededResume(key);
+        return 'stale';
+      }
+      log(`${key}: ${lastError}`);
+      return 'retry';
+    }
+  }
   if (!transitionStopEpisode(rec, 'resumed', {
     lastError: null, verifyRetries: 0, resumeEpisodeAt: null,
     bannerCleared: true,
@@ -1108,8 +1160,14 @@ export async function runResumer({
       // Anything over the attempts cap is dead — mark failed so we can exit.
       for (const s of dueForDispatch()) {
         if ((s.attempts || 0) >= MAX_RESUME_ATTEMPTS) {
+          // Keep the last attempt's reason: this is the state `unsnooze status`
+          // shows after the "gave up" notification, and "exceeded" alone does
+          // not say that every revival died with `spawn codex ENOENT` (#25).
           const applied = transitionStopEpisode(s, 'failed', {
-            lastError: 'max resume attempts exceeded', verifyRetries: 0,
+            lastError: s.lastError
+              ? `max resume attempts exceeded — last: ${s.lastError}`
+              : 'max resume attempts exceeded',
+            verifyRetries: 0,
             resumeEpisodeAt: null,
           }, { expect: ['stopped'] });
           if (!applied) continue;

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) {