diff --git a/kloe.example.json b/kloe.example.json
index 72420f7..1e84ef2 100644
--- a/kloe.example.json
+++ b/kloe.example.json
@@ -41,7 +41,23 @@
     "baseUrl": "https://kloe.dunkirk.sh",
     "allowedSubs": [],
     "sessionTtlDays": 30,
-    "appName": "kloe"
+    "appName": "kloe",
+    "roles": {
+      "owner": {
+        "admin": true,
+        "sandbox": true,
+        "publish": true,
+        "models": ["*"],
+        "search": ["*"],
+        "subs": ["https://you.example/"]
+      },
+      "guest": {
+        "models": ["hyper/*"],
+        "search": ["duckduckgo"],
+        "usdPerDay": 0.5,
+        "tokensPerDay": 0
+      }
+    }
   },
   "prompt": {
     "name": "Kloe",
diff --git a/kloe.schema.json b/kloe.schema.json
index c01aa77..1afdf00 100644
--- a/kloe.schema.json
+++ b/kloe.schema.json
@@ -450,6 +450,14 @@
                 },
                 "default": []
               },
+              "usdPerDay": {
+                "type": "number",
+                "default": 0
+              },
+              "tokensPerDay": {
+                "type": "number",
+                "default": 0
+              },
               "subs": {
                 "type": "array",
                 "items": {
diff --git a/src/auth.ts b/src/auth.ts
index 036ff5c..a56b568 100644
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -348,6 +348,8 @@ const BUILT_IN: Record<string, RolePolicy> = {
     publish: true,
     models: ["*"],
     search: ["*"],
+    usdPerDay: 0,
+    tokensPerDay: 0,
     subs: [],
     providerRoles: [],
   },
@@ -357,6 +359,8 @@ const BUILT_IN: Record<string, RolePolicy> = {
     publish: false,
     models: [],
     search: [],
+    usdPerDay: 0,
+    tokensPerDay: 0,
     subs: [],
     providerRoles: [],
   },
diff --git a/src/client/app.css b/src/client/app.css
index 5a2f529..e872e7b 100644
--- a/src/client/app.css
+++ b/src/client/app.css
@@ -3527,6 +3527,18 @@ body.lb-open {
   color: var(--ink-muted);
   margin-top: 2px;
 }
+/* The figure at the end of a usage row. Tabular so a column of amounts lines
+   up on the decimal instead of shimmering as it updates. */
+.usagefig {
+  flex: none;
+  font-size: 13px;
+  font-variant-numeric: tabular-nums;
+  color: var(--ink-muted);
+}
+.usagebar {
+  margin: 8px 2px 0;
+}
+
 .connrow .btn,
 .connrow .connkey {
   flex: none;
diff --git a/src/client/app.js b/src/client/app.js
index d7604bf..993f5b9 100644
--- a/src/client/app.js
+++ b/src/client/app.js
@@ -817,7 +817,10 @@ import { mountSidebar } from "./sidebar.js";
     delete queued[runId];
     renderQueue();
   }
-  function failUser(runId) {
+  // `reason` is the server's own words when it had any (a budget, a model a
+  // role may not reach). Silence there reads as a bug in kloe rather than a
+  // rule the person could do something about.
+  function failUser(runId, reason) {
     var p = pending[runId];
     if (!p) return;
     p.turn.classList.remove("pending");
@@ -825,7 +828,7 @@ import { mountSidebar } from "./sidebar.js";
     if (p.turn.querySelector(".failbar")) return;
     var fb = document.createElement("div");
     fb.className = "failbar";
-    fb.textContent = "not sent — ";
+    fb.textContent = reason ? reason + " " : "not sent — ";
     var btn = document.createElement("button");
     btn.type = "button";
     btn.textContent = "Retry";
@@ -3103,7 +3106,7 @@ import { mountSidebar } from "./sidebar.js";
         var err = await res.json().catch(function () {
           return {};
         });
-        failUser(runId);
+        failUser(runId, err.error);
         if (err.error) console.warn("prompt rejected:", err.error);
         return;
       }
diff --git a/src/client/views/settings.js b/src/client/views/settings.js
index 116f205..df112eb 100644
--- a/src/client/views/settings.js
+++ b/src/client/views/settings.js
@@ -37,6 +37,7 @@ var TEMPLATE =
   '<div class="settabs" id="settabs" role="tablist">' +
   '<button class="settab active" type="button" data-tab="models" role="tab">Models</button>' +
   '<button class="settab" type="button" data-tab="connections" role="tab">Connections</button>' +
+  '<button class="settab" type="button" data-tab="usage" role="tab">Usage</button>' +
   '<button class="settab" type="button" data-tab="research" role="tab" hidden>Research</button>' +
   '<button class="settab" type="button" data-tab="memory" role="tab" hidden>Memory</button>' +
   '<button class="settab" type="button" data-tab="people" role="tab" hidden>People</button>' +
@@ -48,6 +49,14 @@ var TEMPLATE =
   '<p class="lede">Your picker. Turn models on, drag them into the order you want (⌘-click to move several at once), and rename any of them. Which models you can choose from is set in <code>kloe.json</code>; what you do with them is yours.</p>' +
   '<div id="content">Loading…</div>' +
   "</section>" +
+  '<section class="settabpanel" data-panel="usage" hidden>' +
+  '<p class="lede">What your chats have cost, at each model\'s published rates. Runs on an account you connected yourself are listed too, and never count against a limit here.</p>' +
+  '<div id="usageToday"></div>' +
+  '<div class="seclabel" id="usageModelsLabel">By model</div>' +
+  '<div id="usageByModel"></div>' +
+  '<div class="seclabel" id="usageEveryoneLabel" hidden>Everyone</div>' +
+  '<div id="usageByUser"></div>' +
+  "</section>" +
   '<section class="settabpanel" data-panel="research" hidden>' +
   '<p class="lede">Deep research runs two jobs. The <strong>lead</strong> plans the angles, reads each round of notes to decide what to chase next, and writes the report. The <strong>workers</strong> search and read pages — far more tokens, on a much narrower job. Running a strong lead over cheaper workers is usually better than running one model for both.</p>' +
   '<div class="rolepick" id="rolepick">Loading…</div>' +
@@ -715,6 +724,124 @@ export function mount(root, _params, ctx) {
     }
   }
 
+  // ---- usage ----
+  // A statement, not a control. What a run costs is decided by the model's
+  // price and what the role may spend, both of which live in kloe.json — this
+  // panel exists so nobody has to guess where the month went.
+
+  /** Dollars, with enough digits to be worth reading at kloe's amounts. */
+  function money(v) {
+    if (!v) return "$0";
+    if (v < 0.01) return "$" + v.toFixed(4);
+    if (v < 1) return "$" + v.toFixed(3);
+    return "$" + v.toFixed(2);
+  }
+  function count(n) {
+    return (n || 0).toLocaleString("en-US");
+  }
+  /** A row in the connections vocabulary: name on the left, figure on the right. */
+  function usageRow(title, detail, figure) {
+    var row = document.createElement("div");
+    row.className = "connrow";
+    var text = document.createElement("div");
+    text.className = "conntext";
+    var t = document.createElement("div");
+    t.className = "conntitle";
+    t.textContent = title;
+    var d = document.createElement("div");
+    d.className = "connsub";
+    d.textContent = detail;
+    text.appendChild(t);
+    text.appendChild(d);
+    row.appendChild(text);
+    if (figure) {
+      var f = document.createElement("span");
+      f.className = "usagefig";
+      f.textContent = figure;
+      row.appendChild(f);
+    }
+    return row;
+  }
+
+  function renderToday(u) {
+    var host = byId("usageToday");
+    if (!host) return;
+    host.innerHTML = "";
+    var budget = u.budget || {};
+    var caps = [];
+    if (budget.usdPerDay > 0) caps.push(money(u.spentUsd) + " of " + money(budget.usdPerDay));
+    if (budget.tokensPerDay > 0)
+      caps.push(count(u.spentTokens) + " of " + count(budget.tokensPerDay) + " tokens");
+    var row = usageRow(
+      "Today",
+      caps.length
+        ? caps.join(" \u00b7 ") + (u.ok ? "" : " \u00b7 " + u.reason)
+        : count(u.spentTokens) + " tokens on this instance, with no daily limit",
+      caps.length ? "" : money(u.spentUsd),
+    );
+    if (!u.ok) row.classList.add("on");
+    host.appendChild(row);
+
+    // The bar only means something when there is a limit to be a fraction of.
+    var of = budget.usdPerDay > 0 ? u.spentUsd / budget.usdPerDay : 0;
+    var ofTokens = budget.tokensPerDay > 0 ? u.spentTokens / budget.tokensPerDay : 0;
+    var filled = Math.max(of, ofTokens);
+    if (filled > 0) {
+      var bar = document.createElement("div");
+      bar.className = "rsrchbar usagebar";
+      var fill = document.createElement("span");
+      fill.style.width = Math.min(100, Math.round(filled * 100)) + "%";
+      bar.appendChild(fill);
+      host.appendChild(bar);
+    }
+  }
+
+  function renderTotals(host, rows, label) {
+    host.innerHTML = "";
+    if (!rows.length) {
+      host.innerHTML = '<p class="lede">Nothing yet.</p>';
+      return;
+    }
+    rows.forEach(function (r) {
+      host.appendChild(
+        usageRow(
+          r.key,
+          count(r.calls) +
+            (r.calls === 1 ? " call \u00b7 " : " calls \u00b7 ") +
+            count(r.inputTokens) +
+            " in \u00b7 " +
+            count(r.outputTokens) +
+            " out",
+          money(r.costUsd),
+        ),
+      );
+    });
+    if (label) label.hidden = false;
+  }
+
+  async function loadUsage() {
+    var host = byId("usageByModel");
+    if (!host) return;
+    try {
+      var u = await (await fetch("/api/usage?days=30")).json();
+      renderToday(u);
+      var label = byId("usageModelsLabel");
+      if (label) label.textContent = "By model, last " + u.days + " days";
+      renderTotals(host, u.byModel || []);
+    } catch (_) {
+      host.innerHTML = '<p class="lede">Could not read the ledger.</p>';
+      return;
+    }
+    // Everyone's spending is an admin's business; a 403 here simply means the
+    // section stays away.
+    try {
+      var res = await fetch("/api/usage?days=30&scope=instance");
+      if (!res.ok) return;
+      var all = await res.json();
+      renderTotals(byId("usageByUser"), all.byUser || [], byId("usageEveryoneLabel"));
+    } catch (_) {}
+  }
+
   // ---- lard (memory) ----
   async function loadLard() {
     var tabBtn = root.querySelector('.settab[data-tab="memory"]');
@@ -1015,10 +1142,12 @@ export function mount(root, _params, ctx) {
   // Roles first: the model rows draw a checkbox per role, so they need the list
   // before they render.
   loadRoles();
+  loadUsage();
   if (location.hash === "#memory") selectTab("memory");
   if (location.hash === "#connections") selectTab("connections");
   if (location.hash === "#mine") selectTab("models");
   if (location.hash === "#people") selectTab("people");
+  if (location.hash === "#usage") selectTab("usage");
   loadLard();
   // Models and preferences together: a role picker lists enabled models, so
   // rendering it needs both and rendering it twice would flicker.
diff --git a/src/http.ts b/src/http.ts
index a69c270..841ead6 100644
--- a/src/http.ts
+++ b/src/http.ts
@@ -61,6 +61,7 @@ import {
 import { getConfig } from "./settings";
 import { sseBlock } from "./sse";
 import type { Store } from "./store";
+import { budgetStatus, DAY_MS } from "./usage";
 import { describeRef, forgetUserModels, userModelRefs } from "./usermodels";
 import { withBody } from "./validate";
 
@@ -310,8 +311,23 @@ function requireUsableModel(
   // Otherwise it is the instance paying, and the role says which of its models
   // this person may reach. What they picked for their own picker is their
   // business, not a permission.
-  if (roleMayUse(role, ref)) return null;
-  return Response.json({ error: `model "${ref}" is not available to you` }, { status: 403 });
+  if (!roleMayUse(role, ref)) {
+    return Response.json({ error: `model "${ref}" is not available to you` }, { status: 403 });
+  }
+  // And how much of it they may spend. Checked as a run starts, so a turn
+  // already in flight is never cut off part-way — the budget bounds what gets
+  // started, not what finishes.
+  const budget = budgetStatus(store, sub ?? LOCAL_SUB, role);
+  if (!budget.ok) {
+    return Response.json(
+      {
+        error: `${budget.reason}. Connect your own account to keep going.`,
+        resetsAt: budget.resetsAt,
+      },
+      { status: 429 },
+    );
+  }
+  return null;
 }
 
 /**
@@ -1160,6 +1176,37 @@ export function apiRoutes(deps: { store: Store; blobs: BlobStore; kick?: () => v
         }),
     },
 
+    /**
+     * What has been spent, and what is left to spend.
+     *
+     * Yours by default; `?scope=instance` is everyone's, and needs admin. The
+     * ledger records both payers, so this is also where someone sees that the
+     * account they connected is the one paying.
+     */
+    "/api/usage": {
+      GET: (req: Bun.BunRequest<"/api/usage">) => {
+        const url = new URL(req.url);
+        const sub = whoami(req, store);
+        const role = requestRole(req, store);
+        const instance = url.searchParams.get("scope") === "instance";
+        if (instance) {
+          const denied = requireOwner(req, store);
+          if (denied) return denied;
+        }
+        const days = Math.min(Math.max(Number(url.searchParams.get("days")) || 30, 1), 365);
+        const since = Date.now() - days * DAY_MS;
+        const scope = instance ? {} : { sub };
+        return Response.json({
+          days,
+          role,
+          ...budgetStatus(store, sub, role),
+          byModel: store.usageTotals({ since, groupBy: "model", ...scope }),
+          byDay: store.usageTotals({ since, groupBy: "day", ...scope }),
+          ...(instance ? { byUser: store.usageTotals({ since, groupBy: "sub" }) } : {}),
+        });
+      },
+    },
+
     "/api/conversations/:id/stream": {
       GET: (req: Bun.BunRequest<"/api/conversations/:id/stream">) =>
         guardConv(req, req.params.id) ?? openStream(req.params.id, req, store),
diff --git a/src/inference.ts b/src/inference.ts
index 21c7a7b..6349bca 100644
--- a/src/inference.ts
+++ b/src/inference.ts
@@ -13,6 +13,7 @@ import { searchProviderFor } from "./search";
 import { getConfig } from "./settings";
 import type { Store } from "./store";
 import { type ToolContext, toolSet } from "./tools";
+import { metered } from "./usage";
 
 /**
  * True when provider reasoning metadata carries a signature — the marker of a
@@ -346,12 +347,20 @@ export function resolveModel(modelRef: string, credential?: Credential): Languag
  */
 export async function resolveModelFor(
   modelRef: string,
-  who: { store?: Store; sub?: string },
+  who: { store?: Store; sub?: string; conversationId?: string },
 ): Promise<LanguageModel> {
   if (!who.store || !who.sub || isEchoModel(modelRef)) return resolveModel(modelRef);
   const providerName = modelRef.split("/")[0]!;
   const credential = await credentialFor(who.store, who.sub, "inference", providerName);
-  return resolveModel(modelRef, credential);
+  // Metered here rather than at the turn, because this is where every model a
+  // run touches comes from — the utility ones included. Whose credential
+  // answered is also what says who pays, so the ledger learns it for free.
+  return metered(resolveModel(modelRef, credential), modelRef, {
+    store: who.store,
+    sub: who.sub,
+    payer: credential ? "user" : "instance",
+    conversationId: who.conversationId,
+  });
 }
 
 /** Project-scoped context to fold into a run: the pinned lard project (whose
@@ -393,7 +402,7 @@ export async function* run(messages: ModelMessage[], opts: RunOptions): AsyncGen
   // connected something of their own. Resolved once, here, and reused for every
   // model this run touches — the utility models included, since a research
   // worker on the deployment's key would quietly undo the whole arrangement.
-  const who = { store: opts.store, sub: opts.owner };
+  const who = { store: opts.store, sub: opts.owner, conversationId: opts.conversationId };
   const model = await resolveModelFor(opts.model, who);
   // Per-provider knobs from ops config: an output-token cap, and raw
   // provider-specific options (e.g. a reasoning/thinking toggle) sent under the
diff --git a/src/settings.ts b/src/settings.ts
index b82dffe..edfdf4b 100644
--- a/src/settings.ts
+++ b/src/settings.ts
@@ -414,6 +414,20 @@ const RolePolicySchema = v.object({
    * takes no key and costs nobody anything, so there is nothing to opt into.
    */
   search: v.optional(v.array(v.string()), []),
+  /**
+   * Dollars of the INSTANCE's credits this role may spend in a rolling 24
+   * hours. 0 is no bound, which is what an owner wants and a guest does not.
+   *
+   * Their own connected accounts never count toward it: a budget bounds what
+   * the operator pays for, and someone paying their own way is not spending it.
+   */
+  usdPerDay: v.optional(v.number(), 0),
+  /**
+   * The same bound in tokens, for the models a price is not known for — a free
+   * tier, a router that bills elsewhere, anything the catalog prices at zero.
+   * Whichever limit is reached first stops the next run.
+   */
+  tokensPerDay: v.optional(v.number(), 0),
   /** Subject URLs holding this role outright. Checked before anything else. */
   subs: v.optional(v.array(v.string()), []),
   /** Provider role strings that map to this one (indiko's per-app RBAC). */
@@ -421,6 +435,17 @@ const RolePolicySchema = v.object({
 });
 export type RolePolicy = v.InferOutput<typeof RolePolicySchema>;
 
+/**
+ * A policy from a partial one, defaults filled in.
+ *
+ * The schema already knows what an unstated field means, so nothing that builds
+ * a policy by hand — a test, a caller assembling one — has to restate every
+ * field, and a field added later does not break them.
+ */
+export function rolePolicy(partial: Partial<RolePolicy> = {}): RolePolicy {
+  return v.parse(RolePolicySchema, partial);
+}
+
 const AuthSchema = v.object({
   enabled: v.optional(v.boolean(), false),
   /** The OIDC issuer origin, e.g. https://indiko.dunkirk.sh */
diff --git a/src/store.ts b/src/store.ts
index 20ad963..e444c06 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -500,8 +500,57 @@ CREATE TABLE IF NOT EXISTS user_credentials (
   updated_at    INTEGER NOT NULL,
   PRIMARY KEY (sub, service, provider_id)
 );
+
+-- What each model call cost, and who it was spent on behalf of. One row per
+-- provider call: a turn with three tool steps is three rows, and a research
+-- run's workers land here beside the conversation that asked for them.
+--
+-- payer is the whole reason this table is not just a log. 'instance' is the
+-- operator's credits and is what a budget bounds; 'user' is someone spending
+-- their own connected account, which nobody needs to ration. cost_usd is
+-- computed at write time from the catalog's prices, because a price that
+-- changes next month must not silently restate what last month cost.
+CREATE TABLE IF NOT EXISTS usage_log (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts              INTEGER NOT NULL,
+  sub             TEXT NOT NULL,
+  payer           TEXT NOT NULL,
+  service         TEXT NOT NULL,
+  provider_id     TEXT NOT NULL,
+  model_ref       TEXT NOT NULL,
+  conversation_id TEXT,
+  input_tokens    INTEGER NOT NULL DEFAULT 0,
+  output_tokens   INTEGER NOT NULL DEFAULT 0,
+  cost_usd        REAL NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_usage_sub_ts ON usage_log (sub, ts);
+CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage_log (ts);
 `;
 
+/** One provider call, as the ledger records it. */
+export interface UsageEntry {
+  ts: number;
+  sub: string;
+  /** Whose credits: the deployment's, or the user's own connected account. */
+  payer: "instance" | "user";
+  service: "inference" | "search";
+  providerId: string;
+  modelRef: string;
+  conversationId?: string;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+}
+
+/** A ledger total, by whatever the query grouped on. */
+export interface UsageTotal {
+  key: string;
+  calls: number;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+}
+
 /** The stored row, ciphertext and all. Decrypted into a UserCredential by credentials.ts. */
 export interface CredentialRow {
   sub: string;
@@ -1623,6 +1672,97 @@ export class Store {
     );
   }
 
+  // ---- the spend ledger ---------------------------------------------------
+
+  /** Record one provider call. Never throws — a lost row must not fail a run. */
+  recordUsage(e: UsageEntry): void {
+    try {
+      this.db
+        .query(
+          `INSERT INTO usage_log
+             (ts, sub, payer, service, provider_id, model_ref, conversation_id,
+              input_tokens, output_tokens, cost_usd)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          e.ts,
+          e.sub,
+          e.payer,
+          e.service,
+          e.providerId,
+          e.modelRef,
+          e.conversationId ?? null,
+          e.inputTokens,
+          e.outputTokens,
+          e.costUsd,
+        );
+    } catch (err) {
+      console.warn("[usage] could not record:", (err as Error).message);
+    }
+  }
+
+  /**
+   * What one person has spent of the INSTANCE's credits since `since`.
+   *
+   * Their own connected accounts are excluded on purpose: a budget bounds what
+   * the operator pays for, and someone paying their own way is not spending it.
+   */
+  spentSince(sub: string, since: number): { costUsd: number; tokens: number } {
+    const row = this.db
+      .query(
+        `SELECT COALESCE(SUM(cost_usd), 0) AS cost,
+                COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens
+         FROM usage_log WHERE sub = ? AND payer = 'instance' AND ts >= ?`,
+      )
+      .get(sub, since) as { cost: number; tokens: number };
+    return { costUsd: row.cost, tokens: row.tokens };
+  }
+
+  /**
+   * Ledger totals since `since`, grouped by model, by person, or by day.
+   *
+   * `sub` narrows it to one person — the difference between "what have I spent"
+   * and the admin's "what has this instance spent".
+   */
+  usageTotals(opts: {
+    since: number;
+    groupBy: "model" | "sub" | "day";
+    sub?: string;
+    payer?: "instance" | "user";
+  }): UsageTotal[] {
+    const column =
+      opts.groupBy === "model"
+        ? "model_ref"
+        : opts.groupBy === "sub"
+          ? "sub"
+          : "date(ts / 1000, 'unixepoch')";
+    const where = ["ts >= ?"];
+    const args: Array<string | number> = [opts.since];
+    if (opts.sub) {
+      where.push("sub = ?");
+      args.push(opts.sub);
+    }
+    if (opts.payer) {
+      where.push("payer = ?");
+      args.push(opts.payer);
+    }
+    return this.db
+      .query(
+        `SELECT ${column} AS key, COUNT(*) AS calls,
+                COALESCE(SUM(input_tokens), 0) AS inputTokens,
+                COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                COALESCE(SUM(cost_usd), 0) AS costUsd
+         FROM usage_log WHERE ${where.join(" AND ")}
+         GROUP BY key ORDER BY ${opts.groupBy === "day" ? "key ASC" : "costUsd DESC, calls DESC"}`,
+      )
+      .all(...args) as UsageTotal[];
+  }
+
+  /** Drop ledger rows older than `before` — for whoever prunes. */
+  pruneUsage(before: number): number {
+    return this.db.query("DELETE FROM usage_log WHERE ts < ?").run(before).changes;
+  }
+
   // ---- conversation ownership --------------------------------------------
   /** Stamp who started a conversation, first writer wins (no-op without a sub). */
   setConversationOwner(id: string, sub: string | undefined): void {
diff --git a/src/usage.ts b/src/usage.ts
new file mode 100644
index 0000000..2d867df
--- /dev/null
+++ b/src/usage.ts
@@ -0,0 +1,175 @@
+import { type LanguageModel, wrapLanguageModel } from "ai";
+import { policyFor, type Role } from "./auth";
+import { getCatalog, getRegistry } from "./inference";
+import type { Store, UsageEntry } from "./store";
+
+/**
+ * What a run costs, and who may keep spending.
+ *
+ * Two halves of one idea. The ledger records every provider call with a price
+ * attached, and a budget reads that ledger back to decide whether a role has
+ * spent enough for one day. Both hang off `payer`: a call on someone's own
+ * connected account is recorded but never counted against a budget, because a
+ * budget bounds what the operator pays for and nothing else.
+ *
+ * Metering happens at the model, not at the turn. A turn with three tool steps
+ * is three calls, a research run is a lead plus its workers, and a title is a
+ * fourth model nobody picked — measuring at the model catches all of it, where
+ * measuring at the turn would quietly miss most of what a busy run spends.
+ */
+
+/** The rolling window a budget is measured over. Not a calendar day: no timezone to argue with. */
+export const DAY_MS = 86_400_000;
+
+const num = (n: unknown): number => (typeof n === "number" && Number.isFinite(n) ? n : 0);
+
+/** Per-million prices for a ref, from wherever the ref is known. */
+function priceOf(modelRef: string): { in: number; out: number } {
+  const [providerId, ...rest] = modelRef.split("/");
+  const modelId = rest.join("/");
+  try {
+    const enabled = getRegistry()
+      .listModels()
+      .find((m) => m.ref === modelRef);
+    if (enabled) return { in: num(enabled.costPer1MIn), out: num(enabled.costPer1MOut) };
+  } catch {
+    // no registry yet (early boot, tests): the catalog below may still know it
+  }
+  const model = getCatalog()
+    ?.getProvider(providerId ?? "")
+    ?.models.find((m) => m.id === modelId);
+  return { in: num(model?.costPer1MIn), out: num(model?.costPer1MOut) };
+}
+
+/**
+ * What a call cost, in dollars.
+ *
+ * Cached-input pricing is deliberately not applied: nothing on the response
+ * tells us reliably how much of the prompt was a cache hit, and a guess that
+ * lowers the number is the wrong way to be wrong about a spending limit.
+ */
+export function costOf(modelRef: string, inputTokens: number, outputTokens: number): number {
+  const price = priceOf(modelRef);
+  return (inputTokens / 1e6) * price.in + (outputTokens / 1e6) * price.out;
+}
+
+/** Who a call is billed to, and where to file it. */
+export interface Meter {
+  store: Store;
+  sub: string;
+  payer: UsageEntry["payer"];
+  conversationId?: string;
+}
+
+function record(meter: Meter, modelRef: string, input: number, output: number): void {
+  if (input === 0 && output === 0) return; // the provider told us nothing; nothing to file
+  meter.store.recordUsage({
+    ts: Date.now(),
+    sub: meter.sub,
+    payer: meter.payer,
+    service: "inference",
+    providerId: modelRef.split("/")[0] ?? "",
+    modelRef,
+    conversationId: meter.conversationId,
+    inputTokens: input,
+    outputTokens: output,
+    costUsd: costOf(modelRef, input, output),
+  });
+}
+
+/**
+ * Wrap a model so every call it serves lands in the ledger.
+ *
+ * The stream case files its row when the stream drains rather than when the
+ * `finish` part arrives, so a turn the user cancels mid-sentence still records
+ * what it had spent by then — the provider charged for it either way.
+ */
+export function metered(model: LanguageModel, modelRef: string, meter: Meter): LanguageModel {
+  return wrapLanguageModel({
+    // `LanguageModel` includes the string form (a ref the SDK resolves itself);
+    // everything kloe resolves is already an instance, and only an instance can
+    // be wrapped.
+    model: model as Exclude<LanguageModel, string>,
+    middleware: {
+      wrapGenerate: async ({ doGenerate }) => {
+        const result = await doGenerate();
+        record(meter, modelRef, num(result.usage?.inputTokens), num(result.usage?.outputTokens));
+        return result;
+      },
+      wrapStream: async ({ doStream }) => {
+        const { stream, ...rest } = await doStream();
+        let input = 0;
+        let output = 0;
+        return {
+          ...rest,
+          stream: stream.pipeThrough(
+            new TransformStream({
+              transform(chunk, controller) {
+                const part = chunk as { type?: string; usage?: Record<string, unknown> };
+                if (part.type === "finish" && part.usage) {
+                  input = num(part.usage.inputTokens);
+                  output = num(part.usage.outputTokens);
+                }
+                controller.enqueue(chunk);
+              },
+              flush() {
+                record(meter, modelRef, input, output);
+              },
+            }),
+          ),
+        };
+      },
+    },
+  });
+}
+
+/** What a role may spend of the instance's credits in a day. 0 means no bound. */
+export interface Budget {
+  usdPerDay: number;
+  tokensPerDay: number;
+}
+
+export function budgetFor(role: Role): Budget {
+  const policy = policyFor(role);
+  return { usdPerDay: policy.usdPerDay, tokensPerDay: policy.tokensPerDay };
+}
+
+export interface BudgetStatus {
+  /** True when this person may still start work on the instance's credits. */
+  ok: boolean;
+  /** Why not, in words a person can act on. */
+  reason?: string;
+  spentUsd: number;
+  spentTokens: number;
+  budget: Budget;
+  /** When the window rolls far enough for them to continue. */
+  resetsAt?: number;
+}
+
+/**
+ * Where this person stands against their role's budget.
+ *
+ * Checked when a run starts, not while it runs. A turn already in flight
+ * finishes and is billed in full — stopping mid-sentence would waste what was
+ * already spent to save the tail of one answer.
+ */
+export function budgetStatus(store: Store, sub: string, role: Role): BudgetStatus {
+  const budget = budgetFor(role);
+  const since = Date.now() - DAY_MS;
+  const spent = store.spentSince(sub, since);
+  const out: BudgetStatus = {
+    ok: true,
+    spentUsd: spent.costUsd,
+    spentTokens: spent.tokens,
+    budget,
+  };
+  if (budget.usdPerDay > 0 && spent.costUsd >= budget.usdPerDay) {
+    out.ok = false;
+    out.reason = `daily limit of $${budget.usdPerDay.toFixed(2)} reached`;
+  } else if (budget.tokensPerDay > 0 && spent.tokens >= budget.tokensPerDay) {
+    out.ok = false;
+    out.reason = `daily limit of ${budget.tokensPerDay.toLocaleString("en-US")} tokens reached`;
+  }
+  if (!out.ok) out.resetsAt = since + DAY_MS;
+  return out;
+}
diff --git a/tests/roles.test.ts b/tests/roles.test.ts
index 298a954..b20cf9f 100644
--- a/tests/roles.test.ts
+++ b/tests/roles.test.ts
@@ -8,7 +8,7 @@ import { Catalog } from "../src/catalog";
 import { apiRoutes } from "../src/http";
 import { setRegistry } from "../src/inference";
 import { ProviderRegistry } from "../src/providers";
-import { loadConfig, type RolePolicy, setConfig } from "../src/settings";
+import { loadConfig, type RolePolicy, rolePolicy, setConfig } from "../src/settings";
 import { Store } from "../src/store";
 import { toolSet } from "../src/tools";
 
@@ -46,7 +46,7 @@ function configure(owners: string[], ownerRole?: string): void {
   const roles: Record<string, RolePolicy> =
     owners.length || ownerRole
       ? {
-          owner: {
+          owner: rolePolicy({
             admin: true,
             sandbox: true,
             publish: true,
@@ -54,10 +54,10 @@ function configure(owners: string[], ownerRole?: string): void {
             search: ["*"],
             subs: owners,
             providerRoles: ownerRole ? [ownerRole] : [],
-          },
+          }),
           // Guests may pick from one provider's models here; what they see is
           // whichever of those they turned on.
-          guest: {
+          guest: rolePolicy({
             admin: false,
             sandbox: false,
             publish: false,
@@ -65,7 +65,7 @@ function configure(owners: string[], ownerRole?: string): void {
             search: [],
             subs: [],
             providerRoles: [],
-          },
+          }),
         }
       : {};
   setConfig({ ...base, auth: { ...base.auth, enabled: true, roles } });
@@ -132,7 +132,7 @@ test("auth off means there is nobody to be a guest to", () => {
       ...base.auth,
       enabled: false,
       roles: {
-        owner: {
+        owner: rolePolicy({
           admin: true,
           sandbox: true,
           publish: true,
@@ -140,7 +140,7 @@ test("auth off means there is nobody to be a guest to", () => {
           search: ["*"],
           subs: [OWNER],
           providerRoles: [],
-        },
+        }),
       },
     },
   });
@@ -315,7 +315,7 @@ test("roles declared in config carry their own policy", () => {
       ...base.auth,
       enabled: true,
       roles: {
-        staff: {
+        staff: rolePolicy({
           admin: false,
           sandbox: true,
           publish: true,
@@ -323,8 +323,8 @@ test("roles declared in config carry their own policy", () => {
           search: [],
           subs: [],
           providerRoles: ["staff"],
-        },
-        visitor: {
+        }),
+        visitor: rolePolicy({
           admin: false,
           sandbox: false,
           publish: false,
@@ -332,7 +332,7 @@ test("roles declared in config carry their own policy", () => {
           search: [],
           subs: [],
           providerRoles: ["visitor"],
-        },
+        }),
       },
     },
   });
@@ -362,7 +362,7 @@ test("a later sign-in does not undo an assignment made here", () => {
       ...base.auth,
       enabled: true,
       roles: {
-        owner: {
+        owner: rolePolicy({
           admin: true,
           sandbox: true,
           publish: true,
@@ -370,8 +370,8 @@ test("a later sign-in does not undo an assignment made here", () => {
           search: ["*"],
           subs: [],
           providerRoles: ["operator"],
-        },
-        guest: {
+        }),
+        guest: rolePolicy({
           admin: false,
           sandbox: false,
           publish: false,
@@ -379,7 +379,7 @@ test("a later sign-in does not undo an assignment made here", () => {
           search: [],
           subs: [GUEST],
           providerRoles: [],
-        },
+        }),
       },
     },
   });
@@ -504,3 +504,120 @@ test("your list is what your role may reach, and you cannot curate past it", asy
   // put in or take out.
   expect(await guestPicker()).toEqual(["acme/cheap"]);
 });
+
+/** The same instance, with a spending bound on the guest role. */
+function configureBudget(over: { usdPerDay?: number; tokensPerDay?: number }): void {
+  const base = loadConfig({ path: "does-not-exist.json", env: {} });
+  setConfig({
+    ...base,
+    auth: {
+      ...base.auth,
+      enabled: true,
+      roles: {
+        owner: rolePolicy({ admin: true, models: ["*"], search: ["*"], subs: [OWNER] }),
+        guest: rolePolicy({ models: ["acme/*"], ...over }),
+      },
+    },
+  });
+  resetAuthCache();
+}
+
+/** Charge `costUsd` to `sub` on the instance's credits, as a run would. */
+function charge(store: Store, sub: string, costUsd: number, tokens = 1000): void {
+  store.recordUsage({
+    ts: Date.now(),
+    sub,
+    payer: "instance",
+    service: "inference",
+    providerId: "acme",
+    modelRef: "acme/cheap",
+    inputTokens: tokens,
+    outputTokens: 0,
+    costUsd,
+  });
+}
+
+test("a guest who has spent their day is refused, and told why", async () => {
+  configureBudget({ usdPerDay: 0.5 });
+  const { base, store } = freshApp();
+  const prompt = (sub: string, conversation = "b1") =>
+    fetch(`${base}/api/conversations/${conversation}/prompt`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...as(store, sub) },
+      body: JSON.stringify({ content: "hi", model: "acme/cheap" }),
+    });
+
+  expect((await prompt(GUEST)).status).toBe(202);
+  charge(store, GUEST, 0.6);
+
+  const refused = await prompt(GUEST);
+  expect(refused.status).toBe(429);
+  expect(((await refused.json()) as { error: string }).error).toContain("$0.50");
+  // One person's spending is their own: the owner is unaffected, and so would
+  // another guest be.
+  expect((await prompt(OWNER, "b1-owner")).status).toBe(202);
+});
+
+test("a guest paying for themselves is not bounded by the instance's budget", async () => {
+  configureBudget({ usdPerDay: 0.5 });
+  const { base, store } = freshApp();
+  charge(store, GUEST, 5);
+  // Their own connected account, recorded but never counted.
+  store.recordUsage({
+    ts: Date.now(),
+    sub: GUEST,
+    payer: "user",
+    service: "inference",
+    providerId: "acme",
+    modelRef: "acme/cheap",
+    inputTokens: 10,
+    outputTokens: 10,
+    costUsd: 99,
+  });
+  store.setCredentialRow({
+    sub: GUEST,
+    service: "inference",
+    provider_id: "acme",
+    kind: "key",
+    secret: "ciphertext",
+    refresh_token: null,
+    expires_at: null,
+    label: null,
+    meta: null,
+  });
+
+  const res = await fetch(`${base}/api/conversations/b2/prompt`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...as(store, GUEST) },
+    body: JSON.stringify({ content: "hi", model: "acme/cheap" }),
+  });
+  expect(res.status).toBe(202);
+});
+
+test("the ledger is yours to read, and everyone's only for an admin", async () => {
+  configureBudget({ tokensPerDay: 10_000 });
+  const { base, store } = freshApp();
+  charge(store, GUEST, 0.25, 4000);
+  charge(store, OWNER, 1, 9000);
+
+  const mine = (await (await fetch(`${base}/api/usage`, { headers: as(store, GUEST) })).json()) as {
+    ok: boolean;
+    spentUsd: number;
+    spentTokens: number;
+    byModel: Array<{ key: string; costUsd: number }>;
+    byUser?: unknown;
+  };
+  expect(mine.spentUsd).toBeCloseTo(0.25, 10);
+  expect(mine.spentTokens).toBe(4000);
+  expect(mine.byModel[0]?.key).toBe("acme/cheap");
+  expect(mine.byUser).toBeUndefined(); // nobody else's spending, not even in passing
+
+  expect(
+    (await fetch(`${base}/api/usage?scope=instance`, { headers: as(store, GUEST) })).status,
+  ).toBe(403);
+
+  const all = (await (
+    await fetch(`${base}/api/usage?scope=instance`, { headers: as(store, OWNER) })
+  ).json()) as { byUser: Array<{ key: string; costUsd: number }> };
+  expect(all.byUser.map((u) => u.key).sort()).toEqual([GUEST, OWNER].sort());
+});
diff --git a/tests/usage.test.ts b/tests/usage.test.ts
new file mode 100644
index 0000000..73bbadc
--- /dev/null
+++ b/tests/usage.test.ts
@@ -0,0 +1,198 @@
+import { afterEach, expect, test } from "bun:test";
+import type { LanguageModel } from "ai";
+import { Catalog } from "../src/catalog";
+import { setRegistry } from "../src/inference";
+import { ProviderRegistry } from "../src/providers";
+import { loadConfig, rolePolicy, setConfig } from "../src/settings";
+import { Store } from "../src/store";
+import { budgetStatus, costOf, DAY_MS, metered } from "../src/usage";
+
+/**
+ * The ledger and the budget it feeds.
+ *
+ * The thing worth testing hardest is the boundary between payers: a budget that
+ * counted someone's own connected account would stop them spending their own
+ * money, which is the opposite of the point.
+ */
+
+const SUB = "https://guest.test/";
+
+// This file turns auth on and installs a fixture registry; both are global, so
+// they go back the way they were found or the next file inherits them.
+afterEach(() => {
+  setConfig(null);
+});
+
+function registry(): void {
+  const catalog = Catalog.fromRaw([
+    {
+      id: "acme",
+      name: "Acme",
+      type: "openai-compat",
+      api_endpoint: "https://acme.test/v1",
+      models: [
+        {
+          id: "cheap",
+          name: "Cheap",
+          context_window: 8000,
+          cost_per_1m_in: 2,
+          cost_per_1m_out: 10,
+        },
+        { id: "free", name: "Free", context_window: 8000 },
+      ],
+    },
+  ]);
+  setRegistry(
+    new ProviderRegistry(catalog, { config: { providers: [{ id: "acme", apiKey: "$ACME_KEY" }] } }),
+  );
+}
+
+function configure(policies: Record<string, ReturnType<typeof rolePolicy>>): void {
+  const base = loadConfig({ path: "does-not-exist.json", env: {} });
+  setConfig({
+    ...base,
+    auth: { ...base.auth, enabled: true, issuer: "https://idp.test", roles: policies },
+  });
+}
+
+/** A model that reports the usage it was told to, over both call shapes. */
+function stubModel(inputTokens: number, outputTokens: number): LanguageModel {
+  const usage = { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+  return {
+    specificationVersion: "v4",
+    provider: "acme",
+    modelId: "cheap",
+    doGenerate: async () => ({ content: [], finishReason: "stop", usage, warnings: [] }),
+    doStream: async () => ({
+      stream: new ReadableStream({
+        start(controller) {
+          controller.enqueue({ type: "finish", finishReason: "stop", usage });
+          controller.close();
+        },
+      }),
+      warnings: [],
+    }),
+  } as unknown as LanguageModel;
+}
+
+async function drain(model: LanguageModel): Promise<void> {
+  const { stream } = await (
+    model as unknown as { doStream(o: unknown): Promise<{ stream: ReadableStream }> }
+  ).doStream({});
+  for await (const _ of stream as unknown as AsyncIterable<unknown>) {
+    // drain: the row is written when the stream ends
+  }
+}
+
+test("a call is priced from the catalog, per million tokens", () => {
+  registry();
+  expect(costOf("acme/cheap", 1_000_000, 0)).toBeCloseTo(2, 10);
+  expect(costOf("acme/cheap", 500_000, 100_000)).toBeCloseTo(2, 10);
+  // A model nobody prices costs nothing, rather than throwing mid-run.
+  expect(costOf("acme/free", 1_000_000, 1_000_000)).toBe(0);
+  expect(costOf("nowhere/nothing", 1_000, 1_000)).toBe(0);
+});
+
+test("a streamed call lands in the ledger when the stream drains", async () => {
+  registry();
+  const store = new Store(":memory:");
+  await drain(
+    metered(stubModel(1_000_000, 100_000), "acme/cheap", { store, sub: SUB, payer: "instance" }),
+  );
+
+  const totals = store.usageTotals({ since: 0, groupBy: "model" });
+  expect(totals).toHaveLength(1);
+  expect(totals[0]?.key).toBe("acme/cheap");
+  expect(totals[0]?.inputTokens).toBe(1_000_000);
+  expect(totals[0]?.costUsd).toBeCloseTo(3, 10); // $2 in + $1 out
+});
+
+test("a generated call lands in the ledger too", async () => {
+  registry();
+  const store = new Store(":memory:");
+  const model = metered(stubModel(1_000, 1_000), "acme/cheap", {
+    store,
+    sub: SUB,
+    payer: "user",
+    conversationId: "c1",
+  });
+  await (model as unknown as { doGenerate(o: unknown): Promise<unknown> }).doGenerate({});
+  expect(store.usageTotals({ since: 0, groupBy: "model", payer: "user" })).toHaveLength(1);
+  expect(store.usageTotals({ since: 0, groupBy: "model", payer: "instance" })).toHaveLength(0);
+});
+
+test("a budget counts the instance's spending and ignores the user's own", () => {
+  registry();
+  configure({
+    owner: rolePolicy({ admin: true, models: ["*"], subs: ["https://me.test/"] }),
+    guest: rolePolicy({ models: ["acme/*"], usdPerDay: 1 }),
+  });
+  const store = new Store(":memory:");
+  const spend = (payer: "instance" | "user", costUsd: number) =>
+    store.recordUsage({
+      ts: Date.now(),
+      sub: SUB,
+      payer,
+      service: "inference",
+      providerId: "acme",
+      modelRef: "acme/cheap",
+      inputTokens: 1000,
+      outputTokens: 100,
+      costUsd,
+    });
+
+  spend("user", 50); // their own account: never counted
+  expect(budgetStatus(store, SUB, "guest").ok).toBe(true);
+
+  spend("instance", 0.9);
+  expect(budgetStatus(store, SUB, "guest").ok).toBe(true);
+  spend("instance", 0.2);
+  const status = budgetStatus(store, SUB, "guest");
+  expect(status.ok).toBe(false);
+  expect(status.reason).toContain("$1.00");
+  expect(status.spentUsd).toBeCloseTo(1.1, 10);
+
+  // An owner with no budget is never stopped by one.
+  expect(budgetStatus(store, SUB, "owner").ok).toBe(true);
+});
+
+test("tokens bound a role whose models are priced at zero", () => {
+  registry();
+  configure({
+    owner: rolePolicy({ admin: true, models: ["*"], subs: ["https://me.test/"] }),
+    guest: rolePolicy({ models: ["acme/*"], tokensPerDay: 5_000 }),
+  });
+  const store = new Store(":memory:");
+  const spend = (tokens: number, ts = Date.now()) =>
+    store.recordUsage({
+      ts,
+      sub: SUB,
+      payer: "instance",
+      service: "inference",
+      providerId: "acme",
+      modelRef: "acme/free",
+      inputTokens: tokens,
+      outputTokens: 0,
+      costUsd: 0,
+    });
+
+  spend(4_000);
+  expect(budgetStatus(store, SUB, "guest").ok).toBe(true);
+  spend(2_000);
+  expect(budgetStatus(store, SUB, "guest").reason).toContain("5,000 tokens");
+
+  // The window rolls: yesterday's spending stops counting.
+  const fresh = new Store(":memory:");
+  fresh.recordUsage({
+    ts: Date.now() - DAY_MS - 1000,
+    sub: SUB,
+    payer: "instance",
+    service: "inference",
+    providerId: "acme",
+    modelRef: "acme/free",
+    inputTokens: 100_000,
+    outputTokens: 0,
+    costUsd: 0,
+  });
+  expect(budgetStatus(fresh, SUB, "guest").ok).toBe(true);
+});