@ferris1225/pi-subagents 0.31.0 → 0.32.2

package/src/inspector.ts

@@ -0,0 +1,369 @@
+/**
+ * Pure view-model builder for the /subagents-inspect overlay.
+ *
+ * Joins three read-only sources into one snapshot:
+ *   - monitor (live widget rows: status/usage/activity),
+ *   - runtime.threads (thread state + control phase), and
+ *   - inspectorStore (append-only trajectory + bounded transcript + retained
+ *     snapshots for finished/parked threads whose monitor rows are gone).
+ *
+ * The overlay component renders this snapshot directly and never mutates
+ * runtime state; building it must therefore be side-effect free.
+ */
+
+import { stripVTControlCharacters } from "node:util";
+import { formatUsageCompact, monitor, type RunStatus } from "./monitor.ts";
+import { emptyUsage, type UsageStats } from "./rpc-run.ts";
+import type { SubagentRuntime, ThreadState } from "./runtime.ts";
+import { inspectorStore, type TrajectoryEvent } from "./trajectory.ts";
+
+export interface InspectorRunItem {
+	id: number;
+	agent: string;
+	label: string;
+	status: RunStatus;
+	/** Thread state text ("running", "parked", "completed", ...) or the monitor
+	 * status label for threads without a control record (chain internals). */
+	stateText: string;
+	generation?: number;
+	elapsedMs?: number;
+}
+
+export interface InspectorToolEntry {
+	tool: string;
+	summary?: string;
+	isError?: boolean;
+	running?: boolean;
+	at: number;
+}
+
+export interface InspectorThreadView {
+	id: number;
+	agent: string;
+	label: string;
+	task: string;
+	status: RunStatus;
+	stateText: string;
+	/** Control phase of the current attempt (queued/starting/running/...). */
+	phase?: string;
+	generation?: number;
+	elapsedMs?: number;
+	startedAt?: number;
+	endedAt?: number;
+	model?: string;
+	/** Ordered candidate refs from the dispatch record (primary first). */
+	modelChain: string[];
+	modelFallbackFrom?: string;
+	thinking?: string;
+	isolation?: "shared" | "worktree";
+	integrationStatus?: string;
+	integrationApplied?: boolean;
+	originalCwd?: string;
+	isolationCwd?: string;
+	integrationWorktreePath?: string;
+	integrationPatchPath?: string;
+	integrationError?: string;
+	forkedFromRunId?: number;
+	forkChildRunIds: number[];
+	usage: UsageStats;
+	toolCount: number;
+	activity?: string;
+	currentTool?: string;
+	tools: InspectorToolEntry[];
+	trajectory: readonly TrajectoryEvent[];
+	trajectoryTotal: number;
+	transcript: { text: string; textTruncated: boolean; thinking: string; thinkingTruncated: boolean };
+}
+
+export interface InspectorSnapshot {
+	now: number;
+	items: InspectorRunItem[];
+	detail?: InspectorThreadView;
+}
+
+const TOOL_LIMIT = 6;
+const TRAJECTORY_LIMIT = 10;
+
+function monitorRunsSafe(): ReturnType<typeof monitor.getRuns> {
+	try {
+		return monitor.getRuns();
+	} catch {
+		return [];
+	}
+}
+
+function threadStatusToRunStatus(state: ThreadState): RunStatus {
+	switch (state) {
+		case "queued":
+		case "resuming":
+			return "queued";
+		case "running":
+			return "running";
+		case "steering":
+			return "steering";
+		case "interrupting":
+			return "interrupting";
+		case "parked":
+			return "parked";
+		case "completed":
+			return "done";
+		case "failed":
+		case "stopped":
+			return "failed";
+	}
+}
+
+export function buildInspectorSnapshot(options: {
+	runtime: Pick<SubagentRuntime, "threads">;
+	selectedId?: number;
+	now?: number;
+	toolLimit?: number;
+	trajectoryLimit?: number;
+}): InspectorSnapshot {
+	const now = options.now ?? Date.now();
+	const toolLimit = options.toolLimit ?? TOOL_LIMIT;
+	const trajectoryLimit = options.trajectoryLimit ?? TRAJECTORY_LIMIT;
+	const monitorRuns = monitorRunsSafe();
+
+	// Union of the three sources keyed by id.
+	const ids = new Set<number>();
+	for (const id of options.runtime.threads.keys()) ids.add(id);
+	for (const state of inspectorStore.all()) ids.add(state.runId);
+	for (const run of monitorRuns) ids.add(run.id);
+
+	const items: InspectorRunItem[] = [];
+	let detail: InspectorThreadView | undefined;
+
+	for (const id of [...ids].sort((a, b) => a - b)) {
+		const monitorRun = monitorRuns.find((r) => r.id === id);
+		const thread = options.runtime.threads.get(id);
+		const inspect = inspectorStore.find(id);
+
+		const latestSettled = [...(inspect?.trajectory.getGenerationEvents() ?? [])]
+			.reverse()
+			.find((event): event is Extract<TrajectoryEvent, { kind: "settled" }> => event.kind === "settled");
+		const trajectoryStatus = latestSettled
+			? latestSettled.status === "done" ? "done" : "failed"
+			: undefined;
+		const agent = monitorRun?.agent ?? thread?.agentName ?? inspect?.agent ?? "?";
+		const label = monitorRun?.label ?? inspect?.label ?? "";
+		const task = monitorRun?.task ?? thread?.task ?? inspect?.task ?? "";
+		const status: RunStatus = monitorRun?.status ?? (thread
+			? threadStatusToRunStatus(thread.state)
+			: trajectoryStatus ?? statusFromText(inspect?.status));
+		const stateText = thread?.state ?? monitorRun?.status ?? latestSettled?.status ?? inspect?.status ?? "queued";
+		const startedAt = monitorRun?.startedAt ?? inspect?.startedAt;
+		const endedAt = monitorRun?.endedAt ?? inspect?.endedAt ?? inspect?.trajectory.summary().endedAt;
+		const elapsedMs = startedAt === undefined ? undefined : Math.max(0, (endedAt ?? now) - startedAt);
+
+		items.push({ id, agent, label, status, stateText, generation: thread?.generation ?? inspect?.generation, elapsedMs });
+
+		if (options.selectedId === id) {
+			detail = buildDetail({
+				id,
+				agent,
+				label,
+				task,
+				status,
+				stateText,
+				startedAt,
+				endedAt,
+				elapsedMs,
+				monitorRun,
+				thread,
+				inspect,
+				toolLimit,
+				trajectoryLimit,
+			});
+		}
+	}
+
+	return { now, items, detail };
+}
+
+function statusFromText(text: string | undefined): RunStatus {
+	switch (text) {
+		case "done":
+		case "completed":
+			return "done";
+		case "failed":
+		case "stopped":
+			return "failed";
+		case "running":
+			return "running";
+		case "steering":
+			return "steering";
+		case "interrupting":
+			return "interrupting";
+		case "parked":
+			return "parked";
+		default:
+			return "queued";
+	}
+}
+
+function buildDetail(input: {
+	id: number;
+	agent: string;
+	label: string;
+	task: string;
+	status: RunStatus;
+	stateText: string;
+	startedAt?: number;
+	endedAt?: number;
+	elapsedMs?: number;
+	monitorRun?: ReturnType<typeof monitor.getRuns>[number];
+	thread?: {
+		state: ThreadState;
+		generation: number;
+		control: { getPhase(): string };
+		isolation: "shared" | "worktree";
+		cwd: string;
+		executionCwd: string;
+		worktree?: { worktreePath: string; patchPath: string; state: string };
+		forkedFromRunId?: number;
+		forkChildRunIds: number[];
+	};
+	inspect?: ReturnType<typeof inspectorStore.find>;
+	toolLimit: number;
+	trajectoryLimit: number;
+}): InspectorThreadView {
+	const { monitorRun, thread, inspect } = input;
+	const genEvents = inspect?.trajectory.getGenerationEvents() ?? [];
+	const allEvents = inspect?.trajectory.getEvents() ?? [];
+
+	// Model chain: primary first, then the recorded pool fallbacks. The actual
+	// model currently running is the trajectory summary's latest, or the live
+	// monitor model. modelFallbackFrom marks a pool advancement.
+	const dispatchEvent = [...genEvents].reverse().find((e): e is Extract<TrajectoryEvent, { kind: "dispatch" }> => e.kind === "dispatch");
+	const chain: string[] = [];
+	if (dispatchEvent?.model) chain.push(dispatchEvent.model);
+	for (const ref of dispatchEvent?.pool ?? []) if (ref && !chain.includes(ref)) chain.push(ref);
+	const model = monitorRun?.model ?? inspect?.trajectory.summary().model ?? inspect?.model;
+	const fallbackFrom = monitorRun?.modelFallbackFrom ?? inspect?.trajectory.summary().modelFallbackFrom;
+	if (model && !chain.includes(model)) chain.push(model);
+
+	// Recent tool entries from the current-generation trajectory.
+	const tools: InspectorToolEntry[] = [];
+	for (let i = genEvents.length - 1; i >= 0 && tools.length < input.toolLimit; i--) {
+		const e = genEvents[i];
+		if (e.kind === "tool_start") {
+			// Correlate parallel calls by Pi's stable toolCallId. Name matching is
+			// retained only for legacy events that predate id capture.
+			const ended = genEvents.slice(i + 1).find((later) =>
+				later.kind === "tool_end" &&
+				(e.toolCallId
+					? later.toolCallId === e.toolCallId
+					: later.toolCallId === undefined && later.tool === e.tool),
+			);
+			tools.unshift({
+				tool: e.tool,
+				summary: e.summary || undefined,
+				isError: ended && ended.kind === "tool_end" ? ended.isError : undefined,
+				running: ended === undefined,
+				at: e.at,
+			});
+		}
+	}
+
+	const trajectory = genEvents.slice(-input.trajectoryLimit);
+	const usage = monitorRun?.usage ?? inspect?.runInfo?.usage ?? emptyUsage();
+	const toolCount = monitorRun?.toolCount ?? inspect?.runInfo?.toolCount ?? inspect?.trajectory.summary().toolCount ?? 0;
+	const trajectorySummary = inspect?.trajectory.summary();
+	const lastWorktreeEvent = [...allEvents]
+		.reverse()
+		.find((event): event is Extract<TrajectoryEvent, { kind: "worktree" }> => event.kind === "worktree");
+	const isolation = thread?.isolation ?? monitorRun?.isolation ?? trajectorySummary?.isolation;
+
+	return {
+		id: input.id,
+		agent: input.agent,
+		label: input.label,
+		task: input.task,
+		status: input.status,
+		stateText: input.stateText,
+		phase: thread?.control.getPhase(),
+		generation: thread?.generation ?? (genEvents.length > 0 ? inspect?.generation : undefined),
+		elapsedMs: input.elapsedMs,
+		startedAt: input.startedAt,
+		endedAt: input.endedAt,
+		model: model ?? undefined,
+		modelChain: chain,
+		modelFallbackFrom: fallbackFrom,
+		thinking: monitorRun?.thinking ?? trajectorySummary?.thinking ?? inspect?.thinking,
+		isolation,
+		integrationStatus: monitorRun?.integrationStatus ?? trajectorySummary?.integrationStatus ?? thread?.worktree?.state,
+		integrationApplied: lastWorktreeEvent?.integrated,
+		originalCwd: thread?.cwd ?? trajectorySummary?.originalCwd,
+		isolationCwd: thread?.executionCwd ?? trajectorySummary?.isolationCwd,
+		integrationWorktreePath: lastWorktreeEvent?.worktreePath ?? (thread?.worktree?.state === "retained" ? thread.worktree.worktreePath : undefined),
+		integrationPatchPath: lastWorktreeEvent?.patchPath ?? (thread?.worktree?.state === "retained" ? thread.worktree.patchPath : undefined),
+		integrationError: lastWorktreeEvent?.error,
+		forkedFromRunId: thread?.forkedFromRunId ?? trajectorySummary?.forkedFromRunId,
+		forkChildRunIds: [...(thread?.forkChildRunIds ?? trajectorySummary?.forkChildRunIds ?? [])],
+		usage,
+		toolCount,
+		activity: monitorRun?.activity ?? inspect?.runInfo?.activity ?? inspect?.trajectory.summary().activity,
+		currentTool: monitorRun?.currentTool ?? inspect?.runInfo?.currentTool ?? inspect?.trajectory.summary().currentTool,
+		tools,
+		trajectory,
+		trajectoryTotal: allEvents.length,
+		transcript: inspect?.transcript.snapshot() ?? { text: "", textTruncated: false, thinking: "", thinkingTruncated: false },
+	};
+}
+
+/** One-line event text for the trajectory pane (plain, pre-theme). */
+export function formatTrajectoryEvent(event: TrajectoryEvent): string {
+	return stripVTControlCharacters(formatTrajectoryEventUnsafe(event));
+}
+
+function formatTrajectoryEventUnsafe(event: TrajectoryEvent): string {
+	switch (event.kind) {
+		case "dispatch":
+			return `dispatch ${event.agent}${event.resumed ? " (resumed)" : ""}${event.model ? ` · ${event.model}` : ""}`;
+		case "status":
+			return `status: ${event.status}`;
+		case "candidate":
+			return event.fallbackFrom ? `model: ${event.model ?? "?"} (pool fallback from ${event.fallbackFrom})` : `model: ${event.model ?? "?"}`;
+		case "retry":
+			return `retry${event.reason ? `: ${event.reason}` : ""}`;
+		case "steer":
+			return `steer: ${compactOne(event.instruction, 60)}`;
+		case "retarget":
+			return `retarget: ${compactOne(event.objective, 60)}`;
+		case "park":
+			return "parked at checkpoint";
+		case "resume":
+			return event.objective ? `resume: ${compactOne(event.objective, 60)}` : "resume from retained context";
+		case "fork":
+			return event.runId === event.sourceRunId
+				? `forked child #${event.childRunId}${event.objective ? `: ${compactOne(event.objective, 48)}` : ""}`
+				: `forked from #${event.sourceRunId}${event.objective ? `: ${compactOne(event.objective, 48)}` : ""}`;
+		case "stop":
+			return event.reason ? `stop: ${compactOne(event.reason, 60)}` : "stopped";
+		case "worktree":
+			return event.status === "created"
+				? `worktree created${event.isolationCwd ? ` · ${compactOne(event.isolationCwd, 48)}` : ""}`
+				: event.status === "retained" && event.integrated
+					? `worktree cleanup failed after apply${event.error ? `: ${compactOne(event.error, 48)}` : ""}`
+					: `worktree ${event.status}${event.error ? `: ${compactOne(event.error, 48)}` : ""}`;
+		case "settled":
+			return `settled: ${event.status}${event.model ? ` · ${event.model}` : ""}${event.integrationStatus ? ` · worktree ${event.integrationStatus}` : ""}`;
+		case "tool_start":
+			return `→ ${event.tool}${event.summary ? ` ${compactOne(event.summary, 48)}` : ""}`;
+		case "tool_end":
+			return `${e2(event)}${event.tool}`;
+		case "usage":
+			return `usage: ${formatUsageCompact(event.usage) || "—"}`;
+	}
+}
+
+function e2(event: Extract<TrajectoryEvent, { kind: "tool_end" }>): string {
+	return event.isError ? "✗ " : "✓ ";
+}
+
+function compactOne(text: string, max: number): string {
+	const oneLine = stripVTControlCharacters(text).replace(/\s+/g, " ").trim();
+	const chars = [...oneLine];
+	return chars.length > max ? `${chars.slice(0, max - 1).join("")}…` : oneLine;
+}

