@askalf/dario 4.0.1 → 4.1.0

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',

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 {};

package/dist/tui/tabs/hits.js

@@ -32,13 +32,28 @@ export const HitsTab = {
     label: 'Hits',
     hotkey: 'h',
     initialState() {
-        return { buffer: [], selectedIdx: -1, subscribed: false, connectionError: null };
+        return { buffer: [], selectedIdx: -1, subscribed: false, connectionError: null, halt: null };
     },
     onMount(_state, ctx) {
         // Subscribe to the live stream. Each record is prepended-conceptually
         // (we push to the array and render in reverse, which keeps the
         // buffer's mutation simple — Array.push is O(1) while unshift is O(n)).
-        const close = ctx.client.subscribeAnalyticsStream((record) => {
+        //
+        // The same stream carries named events for overage-halt / -resume
+        // (v4.1, dario#288). The SSE event type is the second argument; we
+        // route on it.
+        const close = ctx.client.subscribeAnalyticsStream((payload, eventType) => {
+            if (eventType === 'overage_halt' || eventType === 'overage_warn') {
+                const state = payload;
+                ctx.setState((s) => ({ ...s, halt: state }));
+                return;
+            }
+            if (eventType === 'overage_resume') {
+                ctx.setState((s) => ({ ...s, halt: null }));
+                return;
+            }
+            // Default ('message') = RequestRecord
+            const record = payload;
             ctx.setState((s) => {
                 const next = {
                     ...s,
@@ -123,6 +138,16 @@ export const HitsTab = {
         const colIn = 8, colOut = 7, colLat = 7, colStatus = 5;
         lines.push(' ' + brand('Hits') +
             dim(`  ${state.buffer.length} buffered · ${state.subscribed ? fg('green', 'live') : fg('yellow', 'disconnected')}`));
+        // ── Overage-halt banner (v4.1, dario#288) ──────────────────
+        // Pinned at the top so it's always visible while scrolling the buffer.
+        if (state.halt) {
+            const since = formatTimestamp(state.halt.since);
+            const cooldown = formatRemaining(state.halt.cooldownUntil - Date.now());
+            const line1 = `  ${fg('red', '⚠ HALTED')}  overage detected at ${since} on ${state.halt.request.model}  (account=${state.halt.request.account})`;
+            const line2 = `  ${dim('→ New /v1/messages requests return 503 until')} ${fg('cyan', 'R')} ${dim('here, or')} ${fg('cyan', 'dario resume')}${dim(' from any shell. Auto-resume in')} ${cooldown}${dim('.')}`;
+            lines.push(line1);
+            lines.push(line2);
+        }
         lines.push('');
         // Header row (aligned with data rows)
         lines.push('  ' + dim(pad('time', colTime) +
@@ -133,7 +158,10 @@ export const HitsTab = {
             pad('st', colStatus)));
         for (let i = startIdx; i < endIdx; i++) {
             const r = newestFirst[i];
-            const marker = i === state.selectedIdx ? fg('cyan', '▎') : ' ';
+            const isOverage = r.claim === 'overage';
+            const marker = i === state.selectedIdx ? fg('cyan', '▎')
+                : isOverage ? fg('red', '!')
+                    : ' ';
             const row = marker + ' ' +
                 pad(formatTime(r.timestamp), colTime) +
                 pad(shortenModel(r.model), colModel) +
@@ -141,7 +169,16 @@ export const HitsTab = {
                 pad(formatTokens(r.outputTokens), colOut) +
                 pad(formatLatency(r.latencyMs), colLat) +
                 pad(formatStatus(r.status), colStatus);
-            lines.push(i === state.selectedIdx ? inverse(truncate(row, w - 2)) : truncate(row, w - 2));
+            // Overage rows render in red even when unselected; selection still
+            // wins via the inverse() wrapper so the user can drill into one.
+            let styled;
+            if (i === state.selectedIdx)
+                styled = inverse(truncate(row, w - 2));
+            else if (isOverage)
+                styled = fg('red', truncate(row, w - 2));
+            else
+                styled = truncate(row, w - 2);
+            lines.push(styled);
         }
         // Scroll hint
         if (newestFirst.length > listRows) {
@@ -221,3 +258,16 @@ function tokenBreakdown(r) {
         parts.push(`thinking ${r.thinkingTokens}`);
     return parts.join(' / ');
 }
+function formatTimestamp(ts) {
+    const d = new Date(ts);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+function formatRemaining(ms) {
+    if (ms <= 0)
+        return fg('yellow', 'now');
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    return m < 60 ? `${m}m ${s % 60}s` : `${Math.floor(m / 60)}h ${m % 60}m`;
+}

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

@@ -20,6 +20,7 @@
  *   └─────────────────────────────────────────────────┘
  */
 import type { Tab, TabContext } from '../tab.js';
+import type { OverageGuardStatus } from '../proxy-client.js';
 export interface StatusState {
     loading: boolean;
     /** Proxy /health response, or null if unreachable. */
@@ -31,6 +32,12 @@ export interface StatusState {
     } | null;
     /** Config-file load source: file | missing | invalid. */
     configSource: 'file' | 'missing' | 'invalid' | null;
+    /** Overage-guard state from /admin/resume — null if unreachable. */
+    overageGuard: OverageGuardStatus | null;
+    /** Transient: did we just attempt a manual resume? */
+    resumePending: boolean;
+    resumeMessage: string | null;
+    resumeKind: 'success' | 'info' | 'error' | null;
     /** Last refresh timestamp (ms). */
     lastRefreshAt: number;
     /** Error from the last refresh attempt, if any. */
@@ -43,3 +50,10 @@ export declare const StatusTab: Tab<StatusState>;
  * 'r' without re-running the full onMount flow.
  */
 export declare function refreshStatus(ctx: TabContext): Promise<StatusState>;
+/**
+ * Fire the manual-resume POST and update state. Called by TuiApp when the
+ * Status tab returns a state with resumePending=true (the `R` key path).
+ * Lives here next to refreshStatus so all status-tab-side-effects sit
+ * together.
+ */
+export declare function performResume(ctx: TabContext<StatusState>): Promise<Partial<StatusState>>;

package/dist/tui/tabs/status.js

@@ -30,6 +30,10 @@ export const StatusTab = {
             loading: true,
             health: null,
             configSource: null,
+            overageGuard: null,
+            resumePending: false,
+            resumeMessage: null,
+            resumeKind: null,
             lastRefreshAt: 0,
             error: null,
         };
@@ -37,12 +41,40 @@ export const StatusTab = {
     async onMount(_state, ctx) {
         return refreshStatus(ctx);
     },
+    onTick(state, ctx) {
+        // Drive the async side-effects that onKey can't fire directly.
+        if (state.resumePending) {
+            void performResume(ctx).then((delta) => ctx.setState(delta));
+            return;
+        }
+        // Poll the overage-guard state every 2s so the halt countdown stays
+        // current without the user having to press `r`. Cheap GET; the proxy
+        // is on loopback. Skip when the rest of the status is still loading.
+        if (!state.loading && state.overageGuard !== null && state.overageGuard.halted) {
+            // While halted, refresh every 2s so the countdown updates.
+            const since = Date.now() - state.lastRefreshAt;
+            if (since >= 2000) {
+                void ctx.client.getOverageGuard().then((g) => {
+                    if (g)
+                        ctx.setState({ overageGuard: g, lastRefreshAt: Date.now() });
+                });
+            }
+        }
+    },
     onKey(state, key) {
-        // `r` triggers a manual refresh by signaling the parent to call
-        // onMount again. The parent watches for a sentinel state.
+        // `r` triggers a manual refresh — signal the parent to call onMount again.
         if (key.name === 'printable' && key.ch === 'r' && !key.ctrl) {
             return { ...state, loading: true };
         }
+        // `R` (shift-r) resumes the overage-guard halt state when one is active.
+        // Returning a sentinel state with resumePending=true signals the parent
+        // to fire the async resume() call.
+        if (key.name === 'printable' && key.ch === 'R' && !key.ctrl) {
+            if (state.overageGuard?.halted) {
+                return { ...state, resumePending: true, resumeMessage: 'Resuming…', resumeKind: 'info' };
+            }
+            return { ...state, resumeMessage: 'Nothing to resume — proxy is not halted.', resumeKind: 'info' };
+        }
         return undefined;
     },
     render(state, dim_) {
@@ -75,12 +107,52 @@ export const StatusTab = {
                     : dim('not loaded');
         lines.push('  ' + renderKvRow('Source', sourceLabel, w - 4));
         lines.push('');
+        // ── Overage-guard section (v4.1, dario#288) ────────────────
+        if (state.overageGuard) {
+            lines.push(' ' + brand('Overage-guard'));
+            if (state.overageGuard.halted && state.overageGuard.state) {
+                const s = state.overageGuard.state;
+                const remainingMs = Math.max(0, s.cooldownUntil - Date.now());
+                const remaining = formatDuration(remainingMs);
+                // Red banner header — this is the loud surface when halted
+                lines.push('  ' + fg('red', '⚠ HALTED') + '  ' + dim(`overage detected ${formatAgo(s.since)} ago`));
+                lines.push('  ' + renderKvRow('Request', `${s.request.model}  ${dim('account=' + s.request.account)}`, w - 4));
+                lines.push('  ' + renderKvRow('Cause', `representative-claim = ${fg('red', s.request.claim)}`, w - 4));
+                lines.push('  ' + renderKvRow('Auto-resume in', remaining === '0s' ? fg('yellow', 'now (cooldown elapsed)') : remaining, w - 4));
+                lines.push('  ' + renderKvRow('Manual resume', `press ${fg('cyan', 'R')} here, or ${fg('cyan', 'dario resume')} from any shell`, w - 4));
+            }
+            else {
+                lines.push('  ' + renderKvRow('State', fg('green', 'normal'), w - 4));
+                const cfg = state.overageGuard.config;
+                lines.push('  ' + renderKvRow('Mode', `${cfg.enabled ? fg('green', 'enabled') : fg('yellow', 'disabled')}  ${dim(`behavior=${cfg.behavior}  cooldown=${formatDuration(cfg.cooldownMs)}`)}`, w - 4));
+            }
+            if (state.resumeMessage) {
+                const c = state.resumeKind === 'error' ? 'red' : state.resumeKind === 'success' ? 'green' : 'cyan';
+                lines.push('  ' + fg(c, state.resumeMessage));
+            }
+            lines.push('');
+        }
         // ── Footer hint ────────────────────────────────────────────
         lines.push('');
-        lines.push(' ' + dim(`Last refresh: ${formatAgo(state.lastRefreshAt)}. Press ${fg('cyan', 'r')} to refresh.`));
+        const resumeHint = state.overageGuard?.halted ? ` · ${fg('cyan', 'R')} resume` : '';
+        lines.push(' ' + dim(`Last refresh: ${formatAgo(state.lastRefreshAt)}. ${fg('cyan', 'r')} refresh${resumeHint}.`));
         return lines.join('\n');
     },
 };
+function formatDuration(ms) {
+    if (ms <= 0)
+        return '0s';
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rs = s % 60;
+    if (m < 60)
+        return rs > 0 ? `${m}m ${rs}s` : `${m}m`;
+    const h = Math.floor(m / 60);
+    const rm = m % 60;
+    return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
+}
 /**
  * Refresh the Status tab's data — probe /health, load config file
  * metadata. Exported separately so the parent can re-invoke on key
@@ -98,14 +170,48 @@ export async function refreshStatus(ctx) {
     catch (e) {
         error = e.message;
     }
+    // Overage-guard state — best-effort; never throws (proxy-client wraps the
+    // GET in try/catch and returns null). Surface as 'unknown' when null.
+    const overageGuard = await ctx.client.getOverageGuard();
     return {
         loading: false,
         health,
         configSource: fileResult.source,
+        overageGuard,
+        resumePending: false,
+        resumeMessage: null,
+        resumeKind: null,
         lastRefreshAt: Date.now(),
         error,
     };
 }
+/**
+ * Fire the manual-resume POST and update state. Called by TuiApp when the
+ * Status tab returns a state with resumePending=true (the `R` key path).
+ * Lives here next to refreshStatus so all status-tab-side-effects sit
+ * together.
+ */
+export async function performResume(ctx) {
+    try {
+        const result = await ctx.client.resume();
+        const refreshed = await ctx.client.getOverageGuard();
+        return {
+            overageGuard: refreshed,
+            resumePending: false,
+            resumeMessage: result.wasHalted
+                ? `Resumed at ${result.resumedAt}.`
+                : 'Already running normally — no-op.',
+            resumeKind: 'success',
+        };
+    }
+    catch (e) {
+        return {
+            resumePending: false,
+            resumeMessage: `Resume failed: ${e.message}`,
+            resumeKind: 'error',
+        };
+    }
+}
 function formatOauth(label, expiresIn) {
     if (label === 'healthy') {
         return fg('green', expiresIn ? `healthy (expires in ${expiresIn})` : 'healthy');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {