unsnooze 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 1.9.0 — 2026-07-13
+
+- **Context-size guard** (`contextGuard`: `off` | `inform` | `pause`, default
+  `inform`; threshold `contextGuardTokens`, default `100000`): waking a
+  session hours after a limit stop re-reads its entire context at full
+  uncached price (the provider's prompt cache expires in minutes) — a
+  150k-token session can eat a real slice of a fresh 5-hour window the moment
+  it wakes. unsnooze now estimates the size from the session transcript (the
+  last `message.usage` entry, tail-read) before dispatch: `inform` resumes
+  and notifies you of the price once the wake lands; `pause` holds sessions
+  at or above the threshold (`held: context ~152k tokens` in status) until
+  `unsnooze resume-now`, which always bypasses the guard. The estimate also
+  shows per-session in `unsnooze status` (`ctx ~152k tok`). Claude Code only
+  for now — the agent-adapter hook (`contextTokens`) is open for Codex, whose
+  rollout `token_count` events carry the same data. Prompted by r/ClaudeAI
+  feedback on a resume consuming 30% of a 5h quota.
+
 ## 1.8.1 — 2026-07-13
 
 - **Discovery / SEO**: package description and keywords expanded so npm and

package/README.md

@@ -200,6 +200,8 @@ unsnooze help                   # full command list (also -h / --help)
 | `agents.claude` / `agents.codex` | `true` | Which CLIs are guarded. |
 | `agents.grok` / `agents.qwen` / `agents.kimi` / `agents.opencode` / `agents.agy` | `false` | Experimental adapters — off by default; enable in `unsnooze setup` or `unsnooze config set agents.qwen on`. |
 | `workspaceGuard` | `inform` | Repo changed while a session slept? `inform` wakes it with a heads-up in the message; `pause` holds it (desktop notification, diff shown on `resume-now`); `off` disables. |
+| `contextGuard` | `inform` | Big cold context at wake? Waking a session re-reads its **entire context at full uncached price** ([why](#why-did-resuming-a-big-session-eat-so-much-of-my-quota)). `inform` resumes and notifies you of the size; `pause` holds sessions above the threshold for `unsnooze resume-now`; `off` disables. Claude Code only for now. |
+| `contextGuardTokens` | `100000` | Context-size threshold (tokens) at which `contextGuard` notifies or holds. |
 | `updateCheck` | `true` | Daily new-version check (a plain GET to the npm registry, nothing identifying is sent). Notices after commands + one desktop toast per version. |
 
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
@@ -258,6 +260,12 @@ watcher stops (no pane context) always use native.
   the wake, the resumed agent is told to re-read before acting — or, with
   `workspaceGuard=pause`, the session is held and `unsnooze resume-now`
   shows the diff first.
+- **Cold-cache wake guard**: waking a session after hours means the provider's
+  prompt cache is long expired — the first message re-reads the entire
+  context at full price, and a fat session can eat a real slice of the fresh
+  quota window. unsnooze estimates the size from the session transcript
+  (shown as `ctx ~152k tok` in `unsnooze status`) and, per `contextGuard`,
+  notifies you or holds the session instead of spending it silently.
 
 ## Requirements
 
@@ -327,6 +335,25 @@ continuing"). Set `workspaceGuard` to `pause` to hold such sessions for a
 manual `unsnooze resume-now` (which prints the diff stat), or `off` to
 disable the check.
 
+### Why did resuming a big session eat so much of my quota?
+
+Because of prompt-cache expiry, not because of unsnooze. Providers cache your
+session's context so each turn only pays full price for what's new — but that
+cache lives ~5 minutes. After hours stopped at a limit, the cache is long
+gone, so the **first** wake message (unsnooze's, or a hand-typed "continue" —
+identical cost either way; the wake message itself is ~30 tokens) makes the
+API re-read the entire conversation at full uncached price. A ~150k-token
+session on a top-tier model can cost a meaningful slice of a fresh 5-hour
+window the moment it wakes, before any new work happens.
+
+What actually helps: `/compact` (or starting a fresh session with a handoff
+summary) *before* you hit the limit, and keeping overnight sessions lean.
+What unsnooze does: the `contextGuard` setting estimates the context size
+from the session transcript before waking. `inform` (default) resumes and
+notifies you of the price; `pause` holds sessions above `contextGuardTokens`
+(default 100k) until you decide with `unsnooze resume-now`; the estimate is
+also visible per-session in `unsnooze status` (`ctx ~152k tok`).
+
 ### Does it work if my laptop was asleep or the terminal was closed?
 
 Yes — reset times are stored as absolute timestamps and checked every 30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Auto-resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode & Antigravity when the 5-hour/weekly usage limit resets — tmux, Zellij, VS Code & desktop apps. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
     "claude",

package/src/agents/claude.js

@@ -3,7 +3,7 @@
 // session-id lookup, and (claude-only) the interactive limit-menu driver.
 
 import { contentLines } from '../patterns.js';
-import { latestSessionId } from '../sessions.js';
+import { latestSessionId, transcriptPath, lastUsageTokens } from '../sessions.js';
 
 export const patterns = {
   // Claude Code renders limits across multiple TUI lines, e.g.:
@@ -93,6 +93,13 @@ export default {
     return { args: sessionId ? ['--resume', sessionId] : ['-c'], messageViaPane: true };
   },
   latestSessionId,
+  // Estimated tokens the API re-reads on a cold wake (prompt cache long
+  // expired). null → unknown, contextGuard skips. Adapters without this
+  // 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));
+  },
   // The foreground process for a claude session is `node` (nvm shim) or `claude`.
   isForegroundCommand(cmd) {
     return cmd === 'claude' || cmd === 'node' || cmd === 'unsnooze';

package/src/cli.js

@@ -4,6 +4,8 @@ import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { LOG_FILE, MAX_RESUME_ATTEMPTS } from './config.js';
 import { readState, setStatus, updateState } from './state.js';
+import { getAgent } from './agents/index.js';
+import { approxTokens } from './sessions.js';
 import { getConfig, setConfigValue, listConfig, CONFIG_FILE } from './settings.js';
 import { spawnResumerIfNeeded } from './spawn.js';
 
@@ -35,10 +37,18 @@ export function cmdStatus() {
       ? ` · msg: "${s.resumeMessage.length > 44 ? s.resumeMessage.slice(0, 44) + '…' : s.resumeMessage}"`
       : '';
     const hold = s.workspaceHold
-      ? ` · workspace changed (${s.holdReason ?? '?'}) — resume-now to wake`
+      ? ` · held: ${s.holdReason ?? '?'} — resume-now to wake`
       : '';
+    // The price of waking: estimated context tokens the API re-reads cold.
+    let ctx = '';
+    if (s.status === 'stopped') {
+      try {
+        const t = getAgent(s.agent).contextTokens?.(s);
+        if (t != null) ctx = ` · ctx ${approxTokens(t)} tok`;
+      } catch { /* estimate unavailable — omit */ }
+    }
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${hold}`);
+    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}`);
   }
   return 0;
 }

package/src/resumer.js

@@ -17,6 +17,7 @@ import { detectLimit, isBusy } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { parseResetTime, resetAtMs } from './time-parser.js';
 import { readState, updateState, setStatus, dueSessions, activeStopped } from './state.js';
+import { approxTokens } from './sessions.js';
 import { getConfig, resolveResumeMessage } from './settings.js';
 import { workspaceFingerprint, workspaceChanged, describeChange } from './workspace.js';
 import { notify } from './notify.js';
@@ -90,7 +91,7 @@ async function driveMenu(mux, pane, agent, text) {
 export async function dispatchOne(rec, {
   mux = resolveRecordMux(rec), resolveMux = null,
   resumeMessage, selfCmd = selfCommand(), fingerprint = workspaceFingerprint,
-  notifier = notify, matchesLease = leaseMatches,
+  notifier = notify, matchesLease = leaseMatches, contextTokens = null,
 } = {}) {
   resolveMux ||= () => mux;
   const key = rec.key;
@@ -108,7 +109,7 @@ export async function dispatchOne(rec, {
     if (change) {
       const desc = describeChange(change);
       if (guardMode === 'pause') {
-        setStatus(key, 'stopped', { workspaceHold: true, holdReason: desc });
+        setStatus(key, 'stopped', { workspaceHold: true, holdReason: `workspace changed (${desc})` });
         notifier('unsnooze: session held', `${rec.cwd}: workspace changed while stopped (${desc}) — run: unsnooze resume-now`, { context: ctxOf(rec) });
         log(`${key}: workspace changed (${desc}) — held (workspaceGuard=pause)`);
         return 'held';
@@ -118,6 +119,36 @@ export async function dispatchOne(rec, {
     }
   }
 
+  // Context-size guard: the prompt cache expired hours ago, so the first wake
+  // message re-reads the session's entire context at full (uncached) price.
+  // Estimate the size from the agent's transcript; `pause` holds big sessions,
+  // `inform` notifies the user — but only once the wake actually lands, since
+  // dispatchOne re-runs on every busy/retry tick. Manual resumes proceed.
+  let contextNote = null;
+  const ctxGuardMode = getConfig('contextGuard');
+  if (ctxGuardMode !== 'off' && !rec.manual) {
+    const estimate = contextTokens
+      ?? (typeof agent.contextTokens === 'function' ? r => agent.contextTokens(r) : null);
+    let tokens = null;
+    try { tokens = estimate ? estimate(rec) : null; } catch { /* unknown size — skip */ }
+    if (tokens != null && tokens >= getConfig('contextGuardTokens')) {
+      const size = approxTokens(tokens);
+      if (ctxGuardMode === 'pause') {
+        setStatus(key, 'stopped', { workspaceHold: true, holdReason: `context ${size} tokens` });
+        notifier('unsnooze: session held', `${rec.cwd}: waking would re-read ${size} tokens of context at full (uncached) price — run: unsnooze resume-now`, { context: ctxOf(rec) });
+        log(`${key}: context ${size} tokens ≥ threshold — held (contextGuard=pause)`);
+        return 'held';
+      }
+      contextNote = `${rec.cwd}: waking a ${size}-token session — its full context is re-read at full (uncached) price`;
+      log(`${key}: context ${size} tokens — informing (contextGuard=inform)`);
+    }
+  }
+  const notifyContext = () => {
+    if (contextNote) notifier('unsnooze: big-context wake', contextNote, { context: ctxOf(rec) });
+  };
+  const reopenGuarded = () =>
+    reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd, onDelivered: notifyContext });
+
   // Live-pane path: only if the pane still exists AND the agent CLI is its
   // foreground command (pane ids get recycled — never inject into a random
   // program).
@@ -140,7 +171,7 @@ export async function dispatchOne(rec, {
     const authorized = owned && contentOwned;
 
     if (menu) {
-      if (!authorized) return reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd });
+      if (!authorized) return reopenGuarded();
       if (!getConfig('menuAutoAnswer')) return 'held';
       try {
         if (await driveMenu(mux, rec.pane, agent, text)) return 'progress';
@@ -154,15 +185,18 @@ export async function dispatchOne(rec, {
       setStatus(key, 'resuming', { lastAttemptAt: Date.now(), lastError: null, verifyRetries: 0 });
       await mux.sendText(rec.pane, resumeMessage);
       log(`${key}: sent continue via ${rec.mux} ${rec.paneOwner ?? '-'}:${rec.pane}`);
+      notifyContext();
       return 'injected';
     }
     if (owned) return 'busy';
   }
 
-  return reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd });
+  return reopenGuarded();
 }
 
-async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd }) {
+// onDelivered fires only when the resume message actually reached the agent
+// (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 resume = agent.resumeArgs(rec.sessionId, resumeMessage);
   const leaseId = createLeaseId();
@@ -193,7 +227,7 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd }) {
 
   // The resume prompt traveled in argv (e.g. `codex resume <id> "msg"`) —
   // nothing to type into the TUI; verifyOne checks the outcome later.
-  if (!resume.messageViaPane) return 'reopen';
+  if (!resume.messageViaPane) { onDelivered(); return 'reopen'; }
 
   // Wait for the TUI to be ready (input prompt visible), then send the message.
   const deadline = Date.now() + READY_TIMEOUT_MS;
@@ -210,6 +244,7 @@ async function reopen(rec, { mux, resolveMux, agent, resumeMessage, selfCmd }) {
     if (!isBusy(text, agent.patterns.busyPatterns) && agent.patterns.idleRegex.test(text)) {
       await mux.sendText(address.pane, resumeMessage);
       log(`${key}: resume message sent to new pane ${address.pane}`);
+      onDelivered();
       return 'reopen';
     }
   }

package/src/sessions.js

@@ -1,8 +1,9 @@
 // Lookup helpers for Claude Code's transcript store (~/.claude/projects/).
 // Used to backfill sessionId when detection came from pane scraping and the
-// StopFailure hook didn't supply one.
+// StopFailure hook didn't supply one, and to estimate a session's context
+// size before waking it (contextGuard).
 
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
 import { CLAUDE_DIR } from './config.js';
 
@@ -37,3 +38,50 @@ export function latestSessionId(cwd, aroundTs = null) {
   }
   return best ? best.id : null;
 }
+
+export function transcriptPath(cwd, sessionId) {
+  return join(projectDir(cwd), `${sessionId}.jsonl`);
+}
+
+export function approxTokens(n) {
+  return n >= 1000 ? `~${Math.round(n / 1000)}k` : `~${n}`;
+}
+
+// Current context size of a session ≈ the last assistant entry's usage block:
+// everything the API read on that turn (fresh + cached) plus what it wrote.
+// 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 } = {}) {
+  let fd;
+  try {
+    const { size } = statSync(path);
+    fd = openSync(path, 'r');
+    for (;;) {
+      const len = Math.min(window, size);
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, size - len);
+      let text = buf.toString('utf-8');
+      if (len < size) text = text.slice(text.indexOf('\n') + 1);   // drop the partial first line
+      const lines = text.split('\n');
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line) continue;
+        let entry;
+        try { entry = JSON.parse(line); } catch { continue; }
+        if (entry.isSidechain === true) continue;   // subagent traffic doesn't ride the main context
+        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 (len >= size || window >= maxWindow) return null;
+      window = Math.min(window * 2, maxWindow);
+    }
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}

