unsnooze 1.19.5 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.20.0 — 2026-10-08
+
+Window priming starts your 5-hour window before you sit down, and `doctor`
+stops flagging a Claude hook you don't need.
+
+### Window priming (experimental)
+
+- Claude's 5-hour window starts with your first message, so starting work at
+  9am means a reset at 2pm. `unsnooze config set primeAt.claude 06:00` has the
+  daemon send one tiny Haiku prompt at 6am, so the window resets at 11am and a
+  fresh one lands mid-morning. Codex works the same on plans with a 5-hour
+  window (`primeAt.codex`).
+- `primeAt.claude auto` works out the time for you: it learns when you usually
+  start from the last 3 weeks of your own prompts (ignoring tool results,
+  subagents, revivals and late nights running past midnight) and primes 3 hours
+  before. It waits for 5 days of history and re-learns daily.
+- Every prime checks the reset time in the reply and reports whether it
+  started the window, found one already running, or found no 5-hour window on
+  the plan. `unsnooze prime` shows the schedule and last result;
+  `unsnooze prime now` runs one immediately. `primeDays weekdays` skips
+  weekends.
+- A prime that fails (say, the network is not back yet after waking) retries
+  up to three times, five minutes apart, and notifies once.
+- A prime that hits a limit is never treated as a session to revive.
+
+### `unsnooze doctor`
+
+- No longer reports a missing Claude StopFailure hook when Claude is disabled.
+  `unsnooze install --yes` skips that hook for a disabled Claude, so the
+  finding could never be cleared (#44).
+
 ## 1.19.5 — 2026-10-05
 
 Sessions resume again under psmux, Antigravity no longer wakes early, and

package/README.md

@@ -128,6 +128,12 @@ reset, and unsnooze does that for every stopped session automatically.
 you would, resumes once, and checks the limit actually lifted. It replaces the
 4am alarm, not the limit.
 
+**Can it start my 5-hour window before I sit down?** Yes, experimentally:
+`unsnooze config set primeAt.claude auto` learns when you usually start and has
+the daemon send one tiny Haiku prompt 3 hours earlier, so the window resets
+mid-session instead of 5 hours in. A fixed time like `06:00` works too. Claude
+and Codex only. See [window priming](https://unsnooze.dev/docs/commands/#prime).
+
 More questions and troubleshooting: [unsnooze.dev/docs/troubleshooting](https://unsnooze.dev/docs/troubleshooting/).
 
 ## Documentation

package/bin/unsnooze.js

@@ -159,6 +159,10 @@ async function main() {
       const { cmdUsage } = await import('../src/usage.js');
       return cmdUsage(rest);
     }
+    case 'prime': {
+      const { cmdPrime } = await import('../src/prime.js');
+      return cmdPrime(rest);
+    }
     case 'hosts': {
       const { cmdHosts } = await import('../src/fleet.js');
       return cmdHosts(rest);
@@ -364,6 +368,8 @@ Usage:
   unsnooze prompt remove <id>      cancel a queued prompt
   unsnooze prompt clear            cancel all pending queued prompts
   unsnooze usage [--json]          account burn rate & time-to-limit forecast
+  unsnooze prime [now [agent]]     window priming (experimental): start the 5-hour
+                                   window early — set a time with primeAt.claude
                                    (--install-statusline for exact Claude %,
                                     --uninstall-statusline to remove it)
   unsnooze design [setup]          Claude Design from the terminal: check whether

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.19.5",
+  "version": "1.20.0",
   "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, Antigravity, and Cursor CLI sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",

package/src/config.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { join, resolve, win32 } from 'node:path';
 import {
   mkdirSync, chmodSync, writeFileSync, renameSync, lstatSync, statSync, readdirSync,
 } from 'node:fs';
@@ -14,6 +14,20 @@ export const STATE_FILE = join(STATE_DIR, 'state.json');
 export const LOCK_DIR = join(STATE_DIR, 'state.lock');
 export const LOG_FILE = join(STATE_DIR, 'unsnooze.log');
 export const EVENTS_DIR = join(STATE_DIR, 'events');
+// Working dir for window primes (prime.js) — the watcher ignores stops in it.
+export const PRIME_DIR = join(STATE_DIR, 'prime');
+
+// Is this (agent-recorded) cwd the prime dir? Codex may record it with a
+// \\?\ prefix or another drive-letter case on Windows.
+export function isPrimeDir(dir, primeDir = PRIME_DIR, platform = process.platform) {
+  if (!dir) return false;
+  const norm = p => {
+    const raw = String(p).replace(/^\\\\\?\\/, '');
+    return platform === 'win32' ? win32.resolve(raw).toLowerCase() : resolve(raw);
+  };
+  return norm(dir) === norm(primeDir);
+}
+
 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');

package/src/doctor.js

@@ -238,7 +238,9 @@ export async function runDoctor({
     });
   }
 
-  if (!hookInstalled()) {
+  // install only writes the hook for an enabled claude, so a codex-only
+  // setup must not be told to run an install that can never clear this.
+  if (enabled('claude') && !hookInstalled()) {
     findings.push({
       id: 'hook-missing', kind: 'health',
       title: 'Claude StopFailure hook is not installed',

package/src/hook.js

@@ -62,6 +62,8 @@ export async function runHook(rest = [], { ensureDaemonFn = ensureDaemon } = {})
     const agentIdx = rest.indexOf('--agent');
     const agent = getAgent(agentIdx !== -1 ? rest[agentIdx + 1] : 'claude');
     if (!getConfig(`agents.${agent.id}`)) return 0;   // agent disabled in settings
+    // A window prime (prime.js) is a throwaway one-shot — never a session to revive.
+    if (process.env.UNSNOOZE_PRIME) return 0;
     // Nothing keeps the daemon running on native Windows (see ensureDaemon),
     // and the hook is the one entry point GUI Claude sessions pass through —
     // so it makes sure the daemon is up. A no-op everywhere else.

package/src/prime-learn.js

@@ -0,0 +1,172 @@
+// primeAt.<id> = auto: learn when the user starts work from their own local
+// history, and prime LEAD_MS before it so the reset lands a couple of hours
+// into the session.
+//
+// "Starts work" = the first human prompt of a day that follows IDLE_GAP_MS of
+// no prompts — a window's worth of quiet. That gap rule is what keeps a late
+// night running past midnight from reading as a 00:10 start. Only human
+// prompts count: tool results, subagent turns, unsnooze's own resume messages
+// and primes are activity unsnooze or the agent produced, and a 4am revival
+// must not teach it that the user starts at 4am.
+//
+// Usage outside these agents' local history (claude.ai, the desktop app) is
+// invisible here; a prime that finds the window already running says so.
+//
+// History is large (hundreds of MB of transcripts), so per-file results are
+// cached by size+mtime in ACTIVITY_FILE and only changed files are re-read.
+
+import { createReadStream, readdirSync, statSync, readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join, dirname } from 'node:path';
+import { CLAUDE_DIR, CODEX_DIR, STATE_DIR, isPrimeDir, writePrivateFile, ensureStateDir } from './config.js';
+import { resolveResumeMessage } from './settings.js';
+
+export const LEARN_DAYS = 21;
+export const MIN_DAYS = 5;
+const IDLE_GAP_MS = 5 * 3_600_000;
+export const LEAD_MS = 3 * 3_600_000;
+const BUCKET_MS = 5 * 60_000;
+const DAY_MS = 86_400_000;
+
+export const ACTIVITY_FILE = () => join(STATE_DIR, 'prime-activity.json');
+
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  if (content.some(b => b?.type === 'tool_result')) return null;
+  const parts = content.filter(b => b?.type === 'text' || b?.type === 'input_text').map(b => b.text || '');
+  return parts.length ? parts.join('\n') : null;
+}
+
+// Epoch ms of a human prompt on this line, else null.
+export function promptTimestamp(agentId, line, { resumePrefix = '' } = {}) {
+  if (agentId === 'claude' ? !line.includes('"type":"user"') : !line.includes('"role":"user"')) return null;
+  let j;
+  try { j = JSON.parse(line); } catch { return null; }
+  let text;
+  if (agentId === 'claude') {
+    if (j.type !== 'user' || j.isSidechain || j.isMeta || j.isCompactSummary) return null;
+    text = textOf(j.message?.content);
+  } else {
+    const p = j.payload;
+    if (j.type !== 'response_item' || p?.type !== 'message' || p.role !== 'user') return null;
+    text = textOf(p.content);
+    // Codex injects <environment_context>, <user_instructions> and AGENTS.md
+    // as user messages at every session start — revivals included.
+    if (text != null && /^\s*(<[a-z_]+>|# AGENTS\.md)/i.test(text)) return null;
+  }
+  if (text == null) return null;
+  if (resumePrefix && text.trimStart().startsWith(resumePrefix)) return null;
+  const ts = Date.parse(j.timestamp);
+  return Number.isFinite(ts) ? ts : null;
+}
+
+// Claude: projects/<dashed-cwd>/<session>.jsonl. Codex: sessions/YYYY/MM/DD/.
+export function historyFiles(agentId, { since, claudeDir = CLAUDE_DIR, codexDir = CODEX_DIR } = {}) {
+  const out = [];
+  const ls = dir => { try { return readdirSync(dir); } catch { return []; } };
+  const add = path => {
+    try {
+      const st = statSync(path);
+      if (st.isFile() && st.mtimeMs >= since) out.push({ path, size: st.size, mtimeMs: st.mtimeMs });
+    } catch { /* vanished */ }
+  };
+  if (agentId === 'claude') {
+    const root = join(claudeDir, 'projects');
+    for (const d of ls(root)) for (const f of ls(join(root, d))) if (f.endsWith('.jsonl')) add(join(root, d, f));
+  } else {
+    const root = join(codexDir, 'sessions');
+    for (const y of ls(root)) for (const m of ls(join(root, y))) for (const d of ls(join(root, y, m))) {
+      // Day dirs older than the window cannot hold anything newer than it.
+      if (Date.parse(`${y}-${m}-${d}T00:00:00Z`) < since - DAY_MS) continue;
+      for (const f of ls(join(root, y, m, d))) if (f.endsWith('.jsonl')) add(join(root, y, m, d, f));
+    }
+  }
+  return out;
+}
+
+async function scanFile(agentId, path, resumePrefix) {
+  const buckets = new Set();
+  const rl = createInterface({ input: createReadStream(path, { encoding: 'utf-8' }), crlfDelay: Infinity });
+  let first = true;
+  for await (const line of rl) {
+    if (first && agentId === 'codex') {
+      first = false;
+      // A prime's own rollout is not the user starting work.
+      try { if (isPrimeDir(JSON.parse(line)?.payload?.cwd)) { rl.close(); return []; } } catch { /* no meta */ }
+    }
+    const ts = promptTimestamp(agentId, line, { resumePrefix });
+    if (ts != null) buckets.add(Math.floor(ts / BUCKET_MS) * BUCKET_MS);
+  }
+  return [...buckets].sort((a, b) => a - b);
+}
+
+// Prompt timestamps (5-minute buckets) over the learning window.
+export async function collectPrompts(agentId, {
+  now = Date.now(), cacheFile = ACTIVITY_FILE(), files = null, scan = scanFile, ...dirs
+} = {}) {
+  const since = now - LEARN_DAYS * DAY_MS;
+  const resumePrefix = resolveResumeMessage(agentId).trim().slice(0, 40);
+  let cache = {};
+  try { cache = JSON.parse(readFileSync(cacheFile, 'utf-8'))?.[agentId] || {}; } catch { /* first run */ }
+  // Cached timestamps were filtered with the resume message of their day.
+  if (cache.resumePrefix !== resumePrefix) cache = {};
+  const cachedFiles = cache.files || {};
+  const next = {};
+  const all = [];
+  for (const f of files || historyFiles(agentId, { since, ...dirs })) {
+    const hit = cachedFiles[f.path];
+    const ts = hit && hit.size === f.size && hit.mtimeMs === f.mtimeMs
+      ? hit.ts
+      : await scan(agentId, f.path, resumePrefix).catch(() => []);
+    next[f.path] = { size: f.size, mtimeMs: f.mtimeMs, ts };
+    for (const t of ts) if (t >= since) all.push(t);
+  }
+  try {
+    let whole = {};
+    try { whole = JSON.parse(readFileSync(cacheFile, 'utf-8')) || {}; } catch { /* fresh */ }
+    whole[agentId] = { resumePrefix, files: next };
+    ensureStateDir(dirname(cacheFile));
+    writePrivateFile(cacheFile, `${cacheFile}.tmp.${process.pid}`, JSON.stringify(whole));
+  } catch { /* cache is an optimisation */ }
+  return all.sort((a, b) => a - b);
+}
+
+const minuteOfDay = ms => { const d = new Date(ms); return d.getHours() * 60 + d.getMinutes(); };
+
+// The usual start time (minutes after local midnight): for each day, the
+// prompt after the longest quiet of at least IDLE_GAP_MS — the one after
+// sleep, not a stray 00:30 prompt after an evening break — then the median.
+// The earliest prompt on record is never a start: what came before it is
+// unknown. null until MIN_DAYS days qualify.
+export function learnStart(timestamps, { days = 'daily' } = {}) {
+  const perDay = new Map();
+  for (let i = 1; i < timestamps.length; i++) {
+    const t = timestamps[i];
+    const gap = t - timestamps[i - 1];
+    if (gap < IDLE_GAP_MS) continue;
+    const d = new Date(t);
+    if (days === 'weekdays' && (d.getDay() === 0 || d.getDay() === 6)) continue;
+    const key = `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+    if (!perDay.has(key) || gap > perDay.get(key).gap) perDay.set(key, { gap, minutes: minuteOfDay(t) });
+  }
+  const mins = [...perDay.values()].map(v => v.minutes).sort((a, b) => a - b);
+  if (mins.length < MIN_DAYS) return { minutes: null, days: mins.length };
+  const mid = mins.length >> 1;
+  const minutes = mins.length % 2 ? mins[mid] : Math.round((mins[mid - 1] + mins[mid]) / 2);
+  return { minutes, days: mins.length };
+}
+
+export const hhmm = minutes => {
+  const m = ((minutes % 1440) + 1440) % 1440;
+  return `${String(Math.floor(m / 60)).padStart(2, '0')}:${String(m % 60).padStart(2, '0')}`;
+};
+
+// Learn and turn into a prime slot: { start, slot, wrap, days } or
+// { slot: null, days }. wrap: the slot falls the evening before (start < 03:00).
+export async function learnSlot(agentId, { days = 'daily', ...opts } = {}) {
+  const learned = learnStart(await collectPrompts(agentId, opts), { days });
+  if (learned.minutes == null) return { slot: null, start: null, days: learned.days };
+  const slotMinutes = learned.minutes - LEAD_MS / 60_000;
+  return { start: hhmm(learned.minutes), slot: hhmm(slotMinutes), wrap: slotMinutes < 0, days: learned.days };
+}

package/src/prime.js

@@ -0,0 +1,384 @@
+// Window priming (experimental). Claude's 5-hour window — and Codex's, on
+// plans that have one — starts on the first message after a reset, not on a
+// clock. One tiny prompt to the cheapest model at a chosen time (primeAt.<id>,
+// or `auto` — learned from history, see prime-learn.js) starts it early, so
+// the reset lands mid-workday instead of mid-afternoon.
+//
+// Only claude and codex: Cursor and Grok reset on a fixed billing clock,
+// Qwen's 5h quota slides per request (and its terms forbid scheduled
+// non-interactive use), and Kimi/Antigravity are unverified.
+//
+// Every prime checks itself: the reply carries the window's reset time, and a
+// reset ~5h after the prime means it started the window. Anything else is
+// reported as it is — already running, no 5-hour window on this plan, failed.
+
+import { spawn } from 'node:child_process';
+import { readdirSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PRIME_DIR, CODEX_DIR } from './config.js';
+import { getConfig } from './settings.js';
+import { getAgent } from './agents/index.js';
+import { updateState, readState } from './state.js';
+import { extractCodexUsage } from './usage.js';
+import { makeLogger } from './logger.js';
+import { learnSlot, MIN_DAYS } from './prime-learn.js';
+import { standaloneEnv } from './spawn.js';
+
+const log = makeLogger('prime');
+
+export const PRIME_AGENTS = ['claude', 'codex'];
+const PROMPT = 'Reply with just: ok';
+const FIVE_HOURS_MS = 5 * 3_600_000;
+// A window started by this prime resets 5h after it, give or take the
+// run time and the minute the server rounds to.
+const STARTED_SLACK_MS = 10 * 60_000;
+// A machine asleep at the scheduled time still primes on wake, within this.
+// Later than that the day is skipped — the user is likely working by then.
+export const GRACE_MS = 4 * 3_600_000;
+const RUN_TIMEOUT_MS = 3 * 60_000;
+
+// "6:00" / "06:00" → "06:00"; "auto"; "" / "off" → ""; anything else → null.
+export function normalizePrimeAt(raw) {
+  const value = String(raw ?? '').trim();
+  if (value === '' || /^off$/i.test(value)) return '';
+  if (/^auto$/i.test(value)) return 'auto';
+  const m = value.match(/^([01]?\d|2[0-3]):([0-5]\d)$/);
+  return m ? `${m[1].padStart(2, '0')}:${m[2]}` : null;
+}
+
+export function dayKey(ms) {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// The day a prime is due for right now, as a dayKey, else null. The slot is
+// local time, open for GRACE_MS — yesterday's slot too, so a machine asleep
+// across midnight still primes on wake. `wrap` marks a slot that falls the
+// evening before the day it serves (auto, for a start before 03:00): the
+// weekday check and the once-a-day key belong to that next day.
+export function dueDay({ at, days = 'daily', lastDay = null, now = Date.now(), wrap = false }) {
+  const hhmm = normalizePrimeAt(at);
+  if (!hhmm || hhmm === 'auto') return null;   // auto resolves to a slot first
+  const [h, m] = hhmm.split(':').map(Number);
+  const d = new Date(now);
+  for (const back of [0, 1]) {
+    const slot = new Date(d.getFullYear(), d.getMonth(), d.getDate() - back, h, m);
+    if (now < slot.getTime() || now - slot.getTime() > GRACE_MS) continue;
+    const served = new Date(slot.getFullYear(), slot.getMonth(), slot.getDate() + (wrap ? 1 : 0));
+    if (days === 'weekdays' && (served.getDay() === 0 || served.getDay() === 6)) continue;
+    const key = dayKey(served.getTime());
+    if (key !== lastDay) return key;
+  }
+  return null;
+}
+
+export const primeDue = opts => dueDay(opts) !== null;
+
+// Codex model slugs vary by account, so the default is the first "luna" or
+// "mini" model this install has cached, else codex's own default.
+export function codexPrimeModel({ codexDir = CODEX_DIR } = {}) {
+  try {
+    const cache = JSON.parse(readFileSync(join(codexDir, 'models_cache.json'), 'utf-8'));
+    const list = Array.isArray(cache) ? cache : cache.models || [];
+    const slug = list.map(m => m?.slug || m?.id).find(s => /luna|mini/i.test(s || ''));
+    return slug || '';
+  } catch { return ''; }
+}
+
+export function primeModel(agentId, opts) {
+  const set = getConfig(`primeModel.${agentId}`);
+  if (set) return set;
+  return agentId === 'claude' ? 'haiku' : codexPrimeModel(opts);
+}
+
+export function primeArgs(agentId, { model = '', cwd = PRIME_DIR } = {}) {
+  if (agentId === 'claude') {
+    // stream-json --verbose is what carries the rate_limit_event readback.
+    return ['-p', PROMPT, ...(model ? ['--model', model] : []), '--no-session-persistence',
+      '--output-format', 'stream-json', '--verbose'];
+  }
+  // No --ephemeral: the rollout it suppresses is the readback.
+  return ['exec', '--json', ...(model ? ['-m', model] : []), '-c', 'model_reasoning_effort="low"',
+    '-s', 'read-only', '--skip-git-repo-check', '-C', cwd, PROMPT];
+}
+
+function jsonLines(text) {
+  return String(text || '').split('\n').map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+// Claude: the rate_limit_events in the stream-json output. Any one of them
+// may describe another bucket (weekly, overage), so "no 5-hour window" is
+// only the answer when none of them carries one.
+export function parseClaudePrime(stdout) {
+  let seen = false;
+  for (const m of jsonLines(stdout)) {
+    if (m.type !== 'rate_limit_event') continue;
+    seen = true;
+    const info = m.rate_limit_info || {};
+    const five = info.unifiedWindows?.five_hour?.resetsAt
+      ?? (info.rateLimitType === 'five_hour' ? info.resetsAt : null);
+    if (Number.isFinite(five)) return { resetsAtMs: five * 1000 };
+  }
+  return seen ? { noWindow: true } : null;
+}
+
+// Newest-first day dirs under sessions/YYYY/MM/DD — a prime's rollout is in
+// one of the last couple.
+function recentDayDirs(root, limit = 3) {
+  const out = [];
+  const desc = dir => { try { return readdirSync(dir).filter(n => /^\d+$/.test(n)).sort().reverse(); } catch { return []; } };
+  for (const y of desc(root)) for (const mo of desc(join(root, y))) for (const d of desc(join(root, y, mo))) {
+    out.push(join(root, y, mo, d));
+    if (out.length >= limit) return out;
+  }
+  return out;
+}
+
+// Codex: thread_id from `exec --json`, then the rollout's last token_count.
+export function parseCodexPrime(stdout, { codexDir = CODEX_DIR } = {}) {
+  const started = jsonLines(stdout).find(m => m.type === 'thread.started');
+  if (!started?.thread_id) return null;
+  for (const dir of recentDayDirs(join(codexDir, 'sessions'))) {
+    let name;
+    try { name = readdirSync(dir).find(n => n.endsWith(`${started.thread_id}.jsonl`)); } catch { continue; }
+    if (!name) continue;
+    const lines = readFileSync(join(dir, name), 'utf-8').split('\n');
+    let last = null;
+    for (const line of lines) last = extractCodexUsage(line) || last;
+    if (!last) return null;
+    const five = [last.primary, last.secondary].find(w => w?.windowMinutes === 300);
+    return five?.resetsAtMs ? { resetsAtMs: five.resetsAtMs } : { noWindow: true, planType: last.planType };
+  }
+  return null;
+}
+
+// stdin closed: `codex exec` with a piped stdin reads it as extra prompt
+// input and exits with no output at all.
+// Resolves on `exit`, not only `close`: a grandchild holding the pipes open
+// must not leave the prime — and with it every later tick — waiting forever.
+function defaultRunner(bin, args, opts) {
+  return new Promise(resolve => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    let done = false;
+    const timers = [];
+    const finish = result => {
+      if (done) return;
+      done = true;
+      timers.forEach(clearTimeout);
+      resolve({ stdout, stderr, ...result });
+    };
+    try {
+      child = spawn(bin, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (err) { finish({ err }); return; }
+    timers.push(setTimeout(() => {
+      child.kill();
+      // An agent that ignores SIGTERM still has to give the tick back.
+      timers.push(setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* gone */ }
+        finish({ err: Object.assign(new Error('timed out'), { killed: true }) });
+      }, 5_000));
+    }, RUN_TIMEOUT_MS));
+    child.stdout.on('data', d => { stdout += d; });
+    child.stderr.on('data', d => { stderr += d; });
+    child.on('error', err => finish({ err }));
+    const settle = (code, signal) => finish({
+      err: code === 0 ? null : Object.assign(new Error(`exit ${code ?? signal}`), { killed: !!signal }),
+    });
+    // close = all output read; exit + a short drain covers held-open pipes.
+    child.on('close', settle);
+    child.on('exit', (code, signal) => { timers.push(setTimeout(() => settle(code, signal), 2_000)); });
+  });
+}
+
+// One prime, verified. Never throws.
+export async function runPrime(agentId, { runner = defaultRunner, now = () => Date.now(), codexDir = CODEX_DIR } = {}) {
+  const at = now();
+  const model = primeModel(agentId, { codexDir });
+  const base = { agent: agentId, at, model: model || null };
+  try {
+    mkdirSync(PRIME_DIR, { recursive: true, mode: 0o700 });
+    const agent = getAgent(agentId);
+    const { err, stdout, stderr } = await runner(agent.bin, primeArgs(agentId, { model, cwd: PRIME_DIR }), {
+      cwd: PRIME_DIR,
+      // standaloneEnv: `prime now` from inside a Claude Code session must not
+      // hand its session markers (CLAUDECODE, UNSNOOZE_MUX…) to the prime.
+      // The StopFailure hook ignores runs carrying UNSNOOZE_PRIME, so a prime
+      // that hits a limit is never recorded as a session to revive.
+      env: { ...standaloneEnv(), UNSNOOZE_PRIME: '1' },
+    });
+    const read = agentId === 'claude' ? parseClaudePrime(stdout) : parseCodexPrime(stdout, { codexDir });
+    if (!read) {
+      const why = err ? (err.killed ? 'timed out' : (stderr.trim().split('\n').pop() || err.message)) : 'no rate-limit readback in the reply';
+      return { ...base, outcome: 'failed', detail: why.slice(0, 200) };
+    }
+    if (read.noWindow) return { ...base, outcome: 'no-window', planType: read.planType || null };
+    const started = Math.abs(read.resetsAtMs - (at + FIVE_HOURS_MS)) <= STARTED_SLACK_MS;
+    return { ...base, outcome: started ? 'started' : 'running', resetsAtMs: read.resetsAtMs };
+  } catch (e) {
+    return { ...base, outcome: 'failed', detail: String(e.message).slice(0, 200) };
+  }
+}
+
+const hm = ms => new Date(ms).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+
+export function formatPrimeResult(r) {
+  switch (r.outcome) {
+    case 'started': return `${r.agent} 5-hour window started — resets ${hm(r.resetsAtMs)}`;
+    case 'running': return `${r.agent} 5-hour window was already running — resets ${hm(r.resetsAtMs)}`;
+    case 'no-window': return `${r.agent} has no 5-hour window${r.planType ? ` on the ${r.planType} plan` : ''} — priming does nothing here (unsnooze config set primeAt.${r.agent} off)`;
+    case 'pending': return `${r.agent} prime in progress`;
+    default: return `${r.agent} prime failed: ${r.detail || 'unknown error'}`;
+  }
+}
+
+const PRIME_TITLES = {
+  started: 'window primed',
+  running: 'window already running',
+  'no-window': 'window priming does nothing',
+};
+
+// A failed prime (network still down after wake, a 5xx) retries within the
+// slot's grace, a few times and not back to back.
+const MAX_ATTEMPTS = 3;
+const RETRY_GAP_MS = 5 * 60_000;
+
+// The day this record has settled, as dueDay's lastDay: a failure with tries
+// left settles nothing once the retry gap has passed.
+function settledDay(rec, now) {
+  if (!rec) return null;
+  const retry = rec.outcome === 'failed' && !rec.manual
+    && (rec.attempts || 1) < MAX_ATTEMPTS && now - rec.at >= RETRY_GAP_MS;
+  return retry ? null : rec.day;
+}
+
+// Scheduled results keep the day they served and the attempt count; a manual
+// `prime now` keeps whatever the schedule had, so testing at 05:00 does not
+// cancel the 06:00 prime.
+function record(result, { day, attempts, manual = false } = {}) {
+  updateState(state => {
+    state.prime = state.prime && typeof state.prime === 'object' ? state.prime : {};
+    const prev = state.prime[result.agent] || {};
+    state.prime[result.agent] = manual
+      ? { learned: prev.learned, ...result, day: prev.day ?? null, attempts: prev.attempts, manual: true }
+      : { learned: prev.learned, ...result, day, attempts };
+  });
+}
+
+// The slot to prime at: the fixed time, or for auto the learned one —
+// re-learned once a day and kept in state, so ticks in between cost nothing.
+async function resolveSlot(id, { now, days, last, learn }) {
+  const at = normalizePrimeAt(getConfig(`primeAt.${id}`));
+  if (at !== 'auto') return { at, wrap: false };
+  const known = last[id]?.learned;
+  if (known?.day === dayKey(now) && known.primeDays === days) return { at: known.slot, wrap: !!known.wrap };
+  const learned = { ...(await learn(id, { days, now })), day: dayKey(now), primeDays: days };
+  updateState(state => {
+    state.prime = state.prime && typeof state.prime === 'object' ? state.prime : {};
+    state.prime[id] = { ...(state.prime[id] || { agent: id }), learned };
+  });
+  log(learned.slot
+    ? `${id}: usually starts ~${learned.start} (${learned.days} days) — priming at ${learned.slot}`
+    : `${id}: auto priming still learning (${learned.days} of ${MIN_DAYS} days)`);
+  return { at: learned.slot, wrap: !!learned.wrap };
+}
+
+let ticking = false;
+
+// Daemon tick. The day is claimed before the run starts, so the next tick
+// (or a second daemon) cannot fire the same prime while this one is out.
+export async function tickPrime({ now = Date.now(), run = runPrime, notifyFn = null, learn = learnSlot } = {}) {
+  const on = PRIME_AGENTS.filter(id => getConfig(`agents.${id}`) && normalizePrimeAt(getConfig(`primeAt.${id}`)));
+  if (!on.length || ticking) return [];   // the common case: priming off, no state read
+  ticking = true;
+  try { return await tickOn(on, { now, run, notifyFn, learn }); } finally { ticking = false; }
+}
+
+async function tickOn(on, { now, run, notifyFn, learn }) {
+  const days = getConfig('primeDays');
+  const last = readState().prime || {};
+  const due = new Map();
+  for (const id of on) {
+    const { at, wrap } = await resolveSlot(id, { now, days, last, learn });
+    const day = dueDay({ at, wrap, days, lastDay: settledDay(last[id], now), now });
+    if (day) due.set(id, day);
+  }
+  if (!due.size) return [];
+  // Claimed under the state lock, so a second daemon cannot fire it too.
+  const claimed = new Map();
+  updateState(state => {
+    state.prime = state.prime && typeof state.prime === 'object' ? state.prime : {};
+    for (const [id, day] of due) {
+      const rec = state.prime[id];
+      if (settledDay(rec, now) === day) continue;
+      const attempts = rec?.day === day && rec.outcome === 'failed' ? (rec.attempts || 1) + 1 : 1;
+      claimed.set(id, { day, attempts });
+      state.prime[id] = { learned: rec?.learned, agent: id, at: now, day, attempts, outcome: 'pending' };
+    }
+  });
+  const notify = notifyFn || (await import('./notify.js')).notify;
+  const results = [];
+  for (const [id, claim] of claimed) {
+    const result = await run(id);
+    record(result, claim);
+    const line = formatPrimeResult(result);
+    log(line);
+    // A failure with retries left is only logged — one toast per prime.
+    const final = result.outcome !== 'failed' || claim.attempts >= MAX_ATTEMPTS;
+    if (final) {
+      try { notify(PRIME_TITLES[result.outcome] || 'window prime failed', line, { priority: 2 }); } catch { /* never break the daemon */ }
+    }
+    results.push(result);
+  }
+  return results;
+}
+
+// `unsnooze prime` — schedule + last result; `unsnooze prime now [agent…]`.
+export async function cmdPrime(rest = [], { run = runPrime, print = console.log, learn = learnSlot } = {}) {
+  if (rest[0] === 'now') {
+    const ids = rest.slice(1).length ? rest.slice(1) : PRIME_AGENTS.filter(id => getConfig(`agents.${id}`));
+    const bad = ids.filter(id => !PRIME_AGENTS.includes(id));
+    if (bad.length) {
+      print(`unsnooze: priming supports ${PRIME_AGENTS.join(' and ')} only (not ${bad.join(', ')})`);
+      return 1;
+    }
+    let code = 0;
+    for (const id of ids) {
+      print(`unsnooze: priming ${id}…`);
+      const result = await run(id);
+      record(result, { manual: true });
+      print(`unsnooze: ${formatPrimeResult(result)}`);
+      if (result.outcome === 'failed') code = 1;
+    }
+    return code;
+  }
+  if (rest[0] && rest[0] !== 'status') {
+    print('usage: unsnooze prime [status] | unsnooze prime now [claude|codex]');
+    return 1;
+  }
+  const days = getConfig('primeDays');
+  const last = readState().prime || {};
+  print('window priming (experimental) — starts the 5-hour window early with one tiny prompt');
+  for (const id of PRIME_AGENTS) {
+    const at = normalizePrimeAt(getConfig(`primeAt.${id}`));
+    let sched = 'off';
+    if (at === 'auto') {
+      const l = await learn(id, { days });
+      sched = l.slot
+        ? `auto — you usually start ~${l.start} (${l.days} days), so it primes at ${l.slot} ${days}, model ${primeModel(id) || 'default'}`
+        : `auto — still learning when you start (${l.days} of ${MIN_DAYS} days); no primes until then`;
+    } else if (at) sched = `${at} ${days}, model ${primeModel(id) || 'default'}`;
+    const prev = last[id]?.at ? `  last: ${dayKey(last[id].at)} ${hm(last[id].at)} — ${formatPrimeResult(last[id])}` : '';
+    print(`  ${id.padEnd(7)} ${sched}${prev ? `\n  ${prev}` : ''}`);
+  }
+  if (PRIME_AGENTS.some(id => normalizePrimeAt(getConfig(`primeAt.${id}`)))) {
+    const { autostartUnitPath } = await import('./install.js');
+    if (process.platform !== 'win32' && !existsSync(autostartUnitPath())) {
+      print('\n  ! scheduled primes run from the daemon, which is not installed: unsnooze install --daemon');
+    }
+  } else {
+    print('\n  turn on: unsnooze config set primeAt.claude auto   (or a time like 06:00)');
+  }
+  return 0;
+}

package/src/resumer.js

@@ -1153,6 +1153,13 @@ export async function runResumer({
         log(`usage warn tick failed: ${err.message}`);
       }
 
+      // Window priming (experimental) — not awaited: a prime is a model call
+      // of up to minutes, and resumes must not queue behind it. tickPrime
+      // claims the day before running, so later ticks cannot double-fire.
+      import('./prime.js')
+        .then(({ tickPrime }) => tickPrime())
+        .catch(err => log(`prime tick failed: ${err.message}`));
+
       // Scheduled cleanup: age prune + pane-aware sweep + abandon stale stops.
       try {
         updateState(state => { prune(state); return state; });

package/src/settings.js

@@ -57,6 +57,12 @@ export const DEFAULTS = {
   // compacted) is useless if it only applies to revives, because the session
   // that runs out of context is the one the user started.
   launchExtraArgs: { claude: '', codex: '', grok: '', qwen: '', kimi: '', opencode: '', agy: '', cursor: '' },
+  // Window priming (experimental, see prime.js): one tiny prompt at primeAt
+  // (local HH:MM, or auto = learned from history) starts the 5-hour window
+  // early. '' = off.
+  primeAt: { claude: '', codex: '' },
+  primeModel: { claude: '', codex: '' },   // '' = claude haiku / codex's cheapest cached model
+  primeDays: 'daily',                      // daily | weekdays
   agents: { claude: true, codex: true, grok: false, qwen: false, kimi: false, opencode: false, agy: false, cursor: false },   // experimental agents default off
 };
 
@@ -107,6 +113,11 @@ const ENV_NAMES = {
   'launchExtraArgs.opencode': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_OPENCODE',
   'launchExtraArgs.agy': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_AGY',
   'launchExtraArgs.cursor': 'UNSNOOZE_LAUNCH_EXTRA_ARGS_CURSOR',
+  'primeAt.claude': 'UNSNOOZE_PRIME_AT_CLAUDE',
+  'primeAt.codex': 'UNSNOOZE_PRIME_AT_CODEX',
+  'primeModel.claude': 'UNSNOOZE_PRIME_MODEL_CLAUDE',
+  'primeModel.codex': 'UNSNOOZE_PRIME_MODEL_CODEX',
+  primeDays: 'UNSNOOZE_PRIME_DAYS',
   'agents.claude': 'UNSNOOZE_AGENT_CLAUDE',
   'agents.codex': 'UNSNOOZE_AGENT_CODEX',
   'agents.grok': 'UNSNOOZE_AGENT_GROK',
@@ -127,6 +138,7 @@ const ENUMS = {
   notifyChannel: ['auto', 'native', 'osc', 'bell'],
   ntfyPrivacy: ['full', 'terse'],
   usageWarn: ['off', 'notify'],
+  primeDays: ['daily', 'weekdays'],
 };
 
 function parseBool(raw) {
@@ -253,6 +265,14 @@ export function setConfigValue(key, rawValue) {
     value = n;
   } else {
     value = String(rawValue);
+    if (key.startsWith('primeAt.')) {
+      // Inline, not imported from prime.js: that module pulls in usage.js,
+      // and settings.js must stay a cheap leaf for the hook path.
+      const m = value.trim().match(/^([01]?\d|2[0-3]):([0-5]\d)$/);
+      const auto = /^auto$/i.test(value.trim());
+      if (!m && !auto && !/^(off)?$/i.test(value.trim())) throw new Error(`unsnooze: "${key}" needs auto, a local time like 06:00, or off`);
+      value = auto ? 'auto' : m ? `${m[1].padStart(2, '0')}:${m[2]}` : '';
+    }
     if (ENUMS[key] && !ENUMS[key].includes(value)) {
       throw new Error(`unsnooze: "${key}" must be one of: ${ENUMS[key].join(', ')}`);
     }

package/src/watcher.js

@@ -18,7 +18,7 @@ import { join, sep, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import {
   CLAUDE_DIR, CODEX_DIR, WATCH_OFFSETS_FILE, WATCH_FRESHNESS_MS,
-  RESET_MARGIN_MS, PROBE_INTERVAL_MS,
+  RESET_MARGIN_MS, PROBE_INTERVAL_MS, isPrimeDir,
 } from './config.js';
 import { getMultiplexer } from './multiplexer.js';
 import { parseTranscriptLine } from './watchers/claude.js';
@@ -170,6 +170,9 @@ export function defaultSources() {
 // MAX_RESUME_ATTEMPTS cap could never bind — and a cancelled record stays
 // cancelled.
 export function dispatchCandidate(c) {
+  // A window prime's own rollout (prime.js runs codex in PRIME_DIR) hitting a
+  // limit is not a session — reviving it would spend quota on nothing.
+  if (isPrimeDir(c.cwd)) return;
   const detectedAt = c.timestampMs || Date.now();
   const bannerAt = c.timestampMs || null;
   let at, source;