@askalf/dario 4.0.1 → 4.1.1

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

package/dist/proxy.js

@@ -10,6 +10,8 @@ import { buildCCRequest, reverseMapResponse, createStreamingReverseMapper, order
 import { describeTemplate, detectDrift, checkCCCompat } from './live-fingerprint.js';
 import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs } from './pool.js';
 import { Analytics, billingBucketFromClaim } from './analytics.js';
+import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
+import { notify as osNotify } from './notify.js';
 import { loadAllAccounts, loadAccount, refreshAccountToken, resyncLoginFromCredentialsIfStale } from './accounts.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI } from './openai-backend.js';
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS } from './request-queue.js';
@@ -573,6 +575,31 @@ export async function startProxy(opts = {}) {
     // endpoint, but burn-rate / per-request visibility is useful for
     // single-account users too.
     const analytics = new Analytics();
+    // Overage-guard (v4.1, dario#288). Resolved from opts with built-in
+    // defaults (enabled=true, behavior='halt', cooldown=30min, notifyOs=true)
+    // so an opts-less proxy still gets protection. The notifier is wired
+    // separately below once notify.ts is loaded.
+    const overageGuard = new OverageGuard({
+        enabled: opts.overageGuardEnabled ?? true,
+        behavior: opts.overageGuardBehavior ?? 'halt',
+        cooldownMs: opts.overageGuardCooldownMs ?? 30 * 60 * 1000,
+        notifyOs: opts.overageGuardNotifyOs ?? true,
+        notifier: osNotify,
+    });
+    overageGuard.attach(analytics);
+    // Surface halt + resume to the foreground startup banner so an
+    // operator running `dario proxy` directly sees the event even without
+    // a TUI attached. -v / --verbose is not required — this is loud by
+    // design.
+    overageGuard.on('halt', (state) => {
+        console.error(`[dario] OVERAGE-GUARD HALTED: ${state.request.model} on account=${state.request.account} returned representative-claim=overage at ${new Date(state.request.timestamp).toISOString()}. Returning 503 to new requests until \`dario resume\` or cooldown expires (${new Date(state.cooldownUntil).toISOString()}). See dario#288.`);
+    });
+    overageGuard.on('warn', (state) => {
+        console.error(`[dario] OVERAGE-GUARD WARN: ${state.request.model} on account=${state.request.account} returned representative-claim=overage at ${new Date(state.request.timestamp).toISOString()}. Behavior=warn — proxy continuing to forward; investigate before bill bleeds. See dario#288.`);
+    });
+    overageGuard.on('resume', (info) => {
+        console.error(`[dario] overage-guard resumed (${info.reason}). Normal request handling restored.`);
+    });
     let status;
     if (pool) {
         for (const acc of accountsList) {
@@ -955,7 +982,16 @@ export async function startProxy(opts = {}) {
             for (const past of analytics.recent(50)) {
                 res.write(`data: ${JSON.stringify(past)}\n\n`);
             }
-            // Live tail
+            // Backlog the current halt state if any — a TUI attaching mid-halt
+            // needs to see the banner immediately without waiting for the
+            // next overage hit (which won't come, because the proxy is halted).
+            const haltedNow = overageGuard.state();
+            if (haltedNow) {
+                res.write(`event: overage_halt\ndata: ${JSON.stringify(haltedNow)}\n\n`);
+            }
+            // Live tail — request records on default 'message' event, halt /
+            // warn / resume on named events so the TUI can route on event type
+            // without changing the existing record shape.
             const onRecord = (r) => {
                 // Use try/catch so a broken socket (peer hung up between events)
                 // doesn't crash the request hot-path — Analytics already wraps
@@ -965,7 +1001,28 @@ export async function startProxy(opts = {}) {
                 }
                 catch { /* ignored */ }
             };
+            const onHalt = (state) => {
+                try {
+                    res.write(`event: overage_halt\ndata: ${JSON.stringify(state)}\n\n`);
+                }
+                catch { /* ignored */ }
+            };
+            const onWarn = (state) => {
+                try {
+                    res.write(`event: overage_warn\ndata: ${JSON.stringify(state)}\n\n`);
+                }
+                catch { /* ignored */ }
+            };
+            const onResume = (info) => {
+                try {
+                    res.write(`event: overage_resume\ndata: ${JSON.stringify(info)}\n\n`);
+                }
+                catch { /* ignored */ }
+            };
             analytics.on('record', onRecord);
+            overageGuard.on('halt', onHalt);
+            overageGuard.on('warn', onWarn);
+            overageGuard.on('resume', onResume);
             // Heartbeat every 25s — SSE comments are ignored by clients but
             // keep middle-boxes (CDNs, dev-proxies) from closing the pipe.
             const heartbeat = setInterval(() => {
@@ -977,10 +1034,39 @@ export async function startProxy(opts = {}) {
             heartbeat.unref?.();
             req.on('close', () => {
                 analytics.off('record', onRecord);
+                overageGuard.off('halt', onHalt);
+                overageGuard.off('warn', onWarn);
+                overageGuard.off('resume', onResume);
                 clearInterval(heartbeat);
             });
             return;
         }
+        // POST /admin/resume — clear overage-guard halt state (v4.1, dario#288).
+        // Idempotent: returns 200 with `wasHalted: false` if the proxy is
+        // already running normally. Auth gating is the same as every other
+        // endpoint (loopback-bind by default; DARIO_API_KEY needed for
+        // non-loopback). GET returns the current state for read-only queries.
+        if (urlPath === '/admin/resume' && req.method === 'GET') {
+            const state = overageGuard.state();
+            res.writeHead(200, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
+            res.end(JSON.stringify({
+                halted: state !== null,
+                state,
+                config: overageGuard.config(),
+            }));
+            return;
+        }
+        if (urlPath === '/admin/resume' && req.method === 'POST') {
+            const wasHalted = overageGuard.state() !== null;
+            overageGuard.clear('manual');
+            res.writeHead(200, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
+            res.end(JSON.stringify({
+                ok: true,
+                wasHalted,
+                resumedAt: new Date().toISOString(),
+            }));
+            return;
+        }
         if (urlPath === '/v1/models' && req.method === 'GET') {
             requestCount++;
             res.writeHead(200, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
@@ -1006,6 +1092,25 @@ export async function startProxy(opts = {}) {
             res.end(ERR_METHOD);
             return;
         }
+        // Overage-guard halt check (v4.1, dario#288). Subscribers should never
+        // see a single `representative-claim: overage` response during normal
+        // operation; one means traffic is being reclassified to per-token
+        // billing. Block upstream forwarding with a 503 + Anthropic-shaped
+        // error body until the user runs `dario resume` or the cooldown
+        // auto-expires. Health / status / analytics / admin endpoints above
+        // bypass this check intentionally — the TUI needs them to surface
+        // the halt and the user needs /admin/resume to clear it.
+        if (overageGuard.isHalted()) {
+            requestCount++;
+            const state = overageGuard.state();
+            writeLogLine(logFileStream, {
+                ts: new Date().toISOString(), req: requestCount,
+                method: req.method ?? '', path: urlPath, status: 503, reject: 'overage-halt',
+            });
+            res.writeHead(503, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
+            res.end(JSON.stringify(buildHaltErrorBody(state)));
+            return;
+        }
         // Proxy to Anthropic (with concurrency control). The bounded queue
         // replaces the v3.30.x-and-earlier unbounded semaphore — dario#80. A
         // queue-full condition returns an explicit 429 with a `"queue-full"`

package/dist/tui/proxy-client.d.ts

@@ -48,10 +48,53 @@ export declare class ProxyClient {
      * Auto-reconnect is intentionally NOT included. The Hits tab decides
      * when to retry (and how often) — pushing that policy into here would
      * couple the client to UI semantics.
+     *
+     * v4.1 (dario#288): the proxy emits named events alongside the default
+     * 'message' event — `event: overage_halt`, `event: overage_warn`,
+     * `event: overage_resume`. The `eventType` passed to `onMessage` is
+     * the value of the `event:` line on the frame (or `'message'` for an
+     * unlabeled / default frame). Existing consumers that pass a
+     * single-arg callback continue to work unchanged.
+     */
+    subscribeAnalyticsStream<T = unknown>(onMessage: (msg: T, eventType?: string) => void, onError?: (err: Error) => void): () => void;
+    /**
+     * Query the overage-guard state (v4.1, dario#288). Returns the current
+     * halt state + configuration. Returns null on any error so the Status
+     * tab can render "unknown" without crashing.
      */
-    subscribeAnalyticsStream<T = unknown>(onMessage: (msg: T) => void, onError?: (err: Error) => void): () => void;
+    getOverageGuard(): Promise<OverageGuardStatus | null>;
+    /**
+     * Clear the overage-guard halt state. POSTs /admin/resume. Returns the
+     * server's response (`wasHalted` indicates whether the call actually
+     * cleared a halt vs no-op'd on already-clear state).
+     */
+    resume(): Promise<{
+        ok: boolean;
+        wasHalted: boolean;
+        resumedAt: string;
+    }>;
     private headers;
 }
+export interface OverageGuardStatus {
+    halted: boolean;
+    state: {
+        since: number;
+        cooldownUntil: number;
+        reason: string;
+        request: {
+            timestamp: number;
+            model: string;
+            account: string;
+            claim: string;
+        };
+    } | null;
+    config: {
+        enabled: boolean;
+        behavior: 'halt' | 'warn';
+        cooldownMs: number;
+        notifyOs: boolean;
+    };
+}
 export interface HealthResponse {
     status: string;
     oauth: string;

package/dist/tui/proxy-client.js

@@ -86,6 +86,13 @@ export class ProxyClient {
      * Auto-reconnect is intentionally NOT included. The Hits tab decides
      * when to retry (and how often) — pushing that policy into here would
      * couple the client to UI semantics.
+     *
+     * v4.1 (dario#288): the proxy emits named events alongside the default
+     * 'message' event — `event: overage_halt`, `event: overage_warn`,
+     * `event: overage_resume`. The `eventType` passed to `onMessage` is
+     * the value of the `event:` line on the frame (or `'message'` for an
+     * unlabeled / default frame). Existing consumers that pass a
+     * single-arg callback continue to work unchanged.
      */
     subscribeAnalyticsStream(onMessage, onError) {
         const url = new URL(this.baseUrl + '/analytics/stream');
@@ -121,15 +128,19 @@ export class ProxyClient {
                 while ((idx = buf.indexOf('\n\n')) >= 0) {
                     const frame = buf.slice(0, idx);
                     buf = buf.slice(idx + 2);
-                    const dataLines = frame.split('\n')
+                    const lines = frame.split('\n');
+                    const dataLines = lines
                         .filter(l => l.startsWith('data:'))
                         .map(l => l.slice(5).replace(/^ /, ''));
                     if (dataLines.length === 0)
                         continue;
+                    // Pull the `event:` line if present. Default is 'message' per SSE spec.
+                    const eventLine = lines.find(l => l.startsWith('event:'));
+                    const eventType = eventLine ? eventLine.slice(6).trim() : 'message';
                     const payload = dataLines.join('\n');
                     try {
                         const parsed = JSON.parse(payload);
-                        onMessage(parsed);
+                        onMessage(parsed, eventType);
                     }
                     catch (e) {
                         onError?.(new Error(`SSE parse: ${e.message}`));
@@ -157,6 +168,59 @@ export class ProxyClient {
             catch { /* ignored */ }
         };
     }
+    /**
+     * Query the overage-guard state (v4.1, dario#288). Returns the current
+     * halt state + configuration. Returns null on any error so the Status
+     * tab can render "unknown" without crashing.
+     */
+    async getOverageGuard() {
+        try {
+            return await this.getJson('/admin/resume');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clear the overage-guard halt state. POSTs /admin/resume. Returns the
+     * server's response (`wasHalted` indicates whether the call actually
+     * cleared a halt vs no-op'd on already-clear state).
+     */
+    async resume() {
+        const url = new URL(this.baseUrl + '/admin/resume');
+        return new Promise((resolve, reject) => {
+            const req = httpRequest({
+                hostname: url.hostname,
+                port: url.port || 80,
+                path: url.pathname,
+                method: 'POST',
+                headers: { ...this.headers(), 'Content-Type': 'application/json', 'Content-Length': '2' },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                        reject(new Error(`HTTP ${res.statusCode}: ${body.slice(0, 200)}`));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(body));
+                    }
+                    catch (e) {
+                        reject(new Error(`JSON parse: ${e.message}`));
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.setTimeout(this.timeoutMs, () => {
+                req.destroy(new Error(`timeout after ${this.timeoutMs}ms`));
+            });
+            req.write('{}');
+            req.end();
+        });
+    }
     headers() {
         const h = {};
         if (this.apiKey)

package/dist/tui/tabs/analytics.js

@@ -102,6 +102,19 @@ export const AnalyticsTab = {
         lines.push('  ' + pad('7d', 6) +
             fg('cyan', progressBar(s.utilization.lastUtil7d, barWidth)) +
             '  ' + dim(`${(s.utilization.lastUtil7d * 100).toFixed(0)}%`));
+        // Overage bucket (v4.1, dario#288). Count of requests that landed in
+        // the overage bucket within the rolling window. Empty bar in normal
+        // operation; non-zero count renders in red. Hard zero IS the success
+        // signal here — anything else is "investigate immediately."
+        const overageCount = s.window.billingBucketBreakdown?.extra_usage ?? 0;
+        const totalCount = Object.values(s.window.billingBucketBreakdown ?? {}).reduce((a, b) => a + b, 0);
+        const overageFrac = totalCount > 0 ? overageCount / totalCount : 0;
+        const overageColor = overageCount > 0 ? 'red' : 'cyan';
+        lines.push('  ' + pad('Overage', 6) +
+            fg(overageColor, progressBar(overageFrac, barWidth)) +
+            '  ' + (overageCount > 0
+            ? fg('red', `${overageCount} req`) + dim(` of ${totalCount}`)
+            : dim('0  ← clean')));
         // ── Billing buckets ───────────────────────────────────────
         const buckets = s.window.billingBucketBreakdown;
         const totalBucketCount = Object.values(buckets).reduce((a, b) => a + b, 0);

package/dist/tui/tabs/config.js

@@ -38,6 +38,11 @@ const FIELDS = [
     { path: 'thinkTime.maxMs', label: 'Think-time cap (ms)', type: 'number', hint: 'upper bound for the whole formula' },
     { path: 'sessionStart.minMs', label: 'Session-start min', type: 'number', hint: 'first-request delay floor' },
     { path: 'sessionStart.jitterMs', label: 'Session-start jitter', type: 'number' },
+    // ── Overage-guard (v4.1, dario#288) ─────────────────────────
+    { path: 'overageGuard.enabled', label: 'Overage-guard', type: 'bool', hint: 'halt proxy on any representative-claim=overage' },
+    { path: 'overageGuard.behavior', label: 'Overage behavior', type: 'string', hint: '"halt" (default) or "warn"' },
+    { path: 'overageGuard.cooldownMs', label: 'Overage cooldown (ms)', type: 'number', hint: 'auto-resume delay; default 1800000 (30 min)' },
+    { path: 'overageGuard.notifyOs', label: 'Overage OS-notify', type: 'bool', hint: 'native desktop notification on halt' },
 ];
 export const ConfigTab = {
     id: 'config',
@@ -212,15 +217,45 @@ function commitEdit(state) {
             if (!Number.isFinite(n)) {
                 return { ...state, editBuffer: null, statusMessage: `Not a number: "${state.editBuffer}"`, statusKind: 'error' };
             }
+            // Path-specific guards. cooldownMs must be non-negative — silently
+            // dropping a bad value on next config-file load is correct but lets
+            // the user save an invalid file. Surface immediately. (v4.1.1)
+            if (f.path === 'overageGuard.cooldownMs' && n < 0) {
+                return { ...state, editBuffer: null, statusMessage: `overageGuard.cooldownMs must be >= 0 (got ${n})`, statusKind: 'error' };
+            }
             parsed = n;
         }
     }
+    else if (f.type === 'string') {
+        // String enums: validate so we reject bad input at commit time rather
+        // than let the proxy's sanitize() silently drop it on next load. v4.1.1
+        // adds the overageGuard.behavior enum; future enums register here.
+        const enumValues = STRING_ENUMS[f.path];
+        if (enumValues && !enumValues.includes(state.editBuffer)) {
+            return {
+                ...state,
+                editBuffer: null,
+                statusMessage: `${f.label} must be one of: ${enumValues.join(', ')} (got "${state.editBuffer}")`,
+                statusKind: 'error',
+            };
+        }
+        parsed = state.editBuffer;
+    }
     else {
         parsed = state.editBuffer;
     }
     const next = setByPath(state.config, f.path, parsed);
     return { ...state, config: next, editBuffer: null, statusMessage: `Updated ${f.label}.`, statusKind: 'success' };
 }
+/**
+ * Allowed values for string-enum fields. Keyed by FIELDS path. Anything
+ * absent here is treated as free-text (no enum validation). v4.1.1+ —
+ * additive: registering a new entry forces enum validation on the next
+ * commit without touching the rest of the editor.
+ */
+const STRING_ENUMS = {
+    'overageGuard.behavior': ['halt', 'warn'],
+};
 function doSave(state) {
     try {
         saveConfig(undefined, { ...state.config, version: CONFIG_SCHEMA_VERSION });

package/dist/tui/tabs/hits.d.ts

@@ -25,10 +25,24 @@
  */
 import type { Tab } from '../tab.js';
 import type { RequestRecord } from '../../analytics.js';
+/** Live overage-halt state — populated from SSE event:overage_halt frames. */
+interface HitsHaltState {
+    since: number;
+    cooldownUntil: number;
+    request: {
+        timestamp: number;
+        model: string;
+        account: string;
+        claim: string;
+    };
+}
 export interface HitsState {
     buffer: RequestRecord[];
     selectedIdx: number;
     subscribed: boolean;
     connectionError: string | null;
+    /** Overage-guard halt banner (v4.1, dario#288). Null when running normally. */
+    halt: HitsHaltState | null;
 }
 export declare const HitsTab: Tab<HitsState>;
+export {};