claude-brink 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linus Pisano
+
+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,265 @@
+# Brink
+
+> **Usage limits should be checkpoints, not walls.**
+
+Brink keeps your AI coding agent's work alive across a usage lockout. When you're about to hit your limit, it gracefully pauses the agent and writes everything in flight to a `HANDOFF.md` — so a surprise mid-task lockout costs you nothing. Optional (experimental): auto-resume when the limit resets.
+
+[![status](https://img.shields.io/badge/status-pre--launch-orange)](#status) [![license](https://img.shields.io/badge/license-MIT-blue)](#license) [![core](https://img.shields.io/badge/core-live--verified-brightgreen)](#proof-live-verified-2026-06-26)
+
+```bash
+npm i -g claude-brink
+brink init      # wires the hooks + sensor into Claude Code
+brink doctor    # verifies the whole chain on YOUR machine
+```
+
+**What works where, today:**
+
+| | Windows | macOS / Linux |
+|---|---|---|
+| Auto-pause + `HANDOFF.md` (the core) | ✅ live-verified | ⚠️ should work — **not yet tested** |
+| Usage statusline + warnings | ✅ | ⚠️ untested |
+| Desktop toast | ✅ | ❌ not built yet (ntfy push works everywhere) |
+| Auto-resume (**experimental**, off by default) | ✅ Task Scheduler | ❌ launchd/cron planned |
+
+**Kill switch:** `brink off` disables everything instantly (`brink on` re-enables, `brink uninstall` removes cleanly and restores your statusline). Brink *blocks tool calls by design* — you always hold the off button.
+
+<!-- DEMO GIF GOES HERE — replace with docs/demo.gif -->
+<p align="center"><em>[ demo.gif — Brink pausing a live session and writing HANDOFF.md ]</em></p>
+
+---
+
+## The problem
+
+You're deep in a task. The agent is three files into a refactor, mid-thought, holding context you'll never reconstruct by hand. Then it hits the wall — the 5-hour limit, the weekly cap — and stops cold. Whatever it understood about the task is gone. When the limit resets, you start over, re-explaining, re-orienting, paying for the same ramp-up twice.
+
+There are 25+ tools that show you your usage. Gauges, countdowns, menu-bar percentages, push notifiers. They tell you the wall is coming. **None of them keep your work alive when you hit it.**
+
+That gap is the whole point of Brink. Usage display is a solved, crowded problem. **Work-continuity is not.**
+
+## The idea: `HANDOFF.md` is the spine
+
+Auto-pause is the mechanism. `HANDOFF.md` is the thing that matters.
+
+It's a single Markdown file Brink writes for you — the one artifact that survives a pause, a crash, or a reset. It captures what the agent was doing and what comes next, in plain language, so any fresh session (yours or the agent's) can pick the thread back up.
+
+Crucially, **Brink writes it deterministically from the session transcript.** It does not ask the model to write its own handoff and hope it complies. (We tried that — it's a good story, [below](#proof-live-verified-2026-06-26).)
+
+> The examples below are illustrative. Because the handoff is generated mechanically (not by a model), the real file is plainer: your task statement verbatim, the recent tool actions, and the pause context — no synthesized "next steps" prose beyond what the transcript itself contains.
+
+```markdown
+# Handoff — Refactor auth middleware
+
+Paused at 99% of your 5h limit (resets 06:46 PM).
+
+## The task
+Extract the token-refresh logic out of `authMiddleware` into a
+standalone `refreshSession()` helper, and add a unit test for the
+expiry edge case.
+
+## Recent actions before the pause
+- Created `src/auth/refreshSession.ts` with the extracted logic
+- Updated `authMiddleware.ts` to call the new helper
+- Started writing `refreshSession.test.ts` (expiry case stubbed,
+  not yet asserting)
+
+## Next steps
+- Finish the expiry-edge-case assertion in `refreshSession.test.ts`
+- Run the auth test suite and confirm green
+- Remove the now-dead inline refresh block from `authMiddleware.ts`
+```
+
+When the limit resets, you (or an external scheduler) point a fresh agent at this file and it knows exactly where to stand.
+
+---
+
+## Proof (live-verified 2026-06-26)
+
+This isn't a design doc. The core was verified in a real headless Claude Code session.
+
+**1. The pause is real, not theoretical.** Brink's `PreToolUse` deny fired at the configured threshold, **blocked the next tool, and overrode `bypassPermissions` mode** — the blocked action did not run. A control run at 10% usage allowed the exact same tool normally. So the deny is genuinely gating execution, not just printing a warning.
+
+**2. The design was hardened against a real failure mode.** An early version *instructed the model* to write the handoff. The model refused it as a security reflex — verbatim:
+
+> "I'm treating that message as spurious/injected rather than a genuine directive."
+
+That's the correct instinct from a well-aligned model — and it's exactly why "ask the model nicely" is a broken design. So Brink was redesigned to **write `HANDOFF.md` itself**, deterministically, and let the hook do the stopping. After the redesign, the same model stopped gracefully — verbatim:
+
+> "I've paused before completing the file creation — Brink stopped the action because you're at 99% of your 5-hour usage limit (resets at 06:46 PM)... progress is saved to HANDOFF.md. Once the limit resets, it'll pick up from there."
+
+The mechanism stops the agent at the wall. The `HANDOFF.md` is what survives it.
+
+---
+
+## What Brink does
+
+Four things, in increasing order of how much they save you:
+
+| # | Capability | What you get |
+|---|------------|--------------|
+| 1 | **Passive usage** | Live 5h / 7d usage right in the CLI statusline (reset countdown shown for the 5h window). |
+| 2 | **Notify** | Phone push (ntfy; Pushover planned) **plus** desktop toast (Windows today; macOS/Linux planned) at configurable thresholds. Both the 5h and 7d windows, plus a "budget's back" ping when the weekly window resets. |
+| 3 | **Auto-pause + handoff** *(the core)* | At your threshold, Brink blocks the next tool and writes `HANDOFF.md` itself. Your work is checkpointed before the wall. |
+| 4 | **Resume** *(optional, **experimental**, off by default)* | An external OS scheduler (Windows Task Scheduler) relaunches a fresh process that reads `HANDOFF.md` after the limit resets. ⚠️ This relaunches an autonomous agent **unattended** — read the caveats before enabling. |
+
+---
+
+## How it works
+
+Brink is a **shared Node core with thin per-CLI adapters**, so the hard logic lives in one place and each CLI just maps its own config and field names.
+
+```
+┌─────────────┐   writes    ┌────────────┐   reads    ┌──────────────┐
+│ statusline  │ ──────────▶ │ state file │ ─────────▶ │ PreToolUse   │
+│ sensor      │  usage %    │ (small)    │            │ hook         │
+│ (per CLI)   │             └────────────┘            └──────┬───────┘
+└─────────────┘                                              │ at threshold
+                                                             ▼
+                                          ┌──────────────────────────────┐
+                                          │ 1. block the next tool        │
+                                          │ 2. emit a short deny message  │
+                                          │ 3. write HANDOFF.md itself    │
+                                          │    (from session transcript)  │
+                                          └──────────────────────────────┘
+```
+
+1. **Sensor.** A statusline sensor reads your current usage and writes a small state file.
+2. **Hook.** A `PreToolUse` hook reads that state file before each tool call. Below threshold, it does nothing. At or above threshold, it blocks the next tool and emits one short, credible, non-contradictory deny:
+
+   > *Paused by Brink at 99% of your 5h limit, resets 06:46 PM. Saved to HANDOFF.md. Stop and reply in plain text.*
+
+3. **Handoff.** Brink writes `HANDOFF.md` itself, deterministically, from the session transcript. It does **not** depend on the model cooperating.
+
+Design choices that matter:
+
+- **Default threshold ≈ 93%** of the 5h window — enough headroom that the pause lands *before* the wall, not on it.
+- **No auto-commit.** Brink will not write to your branch unattended. An agent committing to your repo while you're away is the genuinely scary failure mode, so it's off by design — Brink saves a file; what you do with it is your call.
+- **No trusting the model to write the handoff.** That path was tested and rejected (see the proof above).
+- **Kill-switch escape hatch.** A single file instantly disables the hook. A bad threshold can never brick your session.
+- **BOM-robust reads.** State and transcript reads tolerate byte-order marks, so Windows/PowerShell-written config won't trip the parser.
+
+---
+
+## What a generated `HANDOFF.md` looks like
+
+Built from the live transcript at pause time — not a template you fill in:
+
+```markdown
+# Handoff — feat/payment-retries
+
+Paused at 99% of your 5h limit (resets 06:46 PM).
+
+## The task
+Add exponential-backoff retry to the Stripe webhook handler so transient
+5xx responses don't drop payment events. Cap at 5 attempts, jittered.
+
+## Recent actions before the pause
+- Added `retryWithBackoff()` helper in src/lib/retry.ts
+- Wired it into webhookHandler() for the `charge.failed` path
+- Started updating tests in test/webhook.test.ts (2 of 5 cases done)
+
+## Next steps
+- Finish the remaining 3 test cases (timeout, max-attempts, success-on-retry)
+- Confirm jitter is applied per-attempt, not once
+- Run the suite and check the handler still returns 200 on give-up
+```
+
+---
+
+## Supported CLIs
+
+The promise is honest: **auto-pause where the CLI supports it, notify-before-limit everywhere else.**
+
+| CLI | Auto-pause | Notify | Notes |
+|-----|:----------:|:------:|-------|
+| **Claude Code** | ✅ Full | ✅ | Built and **live-verified** (see proof above). |
+| **Codex CLI** | ⚙️ Pending upstream | ✅ | Adapter built; field names verified against Codex source. Currently **inert** because `rate_limits` is `null` in Codex rollout files ([openai/codex#14880](https://github.com/openai/codex/issues/14880)) — that nulls out notify too, so today the adapter reads nothing. Both notify and auto-pause activate when the upstream data lands (auto-pause with a caveat: Codex's pre-tool gate reliably covers shell commands only). |
+| **Gemini CLI** | 🔜 Planned | 🔜 Planned | Adapter seam ready. |
+| **opencode** | 🔜 Planned | 🔜 Planned | Adapter seam ready. |
+| **Crush** | ❌ | 🔜 Planned | No usage feed / no hooks to gate on — notify-only is the ceiling, and that adapter isn't written yet. |
+| **aider** | ❌ | 🔜 Planned | No usage feed / no hooks to gate on — notify-only is the ceiling, and that adapter isn't written yet. |
+
+> To be explicit: **Codex auto-pause does not work today.** It doesn't yet, because of a bug upstream of Brink. The adapter is real and waiting — when the data lands, it lights up with no change on your side.
+
+---
+
+## Honest caveats
+
+These are kept on purpose. Brink is a continuity tool, not magic.
+
+- **Resume is EXPERIMENTAL.** It's off by default, Windows-only (**Task Scheduler** v1; launchd/cron planned), and has the least real-world runtime of any Brink feature. It relaunches a **fresh** process that reads `HANDOFF.md` — a clean restart from a written checkpoint, **not** an in-memory restore. Enabling it means an autonomous agent restarts **unattended, while you're away**, spending your quota in your project — and `skip_permissions` maps to `--dangerously-skip-permissions` (no permission prompts at all). Leave both off unless you fully accept that.
+- **A 5h reset does not clear the weekly cap.** Brink tracks both windows; if you're up against the 7d wall, a 5h reset won't save you — but Brink will tell you which window you're hitting.
+- **No unattended commits.** By design (see above). `HANDOFF.md` is written; your branch is left untouched.
+- **`HANDOFF.md` contains your session.** It's built from the transcript, so your task text and recent tool actions land in it verbatim — including anything sensitive you typed. It's written to the project directory and **gitignoring it is on you** (Brink never commits it, but *you* might). Treat it like a scratch file, not documentation.
+- **The usage sensor depends on an undocumented surface.** Claude Code pipes `rate_limits` to statuslines today; that's not a versioned API. If your setup doesn't receive usage data (some API-key/enterprise configurations), Brink can't arm — `brink doctor` tells you if that's you.
+
+## Positioning
+
+Anthropic explicitly declined the configurable-threshold-alert feature request ([claude-code#17431](https://github.com/anthropics/claude-code/issues/17431)). Brink is **the threshold-aware pause Anthropic said no to, as a drop-in** — plus the handoff and resume layer on top.
+
+---
+
+## Install
+
+### npm (recommended)
+
+```bash
+npm i -g claude-brink
+brink init      # wires hooks + usage sensor into ~/.claude/settings.json
+brink doctor    # proves the whole chain works on YOUR machine — run it
+```
+
+That's the entire install. `brink init` backs up your settings first (`settings.json.brink-bak`), is idempotent, and **tells you loudly** if it replaces an existing custom statusline (yours is restorable — `brink uninstall` puts it back). If your `settings.json` has a syntax error, `init` **aborts instead of touching it**.
+
+Then run **`brink doctor`**. It exercises the real chain end-to-end — sensor → state file → pause hook (in a sandbox) → kill switch → an actual desktop notification — and prints a copy-pasteable report. This exists because silent environment-dependent failure is the #1 risk of a tool like this; if something on your machine doesn't work, doctor finds it *now*, not at 93%.
+
+Everyday commands:
+
+```bash
+brink off          # kill switch — instantly disables everything
+brink on           # re-enable
+brink uninstall    # removes hooks, restores your original statusline
+```
+
+`brink init` currently targets **Claude Code**. Multi-CLI detection (Codex, Gemini, opencode) is on the roadmap — see [Supported CLIs](#supported-clis).
+
+### Plugin marketplace (alternative)
+
+```
+/plugin marketplace add LinusPisano/claude-brink
+/plugin install brink@brink
+```
+
+This wires the **hooks** only — Claude Code plugins can't register a `statusLine` (platform limit), and the statusline is Brink's usage sensor. Complete it with `npm i -g claude-brink && brink init` anyway, which makes the plugin path redundant. Honestly: **just use npm.**
+
+> ⚠️ If you wire the statusline by hand, never point it into the plugin's install directory — plugin dirs are versioned per update, so the path silently dies on the next update while the hooks keep acting on frozen usage data. The npm global path is stable; use that.
+
+---
+
+## Status
+
+- **The core (pause + handoff) is live-verified** on real sessions and dogfooded daily by the author. It survived a 41-finding adversarial review and a 5-advisor launch council — both in `docs/`.
+- **Resume and notifications are younger** — working and end-to-end tested, but with days (not months) of real-world runtime. That's why resume ships off-by-default and `brink doctor` exists.
+- **Verified on Windows 11; macOS/Linux pause-path untested** — the honesty matrix at the top is the truth. If you run it on a Mac, `brink doctor` output in an issue is gold.
+- **On GitHub, currently private** — the repo goes public alongside the launch of [pisanolinus.com](https://pisanolinus.com) and my [LinkedIn](https://www.linkedin.com/in/linus-pisano); the npm package is live now.
+
+Roadmap from here: the remaining adapters (Gemini, opencode), the `npm` package + `brink init`, the demo GIF + public flip, and the Codex pause flipping live the moment upstream lands.
+
+If you're reading this at launch: the pause is real, the handoff is real, and the caveats above are the whole truth.
+
+---
+
+## License
+
+[MIT](LICENSE).
+
+---
+
+## Author
+
+Built by **Linus Pisano** — CAD + full-stack + agentic AI.
+
+- 🌐 [pisanolinus.com](https://pisanolinus.com)
+- 💼 [linkedin.com/in/linus-pisano](https://www.linkedin.com/in/linus-pisano)
+- ✉️ [pisanolinus@gmail.com](mailto:pisanolinus@gmail.com)
+
+*Follow the launch on X — link coming with the public release.*

package/config.example.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Copy to config.json in ~/.claude/brink/ and edit. Never commit your ntfy topic (it is the only auth for your push channel). The kill switch is a fixed path: create ~/.claude/brink/DISABLED to instantly disable Brink.",
+  "notify": {
+    "ntfy_topic": "REPLACE-with-your-secret-topic",
+    "windows_toast": true
+  },
+  "thresholds": {
+    "five_hour": { "warn": [75, 85], "pause": 93 },
+    "seven_day": { "warn": [80, 90], "pause": 95 }
+  },
+  "_reset_ping_comment": "Ping when a window rolls over (budget is back). 'enabled' off for 5h (resets several times a day = noise) / on for weekly (days of budget back). 'floor' = only ping if you were at/above this % before it reset, so a reset from low usage stays silent.",
+  "reset_ping": {
+    "five_hour": { "enabled": false, "floor": 75 },
+    "seven_day": { "enabled": true, "floor": 80 }
+  },
+  "_resume_comment": "Opt-in. skip_permissions=true relaunches with --dangerously-skip-permissions: the resumed agent runs WITHOUT permission prompts, unattended, in your project. Leave false unless you fully accept that.",
+  "resume": {
+    "enabled": false,
+    "buffer_seconds": 90,
+    "skip_permissions": false
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "comment": "Brink plugin hooks (auto-discovered when installed via the Claude Code plugin marketplace). PreToolUse = graceful auto-pause before the limit; PostToolUse = threshold warning. ${CLAUDE_PLUGIN_ROOT} resolves to the installed plugin dir. NOTE: a plugin CANNOT register the statusLine (the usage sensor) — only 'agent'/'subagentStatusLine' are honored in a plugin's settings.json. The statusLine must be added by the user (one line) or by `node src/install.js --statusline`. Without it, state.json is never written and these hooks have no data to act on.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/brink.js\" claude pause" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/brink.js\" claude warn" }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "claude-brink",
+  "version": "0.1.0",
+  "description": "Claude Code stops at the brink — graceful auto-pause + handoff before you hit a usage limit, with optional auto-resume after reset.",
+  "license": "MIT",
+  "author": "Linus Pisano <pisanolinus@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LinusPisano/claude-brink.git"
+  },
+  "homepage": "https://github.com/LinusPisano/claude-brink#readme",
+  "keywords": ["claude-code", "usage-limit", "rate-limit", "auto-pause", "handoff", "notifications", "ntfy"],
+  "bin": { "brink": "src/cli.js" },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node tests/run.js && node tests/core.test.js && node tests/handoff.test.js && node tests/install.test.js && node tests/reset.test.js && node tests/resume.test.js && node tests/cli.test.js",
+    "install-hooks": "node src/install.js",
+    "install-all": "node src/install.js --statusline"
+  },
+  "files": ["src", "hooks", "config.example.json", "README.md", "LICENSE"]
+}

package/src/adapters/claude.js

@@ -0,0 +1,43 @@
+// Brink adapter — Claude Code. Implements the two-method adapter contract:
+//   readUsage() -> normalized usage   |   denyOutput(reason) -> how this CLI blocks
+// Usage source: the state.json the Brink statusline writes (the cleanest source of all).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const dir = () => process.env.BRINK_DIR || path.join(os.homedir(), '.claude', 'brink');
+
+function readUsage() {
+  const sp = path.join(dir(), 'state.json');
+  if (!fs.existsSync(sp)) return null;
+  try {
+    const raw = fs.readFileSync(sp, 'utf8');
+    const s = JSON.parse(raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw);
+    const num = (v) => (typeof v === 'number' ? v : null);
+    return {
+      provider: 'claude',
+      five_pct: num(s.five_pct),
+      week_pct: num(s.week_pct),
+      five_reset: num(s.five_reset),
+      week_reset: num(s.week_reset),
+      session_id: s.session_id || '',
+      cwd: s.cwd || '',
+    };
+  } catch { return null; }
+}
+
+// Claude Code PreToolUse deny: JSON on stdout, exit 0.
+function denyOutput(reason) {
+  return {
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }),
+    exitCode: 0,
+  };
+}
+
+module.exports = { name: 'claude', readUsage, denyOutput };

package/src/adapters/codex.js

@@ -0,0 +1,80 @@
+// Brink adapter — OpenAI Codex CLI.
+// readUsage(): parse the newest ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl token_count
+//   event, which carries the primary (~5h) + secondary (~weekly) rate-limit windows.
+// denyOutput(): Codex PreToolUse blocks via exit code 2 + reason on stderr.
+//
+// Field names VERIFIED against Codex Rust source (protocol.rs, RateLimitWindow) + 53 real
+// local rollout files: guard .type=="event_msg" && .payload.type=="token_count"; data at
+// .payload.rate_limits.{primary,secondary}.{used_percent, window_minutes, resets_at} (epoch s).
+// ⚠️ UPSTREAM BUG (openai/codex#14880): rate_limits is almost always `null` in rollout files,
+//   so this returns null TODAY and pause won't fire until OpenAI populates it (or we add an alt
+//   source: auth.json -> ChatGPT usage endpoint). We scan back for a populated line and never
+//   act on null (safe no-op). ⚠️ Codex PreToolUse also reliably gates Bash only (edits/MCP leaky).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const sessionsDir = () => process.env.CODEX_SESSIONS || path.join(os.homedir(), '.codex', 'sessions');
+
+function newestRollout(root) {
+  if (!fs.existsSync(root)) return null;
+  let best = null;
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/^rollout-.*\.jsonl$/.test(e.name)) {
+        const m = fs.statSync(p).mtimeMs;
+        if (!best || m > best.m) best = { p, m };
+      }
+    }
+  };
+  try { walk(root); } catch { return null; }
+  return best && best.p;
+}
+
+const pick = (obj, keys) => {
+  for (const k of keys) if (obj && obj[k] != null) return obj[k];
+  return null;
+};
+
+function parseWindow(w, now) {
+  if (!w) return { pct: null, reset: null };
+  const pct = pick(w, ['used_percent', 'used_percentage', 'percent', 'percent_used']);
+  const at = pick(w, ['resets_at', 'reset_at']);
+  const inSecs = pick(w, ['resets_in_seconds', 'reset_in_seconds', 'resets_in']);
+  let reset = null;
+  if (typeof at === 'number') reset = at > 1e12 ? Math.floor(at / 1000) : at;
+  else if (typeof inSecs === 'number') reset = now + inSecs;
+  return { pct: typeof pct === 'number' ? pct : null, reset };
+}
+
+function readUsage() {
+  const f = newestRollout(sessionsDir());
+  if (!f) return null;
+  let lines;
+  try { let raw = fs.readFileSync(f, 'utf8'); if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1); lines = raw.split(/\r?\n/).filter(Boolean); } catch { return null; }
+  let rl = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let ev; try { ev = JSON.parse(lines[i]); } catch { continue; }
+    rl = ev.rate_limits || (ev.payload && ev.payload.rate_limits) || (ev.info && ev.info.rate_limits) || null;
+    if (rl) break;
+  }
+  if (!rl) return null;
+  const now = Math.floor(Date.now() / 1000);
+  const primary = parseWindow(rl.primary || rl.five_hour, now);
+  const secondary = parseWindow(rl.secondary || rl.seven_day || rl.weekly, now);
+  return {
+    provider: 'codex',
+    five_pct: primary.pct, five_reset: primary.reset,
+    week_pct: secondary.pct, week_reset: secondary.reset,
+    session_id: '', cwd: process.cwd(),
+  };
+}
+
+// Codex PreToolUse deny: exit code 2 + reason on stderr (the reliable path).
+function denyOutput(reason) {
+  return { stderr: reason, exitCode: 2 };
+}
+
+module.exports = { name: 'codex', readUsage, denyOutput };

