unsnooze 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## 1.0.0 — 2026-07-10
+
+First public release (previously the private `claude-session-guard`/`csg`).
+
+### Multi-CLI auto-resume
+
+- **Claude Code and OpenAI Codex CLI fully supported; xAI Grok Build
+  experimental** (generic patterns + `unsnooze report` to contribute real
+  banner captures).
+- **Agent adapters** (`src/agents/`): per-CLI banner regexes, busy/idle
+  markers, resume invocation, session-store lookup, hook wiring.
+- **Codex specifics**: verbatim banner strings from the Codex source; parses
+  `try again at 3:51 PM`, `Feb 23rd, 2026 9:01 PM`, and
+  `in 4 days 20 hours 9 minutes`; dead sessions revive via
+  `codex resume <id> "<message>"` — the prompt travels in argv, nothing is
+  typed into the pane.
+
+### Settings & UX
+
+- **Settings**: `~/.unsnooze/config.json`, `unsnooze config list/get/set`,
+  toggles for autoResume, menuAutoAnswer, notifications, resumeMessage, and
+  per-agent enablement (env > file > default).
+- **Setup wizard**: `unsnooze setup` — detects installed CLIs, warns when
+  `grok` is the community CLI rather than Grok Build, installs wrappers
+  (zsh + bash) and hooks.
+- **Desktop notifications** on limit detected / session resumed / gave up
+  (macOS osascript, Linux notify-send, tmux fallback).
+
+### Windows / WSL
+
+- **Windows via WSL**: native Windows toast notifications from inside WSL via
+  `powershell.exe` (no notify-send/X server needed), `where`-based CLI
+  detection, and a friendly "install tmux / use WSL" message instead of a
+  hard failure when tmux is missing (the agent CLI still runs, just
+  unwatched). The tmux-independent core is exercised on Windows in CI.
+
+### Safety hardening
+
+- **Wrappers and hooks can never brick the wrapped CLI**: the shell wrapper
+  falls through to the real `claude`/`codex`/`grok` when the unsnooze entry
+  point is missing, and hook commands no-op (`exit 0`) instead of erroring on
+  every turn.
+- **Menus are answered from the visible screen only**, never from tmux
+  scrollback — an already-answered menu in history can no longer trigger
+  stray keystrokes (relevant for non-alt-screen TUIs like
+  `codex --no-alt-screen`).
+- **Session reopen uses absolute node + entry-point paths** instead of a PATH
+  lookup — a tmux server started without npm globals (or nvm's node) on PATH
+  can no longer break revival with command-not-found.
+- Migrates cleanly off `claude-auto-retry` and the pre-release csg install
+  (fenced rc blocks and settings.json hook entries are replaced, with
+  backups).
+
+### Testing
+
+- 104 unit tests plus a **12-scenario end-to-end suite**
+  (`scripts/e2e-simulate.sh`) that exercises every agent and safety path in
+  real tmux with real monitor/hook/resumer processes — banner detection for
+  all three CLIs, raw-key menu driving with selection verification, hook
+  ingestion, dead-pane and live-pane resume, both toggles, and the
+  529-overload retry ladder (now env-tunable via
+  `UNSNOOZE_OVERLOAD_BACKOFF_S`).
+- CI: Ubuntu + macOS (Node 20/22) and Windows (Node 22).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saaransh Menon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="unsnooze — wakes every limit-stopped AI session the moment the limit resets" width="880"/>
+
+<br/>
+
+[![CI](https://github.com/saaranshM/unsnooze/actions/workflows/ci.yml/badge.svg)](https://github.com/saaranshM/unsnooze/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/unsnooze?color=f59e0b)](https://www.npmjs.com/package/unsnooze)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3fb950)](package.json)
+[![license](https://img.shields.io/badge/license-MIT-8b949e)](LICENSE)
+
+**Claude Code · Codex CLI · Grok** — when they hit a usage limit, your session just… stops.<br/>
+unsnooze tracks **every** limit-stopped session across all your projects and
+**wakes each one up in tmux the moment the limit resets.**
+
+```sh
+npm install -g unsnooze && unsnooze setup
+```
+
+<img src="assets/demo.svg" alt="terminal demo: limit banners detected in two sessions, unsnooze waits for the reset, then wakes both — good morning, the work is done" width="880"/>
+
+</div>
+
+## Why unsnooze
+
+Overnight and long-running agent work dies at the 5-hour / weekly limit, and every
+existing tool solves only a slice of it:
+
+| | **unsnooze** | claude-auto-retry | autoclaude | hydra |
+|---|:---:|:---:|:---:|:---:|
+| Multi-CLI (Claude Code + Codex + Grok) | ✅ | ❌ Claude only | ❌ Claude only | ✅ |
+| Waits for reset & resumes the **same** session | ✅ | ✅ | ✅ | ❌ switches provider |
+| All sessions at once (shared ledger + one daemon) | ✅ | ❌ one pane | ✅ | ✅ |
+| Revives sessions whose pane/process is **gone** | ✅ `--resume <id>` | ❌ | ❌ | ❌ |
+| Survives laptop sleep & weekly-scale waits | ✅ epoch polling | partial | partial | n/a |
+| Settings + first-run wizard | ✅ | ❌ | ❌ | ❌ |
+
+## Supported CLIs
+
+- **Claude Code** — dual-channel detection: the `StopFailure` hook (authoritative,
+  carries `session_id`) plus tmux pane scraping for banners and the interactive
+  limit menu (always answered with *"Stop and wait for limit to reset"*, never a
+  blind Enter). Dead sessions revive via `claude --resume <id>`.
+- **OpenAI Codex CLI** — scrape-based (Codex fires no event on limits). Detects
+  the exact `■ You've hit your usage limit …` banner strings from the Codex
+  source, parses `try again at 3:51 PM` / `Feb 23rd, 2026 9:01 PM` /
+  `in 4 days 20 hours 9 minutes`. Dead sessions revive via
+  `codex resume <id> "<message>"` — the prompt travels in argv.
+- **Grok Build (xAI)** — ⚠️ *experimental*. Hook channel works (Grok reads
+  Claude-compatible hooks, including `StopFailure`); the limit banner text is
+  not publicly documented, so detection uses generic patterns with a safe
+  fallback. Hit a banner unsnooze missed? Run `unsnooze report` and paste the
+  capture into an issue — that's how this adapter gets good.
+
+## How it works
+
+<div align="center">
+<img src="assets/how-it-works.png" alt="architecture: claude/codex/grok panes are watched by unsnooze via hooks and banner scraping; stops land in state.json; the resumer daemon sleeps until the limit resets, then types into live panes or reopens dead ones until every session is running again" width="880"/>
+</div>
+
+<details>
+<summary>text version</summary>
+
+```
+claude / codex / grok (shell wrapper) ──► unsnooze _run <agent> ──► CLI in tmux pane
+                                              │
+                                              ├─ per-pane monitor (scrapes for limit
+                                              │  banners, drives Claude's limit menu,
+                                              │  seconds-scale retry on 5xx/overload)
+                                              │
+StopFailure hook (claude, grok) ──────────────┤
+                                              ▼
+                                ~/.unsnooze/state.json
+                                { agent, sessionId, cwd, pane, resetAt, status }
+                                              │
+                                              ▼
+                                resumer daemon (singleton, epoch-polling —
+                                survives laptop sleep and weekly-scale waits)
+                                              │
+                          ┌───────────────────┴────────────────────┐
+                 pane still alive?                          pane gone?
+                 send resume message into it                tmux new-window,
+                 (only if the CLI is foreground             `unsnooze _run <agent>
+                 and not mid-stream)                        --resume <id>`, verify
+```
+
+</details>
+
+Limit events are never persisted by the CLIs themselves; the reset time is
+parsed from the banner text, DST-safe, with a 5-hour fallback when unparseable
+— and every resume is verified afterwards (banner came back → reschedule from
+the fresh banner, capped at 5 attempts).
+
+## Usage
+
+```sh
+claude / codex / grok           # normal usage — wrapped automatically
+unsnooze status                 # tracked sessions + reset countdowns
+unsnooze resume-now [id|--all]  # don't wait for the reset time
+unsnooze cancel [id|--all]      # stop tracking a session
+unsnooze config list            # settings (see below)
+unsnooze config set <k> <v>     # e.g. autoResume off
+unsnooze logs [-f]              # what unsnooze has been doing
+unsnooze report [agent]         # capture a pane to report an undetected banner
+unsnooze uninstall [--purge]    # remove wrappers + hooks (+ state with --purge)
+```
+
+## Settings
+
+`unsnooze setup` writes `~/.unsnooze/config.json`; change anything later with
+`unsnooze config set`:
+
+| key | default | meaning |
+|---|---|---|
+| `autoResume` | `true` | Master switch. Off = stops are still tracked, but nothing is resumed until you run `unsnooze resume-now` or turn it back on. |
+| `menuAutoAnswer` | `true` | May unsnooze answer Claude's limit menu (send keys in your pane)? Off = watch-only. |
+| `notifications` | `true` | Desktop notification on limit detected / session resumed / gave up. |
+| `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. |
+| `agents.claude` / `agents.codex` / `agents.grok` | `true` / `true` / `false` | Which CLIs are guarded. |
+
+Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
+all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
+
+## Safety properties
+
+- **Never injects blind**: keys are only sent when the pane's foreground
+  process is the agent CLI and no "esc to interrupt"-style busy footer is
+  visible. Recycled pane ids can't receive stray messages.
+- **Never picks a menu option blind**: if Claude's limit menu layout can't be
+  read, unsnooze does not press Enter (that could confirm "Upgrade your plan").
+- **Sleep-safe waits**: the resumer polls wall-clock against the target epoch
+  every 30s instead of one long timer — a laptop asleep past the reset fires
+  on the next tick. Weekly limits are just a bigger epoch.
+- **Verified resumes**: after dispatch it re-captures the pane; if the limit
+  banner reappears (reset time misparsed / not actually reset), it reschedules
+  from the fresh banner, capped at 5 attempts.
+- **Concurrent-writer safe**: state updates go through a mkdir lock + atomic
+  rename; corrupt state is quarantined, never fatal (the hook path must never
+  block the CLI).
+- **Overload ≠ limit**: 5xx/529/429 transient errors take a seconds-scale
+  backoff path ([30,60,120,240,300]s ± jitter) and never enter the ledger.
+
+## Requirements
+
+- Node ≥ 20 and tmux
+- macOS, Linux, or **Windows via WSL** (see below)
+- zsh or bash (the wrappers are installed into `~/.zshrc` / `~/.bashrc`)
+
+### Windows / WSL
+
+unsnooze is built on tmux, so on Windows it runs inside
+[WSL](https://learn.microsoft.com/windows/wsl/install) — which is where the
+agent CLIs live on Windows anyway:
+
+```sh
+# inside your WSL distro (Ubuntu etc.)
+sudo apt install tmux
+npm install -g unsnooze && unsnooze setup
+```
+
+Everything works as on Linux, including desktop notifications: inside WSL,
+unsnooze raises **native Windows toasts** through `powershell.exe` (no
+`notify-send` or X server needed). Native Windows (PowerShell/cmd, no WSL) is
+not supported — without tmux there is nothing to watch; unsnooze will tell you
+so and run your CLI unwatched instead of breaking it.
+
+## Development
+
+```sh
+npm test                     # unit tests (node:test)
+./scripts/e2e-simulate.sh    # full detect → wait → re-open cycle in a
+                             # scratch tmux session (no real limits needed)
+```
+
+## License
+
+[MIT](LICENSE)

package/bin/unsnooze.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// unsnooze — subcommand router; anything unrecognized is treated as claude
+// args and passed through the launcher (back-compat with the zsh wrapper).
+
+const [, , cmd, ...rest] = process.argv;
+
+async function main() {
+  switch (cmd) {
+    case 'status': {
+      const { cmdStatus } = await import('../src/cli.js');
+      return cmdStatus();
+    }
+    case 'resume-now': {
+      const { cmdResumeNow } = await import('../src/cli.js');
+      return cmdResumeNow(rest[0]);
+    }
+    case 'cancel': {
+      const { cmdCancel } = await import('../src/cli.js');
+      return cmdCancel(rest[0]);
+    }
+    case 'logs': {
+      const { cmdLogs } = await import('../src/cli.js');
+      return cmdLogs(rest.includes('-f'));
+    }
+    case 'setup': {
+      const { runWizard } = await import('../src/wizard.js');
+      return runWizard();
+    }
+    case 'report': {
+      const { cmdReport } = await import('../src/report.js');
+      return cmdReport(rest);
+    }
+    case 'config': {
+      const { cmdConfig } = await import('../src/cli.js');
+      return cmdConfig(rest);
+    }
+    case 'install': {
+      const { cmdInstall } = await import('../src/install.js');
+      return cmdInstall(rest);
+    }
+    case 'uninstall': {
+      const { cmdUninstall } = await import('../src/install.js');
+      return cmdUninstall(rest);
+    }
+    case '_hook-stopfailure': {
+      const { runHook } = await import('../src/hook.js');
+      return runHook(rest);
+    }
+    case '_monitor': {
+      if (!rest[0]) { console.error('unsnooze _monitor: pane id required'); return 2; }
+      const { runMonitor } = await import('../src/monitor.js');
+      return runMonitor(rest[0], rest[1]);
+    }
+    case '_run': {
+      if (!rest[0]) { console.error('unsnooze _run: agent id required'); return 2; }
+      const { runLauncher } = await import('../src/launcher.js');
+      return runLauncher(rest.slice(1), rest[0]);
+    }
+    case '_resumer': {
+      const { runResumer } = await import('../src/resumer.js');
+      return runResumer();
+    }
+    case 'help':
+    case '--help-unsnooze': {
+      console.log(`unsnooze — wakes every limit-stopped AI coding session when the limit resets
+
+Usage:
+  unsnooze [claude args...]        run claude under limit-watch (default)
+  unsnooze _run <agent> [args...]  run a specific agent CLI under limit-watch
+  unsnooze status                  list tracked sessions + reset countdowns
+  unsnooze resume-now [id|--all]   resume stopped session(s) immediately
+  unsnooze cancel [id|--all]       stop tracking session(s)
+  unsnooze logs [-f]               show (or follow) the unsnooze log
+  unsnooze config [list|get|set]   view or change settings (toggles, message)
+  unsnooze setup                   interactive setup wizard (agents + toggles)
+  unsnooze install [--yes]         wire up shell wrappers + hooks (non-interactive)
+  unsnooze uninstall [--purge]     remove wrappers + hooks (and state with --purge)
+  unsnooze report [agent] [pane]   capture a pane to report an undetected banner`);
+      return 0;
+    }
+    default: {
+      // Everything else (including no args, --resume, -c, plain prompts) is a
+      // claude invocation — back-compat for the plain wrapper.
+      const { runLauncher } = await import('../src/launcher.js');
+      const args = cmd === undefined ? [] : [cmd, ...rest];
+      return runLauncher(args, 'claude');
+    }
+  }
+}
+
+main().then(code => { process.exitCode = typeof code === 'number' ? code : 0; })
+  .catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "unsnooze",
+  "version": "1.0.0",
+  "description": "Wakes every limit-stopped AI coding session (Claude Code, Codex CLI, Grok) in tmux the moment the usage limit resets.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "codex-cli",
+    "grok",
+    "usage-limit",
+    "rate-limit",
+    "auto-resume",
+    "tmux",
+    "ai-agents",
+    "cli"
+  ],
+  "author": "Saaransh Menon <saaransh.dev2811@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saaranshM/unsnooze.git"
+  },
+  "bugs": {
+    "url": "https://github.com/saaranshM/unsnooze/issues"
+  },
+  "homepage": "https://github.com/saaranshM/unsnooze#readme",
+  "type": "module",
+  "bin": {
+    "unsnooze": "bin/unsnooze.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  }
+}

package/src/agents/claude.js

@@ -0,0 +1,99 @@
+// Claude Code adapter: everything unsnooze needs to know about one CLI lives
+// in its adapter — banner regexes, busy/idle markers, resume invocation,
+// session-id lookup, and (claude-only) the interactive limit-menu driver.
+
+import { contentLines } from '../patterns.js';
+import { latestSessionId } from '../sessions.js';
+
+export const patterns = {
+  // Claude Code renders limits across multiple TUI lines, e.g.:
+  //   "⚠ You've hit your 5-hour limit"
+  //   "· resets 3pm (UTC)"
+  limitPatterns: [
+    /(?:hit|exceeded|reached).*(?:your|the)\s*(?:[\w-]+\s+){0,3}limit/i,
+    /\d+-hour limit/i,
+    /limit reached/i,
+    /usage limit/i,
+    /out of.*usage/i,
+    /rate limit/i,
+    /try again in/i,
+  ],
+  resetPatterns: [
+    /resets?\s+(?:at\s+)?\d{1,2}(?::\d{2})?\s*(?:am|pm)?/i,
+    /resets?\s+in[:\s]\s*\d/i,
+    /try again in \d+\s*(?:hours?|minutes?|h|m)/i,
+    /resets?\s+(?:on\s+)?(?:mon|tue|wed|thu|fri|sat|sun)/i,   // weekly: "resets Tuesday 9am"
+  ],
+  weeklyPatterns: [
+    /week(?:ly)?\s+limit/i,
+    /resets?\s+(?:on\s+)?(?:mon|tue|wed|thu|fri|sat|sun)/i,
+    /limit.*(?:this|per)\s+week/i,
+  ],
+  fiveHourPatterns: [/\d+-hour limit/i, /session limit/i],
+  // While Claude is streaming ("esc to interrupt") or running its own internal
+  // retries ("Retrying in 5s · attempt 3/10"), never inject keys.
+  busyPatterns: [
+    /esc to interrupt/i,
+    /\besc\b.*\binterrupt\b/i,
+    /Retrying in\b/i,
+    /\battempt\s+\d+\/\d+/i,
+  ],
+  idleRegex: /[❯>]/,
+  // Anchored to Claude Code's error render ("API Error: 529") — never bare digits.
+  overloadPatterns: [
+    /API Error:?\s*\(?5\d\d/i,
+    /overloaded_error/i,
+    /API Error:?\s*\(?429/i,
+  ],
+  transientPatterns: [],   // claude's transient errors are the overload set
+};
+
+// --- Interactive /rate-limit-options menu (Claude Code only) ---
+// Newer Claude Code shows a selectable menu on limit hit:
+//   What do you want to do?
+//   ❯ 1. Upgrade your plan
+//     2. Stop and wait for limit to reset
+// Option order varies between versions — never assume a position; locate the
+// cursor and target option and compute the moves. Never blind-Enter (could
+// confirm "Upgrade your plan").
+
+const MENU_CURSOR = '❯';
+const WAIT_OPTION_REGEX = /stop and wait for limit to reset/i;
+const MENU_OPTION_REGEX = /^\s*❯?\s*\d+\.\s/;
+
+export function isRateLimitOptionsPrompt(text, tailLines = 12) {
+  const t = contentLines(text, tailLines).join('\n');
+  return /what do you want to do\?/i.test(t)
+    && WAIT_OPTION_REGEX.test(t)
+    && (/enter to confirm/i.test(t) || /esc to cancel/i.test(t) || t.includes(MENU_CURSOR));
+}
+
+// Steps (in options) from cursor to the "Stop and wait" option. Positive =>
+// Down N times, negative => Up. null => layout unreadable, caller MUST NOT Enter.
+export function menuStepsToWaitOption(text, tailLines = 12) {
+  const optionLines = contentLines(text, tailLines).filter(l => MENU_OPTION_REGEX.test(l));
+  if (optionLines.length === 0) return null;
+  const cursorPos = optionLines.findIndex(l => l.includes(MENU_CURSOR));
+  const waitPos = optionLines.findIndex(l => WAIT_OPTION_REGEX.test(l));
+  if (cursorPos === -1 || waitPos === -1) return null;
+  return waitPos - cursorPos;
+}
+
+export default {
+  id: 'claude',
+  name: 'Claude Code',
+  bin: process.env.UNSNOOZE_CLAUDE_BIN || 'claude',
+  experimental: false,
+  patterns,
+  menu: { isPrompt: isRateLimitOptionsPrompt, stepsToWait: menuStepsToWaitOption },
+  // How to reopen a dead session. messageViaPane: the resume prompt is typed
+  // into the TUI once it's ready (claude has no resume-with-prompt argv form).
+  resumeArgs(sessionId) {
+    return { args: sessionId ? ['--resume', sessionId] : ['-c'], messageViaPane: true };
+  },
+  latestSessionId,
+  // The foreground process for a claude session is `node` (nvm shim) or `claude`.
+  isForegroundCommand(cmd) {
+    return cmd === 'claude' || cmd === 'node' || cmd === 'unsnooze';
+  },
+};

package/src/agents/codex.js

@@ -0,0 +1,112 @@
+// OpenAI Codex CLI adapter.
+//
+// Codex has no hook that fires on usage limits (its `notify` config only emits
+// agent-turn-complete), so detection is scrape-only. The TUI does NOT exit on
+// a hard limit — it renders one red transcript line and sits at the composer:
+//   ■ You've hit your usage limit. …{ or try again at 3:51 PM.}
+// Reset-time tails vary by plan: "try again at 3:51 PM." (same day),
+// "try again at Feb 23rd, 2026 9:01 PM." (cross-day), "Try again in 4 days
+// 20 hours 9 minutes." (older builds), or "Try again later." (no timestamp).
+// Transient errors render "stream error: … retrying 4/5 in 1.4s" and must take
+// the overload path, never the ledger.
+
+import { openSync, readSync, closeSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CODEX_DIR = process.env.UNSNOOZE_CODEX_DIR || join(homedir(), '.codex');
+
+const LIMIT_ANCHORS = [
+  /You've hit your usage limit/i,
+  /Your workspace is out of credits/i,
+  /hit your spend cap/i,
+];
+
+export const patterns = {
+  limitPatterns: LIMIT_ANCHORS,
+  // The whole banner is ONE line, so the anchors double as reset lines — the
+  // proximity engine then hands that line to time-parser (which falls back to
+  // the 5h default for "Try again later.").
+  resetPatterns: [
+    /try again at/i,
+    /try again in \d+/i,
+    /try again later/i,
+    ...LIMIT_ANCHORS,
+  ],
+  weeklyPatterns: [/weekly limit/i],
+  fiveHourPatterns: [/5h limit/i],
+  busyPatterns: [
+    /esc to interrupt/i,           // "• Working (12s • esc to interrupt)"
+    /retrying\s+\d+\/\d+/i,        // internal stream-error retry — don't inject
+  ],
+  idleRegex: /›/,                  // composer: "› Ask Codex to do anything"
+  overloadPatterns: [/stream error/i, /exceeded retry limit/i],
+  transientPatterns: [/stream error/i, /exceeded retry limit/i],
+};
+
+// Sessions live in ~/.codex/sessions/YYYY/MM/DD/rollout-{ts}-{UUID}.jsonl;
+// the first JSONL line carries the session cwd. Conservative: no cwd match →
+// null (the resumer then uses `codex resume --last`, which codex itself scopes
+// to the launch cwd).
+const ROLLOUT_RE = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+function fileHead(path, bytes = 4096) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.toString('utf-8', 0, n);
+  } catch {
+    return '';
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function latestSessionId(cwd, aroundTs = null, sessionsRoot = join(CODEX_DIR, 'sessions')) {
+  const files = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory() && depth < 3) { walk(p, depth + 1); continue; }
+      const m = e.isFile() && e.name.match(ROLLOUT_RE);
+      if (!m) continue;
+      let mtime;
+      try { mtime = statSync(p).mtimeMs; } catch { continue; }
+      if (aroundTs != null && Math.abs(mtime - aroundTs) > 30 * 60_000) continue;
+      files.push({ path: p, id: m[1], mtime });
+    }
+  };
+  walk(sessionsRoot, 0);
+  files.sort((a, b) => b.mtime - a.mtime);
+  // JSON-escape the cwd the way it appears inside the meta line.
+  const needle = cwd ? JSON.stringify(cwd).slice(1, -1) : null;
+  for (const f of files.slice(0, 20)) {
+    if (!needle || fileHead(f.path).includes(needle)) return f.id;
+  }
+  return null;
+}
+
+export default {
+  id: 'codex',
+  name: 'OpenAI Codex CLI',
+  bin: process.env.UNSNOOZE_CODEX_BIN || 'codex',
+  experimental: false,
+  patterns,
+  menu: null,                      // no interactive limit menu
+  // Resume takes the prompt in argv — `codex resume <id> "msg"` starts the turn
+  // immediately, nothing to type into the TUI.
+  resumeArgs(sessionId, message) {
+    return {
+      args: sessionId ? ['resume', sessionId, message] : ['resume', '--last', message],
+      messageViaPane: false,
+    };
+  },
+  latestSessionId,
+  isForegroundCommand(cmd) {
+    return cmd === 'codex' || cmd === 'node' || cmd === 'unsnooze';
+  },
+};