unsnooze 1.0.0

package/src/sessions.js

@@ -0,0 +1,39 @@
+// 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.
+
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLAUDE_DIR } from './config.js';
+
+// Claude Code maps a cwd to a project dir by replacing every '/' and '.' with '-'.
+export function dashCwd(cwd) {
+  return cwd.replace(/[/.]/g, '-');
+}
+
+export function projectDir(cwd) {
+  return join(CLAUDE_DIR, 'projects', dashCwd(cwd));
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;
+
+// Newest transcript (by mtime) for a cwd = the session most recently active
+// there. aroundTs (optional) requires the transcript to have been touched
+// within 30 min of the detection time, to avoid grabbing an unrelated session.
+export function latestSessionId(cwd, aroundTs = null) {
+  let entries;
+  try {
+    entries = readdirSync(projectDir(cwd));
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const name of entries) {
+    if (!UUID_RE.test(name)) continue;
+    let mtime;
+    try { mtime = statSync(join(projectDir(cwd), name)).mtimeMs; } catch { continue; }
+    if (aroundTs != null && Math.abs(mtime - aroundTs) > 30 * 60_000) continue;
+    if (!best || mtime > best.mtime) best = { id: name.slice(0, -6), mtime };
+  }
+  return best ? best.id : null;
+}

package/src/settings.js

@@ -0,0 +1,105 @@
+// User-facing settings: ~/.unsnooze/config.json, managed by `unsnooze config`
+// and the setup wizard. Precedence: env var > config file > default — env
+// stays the power-user/test escape hatch, the file is what the wizard writes.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { STATE_DIR } from './config.js';
+
+export const CONFIG_FILE = () => join(process.env.UNSNOOZE_STATE_DIR || STATE_DIR, 'config.json');
+
+export const DEFAULTS = {
+  autoResume: true,        // master switch: dispatch resumes when limits reset
+  menuAutoAnswer: true,    // may unsnooze drive Claude's limit menu (send keys)?
+  notifications: true,     // desktop notifications on detect/resume
+  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.',
+  agents: { claude: true, codex: true, grok: false },   // grok is experimental
+};
+
+// Env override per key. Booleans accept 1/0, true/false, on/off, yes/no.
+const ENV_NAMES = {
+  autoResume: 'UNSNOOZE_AUTO_RESUME',
+  menuAutoAnswer: 'UNSNOOZE_MENU_AUTO_ANSWER',
+  notifications: 'UNSNOOZE_NOTIFICATIONS',
+  resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
+  'agents.claude': 'UNSNOOZE_AGENT_CLAUDE',
+  'agents.codex': 'UNSNOOZE_AGENT_CODEX',
+  'agents.grok': 'UNSNOOZE_AGENT_GROK',
+};
+
+const KNOWN_KEYS = Object.keys(ENV_NAMES);
+
+function parseBool(raw) {
+  if (/^(1|true|on|yes)$/i.test(raw)) return true;
+  if (/^(0|false|off|no)$/i.test(raw)) return false;
+  return null;
+}
+
+function readFileConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE(), 'utf-8'));
+  } catch {
+    return {};   // missing or corrupt file → defaults (never crash the hook path)
+  }
+}
+
+function dig(obj, key) {
+  return key.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+export function getConfig(key) {
+  if (!KNOWN_KEYS.includes(key)) throw new Error(`unsnooze: unknown setting "${key}"`);
+  const def = dig(DEFAULTS, key);
+  const env = process.env[ENV_NAMES[key]];
+  if (env !== undefined && env !== '') {
+    if (typeof def === 'boolean') {
+      const b = parseBool(env);
+      if (b !== null) return b;
+    } else {
+      return env;
+    }
+  }
+  const fromFile = dig(readFileConfig(), key);
+  return fromFile !== undefined ? fromFile : def;
+}
+
+export function setConfigValue(key, rawValue) {
+  if (!KNOWN_KEYS.includes(key)) throw new Error(`unsnooze: unknown setting "${key}" (known: ${KNOWN_KEYS.join(', ')})`);
+  const def = dig(DEFAULTS, key);
+  let value = rawValue;
+  if (typeof def === 'boolean') {
+    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 {
+    value = String(rawValue);
+  }
+  const config = readFileConfig();
+  const parts = key.split('.');
+  let cursor = config;
+  for (const part of parts.slice(0, -1)) {
+    if (typeof cursor[part] !== 'object' || cursor[part] === null) cursor[part] = {};
+    cursor = cursor[part];
+  }
+  cursor[parts[parts.length - 1]] = value;
+  writeConfig(config);
+  return value;
+}
+
+export function writeConfig(config) {
+  const path = CONFIG_FILE();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.config.tmp.${process.pid}`);
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+  renameSync(tmp, path);
+}
+
+export function configFileExists() {
+  try { readFileSync(CONFIG_FILE()); return true; } catch { return false; }
+}
+
+export function listConfig() {
+  const out = {};
+  for (const key of KNOWN_KEYS) out[key] = getConfig(key);
+  return out;
+}

package/src/spawn.js

@@ -0,0 +1,41 @@
+// Detached-process helpers shared by launcher, hook, and monitor.
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { RESUMER_LOCK } from './config.js';
+import { makeLogger } from './logger.js';
+
+const log = makeLogger('spawn');
+
+export const UNSNOOZE_BIN = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin', 'unsnooze.js');
+
+export function spawnDetached(args, env = {}) {
+  const child = spawn(process.execPath, [UNSNOOZE_BIN, ...args], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, ...env },
+  });
+  child.unref();
+  return child.pid;
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+// Spawn the resumer daemon unless one is already running (pidfile check).
+// The resumer itself re-checks under its own lock; this is just to avoid
+// pointless spawns.
+export function spawnResumerIfNeeded() {
+  try {
+    if (existsSync(RESUMER_LOCK)) {
+      const pid = parseInt(readFileSync(RESUMER_LOCK, 'utf-8'), 10);
+      if (Number.isFinite(pid) && pidAlive(pid)) return null;
+    }
+  } catch { /* unreadable lock — let the daemon sort it out */ }
+  const pid = spawnDetached(['_resumer']);
+  log(`spawned resumer pid ${pid}`);
+  return pid;
+}

package/src/state.js

@@ -0,0 +1,147 @@
+// Shared multi-writer state store: ~/.unsnooze/state.json.
+// Writers: N monitors, the StopFailure hook, the resumer, CLI subcommands.
+// Safety: mkdir-based lock (atomic on POSIX) around read-modify-write, tmp
+// file + rename for atomic replacement, stale-lock stealing, corrupt-file
+// quarantine. All synchronous — callers are short-lived or infrequent.
+
+import {
+  mkdirSync, rmdirSync, readFileSync, writeFileSync, renameSync,
+  existsSync, statSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  STATE_DIR, STATE_FILE, LOCK_DIR, STALE_LOCK_MS, PRUNE_AFTER_MS,
+  DEDUPE_WINDOW_MS,
+} from './config.js';
+import { makeLogger } from './logger.js';
+
+const log = makeLogger('state');
+
+const EMPTY = () => ({ version: 1, resumerPid: null, sessions: {} });
+
+function sleepSync(ms) {
+  const buf = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buf), 0, 0, ms);
+}
+
+function acquireLock() {
+  const deadline = Date.now() + 5_000;
+  for (;;) {
+    try {
+      mkdirSync(LOCK_DIR);
+      return;
+    } catch (err) {
+      if (err.code !== 'EEXIST') { mkdirSync(STATE_DIR, { recursive: true }); continue; }
+      try {
+        const age = Date.now() - statSync(LOCK_DIR).mtimeMs;
+        if (age > STALE_LOCK_MS) {
+          rmdirSync(LOCK_DIR);   // steal stale lock from a killed process
+          log(`stole stale lock (age ${Math.round(age)}ms)`);
+          continue;
+        }
+      } catch { /* lock vanished between check and stat — retry */ }
+      if (Date.now() > deadline) throw new Error('unsnooze: state lock timeout after 5s');
+      sleepSync(50);
+    }
+  }
+}
+
+function releaseLock() {
+  try { rmdirSync(LOCK_DIR); } catch { /* already gone */ }
+}
+
+export function readState() {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return EMPTY();
+    // Corrupt file: quarantine loudly, start fresh — never crash the hook path.
+    try {
+      const quarantine = `${STATE_FILE}.corrupt.${Date.now()}`;
+      renameSync(STATE_FILE, quarantine);
+      log(`CORRUPT state.json quarantined to ${quarantine}: ${err.message}`);
+    } catch { /* someone else quarantined it first */ }
+    return EMPTY();
+  }
+}
+
+// Locked read-modify-write. mutator receives the state object and mutates it
+// (or returns a replacement). Returns the final state.
+export function updateState(mutator) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  acquireLock();
+  try {
+    const state = readState();
+    const result = mutator(state) ?? state;
+    const tmp = join(STATE_DIR, `.state.tmp.${process.pid}`);
+    writeFileSync(tmp, JSON.stringify(result, null, 2));
+    renameSync(tmp, STATE_FILE);
+    return result;
+  } finally {
+    releaseLock();
+  }
+}
+
+// Insert or update a session record. Dedupes hook-vs-scrape double detection:
+// if a record for the same pane was created within DEDUPE_WINDOW_MS, merge into
+// it (a record WITH a sessionId wins over one without).
+export function upsertSession(record) {
+  return updateState(state => {
+    prune(state);
+    const existingKey = findDuplicate(state, record);
+    if (existingKey) {
+      const existing = state.sessions[existingKey];
+      const merged = {
+        ...existing,
+        ...record,
+        // Never downgrade a known sessionId to null.
+        sessionId: record.sessionId || existing.sessionId,
+        key: existingKey,
+      };
+      state.sessions[existingKey] = merged;
+      log(`merged duplicate detection for pane ${record.pane} into ${existingKey}`);
+      return state;
+    }
+    const key = record.sessionId || `pane:${record.pane}:${record.detectedAt}`;
+    state.sessions[key] = { ...record, key };
+    return state;
+  });
+}
+
+function findDuplicate(state, record) {
+  if (record.sessionId && state.sessions[record.sessionId]) return record.sessionId;
+  for (const [key, s] of Object.entries(state.sessions)) {
+    if (s.pane && s.pane === record.pane
+      && s.status === 'stopped'
+      && Math.abs((s.detectedAt || 0) - record.detectedAt) < DEDUPE_WINDOW_MS) {
+      return key;
+    }
+  }
+  return null;
+}
+
+export function setStatus(key, status, extra = {}) {
+  return updateState(state => {
+    const s = state.sessions[key];
+    if (!s) return state;
+    Object.assign(s, extra, { status });
+    return state;
+  });
+}
+
+function prune(state) {
+  const cutoff = Date.now() - PRUNE_AFTER_MS;
+  for (const [key, s] of Object.entries(state.sessions)) {
+    const terminal = ['resumed', 'failed', 'cancelled'].includes(s.status);
+    const ts = s.lastAttemptAt || s.detectedAt || 0;
+    if (terminal && ts < cutoff) delete state.sessions[key];
+  }
+}
+
+export function activeStopped(state = readState()) {
+  return Object.values(state.sessions).filter(s => s.status === 'stopped');
+}
+
+export function dueSessions(now = Date.now(), state = readState()) {
+  return activeStopped(state).filter(s => (s.resetAt || 0) <= now);
+}

package/src/time-parser.js

@@ -0,0 +1,172 @@
+// Parse reset banner text (Claude Code or Codex CLI) into an absolute
+// epoch-ms reset time. DST-safe: resolves "resets 3pm (UTC)" via iterative
+// correction in the stated timezone rather than naive offset math.
+
+// Optional weekday between "resets" and the time covers weekly banners
+// ("resets Tuesday 9am (UTC)").
+const RESET_TIME_REGEX = /resets?\s+(?:at\s+)?(?:on\s+)?(?:(?:mon|tue|wed|thu|fri|sat|sun)[a-z]*\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i;
+const RELATIVE_TIME_REGEX = /(?:try again|wait|resets?\s+in)[:\s]\s*(?:for\s+)?(?:in\s+)?(\d+)\s*(hours?|minutes?|mins?|h|m)\b/i;
+// "resets Tuesday 3pm" / "resets on Mon" — weekly limits carry a day name.
+const DAY_REGEX = /resets?\s+(?:on\s+)?(mon|tue|wed|thu|fri|sat|sun)[a-z]*/i;
+const DAY_INDEX = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+
+// Codex CLI forms ("try again at …", local time):
+//   same day:  "or try again at 3:51 PM."
+//   cross-day: "or try again at Feb 23rd, 2026 9:01 PM."
+//   older:     "Try again in 4 days 20 hours 9 minutes."
+const TRY_AT_TIME_REGEX = /try again at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i;
+const TRY_AT_DATE_REGEX = /try again at\s+(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4})\s+(\d{1,2}):(\d{2})\s*(am|pm)/i;
+const MULTI_RELATIVE_REGEX = /try again in\s+(?:(\d+)\s*days?\s*)?(?:(\d+)\s*hours?\s*)?(?:(\d+)\s*min(?:ute)?s?)?/i;
+const MONTH_INDEX = { jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11 };
+
+function to24h(hour, ampm) {
+  let h = hour;
+  if (ampm === 'pm' && h !== 12) h += 12;
+  if (ampm === 'am' && h === 12) h = 0;
+  return h;
+}
+
+export function parseResetTime(text) {
+  if (!text) return null;
+
+  // Full-date form first — its trailing "9:01 PM" would otherwise be eaten by
+  // the same-day "try again at" regex.
+  const dateMatch = text.match(TRY_AT_DATE_REGEX);
+  if (dateMatch) {
+    const [, mon, day, year, hour, minute, ampm] = dateMatch;
+    const atMs = new Date(
+      parseInt(year, 10), MONTH_INDEX[mon.toLowerCase()], parseInt(day, 10),
+      to24h(parseInt(hour, 10), ampm.toLowerCase()), parseInt(minute, 10),
+    ).getTime();
+    return { absolute: true, atMs };
+  }
+
+  const tryAtMatch = text.match(TRY_AT_TIME_REGEX);
+  if (tryAtMatch) {
+    return {
+      hour: to24h(parseInt(tryAtMatch[1], 10), tryAtMatch[3].toLowerCase()),
+      minute: tryAtMatch[2] ? parseInt(tryAtMatch[2], 10) : 0,
+      timezone: null, ambiguous: false, day: null,
+    };
+  }
+
+  const dayMatch = text.match(DAY_REGEX);
+  const absMatch = text.match(RESET_TIME_REGEX);
+  if (absMatch) {
+    let hour = parseInt(absMatch[1], 10);
+    const minute = absMatch[2] ? parseInt(absMatch[2], 10) : 0;
+    const ampm = absMatch[3]?.toLowerCase() || null;
+    const timezone = absMatch[4] || null;
+
+    if (ampm === 'pm' && hour !== 12) hour += 12;
+    if (ampm === 'am' && hour === 12) hour = 0;
+
+    const ambiguous = !ampm && hour >= 1 && hour <= 12;
+    return {
+      hour, minute, timezone, ambiguous,
+      day: dayMatch ? DAY_INDEX[dayMatch[1].toLowerCase()] : null,
+    };
+  }
+
+  const relMatch = text.match(RELATIVE_TIME_REGEX);
+  if (relMatch) {
+    const amount = parseInt(relMatch[1], 10);
+    const unit = relMatch[2].toLowerCase();
+    const isMinutes = unit.startsWith('m');
+    return { relative: true, waitMs: amount * (isMinutes ? 60_000 : 3_600_000) };
+  }
+
+  // Multi-unit relative ("in 4 days 20 hours 9 minutes") — checked after the
+  // single-unit form, which already covers "in 2 hours" / "in 5 minutes".
+  const multiMatch = text.match(MULTI_RELATIVE_REGEX);
+  if (multiMatch && (multiMatch[1] || multiMatch[2] || multiMatch[3])) {
+    const days = parseInt(multiMatch[1] || '0', 10);
+    const hours = parseInt(multiMatch[2] || '0', 10);
+    const minutes = parseInt(multiMatch[3] || '0', 10);
+    return { relative: true, waitMs: ((days * 24 + hours) * 60 + minutes) * 60_000 };
+  }
+
+  // Day-only weekly banner ("resets Tuesday") with no time — midnight-ish target,
+  // resolved by resetAtMs via hour 0.
+  if (dayMatch) {
+    return { hour: 0, minute: 0, timezone: null, ambiguous: false, day: DAY_INDEX[dayMatch[1].toLowerCase()] };
+  }
+
+  return null;
+}
+
+// Convert parsed reset info into an absolute epoch ms (includes margin).
+// Unparseable input falls back to now + fallbackMs.
+export function resetAtMs(parsed, { marginMs = 60_000, fallbackMs = 5 * 3_600_000, now = new Date() } = {}) {
+  const source = !parsed ? 'fallback' : parsed.relative ? 'relative' : 'absolute';
+  if (!parsed) return { at: now.getTime() + fallbackMs + marginMs, source };
+  if (parsed.relative) return { at: now.getTime() + parsed.waitMs + marginMs, source };
+  // Pre-resolved epoch (full-date banner, local time). A stale past date means
+  // we misread the banner — fall back rather than firing immediately.
+  if (parsed.absolute) {
+    if (parsed.atMs <= now.getTime()) return { at: now.getTime() + fallbackMs + marginMs, source: 'fallback' };
+    return { at: parsed.atMs + marginMs, source };
+  }
+
+  let tz;
+  try {
+    tz = parsed.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+    Intl.DateTimeFormat('en-US', { timeZone: tz });
+  } catch {
+    return { at: now.getTime() + fallbackMs + marginMs, source: 'fallback' };
+  }
+
+  // DST-safe: build today's date in the target tz, then iteratively correct the
+  // UTC guess until it formats as the desired local h:m. Correction normalized
+  // to [-720, +720] minutes to take the minimum-magnitude step (avoids the
+  // off-by-a-day bug in high-offset timezones).
+  function targetTimestamp(h, m) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit', hour12: false,
+    }).formatToParts(now);
+    const y = parseInt(parts.find(p => p.type === 'year').value);
+    const mo = parseInt(parts.find(p => p.type === 'month').value);
+    const d = parseInt(parts.find(p => p.type === 'day').value);
+
+    const targetStr = `${y}-${String(mo).padStart(2, '0')}-${String(d).padStart(2, '0')}T${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:00`;
+    let candidate = new Date(targetStr + 'Z').getTime();
+    for (let i = 0; i < 3; i++) {
+      const fp = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz, hour: 'numeric', minute: 'numeric', hour12: false,
+      }).formatToParts(new Date(candidate));
+      const ch = parseInt(fp.find(p => p.type === 'hour').value) % 24;
+      const cm = parseInt(fp.find(p => p.type === 'minute').value);
+      let diffMin = (h - ch) * 60 + (m - cm);
+      diffMin = ((diffMin % 1440) + 1440) % 1440;
+      if (diffMin > 720) diffMin -= 1440;
+      if (diffMin === 0) break;
+      candidate += diffMin * 60_000;
+    }
+    return candidate;
+  }
+
+  function nextOccurrence(h, m) {
+    let t = targetTimestamp(h, m);
+    if (t <= now.getTime()) t += 86_400_000;
+    if (parsed.day != null) {
+      // Roll forward to the named weekday (in the target tz).
+      for (let i = 0; i < 7; i++) {
+        const wd = new Intl.DateTimeFormat('en-US', { timeZone: tz, weekday: 'short' })
+          .format(new Date(t)).toLowerCase().slice(0, 3);
+        if (DAY_INDEX[wd] === parsed.day) break;
+        t += 86_400_000;
+      }
+    }
+    return t;
+  }
+
+  let at;
+  if (parsed.ambiguous) {
+    const t1 = nextOccurrence(parsed.hour, parsed.minute);
+    const t2 = nextOccurrence((parsed.hour + 12) % 24, parsed.minute);
+    at = Math.min(t1, t2);
+  } else {
+    at = nextOccurrence(parsed.hour, parsed.minute);
+  }
+  return { at: at + marginMs, source };
+}

package/src/tmux.js

@@ -0,0 +1,95 @@
+import { execFile as execFileCb, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFileCb);
+
+// Is tmux runnable at all? Used for a friendly error instead of a cryptic
+// spawn failure (native Windows users get pointed at WSL).
+export function tmuxAvailable() {
+  try {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Submit delay: text and the submitting Enter must be TWO separate send-keys
+// calls with a pause between them, or Ink (Claude Code's TUI) treats the Enter
+// as a newline inside a bracketed-paste burst instead of a submit.
+export const SUBMIT_DELAY_MS = 150;
+
+async function tmux(...args) {
+  const { stdout } = await execFileAsync('tmux', args);
+  return stdout;
+}
+
+export function insideTmux() { return !!process.env.TMUX; }
+export function currentPaneId() { return process.env.TMUX_PANE || null; }
+
+export async function capturePane(pane, lines = 200) {
+  return tmux('capture-pane', '-t', pane, '-p', '-S', `-${lines}`);
+}
+
+// Visible screen ONLY (no scrollback). Interactive menus must be checked
+// against this: a menu that scrolled into history was already answered —
+// re-driving it sends stray keystrokes into whatever is foreground now.
+export async function capturePaneVisible(pane) {
+  return tmux('capture-pane', '-t', pane, '-p');
+}
+
+// Type a message into a TUI and submit it (split form; -l sends literally so
+// tmux key names inside the message are typed, not interpreted).
+export async function sendText(pane, text) {
+  await tmux('send-keys', '-t', pane, '-l', text);
+  await new Promise(r => setTimeout(r, SUBMIT_DELAY_MS));
+  await tmux('send-keys', '-t', pane, 'Enter');
+}
+
+// Single named key ('Down', 'Up', 'Enter', 'Escape') — drives menus.
+export async function sendKey(pane, key) {
+  await tmux('send-keys', '-t', pane, key);
+}
+
+export async function paneAlive(pane) {
+  try {
+    await tmux('display-message', '-t', pane, '-p', '#{pane_id}');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function paneCurrentCommand(pane) {
+  try {
+    return (await tmux('display-message', '-t', pane, '-p', '#{pane_current_command}')).trim();
+  } catch {
+    return null;
+  }
+}
+
+// NOTE: plain session names, not the '=name' exact-match prefix — tmux 3.7b
+// rejects '=name' as a target here ("name not found" despite the session
+// existing). Exact matches take priority over prefix matches anyway.
+export async function sessionExists(name) {
+  try {
+    await tmux('has-session', '-t', name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Open a new window in the named session (creating the session if needed),
+// cd'd to cwd, running command. Returns the new pane id.
+export async function newWindow(sessionName, cwd, command) {
+  if (!(await sessionExists(sessionName))) {
+    await tmux('new-session', '-d', '-s', sessionName, '-c', cwd);
+    // The fresh session's first window IS our window — run the command there.
+    const pane = (await tmux('display-message', '-t', sessionName, '-p', '#{pane_id}')).trim();
+    await tmux('send-keys', '-t', pane, '-l', command);
+    await tmux('send-keys', '-t', pane, 'Enter');
+    return pane;
+  }
+  const out = await tmux('new-window', '-t', `${sessionName}:`, '-c', cwd, '-P', '-F', '#{pane_id}', command);
+  return out.trim();
+}