package/src/arm-resume.ps1

@@ -0,0 +1,27 @@
+# Brink - arm resume (Phase 7, opt-in)
+# Registers a one-shot Windows Task Scheduler job for the reset time that relaunches
+# Claude from HANDOFF.md. Driven by the authoritative resets_at (epoch seconds).
+# Buffer/Skip are passed through from config.json by brink.js (core/resume.js).
+# Invoked SYNCHRONOUSLY by brink.js (detached PowerShell dies without a console -
+# live-fire finding 2026-07-04).
+param(
+  [Parameter(Mandatory)][string]$ResetsAt,
+  [string]$Sid,
+  [string]$Proj,
+  [int]$Buffer = 90,
+  [string]$Skip = '0'
+)
+
+$fireAt = [DateTimeOffset]::FromUnixTimeSeconds([int64]$ResetsAt).ToLocalTime().AddSeconds($Buffer).DateTime
+# Sanitize the task name: session ids are normally uuid-safe, but Task Scheduler
+# rejects several characters, and the name must round-trip to resume-once.ps1.
+$name = 'BrinkResume_' + ($Sid -replace '[^\w\-]', '_')
+Unregister-ScheduledTask -TaskName $name -Confirm:$false -ErrorAction SilentlyContinue
+
+$resume = Join-Path $PSScriptRoot 'resume-once.ps1'
+# -ExecutionPolicy Bypass: stock Windows is Restricted and would refuse the script.
+$arg = "-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$resume`" -Sid `"$Sid`" -Proj `"$Proj`" -Buffer $Buffer -Skip `"$Skip`""
+Register-ScheduledTask -TaskName $name -RunLevel Limited `
+  -Action  (New-ScheduledTaskAction  -Execute 'powershell.exe' -Argument $arg) `
+  -Trigger (New-ScheduledTaskTrigger  -Once -At $fireAt) `
+  -Settings(New-ScheduledTaskSettingsSet -StartWhenAvailable -WakeToRun -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries) -ErrorAction Stop | Out-Null