auto-model-router 0.34.0 → 0.35.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.34.0",
+    "version": "0.35.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.34.0",
+      "version": "0.35.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/omp-extension/router-toast.ts

@@ -27,7 +27,8 @@
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
-import { routerAuthHeaders, routerBaseUrl } from "./router-url.ts";
+import { routerAuthHeaders, routerBaseUrl, routerHome } from "./router-url.ts";
+import { readRemoteRouter } from "./remote-logic.ts";
 import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 
 /** Raw router config.yml, or null when there is none to read. */
@@ -35,8 +36,12 @@ import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 /** Absolute path of the shared embed port file (main session writes it). */
 
 // This harness's id, matching the X-Omp-Harness header the router records.
-// Empty ⇒ toast every harness (single-harness default).
-const HARNESS_ID = process.env.OMP_HARNESS_ID ?? "";
+// In remote (team) mode the team rewrites that header to the member id from
+// the key, so remote.json's userId is the same fact — and the only way to
+// keep OTHER members' task toasts out, because task turns carry their own
+// session id and cannot be scoped by session. Empty ⇒ toast every harness
+// (single-harness default).
+const HARNESS_ID = process.env.OMP_HARNESS_ID ?? readRemoteRouter(routerHome())?.userId ?? "";
 const POLL_MS = 2_000;
 // The toast explains the choice by default: model, tier, cost, why it was picked
 // and what it was handed. `AUTO_MODEL_ROUTER_TOAST=compact` restores the one-liner.
