@askalf/dario 4.0.1 → 4.1.0

package/dist/cli.js

@@ -189,6 +189,53 @@ 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 Node fetch error.
+        if (/ECONNREFUSED|fetch failed/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 +470,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 +529,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
@@ -1802,6 +1889,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;
+    };
+};

package/dist/overage-guard.js

@@ -0,0 +1,189 @@
+/**
+ * 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';
+export class OverageGuard extends EventEmitter {
+    opts;
+    halted = null;
+    cooldownTimer = null;
+    analyticsListener = null;
+    constructor(opts) {
+        super();
+        // /analytics/stream + TUI tabs each register a listener; the in-proc
+        // event listeners ceiling matches the Analytics class's choice.
+        this.setMaxListeners(100);
+        this.opts = opts;
+    }
+    /**
+     * 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) {
+        if (this.analyticsListener) {
+            analytics.off('record', this.analyticsListener);
+        }
+        if (!this.opts.enabled) {
+            // Guard fully disabled — don't even register the listener. No
+            // detection, no halt, no events.
+            this.analyticsListener = null;
+            return;
+        }
+        this.analyticsListener = (r) => {
+            if (r.claim === 'overage') {
+                this.onOverageDetected(r);
+            }
+        };
+        analytics.on('record', this.analyticsListener);
+    }
+    /**
+     * Synthesize a halt event from a record. Public for the test harness;
+     * production code reaches this via attach() + the live Analytics stream.
+     */
+    onOverageDetected(r) {
+        if (this.halted) {
+            // Already halted — don't re-fire halt events. The original halt
+            // state stays in place until cleared. A second overage hit while
+            // halted is expected (the client may not have noticed the 503
+            // yet); silent.
+            return;
+        }
+        const state = {
+            since: Date.now(),
+            cooldownUntil: Date.now() + this.opts.cooldownMs,
+            reason: 'overage_detected',
+            request: {
+                timestamp: r.timestamp,
+                model: r.model,
+                account: r.account,
+                claim: r.claim,
+            },
+        };
+        if (this.opts.behavior === 'halt') {
+            this.halted = state;
+            // Schedule auto-resume. Timer reference is held so we can cancel
+            // it on a manual resume — otherwise a manual resume followed by
+            // continued use, then the original cooldown firing, would emit a
+            // spurious second 'resume' event.
+            this.cooldownTimer = setTimeout(() => {
+                if (this.halted && this.halted.since === state.since) {
+                    this.clear('cooldown');
+                }
+            }, this.opts.cooldownMs);
+            this.cooldownTimer.unref();
+        }
+        // Always fire 'halt' (or 'warn') so SSE subscribers see the event
+        // even in warn-only mode — the TUI's job is to surface this to the
+        // user regardless of whether the proxy chose to block traffic.
+        const eventName = this.opts.behavior === 'halt' ? 'halt' : 'warn';
+        try {
+            this.emit(eventName, state);
+        }
+        catch (err) {
+            // A subscriber threw — log + swallow, don't crash on event side-effects.
+            console.error('[dario] overage-guard subscriber threw:', err.message);
+        }
+        if (this.opts.notifyOs && this.opts.notifier) {
+            try {
+                const title = this.opts.behavior === 'halt' ? 'dario halted' : 'dario warning';
+                const msg = `Request classified as 'overage' (per-token billing)${this.opts.behavior === 'halt' ? '. Proxy halted. Run `dario resume` to continue.' : ''}`;
+                this.opts.notifier(title, msg);
+            }
+            catch {
+                // Native notification failure is non-fatal. Already emitted to
+                // SSE / TUI; the user gets the in-app banner regardless.
+            }
+        }
+    }
+    /**
+     * 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) {
+        if (!this.halted)
+            return;
+        const wasHaltedAt = this.halted.since;
+        this.halted = null;
+        if (this.cooldownTimer) {
+            clearTimeout(this.cooldownTimer);
+            this.cooldownTimer = null;
+        }
+        try {
+            this.emit('resume', { reason, previousSince: wasHaltedAt });
+        }
+        catch (err) {
+            console.error('[dario] overage-guard resume subscriber threw:', err.message);
+        }
+    }
+    /** Current halt state, or `null` if not halted. */
+    state() {
+        return this.halted;
+    }
+    /** Quick boolean for the request hot-path. */
+    isHalted() {
+        return this.halted !== null && this.opts.behavior === 'halt';
+    }
+    /** Detach from Analytics. Used by tests and by graceful shutdown. */
+    destroy() {
+        this.removeAllListeners();
+        if (this.cooldownTimer) {
+            clearTimeout(this.cooldownTimer);
+            this.cooldownTimer = null;
+        }
+        this.halted = null;
+        this.analyticsListener = null;
+    }
+    /** Expose options for the /status endpoint + TUI Status tab. */
+    config() {
+        return this.opts;
+    }
+}
+/**
+ * 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 function buildHaltErrorBody(state) {
+    const isoCooldown = new Date(state.cooldownUntil).toISOString();
+    return {
+        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 ` +
+                `${isoCooldown} for the cooldown to auto-clear. ` +
+                `Details: github.com/askalf/dario/issues/288`,
+        },
+    };
+}

package/dist/proxy.d.ts

@@ -162,6 +162,20 @@ interface ProxyOptions {
      * Sourced from `--system-prompt=<value>` or DARIO_SYSTEM_PROMPT.
      */
     systemPrompt?: string;
+    /**
+     * 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 bleeds against per-token billing.
+     *
+     * Default: enabled, halt behavior, 30-min cooldown, OS-notify on.
+     * See dario#288.
+     */
+    overageGuardEnabled?: boolean;
+    overageGuardBehavior?: 'halt' | 'warn';
+    overageGuardCooldownMs?: number;
+    overageGuardNotifyOs?: boolean;
 }
 /**
  * One JSON-ND record per completed request. Field set kept narrow to