package/src/models.ts

@@ -1,82 +1,224 @@
-/**
- * Model availability helpers shared by setup and sub-agent execution.
+/*
+ * Model-pool resolution and setup-picker helpers.
  *
- * A configured override can outlive a provider login, a scoped-model change, or
- * a model rename. Keep the main session usable by replacing such overrides with
- * the model currently selected in the main window (or the first available model)
- * and let callers persist the repaired mapping.
+ * Runtime pools deliberately do not filter configured references by current
+ * availability: a stale primary/backup is attempted and normal provider/model
+ * failure handling advances to the next candidate. Setup uses the same catalog
+ * only for honest availability labels; it never rewrites persisted choices.
  */
 
+import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export type ModelContext = Pick<ExtensionContext, "model" | "scopedModels" | "modelRegistry">;
+export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
+	Partial<Pick<ExtensionContext, "scopedModels">>;
+
+export const CURRENT_MAIN_MODEL = "__current_main_model__";
+
+export type ModelPoolSlot = "primary" | "backup";
+export type ModelPickerSlot = ModelPoolSlot | "vision";
+
+export interface ModelPickerItem {
+	value: string;
+	label: string;
+	description?: string;
+	/** Visible for diagnosis/search, but cannot be selected. */
+	disabled?: boolean;
+}
+
+export type ModelListEntry = Pick<
+	Model<Api>,
+	"provider" | "id" | "name" | "input" | "reasoning"
+>;
+
+export interface ResolvedAgentModelPool {
+	/** Effective first candidate. Undefined means let pi use its normal default. */
+	primaryRef?: string;
+	/** Ordered candidates after the primary, already deduplicated. */
+	fallbackModelRefs: string[];
+	/** All known references in runtime order, useful for tests/inspection. */
+	candidateRefs: string[];
+}
+
+export interface AgentModelPoolInput {
+	primaryRef?: string;
+	backupRef?: string;
+	mainRef?: string;
+	declaredDefaultRef?: string;
+}
 
