unsnooze 1.14.1 → 1.14.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 1.14.2 — 2026-08-06
+
+- **Resume lifecycle:** a limit banner scrolling out of the pane no longer
+  marks a Claude session resumed without a wake. Unsnooze now requires a
+  newer non-error parent-assistant usage record, rechecks that evidence
+  immediately before dispatch, ignores subagent `StopFailure` records, follows
+  the canonical key retained by state dedupe, and never treats a persistently
+  busy pane as proof of completion.
+- **Usage diagnostics:** estimated usage now says that its percentage is
+  unavailable, rather than claiming no stop was observed. Proxy
+  launcher documentation explains that `headroom wrap` bypasses Unsnooze's
+  shell launcher and same-pane monitor while hook detection and enabled daemon
+  file watching remain available.
+
 ## 1.14.1 — 2026-08-04
 
 - **Package discovery**: refreshed the npm description and README links, and

package/README.md

@@ -147,6 +147,21 @@ risks, and vulnerability reporting: **[SECURITY.md](SECURITY.md)**.
 the CLIs that use it (OpenCode, Qwen Code), and credit exhaustion (402) is
 surfaced as a notification — there's no reset to wait for, only a top-up.
 
+### Proxy launchers such as Headroom
+
+`headroom wrap claude` and `headroom wrap codex` resolve and launch the real
+agent executable directly. That bypasses Unsnooze's shell-function launcher,
+so no same-pane monitor is attached. Claude's installed `StopFailure` hook can
+still record stops, as can the transcript/rollout watcher while the daemon,
+`guiWatch`, and that agent are enabled. For full pane monitoring too, configure
+Headroom's provider-scope persistent routing, then start `claude` / `codex`
+normally so Unsnooze remains the outer launcher. With Headroom v0.34, one
+explicit setup is:
+
+```bash
+headroom install apply --scope provider --providers manual --target claude --target codex
+```
+
 ## GUI surfaces (VS Code extension, desktop apps)
 
 Terminal sessions are watched through the shell wrapper + tmux or Zellij. Sessions in
