claude-brink 0.1.0

package/src/brink.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Brink core driver. Usage: node brink.js <claude|codex> <warn|pause>
+// Reads usage via the adapter, decides via the shared threshold engine, then:
+//   warn  -> fires a debounced notification (once per window/band/reset-block)
+//   pause -> Brink WRITES HANDOFF.md itself, then emits the adapter's native deny with a
+//            short, credible, non-contradictory reason (see Phase 5 / live-test findings).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { decide } = require('./core/thresholds');
+const { writeHandoff } = require('./core/handoff');
+const { shouldArm, armArgs } = require('./core/resume');
+
+const DIR = process.env.BRINK_DIR || path.join(os.homedir(), '.claude', 'brink');
+const HATCH = path.join(DIR, 'DISABLED');
+const FLAG_TTL_MS = 14 * 24 * 3600 * 1000; // GC debounce/armed flags older than 14 days
+
+const DEFAULT_CFG = {
+  five_hour: { warn: [75, 85], pause: Number(process.env.BRINK_PAUSE || 93) },
+  seven_day: { warn: [80, 90], pause: Number(process.env.BRINK_WEEKLY_PAUSE || 95) },
+};
+
+function loadRawCfg() {
+  try {
+    const raw = fs.readFileSync(path.join(DIR, 'config.json'), 'utf8');
+    return JSON.parse(raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw);
+  } catch { return {}; }
+}
+// Deep-merge per window so a partial override ({five_hour:{pause:97}}) cannot
+// silently drop the warn bands or the other window's pause (review finding).
+function mergeThresholds(user) {
+  const out = {};
+  for (const w of ['five_hour', 'seven_day']) {
+    const d = DEFAULT_CFG[w];
+    const u = (user && typeof user[w] === 'object' && user[w]) || {};
+    out[w] = {
+      warn: Array.isArray(u.warn) && u.warn.every((n) => typeof n === 'number') ? u.warn : d.warn,
+      pause: typeof u.pause === 'number' ? u.pause : d.pause,
+    };
+  }
+  return out;
+}
+function loadAdapter(name) {
+  if (name === 'claude') return require('./adapters/claude');
+  if (name === 'codex') return require('./adapters/codex');
+  throw new Error('unknown adapter: ' + name);
+}
+function notify(msg) {
+  try {
+    const c = spawn('node', [path.join(__dirname, 'notify.js'), msg],
+      { detached: true, stdio: 'ignore', windowsHide: true });
+    c.on('error', () => {}); // async spawn failure must never crash the hook
+    c.unref();
+  } catch {}
+}
+function resetText(epoch) {
+  if (typeof epoch !== 'number') return '';
+  const d = new Date(epoch * 1000);
+  if (isNaN(d.getTime())) return '';
+  // A weekly reset can be days out — "resets at 02:30" alone would mislead.
+  const far = epoch * 1000 - Date.now() > 20 * 3600 * 1000;
+  return far
+    ? d.toLocaleString([], { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' })
+    : d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+// A window whose resets_at is in the past has ROLLED — its stored pct is stale.
+// Without this gate a resumed headless session (no statusline running yet) reads
+// the pre-pause 99% and denies its own first tool call (review finding: the
+// Phase 7 resume would self-block). 60s slack absorbs clock skew.
+function dropStaleWindows(usage) {
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof usage.five_reset === 'number' && usage.five_reset < now - 60) usage.five_pct = null;
+  if (typeof usage.week_reset === 'number' && usage.week_reset < now - 60) usage.week_pct = null;
+  return usage;
+}
+function gcFlags() {
+  try {
+    const cutoff = Date.now() - FLAG_TTL_MS;
+    for (const f of fs.readdirSync(DIR)) {
+      if (!/^(notified|armed)_/.test(f)) continue;
+      const p = path.join(DIR, f);
+      try { if (fs.statSync(p).mtimeMs < cutoff) fs.unlinkSync(p); } catch {}
+    }
+  } catch {}
+}
+// Only the pause path needs the hook payload (transcript_path/cwd). Read stdin lazily.
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve({});
+    let s = ''; let done = false;
+    const fin = () => { if (done) return; done = true; try { resolve(JSON.parse(s || '{}')); } catch { resolve({}); } };
+    process.stdin.on('data', (d) => { s += d; });
+    process.stdin.on('end', fin);
+    process.stdin.on('error', () => resolve({}));
+    setTimeout(fin, 800); // fallback so a hook never hangs waiting on stdin
+  });
+}
+
+async function main() {
+  const [adapterName, mode = 'pause'] = process.argv.slice(2);
+  const adapter = loadAdapter(adapterName);
+
+  if (fs.existsSync(HATCH)) process.exit(0);           // kill switch
+  const usage = adapter.readUsage();
+  if (!usage) process.exit(0);                          // no data => never act blind
+  dropStaleWindows(usage);
+
+  const rawCfg = loadRawCfg();
+  const cfg = mergeThresholds(rawCfg.thresholds);
+  const d = decide(usage, cfg);
+  if (d.action === 'allow') process.exit(0);
+
+  fs.mkdirSync(DIR, { recursive: true });
+  gcFlags();
+  const flag = path.join(DIR, `notified_${adapterName}_${d.windowKey}_${d.band}_${d.reset}`.replace(/[^\w.-]/g, '_'));
+  const once = (msg) => { if (!fs.existsSync(flag)) { fs.writeFileSync(flag, ''); notify(msg); } };
+
+  if (mode === 'warn' && d.action === 'warn') {
+    once(`Brink: ${d.window} usage at ${Math.round(d.pct)}%`);
+    process.exit(0);
+  }
+
+  if (mode === 'pause' && d.action === 'pause') {
+    const hook = await readStdin();
+    const cwd = hook.cwd || usage.cwd || process.cwd();
+    const rt = resetText(d.reset);
+    // Brink writes the handoff itself — robust even if the model won't cooperate.
+    const handoffPath = writeHandoff({ transcriptPath: hook.transcript_path, cwd, pct: d.pct, window: d.window, resetText: rt });
+    once(`Brink: paused - ${d.window} at ${Math.round(d.pct)}%`);
+
+    // Resume (Phase 7, opt-in): register a one-shot scheduler job for the reset time.
+    // SYNCHRONOUS on purpose — live-fire testing proved PowerShell 5.1 dies when
+    // spawned detached (DETACHED_PROCESS = no console) and dies with the parent's
+    // console when attached, so fire-and-forget silently never registers the task.
+    // A pause is a terminal event; blocking ~1-2s here is correct. The armed flag is
+    // written only AFTER the scheduler confirms, so a failure can retry next call.
+    // Prefer the hook's own session_id — the shared state.json may hold another
+    // concurrent session's id (multi-window finding).
+    const ctx = { session_id: hook.session_id || usage.session_id, reset: d.reset, proj: cwd };
+    if (shouldArm(rawCfg, ctx, os.platform())) {
+      const armFlag = path.join(DIR, `armed_${ctx.session_id}_${ctx.reset}`.replace(/[^\w.-]/g, '_'));
+      if (!fs.existsSync(armFlag)) {
+        try {
+          const ps = path.join(__dirname, 'arm-resume.ps1');
+          const r = spawnSync('powershell',
+            ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', ps, ...armArgs(rawCfg, ctx)],
+            { stdio: 'ignore', windowsHide: true, timeout: 20000 });
+          if (r.status === 0) fs.writeFileSync(armFlag, '');
+          else notify('Brink: resume arming FAILED - will not auto-resume');
+        } catch { /* arming is best-effort; never block the pause */ }
+      }
+    }
+
+    const file = handoffPath ? path.basename(handoffPath) : '';
+    const saved = file
+      ? `Your progress and next steps are already saved to ${file}. `
+      : ''; // never claim a save that did not happen (review finding)
+    const reason = `Paused by Brink: you are at ${Math.round(d.pct)}% of your ${d.window} usage limit${rt ? `, which resets at ${rt}` : ''}. ${saved}Stop here and reply to the user in plain text — do not start new work; it will resume${file ? ' from the handoff' : ''} when the limit resets.`;
+    const out = adapter.denyOutput(reason);
+    if (out.stdout) process.stdout.write(out.stdout);
+    if (out.stderr) process.stderr.write(out.stderr);
+    process.exit(out.exitCode || 0);
+  }
+
+  process.exit(0);
+}
+main();

