@askalf/dario 4.0.1 → 4.1.1

package/README.md

@@ -34,6 +34,8 @@ That's the whole setup. Every tool that honors those env vars now runs on your s
 
 **New in v4:** type `dario` (no args) in another terminal to open the interactive TUI — live request stream, per-model burn-rate, rate-limit utilization, and a config editor that writes to `~/.dario/config.json`. Migrating from v3? See [MIGRATION.md](MIGRATION.md).
 
+**New in v4.1 — overage-guard:** dario halts itself the moment a single response carries `representative-claim: overage` and returns 503 with a clean error body until you run `dario resume` or the cooldown clears. Subscribers should never see an overage hit during normal operation; one means something is wrong, and continuing to forward requests bleeds against per-token billing. Active protection by default; flip to warn-only with `--overage-behavior=warn` or off entirely with `--no-overage-guard`.
+
 ```
 ┌─ dario v4 ──────────────────────────[ q quit · Tab next · ? help ]──┐
 │  Status   Config   ▎Analytics▎   Hits   Accounts   Backends         │
@@ -154,6 +156,45 @@ Reclassification flips the request from `five_hour` (your subscription) to `over
 
 ---
 
+## What dario does when overage lands (v4.1)
+
+v4 made the billing bucket visible per-request in the TUI's Hits tab. v4.1 turns that visibility into active protection.
+
+The moment any upstream response carries `representative-claim: overage`, dario **halts the proxy**. Every subsequent `/v1/messages`, `/v1/complete`, `/v1/chat/completions` request returns `503` with an Anthropic-shaped error body the client surfaces verbatim:
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "dario_overage_guard",
+    "message": "dario halted to prevent API-rate bleed. A request was classified as 'overage' (per-token billing) instead of your subscription pool. To resume: run `dario resume` in another terminal, or wait until <ISO ts> for the cooldown to auto-clear. Details: github.com/askalf/dario/issues/288"
+  }
+}
+```
+
+The TUI's Status tab pins the loud version:
+
+```
+┌─ dario v4 ──────────────────────────[ q quit · Tab next · ? help ]──┐
+│  ▎Status▎  Config   Analytics   Hits   Accounts   Backends         │
+├─────────────────────────────────────────────────────────────────────┤
+│  Overage-guard                                                      │
+│  ⚠ HALTED   overage detected 12s ago                                │
+│    Request:        claude-opus-4-7  account=default                 │
+│    Cause:          representative-claim = overage                   │
+│    Auto-resume in  29m 48s                                          │
+│    Manual resume   press R here, or `dario resume` from any shell   │
+│                                                                     │
+│  Last refresh: just now. r refresh · R resume.                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Why "halt at hit #1" is the right default: subscribers should never see a single overage response during normal operation. One means something is wrong — wire-shape drift, classifier change, account misconfig — and continuing to forward requests in the same shape bleeds real money for accounts with extra-usage enabled, or returns wall-of-rejections for accounts without it. The first hit is the signal; the second through hundredth are damage.
+
+**Resume paths** — `dario resume` from any shell, `R` on the TUI Status tab, or the cooldown timer (default 30 min). **Configuration** — `~/.dario/config.json` → `overageGuard`, or CLI flags (`--overage-behavior=warn` for visibility-only, `--no-overage-guard` to disable, `--overage-cooldown=<ms>` to tune). **OS notification** — best-effort native toast (osascript / notify-send / BurntToast) plus terminal BEL as the unconditional floor. See [#288](https://github.com/askalf/dario/issues/288).
+
+---
+
 ## Does it actually work?
 
 Four LLMs reviewed the codebase cold, same prompt ([`reviews/PROMPT.md`](./reviews/PROMPT.md)), each signed a verdict:
@@ -238,6 +279,7 @@ The tool doesn't know. The backend doesn't know. Dario is the seam.
 - **Shim mode.** Take the proxy off the wire entirely — `dario shim -- claude --print "hi"` patches `globalThis.fetch` in-process. No HTTP hop, no port, no `BASE_URL`. → [`docs/shim.md`](./docs/shim.md)
 - **Recover output capability.** `dario proxy --system-prompt=partial` strips CC's tone/verbosity/no-comments constraints for 1.2–2.8× more output on open-ended work — empirically without flipping billing (the classifier doesn't read that slot). [Discussion #183](https://github.com/askalf/dario/discussions/183) has the per-prompt receipts. → [`docs/system-prompt.md`](./docs/system-prompt.md)
 - **Reachable from inside CC / any MCP client.** `dario subagent install` registers a CC sub-agent for in-session diagnostics; `dario mcp` exposes dario as a read-only MCP server. → [`docs/sub-agent.md`](./docs/sub-agent.md) · [`docs/mcp-server.md`](./docs/mcp-server.md)
+- **Active overage protection (v4.1).** Halts the proxy on any `representative-claim: overage` response and returns 503 to subsequent requests until you run `dario resume` or the cooldown clears. Visibility-only mode (`--overage-behavior=warn`) for operators who want the signal without disrupting traffic. Halt state visible in TUI Status/Hits/Analytics tabs, surfaced as named SSE events, and as a best-effort native desktop notification. [#288](https://github.com/askalf/dario/issues/288).
 
 ---
 
@@ -245,11 +287,11 @@ The tool doesn't know. The backend doesn't know. Dario is the seam.
 
 | Signal | Status |
 |---|---|
-| Source | **17,507** lines of TypeScript across **42** files — auditable in a weekend |
+| Source | **~18.5k** lines of TypeScript across **44** files — auditable in a weekend |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
-| Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore (v4.0.0 published 2026-05-16T11:46:01Z; Rekor logIndex `1553210791`) |
+| Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore. v4.1.0 published 2026-05-16T15:13:24Z |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push and weekly |
-| Tests | **2,080** assertions across 77 test files (71 in default `npm test` suite) — green on every release |
+| Tests | **80 test files**, **74 in default `npm test` suite** — green on every release |
 | Drift response | [`cc-drift-watch.yml`](./.github/workflows/cc-drift-watch.yml) hourly cron, [`cc-drift-auto-release.yml`](./.github/workflows/cc-drift-auto-release.yml) auto-publish on merge — median CC-release → dario-release under one hour |
 | Credentials | Never logged, redacted from errors, `0600` on disk in `0700` dirs; MCP server redacts at the tool boundary |
 | Network | Binds `127.0.0.1` by default; upstream only to configured backends over HTTPS; hardcoded SSRF allowlist |
@@ -273,7 +315,7 @@ cd $(npm root -g)/@askalf/dario && npm ls --production
 
 ## Commands
 
-`dario` (TUI) · `login` · `proxy` · `doctor` · `accounts {list,add,remove}` · `backend {list,add,remove}` · `shim` · `mcp` · `subagent {install,status,remove}` · `usage` · `config` · `upgrade` · `status` · `refresh` · `logout` · `help`
+`dario` (TUI) · `login` · `proxy` · `doctor` · `accounts {list,add,remove}` · `backend {list,add,remove}` · `shim` · `mcp` · `subagent {install,status,remove}` · `usage` · `config` · `upgrade` · `status` · `refresh` · `resume` · `logout` · `help`
 
 Full flag/env reference: [`docs/commands.md`](./docs/commands.md) · SDK examples + per-tool setup: [`docs/usage.md`](./docs/usage.md)
 
@@ -285,7 +327,10 @@ Full flag/env reference: [`docs/commands.md`](./docs/commands.md) · SDK example
 Mechanically, dario uses your existing Claude Code OAuth tokens — it authenticates you as you, with your subscription, through Anthropic's official endpoints. Whether any particular use complies with current terms is between you and Anthropic; consult their terms and your agreement. Independent, unofficial, third-party — see [DISCLAIMER.md](DISCLAIMER.md).
 
 **What does the v4 TUI actually do?**
-Open `dario` with no args. Six tabs: **Status** shows proxy health + OAuth expiry + config source; **Config** edits `~/.dario/config.json` in place (bool toggles inline, numbers/strings open a prompt, `s` saves); **Analytics** polls `/analytics` every 2s and renders per-model bars + rate-limit utilization + billing buckets; **Hits** subscribes to `/analytics/stream` SSE for the live request feed with per-record detail drilldown; **Accounts** lists the pool; **Backends** lists OpenAI-compat backends. Pure ANSI, zero new runtime deps. Migration from v3: [MIGRATION.md](MIGRATION.md).
+Open `dario` with no args. Six tabs: **Status** shows proxy health + OAuth expiry + config source + overage-guard state (v4.1: halt banner with countdown + `R` to resume); **Config** edits `~/.dario/config.json` in place (bool toggles inline, numbers/strings open a prompt, `s` saves); **Analytics** polls `/analytics` every 2s and renders per-model bars + rate-limit utilization + an Overage bar that's red the moment count is non-zero (v4.1); **Hits** subscribes to `/analytics/stream` SSE for the live request feed with per-record detail drilldown and a pinned halt banner when overage is detected (v4.1); **Accounts** lists the pool; **Backends** lists OpenAI-compat backends. Pure ANSI, zero new runtime deps. Migration from v3: [MIGRATION.md](MIGRATION.md).
+
+**What if a request lands in `overage` despite the wire-shape replay?**
+v4.1+ halts the proxy on the first overage response and returns 503 to subsequent requests until you investigate. See [What dario does when overage lands](#what-dario-does-when-overage-lands-v41). The TUI Status tab shows the triggering request + countdown to auto-resume; `dario resume` from any shell clears the halt immediately; `--overage-behavior=warn` switches to visibility-only mode if you'd rather see the signal than block traffic.
 
 **Do I need Claude Code installed?**
 Recommended, not required. With CC, `dario login` picks up credentials automatically and the live template extractor reads your binary on every startup. Without it, dario runs its own OAuth flow and falls back to the bundled (scrubbed) template snapshot.

package/dist/cli.js

@@ -189,6 +189,56 @@ async function refresh() {
         process.exit(1);
     }
 }
+async function resume() {
+    // v4.1, dario#288 — clear the overage-guard halt state on a running
+    // dario proxy via POST /admin/resume. The proxy returns 200 with
+    // {ok, wasHalted, resumedAt}; we surface that to the operator.
+    //
+    // Port resolution mirrors `dario doctor` — --port flag > DARIO_PORT
+    // env > config file > 3456 default. Auth: DARIO_API_KEY when set
+    // (matches the same auth chain dario applies to every endpoint).
+    const { loadConfig } = await import('./config-file.js');
+    const fileResult = loadConfig();
+    const portArg = args.find(a => a.startsWith('--port='));
+    const portFromCli = portArg ? parseInt(portArg.split('=')[1], 10) : undefined;
+    const portFromEnv = process.env['DARIO_PORT'] ? parseInt(process.env['DARIO_PORT'], 10) : undefined;
+    const port = portFromCli ?? portFromEnv ?? fileResult.config.port ?? 3456;
+    const url = `http://127.0.0.1:${port}/admin/resume`;
+    const headers = { 'Content-Type': 'application/json' };
+    const apiKey = process.env['DARIO_API_KEY'];
+    if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    let resp;
+    try {
+        resp = await fetch(url, { method: 'POST', headers, body: '{}' });
+    }
+    catch (err) {
+        const msg = err.message;
+        // The proxy-not-running case is the common failure path; surface a
+        // friendly hint instead of a raw fetch error. Match across runtimes:
+        //   - Node: 'ECONNREFUSED', 'fetch failed', 'ENOTFOUND', 'ETIMEDOUT'
+        //   - Bun:  'Unable to connect' (different fetch error wording)
+        //   - Both: 'connect EHOSTUNREACH', 'getaddrinfo' (DNS path)
+        if (/ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EHOSTUNREACH|fetch failed|unable to connect|getaddrinfo/i.test(msg)) {
+            console.error(`[dario] No proxy running on localhost:${port}. Start one with \`dario proxy\` (overage-guard state is per-process; there's nothing to resume on a stopped proxy).`);
+            process.exit(1);
+        }
+        console.error(`[dario] Resume request failed: ${msg}`);
+        process.exit(1);
+    }
+    if (!resp.ok) {
+        console.error(`[dario] Resume request returned HTTP ${resp.status}. Body: ${(await resp.text()).slice(0, 500)}`);
+        process.exit(1);
+    }
+    const result = await resp.json();
+    if (result.wasHalted) {
+        console.log(`[dario] Resumed at ${result.resumedAt}. Proxy returning to normal request handling.`);
+    }
+    else {
+        console.log(`[dario] Proxy was not halted — no-op. (Overage-guard state was already clear.)`);
+    }
+}
 async function logout() {
     const path = join(homedir(), '.dario', 'credentials.json');
     try {
@@ -423,6 +473,46 @@ async function proxy() {
     // billable-filter. Empty values are dropped. Falls back to
     // DARIO_PASSTHROUGH_BETAS env var.
     const passthroughBetas = parsePassthroughBetasFlag(args, process.env['DARIO_PASSTHROUGH_BETAS']);
+    // --overage-guard / --no-overage-guard / DARIO_OVERAGE_GUARD=off|on (v4.1)
+    // When any upstream response carries `representative-claim: overage`,
+    // halt the proxy: every new request returns 503 with an Anthropic-shaped
+    // error body until cooldown expires or `dario resume` clears the state.
+    // Subscribers should never see an overage hit during normal operation,
+    // so this defaults ON — the cost of a false negative (silent per-token
+    // billing) far exceeds the cost of a false positive (one disrupted
+    // session that resumes with a single command). See dario#288.
+    //
+    //   --no-overage-guard                 → fully disabled
+    //   --overage-behavior=halt|warn       → halt (default) or warn-only (no 503)
+    //   --overage-cooldown=<MS>            → auto-resume after this delay (default 30 min)
+    //   --no-overage-notify                → suppress OS-level desktop notification
+    //   DARIO_OVERAGE_GUARD=off            → env equivalent of --no-overage-guard
+    //   DARIO_OVERAGE_BEHAVIOR=halt|warn   → env equivalent of --overage-behavior
+    //   DARIO_OVERAGE_COOLDOWN=<MS>        → env equivalent of --overage-cooldown
+    //   DARIO_OVERAGE_NOTIFY=off           → env equivalent of --no-overage-notify
+    const overageGuardEnabledFromFlag = args.includes('--no-overage-guard') ? false
+        : args.includes('--overage-guard') ? true : undefined;
+    const overageGuardEnabledFromEnv = parseBooleanEnv(process.env['DARIO_OVERAGE_GUARD']);
+    const overageGuardEnabled = overageGuardEnabledFromFlag
+        ?? overageGuardEnabledFromEnv
+        ?? fileCfg.overageGuard?.enabled
+        ?? true;
+    const overageBehaviorFromFlag = args.find((a) => a.startsWith('--overage-behavior='))?.split('=').slice(1).join('=');
+    const overageBehaviorFromEnv = process.env['DARIO_OVERAGE_BEHAVIOR'];
+    const overageBehaviorRaw = overageBehaviorFromFlag ?? overageBehaviorFromEnv;
+    const overageGuardBehavior = overageBehaviorRaw === 'halt' || overageBehaviorRaw === 'warn'
+        ? overageBehaviorRaw
+        : (fileCfg.overageGuard?.behavior ?? 'halt');
+    const overageGuardCooldownMs = parsePositiveIntFlag('--overage-cooldown=')
+        ?? parsePositiveIntEnv(process.env['DARIO_OVERAGE_COOLDOWN'])
+        ?? fileCfg.overageGuard?.cooldownMs
+        ?? 30 * 60 * 1000;
+    const overageNotifyFromFlag = args.includes('--no-overage-notify') ? false : undefined;
+    const overageNotifyFromEnv = parseBooleanEnv(process.env['DARIO_OVERAGE_NOTIFY']);
+    const overageGuardNotifyOs = overageNotifyFromFlag
+        ?? overageNotifyFromEnv
+        ?? fileCfg.overageGuard?.notifyOs
+        ?? true;
     // Non-loopback bind without DARIO_API_KEY turns dario into an open
     // OAuth-subscription relay for anyone on the reachable network. Refuse
     // to start rather than rely on the operator to read the startup banner.
@@ -442,7 +532,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens, logFile, passthroughBetas, systemPrompt });
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens, logFile, passthroughBetas, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs });
 }
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
@@ -937,6 +1027,11 @@ async function help() {
     dario proxy [options]    Start the API proxy server
     dario status             Check authentication status
     dario refresh            Force token refresh
+    dario resume             Clear the overage-guard halt on a running proxy.
+                             v4.1.0+. Idempotent: returns "no-op" if the
+                             proxy isn't halted. Errors with a friendly hint
+                             if no proxy is running on localhost:3456.
+                             POSTs /admin/resume on the local proxy. (dario#288)
     dario logout             Remove saved credentials
     dario accounts list      List accounts in the multi-account pool
     dario accounts add NAME [--manual] [--from-keychain[=<target>]]
@@ -1194,6 +1289,37 @@ async function help() {
                              ceiling server-side, so too-high values
                              return a clean 400.
                              Env: DARIO_MAX_TOKENS. (dario#88)
+    --no-overage-guard       Disable the overage-guard (v4.1.0+). Default
+                             behavior halts the proxy on any response with
+                             representative-claim=overage and returns 503
+                             with an Anthropic-shaped error body until
+                             cooldown expires or \`dario resume\` clears
+                             the state. Subscribers should never see an
+                             overage hit during normal operation; one
+                             means something is wrong (wire drift,
+                             classifier change, account misconfig).
+                             Env: DARIO_OVERAGE_GUARD=off. (dario#288)
+    --overage-behavior=<halt|warn>
+                             Behavior when overage is detected (v4.1.0+):
+                               halt — return 503 to new /v1/messages
+                                      requests until resume / cooldown.
+                                      Default. Strongest protection.
+                               warn — emit events + OS notification only,
+                                      keep forwarding. Visibility mode for
+                                      operators who want the signal without
+                                      cutting off traffic.
+                             Env: DARIO_OVERAGE_BEHAVIOR.
+    --overage-cooldown=MS    Ms to wait before auto-clearing the halt
+                             state (v4.1.0+). Default: 1800000 (30 min).
+                             Manual \`dario resume\` clears immediately
+                             regardless of this value.
+                             Env: DARIO_OVERAGE_COOLDOWN.
+    --no-overage-notify      Suppress the native desktop notification on
+                             halt (v4.1.0+). Terminal BEL is the
+                             unconditional floor; TUI banner + SSE event
+                             still fire regardless. Use in headless / CI
+                             contexts where toast popups don't make sense.
+                             Env: DARIO_OVERAGE_NOTIFY=off.
     --port=PORT              Port to listen on (default: 3456)
     --host=ADDRESS           Address to bind to (default: 127.0.0.1)
                              Use 0.0.0.0 for LAN; see README for DARIO_API_KEY
@@ -1802,6 +1928,7 @@ const commands = {
     status,
     proxy,
     refresh,
+    resume,
     logout,
     accounts,
     backend,

package/dist/config-file.d.ts

@@ -86,6 +86,32 @@ export interface DarioConfig {
     systemPrompt?: string | null;
     preserveOrchestrationTags?: boolean;
     logFile?: string | null;
+    /**
+     * Overage-guard — halt the proxy on the first response carrying
+     * `representative-claim: overage`. Subscribers should never see a
+     * single overage hit during normal operation; one means something
+     * is wrong (wire-shape drift, classifier change, account misconfig)
+     * and continuing to forward requests bleeds against per-token
+     * billing. See dario#288.
+     *
+     * `behavior: 'halt'`  — return 503 with an Anthropic-shaped error
+     *                       body until cooldown expires or `dario resume`
+     *                       runs. Default.
+     * `behavior: 'warn'`  — emit the SSE event + OS notification but
+     *                       leave proxy behavior unchanged.
+     *
+     * `cooldownMs` — auto-resume delay after a halt. 30 min default.
+     *
+     * `notifyOs` — best-effort native desktop notification on halt
+     *              (osascript/notify-send/BurntToast); terminal BEL is
+     *              the unconditional floor.
+     */
+    overageGuard?: {
+        enabled?: boolean;
+        behavior?: 'halt' | 'warn';
+        cooldownMs?: number;
+        notifyOs?: boolean;
+    };
 }
 /**
  * Defaults match the v3.x CLI flag defaults exactly. Any value not

package/dist/config-file.js

@@ -71,6 +71,12 @@ export function defaultConfig() {
         systemPrompt: null,
         preserveOrchestrationTags: false,
         logFile: null,
+        overageGuard: {
+            enabled: true,
+            behavior: 'halt',
+            cooldownMs: 30 * 60 * 1000,
+            notifyOs: true,
+        },
     };
 }
 /**
@@ -320,6 +326,23 @@ function sanitize(parsed) {
     const logFile = pickStringOrNull('logFile');
     if (logFile !== undefined)
         out.logFile = logFile;
+    if (isPlainObject(parsed.overageGuard)) {
+        out.overageGuard = {};
+        if (typeof parsed.overageGuard.enabled === 'boolean') {
+            out.overageGuard.enabled = parsed.overageGuard.enabled;
+        }
+        if (parsed.overageGuard.behavior === 'halt' || parsed.overageGuard.behavior === 'warn') {
+            out.overageGuard.behavior = parsed.overageGuard.behavior;
+        }
+        if (typeof parsed.overageGuard.cooldownMs === 'number'
+            && Number.isFinite(parsed.overageGuard.cooldownMs)
+            && parsed.overageGuard.cooldownMs >= 0) {
+            out.overageGuard.cooldownMs = parsed.overageGuard.cooldownMs;
+        }
+        if (typeof parsed.overageGuard.notifyOs === 'boolean') {
+            out.overageGuard.notifyOs = parsed.overageGuard.notifyOs;
+        }
+    }
     // Silence unused-warning helper.
     void pickNumberOrNull;
     return out;

package/dist/notify.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Best-effort cross-platform desktop notification dispatcher.
+ *
+ * Pure Node, no new dependencies. Resolves the platform's native toast
+ * mechanism at load time, falls back to the terminal BEL character on any
+ * platform that doesn't have one (or where the native path is missing).
+ *
+ * Backends:
+ *   - macOS:   `osascript -e 'display notification "msg" with title "dario"'`
+ *   - Linux:   `notify-send "dario" "msg"` (gnome / kde / dunst / mako)
+ *   - Windows: `powershell -Command New-BurntToastNotification ...` if the
+ *              `BurntToast` module is installed; falls back to `msg.exe`,
+ *              else BEL only.
+ *
+ * BEL char (`\x07`) is the unconditional floor — works on every terminal
+ * that respects ANSI control characters, which is nearly all of them.
+ *
+ * Silent on failure: a missing `osascript`/`notify-send`/PowerShell path
+ * is the common case for non-interactive sessions, headless CI runs, and
+ * SSH-into-a-server flows. The TUI banner is the authoritative surface;
+ * OS-notify is the loud, attention-grabbing supplement.
+ *
+ * See dario#288 — overage-guard.
+ */
+/**
+ * Fire a native notification. Returns immediately — the underlying spawn
+ * is fire-and-forget. Errors (missing binary, permission denied, no
+ * graphical session) are swallowed; the caller already has the in-app
+ * surface and shouldn't depend on this firing.
+ *
+ * `title` and `message` are passed verbatim except for shell-meta escaping
+ * — single quotes and backticks are stripped so the AppleScript / shell
+ * payload can't be hijacked by a malicious upstream response.
+ */
+export declare function notify(title: string, message: string): void;
+/**
+ * Test-mode hook — returns a notifier that pushes into a captured array
+ * instead of firing real OS notifications. Used by test/notify-cross-
+ * platform.mjs to verify the dispatch path without invoking osascript.
+ */
+export declare function captureNotifier(): {
+    notify: (title: string, message: string) => void;
+    captured: Array<{
+        title: string;
+        message: string;
+        ts: number;
+    }>;
+};

package/dist/notify.js

@@ -0,0 +1,120 @@
+/**
+ * Best-effort cross-platform desktop notification dispatcher.
+ *
+ * Pure Node, no new dependencies. Resolves the platform's native toast
+ * mechanism at load time, falls back to the terminal BEL character on any
+ * platform that doesn't have one (or where the native path is missing).
+ *
+ * Backends:
+ *   - macOS:   `osascript -e 'display notification "msg" with title "dario"'`
+ *   - Linux:   `notify-send "dario" "msg"` (gnome / kde / dunst / mako)
+ *   - Windows: `powershell -Command New-BurntToastNotification ...` if the
+ *              `BurntToast` module is installed; falls back to `msg.exe`,
+ *              else BEL only.
+ *
+ * BEL char (`\x07`) is the unconditional floor — works on every terminal
+ * that respects ANSI control characters, which is nearly all of them.
+ *
+ * Silent on failure: a missing `osascript`/`notify-send`/PowerShell path
+ * is the common case for non-interactive sessions, headless CI runs, and
+ * SSH-into-a-server flows. The TUI banner is the authoritative surface;
+ * OS-notify is the loud, attention-grabbing supplement.
+ *
+ * See dario#288 — overage-guard.
+ */
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+/**
+ * Fire a native notification. Returns immediately — the underlying spawn
+ * is fire-and-forget. Errors (missing binary, permission denied, no
+ * graphical session) are swallowed; the caller already has the in-app
+ * surface and shouldn't depend on this firing.
+ *
+ * `title` and `message` are passed verbatim except for shell-meta escaping
+ * — single quotes and backticks are stripped so the AppleScript / shell
+ * payload can't be hijacked by a malicious upstream response.
+ */
+export function notify(title, message) {
+    // Always BEL first — works in every TTY, doesn't depend on a graphical
+    // session. The OS notification on top is best-effort.
+    try {
+        process.stderr.write('\x07');
+    }
+    catch {
+        // stderr write can fail under exotic conditions (closed handle,
+        // detached process); silent — we have nothing else to fall back to.
+    }
+    const safeTitle = sanitize(title);
+    const safeMessage = sanitize(message);
+    const plat = platform();
+    try {
+        if (plat === 'darwin') {
+            // AppleScript single-quote inside the script body would need
+            // escaping; sanitize() strips them so the literal substitution
+            // below stays safe. Spawned via array argv to avoid a shell
+            // entirely.
+            spawn('osascript', [
+                '-e',
+                `display notification "${safeMessage}" with title "${safeTitle}"`,
+            ], { detached: true, stdio: 'ignore' }).unref();
+        }
+        else if (plat === 'linux') {
+            spawn('notify-send', [safeTitle, safeMessage], {
+                detached: true,
+                stdio: 'ignore',
+            }).unref();
+        }
+        else if (plat === 'win32') {
+            // BurntToast is the cleanest path — single-line PowerShell, real
+            // Windows toast notification. If BurntToast isn't installed the
+            // command fails silently (stdio: ignore swallows the error
+            // output), which is the desired behavior.
+            //
+            // We don't probe-then-spawn; the cost of one failed BurntToast
+            // attempt is the same as one probe attempt, and probing makes the
+            // hot path slower for the success case.
+            const ps = `try { Import-Module BurntToast -ErrorAction Stop; New-BurntToastNotification -Text '${safeTitle}', '${safeMessage}' } catch { exit 1 }`;
+            spawn('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                ps,
+            ], { detached: true, stdio: 'ignore' }).unref();
+        }
+        // freebsd / openbsd / aix / sunos / android — BEL only. There's no
+        // single "right" native notification on these platforms.
+    }
+    catch {
+        // spawn() itself can throw on EMFILE or similar; silent.
+    }
+}
+/**
+ * Strip characters that would break the embedded shell/AppleScript
+ * payload or allow command injection. Conservative: only allow printable
+ * ASCII + common Unicode word chars + a small whitelist of punctuation.
+ *
+ * This is NOT a general-purpose sanitizer; it exists to defang text we
+ * already control (our own messages) from accidentally containing
+ * AppleScript-breaking characters like a stray double quote.
+ */
+function sanitize(s) {
+    return s
+        .replace(/[\r\n]/g, ' ') // collapse newlines
+        .replace(/[`'"$]/g, '') // strip shell metas + quotes
+        .replace(/\\/g, '/') // strip backslashes
+        .slice(0, 200); // cap length; notifications truncate anyway
+}
+/**
+ * Test-mode hook — returns a notifier that pushes into a captured array
+ * instead of firing real OS notifications. Used by test/notify-cross-
+ * platform.mjs to verify the dispatch path without invoking osascript.
+ */
+export function captureNotifier() {
+    const captured = [];
+    return {
+        notify: (title, message) => {
+            captured.push({ title, message, ts: Date.now() });
+        },
+        captured,
+    };
+}

package/dist/overage-guard.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Overage-guard — halt the proxy on the first `representative-claim: overage`
+ * response to prevent silent API-rate bleed.
+ *
+ * Subscribers should never see a single overage hit during normal
+ * operation. One means something is wrong (wire-shape drift, classifier
+ * change, account misconfig, billing-flip after a CC release) and
+ * continuing to forward requests bleeds against per-token billing.
+ *
+ * The guard subscribes to the Analytics record stream — every completed
+ * request emits a record carrying its `claim` (raw representative-claim
+ * value). When `claim === 'overage'` lands, the guard transitions to a
+ * halted state and emits a `'halt'` event. The HTTP request path checks
+ * `isHalted()` on every incoming request and returns 503 with an
+ * Anthropic-shaped error body when halted.
+ *
+ * Resume paths:
+ *   - explicit:  `dario resume` CLI → POST /admin/resume → `clear('manual')`
+ *   - automatic: cooldown expires (default 30 min) → `clear('cooldown')`
+ *   - TUI:       `r` key on Status tab → POST /admin/resume (same as CLI)
+ *
+ * Behavior:
+ *   - `halt` (default) — record halted state + return 503 on subsequent requests
+ *   - `warn` — emit events + notify only; proxy keeps forwarding (visibility-only mode)
+ *
+ * See dario#288.
+ */
+import { EventEmitter } from 'node:events';
+import type { Analytics, RequestRecord } from './analytics.js';
+export interface HaltState {
+    since: number;
+    cooldownUntil: number;
+    reason: 'overage_detected';
+    request: {
+        timestamp: number;
+        model: string;
+        account: string;
+        claim: string;
+    };
+}
+export interface OverageGuardOptions {
+    enabled: boolean;
+    behavior: 'halt' | 'warn';
+    cooldownMs: number;
+    notifyOs: boolean;
+    /**
+     * Best-effort native desktop notification dispatcher. Pass the function
+     * from `./notify.ts` here. Optional — silent failure if absent. The
+     * guard always emits the `'halt'` event for in-process subscribers
+     * (the SSE stream, the TUI) regardless of whether OS-notify fired.
+     */
+    notifier?: (title: string, message: string) => void;
+}
+export declare class OverageGuard extends EventEmitter {
+    private opts;
+    private halted;
+    private cooldownTimer;
+    private analyticsListener;
+    constructor(opts: OverageGuardOptions);
+    /**
+     * Subscribe to an Analytics instance. Every record emitted with
+     * `claim === 'overage'` triggers halt (when behavior === 'halt') or a
+     * warn-only event (when behavior === 'warn').
+     *
+     * Idempotent — calling attach() a second time replaces the listener
+     * rather than stacking; useful for tests.
+     */
+    attach(analytics: Analytics): void;
+    /**
+     * Synthesize a halt event from a record. Public for the test harness;
+     * production code reaches this via attach() + the live Analytics stream.
+     */
+    onOverageDetected(r: RequestRecord): void;
+    /**
+     * Resume the proxy. Emits a 'resume' event with the reason.
+     *
+     * No-op when not currently halted. Safe to call from any path
+     * (CLI, /admin/resume HTTP endpoint, TUI `r` key, cooldown timer).
+     */
+    clear(reason: 'manual' | 'cooldown'): void;
+    /** Current halt state, or `null` if not halted. */
+    state(): HaltState | null;
+    /** Quick boolean for the request hot-path. */
+    isHalted(): boolean;
+    /** Detach from Analytics. Used by tests and by graceful shutdown. */
+    destroy(): void;
+    /** Expose options for the /status endpoint + TUI Status tab. */
+    config(): Readonly<OverageGuardOptions>;
+}
+/**
+ * The Anthropic-shaped error body returned by halted-503 responses. The
+ * shape matches what `api.anthropic.com` emits for any 4xx so CC /
+ * Cursor / Aider / Cline surface the message verbatim to the user — no
+ * client-specific handling needed.
+ */
+export declare function buildHaltErrorBody(state: HaltState): {
+    type: 'error';
+    error: {
+        type: string;
+        message: string;
+    };
+};