@@ -47,6 +52,11 @@ export default function (pi: ExtensionAPI): void {
 
 	// The newest ledger entry already toasted. Ledger is `created_at_ms DESC`.
 	let lastSeenId: string | null = null;
+	// Task session → the model the task last toasted. Task turns belong to
+	// their own session ids, so this — not the session filter — is what keeps
+	// a task's forty same-model dispatches down to one toast, and surfaces the
+	// mid-task model change when an escalation switches the model.
+	const taskModels = new Map<string, string | null>();
 
 	pi.on("session_start", (_event, ctx) => {
 		// Headless/print/subagent sessions have no UI to toast into; skip the
@@ -94,7 +104,7 @@ export default function (pi: ExtensionAPI): void {
 				const entries = body.entries;
 				if (!Array.isArray(entries) || entries.length === 0) return;
 
-				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId, VERBOSE)) {
+				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId, VERBOSE, taskModels)) {
 					ctx.ui.notify(t.text, "info");
 				}
 				lastSeenId = newestId(entries) ?? lastSeenId;

package/omp-extension/toast-logic.ts

@@ -91,7 +91,7 @@ export interface ToastDecision {
 	/** The router's own decision trail, already written for people. */
 	reasons?: string[];
 	/** Classifier inputs; only a few are worth surfacing. */
-	features?: { promptTokens?: number; toolCount?: number; turnDepth?: number; isToolResultContinuation?: boolean } | null;
+	features?: { promptTokens?: number; toolCount?: number; turnDepth?: number; isToolResultContinuation?: boolean; isSubagent?: boolean } | null;
 	/** Attempt index within the turn; >0 means this served after an escalation. */
 	attempt?: number;
 	/** Prompt tokens compaction removed before dispatch. */
@@ -172,6 +172,7 @@ const tokens = (n: number): string => (n >= 1000 ? `${Math.round(n / 100) / 10}k
 export function factsOf(d: ToastDecision): string[] {
 	const out: string[] = [];
 	const f = d.features ?? undefined;
+	if (f?.isSubagent === true) out.push("task");
 	if (f?.promptTokens !== undefined && f.promptTokens > 0) out.push(`${tokens(f.promptTokens)} prompt`);
 	if (d.promptTokensSaved !== undefined && d.promptTokensSaved > 0) out.push(`${tokens(d.promptTokensSaved)} compacted`);
 	if (f?.toolCount !== undefined && f.toolCount > 0) out.push(`${f.toolCount} tools`);
@@ -215,6 +216,14 @@ export function toToastText(d: ToastDecision, verbose = true): string {
  *
  * When `harnessId` is non-empty, only entries from that harness are toasted,
  * so multiple harnesses sharing one router don't spam each other's toasts.
+ *
+ * `ompSessionId` scopes the toast to this interactive session's own turns.
+ * Subagent (task) turns carry their OWN session id — the subagent process's —
+ * so they never match it and would otherwise be invisible. They are admitted
+ * whenever the harness matches, deduplicated per task session on the served
+ * model through `subModels` (the caller holds the map across ticks): the
+ * first dispatch of a task toasts, a mid-task model change (an escalation)
+ * toasts again, and the forty same-model dispatches after it toast nothing.
  */
 export function selectToasts(
 	entries: ToastDecision[],
@@ -222,6 +231,7 @@ export function selectToasts(
 	harnessId = "",
 	ompSessionId = "",
 	verbose = true,
+	subModels?: Map<string, string | null>,
 ): ToastMessage[] {
 	if (lastSeenId === null) return [];
 	// `entries` is newest-first. Entries strictly newer than lastSeenId are the
@@ -235,7 +245,15 @@ export function selectToasts(
 		if (d === undefined) continue;
 		if (d.wasted) continue;
 		if (harnessId !== "" && d.harnessId !== harnessId) continue;
-		if (ompSessionId !== "" && d.ompSessionId !== ompSessionId) continue;
+		const isTask = d.features?.isSubagent === true;
+		if (!isTask && ompSessionId !== "" && d.ompSessionId !== ompSessionId) continue;
+		if (isTask && subModels !== undefined) {
+			const session = d.ompSessionId ?? "";
+			const model = d.servedSlug ?? d.slug;
+			// Same task, same model as last toasted: not a change, not news.
+			if (subModels.get(session) === model) continue;
+			subModels.set(session, model);
+		}
 		out.push({ model: d.servedSlug ?? d.slug, tier: d.tier, costUsd: d.reportedUsd, text: toToastText(d, verbose) });
 	}
 	return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/catalog/composite.ts

@@ -21,6 +21,7 @@
 
 import type { OllamaAvailability } from "../upstream/ollama.ts";
 import { effectiveOllamaBias, NO_USAGE, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
+import { openRouterServing, type OpenRouterCredits } from "../upstream/openrouter-usage.ts";
 import { mergeSnapshots, type OllamaCatalogSource } from "./ollama-catalog.ts";
 import type { CatalogModel, CatalogShrink, CatalogSnapshot, CatalogSource } from "./types.ts";
 
@@ -34,6 +35,10 @@ export interface CompositeBias {
 	live?: () => { costBias: number; biasUntilUsage: number };
 	/** False when OpenRouter cannot dispatch (no key): its models are listed for metadata only, never served. Default true. */
 	serveOpenRouter?: () => boolean;
+	/** Last known OpenRouter credit balance (USD), or null when never fetched. Read every combine, no network. */
+	openRouterCredits?: () => OpenRouterCredits | null;
+	/** Balance at or below which OpenRouter stops serving. 0 disables the gate. */
+	minCreditsUsd?: number;
 	/** Named upstreams' models, built from the OpenRouter models (twins) and filtered by each upstream's breaker. */
 	named?: {
 		models(openrouter: readonly CatalogModel[]): readonly CatalogModel[];
@@ -69,7 +74,7 @@ export function createCompositeCatalog(
 
 	function combine(base: CatalogSnapshot, models: readonly CatalogModel[]): CatalogSnapshot {
 		const available = availability.available();
-		const serveBase = bias.serveOpenRouter?.() ?? true;
+		const serveBase = (bias.serveOpenRouter?.() ?? true) && openRouterServing(bias.openRouterCredits?.() ?? null, bias.minCreditsUsd ?? 0);
 		const providerBias = currentBias();
 		// Named upstreams: every enabled entry's models, minus those of an upstream in cooldown.
 		const namedAll = bias.named?.models(base.models) ?? NO_NAMED;

package/src/cli/config-wizard.ts

@@ -128,6 +128,8 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "openrouter.timeoutMs", label: "Request timeout", kind: "number", min: 1, hint: "ms" },
 			{ path: "openrouter.catalogTtlMs", label: "Catalog TTL", kind: "number", min: 1, hint: "ms" },
 			{ path: "openrouter.catalogRefreshMs", label: "Catalog refresh", kind: "number", min: 0, hint: "ms, 0=off" },
+			{ path: "openrouter.minCreditsUsd", label: "Credit floor USD", kind: "number", min: 0, hint: "0=serve regardless of balance" },
+			{ path: "openrouter.usagePollMs", label: "Credits poll", kind: "number", min: 0, hint: "ms, 0=off" },
 		],
 	},
 	{

package/src/config/defaults.ts

@@ -32,6 +32,11 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// Refetch the key-scoped catalog every 5 minutes in the background so
 		// guardrail changes are picked up without waiting for traffic + TTL.
 		catalogRefreshMs: 5 * 60 * 1000,
+		// Stop serving OpenRouter at/below this balance (USD); top up to rejoin.
+		// 0 disables the gate. Mirrors ollama.blockBelowUsage's intent.
+		minCreditsUsd: 5,
+		// Balance moves slowly; 10 minutes matches the Ollama usage poll.
+		usagePollMs: 10 * 60 * 1000,
 	},
 	ollama: {
 		// Off: a second upstream changes what every turn can route to.

package/src/config/schema.ts

@@ -33,6 +33,8 @@ const openrouter = z.strictObject({
 	timeoutMs: z.number().positive().optional(),
 	catalogTtlMs: z.number().positive().optional(),
 	catalogRefreshMs: z.number().nonnegative().optional(),
+	minCreditsUsd: z.number().nonnegative().optional(),
+	usagePollMs: z.number().nonnegative().optional(),
 });
 
 const ollamaRate = z.strictObject({

package/src/config/types.ts

@@ -70,6 +70,15 @@ export interface OpenRouterConfig {
 	catalogTtlMs: number;
 	/** Background catalog refresh cadence, ms. 0 disables the periodic refresh. */
 	catalogRefreshMs: number;
+	/**
+	 * Balance (USD, `total_credits − total_usage`) at or below which OpenRouter
+	 * stops serving: its models drop from the catalog until the account is
+	 * topped up. 0 disables the gate — the 402 breaker still catches the real
+	 * thing. Default 5.
+	 */
+	minCreditsUsd: number;
+	/** Credits poll interval, ms. 0 disables the poll (and the gate never fires). */
+	usagePollMs: number;
 }
 
 /**

package/src/server/providers.ts

@@ -19,6 +19,7 @@ import { createOllamaClient, type OllamaClient } from "../upstream/ollama.ts";
 import { setKnownUpstreamIds } from "../cost/report.ts";
 import { createOllamaUsageSource, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
 import { createOpenRouterClient } from "../upstream/openrouter.ts";
+import { createOpenRouterUsageSource } from "../upstream/openrouter-usage.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
 import { createLogger, type Logger } from "../util/log.ts";
 
@@ -75,6 +76,15 @@ export function createProviders(
 		// estimate can be scaled to what ollama.com actually bills.
 		calibration: { db: sqlDb, ledgerUsd: ollamaLedgerUsd, planCreditsOverrideUsd: cfg.ollama.planCreditsUsd },
 	});
+	// OpenRouter's credit balance on the same slow cadence: at/below
+	// `openrouter.minCreditsUsd` its models drop from the catalog until the
+	// account is topped up (a 402 trip only blocks for the rate-limit minute).
+	const openrouterUsage = createOpenRouterUsageSource({
+		apiKey: () => cfg.openrouter.apiKey,
+		pollMs: cfg.openrouter.usagePollMs,
+		timeoutMs: 15_000,
+		log,
+	});
 	// Named upstreams (OpenAI, Azure, Anthropic, vLLM…): a client per id, built when
 	// first needed and kept — its breaker state must survive config reloads — while
 	// the entry it reads is looked up live, so a changed key or URL applies at once.
@@ -105,6 +115,8 @@ export function createProviders(
 			usage: ollamaUsage,
 			live: () => ({ costBias: cfg.ollama.costBias, biasUntilUsage: cfg.ollama.biasUntilUsage }),
 			serveOpenRouter: () => cfg.openrouter.apiKey !== "",
+			openRouterCredits: () => openrouterUsage.peek(),
+			minCreditsUsd: cfg.openrouter.minCreditsUsd,
 			named: { models: (base) => staticCatalog.get(base), serving: namedServingOne, bias: (id) => cfg.upstreams.find((u) => u.id === id)?.costBias ?? 1 },
 		}),
 		ollama,

package/src/upstream/anthropic.ts

@@ -340,6 +340,7 @@ export function classifyAnthropicStatus(id: string, status: number, body: unknow
 	const message = typeof msg === "string" && msg !== "" ? msg : `${id} HTTP ${status}`;
 	const fail = (kind: UpstreamErrorKind, retryable: boolean): UpstreamError => new UpstreamError(kind, status, message, retryable, body);
 	if (status === 401 || status === 403) return fail("auth", false);
+	if (status === 402) return fail("quota", true);
 	if (status === 404) return fail("model_unavailable", true);
 	if (status === 413) return fail("context_length", false);
 	if (status === 429) return fail("rate_limit", true);
@@ -431,7 +432,7 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 			/* status alone */
 		}
 		const err = classifyAnthropicStatus(id, res.status, body);
-		if (err.kind === "rate_limit" || res.status === 529) breaker.trip(err);
+		if (err.kind === "rate_limit" || err.kind === "quota" || res.status === 529) breaker.trip(err);
 		return err;
 	}
 

package/src/upstream/compat.ts

@@ -94,8 +94,10 @@ export function classifyCompatStatus(id: string, status: number, body: unknown):
 	if (status === 401) return fail("auth", false);
 	if (status === 402) return fail("quota", true);
 	if (status === 403) return /credit|quota|plan|limit|billing/i.test(message) ? fail("quota", true) : fail("moderation", true);
-	// OpenAI reports an exhausted balance as a 429 with insufficient_quota: the account, not the moment.
-	if (status === 429) return /insufficient_quota|exceeded your current quota/i.test(`${code} ${message}`) ? fail("quota", true) : fail("rate_limit", true);
+	// OpenAI reports an exhausted balance as a 429 with insufficient_quota; Kimi
+	// ("exceed your available credits given your current in-flight requests") says
+	// credits. Both are the account, not the moment.
+	if (status === 429) return /insufficient_quota|exceeded your current quota|available credits|in-flight requests/i.test(`${code} ${message}`) ? fail("quota", true) : fail("rate_limit", true);
 	if (status === 404) return fail("model_unavailable", true);
 	if (status === 400 || status === 413 || status === 422) {
 		if (/context|too many tokens|token limit|maximum context|too long/i.test(message)) return fail("context_length", false);

package/src/upstream/openrouter-usage.ts

@@ -0,0 +1,120 @@
+/**
+ * OpenRouter credit balance, polled on a slow interval and read without
+ * network on every routing decision (`GET /api/v1/credits`: management-key
+ * scope, `data.total_credits - data.total_usage` = the balance that gates a
+ * dispatch — OpenRouter reserves credits per in-flight request, so the
+ * UNRESERVED balance is what a 402 means).
+ *
+ * Mirrors the Ollama usage source: a key that is empty now may be set from
+ * the dashboard later, so the reader stays live and idles until it is not.
+ * A failed or unparseable poll keeps the last reading — the balance moves
+ * slowly, and hiding a provider on a poll glitch would route around it for
+ * nothing.
+ */
+
+import type { Logger } from "../util/log.ts";
+
+/** Minimal fetch surface, injectable for tests. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface OpenRouterCredits {
+	/** Balance in USD: total_credits − total_usage. Null when the payload lacks it. */
+	remainingUsd: number | null;
+	/** Lifetime credits bought and used, for the dashboard. */
+	totalCreditsUsd: number | null;
+	totalUsageUsd: number | null;
+	fetchedAtMs: number;
+}
+
+export interface OpenRouterUsageSource {
+	/** Latest reading, refreshed when older than the poll interval; last good value on failure. */
+	get(): Promise<OpenRouterCredits | null>;
+	/** Last fetched value without touching the network. */
+	peek(): OpenRouterCredits | null;
+}
+
+export const NO_OPENROUTER_USAGE: OpenRouterUsageSource = { get: async () => null, peek: () => null };
+
+function parseCredits(json: unknown): OpenRouterCredits | null {
+	if (typeof json !== "object" || json === null || !("data" in json)) return null;
+	const data: unknown = json.data;
+	if (typeof data !== "object" || data === null) return null;
+	const d = data as Record<string, unknown>; // narrowed above; cast names the wire shape once
+	const total = typeof d.total_credits === "number" ? d.total_credits : null;
+	const used = typeof d.total_usage === "number" ? d.total_usage : null;
+	if (total === null || used === null) return null;
+	return { remainingUsd: total - used, totalCreditsUsd: total, totalUsageUsd: used, fetchedAtMs: Date.now() };
+}
+
+export function createOpenRouterUsageSource(opts: {
+	apiKey: () => string;
+	pollMs: number;
+	timeoutMs: number;
+	log: Logger;
+	fetchImpl?: FetchLike;
+	root?: string;
+}): OpenRouterUsageSource {
+	if (opts.pollMs <= 0) return NO_OPENROUTER_USAGE;
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const root = (opts.root ?? "https://openrouter.ai/api/v1").replace(/\/+$/, "");
+	let current: OpenRouterCredits | null = null;
+	let checkedAtMs = 0;
+	let inflight: Promise<OpenRouterCredits | null> | null = null;
+	let warned = false;
+
+	async function refresh(): Promise<OpenRouterCredits | null> {
+		try {
+			const res = await fetchImpl(`${root}/credits`, {
+				headers: { authorization: `Bearer ${opts.apiKey()}` },
+				signal: AbortSignal.timeout(opts.timeoutMs),
+			});
+			if (res.ok) {
+				const parsed = parseCredits(await res.json());
+				if (parsed !== null) {
+					current = parsed;
+					warned = false;
+				} else if (!warned) {
+					warned = true;
+					opts.log.warn("openrouter credits payload had no recognisable fields; credit gate keeps its last reading");
+				}
+			} else if (!warned) {
+				warned = true;
+				opts.log.warn("openrouter credits endpoint unavailable; credit gate keeps its last reading", { status: res.status });
+			}
+		} catch (err) {
+			if (!warned) {
+				warned = true;
+				opts.log.warn("openrouter credits fetch failed; credit gate keeps its last reading", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		}
+		checkedAtMs = Date.now();
+		return current;
+	}
+
+	return {
+		async get() {
+			if (opts.apiKey() === "") return null;
+			if (Date.now() - checkedAtMs < opts.pollMs) return current;
+			inflight ??= refresh().finally(() => {
+				inflight = null;
+			});
+			return inflight;
+		},
+		peek: () => current,
+	};
+}
+
+/**
+ * True while OpenRouter may serve: the balance is strictly above the floor, or
+ * unknown (a poll that has not landed yet, no key for the endpoint, a payload
+ * change). Hiding on unknown would take a provider down for a dashboard's
+ * missing field — fail open instead; the 402 breaker still catches the real
+ * thing.
+ */
+export function openRouterServing(credits: OpenRouterCredits | null, minCreditsUsd: number): boolean {
+	if (minCreditsUsd <= 0) return true;
+	if (credits === null || credits.remainingUsd === null) return true;
+	return credits.remainingUsd > minCreditsUsd;
+}

package/src/upstream/openrouter.ts

@@ -55,7 +55,12 @@ function classifyStatus(status: number, body: unknown): UpstreamError {
 	// retrying is pointless.
 	if (status === 401) return fail("auth", false);
 	// 402 = out of credits; retrying changes nothing, only topping up does.
-	if (status === 402) return fail("auth", false);
+	// EXCEPT the concurrency shape: OpenRouter reserves credits for in-flight
+	// requests, so a burst can exhaust the UNRESERVED balance on an account
+	// with plenty left ("would exceed your available credits given your
+	// current in-flight requests"). That clears when the streams settle —
+	// a moment, not an account state — so fail over like a rate limit.
+	if (status === 402) return /in-flight requests/i.test(message) ? fail("rate_limit", true) : fail("auth", false);
 	// 403 = provider content-moderation or per-model policy gate (prompt-injection
 	// block, age/data-policy confirmation). This indicts the model/provider, NOT
 	// the key: siblings routinely serve the same content. Retryable so the turn

package/test/failover.test.ts

@@ -31,7 +31,7 @@ import type {
 function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 	return {
 		server: { host: "127.0.0.1", port: 8787, maxConcurrentTurns: 24, subagentProfile: "auto-sub" },
-		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0 },
+		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0, minCreditsUsd: 0, usagePollMs: 0 },
 		ollama: { enabled: false, baseUrl: "http://127.0.0.1:11434/v1", apiKey: "", timeoutMs: 30_000, catalogTtlMs: 300_000, includeLocal: false, prices: {}, twins: {}, costBias: 1, biasUntilUsage: 0.9, usagePollMs: 0, quotaCooldownMs: 0, rateLimitCooldownMs: 0, planCreditsUsd: 0 },
 		upstreams: [],
 		benchmarks: { enabled: false, artificialAnalysisApiKey: "", benchlm: true, refreshMs: 86_400_000, timeoutMs: 30_000, useLocalScores: false },
@@ -380,6 +380,33 @@ describe("same-tier failover", () => {
 		expect(finishes[0]!.attempts).toBe(2);
 	});
 
+	test("a Kimi credit 429 fails over to another provider's model in the SAME turn", async () => {
+		// Moonshot's balance wording misclassified as rate_limit used to let the
+		// raw 429 (Retry-After 30 min) reach the client. Quota is retryable
+		// elsewhere: the retry re-routes with the failed slug excluded.
+		const { router, calls } = mkRouter([mkDecision("moderate", "kimi/kimi-k3"), mkDecision("moderate", "openrouter/grok-4")]);
+		const { upstream, calls: dispatches } = mkUpstream([
+			{ kind: "fail", error: new UpstreamError("quota", 429, "This request would exceed your available credits given your current in-flight requests", true) },
+			{ kind: "chunks", chunks: okChunks("openrouter/grok-4") },
+		]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors, finishes } = mkSink();
+
+		await runTurn(mkReq(), sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog, context: createDisabledBridge() }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(finishes).toHaveLength(1);
+		expect(calls).toHaveLength(2);
+		expect(calls[1]).toEqual({ attempt: 1, excludeSlugs: ["kimi/kimi-k3"] });
+		expect(dispatches.map((d) => d.body.model)).toEqual(["kimi/kimi-k3", "openrouter/grok-4"]);
+		expect(entries[0]!.error).toContain("available credits");
+		expect(entries[0]!.wasted).toBe(true);
+		expect(entries[1]!.wasted).toBe(false);
+		expect(finishes[0]!.servedSlug).toBe("openrouter/grok-4");
+		expect(finishes[0]!.escalated).toBe(false);
+	});
+
 	test("a 403 moderation block fails over to a different model in the same tier", async () => {
 		const { router, calls } = mkRouter([mkDecision("trivial", "a/model"), mkDecision("trivial", "b/model")]);
 		const { upstream, calls: dispatches } = mkUpstream([
@@ -664,6 +691,7 @@ describe("same-tier failover", () => {
 
 });
 
+
 describe("400 classification (review 2026-09-05 follow-up)", () => {
 	test("a 400 naming a model capability limit is retryable, so failover picks a sibling", async () => {
 		const e = classifyUpstreamStatus(400, { error: { message: "This model only supports single tool-calls at once!" } });
@@ -677,6 +705,19 @@ describe("400 classification (review 2026-09-05 follow-up)", () => {
 		expect(e.retryable).toBe(false);
 	});
 
+	test("an OpenRouter 402 naming in-flight requests is a concurrency throttle, retryable like a rate limit", async () => {
+		// OpenRouter reserves credits per in-flight request: a burst can exhaust
+		// the UNRESERVED balance on an account with plenty left. It clears when
+		// the streams settle — fail over, never surface to the client.
+		const e = classifyUpstreamStatus(402, { error: { message: "This request would exceed your available credits given your current in-flight requests. Retry after in-flight requests settle, or add credits." } });
+		expect(e.kind).toBe("rate_limit");
+		expect(e.retryable).toBe(true);
+		// A plain 402 (balance actually gone) stays final.
+		const broke = classifyUpstreamStatus(402, { error: { message: "Insufficient credits" } });
+		expect(broke.kind).toBe("auth");
+		expect(broke.retryable).toBe(false);
+	});
+
 	test("a 400 for context overflow is still context_length", async () => {
 		const e = classifyUpstreamStatus(400, { error: { message: "This endpoint's maximum context length is 131072 tokens" } });
 		expect(e.kind).toBe("context_length");

package/test/openrouter-usage.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { createOpenRouterUsageSource, NO_OPENROUTER_USAGE, openRouterServing, type OpenRouterCredits } from "../src/upstream/openrouter-usage.ts";
+import { createLogger } from "../src/util/log.ts";
+
+const log = createLogger("error");
+
+function credits(remaining: number | null): OpenRouterCredits | null {
+	return remaining === null ? null : { remainingUsd: remaining, totalCreditsUsd: 100, totalUsageUsd: 100 - remaining, fetchedAtMs: 1 };
+}
+
+describe("openRouterServing", () => {
+	test("serves above the floor and stops at/below it", () => {
+		expect(openRouterServing(credits(5.01), 5)).toBe(true);
+		expect(openRouterServing(credits(5), 5)).toBe(false);
+		expect(openRouterServing(credits(0), 5)).toBe(false);
+	});
+
+	test("fails open on unknown balance and when the gate is off", () => {
+		expect(openRouterServing(null, 5)).toBe(true);
+		expect(openRouterServing(credits(0), 0)).toBe(true);
+	});
+});
+
+describe("createOpenRouterUsageSource", () => {
+	test("returns null without a key and parses the credits payload", async () => {
+		const unkeyed = createOpenRouterUsageSource({ apiKey: () => "", pollMs: 1000, timeoutMs: 100, log, root: "https://x/v1" });
+		expect(await unkeyed.get()).toBe(null);
+		expect(NO_OPENROUTER_USAGE.peek()).toBe(null);
+
+		let calls = 0;
+		const src = createOpenRouterUsageSource({
+			apiKey: () => "k",
+			pollMs: 1000,
+			timeoutMs: 100,
+			log,
+			root: "https://x/v1",
+			fetchImpl: async () => {
+				calls++;
+				return new Response(JSON.stringify({ data: { total_credits: 20, total_usage: 13.5 } }), { status: 200 });
+			},
+		});
+		const v = await src.get();
+		expect(calls).toBe(1);
+		expect(v?.remainingUsd).toBe(6.5);
+		expect(src.peek()?.totalUsageUsd).toBe(13.5);
+
+		// A failed poll keeps the last good reading instead of hiding the provider.
+		const failing = createOpenRouterUsageSource({
+			apiKey: () => "k",
+			pollMs: 0,
+			timeoutMs: 100,
+			log,
+			root: "https://x/v1",
+			fetchImpl: async () => new Response("nope", { status: 500 }),
+		});
+		await failing.get();
+		expect(failing.peek()).toBe(null); // never had a reading; gate stays open on unknown
+	});
+});

package/test/toast-logic.test.ts

@@ -176,6 +176,61 @@ describe("selectToasts", () => {
 		expect(toasts).toHaveLength(1);
 		expect(toasts[0]?.model).toBe("keep");
 	});
+
+	test("task (subagent) turns toast even though they carry their own session id", async () => {
+		// A task's dispatches carry the subagent's own session id and the
+		// isSubagent flag, so the session filter must not drop them.
+		const entries = [
+			dec({ id: "d2", slug: "x/task-model", ompSessionId: "task-1", features: { isSubagent: true } }),
+			dec({ id: "d1", slug: "prior", ompSessionId: "sess-a" }),
+		];
+		const subModels = new Map<string, string | null>();
+		const toasts = selectToasts(entries, "d1", "", "sess-a", true, subModels);
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]?.model).toBe("x/task-model");
+		expect(toasts[0]!.text).toContain("task");
+	});
+
+	test("a task toasts once per model: the first dispatch and every change after", async () => {
+		const entries = [
+			dec({ id: "d5", slug: "x/m2", ompSessionId: "task-1", features: { isSubagent: true } }),
+			dec({ id: "d4", slug: "x/m1", ompSessionId: "task-1", features: { isSubagent: true } }),
+			dec({ id: "d3", slug: "x/m1", ompSessionId: "task-1", features: { isSubagent: true } }),
+			dec({ id: "d2", slug: "x/m1", ompSessionId: "task-1", features: { isSubagent: true } }),
+		];
+		const subModels = new Map<string, string | null>();
+		const first = selectToasts(entries, "d1", "", "sess-a", true, subModels);
+		// oldest→newest: m1 (first dispatch toasts), m1 (skip), m1 (skip), m2 (change, toasts)
+		expect(first.map((t) => t.model)).toEqual(["x/m1", "x/m2"]);
+		// The next tick remembers the task's last model: the same model again is not news.
+		const again = selectToasts([dec({ id: "d6", slug: "x/m2", ompSessionId: "task-1", features: { isSubagent: true } })], "d5", "", "sess-a", true, subModels);
+		expect(again).toHaveLength(0);
+		// A second task with its own session id toasts its own first dispatch.
+		const other = selectToasts([dec({ id: "d7", slug: "x/m3", ompSessionId: "task-2", features: { isSubagent: true } })], "d6", "", "sess-a", true, subModels);
+		expect(other).toHaveLength(1);
+		expect(other[0]?.model).toBe("x/m3");
+	});
+
+	test("task toasts respect the harness filter: another member's tasks stay out", async () => {
+		const entries = [
+			dec({ id: "d2", slug: "theirs", ompSessionId: "task-9", harnessId: "member-b", features: { isSubagent: true } }),
+			dec({ id: "d1", slug: "mine", ompSessionId: "task-8", harnessId: "member-a", features: { isSubagent: true } }),
+			dec({ id: "d0", slug: "prior", ompSessionId: "sess-a", harnessId: "member-a" }),
+		];
+		const subModels = new Map<string, string | null>();
+		const toasts = selectToasts(entries, "d0", "member-a", "sess-a", true, subModels);
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]?.model).toBe("mine");
+	});
+
+	test("a main-session turn still toasts every dispatch, unchanged", async () => {
+		const entries = [
+			dec({ id: "d3", slug: "x/m1", ompSessionId: "sess-a" }),
+			dec({ id: "d2", slug: "x/m1", ompSessionId: "sess-a" }),
+			dec({ id: "d1", slug: "prior", ompSessionId: "sess-a" }),
+		];
+		expect(selectToasts(entries, "d1", "", "sess-a", true)).toHaveLength(2);
+	});
 });
 
 describe("toToastText", () => {

package/test/turn.test.ts

@@ -34,7 +34,7 @@ import type {
 function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 	return {
 		server: { host: "127.0.0.1", port: 8787, maxConcurrentTurns: 24, subagentProfile: "auto-sub" },
-		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0 },
+		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0, minCreditsUsd: 0, usagePollMs: 0 },
 		ollama: { enabled: false, baseUrl: "http://127.0.0.1:11434/v1", apiKey: "", timeoutMs: 30_000, catalogTtlMs: 300_000, includeLocal: false, prices: {}, twins: {}, costBias: 1, biasUntilUsage: 0.9, usagePollMs: 0, quotaCooldownMs: 0, rateLimitCooldownMs: 0, planCreditsUsd: 0 },
 		upstreams: [],
 		benchmarks: { enabled: false, artificialAnalysisApiKey: "", benchlm: true, refreshMs: 86_400_000, timeoutMs: 30_000, useLocalScores: false },

package/test/upstreams.test.ts

@@ -193,6 +193,8 @@ describe("the OpenAI-compatible client", () => {
 	test("statuses: OpenAI's insufficient_quota 429 is the account, a plain 429 the moment; 400 context is final", async () => {
 		expect(classifyCompatStatus("x", 429, { error: { code: "insufficient_quota", message: "You exceeded your current quota" } })).toMatchObject({ kind: "quota", retryable: true });
 		expect(classifyCompatStatus("x", 429, { error: { message: "Rate limit reached" } })).toMatchObject({ kind: "rate_limit", retryable: true });
+		// Kimi's balance wording: 429 but the account, so the 15-minute quota cooldown hides the whole upstream.
+		expect(classifyCompatStatus("kimi", 429, { error: { message: "This request would exceed your available credits given your current in-flight requests" } })).toMatchObject({ kind: "quota", retryable: true });
 		expect(classifyCompatStatus("x", 400, { error: { message: "This model's maximum context length is 8192 tokens" } })).toMatchObject({ kind: "context_length", retryable: false });
 		expect(classifyCompatStatus("x", 401, {})).toMatchObject({ kind: "auth", retryable: false });
 		expect(classifyCompatStatus("x", 503, {})).toMatchObject({ kind: "upstream_error", retryable: true });
@@ -238,6 +240,18 @@ describe("the OpenAI-compatible client", () => {
 		expect(caught).toMatchObject({ kind: "quota", retryable: true });
 		expect(broke.available()).toBe(false);
 		expect(broke.lastTrip()?.kind).toBe("quota");
+		const kimiBroke = createCompatClient(cfg, "openai-direct", async () =>
+			Response.json({ error: { message: "This request would exceed your available credits given your current in-flight requests" } }, { status: 429 }),
+		);
+		caught = null;
+		try {
+			await kimiBroke.dispatch({ body: { model: "openai-direct/gpt-4o", messages: [] }, sessionId: "s", signal: new AbortController().signal });
+		} catch (err) {
+			caught = err;
+		}
+		expect(caught).toMatchObject({ kind: "quota", retryable: true });
+		expect(kimiBroke.available()).toBe(false);
+		expect(kimiBroke.lastTrip()?.kind).toBe("quota");
 		// The live key applies to the next call without a new client.
 		applyConfigPatch(cfg, { upstreams: [{ id: "openai-direct", kind: "openai", baseUrl: "https://api.openai.com/v1", apiKey: "sk-new", models: [{ id: "gpt-4o", input: 2.5, output: 10 }] }] } as never);
 		await client.dispatch({ body: { model: "openai-direct/gpt-4o", messages: [], stream: true }, sessionId: "s", signal: new AbortController().signal });
@@ -363,8 +377,20 @@ describe("the Anthropic client", () => {
 		}
 		expect(caught).toMatchObject({ kind: "upstream_error", retryable: true });
 		expect(overloaded.available()).toBe(false);
+		const billedOut = createAnthropicClient(cfg, "anthropic-direct", async () => Response.json({ error: { message: "Your credit balance is too low" } }, { status: 402 }));
+		caught = null;
+		try {
+			await billedOut.dispatch({ body: { model: "anthropic-direct/claude-sonnet-4", messages: [] }, sessionId: "s", signal: new AbortController().signal });
+		} catch (err) {
+			caught = err;
+		}
+		expect(caught).toMatchObject({ kind: "quota", retryable: true });
+		expect(billedOut.available()).toBe(false);
+		expect(billedOut.lastTrip()?.kind).toBe("quota");
 		expect(classifyAnthropicStatus("a", 400, { error: { message: "prompt is too long: 250000 tokens" } })).toMatchObject({ kind: "context_length", retryable: false });
 		expect(classifyAnthropicStatus("a", 401, {})).toMatchObject({ kind: "auth", retryable: false });
+		// The credit card said no (402): the account, not the moment — quota, and the breaker hides the upstream.
+		expect(classifyAnthropicStatus("a", 402, { error: { message: "Your credit balance is too low" } })).toMatchObject({ kind: "quota", retryable: true });
 	});
 
 	test("a subscription upstream: OAuth bearer instead of x-api-key, and the Claude Code identity leads the system blocks", async () => {