feat: model + thinking control — the stats bar's picker, on pi-ai's catalog

The model-control wave (user-decided design, 2026-09-12): ONE controller
for the conversation agents (prober/teacher are functionally one agent);
background sub-agents stay config-pinned. pi-ai owns the registry — the
shipped 366-model OpenRouter catalog (cost, context, modality,
thinkingLevelMap), getSupportedThinkingLevels/clampThinkingLevel for the
per-model thinking truth, and streamSimple's automatic clamp. No second
registry to drift out of sync.

Seams:
- config.ts: ReasoningEffort retired for pi's ThinkingLevel
  (off|minimal|low|medium|high|xhigh|max). GLM roles go honest at "low" —
  pi's catalog says GLM-5.3-flash accepts exactly low|high|max, and the old
  "minimal" was silently clamped to low by streamSimple since the swap;
  nothing changes behaviorally. visualMaker → qwen/qwen3.8-flash (fixes
  the dead qwen/qwen3.8-max slug — the catalog only ships -0902; also the
  user's cost pick, 0.15/0.47 per-1M).
- src/agent/models.ts: piEngineFor(role, settings?) — provider+id resolved
  from the catalog, thinking level from settings ?? config, CLAMPED to the
  model's supported list (a settings change between models can never send
  an invalid level). PiEngine gains `level` (observability/tests).
- ChatRecord.settings {model?: {provider, id}, thinkingLevel?} — written
  by PUT /api/chats/[id]/settings (replace-whole, no updatedAt churn),
  read by chat-handler at turn composition: agents are stateless per turn,
  so the change is next-turn-effective by construction. The turns log
  still records the ACTUAL billed model (the honest witness).
- GET /api/models: the configured-provider catalog as client-safe DTOs
  (core/contracts/models.ts) + config defaults; a second provider joins
  the picker by registering it in piModels() — nothing else changes.
- PUT settings validation gate (src/server/model-catalog.ts): unknown
  provider/model or unsupported level → 400 carrying the supported list,
  never a silent clamp.
- scripts/sync-pricing.ts: regenerated PRICES/CONTEXT_LIMITS from pi-ai's
  shipped openrouter.json (offline; same source as the engine + picker).
  All 366 models priced; glm's stale 0.15/0.5 → pi's 0.075/0.25, limit
  1310720 → 1048576 — cost is inferred at read time, so history re-prices.
- UI (components/model-picker.tsx): stats-bar right side becomes model +
  thinking buttons; menus open ABOVE; fuzzy search over "provider id
  name" (core/fuzzy.ts — pi's /model pattern); model rows show name/id/
  price/context; the thinking menu lists exactly the chosen model's
  supported levels (GLM: low|high|max — no dead options, no "off").
  Model switch drops an incompatible pinned level (falls back to config,
  which clamps honestly) rather than carrying a 400.

Tests (350/350, +15): catalog projection + defaults, the settings gate,
pi thinking truth pinned against upgrades (glm low|high|max; minimal→low;
off→low — GLM cannot disable thinking), the engine factory's
override/fallback/clamp/throw matrix, fuzzy ranking, store round-trip,
and the re-priced folds (usage, stats bar, activity dock).

Live smoke (disposable driver, deleted): catalog route 366 + defaults;
glm+minimal → 400 + supported; turn 1 billed qwen/qwen3.8-flash under
the override; mid-session switch flipped turn 2 to glm; clear-overrides
restored the config pin. ALL CHECKS PASS on real OpenRouter.

components/chat.tsx

@@ -21,6 +21,7 @@ import { SubagentSteerCard } from "@/components/artifacts/steer-card";
 import { Composer } from "@/components/composer";
 import { JobsContext } from "@/components/jobs-context";
 import { StatsBar } from "@/components/stats-bar";
+import type { ChatSettings } from "@/src/core";
 import { PlanBlock, PlanPopup, latestTree } from "@/components/plan-block";
 import { PlanWindow } from "@/components/plan-window";
 import type { PlanBlockData } from "@/src/core";