package/src/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Brink CLI — the one command a stranger needs. Zero deps, Node >=18.
+//   brink init        wire hooks + statusline into Claude Code (wraps install.js)
+//   brink off | on    kill switch (create/remove the DISABLED file)
+//   brink uninstall   surgically remove Brink from settings.json (restore statusline)
+//   brink doctor      self-check the whole chain: sensor -> state -> hook -> notify
+//   brink version
+// Born from the 2026-07-04 launch council: the kill switch, the doctor, and a TRUE
+// npm install story collapse into this file (docs/council-2026-07-04.html).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SRC = __dirname;
+const DIR = process.env.BRINK_DIR || path.join(os.homedir(), '.claude', 'brink');
+const HATCH = path.join(DIR, 'DISABLED');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0] || 'help';
+const getOpt = (n, d) => { const i = argv.indexOf(n); return i >= 0 ? (argv[i + 1] || true) : d; };
+const settingsPath = getOpt('--settings', path.join(os.homedir(), '.claude', 'settings.json'));
+
+const readJson = (p) => {
+  try { const r = fs.readFileSync(p, 'utf8'); return JSON.parse(r.charCodeAt(0) === 0xFEFF ? r.slice(1) : r); }
+  catch { return null; }
+};
+const ok = (m) => console.log('  ok    ' + m);
+const bad = (m) => console.log('  FAIL  ' + m);
+const warn = (m) => console.log('  warn  ' + m);
+
+// ---- init: delegate to install.js (it owns idempotency, backup, abort-on-bad-JSON) ----
+function init() {
+  const args = [path.join(SRC, 'install.js'), '--settings', settingsPath];
+  if (!argv.includes('--no-statusline')) args.push('--statusline');
+  const r = spawnSync('node', args, { encoding: 'utf8' });
+  process.stdout.write(r.stdout || '');
+  process.stderr.write(r.stderr || '');
+  if (r.status !== 0) process.exit(r.status || 1);
+  console.log('Brink installed. Takes effect on your next Claude Code session.');
+  console.log('Verify anytime:  brink doctor    Kill switch:  brink off');
+}
+
+// ---- kill switch ----
+function off() {
+  fs.mkdirSync(DIR, { recursive: true });
+  fs.writeFileSync(HATCH, 'created by `brink off` ' + new Date().toISOString() + '\n');
+  console.log('Brink DISABLED (kill switch on). Hooks stay installed but do nothing.');
+  console.log('Re-enable:  brink on');
+}
+function on() {
+  try { fs.unlinkSync(HATCH); console.log('Brink enabled.'); }
+  catch { console.log('Brink was not disabled (no kill-switch file).'); }
+}
+
+// ---- uninstall: surgical — remove ONLY Brink's entries, keep everything else ----
+function uninstall() {
+  const s = readJson(settingsPath);
+  if (s === null) {
+    console.error(`Cannot parse ${settingsPath} - nothing changed. Fix or remove it manually.`);
+    process.exit(1);
+  }
+  const removed = [];
+  for (const event of ['PreToolUse', 'PostToolUse']) {
+    const groups = (s.hooks && s.hooks[event]) || [];
+    const kept = groups.filter((g) => !(g.hooks || []).some((h) => /brink\.js/.test(h.command || '')));
+    if (kept.length !== groups.length) { s.hooks[event] = kept; removed.push(event); }
+    if (s.hooks && Array.isArray(s.hooks[event]) && s.hooks[event].length === 0) delete s.hooks[event];
+  }
+  if (s.statusLine && /statusline-brink\.js/.test(JSON.stringify(s.statusLine))) {
+    const bak = readJson(settingsPath + '.brink-bak');
+    if (bak && bak.statusLine) { s.statusLine = bak.statusLine; removed.push('statusLine(restored from backup)'); }
+    else { delete s.statusLine; removed.push('statusLine(removed)'); }
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n');
+  console.log(removed.length
+    ? `Brink removed from ${settingsPath}: ${removed.join(', ')}`
+    : `Nothing to remove - Brink was not installed in ${settingsPath}.`);
+  console.log(`State dir kept at ${DIR} (delete it yourself, or run: brink uninstall --purge)`);
+  if (argv.includes('--purge')) {
+    try { fs.rmSync(DIR, { recursive: true, force: true }); console.log('State dir purged.'); } catch {}
+  }
+}
+
+// ---- doctor: verify the WHOLE chain on THIS machine. Exists because the detached-
+// PowerShell bug passed every unit test for weeks while never working in reality —
+// only end-to-end, on-machine checks catch environment-dependent silent failure. ----
+function doctor() {
+  let fails = 0;
+  const check = (name, pass, failMsg, warnOnly) => {
+    if (pass) ok(name);
+    else if (warnOnly) warn(name + ' - ' + failMsg);
+    else { bad(name + ' - ' + failMsg); fails++; }
+    return pass;
+  };
+  console.log(`brink doctor (v${version()}, ${os.platform()} ${os.release()}, node ${process.version})`);
+
+  // 1. config surface
+  const s = readJson(settingsPath);
+  check('settings.json parses', s !== null, `cannot read/parse ${settingsPath}`);
+  const hookCmds = s ? JSON.stringify(s.hooks || {}) : '';
+  check('PreToolUse pause hook installed', /brink\.js\\?" claude pause|brink\.js" claude pause/.test(hookCmds) || /brink\.js/.test(hookCmds) && /pause/.test(hookCmds), 'run: brink init');
+  check('PostToolUse warn hook installed', /brink\.js/.test(hookCmds) && /warn/.test(hookCmds), 'run: brink init');
+  const sensorWired = s && s.statusLine && /statusline-brink\.js|state\.json/.test(JSON.stringify(s.statusLine));
+  check('statusline sensor wired', !!sensorWired,
+    'no Brink-aware statusLine found - the hooks are BLIND without it (run: brink init, or merge the sensor into your custom statusline)', !s ? false : !sensorWired && !!s.statusLine);
+
+  // 2. kill switch
+  check('kill switch not active', !fs.existsSync(HATCH), 'DISABLED file present - run: brink on', true);
+
+  // 3. live state freshness (only meaningful during/after a real session)
+  const statePath = path.join(DIR, 'state.json');
+  const state = readJson(statePath);
+  if (state === null) warn('state.json not written yet - start a Claude Code session, then re-run doctor');
+  else {
+    ok('state.json exists and parses');
+    const age = (Date.now() - fs.statSync(statePath).mtimeMs) / 60000;
+    check('state is fresh (<30 min)', age < 30, `last write ${Math.round(age)} min ago - no active session, or the sensor is not running`, true);
+    check('usage data present', typeof state.five_pct === 'number' || typeof state.week_pct === 'number',
+      'sensor runs but rate_limits are empty - API-key/Bedrock setups may not receive usage data; Brink cannot arm', true);
+  }
+
+  // 4. end-to-end pause simulation in a sandbox (never touches your real state)
+  const sb = fs.mkdtempSync(path.join(os.tmpdir(), 'brink-doctor-'));
+  try {
+    const future = Math.floor(Date.now() / 1000) + 3600;
+    fs.writeFileSync(path.join(sb, 'state.json'),
+      JSON.stringify({ five_pct: 99, week_pct: 10, five_reset: future, week_reset: future + 500000, session_id: 'doctor', cwd: sb.replace(/\\/g, '/') }));
+    const env = { ...process.env, BRINK_DIR: sb, BRINK_SILENT: '1' };
+    const r = spawnSync('node', [path.join(SRC, 'brink.js'), 'claude', 'pause'],
+      { encoding: 'utf8', env, input: JSON.stringify({ cwd: sb.replace(/\\/g, '/') }), timeout: 15000 });
+    check('pause fires at threshold (sandbox)', (r.stdout || '').includes('"permissionDecision":"deny"'), 'deny did not fire: ' + (r.stderr || r.stdout || 'no output').slice(0, 200));
+    check('HANDOFF.md written (sandbox)', fs.existsSync(path.join(sb, 'HANDOFF.md')), 'handoff writer failed');
+    fs.writeFileSync(path.join(sb, 'DISABLED'), '');
+    const r2 = spawnSync('node', [path.join(SRC, 'brink.js'), 'claude', 'pause'], { encoding: 'utf8', env, input: '{}', timeout: 15000 });
+    check('kill switch blocks the pause (sandbox)', (r2.stdout || '').trim() === '', 'DISABLED file did not stop the hook');
+  } finally { try { fs.rmSync(sb, { recursive: true, force: true }); } catch {} }
+
+  // 5. live notification (real toast on Windows) — the step unit tests can never prove
+  if (argv.includes('--no-toast') || process.env.BRINK_SILENT) warn('notification test skipped (--no-toast/BRINK_SILENT)');
+  else {
+    const n = spawnSync('node', [path.join(SRC, 'notify.js'), 'Brink doctor: notifications work'], { encoding: 'utf8', timeout: 15000 });
+    let res = {}; try { res = JSON.parse((n.stdout || '{}').trim()); } catch {}
+    check('desktop notification fired', res.desktop === 'win-toast' || String(res.desktop || '').startsWith('desktop-todo'),
+      'toast chain failed: ' + JSON.stringify(res), String(res.desktop || '').startsWith('desktop-todo'));
+    if (String(res.desktop) === 'win-toast') console.log('        (a toast should be on your screen right now)');
+    if (res.push && !/skipped/.test(res.push)) ok('phone push: ' + res.push);
+  }
+
+  console.log(fails ? `\n${fails} check(s) FAILED - paste this whole output into a GitHub issue.` : '\nAll critical checks passed.');
+  process.exit(fails ? 1 : 0);
+}
+
+function version() { return (readJson(path.join(SRC, '..', 'package.json')) || {}).version || '?'; }
+
+function help() {
+  console.log(`brink v${version()} - graceful auto-pause + handoff for Claude Code
+  brink init [--no-statusline] [--settings <path>]   install hooks + sensor
+  brink doctor [--no-toast]                          verify the whole chain end-to-end
+  brink off | on                                     kill switch (instant disable/enable)
+  brink uninstall [--purge]                          remove cleanly (restores your statusline)
+  brink version`);
+}
+
+({ init, off, on, uninstall, doctor, version: () => console.log(version()), '--version': () => console.log(version()), help }[cmd] || (() => { console.error(`unknown command: ${cmd}`); help(); process.exit(1); }))();

package/src/core/handoff.js

@@ -0,0 +1,72 @@
+// Brink core — handoff writer (Phase 5).
+// Brink writes HANDOFF.md ITSELF (deterministically, from the session transcript) rather
+// than instructing the model to — because the live test (2026-06-26) showed the model may
+// distrust a tool-result that orders it around and refuse. The handoff must survive even if
+// the model won't cooperate. Best-effort transcript parse; degrades gracefully.
+const fs = require('fs');
+const path = require('path');
+
+function readTranscript(p) {
+  try {
+    let raw = fs.readFileSync(p, 'utf8'); if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    return raw.split(/\r?\n/).filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+function summarize(events) {
+  let lastUser = '';
+  const actions = [];
+  for (const e of events) {
+    const msg = e.message || e;
+    const role = msg.role || e.type;
+    const content = msg.content;
+    if (role === 'user' && content) {
+      const txt = typeof content === 'string'
+        ? content
+        : (Array.isArray(content) && (content.find((c) => c.type === 'text') || {}).text);
+      // skip tool_result echoes; keep real user prose
+      if (txt && !(Array.isArray(content) && content.some((c) => c.type === 'tool_result'))) lastUser = txt;
+    }
+    if (role === 'assistant' && Array.isArray(content)) {
+      for (const c of content) {
+        if (c.type === 'tool_use') {
+          const tgt = (c.input && (c.input.file_path || c.input.path || c.input.command)) || '';
+          actions.push(`${c.name}${tgt ? ' -> ' + String(tgt).slice(0, 80) : ''}`);
+        }
+      }
+    }
+  }
+  return { lastUser: String(lastUser || '').slice(0, 800), actions: actions.slice(-8) };
+}
+
+function writeHandoff({ transcriptPath, cwd, pct, window, resetText }) {
+  const events = transcriptPath ? readTranscript(transcriptPath) : [];
+  const { lastUser, actions } = summarize(events);
+  const dir = cwd || '.';
+  const isGit = fs.existsSync(path.join(dir, '.git'));
+  const lines = [
+    '# HANDOFF - paused by Brink',
+    '',
+    `Paused at **${Math.round(pct)}%** of your ${window} usage limit${resetText ? ` (resets ${resetText})` : ''}.`,
+    'This file was written automatically so no progress is lost. To resume, read it and continue the task.',
+    '',
+    '## The task',
+    '',
+    lastUser ? '> ' + lastUser.replace(/\n/g, '\n> ') : '_(could not read the original request from the transcript)_',
+    '',
+    '## Recent actions before the pause',
+    '',
+    actions.length ? actions.map((a) => '- ' + a).join('\n') : '_(no recent tool actions captured)_',
+    '',
+    '## Next steps',
+    '',
+    '- Continue the task above from where it stopped.',
+    isGit ? '- This IS a git repo - review uncommitted changes before continuing.' : '- (not a git repo - nothing to commit)',
+    '',
+  ];
+  const out = path.join(dir, 'HANDOFF.md');
+  try { fs.writeFileSync(out, lines.join('\n')); return out; } catch { return null; }
+}
+
+module.exports = { writeHandoff, summarize, readTranscript };

package/src/core/reset.js

@@ -0,0 +1,46 @@
+// Brink core — reset-ping detector (pure, no I/O). Phase 6.
+// Detects when a usage window has ROLLED OVER (its resets_at epoch jumped forward)
+// so Brink can fire a "your budget is back" ping. Only meaningful for a window you
+// were actually near the limit on — a floor gate keeps a reset from 12% silent
+// (that is not budget you were waiting on, it is noise).
+//
+// prev / cur: { five_pct, week_pct, five_reset, week_reset }  (last-seen + current state)
+// cfg.reset_ping: { five_hour:{enabled,floor}, seven_day:{enabled,floor} }
+//
+// Signal = resets_at advancing. Within a window resets_at is fixed; on rollover it
+// jumps to the next window's end (hours for 5h, days for weekly). GUARD kills float
+// jitter so only a genuine rollover counts.
+
+const GUARD = 60; // seconds
+
+const WINDOWS = [
+  { key: 'five_hour', label: '5h',     pct: 'five_pct', reset: 'five_reset' },
+  { key: 'seven_day', label: 'weekly', pct: 'week_pct', reset: 'week_reset' },
+];
+
+function detectResets(prev, cur, cfg) {
+  if (!prev || !cur) return []; // first run (no prior state) never pings
+  const rp = (cfg && cfg.reset_ping) || {};
+  const events = [];
+  for (const w of WINDOWS) {
+    const spec = rp[w.key] || {};
+    if (!spec.enabled) continue;
+    const pr = prev[w.reset];
+    const cr = cur[w.reset];
+    if (typeof pr !== 'number' || typeof cr !== 'number') continue;
+    if (cr <= pr + GUARD) continue; // didn't roll over
+    const prevPct = prev[w.pct];
+    const floor = typeof spec.floor === 'number' ? spec.floor : 0;
+    if (typeof prevPct === 'number' && prevPct < floor) continue; // weren't near the limit
+    events.push({
+      windowKey: w.key,
+      label: w.label,
+      prevPct: typeof prevPct === 'number' ? Math.round(prevPct) : null,
+      message: `Brink: ${w.label} limit reset - full quota again`
+        + (typeof prevPct === 'number' ? ` (was ${Math.round(prevPct)}%)` : ''),
+    });
+  }
+  return events;
+}
+
+module.exports = { detectResets, GUARD };

package/src/core/resume.js

@@ -0,0 +1,48 @@
+// Brink core — resume arming decision + arg builder (pure, no I/O). Phase 7.
+// A paused Claude can't wake itself, so resume is EXTERNAL: on pause, Brink (opt-in)
+// registers a one-shot Windows Task Scheduler job for the window's reset time that
+// relaunches `claude --resume` from HANDOFF.md. This module decides WHETHER to arm
+// and builds the PowerShell args; the actual scheduling lives in arm-resume.ps1.
+//
+// cfg.resume: { enabled:false, buffer_seconds:90, skip_permissions:false }
+
+const DEFAULT_RESUME = { enabled: false, buffer_seconds: 90, skip_permissions: false };
+
+function resumeCfg(cfg) {
+  const r = (cfg && cfg.resume) || {};
+  const out = { ...DEFAULT_RESUME, ...r };
+  // coerce / sanity-clamp
+  out.enabled = out.enabled === true;
+  out.buffer_seconds = Number.isFinite(out.buffer_seconds) && out.buffer_seconds >= 0
+    ? Math.floor(out.buffer_seconds) : DEFAULT_RESUME.buffer_seconds;
+  out.skip_permissions = out.skip_permissions === true;
+  return out;
+}
+
+// Arm only when: resume is enabled, we're on a platform with a scheduler (Windows in v1),
+// and we actually have the session id + reset epoch the resume needs.
+function shouldArm(cfg, ctx, platform) {
+  if (!resumeCfg(cfg).enabled) return false;
+  if (platform !== 'win32') return false;       // mac/Linux (launchd/cron) documented, not v1
+  if (!ctx || !ctx.session_id) return false;
+  if (typeof ctx.reset !== 'number' || !isFinite(ctx.reset)) return false;
+  return true;
+}
+
+// PowerShell args for arm-resume.ps1. Strings only (spawn args).
+// Proj is stripped of trailing (back)slashes: the scheduled task embeds it inside
+// an escaped-quoted -Argument string, where a trailing backslash would escape the
+// closing quote and mangle the whole command line (review finding).
+function armArgs(cfg, ctx) {
+  const r = resumeCfg(cfg);
+  const proj = String(ctx.proj || '').replace(/[\\/]+$/, '');
+  return [
+    '-ResetsAt', String(ctx.reset),
+    '-Sid', String(ctx.session_id || ''),
+    '-Proj', proj,
+    '-Buffer', String(r.buffer_seconds),
+    '-Skip', r.skip_permissions ? '1' : '0',
+  ];
+}
+
+module.exports = { resumeCfg, shouldArm, armArgs, DEFAULT_RESUME };

package/src/core/thresholds.js

@@ -0,0 +1,44 @@
+// Brink core — threshold decision engine (pure, no I/O). Phase 3.
+// Shared by every adapter (Claude, Codex, ...). Given normalized usage + config,
+// decide allow | warn | pause for the most-urgent window.
+//
+// usage: { five_pct, week_pct, five_reset, week_reset }  (pct = number 0-100 or null)
+// cfg:   { five_hour:{warn:[75,85], pause:93}, seven_day:{warn:[80,90], pause:95} }
+
+function bandFor(pct, spec) {
+  // highest band crossed: 'pause' | 'warn:<n>' | null
+  if (typeof pct !== 'number') return null;
+  if (typeof spec.pause === 'number' && pct >= spec.pause) return 'pause';
+  const warns = (spec.warn || []).slice().sort((a, b) => b - a); // high -> low
+  for (const w of warns) if (pct >= w) return `warn:${w}`;
+  return null;
+}
+
+function decide(usage, cfg) {
+  const windows = [
+    { key: 'five_hour', label: '5h', pct: usage.five_pct, reset: usage.five_reset },
+    { key: 'seven_day', label: 'weekly', pct: usage.week_pct, reset: usage.week_reset },
+  ];
+  const hit = windows
+    .map((w) => ({ ...w, band: bandFor(w.pct, cfg[w.key] || {}) }))
+    .filter((w) => w.band);
+
+  // pause beats warn; then higher pct wins
+  hit.sort((a, b) => {
+    const rank = (x) => (x.band === 'pause' ? 2 : 1);
+    return rank(b) - rank(a) || b.pct - a.pct;
+  });
+
+  const top = hit[0];
+  if (!top) return { action: 'allow' };
+  return {
+    action: top.band === 'pause' ? 'pause' : 'warn',
+    band: top.band,
+    window: top.label,
+    windowKey: top.key,
+    pct: top.pct,
+    reset: top.reset,
+  };
+}
+
+module.exports = { decide, bandFor };

package/src/install.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Brink installer — Claude Code adapter (the `brink init` for Claude).
+// Usage: node install.js [--settings <path>] [--statusline]
+// Registers the Brink hooks into the target Claude Code settings.json:
+//   PreToolUse  -> node brink.js claude pause   (graceful auto-pause before the limit)
+//   PostToolUse -> node brink.js claude warn    (threshold warning notifications)
+//   --statusline also points statusLine -> node statusline-brink.js (the usage sensor)
+// Idempotent (won't duplicate the brink hook for an event). Backs up the original once.
+//
+// SAFE BY DEFAULT for testing: pass --settings <sandbox> to target a throwaway file.
+// Bare `node` is used (not an absolute path) so the command works whether Claude Code
+// runs the hook in bash or PowerShell — node is on PATH wherever Claude Code runs.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SRC = __dirname;
+const q = (p) => `"${String(p).replace(/\\/g, '/')}"`;
+const cmd = (script, ...args) => ['node', q(path.join(SRC, script)), ...args].join(' ');
+
+const argv = process.argv.slice(2);
+const getOpt = (n, d) => { const i = argv.indexOf(n); return i >= 0 ? (argv[i + 1] || true) : d; };
+const settingsPath = getOpt('--settings', path.join(os.homedir(), '.claude', 'settings.json'));
+const withStatusline = argv.includes('--statusline');
+
+const PAUSE = cmd('brink.js', 'claude', 'pause');
+const WARN = cmd('brink.js', 'claude', 'warn');
+const STATUS = cmd('statusline-brink.js');
+
+// BOM-tolerant read. Returns null (NOT {}) on a parse failure so the caller can
+// ABORT — silently proceeding here wiped the user's whole settings.json down to
+// Brink-only content (review finding: a UTF-8 BOM was enough to trigger it).
+const read = (p) => {
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    return JSON.parse(raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw);
+  } catch { return null; }
+};
+const hasBrinkHook = (s, event) =>
+  ((s.hooks && s.hooks[event]) || []).some((g) => (g.hooks || []).some((h) => /brink\.js/.test(h.command || '')));
+
+function addHook(s, event, command) {
+  s.hooks = s.hooks || {};
+  s.hooks[event] = s.hooks[event] || [];
+  if (hasBrinkHook(s, event)) return false;
+  s.hooks[event].push({ hooks: [{ type: 'command', command }] });
+  return true;
+}
+
+function main() {
+  const existed = fs.existsSync(settingsPath);
+  let s = {};
+  if (existed) {
+    s = read(settingsPath);
+    if (s === null) {
+      console.error(`Brink install ABORTED: ${settingsPath} exists but is not valid JSON. ` +
+        'Fix it (or remove it) and re-run - refusing to overwrite your settings.');
+      process.exit(1);
+    }
+    if (!fs.existsSync(settingsPath + '.brink-bak')) {
+      fs.copyFileSync(settingsPath, settingsPath + '.brink-bak'); // one-time backup
+    }
+  }
+  const changed = [];
+  if (addHook(s, 'PreToolUse', PAUSE)) changed.push('PreToolUse(pause)');
+  if (addHook(s, 'PostToolUse', WARN)) changed.push('PostToolUse(warn)');
+  if (withStatusline && !/brink/.test(JSON.stringify(s.statusLine || ''))) {
+    if (s.statusLine) {
+      // be loud, not silent: the user had a custom statusline (review finding)
+      console.error(`note: replacing existing statusLine (original kept in ${settingsPath}.brink-bak)`);
+    }
+    s.statusLine = { type: 'command', command: STATUS };
+    changed.push('statusLine');
+  }
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n');
+  console.log(JSON.stringify({ settingsPath, changed, alreadyInstalled: changed.length === 0 }));
+}
+main();