@open-everywhere/core 0.1.0

package/agent/tools/set_spend_limit.ts

@@ -0,0 +1,529 @@
+// set_spend_limit PROPOSES a runtime spend-limit override; it never changes the cap. It validates and freezes the change and calls requestApproval, and the admin's Approve click executes the SAME `setSpendLimit` store fn the control-plane write calls — one mutation path, two front doors. `approval: never()` because the tool itself only posts a card.
+// 🔴 A USD PROPOSAL REPORTS ITS OWN PRICING COVERAGE, and never refuses on it. `monthlyUsd` is enforced against priced ledger rows, so a model with no committed rate adds $0 and the cap does not count its traffic. So a `monthlyUsd` proposal reads the scope's recent traffic and returns the models it ran on that carry no rate, under `unpricedModels` — the same field name and shape the sibling runtime write door uses (control/views.ts, and the `unpriced` flag on control/writes.ts's `set_domain_model`). An unpriced model is not an error here: the proposal still posts its card, exactly as it did before.
+// 🔴 THE REPORT REACHES THE APPROVER, not only the asking channel (OPE-1482). It is measured BEFORE the mint and FROZEN into the pending args as `coverage` (approvals/actions.ts's SpendCoverage), so the card renders it and the approver's audit row records it — the person who clicks Approve is often reading the card in another room than the one the tool replied in (approvals/card-venue.ts redirects), and a cap approved without it is a $ bound whose reader does not know which traffic it fails to meter. The tool's own reply still carries the sentence and `unpricedModels`, because the asking channel has a reader too.
+// The read sits AFTER the venue check and before `requestApproval`: a venue refusal still pays no store read, and a failed read freezes the "not measured" state rather than an empty list — see `readSpendCoverage`.
+
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { actingPrincipalId, bindFrom, type SurfaceBinding } from "../identity/binding.js";
+import { principalIdOf, unattendedOf } from "../access/request.js";
+import { untrustedIngestedThisTurn } from "../access/taint-signal.js";
+import { domainForChannel, type Domain } from "../memory/domain.js";
+import { resolvePartition } from "../memory/partition.js";
+import { getConfig } from "../access/config.js";
+import { effectiveCaps, effectiveUserCaps, domainNameForScope } from "../spend/caps.js";
+import { usageSummary } from "../spend/usage-events.js";
+import { modelPricing, soleConfiguredModel } from "../spend/pricing.js";
+import { UNKNOWN_MODEL } from "../spend/spend.js";
+import { userScopeKey, parseScopeKey } from "../access/scope-key.js";
+import { CAP_LEVELS, type CapLevel } from "../operational/store.js";
+import { requestApproval, autoApprovedNote, cardPosterFor, type RequestApprovalDeps } from "../approvals/flow.js";
+// ⚠️ A DELIBERATE IMPORT CYCLE: approvals/card-venue.ts imports `hasApprovalCardPath` from this file, and this file imports the venue walk back. It is safe only because every binding crossing the edge in both directions is a hoisted `export function` and neither module calls across it at module-eval time.
+// Do not convert either side to `const fn = () => …`, and do not call one of these at module scope: either change turns a benign ESM cycle into a TDZ ReferenceError that shows up only as a cold-start failure, which no gate in this repo runs.
+import { checkApprovalVenue, describeVenueRefusal, cardPostedPrefix, cardPostedTail } from "../approvals/card-venue.js";
+import { friendlyScopeLabel } from "../approvals/scope-label.js";
+// TYPE-ONLY, so it adds no runtime edge to the cycle the block above documents: the frozen coverage shape belongs to the args the approvals plane renders, and one definition is what keeps the card and the tool telling the same story.
+import type { SpendCoverage } from "../approvals/actions.js";
+
+// The level vocabulary is the store's. `Level` aliases `CapLevel`, so a level the store can persist and a level a proposal can name are the same set by construction.
+export const LEVELS = CAP_LEVELS;
+export type Level = CapLevel;
+
+// Re-exported so every existing call site is untouched. They belong beside `cardPosterFor`, the registry both read, and a tool module cannot be imported from the approvals plane without a cycle. One definition — the predicate must never become two.
+import { approvalPostDeps, hasApprovalCardPath } from "../approvals/flow.js";
+export { approvalPostDeps, hasApprovalCardPath };
+
+/**
+ * The card-path fence for a caller that cannot walk a venue. A slash command has no model turn to relay "your card is in #ops", and the ephemeral ack it returns — the entire user-facing answer — says the card was posted in this channel, so redirecting under it would make that one sentence false.
+ * So the fence lives at the door that makes the promise. `tool` is the caller's own name in the reader's terms, because a refusal that names the wrong verb is one the reader cannot act on.
+ */
+export function requireCardPathHere(tool: string, platform: string): void {
+  if (hasApprovalCardPath(platform)) return;
+  throw new Error(
+    `${tool} needs a surface with an approval-card path — Slack or Discord for now (this surface is "${platform}") — the approval card renders as a message with Approve/Reject buttons, and a slash command posts it in this channel or not at all. Ask me in this conversation instead: the set_spend_limit / clear_spend_limit tools route the card to a card-capable channel in this domain.`,
+  );
+}
+
+export interface SetSpendLimitInput {
+  /** ≥1 of monthlyTokens/monthlyUsd required (planSetSpendLimit enforces) — a proposal
+   *  can set a token cap, a USD cap, or both in one bridge. */
+  readonly monthlyTokens?: number;
+  readonly monthlyUsd?: number;
+  readonly reason: string;
+  readonly level?: Level;
+  readonly scopeKey?: string;
+}
+
+/** The effective caps frozen at propose time — the card's "current" figures. */
+export interface CurrentCaps {
+  readonly tokens: number | null;
+  readonly usd: number | null;
+}
+
+/**
+ * The card's "current cap" figures, read the way the GATE reads them: EFFECTIVE caps (config plus live runtime overrides), never the config baseline, or an admin approving a change on an already-overridden scope is reading a stale number. The perDomain layer is included, so a surface with an inherited domain default shows THAT figure rather than a misleading "uncapped".
+ * Per level: "domain" reads the SURFACE-shaped pair for a scope that is its own name; "user" leaves the place ladder entirely, because the person axis is not a rung on it and `effectiveCaps` would answer "uncapped" over a live allowance.
+ */
+export async function currentCapsFor(
+  org: string,
+  workspaceKey: string,
+  level: Level,
+  scopeKey: string,
+  mode: SurfaceBinding["mode"],
+  trust: SurfaceBinding["trust"],
+): Promise<CurrentCaps> {
+  if (level === "user") {
+    const parsed = parseScopeKey(scopeKey);
+    // Fail-SOFT to "uncapped" on a shape this level can't read: `assertScopeKeyShapeForLevel`
+    // rejects it a moment later in the planner with a message that says what to pass, and a
+    // throw here would replace that with a worse one.
+    const userCaps = parsed.kind === "principal" ? await effectiveUserCaps(org, parsed.platform, parsed.tenant, parsed.id) : {};
+    return { tokens: userCaps.surfaceMonthlyTokens ?? null, usd: userCaps.surfaceMonthlyUsd ?? null };
+  }
+  const capsSurfaceArg = level === "workspace" ? workspaceKey : scopeKey;
+  const capsDomainArg = level === "domain" ? scopeKey : domainNameForScope(scopeKey, mode, trust);
+  const caps = await effectiveCaps(org, workspaceKey, capsSurfaceArg, capsDomainArg);
+  return {
+    tokens: (level === "workspace" ? caps.workspaceMonthlyTokens : caps.surfaceMonthlyTokens) ?? null,
+    usd: (level === "workspace" ? caps.workspaceMonthlyUsd : caps.surfaceMonthlyUsd) ?? null,
+  };
+}
+
+/**
+ * The traffic window the pricing-coverage report reads, in days. It is the sibling read's own default (control/views.ts's `usageSummaryView` takes `sinceDays ?? 30`), NOT the cap's calendar month. A cap is most often proposed in the days after an incident, and a month-to-date window answers "no gap" for every proposal made in the first days of a month — the moment the report is worth the most.
+ */
+const COVERAGE_WINDOW_DAYS = 30;
+
+/** The label for a usage row that carries no model id at all — the same one control/views.ts's `unpricedModels` uses. The two lists are NOT interchangeable, though: `usageWindowView` prices a stampless row as undefined UNCONDITIONALLY, while the rule below applies the ledger's sole-model fallback, so the same row can be listed there and absent here. This list answers "what does a CAP fail to count", which is the ledger's question, not the view's. */
+const UNSTAMPED = "(unstamped)";
+
+/** The two labels that name an INSTRUMENTATION gap rather than a pricing one — no rate can be committed for either, because nothing observed which model ran. `spend/reporting.ts`'s `pricingNote` splits them out for the same reason: "commit a rate" would send a reader off to price a model id that does not exist. */
+const NO_MODEL_OBSERVED: readonly string[] = [UNKNOWN_MODEL, UNSTAMPED];
+
+/**
+ * The LEDGER's own $0 rule, applied to one usage row's model stamp — spend/pricing.ts's `usdMicrosAtWrite`, restated here as a predicate rather than re-derived: a stamped model prices at its own committed rate; a row with NO stamp prices at the deploy's sole configured model, when it has one. Anything neither path prices contributed $0 to the `usd_micros` column, and that column is the sum a USD cap enforces (spend/check.ts).
+ */
+function contributesZeroUsd(model: string | undefined): boolean {
+  if (model !== undefined) return modelPricing(model) === undefined;
+  const sole = soleConfiguredModel();
+  return sole === undefined || modelPricing(sole) === undefined;
+}
+
+/** What a coverage read found. `models` EMPTY plus no `notMeasurable` is the positive answer "every model this scope ran on is priced" — the two must stay tellable apart, or "we did not look" reads as "there is no gap". */
+export interface CoverageReport {
+  /** Unpriced model ids, sorted and deduplicated. */
+  readonly models: readonly string[];
+  /** Present only when this scope's traffic cannot be identified from the ledger at all — the reason, for the note. `models` is then empty and means nothing. */
+  readonly notMeasurable?: string;
+  /** The scope matched NO usage rows in the window, so nothing was priced either way. A DISTINCT answer, not a clean bill: this read is evidence about traffic that happened, and a scope with none has produced no evidence at all. It reaches the card (OPE-1482), which would otherwise render a green "every model is priced" tick over zero rows — the same false-clean-bill shape as an unmeasurable read. The tool's own note stays silent for it, deliberately: there is no missing rate for the asker to go and commit. */
+  readonly noTraffic?: true;
+}
+
+/**
+ * The rows of `all` that the named scope covers, filtered by the rule the GATE uses for that level — never a reporting rule that merely resembles it.
+ * "domain" therefore matches `domainForChannel`, exactly as `spend/caps.ts`'s `domainNameForScope` does when it resolves an EXPLICIT domain. It deliberately does NOT reuse `spend/reporting.ts`'s `filterToDomain`, which drops every `kind: "dm"` row and folds unclaimed rows into the `org` pseudo-domain: both are right for a usage report and wrong for a cap, which meters a DM that is an explicit domain member and never resolves to "org" at all.
+ * 🔴 "user" matches the person AND their platform. `usage_events.principal_id` is the UNQUALIFIED id, so a bare match collects a different person's rows wherever two vendors' id namespaces collide — the live cross-platform aliasing bug `spend/caps.ts` records removing (OPE-309). Qualified, the read is still a SUPERSET of what the allowance meters, because `spend/check.ts` applies a per-user cap on DM turns only and a row records no mode. That direction is deliberate: a report that MISSES a rate gap is the failure this exists to prevent, and over-reporting one costs the admin a sentence.
+ */
+function rowsForScope<T extends { readonly surfaceKey: string; readonly kind?: string; readonly principalId?: string }>(
+  all: readonly T[],
+  level: Level,
+  scopeKey: string,
+  domains: readonly Domain[],
+): readonly T[] {
+  if (level === "surface") return all.filter((r) => r.surfaceKey === scopeKey);
+  if (level === "domain") return all.filter((r) => domainForChannel(r.surfaceKey, domains)?.name === scopeKey);
+  if (level === "user") {
+    const parsed = parseScopeKey(scopeKey);
+    return parsed.kind === "principal" ? all.filter((r) => r.principalId === parsed.id && r.surfaceKey.startsWith(`${parsed.platform}/`)) : [];
+  }
+  return all;
+}
+
+/**
+ * The models a USD cap on this scope would NOT count: this scope's traffic over the last {@link COVERAGE_WINDOW_DAYS} days, reduced to the model ids whose calls add $0 to the ledger.
+ * The rows are read at the SPEND grain — hooks/spend.ts stamps `usage_events.surfaceKey` with `domainKeyOf`, the same key the gate matches — so the "surface" figure is an EXACT key match. A prefix match would let "slack/T1/C1" absorb "slack/T1/C11".
+ * This is EVIDENCE, not a prediction: it reports the models this scope has already run on, so a scope with no traffic in the window reports nothing. It cannot see a model the scope has not used yet.
+ * 🔴 A CRITERIA domain is NOT MEASURABLE and says so rather than answering "[]". Membership of the dm/public/org criteria layer is decided per turn from the session's MODE and TRUST (memory/domain.ts's classification), and a usage row records neither — so the rows cannot be identified. The cap on such a scope is real (`spend/caps.ts` matches a domain-level override against `domainNameForScope`, which returns a criteria domain's name), which is exactly why a silent empty list here would be a false clean bill on an enforced cap.
+ */
+export async function unpricedModelsForScope(org: string, level: Level, scopeKey: string): Promise<CoverageReport> {
+  const domains = getConfig().loadDomains();
+  const criteria = level === "domain" ? domains.find((d) => d.name === scopeKey)?.match : undefined;
+  if (criteria !== undefined) {
+    return {
+      models: [],
+      notMeasurable: `"${scopeKey}" is a CRITERIA domain — it matches ${criteria} TURNS rather than named channels — and a usage row records neither the session mode nor the trust that decide membership, so this scope's traffic cannot be identified in the ledger.`,
+    };
+  }
+  const sinceTs = new Date(Date.now() - COVERAGE_WINDOW_DAYS * 24 * 60 * 60 * 1000).toISOString();
+  // The trailing "/" makes the workspace prefix exact at the workspace boundary ("slack/T1" must not also sweep up "slack/T1X/…") — the same convention control/views.ts's usageWindowView uses. The surface prefix is an optimisation only; `rowsForScope` applies the exact match.
+  const prefix = level === "workspace" ? `${scopeKey}/` : level === "surface" ? scopeKey : undefined;
+  const all = await usageSummary(org, { sinceTs, ...(prefix !== undefined ? { surfaceKeyPrefix: prefix } : {}) });
+  const rows = rowsForScope(all, level, scopeKey, domains);
+  if (rows.length === 0) return { models: [], noTraffic: true };
+  const unpriced = new Set<string>();
+  for (const r of rows) {
+    if (contributesZeroUsd(r.model)) unpriced.add(r.model ?? UNSTAMPED);
+  }
+  return { models: [...unpriced].sort() };
+}
+
+/**
+ * The frozen card shape for one coverage read (approvals/actions.ts's `SpendCoverage`). The four
+ * states stay distinct across the freeze: a measured-and-clean scope is `"full"`, never an empty
+ * list, because the card must be able to say "every model is priced" out loud.
+ */
+export function frozenCoverage(report: CoverageReport): SpendCoverage {
+  if (report.notMeasurable !== undefined) return { measured: "none", why: report.notMeasurable };
+  if (report.noTraffic) return { measured: "no-traffic", windowDays: COVERAGE_WINDOW_DAYS };
+  if (report.models.length === 0) return { measured: "full", windowDays: COVERAGE_WINDOW_DAYS };
+  // 🔴 THE SPLIT IS MADE HERE, where the labels are known, and it is the SAME split
+  // `unpricedCoverageNote` makes for the asking channel — two gaps, two remedies. The card cannot
+  // make it for itself: `NO_MODEL_OBSERVED` is this module's vocabulary, and a card that told an
+  // approver to commit a rate for "(unstamped)" would send them after a model id that does not exist.
+  return {
+    measured: "gap",
+    windowDays: COVERAGE_WINDOW_DAYS,
+    unratedModels: report.models.filter((m) => !NO_MODEL_OBSERVED.includes(m)),
+    unobservedModels: report.models.filter((m) => NO_MODEL_OBSERVED.includes(m)),
+  };
+}
+
+/**
+ * The coverage read BOTH propose doors run — the model-driven tool and `/oe budget raise` — for the
+ * same reason the acting-sender fence lives in the shared planner: a door that forgets it posts a
+ * card whose $ figure carries no evidence, and the slash door proposes a USD cap every single time.
+ * `undefined` for a token-only proposal: a token cap counts every call, priced or not, so there is
+ * no coverage question and no store read to pay for one.
+ *
+ * FAIL-SOFT, AND IT SAYS SO. A broken usage read must not turn a proposal into an error — but it
+ * must not read as a clean bill either, and an empty report is exactly what a fully priced scope
+ * produces. So the catch returns `notMeasurable`, the same channel a criteria domain uses, and both
+ * the card and the note then say the ledger could not be read. The console warn is for the
+ * operator; it reaches nobody in the conversation.
+ */
+export async function readSpendCoverage(org: string, level: Level, scopeKey: string, monthlyUsd: number | undefined): Promise<CoverageReport | undefined> {
+  if (monthlyUsd == null) return undefined;
+  try {
+    return await unpricedModelsForScope(org, level, scopeKey);
+  } catch (e) {
+    const why = e instanceof Error ? e.message : String(e);
+    console.warn(`[open-everywhere:spend] set_spend_limit could not read pricing coverage for "${scopeKey}": ${why}`);
+    return { models: [], notMeasurable: "the usage ledger could not be read on this turn, so no coverage was measured." };
+  }
+}
+
+/**
+ * The coverage sentence the model relays, or "" when every model in the window is priced. Mirrors the sibling write door's `warning` (control/writes.ts's `set_domain_model`) — same claim, same remedy, so an admin who has read one recognises the other.
+ * TWO REMEDIES, never one. A named model with no rate is a PRICING gap and the remedy is to commit the rate. `(unknown)` / `(unstamped)` rows are an INSTRUMENTATION gap — nothing observed which model ran — and telling a reader to price them sends them off to add a model id that does not exist. `spend/reporting.ts`'s `pricingNote` already splits them for this reason.
+ * The sentence is for the ASKING channel. The approver reads the same fact off the card, from the same frozen value (OPE-1482), so this one no longer carries the whole report — but it stays, because the asker is the person who will go and commit the missing rate.
+ */
+export function unpricedCoverageNote(report: CoverageReport, scopeKey: string): string {
+  if (report.notMeasurable !== undefined) {
+    return ` ⚠ Pricing coverage NOT MEASURED for "${scopeKey}": ${report.notMeasurable} RELAY THIS: tell the user this cap's coverage is unknown — a USD cap counts only priced rows, and nothing here establishes whether this scope has any.`;
+  }
+  if (report.models.length === 0) return "";
+  const rated = report.models.filter((m) => !NO_MODEL_OBSERVED.includes(m));
+  const unobserved = report.models.filter((m) => NO_MODEL_OBSERVED.includes(m));
+  const parts = [`⚠ Pricing coverage: this scope's traffic in the last ${COVERAGE_WINDOW_DAYS} days includes calls that a USD cap on "${scopeKey}" does not count — they add $0 to the spend ledger.`];
+  if (rated.length > 0) {
+    parts.push(`${rated.length} model(s) carry no committed price: ${rated.join(", ")}. Measure the rate (\`npm run probe:models\`) and commit it in agent/spend/model-pricing.ts.`);
+  }
+  if (unobserved.length > 0) {
+    parts.push(`Some rows record no model at all (${unobserved.join(", ")}). That is an instrumentation gap, not a pricing one — no rate can be committed for them, because nothing observed which model ran.`);
+  }
+  parts.push(`The cap still sums every other priced row in the scope, and a token cap is unaffected. RELAY THIS: the $ figure does not meter all of this scope's traffic.`);
+  return ` ${parts.join(" ")}`;
+}
+
+export interface SpendSetPlan {
+  readonly kind: "spend.set";
+  readonly args: {
+    readonly org: string;
+    readonly scopeKey: string;
+    readonly level: Level;
+    readonly monthlyTokens?: number;
+    readonly monthlyUsd?: number;
+    readonly reason: string;
+    readonly currentCap: number | null; // token cap (name kept for pre-USD pending rows)
+    readonly currentUsd: number | null;
+  };
+  readonly scopeKey: string;
+  readonly domain: string | null;
+}
+
+/**
+ * scopeKey defaulting shared by the level-aware propose tools. SPEND grain (`domainSurface ?? surface`): a cap proposed from a Discord thread must target the PARENT channel — the key the gate checks and the hook records under — not the thread's own ephemeral id, which once produced an approved "cap this channel" that gated nothing. "domain" throws when none resolves here, because there is no sane default to fall back to.
+ * 🔴 "user" defaults to the ACTING sender and only ever to them. A triggered fire binds as its ATTESTED CREATOR, so the bound id would silently default a proposal onto a real person who never asked — and this is the one level where that produces a card about somebody rather than about a room.
+ */
+export function defaultScopeKey(binding: SurfaceBinding, level: Level): string {
+  const workspaceKey = `${binding.platform}/${binding.workspace}`;
+  if (level === "workspace") return workspaceKey;
+  if (level === "user") {
+    // principal-gate: presence — "my own allowance" means the HUMAN speaking on this turn, so a
+    // fire (which has only the creator it is attributed to) must not satisfy this default; it is
+    // told to name a `user:<platform>/<id>` key explicitly instead. Reading the ACTING principal
+    // is the whole fence: the bound id would silently default a proposal onto a real person who
+    // never asked.
+    const me = actingPrincipalId(binding);
+    if (!me) {
+      throw new Error(
+        `defaultScopeKey: level:"user" has no default here — there is no acting sender on this turn to mean "my own allowance" (a triggered routine fire has only the creator it is attributed to). Pass scopeKey explicitly (\`user:<platform>/<id>\`).`,
+      );
+    }
+    return userScopeKey(binding.platform, binding.workspace, me);
+  }
+  const surfaceKey = `${workspaceKey}/${binding.domainSurface ?? binding.surface}`;
+  if (level === "surface") return surfaceKey;
+  const domainName = domainNameForScope(surfaceKey, binding.mode, binding.trust);
+  if (!domainName) {
+    throw new Error(
+      `defaultScopeKey: level:"domain" has no default here — this channel isn't an explicit member of any domain, and doesn't classify into a dm/public criteria domain either. Pass scopeKey explicitly (the domain's name).`,
+    );
+  }
+  return domainName;
+}
+
+/**
+ * Refuses DEFAULT-scoped proposals from a DM, where the remaining two defaults are broken in different ways: on Discord (and any platform whose DMs carry no real workspace) `workspace` resolves to the personal DM bucket rather than the server, and `domain` classifies into the dm/public CRITERIA domain, which spans every DM in the deployment.
+ * `level: "surface"` from a DM is allowed — a DM's own surface key is enforced like any other. The domain refusal survives on BLAST RADIUS, a property of the criteria layer, not on unenforceability. An explicit scopeKey is always accepted.
+ */
+export function assertScopableFromHere(tool: string, binding: SurfaceBinding, level: Level, explicitScopeKey: string | undefined): void {
+  if (explicitScopeKey?.trim() || binding.mode === "channel") return;
+  // `level: "surface"` defaults to THIS DM's own key, which the gate enforces (OPE-267) — so it
+  // falls straight through to the accept above's siblings. Nothing to refuse.
+  if (level === "domain") {
+    throw new Error(
+      `${tool}: this is a DM, so a domain-level cap defaulted from here would land on the dm/public CRITERIA domain — which spans every DM in the deployment, not just this conversation. That caps everyone. Say scopeKey explicitly (the domain's name) if you mean it, or use level:"surface" to cap just this DM.`,
+    );
+  }
+  // `level: "user"` defaults to the ACTING sender's own allowance, which is meaningful in every room and most obviously in a DM, so there is nothing to refuse — said out loud rather than left to fall through the bottom.
+  // 🔴 `level === "workspace"` is stated EXPLICITLY. It used to be implied by position, and when "surface" stopped throwing, the guard silently became "any DM default on Discord". A condition that depends on what the branches above happen to reject is one edit away from being wrong.
+  if (level === "workspace" && binding.platform === "discord") {
+    throw new Error(
+      `${tool}: a Discord DM belongs to no server, so level:"workspace" here would target your personal DM bucket ("discord/${binding.workspace}"), not a server. Pass scopeKey "discord/<serverId>" for the server you mean — the ⛔ decline message in an over-budget channel shows it, or ask again from a channel in that server.`,
+    );
+  }
+}
+
+/**
+ * A frozen (level, scopeKey) pair that disagrees about what it addresses stores a row that MATCHES NOTHING: the card renders, the click succeeds, the audit row is written, and the cap does not exist — a configured-and-silently-unenforced budget, the worst failure mode a money gate has.
+ * Only the USER level is checked in both directions, because it is the only one whose shape is unambiguous from the key alone. A domain name and a malformed surface key are genuinely indistinguishable, so the other levels keep their latitude rather than gaining a guess.
+ */
+export function assertScopeKeyShapeForLevel(tool: string, level: Level, scopeKey: string): void {
+  const isUserKey = parseScopeKey(scopeKey).kind === "principal";
+  if (level === "user" && !isUserKey) {
+    throw new Error(
+      `${tool}: level:"user" needs a principal scope key of the form \`user:<platform>/<id>\` (e.g. "user:slack/U0123ABCD") — got "${scopeKey}", which addresses a place, not a person, and would store an allowance nobody can ever present. The over-budget decline message names the exact key.`,
+    );
+  }
+  if (level !== "user" && isUserKey) {
+    throw new Error(
+      `${tool}: "${scopeKey}" is a PERSON's scope key, so it only works with level:"user" — a ${level}-level cap on it would gate nothing. Pass level:"user", or a ${level} scope key.`,
+    );
+  }
+}
+
+/**
+ * Pure input → frozen-args mapping, with `currentCap` and `domain` already resolved by execute(), so this stays unit-testable with a fabricated binding and no I/O.
+ * BOTH front doors come through here — the model-driven tool and `/oe budget raise` — which is why the acting-sender fence lives in this function rather than in one execute(), so a future third caller inherits it instead of having to remember it.
+ */
+export function planSetSpendLimit(binding: SurfaceBinding, input: SetSpendLimitInput, current: CurrentCaps, domain: string | null): SpendSetPlan {
+  // NO CARD-PATH REFUSAL HERE ANY MORE (OPE-312), for the same reason OPE-303 took it out of
+  // `forget` / `request_access` / the connector pair: "can THIS room host a card" is not the
+  // question that decides whether a spend proposal can work. A card-less room's card is ROUTED to a
+  // card-capable channel in the SAME domain (approvals/card-venue.ts), which needs config and an
+  // async floor check and therefore belongs in execute(), not in a pure planner. The fail-closed
+  // property is preserved rather than dropped: the venue walk still refuses — naming the config to
+  // change — when the domain has nowhere to put a card.
+  //
+  // 🔴 THE OTHER FRONT DOOR HAD TO PICK THE FENCE UP. `/oe budget raise` and `/oe budget clear`
+  // (commands/core.ts) call these planners too, and a slash command cannot walk a venue: it has no
+  // model turn to relay "the card went elsewhere", and its ack sentence promises "Card posted in
+  // this channel". So `requireCardPathHere` now guards those two, where the promise is made.
+  // principal-gate: presence — a budget proposal is the credential/config plane; a fire holds no
+  // standing to move a cap, and the card's whole persuasive weight is the human name on it.
+  //
+  // 🔴 THE ACTING principal (identity/binding.ts actingPrincipalId), never the bound one (OPE-273).
+  // `binding.principalId` here was satisfied by a triggered routine fire, which binds as its
+  // routine's ATTESTED creator — a real person's id — so the gate was unreachable on a fire by
+  // construction and a fire could propose a cap raise with an org admin's name on the "asked by"
+  // line. Raising the ceiling on the agent's own spend is exactly the lever an injected fire wants,
+  // and an admin reading "requested by @alice" has no way to learn no human asked.
+  if (!actingPrincipalId(binding)) {
+    throw new Error("set_spend_limit needs a verified sender on this turn — a triggered routine fire has no acting sender (only the creator it is attributed to), and a fire may not propose a spend-limit change in that person's name. Ask a person in this conversation to propose it.");
+  }
+  if (input.monthlyTokens == null && input.monthlyUsd == null) {
+    throw new Error("set_spend_limit needs monthlyTokens or monthlyUsd — set the one the person asked for (either alone is a complete proposal), or both only if they named both.");
+  }
+  const level = input.level ?? "surface";
+  assertScopableFromHere("set_spend_limit", binding, level, input.scopeKey);
+  const scopeKey = input.scopeKey?.trim() || defaultScopeKey(binding, level);
+  assertScopeKeyShapeForLevel("set_spend_limit", level, scopeKey);
+  const reason = input.reason.trim();
+  if (!reason) {
+    throw new Error("set_spend_limit needs a non-empty reason — it's shown on the approval card.");
+  }
+  return {
+    kind: "spend.set",
+    args: {
+      org: binding.org,
+      scopeKey,
+      level,
+      ...(input.monthlyTokens != null ? { monthlyTokens: input.monthlyTokens } : {}),
+      ...(input.monthlyUsd != null ? { monthlyUsd: input.monthlyUsd } : {}),
+      reason,
+      currentCap: current.tokens,
+      currentUsd: current.usd,
+    },
+    scopeKey,
+    domain,
+  };
+}
+
+export default defineTool({
+  description:
+    'PROPOSE a monthly spend limit — token count and/or USD — for this surface (or, with level:"workspace", the whole workspace: the Slack workspace / Discord server; with level:"domain", every surface in this channel\'s memory domain; or with level:"user", ONE PERSON\'s own allowance) — this does NOT change the cap. It posts a confirmation card in this channel showing the current cap and the proposed one. Approval standing: an org admin can always decide; a domain admin whose domain covers this scope can too for "surface"/"workspace" — but a DOMAIN-LEVEL or USER-LEVEL cap needs an ORG ADMIN specifically (domain admins cannot approve or raise their own domain\'s budget, and a per-person allowance is a change about somebody who is not in the room the card lands in). Propose ONLY the component(s) the person named: monthlyUsd alone is a complete proposal, and so is monthlyTokens alone. A dollar-only request is a dollar-only proposal — never add a token cap (or a $ cap) nobody asked for; a component you leave out stays exactly as it is. A repeat of the same proposal (same level, scope and figures) while its card is still undecided posts no second card: you get the open card\'s pendingId back, so do not call again to "retry". DM turns are spend-capped like any other surface, so from a DM the default level:"surface" caps THIS DM and is accepted; level:"domain" needs an explicit scopeKey there (a DM\'s default domain spans every DM), and so does level:"workspace" on Discord (a Discord DM belongs to no server). level:"user" defaults to the person who just spoke ("my own allowance"); to change somebody ELSE\'s, pass their key explicitly as "user:<platform>/<id>". A person\'s allowance is checked INDEPENDENTLY of the room\'s cap — raising it never switches off the cap on the channel they are in. An over-budget decline message names the exact cap that stopped the turn and its key. Config-as-code (the spend budgets registry, reviewed by PR) is still the permanent way to set budgets — this is the fast runtime bridge for a one-off change an admin can approve on the spot. The posted card IS the reply to the user — do not add any narration, summary, or confirmation text after this call; the channel already sees everything the card says. EXCEPT in two cases, where the `note` carries something the channel cannot see and you MUST relay it: when this surface can\'t host a card (it then goes to a card-capable channel in the same domain, and the `note` names it), and whenever the `note` carries a "Pricing coverage" sentence (the USD cap you proposed does not count some of this scope\'s traffic, or its coverage could not be measured at all — the proposal still stands either way, this is a report, not a refusal). The approval card carries the same coverage line for the approver to read; relay the note anyway, because the person who asked is the one who can go and commit the missing rate.',
+  inputSchema: z.object({
+    monthlyTokens: z.number().int().positive().optional().describe("Proposed monthly token budget. Set it ONLY when the person asked for a token cap — omit it for a dollar-only request, and the token cap stays unchanged."),
+    monthlyUsd: z.number().positive().optional().describe("Proposed monthly USD budget (estimated $, enforced against per-row priced usage). Set it ONLY when the person asked for a $ cap — omit it for a token-only request, and the $ cap stays unchanged."),
+    reason: z.string().min(1).describe("Why you're proposing this — shown on the approval card."),
+    level: z
+      .enum(LEVELS)
+      .optional()
+      .describe(
+        '"surface" (default — this channel/DM only), "workspace" (the whole Slack workspace / Discord server), "domain" (this channel\'s memory domain — ORG ADMIN approval only), or "user" (ONE PERSON\'s own monthly allowance, checked independently of the room\'s cap — ORG ADMIN approval only).',
+      ),
+    scopeKey: z
+      .string()
+      .optional()
+      .describe(
+        'Override the scope key, e.g. "slack/T123/C456" or "discord/G123/C456" for a surface, "slack/T123" for a workspace, a domain\'s own name for level:"domain", or "user:slack/U123" for level:"user". Defaults to this surface\'s own scope — or, for level:"user", to the person who just spoke.',
+      ),
+  }),
+  outputSchema: z.object({
+    requested: z.boolean(),
+    pendingId: z.string(),
+    expiresAt: z.string().optional().describe("Absent when the chain auto-approved: the row is already decided, so nothing expires."),
+    note: z.string(),
+    autoApproved: z.boolean().optional().describe("The approver chain lowered this verb: no card was posted and it has ALREADY run."),
+    unpricedModels: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Models this scope ran on in the last 30 days that carry no committed price, so a USD cap does not count their calls ("(unstamped)" = rows with no model id). Present only on a monthlyUsd proposal that found one. 🔴 ITS ABSENCE IS NOT PROOF OF FULL COVERAGE — three different things produce it: every model was priced, the scope ran NO traffic in the window (so nothing was measured either way), or coverage could not be measured at all. `note` names only the last of the three; the approval card states which of them happened, in every case. Never report an absent field as "coverage is fine" — say the tool found no unpriced models, and leave it there. The proposal stands in all three cases.',
+      ),
+  }),
+  approval: never(),
+  async execute(input, ctx) {
+    const binding = bindFrom(ctx);
+    const level = input.level ?? "surface";
+    const scopeKey = input.scopeKey?.trim() || defaultScopeKey(binding, level);
+    // The frozen `domain` decides WHO may approve, so it must be the TARGET scope's explicit domain, never the proposing channel's: with an explicit scopeKey those differ, and freezing the proposer's would let a domain-A admin approve a mutation on a domain-B scope. No explicit domain resolves to null, which is org-admin-only and fail-closed.
+    // 🔴 A "user"-level proposal freezes `domain: null` ALWAYS, and that is load-bearing rather than incidental: it makes the domain-admin fallback structurally unreachable for this level, on top of the explicit org-admin-only carve-out, so a future edit to either fence cannot open it alone.
+    const domain = level === "user" ? null : level === "domain" ? scopeKey : (domainForChannel(scopeKey, getConfig().loadDomains())?.name ?? null);
+    const workspaceKey = `${binding.platform}/${binding.workspace}`;
+    const current = await currentCapsFor(binding.org, workspaceKey, level, scopeKey, binding.mode, binding.trust);
+
+    const plan = planSetSpendLimit(binding, input, current, domain);
+
+    // Where the card goes: this room when it can host one, otherwise a card-capable channel in the SAME domain. `checkApprovalVenue`, never the floor-blind `approvalVenueFor` — a redirect destination is chosen by config on the asker's behalf and they never see which room it picked, so a candidate the platform positively reports as externally shared is skipped.
+    // This also subsumes the old "couldn't resolve this channel's id" throw: a missing channelId simply means no own-room venue, and on a Teams personal chat, which carries none at all, that throw would have made the redirect unreachable for exactly the surface it exists to serve.
+    const venueResult = await checkApprovalVenue(binding, resolvePartition(ctx), () => getConfig().loadDomains());
+    if ("refusal" in venueResult) {
+      throw new Error(describeVenueRefusal(venueResult.refusal, binding.platform, "set that spend limit"));
+    }
+    const venue = venueResult.venue;
+
+    // Friendly display label for the card ("#proj-chat" instead of the raw id key) —
+    // resolved once at propose time and FROZEN with the args so the pending and decided
+    // renders agree. Fail-open: unresolvable → the card shows the raw scope key.
+    const scopeLabel = await friendlyScopeLabel(plan.scopeKey);
+
+    // Read here rather than in the planner because it is an execute-time session signal, not a function of the inputs — the same reason `scopeLabel` above is resolved here.
+    // Reviewer-scrutiny only, never an auto-reject: the approval plane's whole defence against an injected proposal is that a human reads the card, and "requested by @admin" alone reads as consent from someone who never asked for it.
+    const tainted = untrustedIngestedThisTurn();
+
+    // PRICING COVERAGE FOR THE $ COMPONENT — a REPORT, never a refusal (see the header rule).
+    // Read HERE: after the venue check, so a venue refusal still pays no store read, and before the
+    // mint, because the card renders it off the frozen args. A token-only proposal reads nothing.
+    const coverageReport = await readSpendCoverage(plan.args.org, plan.args.level, plan.args.scopeKey, plan.args.monthlyUsd);
+    const coverage = coverageReport === undefined ? undefined : frozenCoverage(coverageReport);
+
+    const posted = await requestApproval(
+      {
+        org: plan.args.org,
+        kind: plan.kind,
+        // 🔴 `coverage` joins the DEDUP IDENTITY by joining the frozen args, and that is the intended
+        // behaviour rather than a side effect — approvals/actions.ts's SpendSetArgs.coverage says why.
+        args: { ...plan.args, ...(scopeLabel ? { scopeLabel } : {}), ...(coverage ? { coverage } : {}), tainted },
+        scopeKey: plan.scopeKey,
+        domain: plan.domain,
+        // DELIBERATELY the PROVENANCE read and not the acting one: this is the card's "asked by"
+        // label, which answers WHO, and `principalIdOf` is the honest answer to that. The AUTHORITY
+        // question was already asked and refused in `planSetSpendLimit` above, so by here an acting
+        // principal exists and the two agree — the `!` is what that gate makes true.
+        requestedBy: principalIdOf(ctx)!,
+        channelId: venue.channelId,
+        // Thread the card under the conversation that asked for it; absent, it posts top-level. On a REDIRECT it is null regardless — a ts belongs to another workspace's channel and anchors nothing there.
+        threadTs: venue.sameRoom ? binding.threadTs ?? null : null,
+        // Mint-frozen proposing-surface identity (task #105) — the TTL sweep's feedback target,
+        // and the VENUE's key because that is where the card actually is. A stale asking-room key
+        // strands the row: the sweep and the decision wake both go looking there.
+        postedTo: venue.surfaceKey,
+        chain: { unattended: unattendedOf(ctx) },
+      },
+      // 🔴 THE VENUE's platform, not the binding's: on a redirect the card renders in the
+      // destination's chat app, and asking a card-less surface for a poster would render nothing.
+      // Discord swaps in its own CardPoster; Slack keeps the default path untouched.
+      approvalPostDeps(venue.platform, ctx),
+    );
+
+    // The asking channel's copy of the same frozen read (see `unpricedCoverageNote`).
+    const coverageNote = unpricedCoverageNote(coverageReport ?? { models: [] }, plan.args.scopeKey);
+    const coverageFields = coverageReport !== undefined && coverageReport.models.length > 0 ? { unpricedModels: [...coverageReport.models] } : {};
+
+    const proposed = [
+      ...(plan.args.monthlyTokens != null ? [`${plan.args.monthlyTokens.toLocaleString()} tokens/month (current: ${plan.args.currentCap === null ? "uncapped" : plan.args.currentCap.toLocaleString()})`] : []),
+      ...(plan.args.monthlyUsd != null ? [`$${plan.args.monthlyUsd.toFixed(2)}/month (current: ${plan.args.currentUsd === null ? "uncapped" : `$${plan.args.currentUsd.toFixed(2)}`})`] : []),
+    ].join(" + ");
+    // An identical proposal was already awaiting a click, so requestApproval handed back the LIVE card instead of minting a second one. No new card was posted this turn, so — unlike the fresh-card path — the model must relay this. A prior rejected or expired proposal never dedups.
+    // The dedup identity is the frozen (kind, scopeKey, channelId, argsJson) tuple and `channelId` here IS the venue's, so a dedup hit is by construction a live card in THIS venue. Naming it is the only way an asker in a card-less room learns where the thing they cannot see is.
+    if (posted.deduped) {
+      return {
+        requested: false,
+        pendingId: posted.id,
+        expiresAt: posted.expiresAt,
+        ...coverageFields,
+        note:
+          `Already pending — the same ${plan.args.level} limit ${proposed} on "${plan.args.scopeKey}" is awaiting an admin's Approve/Reject (pending ${posted.id}). ` +
+          `No new card was posted; tell the user the existing card${venue.sameRoom ? "" : ` in ${venue.surfaceKey}`} still needs an admin to tap Approve or Reject.` +
+          (venue.sameRoom ? "" : " Name that channel — the card is not in this conversation, so the user cannot see it from here.") +
+          coverageNote,
+      };
+    }
+    const subject = `${plan.args.level} limit ${proposed} on "${plan.args.scopeKey}"${tainted ? " ⚠ tainted" : ""}`;
+    // Chain-lowered (OPE-296) ⇒ no card, the cap is already in force. See revoke_connector.ts for
+    // why this note stops being internal-only on this branch. (Ordered AFTER the dedup check
+    // because an auto-approve never dedups — it mints a row already decided.)
+    if (posted.autoApproved) {
+      return {
+        requested: false,
+        autoApproved: true,
+        pendingId: posted.id,
+        ...coverageFields,
+        note: autoApprovedNote(subject, posted.autoApproved) + coverageNote,
+      };
+    }
+    return {
+      requested: true,
+      pendingId: posted.id,
+      expiresAt: posted.expiresAt,
+      ...coverageFields,
+      // Internal-only WHEN THE CARD IS IN THIS ROOM AND THE SCOPE'S MODELS ARE ALL PRICED: it is then the user-facing reply, so this is just the model's own bookkeeping.
+      // On a REDIRECT that posture inverts — the card is by construction invisible from here, so this note is the only way the asker learns their proposal exists at all.
+      // A PRICING-COVERAGE sentence inverts it for a different reason since OPE-1482: the APPROVER now reads coverage off the card, so this sentence is no longer their only copy — but it is still the ASKER's only copy, and the asker is the person who goes and commits the missing rate.
+      note: `${cardPostedPrefix(venue)} — ${subject} (pending ${posted.id}).` + cardPostedTail(venue, "approve it", posted) + coverageNote,
+    };
+  },
+});