limn-review 0.1.135 → 0.1.136

package/dist/ai/budget.js

@@ -0,0 +1,495 @@
+// THE CLAUDE SPEND BUDGET — the ONE decision and the ONE gate (packages/shared ai-budget.ts holds
+// the types, the defaults, the subscription rule and the estimate table).
+//
+//   decideAiBudget(input)          PURE. Settings + credential route + the latest usage reading +
+//                                  Limn's own recorded spend (ai_usage) + its typical cycle cost →
+//                                  AiBudgetStatus.
+//   aiBudgetStatus(accountId)      gathers those inputs (and, when useful, runs the cached usage
+//                                  probe) and calls decideAiBudget. Never throws.
+//   allowAutomaticRun(accountId)   THE GATE. Every AUTOMATIC model run asks it first (auto review and
+//                                  its thread checks, auto fix, the CI and ticket review sweepers,
+//                                  the post-review diagrams, the sprint after-read chain, the Slack
+//                                  digest's sprint summary). Over budget ⇒ the run is SKIPPED, not
+//                                  queued: the sweepers re-derive what is due every tick, so it
+//                                  becomes due again by itself once the week resets.
+//                                  Logged once per pause, never per tick.
+//
+// A run the READER starts is never refused here — the SPA reads GET /api/ai/budget and asks for a
+// second press.
+//
+// SUBSCRIPTION: Limn's SHARE of the week = its own ai_usage spend in the current week ÷ the
+// subscription's estimated weekly allowance (SUBSCRIPTION_ESTIMATES); likewise of the 5-hour session
+// (the setting follows the weekly share unless the reader set its own). Over when EITHER share reaches
+// its setting. Each window is [reset − length, reset) when Claude's reset has been read and is still
+// ahead, otherwise rolling. The pure rules live in packages/shared (`decideAiBudget`, `aiUsageView`)
+// so the static demo runs the same ones; the status carries percentages only.
+//
+// THE USAGE READING (login route only) gives the subscription type, the reset times and the header's
+// account-wide figures — it never blocks. Two sources fold into ONE latest reading, kept in memory and
+// persisted on `accounts.ai_budget_reading` so a restart keeps it:
+//   • every agent run's `rate_limit_event` (ai/runtime.ts taps every Query): the 5-hour, weekly and
+//     per-model weekly windows' resets and utilisation — a 0–1 FRACTION on this path (the CLI's
+//     header parsing), converted to 0–100 HERE, explicitly;
+//   • a cheap probe through the Agent SDK's EXPERIMENTAL usage method (login route, at most every
+//     PROBE_MIN_INTERVAL_MS, a 20s timeout, in the BACKGROUND — a request never waits for it): the
+//     subscription type and every window, utilisation ALREADY 0–100 (measured on a real login) and
+//     kept as-is. A failure keeps the last reading.
+// There is no shared "≤ 1 means a fraction" guess: each path knows its own scale. Any throw or shape
+// mismatch is "no reading" — the windows are then rolling and the subscription is the reader's pick.
+//
+// One budget per ACCOUNT (= per machine), never per workspace.
+import { and, eq, gte, inArray } from 'drizzle-orm';
+import { AI_BUDGET_DAY_MS, AI_BUDGET_WEEK_MS, aiUsageView, decideAiBudget, liveFiveHourReset, liveWeekReset, resolveAiBudgetSettings, rollingSpend, } from '../shared/index.js';
+import { db, schema } from '../db/client.js';
+import { LOCAL_ACCOUNT_ID } from '../auth/account.js';
+import { resolveAiCredential, agentAuthOptions } from './credentials.js';
+import { ISOLATED_MCP } from './agent-isolation.js';
+import { claudeExecutableOptions, getAiRuntimeStatus, loadAgentSdk, setAgentMessageObserver, } from './runtime.js';
+export const DAY_MS = AI_BUDGET_DAY_MS;
+export const WEEK_MS = AI_BUDGET_WEEK_MS;
+/** The window "typical cycle cost" is averaged over. */
+export const CYCLE_COST_WINDOW_MS = 28 * DAY_MS;
+/** The usage probe runs at most this often (the header polls every ~2 minutes while visible). */
+export const PROBE_MIN_INTERVAL_MS = 5 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 20_000;
+/** At most this many per-model windows are kept from one reading. */
+const MAX_MODEL_WINDOWS = 8;
+export { decideAiBudget, rollingSpend, liveWeekReset, liveFiveHourReset, aiUsageView };
+// ---- folding the SDK's usage reports (pure) ---------------------------------------------------
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** Epoch seconds or ms → ms. */
+function epochMs(v) {
+    const n = num(v);
+    if (n == null || n <= 0)
+        return null;
+    return n < 1e12 ? n * 1000 : n;
+}
+/** A `rate_limit_event` utilisation is a 0–1 FRACTION (the CLI parses it from the rate-limit header):
+ *  → 0–100, explicitly. Out of range or not a number → null. */
+function eventFractionToPct(v) {
+    const n = num(v);
+    if (n == null || n < 0 || n > 1.5)
+        return null;
+    return n * 100;
+}
+/** Claude's window keys this module keeps: the 5-hour, the week, and per-model weeks. */
+const MODEL_WINDOW_KEY = /^seven_day_[a-z0-9_]{1,40}$/;
+/** Put one window into a reading under Claude's key. Unknown keys are ignored. Pure. */
+function withWindow(reading, key, w) {
+    if (key === 'five_hour')
+        return { ...reading, fiveHour: w };
+    if (key === 'seven_day')
+        return { ...reading, week: w };
+    if (MODEL_WINDOW_KEY.test(key)) {
+        const models = { ...(reading.models ?? {}) };
+        if (!(key in models) && Object.keys(models).length >= MAX_MODEL_WINDOWS)
+            return reading;
+        models[key] = w;
+        return { ...reading, models };
+    }
+    return reading;
+}
+const isWindowKey = (k) => k === 'five_hour' || k === 'seven_day' || MODEL_WINDOW_KEY.test(k);
+/**
+ * Fold one Agent SDK message into the reading. Returns the NEW reading (the windows this message names
+ * merged over the rest), or null when the message names none. Pure.
+ *
+ * Reads `rate_limit_event.rate_limit_info`: every window in `unifiedWindows` (when the CLI sends
+ * them) and otherwise the one named by `rateLimitType` ('five_hour', 'seven_day', 'seven_day_opus',
+ * …). Reset times arrive in epoch seconds. Utilisation is a fraction on this path.
+ */
+export function foldRateLimitEvent(reading, message, nowMs) {
+    if (!message || typeof message !== 'object')
+        return null;
+    const m = message;
+    if (m.type !== 'rate_limit_event' || !m.rate_limit_info || typeof m.rate_limit_info !== 'object')
+        return null;
+    const info = m.rate_limit_info;
+    const unified = info.unifiedWindows && typeof info.unifiedWindows === 'object'
+        ? info.unifiedWindows
+        : null;
+    const sources = [];
+    if (unified) {
+        for (const [k, v] of Object.entries(unified)) {
+            if (isWindowKey(k) && v && typeof v === 'object')
+                sources.push([k, v]);
+        }
+    }
+    else if (typeof info.rateLimitType === 'string' && isWindowKey(info.rateLimitType)) {
+        sources.push([info.rateLimitType, info]);
+    }
+    let out = {};
+    let any = false;
+    for (const [key, src] of sources) {
+        let utilization = eventFractionToPct(src.utilization);
+        if (utilization == null && src.status === 'rejected')
+            utilization = 100;
+        const resetsAtMs = epochMs(src.resetsAt);
+        if (utilization == null && resetsAtMs == null)
+            continue;
+        out = withWindow(out, key, { utilization, resetsAtMs, observedAtMs: nowMs });
+        any = true;
+    }
+    return any ? mergeReadings(reading, out) : null;
+}
+/** Parse the experimental usage method's answer. Its utilisation is ALREADY 0–100 (measured on a
+ *  real login: `seven_day.utilization: 31`) and is kept as-is. Null on any shape mismatch. Pure. */
+export function parseUsageProbe(resp, nowMs) {
+    if (!resp || typeof resp !== 'object')
+        return null;
+    const r = resp;
+    const subscriptionType = typeof r.subscription_type === 'string' && r.subscription_type !== '' ? r.subscription_type : null;
+    let out = {};
+    let any = false;
+    if (r.rate_limits_available === true && r.rate_limits && typeof r.rate_limits === 'object') {
+        for (const [key, v] of Object.entries(r.rate_limits)) {
+            if (!isWindowKey(key) || !v || typeof v !== 'object')
+                continue;
+            const o = v;
+            const u = num(o.utilization);
+            const t = typeof o.resets_at === 'string' ? Date.parse(o.resets_at) : NaN;
+            const utilization = u != null && u >= 0 && u <= 150 ? u : null;
+            const resetsAtMs = Number.isFinite(t) ? t : null;
+            if (utilization == null && resetsAtMs == null)
+                continue;
+            out = withWindow(out, key, { utilization, resetsAtMs, observedAtMs: nowMs });
+            any = true;
+        }
+    }
+    if (!any && subscriptionType == null)
+        return null;
+    return { ...out, subscriptionType };
+}
+function storedWindow(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const w = v;
+    const observedAtMs = num(w.observedAtMs);
+    return observedAtMs == null ? null : { utilization: num(w.utilization), resetsAtMs: num(w.resetsAtMs), observedAtMs };
+}
+/** A stored reading of any age → today's shape. Never throws. */
+export function normaliseStoredReading(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const week = storedWindow(r.week);
+    const fiveHour = storedWindow(r.fiveHour);
+    let models = null;
+    if (r.models && typeof r.models === 'object') {
+        for (const [k, v] of Object.entries(r.models).slice(0, MAX_MODEL_WINDOWS)) {
+            const w = MODEL_WINDOW_KEY.test(k) ? storedWindow(v) : null;
+            if (w)
+                (models ??= {})[k] = w;
+        }
+    }
+    const subscriptionType = typeof r.subscriptionType === 'string' ? r.subscriptionType : null;
+    if (week == null && fiveHour == null && models == null && subscriptionType == null)
+        return null;
+    return { week, fiveHour, models, subscriptionType };
+}
+// ---- the reading: memory + persistence --------------------------------------------------------
+let memReading; // undefined = not loaded yet
+async function loadReading() {
+    if (memReading !== undefined)
+        return memReading;
+    try {
+        const rows = await db
+            .select({ r: schema.accounts.aiBudgetReading })
+            .from(schema.accounts)
+            .where(eq(schema.accounts.id, LOCAL_ACCOUNT_ID))
+            .limit(1)
+            .execute();
+        memReading = normaliseStoredReading(rows[0]?.r);
+    }
+    catch {
+        memReading = null;
+    }
+    return memReading;
+}
+/** One window merged: the new one wins, but keeps the known reset when it read none. */
+function mergeWindow(prev, next) {
+    if (next == null)
+        return prev ?? null;
+    if (next.resetsAtMs == null && prev?.resetsAtMs != null)
+        return { ...next, resetsAtMs: prev.resetsAtMs };
+    return next;
+}
+/** Merge two readings (pure): each window independently; what `next` does not mention is kept (an
+ *  event never names the subscription, and names one or two windows). */
+export function mergeReadings(prev, next) {
+    const models = { ...(prev?.models ?? {}) };
+    for (const [k, w] of Object.entries(next.models ?? {})) {
+        const merged = mergeWindow(models[k], w);
+        if (merged && (k in models || Object.keys(models).length < MAX_MODEL_WINDOWS))
+            models[k] = merged;
+    }
+    return {
+        week: mergeWindow(prev?.week, next.week),
+        fiveHour: mergeWindow(prev?.fiveHour, next.fiveHour),
+        models: Object.keys(models).length === 0 ? null : models,
+        subscriptionType: next.subscriptionType ?? prev?.subscriptionType ?? null,
+    };
+}
+function storeReading(next) {
+    memReading = mergeReadings(memReading ?? null, next);
+    const value = memReading;
+    void db
+        .update(schema.accounts)
+        .set({ aiBudgetReading: value })
+        .where(eq(schema.accounts.id, LOCAL_ACCOUNT_ID))
+        .execute()
+        .catch(() => {
+        /* in memory still; the next reading tries again */
+    });
+}
+/** The observer ai/runtime.ts calls with every agent message. */
+export function noteAgentMessage(message, nowMs = Date.now()) {
+    const next = foldRateLimitEvent(null, message, nowMs);
+    if (next == null)
+        return;
+    // ⚠ Merge over the PERSISTED reading, never over "not loaded yet": a run's event arriving before
+    // the boot load finished would otherwise overwrite the stored subscription type and the other
+    // windows (storeReading merges `next` over what is in memory).
+    if (memReading === undefined) {
+        void loadReading().then(() => storeReading(next));
+        return;
+    }
+    storeReading(next);
+}
+/** Install the observer. Called once at boot when AI is on. */
+export function installAiBudgetObserver() {
+    void loadReading();
+    setAgentMessageObserver((m) => noteAgentMessage(m));
+}
+// ---- the usage probe ----------------------------------------------------------------------------
+let lastProbeAtMs = 0;
+let probeInFlight = null;
+/** Ask the Agent SDK's experimental usage method. Spawns the CLI with an empty input stream (no model
+ *  call), asks, closes. Throws on anything unexpected; the caller swallows. */
+const sdkUsageProbe = async () => {
+    const sdk = await loadAgentSdk();
+    let release = () => { };
+    const held = new Promise((r) => {
+        release = r;
+    });
+    // An input stream that never yields a turn: the CLI starts, answers control requests, and spends
+    // nothing.
+    async function* noTurns() {
+        await held;
+    }
+    const q = sdk.query({
+        prompt: noTurns(),
+        options: {
+            allowedTools: [],
+            settingSources: [],
+            ...ISOLATED_MCP,
+            ...claudeExecutableOptions(),
+            ...agentAuthOptions(),
+        },
+    });
+    try {
+        const method = q
+            .usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET;
+        if (typeof method !== 'function')
+            throw new Error('usage method not available');
+        let timer;
+        try {
+            return await Promise.race([
+                method.call(q, { skipBehaviors: true }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('usage probe timed out')), PROBE_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    finally {
+        release();
+        try {
+            q.close?.();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+};
+let probeImpl = sdkUsageProbe;
+/** Test hook. */
+export function _setUsageProbeForTest(p) {
+    probeImpl = p ?? sdkUsageProbe;
+    lastProbeAtMs = 0;
+    probeInFlight = null;
+}
+/** Test hook. */
+export function _resetAiBudgetForTest() {
+    memReading = undefined;
+    lastProbeAtMs = 0;
+    probeInFlight = null;
+    pausedAccounts.clear();
+}
+/** Start the probe IN THE BACKGROUND when it can help: login route (the caller checks), runtime
+ *  ready, not run in the last PROBE_MIN_INTERVAL_MS. Single-flight. Never throws, never awaited by a
+ *  request: the caller serves the cached reading. Returns the in-flight promise for tests. */
+export function kickUsageProbe(nowMs = Date.now()) {
+    if (probeInFlight)
+        return probeInFlight;
+    if (nowMs - lastProbeAtMs < PROBE_MIN_INTERVAL_MS)
+        return null;
+    if (probeImpl === sdkUsageProbe && getAiRuntimeStatus().runtime !== 'ready')
+        return null;
+    lastProbeAtMs = nowMs;
+    probeInFlight = (async () => {
+        try {
+            await loadReading();
+            const parsed = parseUsageProbe(await probeImpl(), Date.now());
+            if (parsed)
+                storeReading(parsed);
+        }
+        catch {
+            /* no reading — the last one stays */
+        }
+        finally {
+            probeInFlight = null;
+        }
+    })();
+    return probeInFlight;
+}
+// ---- settings -----------------------------------------------------------------------------------
+export async function readAiBudgetSettings(accountId) {
+    const rows = await db
+        .select({ s: schema.accounts.aiBudgetSettings })
+        .from(schema.accounts)
+        .where(eq(schema.accounts.id, accountId))
+        .limit(1)
+        .execute();
+    const raw = rows[0]?.s ?? null;
+    return { settings: resolveAiBudgetSettings(raw), isDefault: raw == null };
+}
+/** Merge a VALIDATED body over the stored settings and store the whole resolved object. */
+export async function writeAiBudgetSettings(accountId, body) {
+    const { settings: current } = await readAiBudgetSettings(accountId);
+    const next = resolveAiBudgetSettings({ ...current, ...body });
+    await db
+        .update(schema.accounts)
+        .set({ aiBudgetSettings: next })
+        .where(eq(schema.accounts.id, accountId))
+        .execute();
+    return next;
+}
+// ---- the status and the gate ----------------------------------------------------------------------
+async function readLedger(accountId, sinceMs) {
+    const { aiUsage } = schema;
+    const rows = await db
+        .select({ at: aiUsage.occurredAt, usd: aiUsage.costUsd, inTok: aiUsage.inputTokens, outTok: aiUsage.outputTokens })
+        .from(aiUsage)
+        .where(and(eq(aiUsage.accountId, accountId), gte(aiUsage.occurredAt, new Date(sinceMs))))
+        .execute();
+    return rows.map((r) => ({
+        atMs: r.at.getTime(),
+        usd: Number(r.usd) || 0,
+        inputTokens: r.inTok ?? null,
+        outputTokens: r.outTok ?? null,
+    }));
+}
+/** The account's typical automatic-review cycle: the mean recorded cost of a Claude review and of a
+ *  diagram run over the last 28 days, and whether any of its workspaces draws diagrams by itself. */
+export async function readCycleCosts(accountId, nowMs) {
+    const { aiUsage, workspaces } = schema;
+    const [rows, ws] = await Promise.all([
+        db
+            .select({ feature: aiUsage.feature, usd: aiUsage.costUsd })
+            .from(aiUsage)
+            .where(and(eq(aiUsage.accountId, accountId), inArray(aiUsage.feature, ['claude_review', 'sequence_diagram']), gte(aiUsage.occurredAt, new Date(nowMs - CYCLE_COST_WINDOW_MS))))
+            .execute(),
+        db
+            .select({ id: workspaces.id })
+            .from(workspaces)
+            .where(and(eq(workspaces.accountId, accountId), eq(workspaces.autoDiagramsEnabled, true)))
+            .limit(1)
+            .execute(),
+    ]);
+    const mean = (feature) => {
+        const xs = rows.filter((r) => r.feature === feature).map((r) => Number(r.usd)).filter((n) => Number.isFinite(n));
+        return xs.length === 0 ? null : xs.reduce((a, b) => a + b, 0) / xs.length;
+    };
+    return { reviewMeanUsd: mean('claude_review'), diagramMeanUsd: mean('sequence_diagram'), autoDiagrams: ws.length > 0 };
+}
+const NO_CYCLE_COSTS = { reviewMeanUsd: null, diagramMeanUsd: null, autoDiagrams: false };
+const OFF_STATUS = (route) => ({
+    enabled: false,
+    mode: 'off',
+    route,
+    subscription: null,
+    apiKey: null,
+    overBudget: false,
+    limitedBy: null,
+    reason: null,
+    resumesAt: null,
+});
+/** Local midnight on this machine (the server IS the reader's machine), for "today". */
+function localMidnightMs(nowMs) {
+    const d = new Date(nowMs);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+/**
+ * Everything GET /api/ai/budget returns, from ONE set of reads: the settings, the decision and the
+ * header's usage view. Serves the CACHED reading; the probe (when asked) refreshes it in the
+ * background for the next call.
+ */
+export async function aiBudgetSnapshot(accountId, opts = {}) {
+    const nowMs = opts.nowMs ?? Date.now();
+    const route = resolveAiCredential().route;
+    const { settings, isDefault } = await readAiBudgetSettings(accountId);
+    const probe = opts.probe ?? 'when_on';
+    if (route === 'login' && (probe === 'always' || (probe === 'when_on' && settings.enabled)))
+        kickUsageProbe(nowMs);
+    const [reading, ledger, costs] = await Promise.all([
+        route === 'login' ? loadReading() : Promise.resolve(null),
+        readLedger(accountId, Math.min(nowMs - WEEK_MS, localMidnightMs(nowMs))),
+        settings.enabled && route === 'login' ? readCycleCosts(accountId, nowMs) : Promise.resolve(NO_CYCLE_COSTS),
+    ]);
+    return {
+        settings,
+        isDefault,
+        status: decideAiBudget({ settings, route, reading, ledger, costs, nowMs }),
+        usage: aiUsageView({ settings, route, reading, ledger, nowMs, todayFromMs: localMidnightMs(nowMs) }),
+    };
+}
+/** The budget's status for an account. Never throws: a failed read is "off" (never blocks). */
+export async function aiBudgetStatus(accountId, opts = {}) {
+    try {
+        return (await aiBudgetSnapshot(accountId, opts)).status;
+    }
+    catch {
+        return OFF_STATUS(resolveAiCredential().route);
+    }
+}
+// account → when its current pause was first logged (log once per pause).
+const pausedAccounts = new Map();
+/**
+ * THE GATE before every AUTOMATIC model run. True ⇒ go. False ⇒ skip this run (do not queue it);
+ * the caller's next tick asks again. `what` names the run for the one log line.
+ */
+export async function allowAutomaticRun(accountId, what, log, statusOf = (a) => aiBudgetStatus(a)) {
+    const status = await statusOf(accountId);
+    if (!status.overBudget) {
+        if (pausedAccounts.delete(accountId))
+            log?.info('claude budget: back under the limit, automatic runs resume');
+        return true;
+    }
+    if (!pausedAccounts.has(accountId)) {
+        pausedAccounts.set(accountId, Date.now());
+        log?.info(`claude budget: automatic runs paused (${what} skipped)${status.resumesAt ? `; resumes about ${status.resumesAt}` : ''}`);
+    }
+    return false;
+}
+export function buildAiBudgetGate(log) {
+    return { allowAutomaticRun: (accountId, what) => allowAutomaticRun(accountId, what, log) };
+}
+//# sourceMappingURL=budget.js.map

package/dist/ai/runtime.js

@@ -548,7 +548,52 @@ export function installAiRuntime(onProgress, opts) {
 export function aiRuntimePins() {
     return runtime.pins();
 }
-export const loadAgentSdk = () => runtime.load('@anthropic-ai/claude-agent-sdk');
+export const loadAgentSdk = async () => tapAgentSdk(await runtime.load('@anthropic-ai/claude-agent-sdk'));
+let agentMessageObserver = null;
+/** Install (or clear) the one observer every agent run's messages pass through. */
+export function setAgentMessageObserver(fn) {
+    agentMessageObserver = fn;
+}
+function observe(message) {
+    if (!agentMessageObserver)
+        return;
+    try {
+        agentMessageObserver(message);
+    }
+    catch {
+        /* never into the run */
+    }
+}
+/** Wrap a Query (an AsyncGenerator with extra methods) so each yielded message is observed. */
+export function tapQuery(q) {
+    const proxy = new Proxy(q, {
+        get(target, prop) {
+            if (prop === 'next') {
+                return async (...args) => {
+                    const r = await target.next(...args);
+                    if (!r.done)
+                        observe(r.value);
+                    return r;
+                };
+            }
+            if (prop === Symbol.asyncIterator)
+                return () => proxy;
+            const v = Reflect.get(target, prop, target);
+            return typeof v === 'function' ? v.bind(target) : v;
+        },
+    });
+    return proxy;
+}
+const tappedSdks = new WeakMap();
+function tapAgentSdk(mod) {
+    const hit = tappedSdks.get(mod);
+    if (hit)
+        return hit;
+    const query = ((params) => tapQuery(mod.query(params)));
+    const tapped = { ...mod, query };
+    tappedSdks.set(mod, tapped);
+    return tapped;
+}
 export const loadAnthropicSdk = () => runtime.load('@anthropic-ai/sdk');
 export const loadMcpSdk = () => runtime.load('@modelcontextprotocol/sdk');
 export const loadZodModule = () => runtime.load('zod');

package/dist/api/plugins/rate-limit.js

@@ -65,6 +65,13 @@ function tierFor(method, path) {
     // over the user's own bandwidth, single-flight in ml/runtime.ts), the same bucket, spelled exactly.
     if (path === '/api/ml/install')
         return [TIERS.sync];
+    // THE CLAUDE SPEND BUDGET: GET/PUT /api/ai/budget (ai/budget.ts). FOLLOWING THE TOKEN: no model
+    // call and no GitHub call. The PUT is one validated UPDATE of one column; the GET (the header's usage
+    // item polls it every ~2 minutes) reads the ledger and may START the usage probe in the background,
+    // which is single-flight and at most once per 5 minutes inside ai/budget.ts — a loop cannot
+    // multiply it. `read`, decided rather than inherited; EXACT `===`. No other usage route exists.
+    if (path === '/api/ai/budget')
+        return [TIERS.read];
     // ---- Workspace CRUD: `read`, RECORDED rather than inherited ----
     //
     // The six surviving routes (list / create / rename+reassign / delete / move-one-repo-in /

package/dist/api/routes/ai-budget.js

@@ -0,0 +1,36 @@
+import { aiBudgetSettingsView, validateAiBudgetBody, } from '../../shared/index.js';
+import { config } from '../../config.js';
+import { accountIdOf } from '../plugins/auth.js';
+import { aiBudgetSnapshot, installAiBudgetObserver, writeAiBudgetSettings } from '../../ai/budget.js';
+// THE CLAUDE SPEND BUDGET (ai/budget.ts; types in packages/shared ai-budget.ts).
+//
+//   GET /api/ai/budget   → AiBudgetResponse: the settings (defaults filled in; `weeklyUsd` null off
+//                          the API-key route), whether anything is stored, the ONE decision
+//                          (`status`) and the header's usage view (`usage`). Serves the CACHED usage
+//                          reading and, on the login route, starts the usage probe IN THE BACKGROUND
+//                          (at most every 5 minutes, 20s timeout, no model call) — it never waits.
+//                          The header polls it every ~2 minutes while the tab is visible.
+//   PUT /api/ai/budget   AiBudgetBody (any subset; validated) → AiBudgetResponse.
+//
+// Registered only when `config.aiEnabled`. Registering it also installs the message observer every
+// agent run's `rate_limit_event`s pass through, so the reading exists before anyone opens Settings.
+export async function aiBudgetRoutes(app) {
+    if (!config.aiEnabled)
+        return;
+    installAiBudgetObserver();
+    const respond = async (accountId) => {
+        const { settings, isDefault, status, usage } = await aiBudgetSnapshot(accountId, { probe: 'always' });
+        // A subscription carries no US$ on the wire: the API key's weekly figure is sent only on that route.
+        return { settings: aiBudgetSettingsView(settings, status.route), isDefault, status, usage };
+    };
+    app.get('/api/ai/budget', async (req) => respond(accountIdOf(req)));
+    app.put('/api/ai/budget', async (req, reply) => {
+        const accountId = accountIdOf(req);
+        const problem = validateAiBudgetBody(req.body);
+        if (problem != null)
+            return reply.code(400).send({ error: 'InvalidAiBudget', message: problem });
+        await writeAiBudgetSettings(accountId, req.body);
+        return respond(accountId);
+    });
+}
+//# sourceMappingURL=ai-budget.js.map

package/dist/app.js

@@ -8,6 +8,7 @@ import { corsOriginDelegate, registerCrossOriginGuard, registerHostGuard, regist
 import { registerRateLimit } from './api/plugins/rate-limit.js';
 import { healthRoutes } from './api/routes/health.js';
 import { aiRuntimeRoutes } from './api/routes/ai-runtime.js';
+import { aiBudgetRoutes } from './api/routes/ai-budget.js';
 import { mlRuntimeRoutes } from './api/routes/ml-runtime.js';
 import { registerAgenticRoutes } from './review/agentic.js';
 import { registerTracker } from './tracker/index.js';
@@ -200,6 +201,10 @@ export async function buildApp() {
     // LIMN_AI_DISABLED.
     if (config.aiEnabled)
         await app.register(aiRuntimeRoutes);
+    // The Claude spend budget (ai/budget.ts): GET/PUT /api/ai/budget. Not registered under
+    // LIMN_AI_DISABLED.
+    if (config.aiEnabled)
+        await app.register(aiBudgetRoutes);
     // "Set up" for local bot-comment scoring (ml/runtime.ts). Not registered under LIMN_ML_DISABLED.
     if (config.mlLocalEnabled)
         await app.register(mlRuntimeRoutes);

package/dist/coding/ai-fix/auto-fix.js

@@ -48,6 +48,7 @@ import { isFixRunning, loadReviewSeed, startReviewFix } from './manager.js';
 import { parseChangeReport, parseReviewItems } from './persist.js';
 import { getFixPrContext } from './pr-context.js';
 import { readWorkspaceAutoFixSettingsForPr } from '../../review/claude-review/auto-settings.js';
+import { automaticRunAllowed } from '../../review/budget-gate.js';
 // At most AUTO_FIX_DAILY_CAP (shared) AUTO fixes per PR in any rolling AUTO_FIX_WINDOW_MS.
 export { AUTO_FIX_DAILY_CAP };
 export const AUTO_FIX_WINDOW_MS = 24 * 60 * 60 * 1000;
@@ -137,6 +138,9 @@ export async function maybeStartAutoFix(ctx, input, deps = defaultDeps, nowMs =
         const ws = await readWorkspaceAutoFixSettingsForPr(ctx, accountId, prId);
         if (!ws?.enabled)
             return skip('off');
+        // THE CLAUDE SPEND BUDGET (ai/budget.ts): over it, no auto fix — the next auto review decides again.
+        if (!(await automaticRunAllowed(ctx, accountId, 'auto fix')))
+            return skip('over_budget');
         // WHAT an auto fix carries is the workspace's "Always include" sections (AutoFixSettings).
         const include = ws.settings.include;
         const loaded = await deps.loadReviewSeed(ctx, {

package/dist/db/export-account.js

@@ -51,6 +51,8 @@ export async function exportAccountData(accountId) {
         largePrCodeLocThreshold: accounts.largePrCodeLocThreshold,
         blastRadiusConfig: accounts.blastRadiusConfig,
         myTurnSettings: accounts.myTurnSettings,
+        aiBudgetSettings: accounts.aiBudgetSettings,
+        aiBudgetReading: accounts.aiBudgetReading,
         lastLoginAt: accounts.lastLoginAt,
         lastActiveAt: accounts.lastActiveAt,
         createdAt: accounts.createdAt,

package/dist/db/migrations/0125_account_ai_budget.sql

@@ -0,0 +1,10 @@
+-- THE CLAUDE SPEND BUDGET (core; packages/shared ai-budget.ts, ai/budget.ts).
+--
+-- accounts.ai_budget_settings: the optional per-machine budget that pauses AUTOMATIC model runs —
+-- the subscription thresholds (5-hour / 7-day %), the subscription picked for the estimate, and the
+-- API-key US$ budget. NULL = never set = off. One writer: PUT /api/ai/budget.
+-- accounts.ai_budget_reading: the latest subscription usage reading (utilisation + reset time per
+-- window), so a restart keeps it. Both nullable, no backfill.
+ALTER TABLE `accounts` ADD `ai_budget_settings` text;
+--> statement-breakpoint
+ALTER TABLE `accounts` ADD `ai_budget_reading` text;

package/dist/db/migrations/0126_workspace_auto_diagrams.sql

@@ -0,0 +1,8 @@
+-- AUTOMATIC DESIGN DIAGRAMS, PER WORKSPACE — `workspaces.auto_diagrams_enabled`. After every
+-- succeeded Claude review (manual or auto), review/diagrams/trigger.ts may queue the PR's design
+-- diagram and its tickets' story diagrams. This is that step's switch, edited in Settings beside
+-- auto review and written by `setWorkspaceAutoReview` (review/claude-review/auto-settings.ts).
+-- ⚠ DEFAULT TRUE (1) and NOT NULL: diagrams were drawn after every review before this column
+-- existed, so every workspace, existing and new, keeps that until someone switches it off. Off
+-- stops only the AUTOMATIC draw; the Draw / Redraw button still works.
+ALTER TABLE `workspaces` ADD `auto_diagrams_enabled` integer DEFAULT 1 NOT NULL;