@@ -85,6 +86,7 @@ export function Chat({
 	initialMessages,
 	initialPrompt,
 	initiallyInFlight,
+	initialSettings,
 }: {
 	chatId: string;
 	title: string;
@@ -93,6 +95,8 @@ export function Chat({
 	/** A teacher turn is running server-side but attached to no client
 	 * (navigated away mid-turn, returned while in flight). */
 	initiallyInFlight?: boolean;
+	/** The record's per-chat model/thinking settings (the picker's seed). */
+	initialSettings?: ChatSettings;
 }) {
 	const { messages, sendMessage, addToolOutput, setMessages, status, error, stop } =
 		useChat<TeacherUIMessage>({
@@ -250,6 +254,9 @@ export function Chat({
 	// server-side), and kept fresh by syncFromServer whenever it already
 	// fetches the record. No turns yet → the bar renders "—" everywhere.
 	const [turns, setTurns] = useState<TurnUsage[]>([]);
+	// The per-chat model control state (model-picker writes via PUT; the
+	// record is the source of truth, lifted here so the stats bar re-renders).
+	const [settings, setSettings] = useState<ChatSettings | undefined>(initialSettings);
 	const syncTurns = useCallback(async () => {
 		try {
 			const res = await fetch(`/api/chats/${chatId}`);
@@ -582,6 +589,9 @@ export function Chat({
 
 						<DockOverlay
 							pending={pending}
+							chatId={chatId}
+							settings={settings}
+							onSettingsSaved={setSettings}
 							requiresReveal={requiresReveal}
 							phase={phases.at(-1) ?? "probe"}
 							turns={turns}
@@ -645,6 +655,9 @@ function DockOverlay({
 	turns,
 	composer,
 	onSubmitAnswer,
+	chatId,
+	settings,
+	onSettingsSaved,
 }: {
 	pending: ReturnType<typeof findPendingToolCall>;
 	/** Teach-phase pending question: arrives collapsed behind the reveal button (W5). */
@@ -655,6 +668,10 @@ function DockOverlay({
 	turns: TurnUsage[];
 	composer: React.ReactNode;
 	onSubmitAnswer: (output: QuestionAnswerData) => void;
+	/** The model control's pass-through (the stats bar hosts it). */
+	chatId: string;
+	settings?: ChatSettings;
+	onSettingsSaved: (settings: ChatSettings) => void;
 }) {
 	const { isAtBottom, scrollToBottom, scrollRef } = useStickToBottomContext();
 	// Teach-phase mount (session reload with a pending check): the dock starts
@@ -818,7 +835,12 @@ function DockOverlay({
 					{/* The stats row: beneath the composer/question shell, not
 					    flush to the screen bottom — static height, outside the
 					    morphing shell so it never joins a height animation. */}
-					<StatsBar turns={turns} />
+					<StatsBar
+						turns={turns}
+						chatId={chatId}
+						settings={settings}
+						onSettingsSaved={onSettingsSaved}
+					/>
 				</div>
 			</div>
 		</div>

components/model-picker.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+/**
+ * The model + thinking control (model-control wave, 2026-09-12) — the stats
+ * bar's right side. ONE controller for the conversation agents (prober +
+ * teacher are functionally one agent); background sub-agents stay
+ * config-pinned. Writes go to PUT /api/chats/[id]/settings (validated
+ * server-side against pi-ai's catalog) and take effect on the next turn by
+ * construction — the agents are stateless per turn.
+ *
+ * The data is pi-ai's catalog (GET /api/models): the model menu is a fuzzy
+ * search over "provider id name" (core/fuzzy.ts — pi's /model pattern), and
+ * the thinking menu lists EXACTLY the chosen model's supported levels
+ * (getSupportedThinkingLevels — GLM-5.3-flash shows low|high|max, never a
+ * level it would silently clamp). Menus open ABOVE the buttons (the
+ * composer owns everything below).
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	fuzzyScore,
+	type ChatSettings,
+	type ModelCatalogEntry,
+	type ModelCatalogResponse,
+} from "@/src/core";
+import { formatTokens, prettyModel } from "@/components/usage-format";
+
+/** GET /api/models is fetched once per page load and shared by every
+ *  picker instance (the catalog is static within a pi-ai version). */
+let catalogCache: ModelCatalogResponse | undefined;
+let catalogInflight: Promise<ModelCatalogResponse> | undefined;
+
+function fetchCatalog(): Promise<ModelCatalogResponse> {
+	catalogInflight ??= fetch("/api/models")
+		.then((r) => {
+			if (!r.ok) throw new Error(`catalog request failed: ${r.status}`);
+			return r.json() as Promise<ModelCatalogResponse>;
+		})
+		.then((c) => {
+			catalogCache = c;
+			return c;
+		})
+		.catch((err) => {
+			catalogInflight = undefined; // retry on next mount
+			throw err;
+		});
+	return catalogInflight;
+}
+
+function useModelCatalog(): ModelCatalogResponse | undefined {
+	const [catalog, setCatalog] = useState(catalogCache);
+	useEffect(() => {
+		if (catalogCache) return;
+		let alive = true;
+		fetchCatalog()
+			.then((c) => alive && setCatalog(c))
+			.catch(() => {
+				/* the picker stays closed on failure; the buttons still display
+				   the effective model from props */
+			});
+		return () => {
+			alive = false;
+		};
+	}, []);
+	return catalog;
+}
+
+const LEVEL_LABEL: Record<string, string> = {
+	off: "Off",
+	minimal: "Minimal",
+	low: "Low",
+	medium: "Medium",
+	high: "High",
+	xhigh: "Xhigh",
+	max: "Max",
+};
+
+/** USD per 1M tokens, compact: "$0.08 in · $0.25 out". */
+function priceLabel(cost: ModelCatalogEntry["cost"]): string {
+	const fmt = (n: number) => `$${n < 1 ? n.toFixed(2).replace(/0$/, "") : n.toFixed(2)}`;
+	return `${fmt(cost.input)}/${fmt(cost.output)}`;
+}
+
+export function ModelControl({
+	chatId,
+	settings,
+	onSaved,
+	fallbackModelId,
+}: {
+	chatId: string;
+	/** The record's current settings (undefined = config pin). */
+	settings?: ChatSettings;
+	/** Lifts the persisted settings into the chat view's state. */
+	onSaved: (settings: ChatSettings) => void;
+	/** The last turn's actual model (from the turns log) — the label until
+	 *  the catalog (with config's defaults) finishes loading. */
+	fallbackModelId?: string;
+}) {
+	const catalog = useModelCatalog();
+	const [open, setOpen] = useState<"model" | "thinking" | null>(null);
+	const [query, setQuery] = useState("");
+	const [error, setError] = useState<string | null>(null);
+	const searchRef = useRef<HTMLInputElement>(null);
+
+	const defaults = catalog?.defaults;
+	const effectiveId = settings?.model?.id ?? defaults?.model.id ?? fallbackModelId;
+	const effectiveLevel =
+		settings?.thinkingLevel ?? defaults?.thinkingLevel;
+	const entry = catalog?.models.find((m) => m.id === effectiveId);
+	const levels = entry?.supportedLevels ?? [];
+
+	// Focus the search box when the model menu opens (pi's /model feel).
+	useEffect(() => {
+		if (open === "model") searchRef.current?.focus();
+	}, [open]);
+
+	const save = useCallback(
+		async (next: ChatSettings) => {
+			setError(null);
+			try {
+				const res = await fetch(`/api/chats/${chatId}/settings`, {
+					method: "PUT",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(next),
+				});
+				if (!res.ok) {
+					const body = (await res.json().catch(() => ({}))) as { error?: string };
+					setError(body.error ?? `settings rejected (${res.status})`);
+					return;
+				}
+				const { settings: saved } = (await res.json()) as { settings: ChatSettings };
+				onSaved(saved);
+				setOpen(null);
+			} catch {
+				setError("Could not reach the server — try again.");
+			}
+		},
+		[chatId, onSaved],
+	);
+
+	// The filtered, ranked model list.
+	const results = (catalog?.models ?? [])
+		.map((m) => ({ m, s: fuzzyScore(query, m.provider, m.id, m.name) }))
+		.filter((r) => r.s !== null)
+		.sort((a, b) => (b.s! - a.s!) || a.m.id.localeCompare(b.m.id))
+		.map((r) => r.m);
+
+	return (
+		<div className="relative flex items-center gap-1.5" data-testid="model-control">
+			<button
+				type="button"
+				data-testid="stats-model"
+				onClick={() => {
+					setOpen((o) => (o === "model" ? null : "model"));
+					setQuery("");
+					setError(null);
+				}}
+				aria-expanded={open === "model"}
+				title="Conversation model — applies next turn"
+				className="flex items-center gap-1 transition-colors hover:text-foreground"
+			>
+				<span>{effectiveId ? prettyModel(effectiveId) : "—"}</span>
+			</button>
+			<span aria-hidden>·</span>
+			<button
+				type="button"
+				data-testid="stats-thinking"
+				onClick={() => {
+					setOpen((o) => (o === "thinking" ? null : "thinking"));
+					setError(null);
+				}}
+				aria-expanded={open === "thinking"}
+				title="Thinking level — applies next turn"
+				className="flex items-center gap-1 transition-colors hover:text-foreground"
+			>
+				<span>
+					{effectiveLevel === undefined ? "Thinking —" : `Thinking: ${LEVEL_LABEL[effectiveLevel] ?? effectiveLevel}`}
+				</span>
+			</button>
+
+			{open === "model" && (
+				<div
+					data-testid="model-menu"
+					className="absolute bottom-full right-0 z-40 mb-1.5 flex w-[22rem] flex-col rounded-xl border bg-card p-2 text-xs shadow-xl"
+				>
+					<input
+						ref={searchRef}
+						data-testid="model-search"
+						value={query}
+						onChange={(e) => setQuery(e.target.value)}
+						placeholder="Search models…"
+						className="mb-1.5 w-full rounded-lg border bg-background px-2 py-1.5 text-foreground outline-none focus:ring-1 focus:ring-ring"
+					/>
+					{error && <div className="mb-1.5 text-destructive">{error}</div>}
+					{!catalog && (
+						<div className="px-2 py-3 text-center text-muted-foreground">Loading models…</div>
+					)}
+					{catalog && results.length === 0 && (
+						<div className="px-2 py-3 text-center text-muted-foreground">No models match.</div>
+					)}
+					<ul data-testid="model-list" className="flex max-h-72 flex-col overflow-y-auto">
+						{results.map((m) => (
+							<li key={`${m.provider}/${m.id}`}>
+								<button
+									type="button"
+									data-testid={`model-option-${m.id.replace(/[^a-z0-9-]/gi, "_")}`}
+									onClick={() => {
+										// Keep the thinking level only when the new model
+										// supports it — otherwise drop it (config fallback
+										// clamps honestly; a carry-over would 400).
+										const nextLevel =
+											effectiveLevel !== undefined && m.supportedLevels.includes(effectiveLevel)
+												? effectiveLevel
+												: undefined;
+										void save({ model: { provider: m.provider, id: m.id }, thinkingLevel: nextLevel });
+									}}
+									className={`flex w-full flex-col gap-0.5 rounded-lg px-2 py-1.5 text-left transition-colors hover:bg-muted ${
+										m.id === effectiveId ? "bg-muted/60" : ""
+									}`}
+								>
+									<span className="flex items-center justify-between gap-2">
+										<span className="truncate text-card-foreground">{m.name}</span>
+										<span className="shrink-0 tabular-nums text-muted-foreground" title="USD per 1M tokens in/out">
+											{priceLabel(m.cost)}
+										</span>
+									</span>
+									<span className="flex items-center justify-between gap-2 text-muted-foreground">
+										<span className="truncate">{m.id}</span>
+										<span className="shrink-0 tabular-nums">{formatTokens(m.contextWindow)}</span>
+									</span>
+								</button>
+							</li>
+						))}
+					</ul>
+					<div className="mt-1 border-t px-2 pt-1.5 text-[10px] text-muted-foreground">
+						Applies to the next turn · background agents stay config-pinned
+					</div>
+				</div>
+			)}
+
+			{open === "thinking" && (
+				<div
+					data-testid="thinking-menu"
+					className="absolute bottom-full right-0 z-40 mb-1.5 flex w-44 flex-col gap-0.5 rounded-xl border bg-card p-2 text-xs shadow-xl"
+				>
+					{!catalog && <div className="px-2 py-3 text-center text-muted-foreground">Loading…</div>}
+					{catalog && levels.length === 0 && (
+						<div className="px-2 py-3 text-center text-muted-foreground">
+							{effectiveId ? `${prettyModel(effectiveId)} has no thinking levels.` : "Pick a model first."}
+						</div>
+					)}
+					{levels.map((level) => (
+						<button
+							key={level}
+							type="button"
+							data-testid={`thinking-option-${level}`}
+							onClick={() => void save({ ...(settings ?? {}), thinkingLevel: level })}
+							className={`flex items-center justify-between rounded-lg px-2 py-1.5 text-left transition-colors hover:bg-muted ${
+								level === effectiveLevel ? "bg-muted/60 text-card-foreground" : "text-card-foreground"
+							}`}
+						>
+							<span>{LEVEL_LABEL[level] ?? level}</span>
+							{level === effectiveLevel && <span aria-hidden>✓</span>}
+						</button>
+					))}
+					{error && <div className="mt-1 text-destructive">{error}</div>}
+					<div className="mt-1 border-t px-2 pt-1.5 text-[10px] text-muted-foreground">
+						Levels this model actually supports
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}

components/stats-bar.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import { useState } from "react";
-import { contextWindow, sessionCost, turnCost, type TurnUsage } from "@/src/core";
+import { contextWindow, sessionCost, turnCost, type ChatSettings, type TurnUsage } from "@/src/core";
 import { formatTokens, formatUsd, prettyModel } from "@/components/usage-format";
+import { ModelControl } from "@/components/model-picker";
 
 /**
  * The below-composer stats bar (wave 4 observability): the session's
@@ -14,11 +15,23 @@ import { formatTokens, formatUsd, prettyModel } from "@/components/usage-format"
  * — no cost math lives here. Absent data renders "—", never zero (the
  * doctrine): no turns yet → every figure is "—"; turns the price table
  * can't price count as unpriced, shown in the popover, never folded into a
- * fake $0. The RIGHT side is a PLACEHOLDER for the model + thinking-level
- * control (later work, with its contract changes): display-only for now,
- * model read from the last turn's usage.
+ * fake $0. The RIGHT side is the model + thinking control (components/
+ * model-picker.tsx): one controller for the conversation agents, backed by
+ * pi-ai's catalog; the buttons show the EFFECTIVE model (the record's
+ * settings, else config's pin), while the left-side figures still fold the
+ * turn log's actual billed models.
  */
-export function StatsBar({ turns }: { turns: TurnUsage[] }) {
+export function StatsBar({
+	turns,
+	chatId,
+	settings,
+	onSettingsSaved,
+}: {
+	turns: TurnUsage[];
+	chatId: string;
+	settings?: ChatSettings;
+	onSettingsSaved: (settings: ChatSettings) => void;
+}) {
 	const [open, setOpen] = useState(false);
 	const ctx = contextWindow({ turns });
 	const { cost, unpriced } = sessionCost({ turns });
@@ -47,15 +60,15 @@ export function StatsBar({ turns }: { turns: TurnUsage[] }) {
 				<span aria-hidden>·</span>
 				<span data-testid="stats-cost">{costLabel}</span>
 			</button>
-			{/* Model + thinking level — a placeholder for the coming control
-			    (contract changes land with it); display-only today. */}
-			<div className="flex items-center gap-1.5" data-testid="stats-model-chip">
-				<span data-testid="stats-model">{lastModel ? prettyModel(lastModel) : "—"}</span>
-				<span aria-hidden>·</span>
-				<span data-testid="stats-thinking" title="Thinking level control lands soon">
-					Thinking —
-				</span>
-			</div>
+			{/* The model + thinking control — one controller for the conversation
+			    agents (prober/teacher); the record's `turns` above still folds
+			    the ACTUAL models billed, regardless of what the picker says. */}
+			<ModelControl
+				chatId={chatId}
+				settings={settings}
+				onSaved={onSettingsSaved}
+				fallbackModelId={lastModel}
+			/>
 
 			{open && (
 				<div