-export interface ModelOverrideRepair {
+export interface AgentModelPoolMaps {
 	agentModels: Record<string, string>;
-	changed: boolean;
-	replaced: number;
-	removed: number;
-	fallbackRef?: string;
+	agentBackupModels: Record<string, string>;
+}
+
+export interface AgentModelPoolRow {
+	name: string;
+	primary: string;
+	backup: string;
+}
+
+function cleanModelRef(ref: string | undefined): string | undefined {
+	const trimmed = ref?.trim();
+	return trimmed || undefined;
 }
 
 export function modelRef(model: { provider: string; id: string }): string {
 	return `${model.provider}/${model.id}`;
 }
 
+export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
+	return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
 /**
- * Return model references usable by the current main window, with its current
- * model first so it is the deterministic fallback for stale configuration.
+ * Models usable by this main window. Scoped models replace the full available
+ * registry, matching pi's built-in model picker semantics.
  */
 export function availableModelRefs(ctx: ModelContext): string[] {
-	const scoped = ctx.scopedModels.length > 0 ? ctx.scopedModels.map((entry) => entry.model) : undefined;
+	// scopedModels was added after the declared Pi 0.80.6 minimum. Treat a
+	// missing field exactly like an empty scope and use the registry fallback.
+	const scopedModels = ctx.scopedModels ?? [];
+	const scoped = scopedModels.length > 0 ? scopedModels.map((entry) => entry.model) : undefined;
 	const models = scoped ?? ctx.modelRegistry.getAvailable();
 	const refs = [...new Set(models.map(modelRef))];
-	const currentRef = ctx.model ? modelRef(ctx.model) : undefined;
+	const currentRef = currentModelRef(ctx);
 	if (!currentRef) return refs;
 	return [currentRef, ...refs.filter((ref) => ref !== currentRef)];
 }
 
 /**
- * Resolve the model for a `vision: true` dispatch. The configured vision model
- * wins when it is usable by the current session; otherwise the task falls back
- * to the main window's current model (the documented behavior when the vision
- * model is unset). Returns undefined only when neither exists — callers then
- * keep the agent's own model as the last resort.
+ * Resolve one agent's ordered runtime pool:
+ *
+ * configured primary -> configured backup -> current main-window model
+ *
+ * Without a primary override, the current main model remains the primary; an
+ * agent-declared default is used only when no main model exists. Equal refs are
+ * removed without consulting availability, so stale refs stay in the chain and
+ * fail normally at runtime instead of being silently repaired.
  */
-export function resolveVisionModelRef(ctx: ModelContext, visionModel?: string): string | undefined {
-	const configured = visionModel?.trim();
-	if (configured && availableModelRefs(ctx).includes(configured)) return configured;
-	return ctx.model ? modelRef(ctx.model) : undefined;
+export function resolveAgentModelPool(input: AgentModelPoolInput): ResolvedAgentModelPool {
+	const mainRef = cleanModelRef(input.mainRef);
+	const primaryRef = cleanModelRef(input.primaryRef) ?? mainRef ?? cleanModelRef(input.declaredDefaultRef);
+	const ordered = [primaryRef, cleanModelRef(input.backupRef), mainRef];
+	const seen = new Set<string>();
+	const candidateRefs: string[] = [];
+	for (const ref of ordered) {
+		if (!ref || seen.has(ref)) continue;
+		seen.add(ref);
+		candidateRefs.push(ref);
+	}
+	const fallbackModelRefs = candidateRefs.filter((ref) => ref !== primaryRef);
+	return { primaryRef, fallbackModelRefs, candidateRefs };
 }
 
-/** Replace unavailable persisted overrides with a model usable by the main session. */
-export function repairUnavailableModelOverrides(
-	ctx: ModelContext,
-	agentModels: Record<string, string>,
-): ModelOverrideRepair {
-	const refs = availableModelRefs(ctx);
-	const available = new Set(refs);
-	const fallbackRef = refs[0];
-	const repaired: Record<string, string> = {};
-	let changed = false;
-	let replaced = 0;
-	let removed = 0;
-
-	for (const [name, configuredRef] of Object.entries(agentModels)) {
-		const ref = configuredRef.trim();
-		if (available.has(ref)) {
-			repaired[name] = ref;
-			continue;
+function modelCapabilities(model: ModelListEntry): string {
+	const capabilities = [model.input.includes("image") ? "vision" : "text-only"];
+	if (model.reasoning) capabilities.push("reasoning");
+	return capabilities.join(" + ");
+}
+
+/** Build the single searchable model list shared by primary/backup/vision picks. */
+export function buildModelPickerItems(options: {
+	models: readonly ModelListEntry[];
+	availableRefs: readonly string[];
+	slot: ModelPickerSlot;
+	configuredRef?: string;
+	mainRef?: string;
+}): ModelPickerItem[] {
+	const configuredRef = cleanModelRef(options.configuredRef);
+	const mainRef = cleanModelRef(options.mainRef);
+	const available = new Set(options.availableRefs.map((ref) => ref.trim()));
+	const byRef = new Map<string, ModelListEntry>();
+	for (const model of options.models) {
+		const ref = modelRef(model);
+		if (!byRef.has(ref)) byRef.set(ref, model);
+	}
+
+	const refs = [...byRef.keys()]
+		.filter((ref) =>
+			options.slot !== "vision" ||
+			byRef.get(ref)?.input.includes("image") === true ||
+			ref === configuredRef,
+		)
+		.sort((left, right) => {
+			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
+			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
+			return leftRank - rightRank || left.localeCompare(right);
+		});
+	if (configuredRef && !byRef.has(configuredRef)) refs.unshift(configuredRef);
+
+	const dynamic = options.slot === "backup"
+		? {
+			value: CURRENT_MAIN_MODEL,
+			label: "Current main model (default)",
+			description: "Clear configured backup; use the main-window model dynamically",
 		}
+		: {
+			value: CURRENT_MAIN_MODEL,
+			label: "Current main model (dynamic)",
+			description: options.slot === "vision"
+				? "Clear vision override; use the main-window model for vision tasks"
+				: "Clear primary override; use the main-window model dynamically",
+		};
 
-		changed = true;
-		if (fallbackRef) {
-			repaired[name] = fallbackRef;
-			replaced++;
-		} else {
-			removed++;
+	const items: ModelPickerItem[] = [dynamic];
+	for (const ref of refs) {
+		const model = byRef.get(ref);
+		const tags = [available.has(ref) ? "available" : "unavailable"];
+		if (ref === configuredRef) tags.push("configured");
+		if (ref === mainRef) tags.push("current main");
+		if (!model) {
+			const compatibility = options.slot === "vision"
+				? "incompatible with vision (capability unknown)"
+				: undefined;
+			items.push({
+				value: ref,
+				label: ref,
+				description: [...tags, compatibility, "saved model reference"].filter(Boolean).join(" · "),
+				...(options.slot === "vision" ? { disabled: true } : {}),
+			});
+			continue;
 		}
+		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
+		const compatibility = options.slot === "vision" && !model.input.includes("image")
+			? "incompatible with vision"
+			: undefined;
+		items.push({
+			value: ref,
+			label: ref,
+			description: [name, modelCapabilities(model), compatibility, ...tags].filter(Boolean).join(" · "),
+			...(compatibility ? { disabled: true } : {}),
+		});
 	}
+	return items;
+}
+
+/** Pure pool update: the dynamic/default choice removes the persisted override. */
+export function applyModelPoolChoice(
+	current: AgentModelPoolMaps,
+	agentName: string,
+	slot: ModelPoolSlot,
+	choice: string,
+): AgentModelPoolMaps {
+	const next: AgentModelPoolMaps = {
+		agentModels: { ...current.agentModels },
+		agentBackupModels: { ...current.agentBackupModels },
+	};
+	const target = slot === "primary" ? next.agentModels : next.agentBackupModels;
+	if (choice === CURRENT_MAIN_MODEL) delete target[agentName];
+	else target[agentName] = choice.trim();
+	return next;
+}
 
-	return { agentModels: repaired, changed, replaced, removed, fallbackRef };
+/** Pure rows used by the overview component and focused helper tests. */
+export function buildAgentModelPoolRows(
+	agentNames: readonly string[],
+	pools: AgentModelPoolMaps,
+): AgentModelPoolRow[] {
+	return agentNames.map((name) => ({
+		name,
+		primary: pools.agentModels[name] ?? "Main (dynamic)",
+		backup: pools.agentBackupModels[name] ?? "Main (default)",
+	}));
 }