@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

package/src/modes/rpc/rpc-frame.ts

@@ -1,8 +1,24 @@
 import { isDeepStrictEqual } from "node:util";
 import { isRecord } from "@oh-my-pi/pi-utils";
+import type { RpcChunkFrame } from "./rpc-types";
 
 /** Maximum UTF-8 size of one newline-delimited RPC frame, including the newline. */
 export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+/** Maximum UTF-8 size of one logical frame reassembled by protocol v2. */
+export const MAX_RPC_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+
+const RPC_CHUNK_PAYLOAD_BYTES = 256 * 1024;
+
+export type RpcProtocolVersion = 1 | 2;
+
+interface PendingRpcChunks {
+	chunkId: string;
+	count: number;
+	byteLength: number;
+	nextIndex: number;
+	chunks: Buffer[];
+	receivedBytes: number;
+}
 
 interface ShrinkPass {
 	stringCap: number;
@@ -68,6 +84,110 @@ function encodedMessageSnapshot(encoded: string): { message: unknown } | undefin
 		: undefined;
 }
 
+/**
+ * Emit protocol v2 chunk frames for one pre-serialized logical frame, one physical
+ * JSONL line at a time so callers can write with backpressure instead of holding the
+ * whole ~4/3-sized base64 transport in memory. The reassembly ceiling is enforced on
+ * `Buffer.byteLength` BEFORE any full-payload allocation.
+ */
+function* encodeChunkedRpcFrames(frame: object, json: string, chunkId: string): Generator<string> {
+	const byteLength = Buffer.byteLength(json, "utf8");
+	if (byteLength > MAX_RPC_REASSEMBLED_BYTES) {
+		yield `${JSON.stringify(overflowFrame(frame))}\n`;
+		return;
+	}
+	const bytes = Buffer.from(json, "utf8");
+	const count = Math.ceil(byteLength / RPC_CHUNK_PAYLOAD_BYTES);
+	for (let index = 0; index < count; index++) {
+		const chunk: RpcChunkFrame = {
+			type: "rpc_chunk",
+			chunkId,
+			index,
+			count,
+			byteLength,
+			data: bytes
+				.subarray(index * RPC_CHUNK_PAYLOAD_BYTES, (index + 1) * RPC_CHUNK_PAYLOAD_BYTES)
+				.toString("base64"),
+		};
+		const line = `${JSON.stringify(chunk)}\n`;
+		if (serializedFrameBytes(line.slice(0, -1)) > MAX_RPC_FRAME_BYTES)
+			throw new Error("RPC chunk exceeded the transport limit");
+		yield line;
+	}
+}
+
+function isRpcChunkFrame(value: unknown): value is RpcChunkFrame {
+	return isRecord(value) && value.type === "rpc_chunk";
+}
+
+function decodeBase64(data: unknown): Buffer {
+	if (
+		typeof data !== "string" ||
+		data.length === 0 ||
+		!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)
+	)
+		throw new Error("invalid rpc chunk data");
+	const bytes = Buffer.from(data, "base64");
+	if (bytes.toString("base64") !== data) throw new Error("invalid rpc chunk data");
+	return bytes;
+}
+
+/** Reassemble protocol v2 chunk frames after each JSONL line has been parsed. */
+export class RpcFrameDecoder {
+	#pending?: PendingRpcChunks;
+
+	push(value: unknown): object | undefined {
+		if (!isRpcChunkFrame(value)) {
+			if (this.#pending) throw new Error("rpc chunk sequence interrupted");
+			if (!isRecord(value)) throw new Error("rpc frame must be an object");
+			return value;
+		}
+		const { chunkId, index, count, byteLength } = value;
+		if (
+			typeof chunkId !== "string" ||
+			chunkId.length === 0 ||
+			chunkId.length > 128 ||
+			!Number.isSafeInteger(index) ||
+			!Number.isSafeInteger(count) ||
+			!Number.isSafeInteger(byteLength) ||
+			index < 0 ||
+			count < 2 ||
+			count > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||
+			index >= count ||
+			byteLength < MAX_RPC_FRAME_BYTES ||
+			byteLength > MAX_RPC_REASSEMBLED_BYTES
+		)
+			throw new Error("invalid rpc chunk metadata");
+		const bytes = decodeBase64(value.data);
+		if (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error("rpc chunk payload exceeds the transport limit");
+
+		if (!this.#pending) {
+			if (index !== 0) throw new Error("rpc chunk sequence must start at index 0");
+			this.#pending = { chunkId, count, byteLength, nextIndex: 0, chunks: [], receivedBytes: 0 };
+		}
+		const pending = this.#pending;
+		if (
+			pending.chunkId !== chunkId ||
+			pending.count !== count ||
+			pending.byteLength !== byteLength ||
+			pending.nextIndex !== index
+		)
+			throw new Error("rpc chunk sequence mismatch");
+		pending.chunks.push(bytes);
+		pending.receivedBytes += bytes.byteLength;
+		pending.nextIndex++;
+		if (pending.receivedBytes > pending.byteLength) throw new Error("rpc chunk sequence exceeds declared length");
+		if (pending.nextIndex < pending.count) return undefined;
+		if (pending.receivedBytes !== pending.byteLength) throw new Error("rpc chunk sequence length mismatch");
+
+		this.#pending = undefined;
+		const decoded = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(pending.chunks));
+		const frame: unknown = JSON.parse(decoded);
+		if (!isRecord(frame)) throw new Error("rpc frame must be an object");
+		return frame;
+	}
+}
+
 function compactTerminalFrame(
 	frame: object,
 	streamedMessageCount: number,
@@ -142,15 +262,55 @@ export function encodeRpcFrame(frame: object, streamedMessageCount = 0, streamed
 /** Stateful encoder that tracks which messages a client has already received. */
 export class RpcFrameEncoder {
 	#streamedMessages: unknown[] = [];
+	#protocolVersion: RpcProtocolVersion = 1;
+	#chunkCounter = 0;
 
-	encode(frame: object): string {
+	setProtocolVersion(version: number): void {
+		if (version !== 1 && version !== 2) throw new Error(`Unsupported RPC protocol version: ${version}`);
+		this.#protocolVersion = version;
+	}
+
+	/**
+	 * Encode one logical frame into physical JSONL lines. Encoder bookkeeping runs
+	 * eagerly; only chunk emission is lazy, so a chunked result can be streamed to
+	 * stdout with backpressure without holding the whole transport in memory. The
+	 * returned iterable MUST be fully consumed exactly once.
+	 */
+	encodeFrames(frame: object): Iterable<string> {
 		if (isRecord(frame) && frame.type === "agent_start") this.#streamedMessages = [];
-		const encoded = encodeRpcFrame(frame, this.#streamedMessages.length, this.#streamedMessages);
-		if (!isRecord(frame)) return encoded;
+		const json = JSON.stringify(frame);
+		let frames: Iterable<string>;
+		let singleFrame: string | undefined;
+		if (this.#protocolVersion === 2 && serializedFrameBytes(json) > MAX_RPC_FRAME_BYTES) {
+			const compacted = compactTerminalFrame(frame, this.#streamedMessages.length, this.#streamedMessages);
+			// Reuse the original serialization when compaction was a no-op.
+			const compactedJson = compacted === frame ? json : JSON.stringify(compacted);
+			if (serializedFrameBytes(compactedJson) > MAX_RPC_FRAME_BYTES) {
+				frames = encodeChunkedRpcFrames(compacted, compactedJson, `rpc-${++this.#chunkCounter}`);
+			} else {
+				singleFrame = `${compactedJson}\n`;
+				frames = [singleFrame];
+			}
+		} else {
+			singleFrame = encodeRpcFrame(frame, this.#streamedMessages.length, this.#streamedMessages);
+			frames = [singleFrame];
+		}
+		if (!isRecord(frame)) return frames;
 		if (frame.type === "message_end") {
-			const snapshot = encodedMessageSnapshot(encoded);
+			const snapshot =
+				this.#protocolVersion === 2 && Object.hasOwn(frame, "message")
+					? { message: jsonSnapshot(frame.message) }
+					: singleFrame !== undefined
+						? encodedMessageSnapshot(singleFrame)
+						: undefined;
 			if (snapshot) this.#streamedMessages.push(snapshot.message);
 		} else if (frame.type === "agent_end" && frame.willContinue !== true) this.#streamedMessages = [];
+		return frames;
+	}
+
+	encode(frame: object): string {
+		let encoded = "";
+		for (const line of this.encodeFrames(frame)) encoded += line;
 		return encoded;
 	}
 }

package/src/modes/rpc/rpc-messages.ts

@@ -0,0 +1,127 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { isRecord } from "@oh-my-pi/pi-utils";
+
+const DEFAULT_RPC_MESSAGE_PAGE_LIMIT = 100;
+const MAX_RPC_MESSAGE_PAGE_LIMIT = 256;
+const MAX_RPC_MESSAGE_PAGE_BYTES = 768 * 1024;
+const MAX_RPC_MESSAGE_CURSOR_CHARS = 2048;
+
+export const RPC_MESSAGES_PAGE_BUSY_ERROR = "Cannot page messages while the session is changing";
+export const RPC_MESSAGES_PAGE_STALE_ERROR = "RPC message cursor is stale";
+
+/** Machine-readable reasons a `get_messages_page` request can fail; carried as `code` on the error response. */
+export type RpcMessagesPageErrorCode = "session_busy" | "stale_cursor";
+
+/** Paging failure that maps to a structured wire `code`, so clients can react without matching message text. */
+export class RpcMessagesPageError extends Error {
+	constructor(
+		message: string,
+		readonly code: RpcMessagesPageErrorCode,
+	) {
+		super(message);
+		this.name = "RpcMessagesPageError";
+	}
+}
+
+export interface RpcMessageSnapshot {
+	sessionId: string;
+	leafId: string | null;
+	messageCount: number;
+}
+
+export interface RpcMessagesPage {
+	messages: AgentMessage[];
+	nextCursor?: string;
+	totalMessages: number;
+}
+
+interface RpcMessageCursorPayload extends RpcMessageSnapshot {
+	version: 1;
+	offset: number;
+}
+
+export interface RpcMessagesPageOptions {
+	cursor?: string;
+	limit?: number;
+}
+
+function encodeCursor(snapshot: RpcMessageSnapshot, offset: number): string {
+	const payload: RpcMessageCursorPayload = { version: 1, ...snapshot, offset };
+	return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+
+function decodeCursor(cursor: string): RpcMessageCursorPayload {
+	if (cursor.length === 0 || cursor.length > MAX_RPC_MESSAGE_CURSOR_CHARS || !/^[A-Za-z0-9_-]+$/.test(cursor))
+		throw new Error("Invalid RPC message cursor");
+	const bytes = Buffer.from(cursor, "base64url");
+	if (bytes.toString("base64url") !== cursor) throw new Error("Invalid RPC message cursor");
+	let value: unknown;
+	try {
+		value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+	} catch {
+		throw new Error("Invalid RPC message cursor");
+	}
+	if (!isRecord(value)) throw new Error("Invalid RPC message cursor");
+	const { version, sessionId, leafId, messageCount, offset } = value;
+	if (
+		version !== 1 ||
+		typeof sessionId !== "string" ||
+		sessionId.length === 0 ||
+		sessionId.length > 256 ||
+		!((typeof leafId === "string" && leafId.length > 0 && leafId.length <= 256) || leafId === null) ||
+		typeof messageCount !== "number" ||
+		!Number.isSafeInteger(messageCount) ||
+		messageCount < 0 ||
+		typeof offset !== "number" ||
+		!Number.isSafeInteger(offset) ||
+		offset < 0 ||
+		offset > messageCount
+	)
+		throw new Error("Invalid RPC message cursor");
+	return { version, sessionId, leafId, messageCount, offset };
+}
+
+function sameSnapshot(cursor: RpcMessageCursorPayload, snapshot: RpcMessageSnapshot): boolean {
+	return (
+		cursor.sessionId === snapshot.sessionId &&
+		cursor.leafId === snapshot.leafId &&
+		cursor.messageCount === snapshot.messageCount
+	);
+}
+
+/** Page one stable in-memory message snapshot without crossing the v1 frame budget. */
+export function pageRpcMessages(
+	messages: readonly AgentMessage[],
+	snapshot: RpcMessageSnapshot,
+	options: RpcMessagesPageOptions = {},
+): RpcMessagesPage {
+	if (snapshot.messageCount !== messages.length)
+		throw new Error("RPC message snapshot does not match current messages");
+	const limit = options.limit ?? DEFAULT_RPC_MESSAGE_PAGE_LIMIT;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RPC_MESSAGE_PAGE_LIMIT)
+		throw new Error(`RPC message page limit must be between 1 and ${MAX_RPC_MESSAGE_PAGE_LIMIT}`);
+	let offset = 0;
+	if (options.cursor !== undefined) {
+		const cursor = decodeCursor(options.cursor);
+		if (!sameSnapshot(cursor, snapshot))
+			throw new RpcMessagesPageError(RPC_MESSAGES_PAGE_STALE_ERROR, "stale_cursor");
+		offset = cursor.offset;
+	}
+
+	const page: AgentMessage[] = [];
+	let pageBytes = 2;
+	while (offset + page.length < messages.length && page.length < limit) {
+		const message = messages[offset + page.length];
+		const messageBytes = Buffer.byteLength(JSON.stringify(message), "utf8") + (page.length === 0 ? 0 : 1);
+		if (page.length > 0 && pageBytes + messageBytes > MAX_RPC_MESSAGE_PAGE_BYTES) break;
+		page.push(message);
+		pageBytes += messageBytes;
+	}
+
+	const nextOffset = offset + page.length;
+	return {
+		messages: page,
+		...(nextOffset < messages.length ? { nextCursor: encodeCursor(snapshot, nextOffset) } : {}),
+		totalMessages: messages.length,
+	};
+}

package/src/modes/rpc/rpc-mode.ts

@@ -10,6 +10,7 @@
  * - Events: AgentSessionEvent objects streamed as they occur
  * - Extension UI: Extension UI requests are emitted, client responds with extension_ui_response
  */
+import { once } from "node:events";
 import { getOAuthProviders } from "@oh-my-pi/pi-ai/oauth";
 import { isZodSchema, zodToWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
 import { $env, isRecord, readLines, Snowflake } from "@oh-my-pi/pi-utils";
@@ -34,8 +35,9 @@ import type { EventBus } from "../../utils/event-bus";
 import { initializeExtensions } from "../runtime-init";
 import { isRpcHostToolResult, isRpcHostToolUpdate, RpcHostToolBridge } from "./host-tools";
 import { isRpcHostUriResult, RpcHostUriBridge } from "./host-uris";
-import { RpcFrameEncoder } from "./rpc-frame";
+import { MAX_RPC_FRAME_BYTES, MAX_RPC_REASSEMBLED_BYTES, RpcFrameEncoder } from "./rpc-frame";
 import { claimRpcInput } from "./rpc-input";
+import { pageRpcMessages, RPC_MESSAGES_PAGE_BUSY_ERROR, RpcMessagesPageError } from "./rpc-messages";
 import { RpcSubagentRegistry, readRpcSubagentTranscript } from "./rpc-subagents";
 import type {
 	RpcCommand,
@@ -619,9 +621,33 @@ export async function runRpcMode(
 	process.env.PI_NOTIFICATIONS = "off";
 
 	const frameEncoder = new RpcFrameEncoder();
-	process.stdout.write(frameEncoder.encode({ type: "ready" }));
+	// Ordered stdout writer honoring backpressure: chunked v2 frames are produced
+	// lazily by the encoder and written one physical line at a time, so a near-limit
+	// logical frame never materializes its full base64 transport in memory.
+	let stdoutQueue: Promise<void> = Promise.resolve();
+	const writeFrames = (frames: Iterable<string>) => {
+		stdoutQueue = stdoutQueue
+			.then(async () => {
+				for (const line of frames) {
+					if (!process.stdout.write(line)) await once(process.stdout, "drain");
+				}
+			})
+			// stdout gone (host exited) — nothing left to deliver; keep the queue alive.
+			.catch(() => {});
+	};
+	writeFrames(
+		frameEncoder.encodeFrames({
+			type: "ready",
+			protocolVersion: 1,
+			supportedProtocolVersions: [1, 2],
+			maxFrameBytes: MAX_RPC_FRAME_BYTES,
+			maxReassembledFrameBytes: MAX_RPC_REASSEMBLED_BYTES,
+		}),
+	);
 	const output = (obj: RpcResponse | RpcExtensionUIRequest | object) => {
-		process.stdout.write(frameEncoder.encode(obj));
+		writeFrames(frameEncoder.encodeFrames(obj));
+		if (isRecord(obj) && obj.type === "response" && obj.command === "negotiate_protocol" && obj.success === true)
+			frameEncoder.setProtocolVersion(2);
 	};
 	const emitRpcTitles = shouldEmitRpcTitles();
 
@@ -636,8 +662,8 @@ export async function runRpcMode(
 		return { id, type: "response", command, success: true, data } as RpcResponse;
 	};
 
-	const error = (id: string | undefined, command: string, message: string): RpcResponse => {
-		return { id, type: "response", command, success: false, error: message };
+	const error = (id: string | undefined, command: string, message: string, code?: string): RpcResponse => {
+		return { id, type: "response", command, success: false, error: message, ...(code ? { code } : {}) };
 	};
 
 	const extensionUserMessageTracker = new RpcExtensionUserMessageTracker();
@@ -936,6 +962,12 @@ export async function runRpcMode(
 		const id = command.id;
 
 		switch (command.type) {
+			case "negotiate_protocol": {
+				if (command.protocolVersion !== 2)
+					return error(id, "negotiate_protocol", `Unsupported RPC protocol version: ${command.protocolVersion}`);
+				return success(id, "negotiate_protocol", { protocolVersion: 2 });
+			}
+
 			// =================================================================
 			// Prompting
 			// =================================================================
@@ -1122,8 +1154,19 @@ export async function runRpcMode(
 			// =================================================================
 
 			case "set_model": {
-				const models = session.getAvailableModels();
-				const model = models.find(m => m.provider === command.provider && m.id === command.modelId);
+				let models = session.getAvailableModels();
+				let model = models.find(m => m.provider === command.provider && m.id === command.modelId);
+				if (!model) {
+					// Model not in the current catalog. Wait for in-flight
+					// background discovery before declaring it missing: on cold
+					// start, discovery-backed providers (proxy / ollama / etc.)
+					// populate seconds after session ready. Models already in
+					// the bundled catalog skip this await entirely so the RPC
+					// queue is not stalled behind unrelated discovery.
+					await session.modelRegistry.awaitBackgroundRefresh();
+					models = session.getAvailableModels();
+					model = models.find(m => m.provider === command.provider && m.id === command.modelId);
+				}
 				if (!model) {
 					return error(id, "set_model", `Model not found: ${command.provider}/${command.modelId}`);
 				}
@@ -1140,6 +1183,7 @@ export async function runRpcMode(
 			}
 
 			case "get_available_models": {
+				await session.modelRegistry.awaitBackgroundRefresh();
 				const models = session.getAvailableModels();
 				return success(id, "get_available_models", { models });
 			}
@@ -1277,6 +1321,34 @@ export async function runRpcMode(
 				return success(id, "get_messages", { messages: session.messages });
 			}
 
+			case "get_messages_page": {
+				if (session.isStreaming || session.isCompacting)
+					return error(id, "get_messages_page", RPC_MESSAGES_PAGE_BUSY_ERROR, "session_busy");
+				const messages = session.messages;
+				try {
+					return success(
+						id,
+						"get_messages_page",
+						pageRpcMessages(
+							messages,
+							{
+								sessionId: session.sessionId,
+								leafId: session.sessionManager.getLeafId(),
+								messageCount: messages.length,
+							},
+							{ cursor: command.cursor, limit: command.limit },
+						),
+					);
+				} catch (pageError) {
+					return error(
+						id,
+						"get_messages_page",
+						pageError instanceof Error ? pageError.message : String(pageError),
+						pageError instanceof RpcMessagesPageError ? pageError.code : undefined,
+					);
+				}
+			}
+
 			// =================================================================
 			// Login
 			// =================================================================

package/src/modes/rpc/rpc-types.ts

@@ -19,12 +19,16 @@ import type {
 	SubagentProgressPayload,
 } from "../../task";
 import type { TodoPhase } from "../../tools/todo";
+import type { RpcMessagesPage } from "./rpc-messages";
 
 // ============================================================================
 // RPC Commands (stdin)
 // ============================================================================
 
 export type RpcCommand =
+	// Protocol
+	| { id?: string; type: "negotiate_protocol"; protocolVersion: number }
+
 	// Prompting
 	| { id?: string; type: "prompt"; message: string; images?: ImageContent[]; streamingBehavior?: "steer" | "followUp" }
 	| { id?: string; type: "steer"; message: string; images?: ImageContent[] }
@@ -81,6 +85,7 @@ export type RpcCommand =
 
 	// Messages
 	| { id?: string; type: "get_messages" }
+	| { id?: string; type: "get_messages_page"; cursor?: string; limit?: number }
 
 	// Login
 	| { id?: string; type: "get_login_providers" }
@@ -132,6 +137,23 @@ export interface RpcPromptResultFrame {
 	agentInvoked: boolean;
 }
 
+export interface RpcReadyFrame {
+	type: "ready";
+	protocolVersion: 1;
+	supportedProtocolVersions: [1, 2];
+	maxFrameBytes: number;
+	maxReassembledFrameBytes: number;
+}
+
+export interface RpcChunkFrame {
+	type: "rpc_chunk";
+	chunkId: string;
+	index: number;
+	count: number;
+	byteLength: number;
+	data: string;
+}
+
 export interface RpcHandoffResult {
 	savedPath?: string;
 }
@@ -168,6 +190,15 @@ export interface RpcSubagentMessagesResult {
 
 // Success responses with data
 export type RpcResponse =
+	// Protocol
+	| {
+			id?: string;
+			type: "response";
+			command: "negotiate_protocol";
+			success: true;
+			data: { protocolVersion: 2 };
+	  }
+
 	// Prompting (async - events follow)
 	| { id?: string; type: "response"; command: "prompt"; success: true; data?: { agentInvoked: boolean } }
 	| { id?: string; type: "response"; command: "steer"; success: true }
@@ -284,6 +315,7 @@ export type RpcResponse =
 
 	// Messages
 	| { id?: string; type: "response"; command: "get_messages"; success: true; data: { messages: AgentMessage[] } }
+	| { id?: string; type: "response"; command: "get_messages_page"; success: true; data: RpcMessagesPage }
 
 	// Login
 	| {
@@ -295,8 +327,8 @@ export type RpcResponse =
 	  }
 	| { id?: string; type: "response"; command: "login"; success: true; data: { providerId: string } }
 
-	// Error response (any command can fail)
-	| { id?: string; type: "response"; command: string; success: false; error: string };
+	// Error response (any command can fail); `code` is an optional machine-readable reason.
+	| { id?: string; type: "response"; command: string; success: false; error: string; code?: string };
 
 // ============================================================================
 // Subagent Events (stdout)

package/src/modes/runtime-init.ts

@@ -90,6 +90,8 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 			setModel: model => runExtensionSetModel(session, model),
 			getThinkingLevel: () => session.thinkingLevel,
 			setThinkingLevel: level => session.setThinkingLevel(level),
+			getServiceTiers: () => session.serviceTierByFamily,
+			setServiceTier: (family, tier) => session.setServiceTierFamily(family, tier),
 			getSessionName: () => session.sessionManager.getSessionName(),
 			setSessionName: async name => {
 				await session.sessionManager.setSessionName(name, "user");

package/src/modes/setup-wizard/scenes/model.ts

@@ -10,7 +10,8 @@ import { theme } from "../../theme/theme";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
 const MAX_VISIBLE_MODELS = 10;
-const WIZARD_SCREEN_RESERVE = 22;
+/** ModelBrowser chrome: search row + blank above the list, blank + two detail rows below. */
+const BROWSER_FRAME_ROWS = 5;
 
 class ModelSceneController implements SetupSceneController {
 	title = "Choose your default model";
@@ -54,16 +55,13 @@ class ModelSceneController implements SetupSceneController {
 		this.#browser.routeMouse(event, line - this.#browserRowStart);
 	}
 
-	render(width: number): readonly string[] {
-		const visibleRows = Math.max(
-			1,
-			Math.min(MAX_VISIBLE_MODELS, this.host.ctx.ui.terminal.rows - WIZARD_SCREEN_RESERVE),
-		);
-		this.#browser.setMaxVisible(visibleRows);
+	render(width: number, maxLines?: number): readonly string[] {
 		const lines = [
 			this.#status ?? theme.fg("muted", "Type to search. Enter saves the highlighted model as your default."),
 			"",
 		];
+		const budget = maxLines === undefined ? MAX_VISIBLE_MODELS : maxLines - lines.length - BROWSER_FRAME_ROWS;
+		this.#browser.setMaxVisible(Math.max(1, Math.min(MAX_VISIBLE_MODELS, budget)));
 		this.#browserRowStart = lines.length;
 		lines.push(...this.#browser.render(width));
 		return lines;

package/src/modes/setup-wizard/scenes/providers.ts

@@ -85,10 +85,11 @@ class ProvidersSceneController implements SetupSceneController {
 		}
 	}
 
-	render(width: number): readonly string[] {
+	render(width: number, maxLines?: number): readonly string[] {
 		const tabLines = this.#tabBar.render(width);
 		this.#tabRowCount = tabLines.length;
-		return [...tabLines, "", ...this.#activeTab().render(width)];
+		const tabBudget = maxLines === undefined ? undefined : Math.max(1, maxLines - tabLines.length - 1);
+		return [...tabLines, "", ...this.#activeTab().render(width, tabBudget)];
 	}
 
 	dispose(): void {

package/src/modes/setup-wizard/scenes/sign-in.ts

@@ -131,13 +131,19 @@ export class SignInTab implements SetupTab {
 		this.#selector.routeMouse(event, line - this.#selectorRowStart, col);
 	}
 
-	render(width: number): readonly string[] {
+	render(width: number, maxLines?: number): readonly string[] {
 		const lines: string[] = [];
 		if (this.#loggingInProvider) {
 			lines.push(theme.bold(`Signing in to ${this.#loggingInProvider}`));
 		} else {
-			lines.push(theme.fg("muted", "Pick a provider to sign in — you can connect more than one."), "");
+			// Hint + blank cost two rows; the wizard subtitle already explains
+			// this panel, so on short screens the rows go to the provider list
+			// instead (17 = full selector: 4 chrome above, 10 rows, 3 below).
+			if (maxLines === undefined || maxLines >= 17 + 2) {
+				lines.push(theme.fg("muted", "Pick a provider to sign in — you can connect more than one."), "");
+			}
 			this.#selectorRowStart = lines.length;
+			if (maxLines !== undefined) this.#selector.setMaxHeight(maxLines - lines.length);
 			lines.push(...this.#selector.render(width));
 		}
 

package/src/modes/setup-wizard/scenes/theme.ts

@@ -136,21 +136,31 @@ class ThemeSceneController implements SetupSceneController {
 		routeSelectListMouse(this.#selectList, event, listLine);
 	}
 
-	render(width: number): readonly string[] {
+	render(width: number, maxLines?: number): readonly string[] {
+		const budget = maxLines ?? Number.POSITIVE_INFINITY;
 		const lines = [
 			theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."),
 			this.#mode === "all"
 				? theme.fg("dim", "Browsing all themes · Esc returns to curated choices")
 				: theme.fg("dim", "Esc skips this step"),
 			"",
-			...renderThemePreview(width),
-			"",
 		];
+		// The mock status-line/editor block is decorative — the wizard itself
+		// re-renders in the highlighted theme — so it yields to the list when
+		// it would squeeze the window below the six curated rows (+1 for the
+		// list's own search-status row).
+		const preview = renderThemePreview(width);
+		if (budget - lines.length - (preview.length + 1) - 1 >= CURATED_ITEMS.length) {
+			lines.push(...preview, "");
+		}
 		if (this.#loadingAllThemes) {
 			this.#listRowStart = -1;
 			lines.push(theme.fg("dim", "Loading themes…"));
 		} else {
 			this.#listRowStart = lines.length;
+			if (maxLines !== undefined) {
+				this.#selectList.setMaxVisible(Math.max(1, Math.min(10, budget - lines.length - 1)));
+			}
 			lines.push(...this.#selectList.render(width));
 		}
 		if (this.#message) {