feat(models): strong/cheap/vision model slots + multi-provider engine federation

Model slots wave (2026-09-20), chunk B:

- settings: new `models` section {strong, cheap, vision} slots (each
  field independent, same shape as a role override); ROLE_SLOT maps all
  nine roles to tiers (strong=prober+teacher, cheap=researcher/
  demoBuilder/extractor/auditor/labeler, vision=visualMaker+pdfReader);
  resolution chain per role: override → slot → factory pin.
- config: ModelSpec gains provider (all pins openrouter, the BYOK
  default); MODEL_PINS in stores.ts now spans all nine roles (the strong
  slot's factory rep IS the prober pin).
- engine: piModels() registers EVERY builtin provider catalog;
  piEngineForSpec(resolved spec) is the new engine factory (pi-ai
  resolves per-provider keys from env itself); piEngineFor stays as the
  config-pin fallback. chat-handler resolves the conversation chain
  (chat override → strong slot → pin) and injects engineFor into the job
  runner, closing the old gap where per-role overrides never reached
  job engines.
- /api/models: models federate ONLY keyed providers (providers surface
  with keyPresent, env-wins, fresh per call); slots (resolved tier pins)
  join rolePins; catalogDefaultsFor inherits the strong slot; the models
  settings section gets the same catalog gate as chat.
- pricing: PRICES/CONTEXT_LIMITS uniformly keyed provider:id
  (regenerated from ALL pi-ai catalogs, 1354 keys); usage stamps
  (TurnUsage, JobUsage, extraction stages) switch to provider:id —
  owner decision: no legacy compat, old stamps render unpriced.

src/agent/models.ts

@@ -6,7 +6,7 @@ import {
 	type Models,
 	type StreamFunction,
 } from "@earendil-works/pi-ai";
-import { openrouterProvider } from "@earendil-works/pi-ai/providers/openrouter";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { MODELS, type ModelRole } from "../../config.ts";
 import type { ChatSettings } from "../core/contracts/chat.ts";
@@ -42,11 +42,18 @@ export function thinkingLevelFor(role: ModelRole): ThinkingLevel {
 
 let collection: ReturnType<typeof createModels> | undefined;
 
-/** The process-wide pi-ai Models collection (OpenRouter catalog). */
+/** The process-wide pi-ai Models collection — EVERY builtin provider's
+ *  catalog (model slots wave, 2026-09-20): engines and the picker resolve
+ *  against all of pi-ai's per-provider catalogs, so a settings slot can pin
+ *  any native model id. Auth is resolved per request by pi-ai itself from
+ *  the environment (the keys seam reflects file-saved keys into env), and
+ *  a provider with no key simply fails its stream with "not configured" —
+ *  honest, late, and unreachable through the picker, which gates on
+ *  keyPresent. */
 export function piModels() {
 	if (!collection) {
 		collection = createModels();
-		collection.setProvider(openrouterProvider());
+		for (const provider of builtinProviders()) collection.setProvider(provider);
 	}
 	return collection;
 }
@@ -56,23 +63,28 @@ export function openRouterApiKey(): string | undefined {
 	return process.env.OPENROUTER_API_KEY || undefined;
 }
 
-/** The production engine for one agent role. `settings` is the chat's
- * model-control override (prober/teacher only — sub-agent callers pass
- * nothing and get config.ts's pin): any absent field falls back to the
- * config spec, and the thinking level is CLAMPED to the model's supported
- * list (pi's thinkingLevelMap — e.g. GLM-5.3-flash accepts low|high|max),
- * so a settings change between models can never send an invalid level. */
-export function piEngineFor(role: ModelRole, settings?: ChatSettings): PiEngine {
+/** A fully-resolved model pin — the shape every engine now comes from
+ *  (model slots wave, 2026-09-20): the settings-resolution chain's output.
+ *  Every field concrete; the CALLER resolved the chain (role override →
+ *  slot → factory pin, or the chat's conversation chain). */
+export interface ResolvedModelSpec {
+	provider: string;
+	id: string;
+	thinkingLevel: ThinkingLevel;
+}
+
+/** The production engine for a RESOLVED spec (model slots wave,
+ *  2026-09-20): provider-aware catalog lookup + thinking clamp. The API
+ *  key is resolved by pi-ai itself from the environment per request (the
+ *  keys seam reflects file-saved keys into env), so the engine never
+ *  hardcodes OpenRouter's. */
+export function piEngineForSpec(spec: ResolvedModelSpec): PiEngine {
 	const models: Models = piModels();
-	const spec = MODELS[role];
-	const modelId = settings?.model?.id ?? spec.model;
-	const providerId = settings?.model?.provider ?? "openrouter";
-	const model = models.getModel(providerId, modelId);
+	const model = models.getModel(spec.provider, spec.id);
 	if (!model) {
-		throw new Error(`${providerId} catalog has no model ${modelId} (role ${role})`);
+		throw new Error(`${spec.provider} catalog has no model ${spec.id}`);
 	}
-	const requested = settings?.thinkingLevel ?? thinkingLevelFor(role);
-	const level = clampThinkingLevel(model, requested);
+	const level = clampThinkingLevel(model, spec.thinkingLevel);
 	return {
 		model,
 		level,
@@ -83,7 +95,21 @@ export function piEngineFor(role: ModelRole, settings?: ChatSettings): PiEngine
 			models.streamSimple(requestModel, context, {
 				...options,
 				reasoning: level === "off" ? undefined : level,
-				apiKey: options?.apiKey ?? openRouterApiKey(),
 			}),
 	};
-}
+}
+
+/** The production engine for one agent role — the LEGACY fallback path:
+ *  the chat's model-control override over config.ts's pin. Production
+ *  callers (chat-handler) now resolve the full chain (chat override →
+ *  strong slot → factory pin) and call piEngineForSpec; this stays for
+ *  direct config-pin fallbacks (sub-agents without an injected engine —
+ *  the job runner injects one — and tests). */
+export function piEngineFor(role: ModelRole, settings?: ChatSettings): PiEngine {
+	const spec = MODELS[role];
+	return piEngineForSpec({
+		provider: settings?.model?.provider ?? spec.provider,
+		id: settings?.model?.id ?? spec.model,
+		thinkingLevel: settings?.thinkingLevel ?? thinkingLevelFor(role),
+	});
+}

src/agent/subagents/extraction.ts

@@ -293,7 +293,10 @@ async function runSubmitAgent<T>(opts: {
 			onAssistantMessage: (message, step) =>
 				opts.onStep(
 					message.usage,
-					message.model,
+					// Provider-qualified stamp (model slots wave, 2026-09-20):
+					// pi reports the bare id; usage stamps carry provider:id to
+					// match the price table's uniform keys.
+					`${message.provider}:${message.model}`,
 					step,
 					message.stopReason,
 					message.content.filter((c) => c.type === "toolCall").map((c) => (c as { name: string }).name).join(", ") || "(none)",

src/agent/subagents/runner.ts

@@ -19,7 +19,7 @@ import {
 	type VisualToolInput,
 } from "../../core/contracts.ts";
 import { registerJobAbort, unregisterJobAbort } from "./aborts.ts";
-import { MODELS } from "../../../config.ts";
+import { MODELS, type ModelRole } from "../../../config.ts";
 import type { ChatStore, JobStore } from "../../core/ports.ts";
 import { runDemoBuilder } from "./demo-builder.ts";
 import { runPdfReaderAgent } from "./pdf-reader.ts";
@@ -68,6 +68,14 @@ export interface JobRunnerDeps {
 	 * flipped); rejects when delivery fails unrecoverably.
 	 */
 	deliver: (steer: SubagentSteerMessage) => Promise<void>;
+	/**
+	 * Settings-resolved engine per role (model slots wave, 2026-09-20): the
+	 * role-override → slot → factory-pin chain, read FRESH per job (the
+	 * server wiring passes effectiveSettings-based resolution). Closes the
+	 * old gap where per-role settings overrides never reached job engines.
+	 * Test overrides (below) still win; absent → config pins.
+	 */
+	engineFor?: (role: ModelRole) => PiEngine;
 }
 
 export interface JobRunner {
@@ -89,18 +97,26 @@ interface LoopContext {
 	onUsage: (step: UsageStepLike) => void;
 }
 
-/** The OpenRouter model id for a job kind — JobUsage.model. The kind→role
- * table mirrors MODELS in config.ts (research→researcher, demo→demoBuilder,
- * visual→visualMaker); the id is taken from config so a price-table sync
- * re-prices jobs for free. Model overrides (tests) still bill under the
- * configured model — usage is what is being captured, not which instance.
- * Context-injection jobs make NO model call ("" — onUsage never fires for
- * them; the kind is deliberately absent from the runners below). */
+/** The kind→role table (model slots wave, 2026-09-20): which ModelRole's
+ * engine each sub-agent kind runs — the engineFor injection key. */
+const KIND_ROLE: Record<Exclude<JobKind, "graph-context">, ModelRole> = {
+	research: "researcher",
+	demo: "demoBuilder",
+	visual: "visualMaker",
+	pdf: "pdfReader",
+};
+
+/** The config-pin model stamp for a job kind — JobUsage.model when no
+ * engine was resolved (engineFor absent AND no test override). Stamps are
+ * provider-qualified ("provider:id") since the model slots wave, matching
+ * the price table's uniform keys. Context-injection jobs make NO model
+ * call ("" — onUsage never fires for them; the kind is deliberately
+ * absent from the runners below). */
 const KIND_MODEL: Record<JobKind, string> = {
-	research: MODELS.researcher.model,
-	demo: MODELS.demoBuilder.model,
-	visual: MODELS.visualMaker.model,
-	pdf: MODELS.pdfReader.model,
+	research: `${MODELS.researcher.provider}:${MODELS.researcher.model}`,
+	demo: `${MODELS.demoBuilder.provider}:${MODELS.demoBuilder.model}`,
+	visual: `${MODELS.visualMaker.provider}:${MODELS.visualMaker.model}`,
+	pdf: `${MODELS.pdfReader.provider}:${MODELS.pdfReader.model}`,
 	"graph-context": "",
 };
 
@@ -111,8 +127,10 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
 	 * then writes through the job store so the poll sees progress). */
 	const usageTotals = new Map<string, JobUsage>();
 
-	function makeLoopContext(jobId: string, kind: JobKind): LoopContext {
-		const model = KIND_MODEL[kind];
+	function makeLoopContext(jobId: string, kind: JobKind, engine?: PiEngine): LoopContext {
+		// Provider-qualified stamp (model slots wave): the engine's actual
+		// model, else the legacy config-pin id (see KIND_MODEL).
+		const model = engine ? `${engine.model.provider}:${engine.model.id}` : KIND_MODEL[kind];
 		// Real-kill wiring (2026-09 abort semantics): the controller is what
 		// the abort endpoint fires (agent/subagents/aborts.ts registry); the
 		// signal rides into every model call of the loop.
@@ -143,14 +161,28 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
 	 *  them below rather than guessing wrong. */
 	// Each kind's runner narrows the union input itself (dispatch-time inputs
 	// are kind-correct by construction; transcript fallbacks are cast after).
+	/** The engine one job runs on: test override first (the old seam —
+	 *  tests swap scripted engines without touching deps), then the injected
+	 *  settings-resolved engineFor (model slots wave, 2026-09-20), else
+	 *  undefined → the sub-agent factories fall back to config pins. */
+	function pickEngine(kind: Exclude<JobKind, "graph-context">): PiEngine | undefined {
+		const testOverride: Record<string, { current?: PiEngine } | undefined> = {
+			researcher: researchModelOverride,
+			demoBuilder: demoModelOverride,
+			visualMaker: visualModelOverride,
+			pdfReader: pdfModelOverride,
+		};
+		return testOverride[KIND_ROLE[kind]]?.current ?? deps.engineFor?.(KIND_ROLE[kind]);
+	}
+
 	const KIND_RUNNERS: Record<
 		Exclude<JobKind, "graph-context">,
-		(jobId: string, input: JobToolInput | undefined, loop: LoopContext) => Promise<void>
+		(jobId: string, engine: PiEngine | undefined, input: JobToolInput | undefined, loop: LoopContext) => Promise<void>
 	> = {
-		research: (jobId, input, loop) => runResearchJob(jobId, researchModelOverride.current, input, loop),
-		demo: (jobId, input, loop) => runDemoJob(jobId, demoModelOverride.current, input, loop),
-		visual: (jobId, input, loop) => runVisualJob(jobId, visualModelOverride.current, input, loop),
-		pdf: (jobId, input, loop) => runPdfJob(jobId, pdfModelOverride.current, input, loop),
+		research: (jobId, engine, input, loop) => runResearchJob(jobId, engine, input, loop),
+		demo: (jobId, engine, input, loop) => runDemoJob(jobId, engine, input, loop),
+		visual: (jobId, engine, input, loop) => runVisualJob(jobId, engine, input, loop),
+		pdf: (jobId, engine, input, loop) => runPdfJob(jobId, engine, input, loop),
 	};
 
 	async function runJob(jobId: string, input?: JobToolInput): Promise<void> {
@@ -173,7 +205,8 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
 			return;
 		}
 		try {
-			await run(jobId, input, makeLoopContext(jobId, job.kind));
+			const engine = pickEngine(job.kind);
+			await run(jobId, engine, input, makeLoopContext(jobId, job.kind, engine));
 		} finally {
 			unregisterJobAbort(jobId);
 			// The last usage write may have been mid-flight when the loop died;

src/core/contracts/chat.ts

@@ -86,7 +86,8 @@ export const GRAPH_CONTEXT_TOKENS_STOPS = [0, 64, 256, 1024, 4096, 16384] as con
  *  billed (CallUsage per agent step). Steps, not a sum: cost and context
  *  folds happen at read time (core/prices.ts). */
 export interface ExtractionStageUsage {
-	/** The OpenRouter model id that ran this stage. */
+	/** The model that ran this stage, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	steps: CallUsage[];
 }
@@ -142,7 +143,8 @@ export interface TurnUsage {
 	 *  entry to the transcript (the block this turn "belongs" to). */
 	messageId: string;
 	at: string;
-	/** The OpenRouter model id that ran the turn. */
+	/** The model that ran the turn, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	/** One entry per agent step (model call) in this turn. */
 	steps: CallUsage[];

src/core/contracts/jobs.ts

@@ -41,7 +41,8 @@ export interface JobRecord {
  * field NO model call reported stays undefined — absent is not zero (the
  * money-channel doctrine; cost renders "—", never $0). */
 export interface JobUsage {
-	/** The OpenRouter model id that ran the sub-agent. */
+	/** The model that ran the sub-agent, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	/** Running totals summed over the run's model calls so far. */
 	inputTokens: number | undefined;

src/core/contracts/models.ts

@@ -6,7 +6,7 @@
  * components never import from the server band).
  */
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { BackgroundModelRole } from "../settings.ts";
+import type { BackgroundModelRole, ModelSlotName } from "../settings.ts";
 
 /** One picker row: everything the UI shows about a model, projected from
  *  pi-ai's catalog. Costs are USD per 1M tokens (the same catalog, the same
@@ -42,6 +42,12 @@ export type RolePins = Record<
 	{ model: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }
 >;
 
+/** One slot tier's RESOLVED pin (model slots wave, 2026-09-20): the
+ *  strong/cheap/vision tier's concrete model — slot override falling back
+ *  to the factory rep pin. The settings UI captions each slot row with it
+ *  and the picker pre-fills from it. */
+export type SlotPins = Record<ModelSlotName, { model: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }>;
+
 /** GET /api/models response. */
 export interface ModelCatalogResponse {
 	models: ModelCatalogEntry[];
@@ -49,4 +55,23 @@ export interface ModelCatalogResponse {
 	/** The six background roles' resolved pins (same resolution the agent
 	 *  factories use — src/server/stores.ts effectiveSettings). */
 	rolePins: RolePins;
+	/** The three slot tiers' resolved pins (model slots wave, 2026-09-20):
+	 *  same resolution chain — role override → slot → factory pin — reported
+	 *  at tier granularity; effectiveSettings().models verbatim. */
+	slots: SlotPins;
+	/** Providers with a PRESENT key, and which env var gates each — the
+	 *  model slots wave's federation surface (2026-09-20): the picker lists
+	 *  models from these providers' pi-ai catalogs only. Keyless providers
+	 *  are simply absent (the Keys page is the discovery surface, same
+	 *  discipline as the search engines). */
+	providers: CatalogProvider[];
+}
+
+/** One row of the providers surface. */
+export interface CatalogProvider {
+	id: string;
+	/** The env var whose presence federates this provider in. */
+	envVar: string;
+	/** Whether that var is currently present (env or auth file). */
+	keyPresent: boolean;
 }

src/core/settings-resolution.ts

@@ -23,23 +23,40 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ModelRole } from "../../config.ts";
 import type { ChatSettings } from "./contracts/chat.ts";
 import type { SearchEngineId } from "./search.ts";
 import {
 	BACKGROUND_MODEL_ROLES,
 	FACTORY_SETTINGS,
+	MODEL_SLOTS,
+	ROLE_SLOT,
 	type AgentSettings,
 	type BackgroundModelRole,
 	type FactorySettings,
 	type GeneralSettings,
 	type GraphSettings,
+	type ModelSlot,
+	type ModelSlotName,
 	type RoleModelOverride,
 	type UserSettings,
 } from "./settings.ts";
 
 /** The factory layer for model roles — config.ts's MODELS shape (types only
- *  here; the runtime object is threaded in by the caller). */
-export type ModelRoleSpecs = Record<BackgroundModelRole, { model: string; effort: ThinkingLevel }>;
+ *  here; the runtime object is threaded in by the caller). Model slots
+ *  (2026-09-20): the factory map spans ALL nine roles (the strong slot's
+ *  factory fallback is the prober pin), while per-role OVERRIDES stay
+ *  background-only (the conversation pair is chat-settings-controlled). */
+export type ModelRoleSpecs = Record<ModelRole, { provider: string; model: string; effort: ThinkingLevel }>;
+
+/** A fully-resolved model slot: the tier's concrete model (slot over factory
+ *  rep pin) — strong's factory rep is the prober pin, cheap's the researcher
+ *  pin, vision's the visualMaker pin (owner-settled tier mapping). */
+export interface EffectiveSlot {
+	provider: string;
+	id: string;
+	thinkingLevel: ThinkingLevel;
+}
 
 /** A fully-resolved model pin for one background role. */
 export interface EffectiveModelSpec {
@@ -68,23 +85,78 @@ export interface EffectiveSettings {
 		 *  lives in server/search.ts, where keys are visible. */
 		search: { engine?: SearchEngineId };
 	};
+	/** The resolved strong/cheap/vision slots (model slots wave,
+	 *  2026-09-20): each tier's concrete model (slot over factory rep pin)
+	 *  — the per-role chain (override → slot → pin) is resolved into
+	 *  agent.models; these are the tier-level views the picker captions. */
+	models: Record<ModelSlotName, EffectiveSlot>;
 	appearance: EffectiveAppearance;
 	graph: Required<GraphSettings>;
 }
 
-/** Resolve one background role's spec: record override per field,
- *  config.ts pin per absent field (provider pinned to openrouter today). */
+/** Full-chain resolution for ANY role (model slots wave, 2026-09-20):
+ *  per-role override (background roles only) → slot → factory pin. The
+ *  conversation pair (prober/teacher) resolves the same chain MINUS the
+ *  role override (their override is the chat's own settings — the
+ *  chat-handler overlays it itself). This is the engine wiring's one call. */
+export function resolveRoleSpec(
+	role: ModelRole,
+	record: UserSettings | null,
+	factory: ModelRoleSpecs,
+): EffectiveModelSpec {
+	const bg = BACKGROUND_MODEL_ROLES as readonly string[];
+	const override = bg.includes(role) ? record?.agent?.models?.[role as BackgroundModelRole] : undefined;
+	return resolveModelSpec(role as BackgroundModelRole, override, factory, record?.models);
+}
+
+/** The factory representative pin for a slot tier — the pin the slot
+ *  falls back to when unset (owner-settled mapping: strong's rep is the
+ *  prober pin — prober and teacher share the strong tier — cheap's the
+ *  researcher pin, vision's the visualMaker pin). */
+export function factorySlotRep(slot: ModelSlotName, factory: ModelRoleSpecs): EffectiveSlot {
+	const rep =
+		slot === "strong" ? factory.prober : slot === "cheap" ? factory.researcher : factory.visualMaker;
+	// The factory contract spans all nine roles (stores.ts MODEL_PINS) —
+	// the rep lookup cannot miss; the cast is for the checker only.
+	const r = rep as { provider: string; model: string; effort: ThinkingLevel };
+	return { provider: r.provider, id: r.model, thinkingLevel: r.effort };
+}
+
+/** Resolve one slot: the slot override per field, the factory rep pin per
+ *  absent field (model slots wave, 2026-09-20). */
+export function resolveSlot(
+	slot: ModelSlotName,
+	override: ModelSlot | undefined,
+	factory: ModelRoleSpecs,
+): EffectiveSlot {
+	const rep = factorySlotRep(slot, factory);
+	return {
+		provider: override?.model?.provider ?? rep.provider,
+		id: override?.model?.id ?? rep.id,
+		thinkingLevel: override?.thinkingLevel ?? rep.thinkingLevel,
+	};
+}
+
+/** Resolve one background role's spec — the model slots chain (owner
+ *  decision 2026-09-20): role override → SLOT → factory pin, each field
+ *  independent (a role can borrow only the slot's model, or only its
+ *  thinking budget). An absent provider coordinate anywhere resolves to
+ *  the factory pin's provider (the BYOK default, openrouter today) —
+ *  legacy ids without a provider ride the factory provider. */
 export function resolveModelSpec(
 	role: BackgroundModelRole,
 	override: RoleModelOverride | undefined,
 	factory: ModelRoleSpecs,
+	slots?: Partial<Record<ModelSlotName, ModelSlot>>,
 ): EffectiveModelSpec {
-	const spec = factory[role];
-	const model = override?.model;
+	// The factory contract spans all nine roles; background roles always hit.
+	const spec = factory[role] as { provider: string; model: string; effort: ThinkingLevel };
+	const slotName = ROLE_SLOT[role] as ModelSlotName | undefined;
+	const slot = slotName ? slots?.[slotName] : undefined;
 	return {
-		provider: model?.provider ?? "openrouter",
-		id: model?.id ?? spec.model,
-		thinkingLevel: override?.thinkingLevel ?? spec.effort,
+		provider: override?.model?.provider ?? slot?.model?.provider ?? spec.provider,
+		id: override?.model?.id ?? slot?.model?.id ?? spec.model,
+		thinkingLevel: override?.thinkingLevel ?? slot?.thinkingLevel ?? spec.effort,
 	};
 }
 
@@ -92,6 +164,7 @@ export function resolveModelSpec(
  *  field then lands on its factory default. */
 export function resolveSettings(record: UserSettings | null, factory: ModelRoleSpecs): EffectiveSettings {
 	const agent = record?.agent ?? {};
+	const modelsSection = record?.models ?? {};
 	const appearance = record?.appearance ?? {};
 	const md = appearance.mdRendering ?? {};
 	const graph = record?.graph ?? {};
@@ -99,7 +172,7 @@ export function resolveSettings(record: UserSettings | null, factory: ModelRoleS
 	const factoryMd = factoryAppearance.mdRendering;
 	const models = {} as Record<BackgroundModelRole, EffectiveModelSpec>;
 	for (const role of BACKGROUND_MODEL_ROLES) {
-		models[role] = resolveModelSpec(role, agent.models?.[role], factory);
+		models[role] = resolveModelSpec(role, agent.models?.[role], factory, modelsSection);
 	}
 	return {
 		general: {
@@ -112,6 +185,11 @@ export function resolveSettings(record: UserSettings | null, factory: ModelRoleS
 			prompts: agent.prompts ?? {},
 			search: agent.search ?? {},
 		},
+		models: {
+			strong: resolveSlot("strong", modelsSection.strong, factory),
+			cheap: resolveSlot("cheap", modelsSection.cheap, factory),
+			vision: resolveSlot("vision", modelsSection.vision, factory),
+		},
 		appearance: {
 			mode: appearance.mode ?? factoryAppearance.mode,
 			background: appearance.background ?? factoryAppearance.background,

src/core/settings.ts

@@ -57,6 +57,51 @@ export interface RoleModelOverride {
 	thinkingLevel?: ThinkingLevel;
 }
 
+// ─── Model slots (model slots wave, 2026-09-20) ──────────────────────────────
+
+/** The capability tiers a user can pin models into (owner-settled mapping):
+ *  strong = prober + teacher (also the per-session default-teacher
+ *  starting point); cheap = researcher, demo-builder, extractor, auditor,
+ *  labeler; vision = visual-maker + pdf-reader. Resolution per role:
+ *  ROLE OVERRIDE → slot → factory pin. */
+export const MODEL_SLOTS = ["strong", "cheap", "vision"] as const;
+export type ModelSlotName = (typeof MODEL_SLOTS)[number];
+
+/** One slot's override — same per-field independence as a role override:
+ *  absent model keeps the tier's current model, absent thinkingLevel keeps
+ *  its thinking budget. */
+export interface ModelSlot {
+	/** The model swap: both coordinates or neither. */
+	model?: { provider: string; id: string };
+	/** The thinking budget swap. */
+	thinkingLevel?: ThinkingLevel;
+}
+
+/** The `models` settings section (owner decision 2026-09-20: a dedicated
+ *  section — slots are engine-level choices, not one session's). All slots
+ *  optional: an absent slot means every role of its tier runs whatever the
+ *  deeper tiers of the chain resolve to (per-role override → factory pin). */
+export interface ModelsSettings {
+	strong?: ModelSlot;
+	cheap?: ModelSlot;
+	vision?: ModelSlot;
+}
+
+/** Which slot a role draws from (model slots wave, 2026-09-20). Includes the
+ *  conversation pair and pdfReader (not BackgroundModelRoles — the slot
+ *  tier spans every role; only background roles surface per-role overrides). */
+export const ROLE_SLOT: Readonly<Record<string, ModelSlotName>> = {
+	prober: "strong",
+	teacher: "strong",
+	researcher: "cheap",
+	demoBuilder: "cheap",
+	extractor: "cheap",
+	auditor: "cheap",
+	labeler: "cheap",
+	visualMaker: "vision",
+	pdfReader: "vision",
+};
+
 /** General settings — app-level behavior. Version DISPLAY and plans login
  *  live outside the record (package.json / auth.json) by owner decision. */
 export interface GeneralSettings {
@@ -140,6 +185,8 @@ export interface UserSettings {
 	 *  controls. NOT shown in the settings panel (owner decision). */
 	chat?: ChatSettings;
 	agent?: AgentSettings;
+	/** The strong/cheap/vision model slots (model slots wave, 2026-09-20). */
+	models?: ModelsSettings;
 	appearance?: AppearanceSettings;
 	graph?: GraphSettings;
 	[key: string]: unknown;
@@ -244,6 +291,18 @@ function sanitizeRoleOverride(raw: unknown): RoleModelOverride | undefined {
 	return Object.keys(out).length ? out : undefined;
 }
 
+/** The models section (model slots wave, 2026-09-20): each slot keeps
+ *  only well-formed parts — the same shape rules as a role override, so a
+ *  stale client can't park junk in a slot. */
+function sanitizeModels(raw: Record<string, unknown>): ModelsSettings {
+	const out: ModelsSettings = {};
+	for (const slot of MODEL_SLOTS) {
+		const cleaned = sanitizeRoleOverride(raw[slot]);
+		if (cleaned) out[slot] = cleaned;
+	}
+	return out;
+}
+
 function sanitizeBooleanMap(raw: unknown): Record<string, boolean> | undefined {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const out: Record<string, boolean> = {};
@@ -348,6 +407,10 @@ export function sanitizeUserSettings(raw: unknown): UserSettings | null {
 	if (r.appearance !== null && typeof r.appearance === "object" && !Array.isArray(r.appearance)) {
 		out.appearance = sanitizeAppearance(r.appearance as Record<string, unknown>);
 	}
+	if (r.models !== null && typeof r.models === "object" && !Array.isArray(r.models)) {
+		const models = sanitizeModels(r.models as Record<string, unknown>);
+		if (Object.keys(models).length) out.models = models;
+	}
 	if (r.graph !== null && typeof r.graph === "object" && !Array.isArray(r.graph)) {
 		out.graph = sanitizeGraph(r.graph as Record<string, unknown>);
 	}

src/server/chat-handler.ts

@@ -1,7 +1,7 @@
 import type { UIMessage } from "ai";
 import type { Usage } from "@earendil-works/pi-ai";
 import { createProberAgent, createTeacherAgent, type AgentBuildOptions, type TeachingAgent } from "../agent/teacher-agent.ts";
-import { piEngineFor } from "../agent/models.ts";
+import { piEngineForSpec } from "../agent/models.ts";
 import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createExtractionPipeline } from "../agent/subagents/extraction.ts";
 import { runGraphContextJob, type GraphContextDeps } from "../agent/subagents/graph-context.ts";
@@ -10,8 +10,8 @@ import type { ModelRole } from "../../config.ts";
 import { claimSteers, deliverJobResult, setContextRespawn, setJobRespawn, setTurnRunner } from "./jobs.ts";
 import { recordToPiMessages } from "./pi/record-adapter.ts";
 import { createPiTurnResponse } from "./pi/ui-stream.ts";
-import { effectiveSettings, stores } from "./stores.ts";
-import { extractionEnabled, graphContextEnabled } from "../core/settings-resolution.ts";
+import { effectiveSettings, MODEL_PINS, stores } from "./stores.ts";
+import { extractionEnabled, graphContextEnabled, resolveRoleSpec } from "../core/settings-resolution.ts";
 import { beginTurn, endTurn } from "./turn-liveness.ts";
 import { persistTurn, triggerExtraction, triggerGraphContext, withMessageIds } from "./turn-service.ts";
 import type { CallUsage } from "../core/contracts.ts";
@@ -39,6 +39,12 @@ const jobRunner = createJobRunner({
 	chatStore: stores.chatStore,
 	jobStore: stores.jobStore,
 	deliver: deliverJobResult,
+	// Model slots wave (2026-09-20): job engines resolve the full chain —
+	// role override → slot → factory pin — read FRESH per job (a settings
+	// PUT between dispatch and spawn lands). Closes the old gap where
+	// per-role overrides reached rolePins but never the engines.
+	engineFor: (role) =>
+		piEngineForSpec(resolveRoleSpec(role, stores.settingsStore.readSettings(), MODEL_PINS)),
 });
 /** The app's ONE extraction pipeline instance — both front doors share it:
  *  quiz-triggered session runs (turn-service) and notes imports
@@ -205,8 +211,18 @@ export async function handleChatRequest(
 	// for the conversation agents; piEngineFor falls back to config on absent
 	// fields and clamps the thinking level to the model's supported list).
 	const settings = stores.chatStore.getChat(chatId)?.settings;
-	const engine = piEngineFor(role, settings);
-	const modelId = engine.model.id;
+	// Model slots wave (2026-09-20): the conversation chain is the chat's
+	// own override over the STRONG slot (prober + teacher's tier) over the
+	// factory pin — each field independent, same discipline as the roles.
+	const strong = effective.models.strong;
+	const engine = piEngineForSpec({
+		provider: settings?.model?.provider ?? strong.provider,
+		id: settings?.model?.id ?? strong.id,
+		thinkingLevel: settings?.thinkingLevel ?? strong.thinkingLevel,
+	});
+	// Provider-qualified stamp (model slots wave): matches the price table's
+	// provider:id keys.
+	const modelId = `${engine.model.provider}:${engine.model.id}`;
 	// Tests inject a factory: the agent is stateless per turn (docs/
 	// pi-engine-swap.md §2), so each request builds a fresh one off the
 	// transcript — the factory mirrors that seam exactly.

src/server/model-catalog.ts

@@ -16,19 +16,22 @@
 
 import { getSupportedThinkingLevels, type Api, type Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { MODELS } from "../../config.ts";
 import { piModels } from "../agent/models.ts";
 import { settingsStore } from "../store/settings.ts";
 import { effectiveSettings } from "./stores.ts";
+import { keyValue } from "./keys.ts";
 import type { ChatSettings } from "../core/contracts/chat.ts";
 import type {
 	CatalogDefaults,
+	CatalogProvider,
 	ModelCatalogEntry,
 	ModelCatalogResponse,
 	RolePins,
+	SlotPins,
 } from "../core/contracts/models.ts";
-import type { EffectiveModelSpec } from "../core/settings-resolution.ts";
-import { BACKGROUND_MODEL_ROLES, type BackgroundModelRole } from "../core/settings.ts";
+import type { EffectiveModelSpec, EffectiveSlot } from "../core/settings-resolution.ts";
+import { AUTH_PROVIDER_KEYS } from "../core/auth-keys.ts";
+import { BACKGROUND_MODEL_ROLES, type BackgroundModelRole, type ModelSlotName, type ModelsSettings } from "../core/settings.ts";
 
 /** The picker's client-safe model entry (contract: core/contracts/models.ts). */
 export type ModelDto = ModelCatalogEntry;
@@ -37,10 +40,10 @@ export type ModelDto = ModelCatalogEntry;
  *  chat section in, CatalogDefaults out; `catalogDefaults()` below is the
  *  fs wrapper). Absent fields (or no record — BYOK first boot) fall back
  *  to the config pin, exactly as before. */
-export function catalogDefaultsFor(chat?: ChatSettings): CatalogDefaults {
+export function catalogDefaultsFor(chat: ChatSettings | undefined, strong: EffectiveSlot): CatalogDefaults {
 	return {
-		model: chat?.model ?? { provider: "openrouter", id: MODELS.prober.model },
-		thinkingLevel: (chat?.thinkingLevel ?? MODELS.prober.effort) as ThinkingLevel,
+		model: chat?.model ?? { provider: strong.provider, id: strong.id },
+		thinkingLevel: chat?.thinkingLevel ?? strong.thinkingLevel,
 	};
 }
 
@@ -49,7 +52,7 @@ export function catalogDefaultsFor(chat?: ChatSettings): CatalogDefaults {
  *  the settings record's `chat` section; the picker's defaults row shows
  *  it once chosen. */
 export function catalogDefaults(): CatalogDefaults {
-	return catalogDefaultsFor(settingsStore.readSettings()?.chat);
+	return catalogDefaultsFor(settingsStore.readSettings()?.chat, effectiveSettings().models.strong);
 }
 
 /** Project the resolved per-role specs to the client DTO (pure — the
@@ -77,6 +80,42 @@ export function catalogRolePins(): RolePins {
 	return rolePinsFor(effectiveSettings().agent.models);
 }
 
+/** The three slot tiers' RESOLVED pins (model slots wave, 2026-09-20) —
+ *  effectiveSettings().models verbatim: slot over factory rep pin, the
+ *  same resolution the engine wiring uses, so the Models settings page's
+ *  captions cannot drift from what actually runs. */
+export function catalogSlots(): SlotPins {
+	const slots = effectiveSettings().models;
+	const pins = {} as SlotPins;
+	for (const name of ["strong", "cheap", "vision"] as const) {
+		const slot: EffectiveSlot = slots[name];
+		pins[name] = {
+			model: { provider: slot.provider, id: slot.id },
+			thinkingLevel: slot.thinkingLevel,
+		};
+	}
+	return pins;
+}
+
+/** The providers surface (model slots wave, 2026-09-20): one row per
+ *  plain-key model provider (core/auth-keys.ts's pi-ai-derived table),
+ *  with keyPresent read env-wins through the keys seam, fresh per call —
+ *  saving a key immediately federates the provider into the picker. */
+export function catalogProviders(): CatalogProvider[] {
+	return AUTH_PROVIDER_KEYS.map((p) => ({
+		id: p.id,
+		envVar: p.envVar,
+		keyPresent: keyValue(p.envVar) !== undefined,
+	})).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** The providers whose key is present — the picker federates exactly
+ *  these (a keyless provider's models are unreachable by design; the
+ *  Keys page is the discovery surface, same discipline as search). */
+function keyedProviderIds(): Set<string> {
+	return new Set(catalogProviders().filter((p) => p.keyPresent).map((p) => p.id));
+}
+
 /** Project one catalog model to the client DTO. */
 export function toModelDto(model: Model<Api>): ModelDto {
 	return {
@@ -102,12 +141,20 @@ export function toModelDto(model: Model<Api>): ModelDto {
  *  defaults a settings-less chat runs + the background roles' resolved
  *  pins (the settings UI's per-role default captions). */
 export function modelCatalog(): ModelCatalogResponse {
+	const keyed = keyedProviderIds();
 	const models = piModels()
 		.getProviders()
+		.filter((p) => keyed.has(p.id))
 		.flatMap((p) => piModels().getModels(p.id))
 		.map(toModelDto)
 		.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
-	return { models, defaults: catalogDefaults(), rolePins: catalogRolePins() };
+	return {
+		models,
+		defaults: catalogDefaults(),
+		rolePins: catalogRolePins(),
+		slots: catalogSlots(),
+		providers: catalogProviders(),
+	};
 }
 
 /** One validated outcome for a settings write. */
@@ -133,8 +180,11 @@ export function validateChatSettings(settings: ChatSettings): SettingsValidation
 		}
 	}
 	if (settings.thinkingLevel !== undefined) {
-		const provider = settings.model?.provider ?? "openrouter";
-		const id = settings.model?.id ?? MODELS.prober.model;
+		// The conversation chain's fallback is the strong slot (model slots
+		// wave, 2026-09-20) — the model a settings-less chat would run.
+		const strong = effectiveSettings().models.strong;
+		const provider = settings.model?.provider ?? strong.provider;
+		const id = settings.model?.id ?? strong.id;
 		const model = piModels().getModel(provider, id);
 		if (!model) return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
 		const supported = getSupportedThinkingLevels(model);
@@ -147,4 +197,48 @@ export function validateChatSettings(settings: ChatSettings): SettingsValidation
 		}
 	}
 	return { ok: true };
-}
+}
+/** Validate a models-section write (PUT /api/settings/models) against the
+ *  catalog — the same gate the chat section gets. Model swaps must name a
+ *  real provider+model; a thinkingLevel must be supported by the model the
+ *  slot would resolve to (the slot's own model, else the factory rep pin).
+ *  keyPresent is NOT gated here (a stored pin for a provider whose key
+ *  lapsed stays valid — it fails honestly at stream time, and the picker
+ *  stops offering it). */
+export function validateModelsSettings(settings: ModelsSettings): SettingsValidation {
+	for (const name of ["strong", "cheap", "vision"] as const) {
+		const slot = settings[name];
+		if (!slot) continue;
+		const verdict = validateSlotSpec(name, slot);
+		if (!verdict.ok) return verdict;
+	}
+	return { ok: true };
+}
+
+function validateSlotSpec(name: ModelSlotName, slot: { model?: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }): SettingsValidation {
+	const providers = piModels().getProviders().map((p) => p.id);
+	if (slot.model) {
+		const { provider, id } = slot.model;
+		if (!providers.includes(provider)) {
+			return { ok: false, error: `Unknown provider "${provider}" — configured: ${providers.join(", ")}` };
+		}
+		if (!piModels().getModel(provider, id)) {
+			return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
+		}
+	}
+	if (slot.thinkingLevel !== undefined) {
+		const provider = slot.model?.provider ?? effectiveSettings().models[name].provider;
+		const id = slot.model?.id ?? effectiveSettings().models[name].id;
+		const model = piModels().getModel(provider, id);
+		if (!model) return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
+		const supported = getSupportedThinkingLevels(model);
+		if (!supported.includes(slot.thinkingLevel)) {
+			return {
+				ok: false,
+				error: `${id} does not support thinking level "${slot.thinkingLevel}"`,
+				supported,
+			};
+		}
+	}
+	return { ok: true };
+}

src/server/settings-body.ts

@@ -19,9 +19,10 @@ import type {
 	BackgroundModelRole,
 	GeneralSettings,
 	GraphSettings,
+	ModelsSettings,
 	RoleModelOverride,
 } from "../core/settings.ts";
-import { BACKGROUND_MODEL_ROLES } from "../core/settings.ts";
+import { BACKGROUND_MODEL_ROLES, MODEL_SLOTS } from "../core/settings.ts";
 import { TOGGLEABLE_TOOLS } from "../core/pending.ts";
 
 /** Parsed-or-rejected — `ok: false` carries the 400's error message. */
@@ -292,6 +293,31 @@ export function parseGraphSettingsBody(body: unknown): SettingsBodyResult<GraphS
 	return { ok: true, settings };
 }
 
+/** models: { strong?, cheap?, vision? } — the slot tiers (model slots
+ *  wave, 2026-09-20). Each slot is the same shape as a role override; a
+ *  present-but-empty slot object is rejected (absent slot = unset; say
+ *  what you mean). Catalog validity is checked by the route
+ *  (validateChatSettings discipline). */
+export function parseModelsSettingsBody(body: unknown): SettingsBodyResult<ModelsSettings> {
+	const raw = asRecord(body);
+	if (!raw) return { ok: false, error: "Invalid JSON body" };
+	const settings: ModelsSettings = {};
+	for (const key of Object.keys(raw)) {
+		const known = MODEL_SLOTS as readonly string[];
+		if (!known.includes(key)) {
+			return { ok: false, error: `unknown slot "${key}" (supported: ${known.join(", ")})` };
+		}
+		const parsed = parseRoleOverride(raw[key], key);
+		if (!parsed.ok) return { ok: false, error: parsed.error };
+		if (Object.keys(parsed.override).length) {
+			settings[key as (typeof MODEL_SLOTS)[number]] = parsed.override;
+		} else {
+			return { ok: false, error: `slot "${key}" must set model or thinkingLevel (absent slot = unset)` };
+		}
+	}
+	return { ok: true, settings };
+}
+
 /** The section→parser map for PUT /api/settings/[section] (the route also
  *  carries the special prompts sub-resource). */
 export const SETTINGS_SECTIONS = {
@@ -300,6 +326,7 @@ export const SETTINGS_SECTIONS = {
 	agent: parseAgentSettingsBody,
 	appearance: parseAppearanceSettingsBody,
 	graph: parseGraphSettingsBody,
+	models: parseModelsSettingsBody,
 } as const;
 
 export type SettingsSectionName = keyof typeof SETTINGS_SECTIONS;

src/server/stores.ts

@@ -22,20 +22,25 @@ export const stores = {
 
 export type Stores = typeof stores;
 
-/** config.ts's MODELS narrowed to the background roles — the compiled
- *  factory layer the resolution reads. core stays pure (it takes this as a
- *  parameter, never imports config at runtime); the prober/teacher pins
- *  are chat-settings-controlled and deliberately absent here. Tests pin
- *  that the role set matches core's BACKGROUND_MODEL_ROLES. */
-const BACKGROUND_MODEL_PINS: ModelRoleSpecs = {
+/** config.ts's MODELS as the compiled factory layer the resolution reads —
+ *  ALL NINE roles since the model-slots wave (2026-09-20): the strong
+ *  slot's factory fallback IS the prober pin. core stays pure (it takes
+ *  this as a parameter, never imports config at runtime). Per-role
+ *  OVERRIDES stay background-only (the conversation pair is
+ *  chat-settings-controlled) — that split lives in core's
+ *  BACKGROUND_MODEL_ROLES, unchanged. */
+const MODEL_PINS: ModelRoleSpecs = {
+	prober: MODELS.prober,
+	teacher: MODELS.teacher,
 	researcher: MODELS.researcher,
 	demoBuilder: MODELS.demoBuilder,
 	visualMaker: MODELS.visualMaker,
+	pdfReader: MODELS.pdfReader,
 	extractor: MODELS.extractor,
 	auditor: MODELS.auditor,
 	labeler: MODELS.labeler,
 };
-export { BACKGROUND_MODEL_PINS };
+export { MODEL_PINS };
 
 /**
  * The resolved view of the settings record (core/settings-resolution.ts):
@@ -44,5 +49,5 @@ export { BACKGROUND_MODEL_PINS };
  * no caching layer (stale toggles after a settings PUT would be worse).
  */
 export function effectiveSettings(): EffectiveSettings {
-	return resolveSettings(settingsStore.readSettings(), BACKGROUND_MODEL_PINS);
+	return resolveSettings(settingsStore.readSettings(), MODEL_PINS);
 }