package/src/settings.js

@@ -21,6 +21,8 @@ export const DEFAULTS = {
   guiWatch: true,          // daemon watches transcripts/rollouts for GUI-session stops
   updateCheck: true,       // daily registry version check + update notices/toast
   workspaceGuard: 'inform', // repo changed while stopped: off | inform | pause
+  contextGuard: 'inform',   // wake re-reads a big cold context: off | inform | pause
+  contextGuardTokens: 100_000, // contextGuard notify/hold threshold (tokens)
   resumeMessage: 'Continue where you left off. The session was interrupted by a usage limit which has now reset — pick up the task you were working on and finish it.',
   resumeMessages: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '' },  // per-agent override; '' = use resumeMessage
   agents: { claude: true, codex: true, grok: false, qwen: false, kimi: false, opencode: false, agy: false },   // experimental agents default off
@@ -36,6 +38,8 @@ const ENV_NAMES = {
   guiWatch: 'UNSNOOZE_GUI_WATCH',
   updateCheck: 'UNSNOOZE_UPDATE_CHECK',
   workspaceGuard: 'UNSNOOZE_WORKSPACE_GUARD',
+  contextGuard: 'UNSNOOZE_CONTEXT_GUARD',
+  contextGuardTokens: 'UNSNOOZE_CONTEXT_GUARD_TOKENS',
   resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
   'resumeMessages.claude': 'UNSNOOZE_RESUME_MESSAGE_CLAUDE',
   'resumeMessages.codex': 'UNSNOOZE_RESUME_MESSAGE_CODEX',
@@ -59,6 +63,7 @@ const KNOWN_KEYS = Object.keys(ENV_NAMES);
 const ENUMS = {
   multiplexer: ['auto', 'tmux', 'zellij'],
   workspaceGuard: ['off', 'inform', 'pause'],
+  contextGuard: ['off', 'inform', 'pause'],
   notifyChannel: ['auto', 'native', 'osc', 'bell'],
 };
 
@@ -90,12 +95,22 @@ export function getConfig(key) {
     if (typeof def === 'boolean') {
       const b = parseBool(env);
       if (b !== null) return b;
+    } else if (typeof def === 'number') {
+      const n = parseInt(env, 10);
+      if (Number.isFinite(n)) return n;
     } else {
       return env;
     }
   }
   const fromFile = dig(readFileConfig(), key);
-  return fromFile !== undefined ? fromFile : def;
+  if (fromFile === undefined) return def;
+  if (typeof def === 'number') {
+    // Hand-edited files may hold anything; a non-numeric value must not
+    // silently disable a threshold — fall back to the default instead.
+    const n = Number(fromFile);
+    return Number.isFinite(n) ? n : def;
+  }
+  return fromFile;
 }
 
 // The message to send a given agent: its resumeMessages.<id> override when
@@ -117,6 +132,10 @@ export function setConfigValue(key, rawValue) {
     const b = typeof rawValue === 'boolean' ? rawValue : parseBool(String(rawValue));
     if (b === null) throw new Error(`unsnooze: "${key}" needs a boolean (on/off, true/false)`);
     value = b;
+  } else if (typeof def === 'number') {
+    const n = parseInt(String(rawValue), 10);
+    if (!Number.isFinite(n) || n <= 0) throw new Error(`unsnooze: "${key}" needs a positive integer`);
+    value = n;
   } else {
     value = String(rawValue);
     if (ENUMS[key] && !ENUMS[key].includes(value)) {