@@ -251,7 +266,7 @@ unsnooze usage — account burn & time-to-limit  (daemon: running · warnings at
 
 | What you get | How |
 |---|---|
-| **Honest labels** | Every figure is tagged `(exact)`, `(calibrated from N stops)`, or `(estimated — calibrating…)`. Never a bare %. |
+| **Honest labels** | Every figure is tagged `(exact)`, `(calibrated from N stops)`, or `(estimated — percentage unavailable)`. Never a bare %. |
 | **Account-wide burn** | Sums all active sessions **and** subagents (the limit is per-account, not per-pane). Idle gaps >5 min are excluded so a quiet hour doesn't hide a fast burn. |
 | **Time-to-wall** | ETA as a band (not a false-precision minute), cross-checked against known reset times. Weekly shown info-only — no unstable weekly ETA. |
 | **Pre-wall warnings** | Daemon notifies at `%` bands (`usageWarnAt`, default `80,95`) **and** time tiers (30 / 10 min). Deduped once per window. |
@@ -259,9 +274,9 @@ unsnooze usage — account burn & time-to-limit  (daemon: running · warnings at
 
 **Provenance ladder** (why this isn't another guessed-quota dashboard):
 
-1. **`(exact)`** — Codex always (local `used_percent` + epoch reset). Claude only with the opt-in statusline shim (server-authoritative `rate_limits` from [Claude Code's statusline JSON](https://code.claude.com/docs/en/statusline)).
-2. **`(calibrated from N stops)`** — Claude token burn vs a ceiling learned from **your** limit-stop ledger (the same stops unsnooze already records for resume). Not plan presets, not circular P90-of-history.
-3. **`(estimated)`** — used tokens + burn shown; ceiling unknown until the first observed stop.
+1. **`(exact)`** — Codex when a recent local rollout contains `token_count.rate_limits` (`used_percent` + epoch reset). Claude only with the opt-in statusline shim (server-authoritative `rate_limits` from [Claude Code's statusline JSON](https://code.claude.com/docs/en/statusline)).
+2. **`(calibrated from N stops)`** — Claude 5-hour token burn vs a ceiling learned from **your matching usable calibration samples**: a stop classified as `5h`, with a nonzero local token sample from the same model pool when known, otherwise an unpooled fallback sample. A stop can still be valid for revival without meeting those calibration requirements. Not plan presets, not circular P90-of-history.
+3. **`(estimated — percentage unavailable)`** — used tokens + burn are shown when available, but there is no exact percentage (and a Claude 5-hour row has no matching usable calibration ceiling yet).
 
 **Honest limits:** Claude transcript sums are a **lower bound** — subscription quotas are account-pooled with claude.ai and the Desktop app. Without the statusline shim, Claude tops out at calibrated/estimated. Exact Claude % needs Pro/Max after the first API response of a session (absent after `/clear` and on API auth).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, and Antigravity sessions when 5-hour or weekly usage limits reset—across tmux, Zellij, VS Code, and desktop apps.",
   "keywords": [
     "claude",

package/src/agents/claude.js

@@ -100,7 +100,9 @@ export default {
   // method are unguarded.
   contextTokens(rec) {
     if (!rec?.cwd || !rec?.sessionId) return null;   // watcher/scrape records may lack either
-    return lastUsageTokens(transcriptPath(rec.cwd, rec.sessionId));
+    return lastUsageTokens(transcriptPath(rec.cwd, rec.sessionId, {
+      claudeDir: rec.env?.CLAUDE_CONFIG_DIR || process.env.CLAUDE_CONFIG_DIR,
+    }));
   },
   // The foreground process for a claude session is `node` (nvm shim) or `claude`.
   isForegroundCommand(cmd) {

package/src/config.js

@@ -15,7 +15,8 @@ export const RESUMER_LOCK = join(STATE_DIR, 'resumer.lock');
 // High-frequency burn accumulator + warn-dedup (daemon single-writer).
 export const USAGE_FILE = join(STATE_DIR, 'usage.json');
 
-export const CLAUDE_DIR = process.env.UNSNOOZE_CLAUDE_DIR || join(homedir(), '.claude');
+export const CLAUDE_DIR = process.env.UNSNOOZE_CLAUDE_DIR
+  || process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 export const CLAUDE_SETTINGS = join(CLAUDE_DIR, 'settings.json');
 export const CODEX_DIR = process.env.UNSNOOZE_CODEX_DIR || join(homedir(), '.codex');
 // Opt-in statusline shim drop dir for exact Claude rate_limits.

package/src/hook.js

@@ -20,6 +20,7 @@ import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { addressHash } from './lease.js';
 import { prepareCalibrationSample, applyCalibrationToState } from './usage.js';
+import { claudeRecordEnv } from './sessions.js';
 
 const log = makeLogger('hook');
 
@@ -48,6 +49,13 @@ export async function runHook(rest = []) {
     const raw = await readStdin();
     let payload = {};
     try { payload = JSON.parse(raw); } catch { /* tolerate non-JSON */ }
+    // Claude includes agent_id when a hook fires inside a subagent. The parent
+    // transcript owns revival; recording the child would create a second stop
+    // with no independently resumable pane.
+    if (agent.id === 'claude' && payload.agent_id) {
+      log(`StopFailure: ignoring subagent ${payload.agent_id}; parent session owns resume`);
+      return 0;
+    }
 
     const managedMux = process.env.UNSNOOZE_MUX;
     const muxName = managedMux || (process.env.ZELLIJ_PANE_ID ? 'zellij' : 'tmux');
@@ -129,6 +137,7 @@ export async function runHook(rest = []) {
       log(`calibration prepare failed: ${err.message}`);
     }
     // Stop record + calibration sample in ONE locked update (plan §6).
+    const recordEnv = agent.id === 'claude' ? claudeRecordEnv() : null;
     upsertSession({
       sessionId: sessionId || null,
       cwd,
@@ -149,6 +158,7 @@ export async function runHook(rest = []) {
       attempts: 0,
       lastAttemptAt: null,
       lastError: null,
+      ...(recordEnv ? { env: recordEnv } : {}),
       ...(source === 'fallback' ? { probeCount: 0 } : {}),
     }, {
       after: calSample

package/src/monitor.js

@@ -27,6 +27,7 @@ import { latestRateLimitFromTranscript } from './watchers/claude.js';
 import { spawnResumerIfNeeded } from './spawn.js';
 import { makeLogger } from './logger.js';
 import { addressHash, readLease } from './lease.js';
+import { claudeRecordEnv, hasClaudeParentUsageAfter } from './sessions.js';
 
 const log = makeLogger('monitor');
 
@@ -148,7 +149,9 @@ export function createMonitor({
         now: resolved.detectedAt,
       });
     } catch { /* best-effort */ }
-    const state = upsertSession({
+    const recordEnv = agent.id === 'claude' ? claudeRecordEnv() : null;
+    let appliedKey = null;
+    upsertSession({
       sessionId: resolved.sessionId, cwd, pane, mux: muxName, paneOwner, leaseId,
       agent: agent.id, muxSession,
       status: 'stopped', limitType: resolved.limitType, detectedVia,
@@ -156,15 +159,18 @@ export function createMonitor({
       bannerAt: resolved.bannerAt,
       resetAt: at, resetSource: source,
       attempts: 0, lastAttemptAt: null, lastError: null,
+      ...(recordEnv ? { env: recordEnv } : {}),
       ...(source === 'fallback' ? { probeCount: 0 } : {}),
     }, {
-      after: calSample ? (s) => applyCalibrationToState(s, calSample) : null,
+      after: (s, applied) => {
+        appliedKey = applied.key;
+        if (calSample) applyCalibrationToState(s, calSample);
+      },
     });
-    trackedKey = resolved.sessionId
-      || Object.values(state.sessions).find(s => s.mux === muxName
-        && s.paneOwner === paneOwner && s.pane === pane
-        && ['stopped', 'resuming', 'resumed'].includes(s.status))?.key
-      || null;
+    // upsertSession may retain a pane-based key while learning a sessionId.
+    // Capture the exact record applied under the state lock; a lookup by pane
+    // is ambiguous when historical records exist for the same address.
+    trackedKey = appliedKey;
     log(`pane ${pane}: limit recorded (${resolved.limitType}, via ${detectedVia}), resets ${new Date(at).toISOString()} (${source})`);
     notifier(`${agent.name} hit a usage limit`, `${cwd} — auto-resume at ${new Date(at).toLocaleTimeString()}`, { context: notifyCtx });
     spawnResumerIfNeeded();
@@ -318,18 +324,32 @@ export function createMonitor({
       terminalNotified = false;
     }
 
-    // No banner. If we were tracking a stopped record and claude is active
-    // again, someone resumed it (user or resumer) — mark it.
+    // A banner leaving the 12-line scan is not evidence of a resume: ordinary
+    // output (including background-agent notices) can scroll it away. Claude
+    // is terminal only after its parent transcript records newer non-error
+    // assistant usage. Other adapters retain their legacy behavior until they
+    // expose an equally authoritative progress signal.
     if (trackedKey) {
       const state = readState();
       const rec = state.sessions[trackedKey];
       if (rec && rec.status === 'stopped') {
-        setStatus(trackedKey, 'resumed', { lastAttemptAt: Date.now(), bannerCleared: true });
-        log(`pane ${pane}: banner cleared, ${trackedKey} marked resumed`);
-        trackedKey = null;
+        const cutoff = rec.bannerAt ?? rec.detectedAt;
+        const progressed = agent.id !== 'claude'
+          || hasClaudeParentUsageAfter(rec, cutoff);
+        if (progressed) {
+          const next = setStatus(trackedKey, 'resumed', {
+            lastAttemptAt: Date.now(), bannerCleared: true, lastError: null,
+          }, { expect: ['stopped'], expectCutoff: cutoff });
+          const applied = next.sessions[trackedKey];
+          if (applied?.status === 'resumed'
+            && (applied.bannerAt ?? applied.detectedAt) === cutoff) {
+            log(`pane ${pane}: post-limit progress observed, ${trackedKey} marked resumed`);
+            trackedKey = null;
+          }
+        }
       }
       if (rec && rec.status === 'resumed') {
-        setStatus(trackedKey, 'resumed', { bannerCleared: true });
+        setStatus(trackedKey, 'resumed', { bannerCleared: true }, { expect: ['resumed'] });
         trackedKey = null;
       } else if (rec && rec.status !== 'stopped') trackedKey = null;
     }

package/src/reap.js

@@ -3,13 +3,84 @@
 
 import { MUX_SESSION_NAME, RESUME_SESSION_NAME } from './config.js';
 import { getMultiplexer } from './multiplexer.js';
-import { readState, setStatus, updateState } from './state.js';
+import { readState, updateState } from './state.js';
 import { getConfig } from './settings.js';
 import { paneOwnedByRecord } from './lease.js';
 import { makeLogger } from './logger.js';
 
 const log = makeLogger('reap');
 
+function samePaneGeneration(a, b) {
+  return !!(a?.pane && b?.pane && a.leaseId && b.leaseId
+    && a.mux === b.mux && a.paneOwner === b.paneOwner && a.pane === b.pane
+    && a.leaseId === b.leaseId);
+}
+
+function sameRecordEpisode(a, b) {
+  return !!(a && b && a.status === b.status && a.pane === b.pane
+    && a.mux === b.mux && a.paneOwner === b.paneOwner && a.leaseId === b.leaseId
+    && (a.bannerAt ?? a.detectedAt) === (b.bannerAt ?? b.detectedAt)
+    && (a.resumeEpisodeAt ?? null) === (b.resumeEpisodeAt ?? null));
+}
+
+function activePaneAlias(state, rec) {
+  return Object.values(state.sessions).find(other => other.key !== rec.key
+    && ['stopped', 'resuming', 'resumed'].includes(other.status)
+    && samePaneGeneration(rec, other));
+}
+
+// Reserve a close under the state lock immediately before touching the mux.
+// Removing the terminal record is the claim: another reap cannot close it,
+// and a live alias that appeared during an awaited ownership probe wins.
+function claimPaneClose(rec) {
+  let result = { kind: 'stale' };
+  updateState(state => {
+    const current = state.sessions[rec.key];
+    if (!sameRecordEpisode(current, rec)) return state;
+    const alias = activePaneAlias(state, current);
+    delete state.sessions[rec.key];
+    if (alias) {
+      result = { kind: 'alias', alias };
+    } else if ((state.paneClosures || []).some(c => samePaneGeneration(c, current))) {
+      result = { kind: 'closing' };
+    } else {
+      state.paneClosures ||= [];
+      state.paneClosures.push({
+        mux: current.mux,
+        paneOwner: current.paneOwner,
+        pane: current.pane,
+        leaseId: current.leaseId,
+        claimedAt: Date.now(),
+      });
+      result = { kind: 'claimed' };
+    }
+    return state;
+  });
+  return result;
+}
+
+function dropIfUnchanged(rec) {
+  let dropped = false;
+  updateState(state => {
+    if (sameRecordEpisode(state.sessions[rec.key], rec)) {
+      delete state.sessions[rec.key];
+      dropped = true;
+    }
+    return state;
+  });
+  return dropped;
+}
+
+function restoreFailedClaim(rec) {
+  updateState(state => {
+    state.paneClosures = (state.paneClosures || []).filter(c => !samePaneGeneration(c, rec));
+    if (!state.sessions[rec.key] && !activePaneAlias(state, rec)) {
+      state.sessions[rec.key] = rec;
+    }
+    return state;
+  });
+}
+
 // How a user reaches a revived session. Shared by status, toast, and `sessions`.
 export function attachHint(muxName, sessionName) {
   if (!sessionName) return null;
@@ -81,8 +152,7 @@ export async function reap({
   // --yes flips dry-run off; plain default stays dry-run.
   if (yes) dryRun = false;
   const actions = [];
-  const state = readState();
-  const terminal = Object.values(state.sessions).filter(s =>
+  const terminal = Object.values(readState().sessions).filter(s =>
     ['resumed', 'failed', 'cancelled'].includes(s.status) && s.pane);
 
   const reapIdleAfter = getConfig('reapIdleAfter');
@@ -107,9 +177,7 @@ export async function reap({
     } catch { alive = false; }
     if (!alive) {
       actions.push({ kind: 'drop-record', key: rec.key, reason: 'pane already dead' });
-      if (!dryRun) {
-        updateState(s => { delete s.sessions[rec.key]; return s; });
-      }
+      if (!dryRun) dropIfUnchanged(rec);
       continue;
     }
     // Pane ids get recycled — closing by bare id could kill someone else's
@@ -119,9 +187,7 @@ export async function reap({
     try { owned = await paneOwnedByRecord(rec, { mux }); } catch { owned = null; }
     if (owned === false) {
       actions.push({ kind: 'drop-record', key: rec.key, reason: 'pane recycled — not ours' });
-      if (!dryRun) {
-        updateState(s => { delete s.sessions[rec.key]; return s; });
-      }
+      if (!dryRun) dropIfUnchanged(rec);
       continue;
     }
     if (owned === null) {
@@ -130,6 +196,33 @@ export async function reap({
         reason: 'ownership unprovable (pre-lease record) — close it manually' });
       continue;
     }
+    if (dryRun) {
+      const alias = activePaneAlias(readState(), rec);
+      if (alias) {
+        actions.push({ kind: 'drop-record', key: rec.key,
+          reason: `pane is shared with active record ${alias.key} — not closing` });
+        continue;
+      }
+    } else {
+      // paneAlive() and ownership checks await external commands. Re-check and
+      // claim only now so an owner created while they ran cannot be killed.
+      const claim = claimPaneClose(rec);
+      if (claim.kind === 'alias') {
+        actions.push({ kind: 'drop-record', key: rec.key,
+          reason: `pane is shared with active record ${claim.alias.key} — not closing` });
+        continue;
+      }
+      if (claim.kind === 'closing') {
+        actions.push({ kind: 'drop-record', key: rec.key,
+          reason: 'pane generation is already being closed by another reap' });
+        continue;
+      }
+      if (claim.kind !== 'claimed') {
+        actions.push({ kind: 'skip-stale', key: rec.key, pane: rec.pane,
+          reason: 'record changed while checking pane — not closing' });
+        continue;
+      }
+    }
     actions.push({
       kind: 'close-pane',
       key: rec.key,
@@ -141,9 +234,8 @@ export async function reap({
     if (!dryRun) {
       try {
         if (typeof mux.closePane === 'function') await mux.closePane(rec.pane);
-        setStatus(rec.key, rec.status, { pane: null });
-        updateState(s => { delete s.sessions[rec.key]; return s; });
       } catch (err) {
+        restoreFailedClaim(rec);
         actions.push({ kind: 'error', key: rec.key, message: err.message });
       }
     }
@@ -202,24 +294,30 @@ export async function autoReapIfEnabled({
     try {
       const mux = resolveMux(rec);
       if (!(await mux.paneAlive(rec.pane))) {
-        updateState(s => { delete s.sessions[rec.key]; return s; });
+        dropIfUnchanged(rec);
         continue;
       }
       // Same recycled-pane rule as reap(): positive ownership or no close.
       const owned = await paneOwnedByRecord(rec, { mux });
       if (owned !== true) {
         if (owned === false) {
-          updateState(s => { delete s.sessions[rec.key]; return s; });
+          dropIfUnchanged(rec);
           log(`${rec.key}: auto-reap skipped — pane ${rec.pane} recycled, record dropped`);
         }
         continue;
       }
+      const claim = claimPaneClose(rec);
+      if (claim.kind !== 'claimed') continue;
       if (typeof mux.closePane === 'function') {
-        await mux.closePane(rec.pane);
-        closed += 1;
-        log(`${rec.key}: auto-reaped idle resumed pane ${rec.pane}`);
+        try {
+          await mux.closePane(rec.pane);
+          closed += 1;
+          log(`${rec.key}: auto-reaped idle resumed pane ${rec.pane}`);
+        } catch (err) {
+          restoreFailedClaim(rec);
+          throw err;
+        }
       }
-      updateState(s => { delete s.sessions[rec.key]; return s; });
     } catch (err) {
       log(`${rec.key}: auto-reap failed: ${err.message}`);
     }

package/src/resumer.js

@@ -21,7 +21,7 @@ import {
   readState, updateState, setStatus, dueSessions, activeStopped,
   prune, sweepRecords, markStaleAbandoned,
 } from './state.js';
-import { approxTokens } from './sessions.js';
+import { approxTokens, hasClaudeParentUsageAfter } from './sessions.js';
 import { latestRateLimitFromTranscript } from './watchers/claude.js';
 import { getConfig, resolveResumeMessage } from './settings.js';
 import { workspaceFingerprint, workspaceChanged, describeChange } from './workspace.js';
@@ -126,6 +126,125 @@ export function resolveRecordMux(rec) {
   return getMultiplexer(rec.mux, { owner: rec.paneOwner });
 }
 
+const stopEpisodeAt = rec => rec?.bannerAt ?? rec?.detectedAt;
+
+// Newer non-error parent-context Claude usage proves that a user/provider retry
+// already made progress after this stop. Banner absence alone does not.
+function claudeProgressedAfterStop(rec, agent) {
+  const cutoff = stopEpisodeAt(rec);
+  return agent.id === 'claude' && hasClaudeParentUsageAfter(rec, cutoff);
+}
+
+// Compare-and-set for one stop episode, with an applied result for callers
+// that must suppress stale logs, notifications, or follow-up actions.
+function transitionStopEpisode(rec, status, extra = {}, {
+  expect = ['stopped', 'resuming'],
+} = {}) {
+  const cutoff = stopEpisodeAt(rec);
+  let applied = false;
+  updateState(state => {
+    const current = state.sessions[rec.key];
+    if (!current || !expect.includes(current.status)
+      || stopEpisodeAt(current) !== cutoff) return state;
+    Object.assign(current, extra, { status });
+    if (status !== 'resuming') current.resumeEpisodeAt = null;
+    applied = true;
+    return state;
+  });
+  return applied;
+}
+
+// Reconcile durable progress without letting a stale snapshot clear a newer
+// stop episode. A false return means no progress was observed; true means this
+// dispatch must stop, whether the transition applied or the snapshot went stale.
+function finishIfClaudeProgressed(rec, agent) {
+  if (!claudeProgressedAfterStop(rec, agent)) return false;
+  const cutoff = stopEpisodeAt(rec);
+  let applied = false;
+  updateState(state => {
+    const current = state.sessions[rec.key];
+    if (current?.status === 'stopped'
+      && stopEpisodeAt(current) === cutoff) {
+      Object.assign(current, {
+        status: 'resumed', lastAttemptAt: Date.now(), bannerCleared: true,
+        lastError: null, verifyRetries: 0, resumeEpisodeAt: null,
+      });
+      applied = true;
+    }
+    return state;
+  });
+  log(applied
+    ? `${rec.key}: newer non-error parent-context usage recorded — no wake sent`
+    : `${rec.key}: stop episode changed during progress check — stale dispatch skipped`);
+  return true;
+}
+
+function samePaneTarget(a, b) {
+  return !!(a?.pane && b?.pane
+    && a.mux === b.mux && a.paneOwner === b.paneOwner && a.pane === b.pane
+    && a.agent === b.agent && a.cwd === b.cwd
+    // A different non-null lease is a different pane generation. Missing
+    // legacy leases only coalesce with each other; they cannot overrule a
+    // record whose current generation is demonstrable.
+    && (a.leaseId ?? null) === (b.leaseId ?? null));
+}
+
+function newerStop(a, b) {
+  const aCutoff = stopEpisodeAt(a) ?? 0;
+  const bCutoff = stopEpisodeAt(b) ?? 0;
+  if (aCutoff !== bCutoff) return aCutoff > bCutoff ? a : b;
+  if ((a.detectedAt ?? 0) !== (b.detectedAt ?? 0)) {
+    return (a.detectedAt ?? 0) > (b.detectedAt ?? 0) ? a : b;
+  }
+  if (!!a.sessionId !== !!b.sessionId) return a.sessionId ? a : b;
+  return String(a.key).localeCompare(String(b.key)) >= 0 ? a : b;
+}
+
+function paneStopOwner(rec, state = readState()) {
+  if (!rec?.pane) return rec;
+  const contenders = Object.values(state.sessions).filter(s =>
+    ['stopped', 'resuming'].includes(s.status) && samePaneTarget(s, rec));
+  return contenders.reduce((latest, candidate) => newerStop(latest, candidate), rec);
+}
+
+// Atomically own this exact stop before the irreversible pane/window action.
+// One live pane can accept one wake. Legacy/subagent detections outside the
+// short ingest-dedupe window are therefore collapsed here: the newest active
+// stop owns the target and older active records become explicit history.
+function claimStopForResume(rec) {
+  const cutoff = stopEpisodeAt(rec);
+  let claimed = false;
+  updateState(state => {
+    const current = state.sessions[rec.key];
+    if (current?.status !== 'stopped'
+      || stopEpisodeAt(current) !== cutoff) return state;
+
+    const contenders = current.pane
+      ? Object.values(state.sessions).filter(s => ['stopped', 'resuming'].includes(s.status)
+        && samePaneTarget(s, current))
+      : [current];
+    const owner = paneStopOwner(current, state);
+    const now = Date.now();
+    for (const candidate of contenders) {
+      if (candidate.key === owner.key) continue;
+      Object.assign(candidate, {
+        status: 'cancelled', lastAttemptAt: now, verifyRetries: 0,
+        resumeEpisodeAt: null,
+        lastError: `superseded by newer stop ${owner.key} on the same pane`,
+      });
+    }
+    if (owner.key === current.key && current.status === 'stopped') {
+      Object.assign(current, {
+        status: 'resuming', lastAttemptAt: now, lastError: null, verifyRetries: 0,
+        resumeEpisodeAt: cutoff,
+      });
+      claimed = true;
+    }
+    return state;
+  });
+  return claimed;
+}
+
 // Join the session the pane lived in only if it is still alive; otherwise the
 // daemon gets its own session. It must never CREATE the launcher's base name.
 export async function reviveTarget(mux, rec) {
@@ -174,7 +293,9 @@ export async function probeFallback(rec, {
   let bannerAt = rec.bannerAt ?? null;
 
   // Prefer a fresh transcript entry when available (claude).
-  const fromTx = latestRateLimitFromTranscript(rec.cwd, rec.sessionId, { now });
+  const fromTx = latestRateLimitFromTranscript(rec.cwd, rec.sessionId, {
+    now, claudeDir: rec.env?.CLAUDE_CONFIG_DIR,
+  });
   if (fromTx) {
     stillLimited = true;
     resetLine = fromTx.resetLine;
@@ -211,11 +332,12 @@ export async function probeFallback(rec, {
       bannerAt,
     });
     if (source !== 'fallback') {
-      setStatus(key, 'stopped', {
+      const applied = transitionStopEpisode(rec, 'stopped', {
         resetAt: at, resetSource: source, bannerAt,
         lastError: 'limit still active (probe upgraded estimate)',
         probeCount: 0,
-      });
+      }, { expect: ['stopped'] });
+      if (!applied) return 'stale';
       log(`${key}: probe upgraded fallback→${source}, rescheduled to ${new Date(at).toISOString()}`);
       return 'probe';
     }
@@ -232,12 +354,13 @@ function rescheduleProbe(rec, now = Date.now()) {
   // Past the hard ceiling: schedule a final attempt at the ceiling (or now
   // if already past) and stop tagging as endless probes — reopen path runs.
   if (now >= ceiling) {
-    setStatus(key, 'stopped', {
+    const applied = transitionStopEpisode(rec, 'stopped', {
       resetAt: now,
       resetSource: 'fallback',
       lastError: 'probe ceiling reached — attempting resume',
       probeCount: probeCount + 1,
-    });
+    }, { expect: ['stopped'] });
+    if (!applied) return 'stale';
     log(`${key}: probe ceiling reached — attempting resume`);
     return null;   // proceed with dispatch
   }
@@ -246,12 +369,13 @@ function rescheduleProbe(rec, now = Date.now()) {
   });
   let nextAt = now + delay + RESET_MARGIN_MS;
   if (nextAt > ceiling) nextAt = ceiling;
-  setStatus(key, 'stopped', {
+  const applied = transitionStopEpisode(rec, 'stopped', {
     resetAt: nextAt,
     resetSource: 'fallback',
     lastError: 'limit still active — probing',
     probeCount: probeCount + 1,
-  });
+  }, { expect: ['stopped'] });
+  if (!applied) return 'stale';
   log(`${key}: probe #${probeCount + 1} rescheduled to ${new Date(nextAt).toISOString()}`);
   return 'probe';
 }
@@ -341,6 +465,15 @@ export async function planFor(rec, {
     gates.push(`status ${rec.status} — nothing to dispatch`);
     return { ...base, action: 'none' };
   }
+  if (claudeProgressedAfterStop(rec, agent)) {
+    gates.push('newer non-error parent-context usage shows that the session already resumed');
+    return { ...base, action: 'none' };
+  }
+  const paneOwner = paneStopOwner(rec);
+  if (paneOwner?.key !== rec.key) {
+    gates.push(`newer active stop ${paneOwner.key} owns this live pane target`);
+    return { ...base, action: 'none' };
+  }
   // Gate order mirrors runResumer exactly: give-up only ever happens to
   // records that pass dueForDispatch (due AND auto-or-manual AND not held),
   // so paused/held/backing-off records are narrated as such even when their
@@ -429,7 +562,8 @@ export async function planFor(rec, {
   };
 }
 
-// Ordered safety decision. Returns: busy | retry | progress | held | injected | reopen | probe.
+// 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,
@@ -438,6 +572,9 @@ export async function dispatchOne(rec, {
   resolveMux ||= () => mux;
   const key = rec.key;
   const agent = getAgent(rec.agent);
+  // Cheap early reconciliation; this is repeated after asynchronous pane or
+  // multiplexer inspection, immediately before any keystroke/window launch.
+  if (finishIfClaudeProgressed(rec, agent)) return 'already-resumed';
   // Wake-message precedence: per-session (`unsnooze message <id> "..."`) →
   // explicit option → per-agent (`resumeMessages.<id>`) → global. Applies to
   // both the live-pane sendText and the argv reopen path.
@@ -445,11 +582,17 @@ export async function dispatchOne(rec, {
 
   // §4: fallback records probe cheaply before a real resume attempt.
   if (rec.resetSource === 'fallback' && !rec.manual) {
+    const episode = stopEpisodeAt(rec);
     const probed = await probeFallback(rec, { mux });
-    if (probed === 'probe') return 'probe';
+    if (probed != null) return probed;
     // null → banner gone or ceiling hit — fall through to normal dispatch.
-    // Re-read record in case probeFallback mutated it.
-    rec = readState().sessions[key] || rec;
+    // Re-read only this episode in case the ceiling probe updated its fields.
+    // A newer stop may not inherit the old episode's due decision.
+    const current = readState().sessions[key];
+    if (!current || current.status !== 'stopped' || stopEpisodeAt(current) !== episode) {
+      return 'stale';
+    }
+    rec = current;
   }
 
   // Stale-workspace guard: another session (or a human) may have moved the
@@ -458,7 +601,9 @@ export async function dispatchOne(rec, {
   // dispatch owns the side effects.
   const ws = evaluateWorkspaceGuard(rec, resumeMessage, { fingerprint });
   if (ws.hold) {
-    setStatus(key, 'stopped', { workspaceHold: true, holdReason: ws.hold.reason });
+    if (!transitionStopEpisode(rec, 'stopped', {
+      workspaceHold: true, holdReason: ws.hold.reason,
+    }, { expect: ['stopped'] })) return 'stale';
     notifier('unsnooze: session held', `${rec.cwd}: workspace changed while stopped (${ws.hold.desc}) — run: unsnooze resume-now`, { context: ctxOf(rec) });
     log(`${key}: workspace changed (${ws.hold.desc}) — held (workspaceGuard=pause)`);
     return 'held';
@@ -473,7 +618,9 @@ export async function dispatchOne(rec, {
   // tick. Manual resumes proceed.
   const ctx = evaluateContextGuard(rec, agent, { contextTokens });
   if (ctx.hold) {
-    setStatus(key, 'stopped', { workspaceHold: true, holdReason: ctx.hold.reason });
+    if (!transitionStopEpisode(rec, 'stopped', {
+      workspaceHold: true, holdReason: ctx.hold.reason,
+    }, { expect: ['stopped'] })) return 'stale';
     notifier('unsnooze: session held', `${rec.cwd}: waking would re-read ${ctx.hold.size} tokens of context at full (uncached) price — run: unsnooze resume-now`, { context: ctxOf(rec) });
     log(`${key}: context ${ctx.hold.size} tokens ≥ threshold — held (contextGuard=pause)`);
     return 'held';
@@ -491,23 +638,37 @@ export async function dispatchOne(rec, {
   const a = await assessPane(rec, agent, { mux, matchesLease });
   if (a.alive) {
     if (a.captureError) {
-      setStatus(key, 'stopped', { lastError: `capture: ${a.captureError}` });
+      if (!transitionStopEpisode(rec, 'stopped', {
+        lastError: `capture: ${a.captureError}`,
+      }, { expect: ['stopped'] })) return 'stale';
       return 'retry';
     }
     if (a.busy) return 'busy';
     if (a.menu) {
+      if (finishIfClaudeProgressed(rec, agent)) return 'already-resumed';
       if (!a.authorized) return reopenGuarded();
       if (!getConfig('menuAutoAnswer')) return 'held';
+      // Menu navigation is an irreversible pane action too. Claim the exact
+      // stop after assessment so a refreshed episode cannot receive stale
+      // Down/Enter keystrokes.
+      if (!claimStopForResume(rec)) return 'stale';
       try {
         if (await driveMenu(mux, rec.pane, agent, a.text)) return 'progress';
-        setStatus(key, 'stopped', { lastError: 'menu drive: wait option unavailable' });
+        transitionStopEpisode(rec, 'stopped', {
+          lastError: 'menu drive: wait option unavailable',
+        }, { expect: ['resuming'] });
       } catch (err) {
-        setStatus(key, 'stopped', { lastError: `menu drive: ${err.message}` });
+        transitionStopEpisode(rec, 'stopped', {
+          lastError: `menu drive: ${err.message}`,
+        }, { expect: ['resuming'] });
       }
       return 'retry';
     }
     if (a.authorized) {
-      setStatus(key, 'resuming', { lastAttemptAt: Date.now(), lastError: null, verifyRetries: 0 });
+      // assessPane is asynchronous. Close the final human/provider-resume race
+      // after assessment and immediately before the keystroke.
+      if (finishIfClaudeProgressed(rec, agent)) return 'already-resumed';
+      if (!claimStopForResume(rec)) return 'stale';
       await mux.sendText(rec.pane, resumeMessage);
       log(`${key}: sent continue via ${rec.mux} ${rec.paneOwner ?? '-'}:${rec.pane}`);
       notifyContext();
@@ -523,6 +684,7 @@ export async function dispatchOne(rec, {
 // (argv or typed) — not on ready-timeouts or a still-active limit banner.
 async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onDelivered = () => {} }) {
   const key = rec.key;
+  const cutoff = rec.bannerAt ?? rec.detectedAt;
   const resume = agent.resumeArgs(rec.sessionId, resumeMessage);
   const leaseId = createLeaseId();
   const target = await reviveTarget(mux, rec);
@@ -530,7 +692,10 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onD
     file: selfCmd[0], args: [...selfCmd.slice(1), '_run', agent.id, ...resume.args],
     env: reopenEnv(rec, leaseId, target),
   };
-  setStatus(key, 'resuming', { lastAttemptAt: Date.now(), verifyRetries: 0 });
+  // reviveTarget can await a multiplexer query. Recheck after it and claim the
+  // exact episode immediately before opening a new pane.
+  if (finishIfClaudeProgressed(rec, agent)) return 'already-resumed';
+  if (!claimStopForResume(rec)) return 'stale';
   let address;
   try {
     address = await mux.newWindow(target, rec.cwd || homedir(), launchSpec);
@@ -542,8 +707,8 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onD
     setStatus(key, 'stopped', {
       attempts: (rec.attempts || 0) + 1,
       lastError: `new-window: ${err.message}`,
-      verifyRetries: 0,
-    });
+      verifyRetries: 0, resumeEpisodeAt: null,
+    }, { expect: ['resuming'], expectCutoff: cutoff });
     return 'retry';
   }
   // Stamp the fresh pane as ours (best-effort; tmux only) so later close /
@@ -555,7 +720,10 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onD
   // name the session the pane actually lives in.
   updateState(state => {
     const s = state.sessions[key];
-    if (s) Object.assign(s, address, { leaseId, muxSession: target });
+    if (s?.status === 'resuming' && (s.bannerAt ?? s.detectedAt) === cutoff) {
+      Object.assign(s, address, { leaseId, muxSession: target });
+    }
+    return state;
   });
   const rebound = { ...rec, ...address, leaseId, muxSession: target };
   mux = resolveMux(rebound);
@@ -579,8 +747,8 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onD
   setStatus(key, 'stopped', {
     attempts: (rec.attempts || 0) + 1,
     lastError: 'ready timeout',
-    verifyRetries: 0,
-  });
+    verifyRetries: 0, resumeEpisodeAt: null,
+  }, { expect: ['resuming'], expectCutoff: cutoff });
   return 'retry';
 }
 
@@ -611,25 +779,42 @@ export async function awaitReadyAndSend(mux, pane, agent, message, {
 
 function recordVerifyRetry(rec, lastError) {
   const verifyRetries = (rec.verifyRetries || 0) + 1;
+  let applied;
   if (verifyRetries >= MAX_VERIFY_RETRIES) {
     const attempts = (rec.attempts || 0) + 1;
-    setStatus(rec.key, 'stopped', {
+    applied = transitionStopEpisode(rec, 'stopped', {
       attempts,
       // Same backoff (and same manual exemption) as routed retries.
       resetAt: rec.manual ? Date.now() : Date.now() + retryBackoffMs(attempts),
       lastError,
-      verifyRetries: 0,
-    });
+      verifyRetries: 0, resumeEpisodeAt: null,
+    }, { expect: ['resuming'] });
   } else {
-    setStatus(rec.key, 'resuming', { lastError, verifyRetries });
+    applied = transitionStopEpisode(rec, 'resuming', { lastError, verifyRetries },
+      { expect: ['resuming'] });
   }
-  return 'retry';
+  if (!applied) releaseSupersededResume(rec.key);
+  return applied ? 'retry' : 'stale';
+}
+
+function releaseSupersededResume(key) {
+  const current = readState().sessions[key];
+  if (!current || current.status !== 'resuming' || current.resumeEpisodeAt == null
+    || stopEpisodeAt(current) === current.resumeEpisodeAt) return false;
+  return transitionStopEpisode(current, 'stopped', {
+    lastError: 'newer limit detected during resume', verifyRetries: 0,
+    resumeEpisodeAt: null,
+  }, { expect: ['resuming'] });
 }
 
 // Post-dispatch verification: did the limit banner come back?
 export async function verifyOne(key, { resolveMux = resolveRecordMux } = {}) {
   const rec = readState().sessions[key];
   if (!rec || rec.status !== 'resuming') return;
+  // A detection that lands after the action claim deliberately preserves the
+  // in-flight status, but it advances bannerAt/detectedAt. Do not verify that
+  // newer episode using an older pane action.
+  if (releaseSupersededResume(key)) return 'stale';
   const agent = getAgent(rec.agent);
   if (!rec.pane) {
     return recordVerifyRetry(rec, 'verify: pane unavailable');
@@ -647,7 +832,9 @@ export async function verifyOne(key, { resolveMux = resolveRecordMux } = {}) {
     // offsets anchor to the banner's own time.
     let resetLine = d.hit ? d.resetLine : null;
     let bannerAt = null;
-    const fromTx = latestRateLimitFromTranscript(rec.cwd, rec.sessionId);
+    const fromTx = latestRateLimitFromTranscript(rec.cwd, rec.sessionId, {
+      claudeDir: rec.env?.CLAUDE_CONFIG_DIR,
+    });
     if (fromTx) {
       resetLine = fromTx.resetLine ?? resetLine;
       bannerAt = fromTx.timestampMs;
@@ -657,16 +844,27 @@ export async function verifyOne(key, { resolveMux = resolveRecordMux } = {}) {
       fallbackMs: PROBE_INTERVAL_MS,
       bannerAt,
     });
-    setStatus(key, 'stopped', {
+    const applied = transitionStopEpisode(rec, 'stopped', {
       attempts: (rec.attempts || 0) + 1, resetAt: at, resetSource: source,
       bannerAt: bannerAt ?? rec.bannerAt ?? null,
       lastError: 'limit still active at resume time', verifyRetries: 0,
+      resumeEpisodeAt: null,
       ...(source === 'fallback' ? { probeCount: (rec.probeCount || 0) + 1 } : { probeCount: 0 }),
-    });
+    }, { expect: ['resuming'] });
+    if (!applied) {
+      releaseSupersededResume(key);
+      return 'stale';
+    }
     log(`${key}: limit still active, rescheduled to ${new Date(at).toISOString()} (${source})`);
     return;
   }
-  setStatus(key, 'resumed', { lastError: null, verifyRetries: 0 });
+  if (!transitionStopEpisode(rec, 'resumed', {
+    lastError: null, verifyRetries: 0, resumeEpisodeAt: null,
+    bannerCleared: true,
+  }, { expect: ['resuming'] })) {
+    releaseSupersededResume(key);
+    return 'stale';
+  }
   const session = rec.muxSession || RESUME_SESSION_NAME;
   const hint = attachHint(rec.mux, session);
   log(`${key}: verified resumed in ${session}${hint ? ` — ${hint}` : ''}`);
@@ -681,30 +879,50 @@ export function routeDispatchOutcome(result, rec, deferCounts, { maxBusyDefers =
     const n = (deferCounts.get(rec.key) || 0) + 1;
     deferCounts.set(rec.key, n);
     if (n > maxBusyDefers) {
-      setStatus(rec.key, 'resumed', { lastError: null, verifyRetries: 0 });
+      // Busy is evidence that typing would be unsafe, not evidence that the
+      // stopped episode completed. Drop the hot-loop delay after the cap but
+      // leave the record stopped for the next normal poll.
       return { verify: false, waitBusy: false };
     }
     return { verify: false, waitBusy: true };
   }
+  deferCounts.delete(rec.key);
   if (result === 'retry') {
     const attempts = (rec.attempts || 0) + 1;
-    setStatus(rec.key, 'stopped', {
-      attempts,
-      // Back off before the next attempt — a due record retried on every poll
-      // tick exhausts MAX_RESUME_ATTEMPTS in minutes. Manual records are
-      // exempt: `resume-now` promised an immediate wake, so a transient error
-      // must not silently defer it.
-      resetAt: rec.manual ? now : now + retryBackoffMs(attempts),
-      lastError: readState().sessions[rec.key]?.lastError,
-      verifyRetries: 0,
+    const episode = stopEpisodeAt(rec);
+    updateState(state => {
+      const current = state.sessions[rec.key];
+      if (!current || !['stopped', 'resuming'].includes(current.status)) return state;
+      if (stopEpisodeAt(current) !== episode) {
+        // A fresh detection superseded this failed attempt. If ingest kept the
+        // action marked in-flight, release it without charging the new stop.
+        if (current.status === 'resuming') {
+          Object.assign(current, { status: 'stopped', resumeEpisodeAt: null, verifyRetries: 0 });
+        }
+        return state;
+      }
+      Object.assign(current, {
+        status: 'stopped', attempts,
+        // Back off before the next attempt — a due record retried on every poll
+        // tick exhausts MAX_RESUME_ATTEMPTS in minutes. Manual records are
+        // exempt: `resume-now` promised an immediate wake, so a transient error
+        // must not silently defer it.
+        resetAt: rec.manual ? now : now + retryBackoffMs(attempts),
+        lastError: current.lastError, verifyRetries: 0, resumeEpisodeAt: null,
+      });
+      return state;
     });
     return { verify: false, waitBusy: false };
   }
   if (result === 'progress') {
-    setStatus(rec.key, 'stopped', { lastError: null, verifyRetries: 0 });
+    setStatus(rec.key, 'stopped', {
+      lastError: null, verifyRetries: 0, resumeEpisodeAt: null,
+    }, { expect: ['resuming'] });
+    return { verify: false, waitBusy: false };
+  }
+  if (result === 'already-resumed' || result === 'stale' || result === 'held' || result === 'probe') {
     return { verify: false, waitBusy: false };
   }
-  if (result === 'held' || result === 'probe') return { verify: false, waitBusy: false };
   return { verify: result === 'injected' || result === 'reopen', waitBusy: false };
 }
 
@@ -758,6 +976,12 @@ export async function runResumer({
         log(`cleanup tick failed: ${err.message}`);
       }
 
+      // Reconcile manual/provider retries before waiting/attempt-cap decisions.
+      // dispatchOne repeats this immediately before acting to close the race.
+      for (const rec of activeStopped()) {
+        finishIfClaudeProgressed(rec, getAgent(rec.agent));
+      }
+
       const stopped = activeStopped();
       const resuming = Object.values(readState().sessions).filter(s => s.status === 'resuming');
       // Additive: a pending/launching prompt-queue entry keeps a transient
@@ -774,7 +998,11 @@ 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) {
-          setStatus(s.key, 'failed', { lastError: 'max resume attempts exceeded', verifyRetries: 0 });
+          const applied = transitionStopEpisode(s, 'failed', {
+            lastError: 'max resume attempts exceeded', verifyRetries: 0,
+            resumeEpisodeAt: null,
+          }, { expect: ['stopped'] });
+          if (!applied) continue;
           log(`${s.key}: giving up after ${s.attempts} attempts`);
           notify('unsnooze gave up ⚠️', `${s.cwd}: ${s.attempts} resume attempts failed — check \`unsnooze status\``, { context: ctxOf(s), priority: 4 });
         }

package/src/sessions.js

@@ -40,8 +40,18 @@ export function latestSessionId(cwd, aroundTs = null) {
   return best ? best.id : null;
 }
 
-export function transcriptPath(cwd, sessionId) {
-  return join(projectDir(cwd), `${sessionId}.jsonl`);
+export function transcriptPath(cwd, sessionId, { claudeDir = CLAUDE_DIR } = {}) {
+  return join(claudeDir, 'projects', dashCwd(cwd), `${sessionId}.jsonl`);
+}
+
+export function claudeRecordEnv(env = process.env) {
+  if (!env.CLAUDE_CONFIG_DIR) return null;
+  return {
+    CLAUDE_CONFIG_DIR: env.CLAUDE_CONFIG_DIR,
+    ...(env.CLAUDE_SECURESTORAGE_CONFIG_DIR != null
+      ? { CLAUDE_SECURESTORAGE_CONFIG_DIR: env.CLAUDE_SECURESTORAGE_CONFIG_DIR }
+      : {}),
+  };
 }
 
 export function approxTokens(n) {
@@ -53,7 +63,11 @@ export function approxTokens(n) {
 // Tail-read only — transcripts reach tens of MB — doubling the window until a
 // usage entry appears or maxWindow is hit. null = unknown (missing file, no
 // usage found); callers skip the guard, like workspaceFingerprint's null.
-export function lastUsageTokens(path, { window = 256 * 1024, maxWindow = 4 * 1024 * 1024 } = {}) {
+export function lastUsageTokens(path, {
+  window = 256 * 1024,
+  maxWindow = 4 * 1024 * 1024,
+  afterMs = null,
+} = {}) {
   let fd;
   try {
     const { size } = statSync(path);
@@ -71,11 +85,24 @@ export function lastUsageTokens(path, { window = 256 * 1024, maxWindow = 4 * 102
         let entry;
         try { entry = JSON.parse(line); } catch { continue; }
         if (entry.isSidechain === true) continue;   // subagent traffic doesn't ride the main context
+        if (afterMs != null && entry.isApiErrorMessage === true && entry.error === 'rate_limit') {
+          // The newest main-context outcome is another stop, so an older
+          // successful turn cannot prove that the current episode resumed.
+          return null;
+        }
+        if (afterMs != null && (entry.isApiErrorMessage === true
+          || entry.type !== 'assistant' || entry.message?.role !== 'assistant')) continue;
         const u = entry.message?.usage;
         if (!u || typeof u !== 'object') continue;
         const sum = (u.input_tokens || 0) + (u.cache_creation_input_tokens || 0)
           + (u.cache_read_input_tokens || 0) + (u.output_tokens || 0);
-        if (sum > 0) return sum;   // zero-sum = synthetic/error entry, keep scanning
+        if (sum <= 0) continue;   // zero-sum = synthetic/error entry, keep scanning
+        if (afterMs == null) return sum;
+        const at = entry.timestamp ? Date.parse(entry.timestamp) : NaN;
+        if (Number.isFinite(at) && at > afterMs) return sum;
+        // Lines are chronological. Once the newest timestamped main-context
+        // usage is at/before the cutoff, no older entry can prove progress.
+        if (Number.isFinite(at)) return null;
       }
       if (len >= size || window >= maxWindow) return null;
       window = Math.min(window * 2, maxWindow);
@@ -86,3 +113,14 @@ export function lastUsageTokens(path, { window = 256 * 1024, maxWindow = 4 * 102
     if (fd !== undefined) closeSync(fd);
   }
 }
+
+// Durable evidence that Claude's parent context received a non-error response
+// after a recorded stop. Desktop records may live under an isolated
+// CLAUDE_CONFIG_DIR rather than the global ~/.claude tree.
+export function hasClaudeParentUsageAfter(rec, afterMs) {
+  if (!rec?.cwd || !rec?.sessionId || !Number.isFinite(afterMs)) return false;
+  const path = transcriptPath(rec.cwd, rec.sessionId, {
+    claudeDir: rec.env?.CLAUDE_CONFIG_DIR || process.env.CLAUDE_CONFIG_DIR || CLAUDE_DIR,
+  });
+  return lastUsageTokens(path, { afterMs }) != null;
+}

package/src/state.js

@@ -20,7 +20,9 @@ import { addressHash } from './lease.js';
 
 const log = makeLogger('state');
 
-const EMPTY = () => ({ version: 1, resumerPid: null, sessions: {}, calibration: {}, promptQueue: [] });
+const EMPTY = () => ({
+  version: 1, resumerPid: null, sessions: {}, calibration: {}, promptQueue: [], paneClosures: [],
+});
 
 function sleepSync(ms) {
   const buf = new SharedArrayBuffer(4);
@@ -98,6 +100,9 @@ function normalizeState(state) {
   }
   // One-shot prompt queue — always an array; corrupt/missing values reset empty.
   if (!Array.isArray(state.promptQueue)) state.promptQueue = [];
+  // Short-lived pane-generation tombstones prevent a detection racing a
+  // user-requested reap from publishing a just-closed pane as live.
+  if (!Array.isArray(state.paneClosures)) state.paneClosures = [];
   for (const rec of Object.values(state.sessions)) normalizeRecord(rec);
   return state;
 }
@@ -155,6 +160,24 @@ export function upsertSession(record, { after = null } = {}) {
   record = normalizeRecord({ ...record });
   return updateState(state => {
     prune(state);
+    const closing = state.paneClosures.find(c => c.pane && c.leaseId
+      && c.mux === record.mux && c.paneOwner === record.paneOwner
+      && c.pane === record.pane && c.leaseId === record.leaseId);
+    if (closing) {
+      // The close command has already been submitted. Keep the stop, but make
+      // it reopenable instead of attaching it to a pane that is going away.
+      record = {
+        ...record,
+        pane: null,
+        paneOwner: null,
+        muxSession: null,
+        leaseId: null,
+        pid: null,
+        pidBirth: null,
+        status: record.status === 'resuming' ? 'stopped' : record.status,
+        resumeEpisodeAt: null,
+      };
+    }
     let applied = null;
     const existingKey = findDuplicate(state, record);
     if (existingKey) {
@@ -175,6 +198,7 @@ export function upsertSession(record, { after = null } = {}) {
         lastAttemptAt: staleBanner ? existing.lastAttemptAt : record.lastAttemptAt,
         key: existingKey,
       };
+      if (merged.status !== 'resuming') merged.resumeEpisodeAt = null;
       state.sessions[existingKey] = merged;
       applied = merged;
       log(`merged duplicate detection for pane ${record.pane} into ${existingKey}`);
@@ -229,15 +253,19 @@ function findDuplicate(state, record) {
   return null;
 }
 
-// `expect`: compare-and-set — apply only while the record is still in one of
-// the listed statuses. Sweepers that decide from a snapshot (markStaleAbandoned)
-// must not clobber a record that moved on (e.g. to 'resumed') mid-decision.
-export function setStatus(key, status, extra = {}, { expect = null } = {}) {
+// `expect` / `expectCutoff`: compare-and-set — apply only while the record is
+// still in the expected state and stop episode. Snapshot-based decisions must
+// not clobber a record that moved on or was refreshed by a newer limit.
+export function setStatus(key, status, extra = {}, {
+  expect = null, expectCutoff = null,
+} = {}) {
   return updateState(state => {
     const s = state.sessions[key];
     if (!s) return state;
     if (expect && !expect.includes(s.status)) return state;
+    if (expectCutoff != null && (s.bannerAt ?? s.detectedAt) !== expectCutoff) return state;
     Object.assign(s, extra, { status });
+    if (status !== 'resuming') s.resumeEpisodeAt = null;
     return state;
   });
 }
@@ -258,6 +286,9 @@ export function prune(state) {
       return !(terminal && ts < cutoff);
     });
   }
+  const closureCutoff = Date.now() - DEDUPE_WINDOW_MS;
+  state.paneClosures = (Array.isArray(state.paneClosures) ? state.paneClosures : [])
+    .filter(c => Number.isFinite(c?.claimedAt) && c.claimedAt >= closureCutoff);
 }
 
 export function pruneNow() {
@@ -279,22 +310,31 @@ export async function sweepRecords({ resolveMux } = {}) {
     // 30 seconds of happening. Age-based prune() owns failed-record expiry.
     if (!['resumed', 'cancelled'].includes(rec.status)) continue;
     if (!rec.pane) {
-      drop.push(rec.key);
+      drop.push({ key: rec.key, status: rec.status, cutoff: rec.bannerAt ?? rec.detectedAt });
       continue;
     }
     try {
       const mux = resolveMux(rec);
-      if (!(await mux.paneAlive(rec.pane))) drop.push(rec.key);
+      if (!(await mux.paneAlive(rec.pane))) {
+        drop.push({ key: rec.key, status: rec.status, cutoff: rec.bannerAt ?? rec.detectedAt });
+      }
     } catch {
-      drop.push(rec.key);
+      drop.push({ key: rec.key, status: rec.status, cutoff: rec.bannerAt ?? rec.detectedAt });
     }
   }
   if (drop.length === 0) return 0;
+  let removed = 0;
   updateState(s => {
-    for (const key of drop) delete s.sessions[key];
+    for (const snapshot of drop) {
+      const current = s.sessions[snapshot.key];
+      if (current?.status !== snapshot.status
+        || (current.bannerAt ?? current.detectedAt) !== snapshot.cutoff) continue;
+      delete s.sessions[snapshot.key];
+      removed += 1;
+    }
     return s;
   });
-  return drop.length;
+  return removed;
 }
 
 // Non-terminal records with a dead/absent pane and old detectedAt are marked
@@ -320,11 +360,15 @@ export async function markStaleAbandoned({
     }
     if (!dead) continue;
     // CAS: the async liveness probe races real resumes — only mark failed if
-    // the record is still where the snapshot saw it.
-    setStatus(rec.key, 'failed', {
+    // the record is still where the snapshot saw it, including its episode.
+    const episode = rec.bannerAt ?? rec.detectedAt;
+    const next = setStatus(rec.key, 'failed', {
       lastError: rec.pane ? 'stale: pane dead' : 'stale: pane absent',
       verifyRetries: 0,
-    }, { expect: ['stopped', 'resuming'] });
+    }, { expect: ['stopped', 'resuming'], expectCutoff: episode });
+    const applied = next.sessions[rec.key];
+    if (applied?.status !== 'failed'
+      || (applied.bannerAt ?? applied.detectedAt) !== episode) continue;
     marked += 1;
     log(`${rec.key}: marked failed (stale abandoned, detectedAt ${new Date(rec.detectedAt || 0).toISOString()})`);
   }

package/src/tui.js

@@ -256,7 +256,7 @@ export function formatUsageTui(report, {
       const n = ladder.stopCount || 0;
       return `(calibrated from ${n} stop${n === 1 ? '' : 's'})`;
     }
-    return '(estimated — calibrating, needs one observed limit stop)';
+    return '(estimated — percentage unavailable)';
   });
 
   for (const a of report.agents || []) {

package/src/usage.js

@@ -200,13 +200,13 @@ export function ladderUsage({ exactPct = null, used = null, ceiling = null, stop
 }
 
 export function fmtUsageProvenance(ladder) {
-  if (!ladder) return '(estimated — calibrating, needs one observed limit stop)';
+  if (!ladder) return '(estimated — percentage unavailable)';
   if (ladder.tier === 'exact') return '(exact)';
   if (ladder.tier === 'calibrated') {
     const n = ladder.stopCount || 0;
     return `(calibrated from ${n} stop${n === 1 ? '' : 's'})`;
   }
-  return '(estimated — calibrating, needs one observed limit stop)';
+  return '(estimated — percentage unavailable)';
 }
 
 export function parseUsageWarnAt(raw) {

package/src/watchers/claude.js

@@ -52,9 +52,10 @@ export function latestRateLimitFromTranscript(cwd, sessionId, {
   now = Date.now(),
   window = 256 * 1024,
   maxWindow = 4 * 1024 * 1024,
+  claudeDir,
 } = {}) {
   if (!cwd || !sessionId) return null;
-  const path = transcriptPath(cwd, sessionId);
+  const path = transcriptPath(cwd, sessionId, { claudeDir });
   let fd;
   try {
     const { size } = statSync(path);