main.ts

// allow: SIZE_OK - CLI coordinator is pre-existing oversized glue; a full main split needs behavior-locked follow-up coverage.
/**
 * Main entry point for the coding agent CLI.
 *
 * This file handles CLI argument parsing and translates them into
 * createAgentSession() options. The SDK does the heavy lifting.
 */

import { existsSync } from "node:fs";
import { join } from "node:path";
import { createInterface } from "node:readline";
import { type ImageContent, modelsAreEqual } from "@earendil-works/pi-ai";
import { setCapabilityOverrides } from "@earendil-works/pi-tui";
import chalk from "chalk";
import { type Args, type Mode, normalizeSessionName, parseArgs, printHelp, resolveSessionRuntime } from "./cli/args.ts";
import {
	type AuthCheckResult,
	checkProviderAuth,
	createAuthCheckModelRuntime,
	getProviderCredential,
} from "./cli/auth-check.ts";
import {
	type AuthCommand,
	AuthCommandError,
	getAuthCommandName,
	getAuthCommandUsage,
	isAuthCommandHelp,
	parseAuthCommand,
	printAuthCommandHelp,
	validateAuthCommandArgs,
} from "./cli/auth-command.ts";
import { movedSessionToContinue } from "./cli/continue-moved.ts";
import { resolveCredentialForPrint } from "./cli/credential-print.ts";
import { chooseCrossProjectAction, confirmSameRepositoryRebind } from "./cli/cross-project-session.ts";
import {
	dispatchConfigCommand,
	dispatchHostCommand,
	dispatchPackageCommand,
	dispatchScheduleCommand,
} from "./cli/deferred-commands.ts";
import { processFileArguments } from "./cli/file-processor.ts";
import { resolveHelpExtensionFlags } from "./cli/help-extension-flags.ts";
import { helpFlagsScope, isPlainHelpRequest, resolveHelpProjectTrust } from "./cli/help-fast-path.ts";
import { writeHelpFlagsCache } from "./cli/help-flags-cache.ts";
import { buildInitialMessage } from "./cli/initial-message.ts";
import { listModels } from "./cli/list-models.ts";
import { isModelsDiscoverCommand, runModelsDiscoverCommand } from "./cli/models-command.ts";
import { printPromptSizes } from "./cli/print-prompt-sizes.ts";
import { pipedStdinOptions } from "./cli/piped-stdin-options.ts";
import { exitAfterOutput, printThenExit } from "./cli/print-then-exit.ts";
import { createProjectTrustContext } from "./cli/project-trust.ts";
import { prepareSessionOpening } from "./cli/session-opening.ts";
import {
	createStartupLoadingIndicator,
	pauseIndicatorDuringPrompts,
	shouldShowStartupLoadingIndicator,
} from "./cli/startup-loading-indicator.ts";
import { shouldRunFirstTimeSetup, showFirstTimeSetup, showStartupSelector } from "./cli/startup-ui.ts";
import { resolveToolRuntime, type ToolRuntimeKind } from "./cli/tool-runtime.ts";
import {
	APP_NAME,
	DISPLAY_VERSION,
	ENV_SESSION_DIR,
	expandTildePath,
	getAgentDir,
	getInstallPackageDir,
} from "./config.ts";
import {
	applyRetryFallbackProfile,
	type CreateAgentSessionRuntimeFactory,
	createAgentSessionRuntime,
} from "./core/agent-session-runtime.ts";
import {
	type AgentSessionRuntimeDiagnostic,
	createAgentSessionFromServices,
	createAgentSessionServices,
} from "./core/agent-session-services.ts";
import { formatNoModelsAvailableMessage } from "./core/auth-guidance.ts";
import { AuthStorage, ReadOnlyAuthStorage } from "./core/auth-storage.ts";
import { envValue } from "./core/brand.ts";
import { type CredentialAccountSummary, summarizeCredentialAccounts } from "./core/credential-accounts.ts";
import { exportFromFile } from "./core/export-html/index.ts";
import { ModelUsabilityBudgetError } from "./core/extensions/builtin/compaction/model-usability-budget.ts";
import { resolveMovedPath } from "./core/extensions/builtin/moved-path-guard/resolve.ts";
import type { InlineExtension } from "./core/extensions/types.ts";
import { applyHttpProxySettings, configureHttpDispatcher } from "./core/http-dispatcher.ts";
import { installMemoryReportSignal } from "./core/memory-report/memory-report-write.ts";
import {
	getModelNarrowingPatterns,
	resolveCliModel,
	resolveModelScope,
	type ScopedModel,
} from "./core/model-resolver.ts";
import { ModelRuntime } from "./core/model-runtime.ts";
import { markMovedSessions, movedHereSessionToContinue, withMovedSessions } from "./core/moved-sessions.ts";
import { restoreStdout, takeOverStdout } from "./core/output-guard.ts";
import { recordProcessLifetime } from "./core/process-crash-record.ts";
import { type AppMode, presetTrustsProject, resolveProjectTrusted } from "./core/project-trust.ts";
import { resolveResumeTarget } from "./core/resume-target.ts";
import type { CreateAgentSessionOptions } from "./core/sdk.ts";
import {
	formatMissingSessionCwdPrompt,
	getMissingSessionCwdIssue,
	MissingSessionCwdError,
	type SessionCwdIssue,
} from "./core/session-cwd.ts";
import { sessionExtensionFlagValues } from "./core/session-extension-flags.ts";
import { assertValidSessionId, SessionManager, sessionFileNameId } from "./core/session-manager.ts";
import { classifySessionRepository, readSessionCwd, rebindSessionFile } from "./core/session-rebind.ts";
import { collectSettingsDiagnosticsWithContext } from "./core/settings-diagnostics.ts";
import { SettingsManager } from "./core/settings-manager.ts";
import { startSubscriptionUsagePolling } from "./core/subscription-limits/usage-poller.ts";
import { type ClampedThinkingSelection, formatThinkingClampWarning } from "./core/thinking-levels.ts";
import { printTimings, recordTiming, resetTimings, time } from "./core/timings.ts";
import { hasTrustRequiringProjectResources, ProjectTrustStore } from "./core/trust-manager.ts";
import { builtInExtensions } from "./extensions/index.ts";
import { getFromSourceRealConfigWarning } from "./from-source-config-guard.ts";
import { legacyPiEditStartupNotice } from "./legacy-pi-edits.ts";
import { runMigrations, showDeprecationWarnings } from "./migrations.ts";
import { initTheme, stopThemeWatcher } from "./modes/interactive/theme/theme.ts";
import { runPrintMode } from "./modes/print-mode.ts";
import { startHostChildReaper } from "./modes/rpc/child-reaper.ts";
import { AUTO_TITLE_SESSIONS_CAPABILITY, parseClientCapabilities } from "./modes/rpc/custom-capability.ts";
import type { PreparableRuntimeFactory, PrepareRuntimeOptions } from "./modes/rpc/host-warm.ts";
import { dispatchInternalSupervisor } from "./modes/rpc/supervisor-route.ts";
import { isLocalPath, normalizePath, resolvePath } from "./utils/paths.ts";
import { readPipedStdin } from "./utils/piped-stdin.ts";
import { cleanupWindowsSelfUpdateQuarantine } from "./utils/windows-self-update.ts";

const EXTENSION_LOAD_FAILURE_HINT = `Hint: Start without extensions using "${APP_NAME} -ne".`;

/**
 * Auth problems for a run's diagnostics. Each credential notice appears once per process; with
 * `persistSeen` (a run a person reads) it is also recorded as seen, so later runs stay quiet until
 * the problem changes (senpi#3486).
 */
export function collectAuthDiagnostics(
	authStorage: AuthStorage,
	context: string,
	options: { persistSeen: boolean },
): AgentSessionRuntimeDiagnostic[] {
	return [
		...authStorage.drainErrors().map((error) => error.message),
		...authStorage.takePendingNotices(options).map((notice) => notice.message),
	].map((message) => ({ type: "warning", message: `(${context}, auth storage) ${message}` }));
}

/** The TUI shows auth problems at startup; credential notices are marked seen once shown (senpi#3486). */
export function interactiveAuthNotices(authStorage: AuthStorage): { messages: string[]; markSeen: () => void } {
	const pending = authStorage.takePendingNotices({ persistSeen: false });
	return {
		messages: [
			...authStorage.drainErrors().map((error) => error.message),
			...pending.map((notice) => notice.message),
		],
		markSeen: () => authStorage.markNoticesSeen(pending.map((notice) => notice.id)),
	};
}

export function collectExtensionLoadDiagnostics(
	errors: readonly { path: string; error: string }[],
): AgentSessionRuntimeDiagnostic[] {
	return errors.map(({ path, error }) => ({
		type: "warning",
		message: `Failed to load extension "${path}": ${error}`,
	}));
}

function reportDiagnostics(diagnostics: readonly AgentSessionRuntimeDiagnostic[]): void {
	for (const diagnostic of diagnostics) {
		const color = diagnostic.type === "error" ? chalk.red : diagnostic.type === "warning" ? chalk.yellow : chalk.dim;
		const prefix = diagnostic.type === "error" ? "Error: " : diagnostic.type === "warning" ? "Warning: " : "";
		console.error(color(`${prefix}${diagnostic.message}`));
	}
}

function isTruthyEnvFlag(value: string | undefined): boolean {
	if (!value) return false;
	return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
}

function resolveAppMode(parsed: Args, stdinIsTTY: boolean, stdoutIsTTY: boolean): AppMode {
	if (parsed.mode === "rpc") {
		return "rpc";
	}
	if (parsed.mode === "json") {
		return "json";
	}
	if (parsed.print || !stdinIsTTY || !stdoutIsTTY) {
		return "print";
	}
	return "interactive";
}

function toPrintOutputMode(appMode: AppMode): Exclude<Mode, "rpc"> {
	return appMode === "json" ? "json" : "text";
}

/**
 * Interactive launches auto-title by default. RPC clients can opt in through
 * `auto_title_sessions`; every other non-interactive app mode opts in with
 * `--auto-title-sessions`. A per-session `open_session.auto_title`, when present,
 * replaces that host-wide decision for that session only. Sessions resumed with
 * existing context messages are never retitled, whatever the mode, capability,
 * flag, or per-session override.
 */
export function resolveAutoTitleSessions(
	appMode: AppMode,
	parsed: Args,
	hasContextMessages: boolean,
	clientCapabilities: readonly string[] = parseClientCapabilities(envValue("RPC_CLIENT_CAPABILITIES")),
	sessionAutoTitle?: boolean,
): boolean {
	if (hasContextMessages) return false;
	if (sessionAutoTitle !== undefined) return sessionAutoTitle;
	return (
		appMode === "interactive" ||
		parsed.autoTitleSessions === true ||
		(appMode === "rpc" && clientCapabilities.includes(AUTO_TITLE_SESSIONS_CAPABILITY))
	);
}

function isPlainRuntimeMetadataCommand(parsed: Args): boolean {
	return (
		!parsed.print &&
		parsed.mode === undefined &&
		(parsed.help === true || parsed.listModels !== undefined || parsed.listTips === true)
	);
}

async function runAuthCommand(args: string[]): Promise<boolean> {
	if (isAuthCommandHelp(args)) {
		printAuthCommandHelp();
		return true;
	}

	let command: AuthCommand | undefined;
	try {
		command = parseAuthCommand(args);
	} catch (error) {
		const message = error instanceof AuthCommandError ? error.message : "Failed to parse auth command";
		console.error(chalk.red(`Error: ${message}`));
		process.exitCode = 1;
		return true;
	}
	if (!command) return false;

	const parsed = parseArgs(command.args);
	if (parsed.unknownFlags.size > 0) {
		const option = parsed.unknownFlags.keys().next().value;
		console.error(chalk.red(`Unknown option --${option} for "${getAuthCommandName(command.kind)}".`));
		console.error(chalk.dim(`Use "${APP_NAME} --help" or "${getAuthCommandUsage(command.kind)}".`));
		process.exitCode = 1;
		return true;
	}
	try {
		if (parsed.diagnostics.length > 0) {
			throw new AuthCommandError(parsed.diagnostics.map((diagnostic) => diagnostic.message).join("\n"));
		}
		if (command.kind !== "check") {
			const signal = AbortSignal.timeout(15_000);
			const modelRuntime = await ModelRuntime.create({ allowModelNetwork: false, signal });
			const credential = await resolveCredentialForPrint(
				parsed,
				modelRuntime,
				command.kind,
				command.minExpiryMs,
				signal,
			);
			process.stdout.write(`${credential}\n`);
			return true;
		}

		const requestedAuth = validateAuthCommandArgs(parsed, command.kind);
		let result: AuthCheckResult;
		let credential: string | undefined;
		try {
			const credentials = command.noRefresh ? new ReadOnlyAuthStorage() : AuthStorage.create();
			const modelRuntime = await createAuthCheckModelRuntime(credentials);
			result = await checkProviderAuth(parsed, modelRuntime, { refresh: !command.noRefresh });
			if (command.credentials && result.status === "ready") {
				credential = await getProviderCredential(result.provider, modelRuntime, credentials, {
					refresh: !command.noRefresh,
				});
				if (!credential) {
					result = { status: "not_ready", provider: result.provider, reason: "credential_not_available" };
				}
			}
		} catch {
			result = {
				status: "invalid",
				provider: requestedAuth.provider ?? requestedAuth.model!,
				reason: "invalid_state",
			};
		}
		let accounts: CredentialAccountSummary[] = [];
		if (command.json && result.status !== "invalid") {
			try {
				const credentials = command.noRefresh ? new ReadOnlyAuthStorage() : AuthStorage.create();
				accounts = await summarizeCredentialAccounts(result.provider, await credentials.read(result.provider));
			} catch {
				// Account enrichment must never turn a readable auth state into a failure.
			}
		}
		const output = command.json
			? JSON.stringify({ ...result, accounts, ...(credential ? { credentials: credential } : {}) })
			: (credential ?? result.status);
		process.stdout.write(`${output}\n`);
		process.exitCode = result.status === "ready" ? 0 : result.status === "not_ready" ? 1 : 2;
	} catch (error) {
		const message = error instanceof AuthCommandError ? error.message : "Failed to resolve credential";
		console.error(chalk.red(`Error: ${message}`));
		process.exitCode = command.kind === "check" ? 2 : 1;
	}
	return true;
}

async function prepareInitialMessage(
	parsed: Args,
	autoResizeImages: boolean,
	stdinContent?: string,
): Promise<{
	initialMessage?: string;
	initialImages?: ImageContent[];
	initialTitlePrompt?: string;
}> {
	if (parsed.fileArgs.length === 0) {
		return buildInitialMessage({ parsed, stdinContent });
	}

	const { text, images } = await processFileArguments(parsed.fileArgs, { autoResizeImages });
	return buildInitialMessage({
		parsed,
		fileText: text,
		fileImages: images,
		stdinContent,
	});
}

/** Result from resolving a session argument */
type ResolvedSession =
	| { type: "path"; path: string } // Direct file path
	| { type: "local"; path: string } // Found in current project
	| { type: "global"; path: string; cwd: string } // Found in different project
	| { type: "not_found"; arg: string }; // Not found anywhere

/**
 * Resolve a session argument to a file path.
 * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.
 */
async function findLocalSessionByExactId(
	sessionId: string,
	cwd: string,
	sessionDir?: string,
): Promise<{ type: "local"; path: string } | undefined> {
	const localSessions = sessionDir ? await SessionManager.listAll(sessionDir) : await SessionManager.list(cwd);
	// The id a file name carries counts too: a session named after it must not get a second file under that id.
	const localMatch =
		localSessions.find((s) => s.id === sessionId) ??
		localSessions.find((s) => sessionFileNameId(s.path) === sessionId);
	return localMatch ? { type: "local", path: localMatch.path } : undefined;
}

/** Header id first, then the id the file name carries (what a resume hint printed), then an id prefix. */
function findSessionByIdOrFileName<T extends { id: string; path: string }>(sessions: T[], arg: string): T | undefined {
	return (
		sessions.find((s) => s.id === arg) ??
		sessions.find((s) => sessionFileNameId(s.path) === arg) ??
		sessions.find((s) => s.id.startsWith(arg))
	);
}

async function resolveSessionPath(sessionArg: string, cwd: string, sessionDir?: string): Promise<ResolvedSession> {
	// If it looks like a file path, resolve it before handing it to the session manager.
	if (sessionArg.includes("/") || sessionArg.includes("\\") || sessionArg.endsWith(".jsonl")) {
		return { type: "path", path: resolvePath(sessionArg, cwd) };
	}

	// Try to match as session ID in current project first
	const localSessions = await SessionManager.list(cwd, sessionDir);
	const localMatch = findSessionByIdOrFileName(localSessions, sessionArg);

	if (localMatch) {
		return { type: "local", path: localMatch.path };
	}

	// Try global search across all projects
	const allSessions = await SessionManager.listAll(sessionDir);
	const globalMatch = findSessionByIdOrFileName(allSessions, sessionArg);

	if (globalMatch) {
		return { type: "global", path: globalMatch.path, cwd: globalMatch.cwd };
	}

	// Not found anywhere
	return { type: "not_found", arg: sessionArg };
}

/**
 * Prompt user for yes/no confirmation.
 * Resolves false on stdin EOF (Ctrl+D, closed pipe): without the close handler a
 * readline question never settles once the input stream ends, hanging the process.
 */
export async function promptConfirm(message: string): Promise<boolean> {
	return new Promise((resolve) => {
		const rl = createInterface({
			input: process.stdin,
			output: process.stdout,
		});
		let settled = false;
		const settle = (result: boolean): void => {
			if (settled) return;
			settled = true;
			resolve(result);
		};
		rl.question(`${message} [y/N] `, (answer) => {
			const normalized = answer.trim().toLowerCase();
			settle(normalized === "y" || normalized === "yes");
			rl.close();
		});
		rl.once("close", () => settle(false));
	});
}

function validateForkFlags(parsed: Args): void {
	if (!parsed.fork) return;

	const conflictingFlags = [
		parsed.session ? "--session" : undefined,
		parsed.continue ? "--continue" : undefined,
		parsed.resume ? "--resume" : undefined,
		parsed.noSession ? "--no-session" : undefined,
	].filter((flag): flag is string => flag !== undefined);

	if (conflictingFlags.length > 0) {
		console.error(chalk.red(`Error: --fork cannot be combined with ${conflictingFlags.join(", ")}`));
		process.exit(1);
	}
}

function validateRebindFlags(parsed: Args): void {
	if (!parsed.rebind) return;

	const conflictingFlags = [
		parsed.session ? "--session" : undefined,
		parsed.fork ? "--fork" : undefined,
		parsed.continue ? "--continue" : undefined,
		parsed.resume ? "--resume" : undefined,
		parsed.noSession ? "--no-session" : undefined,
		parsed.sessionId !== undefined ? "--session-id" : undefined,
	].filter((flag): flag is string => flag !== undefined);

	if (conflictingFlags.length > 0) {
		console.error(chalk.red(`Error: --rebind cannot be combined with ${conflictingFlags.join(", ")}`));
		process.exit(1);
	}
}

function validateSessionIdFlags(parsed: Args): void {
	if (parsed.sessionId === undefined) return;

	const conflictingFlags = [
		parsed.session ? "--session" : undefined,
		parsed.continue ? "--continue" : undefined,
		parsed.resume ? "--resume" : undefined,
	].filter((flag): flag is string => flag !== undefined);

	if (conflictingFlags.length > 0) {
		console.error(chalk.red(`Error: --session-id cannot be combined with ${conflictingFlags.join(", ")}`));
		process.exit(1);
	}

	try {
		assertValidSessionId(parsed.sessionId);
	} catch (error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(chalk.red(`Error: ${message}`));
		process.exit(1);
	}
}

function openSessionOrExit(path: string, sessionDir?: string): SessionManager {
	try {
		return SessionManager.open(path, sessionDir);
	} catch (error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(chalk.red(`Error: ${message}`));
		process.exit(1);
	}
}

function forkSessionOrExit(sourcePath: string, cwd: string, sessionDir?: string, sessionId?: string): SessionManager {
	try {
		return SessionManager.forkFrom(sourcePath, cwd, sessionDir, { id: sessionId });
	} catch (error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(chalk.red(`Error: ${message}`));
		process.exit(1);
	}
}

async function rebindSessionOrExit(sourcePath: string, cwd: string, sessionDir?: string): Promise<SessionManager> {
	try {
		const reboundPath = await rebindSessionFile(sourcePath, cwd, sessionDir);
		console.log(chalk.dim(`Session moved to ${cwd}`));
		return SessionManager.open(reboundPath, sessionDir);
	} catch (error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(chalk.red(`Error: ${message}`));
		process.exit(1);
	}
}

async function sessionCwdOrUndefined(sessionFile: string): Promise<string | undefined> {
	try {
		return await readSessionCwd(sessionFile);
	} catch {
		return undefined;
	}
}

export async function createSessionManager(
	parsed: Args,
	cwd: string,
	sessionDir: string | undefined,
	settingsManager: SettingsManager,
	appMode: AppMode,
): Promise<SessionManager> {
	if (parsed.spawnedBy && (parsed.session || parsed.resume || parsed.continue || parsed.fork || parsed.rebind)) {
		console.error(chalk.yellow("Warning: --spawned-by is ignored when resuming or forking a session."));
	}
	if (parsed.noSession || parsed.help || parsed.listModels !== undefined || parsed.listTips) {
		return SessionManager.inMemory(cwd, { id: parsed.sessionId, spawnedBy: parsed.spawnedBy });
	}

	if (parsed.fork) {
		if (parsed.sessionId) {
			const existingTarget = await findLocalSessionByExactId(parsed.sessionId, cwd, sessionDir);
			if (existingTarget) {
				console.error(chalk.red(`Session already exists with id '${parsed.sessionId}'`));
				process.exit(1);
			}
		}

		const resolved = await resolveSessionPath(parsed.fork, cwd, sessionDir);

		switch (resolved.type) {
			case "path":
			case "local":
			case "global":
				return forkSessionOrExit(resolved.path, cwd, sessionDir, parsed.sessionId);

			case "not_found":
				console.error(chalk.red(`No session found matching '${resolved.arg}'`));
				process.exit(1);
		}
	}

	if (parsed.rebind) {
		const resolved = await resolveSessionPath(parsed.rebind, cwd, sessionDir);
		if (resolved.type === "not_found") {
			console.error(chalk.red(`No session found matching '${resolved.arg}'`));
			process.exit(1);
		}
		const sessionCwd = resolved.type === "global" ? resolved.cwd : await sessionCwdOrUndefined(resolved.path);
		if (resolved.type === "local" || sessionCwd === undefined || resolvePath(sessionCwd) === resolvePath(cwd)) {
			return openSessionOrExit(resolved.path, sessionDir);
		}
		if ((await classifySessionRepository(resolved.path, sessionCwd, cwd)) === "different") {
			console.error(
				chalk.red(
					`Refusing to rebind: ${cwd} is a different git repository than ${sessionCwd}. Use --fork '${parsed.rebind}' to copy the session into this directory instead.`,
				),
			);
			process.exit(1);
		}
		return rebindSessionOrExit(resolved.path, cwd, sessionDir);
	}

	if (parsed.session) {
		const resolved = await resolveSessionPath(parsed.session, cwd, sessionDir);

		switch (resolved.type) {
			case "path":
			case "local":
				return openSessionOrExit(resolved.path, sessionDir);

			case "global": {
				// Recorded under a folder the OmO desktop moved here: this folder's own session (senpi#2990).
				if (resolved.cwd !== "" && resolvePath(resolveMovedPath(resolved.cwd)) === resolvePath(cwd))
					return openSessionOrExit(resolved.path, sessionDir);
				// The confirmation blocks on readline, which only an interactive session can
				// answer. Print, JSON, and RPC runs reach here with a TTY attached
				// too (`-p` from a terminal), where the question hangs the process or resolves
				// as "no" on stdin EOF, so they get the exact commands and a non-zero exit.
				const action = await chooseCrossProjectAction({
					sessionArg: parsed.session,
					sessionCwd: resolved.cwd,
					cwd,
					match: await classifySessionRepository(resolved.path, resolved.cwd, cwd),
					interactive: appMode === "interactive",
					confirm: promptConfirm,
					out: (line) => console.log(line),
					err: (line) => console.error(line),
				});
				if (action === "rebind") return rebindSessionOrExit(resolved.path, cwd, sessionDir);
				if (action === "fork") return forkSessionOrExit(resolved.path, cwd, sessionDir);
				if (action === "abort") console.log(chalk.dim("Aborted."));
				return process.exit(action === "abort" ? 0 : 1);
			}

			case "not_found":
				console.error(chalk.red(`No session found matching '${resolved.arg}'`));
				process.exit(1);
		}
	}

	if (parsed.resume) {
		try {
			const { selectSession } = await import("./cli/session-picker.ts");
			const movedOptions = sessionDir === undefined ? {} : { sessionDir };
			const selectedPath = await selectSession(
				(onProgress) => withMovedSessions(SessionManager.list(cwd, sessionDir, onProgress), cwd, movedOptions),
				async (onProgress) => markMovedSessions(await SessionManager.listAll(sessionDir, onProgress), cwd),
				settingsManager,
			);
			if (!selectedPath) {
				console.log(chalk.dim("No session selected"));
				process.exit(0);
			}
			const target = await resolveResumeTarget({
				sessionPath: selectedPath,
				cwd,
				...movedOptions,
				confirm: (selectedCwd) => {
					console.log(chalk.yellow(`Session found in different project: ${selectedCwd}`));
					return confirmSameRepositoryRebind({
						sessionArg: selectedPath,
						cwd,
						confirm: promptConfirm,
						out: (line) => console.log(line),
					});
				},
			}).catch((error: unknown) => {
				console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
				return process.exit(1);
			});
			if (target.rebound) console.log(chalk.dim(`Session moved to ${cwd}`));
			return SessionManager.open(target.path, sessionDir);
		} finally {
			stopThemeWatcher();
		}
	}

	if (parsed.continue) {
		// A shared session dir matches sessions the OmO desktop moved here in continueRecent. In the default per-folder
		// layout they sit in the old folder's dir: continue the newest of those and the folder's own, in place (senpi#2990).
		const movedHere = sessionDir === undefined ? await movedHereSessionToContinue(cwd) : undefined;
		if (movedHere !== undefined) return SessionManager.open(movedHere, sessionDir);
		const recent = SessionManager.continueRecent(cwd, sessionDir);
		const recentFile = recent.getSessionFile();
		if (recentFile !== undefined && existsSync(recentFile)) return recent;
		const movedChoice = await movedSessionToContinue({
			cwd,
			...(sessionDir === undefined ? {} : { sessionDir }),
			interactive: appMode === "interactive",
			confirm: promptConfirm,
			out: (line) => console.log(line),
			err: (line) => console.error(line),
		});
		return movedChoice === undefined ? recent : rebindSessionOrExit(movedChoice, cwd, sessionDir);
	}

	if (parsed.sessionId) {
		const existingSession = await findLocalSessionByExactId(parsed.sessionId, cwd, sessionDir);
		if (existingSession) {
			if (parsed.spawnedBy)
				console.error(chalk.yellow("Warning: --spawned-by is ignored when resuming an existing session."));
			return SessionManager.open(existingSession.path, sessionDir);
		}
		console.error(
			chalk.yellow(
				`Warning: No project session found with id '${parsed.sessionId}'; creating a new session with that id.`,
			),
		);
	}

	return SessionManager.create(cwd, sessionDir, { id: parsed.sessionId, spawnedBy: parsed.spawnedBy });
}

function buildSessionOptions(
	parsed: Args,
	scopedModels: ScopedModel[],
	hasExistingSession: boolean,
	modelRuntime: ModelRuntime,
	settingsManager: SettingsManager,
): {
	options: CreateAgentSessionOptions;
	cliThinkingFromModel: boolean;
	diagnostics: AgentSessionRuntimeDiagnostic[];
} {
	const options: CreateAgentSessionOptions = {};
	const diagnostics: AgentSessionRuntimeDiagnostic[] = [];
	let cliThinkingFromModel = false;

	// Model from CLI
	// - supports --provider <name> --model <pattern>
	// - supports --model <provider>/<pattern>
	if (parsed.provider && !parsed.model) {
		diagnostics.push({
			type: "error",
			message: `--provider requires --model (for example: --provider ${parsed.provider} --model <pattern>)`,
		});
	}
	if (parsed.model) {
		const resolved = resolveCliModel({
			cliProvider: parsed.provider,
			cliModel: parsed.model,
			cliThinking: parsed.thinking,
			modelRuntime,
		});
		if (resolved.warning) {
			diagnostics.push({ type: "warning", message: resolved.warning });
		}
		if (resolved.error) {
			diagnostics.push({ type: "error", message: resolved.error, code: "model_unresolved" });
		}
		if (resolved.model) {
			options.model = resolved.model;
			options.serviceTier = resolved.serviceTier;
			options.initialModelProvenance = "cli";
			// Allow "--model <pattern>:<thinking>" as a shorthand.
			// Explicit --thinking still takes precedence (applied later).
			if (!parsed.thinking && resolved.thinkingLevel) {
				options.thinkingLevel = resolved.thinkingLevel;
				options.thinkingSelection = resolved.thinkingSelection;
				cliThinkingFromModel = true;
			}
		}
	}

	if (!options.model && scopedModels.length > 0 && !hasExistingSession) {
		// Check if saved default is in scoped models - use it if so, otherwise first scoped model
		const savedProvider = settingsManager.getDefaultProvider();
		const savedModelId = settingsManager.getDefaultModel();
		const savedModel = savedProvider && savedModelId ? modelRuntime.getModel(savedProvider, savedModelId) : undefined;
		const savedInScope = savedModel ? scopedModels.find((sm) => modelsAreEqual(sm.model, savedModel)) : undefined;

		if (savedInScope) {
			options.model = savedInScope.model;
			options.initialModelProvenance = "scoped";
			// Use thinking level from scoped model config if explicitly set
			if (!parsed.thinking && savedInScope.thinkingLevel) {
				options.thinkingLevel = savedInScope.thinkingLevel;
				options.thinkingSelection = savedInScope.thinkingSelection;
			}
		} else {
			options.model = scopedModels[0].model;
			options.initialModelProvenance = "scoped";
			// Use thinking level from first scoped model if explicitly set
			if (!parsed.thinking && scopedModels[0].thinkingLevel) {
				options.thinkingLevel = scopedModels[0].thinkingLevel;
				options.thinkingSelection = scopedModels[0].thinkingSelection;
			}
		}
	}

	// Thinking level from CLI (takes precedence over scoped model thinking levels set above)
	if (parsed.thinking) {
		options.thinkingLevel = parsed.thinking;
		options.thinkingSelection = { level: parsed.thinking, source: "explicit" };
	}

	// Scoped models for Ctrl+P cycling
	// Keep thinking level undefined when not explicitly set in the model pattern.
	// Undefined means "inherit current session thinking level" during cycling.
	if (scopedModels.length > 0) {
		options.scopedModels = scopedModels.map((sm) => ({
			model: sm.model,
			thinkingLevel: sm.thinkingLevel,
			thinkingSelection: sm.thinkingSelection,
			serviceTier: sm.serviceTier,
		}));
	}

	// API key from CLI - set as a non-persistent runtime override
	// (handled by caller before createAgentSession)

	// Tools
	if (parsed.noTools) {
		options.noTools = "all";
	} else if (parsed.noBuiltinTools) {
		options.noTools = "builtin";
	}
	if (parsed.tools) {
		options.tools = [...parsed.tools];
	}
	if (parsed.excludeTools) {
		options.excludeTools = [...parsed.excludeTools];
	}

	return { options, cliThinkingFromModel, diagnostics };
}

function resolveCliPaths(cwd: string, paths: string[] | undefined): string[] | undefined {
	return paths?.map((value) => (isLocalPath(value) ? resolvePath(value, cwd) : value));
}

async function promptForMissingSessionCwd(
	issue: SessionCwdIssue,
	settingsManager: SettingsManager,
): Promise<string | undefined> {
	return showStartupSelector(settingsManager, formatMissingSessionCwdPrompt(issue), [
		{ label: "Continue", value: issue.fallbackCwd },
		{ label: "Cancel", value: undefined },
	]);
}

export interface MainOptions {
	extensionFactories?: InlineExtension[];
}

/**
 * Supply grok-night as a non-persistent fallback until a user explicitly chooses
 * a theme. Existing settings are always returned first.
 */
export function applyGrokNeoThemeFallback(settingsManager: SettingsManager): void {
	if (settingsManager.getThemeSetting() !== undefined) return;

	const getThemeSetting = settingsManager.getThemeSetting.bind(settingsManager);
	const setTheme = settingsManager.setTheme.bind(settingsManager);
	let fallbackActive = true;

	settingsManager.getThemeSetting = () => getThemeSetting() ?? (fallbackActive ? "grok-night" : undefined);
	settingsManager.setTheme = (theme) => {
		fallbackActive = false;
		setTheme(theme);
	};
}

export interface CliRuntimeConfiguration {
	parsed: Args;
	cwd: string;
	agentDir: string;
	appMode: AppMode;
	/** Resolved `--tool-runtime` (flag, then env); absent means `in-process`. A worker isolate never re-reads env. */
	toolRuntime?: ToolRuntimeKind;
}

/** Fixed launch data is cloneable; UI callbacks and extension factories stay in their isolate. */
export function createCliRuntimeFactory(
	configuration: CliRuntimeConfiguration,
	local: {
		extensionFactories?: InlineExtension[];
		startupSettingsManager?: SettingsManager;
		startupLoadingIndicator?: ReturnType<typeof createStartupLoadingIndicator>;
		/**
		 * One model runtime for every session this factory creates. A shared host's
		 * sessions all live in one agent dir, so they would each build an identical
		 * runtime - ~100 ms of loop CPU per open that, concurrent, every open pays
		 * N times over (senpi#1844). Provider registration is keyed by id and
		 * merges, so replaying each session's extension providers into one runtime
		 * is idempotent.
		 */
		modelRuntime?: ModelRuntime;
	} = {},
): PreparableRuntimeFactory {
	const { parsed, cwd, agentDir, appMode, toolRuntime } = configuration;
	const extensionFactories = local.extensionFactories ?? builtInExtensions;
	const startupSettingsManager = local.startupSettingsManager ?? SettingsManager.create(cwd, agentDir);
	const startupLoadingIndicator =
		local.startupLoadingIndicator ??
		createStartupLoadingIndicator({
			writer: () => {},
			isTTY: false,
			label: `Loading ${APP_NAME}`,
		});
	const trustStore = new ProjectTrustStore(agentDir);
	const projectTrustByCwd = new Map<string, boolean>();
	const trustPromptMode: AppMode =
		parsed.help || parsed.listModels !== undefined || parsed.listTips ? "print" : appMode;
	const resolvedExtensionPaths = resolveCliPaths(cwd, parsed.extensions);
	const resolvedSkillPaths = resolveCliPaths(cwd, parsed.skills);
	const resolvedPromptTemplatePaths = resolveCliPaths(cwd, parsed.promptTemplates);
	const resolvedThemePaths = resolveCliPaths(cwd, parsed.themes);
	// The cwd-bound services one session needs, built alone: the runtime factory below builds them
	// before its session, and a multi-session host's `warm` builds and drops them (senpi#2314).
	const createServices = async ({
		cwd,
		agentDir,
		projectTrustContext,
		launchProfile,
		mcpRegistry,
		isInitialRuntime,
	}: Omit<Parameters<CreateAgentSessionRuntimeFactory>[0], "sessionManager" | "sessionStartEvent"> & {
		isInitialRuntime: boolean;
	}) => {
		const projectTrustDiagnostics: AgentSessionRuntimeDiagnostic[] = [];
		const cachedProjectTrust = projectTrustByCwd.get(cwd);
		const hasTrustRequiringResources = hasTrustRequiringProjectResources(cwd);
		// A full-access session trusts its project without asking, for that session only: nothing is
		// cached here or saved to the trust store, and a saved "do not trust" still wins (#2465).
		const fullAccessTrust =
			presetTrustsProject(
				sessionExtensionFlagValues(parsed.unknownFlags, launchProfile).get("permission-preset"),
				(startupSettingsManager.getGlobalSettings() as { readonly permissionPreset?: unknown }).permissionPreset,
			) && trustStore.get(cwd) !== false;
		const shouldResolveProjectTrust =
			parsed.projectTrustOverride === undefined &&
			cachedProjectTrust === undefined &&
			!fullAccessTrust &&
			hasTrustRequiringResources;
		const projectTrusted = shouldResolveProjectTrust
			? false
			: (cachedProjectTrust ??
				parsed.projectTrustOverride ??
				(fullAccessTrust || !hasTrustRequiringResources || trustStore.get(cwd) === true));
		// Trusted only because of Full access (resources need trust and nothing else granted it): leaving
		// Full access withdraws it (#3420 review T5).
		const trustFromFullAccess =
			fullAccessTrust &&
			hasTrustRequiringResources &&
			cachedProjectTrust === undefined &&
			parsed.projectTrustOverride === undefined &&
			trustStore.get(cwd) !== true;
		const runtimeSettingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted, trustFromFullAccess });
		// The opener's per-session fallback policy is an in-memory override: never saved, never shared.
		if (launchProfile?.retryFallback) applyRetryFallbackProfile(runtimeSettingsManager, launchProfile.retryFallback);
		const services = await createAgentSessionServices({
			cwd,
			agentDir,
			settingsManager: runtimeSettingsManager,
			...(local.modelRuntime === undefined ? {} : { modelRuntime: local.modelRuntime }),
			mcpRegistry,
			modelRuntimeSignal: AbortSignal.timeout(15_000),
			extensionFlagValues: sessionExtensionFlagValues(parsed.unknownFlags, launchProfile),
			resourceLoaderReloadOptions: shouldResolveProjectTrust
				? {
						resolveProjectTrust: async ({ extensionsResult }) => {
							const trusted = await resolveProjectTrusted({
								cwd,
								trustStore,
								trustOverride: parsed.projectTrustOverride,
								defaultProjectTrust: startupSettingsManager.getDefaultProjectTrust(),
								extensionsResult,
								projectTrustContext:
									projectTrustContext ??
									pauseIndicatorDuringPrompts(
										createProjectTrustContext({
											cwd,
											mode: isInitialRuntime ? trustPromptMode : appMode,
											settingsManager: startupSettingsManager,
											hasUI: isInitialRuntime && trustPromptMode === "interactive",
										}),
										startupLoadingIndicator,
									),
								onExtensionError: (message) => projectTrustDiagnostics.push({ type: "warning", message }),
							});
							projectTrustByCwd.set(cwd, trusted);
							return trusted;
						},
					}
				: undefined,
			resourceLoaderOptions: {
				// Per-session identity reaches the extensions this session loads and stops
				// there: it is deliberately NOT merged into `parsed`, so it can never move
				// a model, an auth decision or a CLI flag.
				sessionKind: launchProfile?.sessionKind,
				sessionContext: launchProfile?.sessionContext,
				additionalExtensionPaths: resolvedExtensionPaths,
				additionalSkillPaths: resolvedSkillPaths,
				additionalPromptTemplatePaths: resolvedPromptTemplatePaths,
				additionalThemePaths: resolvedThemePaths,
				noExtensions: parsed.noExtensions,
				noSkills: parsed.noSkills,
				noPromptTemplates: parsed.noPromptTemplates,
				noThemes: parsed.noThemes,
				noContextFiles: parsed.noContextFiles,
				systemPrompt: parsed.systemPrompt,
				appendSystemPrompt: parsed.appendSystemPrompt,
				extensionFactories,
			},
		});
		return { services, projectTrustDiagnostics };
	};
	const createRuntime: CreateAgentSessionRuntimeFactory = async ({
		cwd,
		agentDir,
		sessionManager,
		sessionStartEvent,
		projectTrustContext,
		launchProfile,
		mcpRegistry,
	}) => {
		const isInitialRuntime = sessionStartEvent === undefined;
		const markSwitch = (label: string): void => {
			if (sessionStartEvent?.reason === "resume") time(label, "switch");
		};
		const { services, projectTrustDiagnostics } = await createServices({
			cwd,
			agentDir,
			...(projectTrustContext !== undefined ? { projectTrustContext } : {}),
			...(launchProfile !== undefined ? { launchProfile } : {}),
			...(mcpRegistry !== undefined ? { mcpRegistry } : {}),
			isInitialRuntime,
		});
		markSwitch("services");
		const { settingsManager, modelRuntime, resourceLoader } = services;
		const diagnostics: AgentSessionRuntimeDiagnostic[] = [
			...projectTrustDiagnostics,
			...services.diagnostics,
			...collectSettingsDiagnosticsWithContext(settingsManager, "runtime creation"),
			...collectExtensionLoadDiagnostics(resourceLoader.getExtensions().errors),
			...(resourceLoader.getExtensions().warnings ?? []).map(({ path, warning }) => ({
				type: "warning" as const,
				message: `Extension package "${path}": ${warning}`,
			})),
		];

		const modelPatterns = getModelNarrowingPatterns({
			cliPatterns: parsed.models,
			legacyEnabledPatterns: settingsManager.getEnabledModels(),
		});
		const scopedModels =
			modelPatterns && modelPatterns.length > 0
				? await resolveModelScope(modelPatterns, modelRuntime, { signal: AbortSignal.timeout(15_000) })
				: [];
		// Multi-session opens carry their per-session startup choices here rather
		// than through process argv. This deliberately feeds the same resolver as
		// --provider/--model/--thinking, preserving classic flag semantics.
		const runtimeParsed: Args =
			launchProfile === undefined
				? parsed
				: {
						...parsed,
						...(launchProfile.creationModel === undefined
							? {}
							: {
									provider: launchProfile.creationModel.provider,
									model: launchProfile.creationModel.modelId,
								}),
						...(launchProfile.initialThinkingLevel === undefined
							? {}
							: { thinking: launchProfile.initialThinkingLevel as Args["thinking"] }),
					};
		const {
			options: sessionOptions,
			cliThinkingFromModel,
			diagnostics: sessionOptionDiagnostics,
		} = buildSessionOptions(
			runtimeParsed,
			scopedModels,
			sessionManager.hasContextMessages(),
			modelRuntime,
			settingsManager,
		);
		diagnostics.push(...sessionOptionDiagnostics);

		if (parsed.apiKey) {
			if (!sessionOptions.model) {
				diagnostics.push({
					type: "error",
					message: "--api-key requires a model to be specified via --model, --provider/--model, or --models",
				});
			} else {
				await modelRuntime.setRuntimeApiKey(sessionOptions.model.provider, parsed.apiKey);
			}
		}

		if (isInitialRuntime) {
			startupLoadingIndicator.setPhase("opening session");
		}
		markSwitch("sessionOptions");
		const created = await createAgentSessionFromServices({
			services,
			sessionManager,
			sessionStartEvent,
			model: sessionOptions.model,
			initialModelProvenance: sessionOptions.initialModelProvenance,
			thinkingLevel: sessionOptions.thinkingLevel,
			thinkingSelection: sessionOptions.thinkingSelection,
			serviceTier: sessionOptions.serviceTier,
			scopedModels: sessionOptions.scopedModels,
			tools: sessionOptions.tools,
			excludeTools: sessionOptions.excludeTools,
			noTools: sessionOptions.noTools,
			customTools: sessionOptions.customTools,
			autoTitleSessions: resolveAutoTitleSessions(
				appMode,
				parsed,
				sessionManager.hasContextMessages(),
				parseClientCapabilities(envValue("RPC_CLIENT_CAPABILITIES")),
				launchProfile?.autoTitle,
			),
			promptSurface: launchProfile?.promptSurface,
			browserEngine: launchProfile?.browserEngine,
			...(toolRuntime !== undefined ? { toolRuntime } : {}),
		});
		markSwitch("createSession");
		const cliThinkingOverride = runtimeParsed.thinking !== undefined || cliThinkingFromModel;
		if (created.session.model && cliThinkingOverride) {
			// senpi#2395: re-apply the level the CLI asked for, so a clamp keeps its requested level and reason.
			const selection = created.session.thinkingSelection as ClampedThinkingSelection | undefined;
			created.session.setThinkingLevel(selection?.requested ?? created.session.thinkingLevel);
		}

		return {
			...created,
			services,
			diagnostics,
		};
	};
	// A host open creates its session with no start event, so a warm prepares exactly that open.
	return Object.assign(createRuntime, {
		prepare: async (options: PrepareRuntimeOptions): Promise<void> => {
			await createServices({ ...options, isInitialRuntime: true });
		},
	});
}

export async function main(args: string[], options?: MainOptions) {
	resetTimings();
	// The pre-main phase - runtime boot, cli.js, and this module's static import graph - is already
	// over when the first statement runs, so it is read from the process clock rather than measured.
	recordTiming("processStart->main", Math.round(process.uptime() * 1000));
	const extensionFactories = [...builtInExtensions, ...(options?.extensionFactories ?? [])];
	const offlineMode =
		args.includes("--print-prompt-sizes") || args.includes("--offline") || isTruthyEnvFlag(envValue("OFFLINE"));
	if (offlineMode) {
		process.env.PI_OFFLINE = "1";
		process.env.PI_SKIP_VERSION_CHECK = "1";
	}

	if (await runAuthCommand(args)) {
		return;
	}

	if (isModelsDiscoverCommand(args)) {
		process.exitCode = await runModelsDiscoverCommand(args.slice(2));
		return;
	}

	// Internal launch surface used by bundled/rebranded runtimes. It is deliberately
	// not accepted by parseArgs, so existing CLI modes remain unchanged. The route and
	// the RPC host graph behind it live in ./modes/rpc/supervisor-route.ts.
	if (await dispatchInternalSupervisor(args)) {
		return;
	}

	if (process.platform === "win32") {
		cleanupWindowsSelfUpdateQuarantine(getInstallPackageDir());
	}

	const cwd = process.cwd();
	const agentDir = getAgentDir();
	const fromSourceWarning = getFromSourceRealConfigWarning(agentDir);
	if (fromSourceWarning) {
		console.error(chalk.yellow(fromSourceWarning));
	}
	const bootstrapSettingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
	applyHttpProxySettings(bootstrapSettingsManager.getGlobalSettings().httpProxy);
	configureHttpDispatcher();

	if (await dispatchPackageCommand(args, { extensionFactories })) {
		const exitCode = process.exitCode ?? 0;
		if (process.platform === "win32" && exitCode === 0 && args[0] === "update") {
			// We normally prefer process.exit(0) for package commands so bad extensions cannot keep
			// one-shot commands alive. On Windows, Node can assert after fetch() if process.exit(0)
			// runs during teardown; let successful `pi update` drain naturally instead.
			// https://github.com/nodejs/node/issues/56645
			return;
		}
		await exitAfterOutput("", exitCode);
		return;
	}

	if (await dispatchConfigCommand(args, { extensionFactories })) {
		return;
	}

	// The shared-daemon command: one JSON line on stdout and an exit code that classifies it, so it
	// exits here rather than falling through into argument parsing and the interactive path.
	const hostExitCode = await dispatchHostCommand(args);
	if (hostExitCode !== undefined) {
		await exitAfterOutput("", hostExitCode);
	}

	// Durable scheduled prompts: fired out of process, so a job scheduled by an exited --print run still runs.
	const scheduleExitCode = await dispatchScheduleCommand(args);
	if (scheduleExitCode !== undefined) {
		await exitAfterOutput("", scheduleExitCode);
	}

	const parsed = parseArgs(args);
	if (parsed.diagnostics.length > 0) {
		for (const d of parsed.diagnostics) {
			const color = d.type === "error" ? chalk.red : chalk.yellow;
			console.error(color(`${d.type === "error" ? "Error" : "Warning"}: ${d.message}`));
		}
		if (parsed.diagnostics.some((d) => d.type === "error")) {
			process.exit(1);
		}
	}
	const toolRuntimeResolution = resolveToolRuntime(parsed);
	// --version and --help never run a tool, so a bad tool-runtime env value must not block them.
	if (!toolRuntimeResolution.ok && !parsed.version && !parsed.help) {
		console.error(chalk.red(`Error: ${toolRuntimeResolution.message}`));
		process.exit(1);
	}
	const toolRuntime = toolRuntimeResolution.ok ? toolRuntimeResolution.value : "in-process";
	time("parseArgs");

	if (parsed.version) {
		await printThenExit(() => console.log(DISPLAY_VERSION), 0);
	}

	if (parsed.export) {
		let result: string;
		try {
			const outputPath = parsed.messages.length > 0 ? parsed.messages[0] : undefined;
			result = await exportFromFile(parsed.export, outputPath);
		} catch (error: unknown) {
			const message = error instanceof Error ? error.message : "Failed to export session";
			console.error(chalk.red(`Error: ${message}`));
			process.exit(1);
		}
		await printThenExit(() => console.log(`Exported to: ${result}`), 0);
	}

	let appMode: AppMode = parsed.printPromptSizes
		? "print"
		: resolveAppMode(parsed, process.stdin.isTTY, process.stdout.isTTY);
	const shouldTakeOverStdout =
		appMode !== "interactive" && (!isPlainRuntimeMetadataCommand(parsed) || (parsed.help && parsed.mode === "json"));
	if (shouldTakeOverStdout) {
		takeOverStdout();
	}
	if (parsed.mode === "json") {
		const log = console.log.bind(console);
		console.log = (...args: unknown[]) => console.error(...args);
		process.once("exit", () => {
			console.log = log;
		});
	}

	if (parsed.mode === "rpc" && parsed.fileArgs.length > 0) {
		console.error(chalk.red("Error: @file arguments are not supported in RPC mode"));
		process.exit(1);
	}

	validateForkFlags(parsed);
	validateRebindFlags(parsed);
	validateSessionIdFlags(parsed);

	// Run migrations (pass cwd for project-local migrations)
	const { migratedAuthProviders: migratedProviders, deprecationWarnings } = runMigrations(cwd);
	time("runMigrations");

	const startupSettingsManager = SettingsManager.create(cwd, agentDir);
	reportDiagnostics(collectSettingsDiagnosticsWithContext(startupSettingsManager, "startup session lookup"));
	const resolvedExtensionPaths = resolveCliPaths(cwd, parsed.extensions);
	const resolvedSkillPaths = resolveCliPaths(cwd, parsed.skills);
	const resolvedPromptTemplatePaths = resolveCliPaths(cwd, parsed.promptTemplates);
	const resolvedThemePaths = resolveCliPaths(cwd, parsed.themes);

	// Help is answered from the flags alone, so it stops here instead of continuing into the model
	// runtime, the session manager and the rest of the resource load. The flags are cached for the
	// next run, which `cli.ts` then answers before this module is even imported.
	if (isPlainHelpRequest(parsed)) {
		const projectTrusted = resolveHelpProjectTrust(parsed, cwd, agentDir);
		const scope = helpFlagsScope(parsed, cwd, agentDir, projectTrusted);
		const { flags, extensionPaths } = await resolveHelpExtensionFlags({
			cwd,
			agentDir,
			settingsManager: SettingsManager.create(cwd, agentDir, { projectTrusted }),
			additionalExtensionPaths: resolvedExtensionPaths ?? [],
			noExtensions: parsed.noExtensions === true,
			...(extensionFactories ? { extensionFactories } : {}),
		});
		writeHelpFlagsCache({ scope, flags, extensionPaths });
		await printThenExit(() => {
			printHelp(flags);
			printTimings();
		}, 0);
	}

	if (parsed.listTips) {
		const { listTips } = await import("./cli/list-tips.ts");
		await printThenExit(listTips, 0);
	}

	if (parsed.listModels !== undefined) {
		const services = await createAgentSessionServices({
			cwd,
			agentDir,
			settingsManager: startupSettingsManager,
			extensionFlagValues: parsed.unknownFlags,
			resourceLoaderOptions: {
				additionalExtensionPaths: resolvedExtensionPaths,
				additionalSkillPaths: resolvedSkillPaths,
				additionalPromptTemplatePaths: resolvedPromptTemplatePaths,
				additionalThemePaths: resolvedThemePaths,
				noExtensions: parsed.noExtensions,
				noSkills: true,
				noPromptTemplates: true,
				noThemes: true,
				noContextFiles: true,
				extensionFactories,
			},
		});
		reportDiagnostics([
			...services.diagnostics,
			...collectSettingsDiagnosticsWithContext(services.settingsManager, "model listing"),
			...collectAuthDiagnostics(services.authStorage, "model listing", { persistSeen: true }),
		]);
		const searchPattern = typeof parsed.listModels === "string" ? parsed.listModels : undefined;
		await printThenExit(() => listModels(services.modelRuntime, searchPattern), 0);
	}

	// Experimental first-time setup: theme choice and analytics opt-in.
	// Runs before any runtime services are created so the chosen settings apply everywhere.
	if (
		appMode === "interactive" &&
		!parsed.help &&
		parsed.listModels === undefined &&
		!parsed.listTips &&
		shouldRunFirstTimeSetup()
	) {
		await showFirstTimeSetup(startupSettingsManager);
		time("firstTimeSetup");
	}

	if (appMode === "interactive" && parsed.useTheme !== undefined) {
		startupSettingsManager.applyOverrides({ theme: parsed.useTheme });
	}

	// Installs nothing unless SENPI_MEMORY_REPORT=1; then SIGUSR2 writes a memory report for every live session.
	installMemoryReportSignal();

	if (appMode === "rpc" && parsed.multiSession) {
		if (options?.extensionFactories?.length)
			throw new Error("Shared RPC workers require file-backed extensions; inline factories cannot cross isolates");
		const { presenterBootstrapFd, mcpPresenterEnforcement, ...sessionArgs } = parsed;
		const runtimeConfiguration = { parsed: sessionArgs, cwd, agentDir, appMode, toolRuntime };
		// Socket hosts (the machine-wide daemon) run every session IN this process:
		// createHostCore selects the worker registry only when a workerConfiguration
		// is passed, so withholding it is what selects the uncapped in-process registry.
		const sessionRuntime = resolveSessionRuntime(parsed);
		const { runMultiSessionHost } = await import("./modes/rpc/multi-session-host.ts");
		// In-process sessions share the host's model runtime: one agent dir, one
		// catalog. Worker sessions build their own inside the isolate - an object
		// cannot cross that boundary - so the shared one is offered only here.
		const hostModelRuntime =
			sessionRuntime === "worker"
				? undefined
				: await ModelRuntime.create({
						credentials: AuthStorage.create(join(agentDir, "auth.json")),
						authPath: join(agentDir, "auth.json"),
						agentDir,
						modelsPath: join(agentDir, "models.json"),
						signal: AbortSignal.timeout(15_000),
					});
		// The multi-session host below never returns, so the initTheme() call further
		// down main() is unreachable on this path. Extensions load per open_session and
		// read the theme proxy: the worker runtime initializes the theme inside each
		// session worker, but the in-process runtime (the socket-host default) shares
		// this process, so the host must initialize the theme before serving sessions -
		// otherwise theme-touching extensions fail with "Theme not initialized. Call
		// initTheme() first." (senpi#1894).
		initTheme(startupSettingsManager.getTheme(), false);
		if (!offlineMode) {
			startSubscriptionUsagePolling({ agentDir, report: (message) => void process.stderr.write(`${message}\n`) });
		}
		printTimings();
		await runMultiSessionHost({
			presenterBootstrapFd,
			mcpPresenterEnforcement,
			agentDir,
			createRuntime: createCliRuntimeFactory(runtimeConfiguration, {
				...(hostModelRuntime === undefined ? {} : { modelRuntime: hostModelRuntime }),
			}),
			...(sessionRuntime === "worker" ? { workerConfiguration: runtimeConfiguration } : {}),
			cwd,
			creationModel:
				parsed.provider && parsed.model ? { provider: parsed.provider, modelId: parsed.model } : undefined,
			initialThinkingLevel: parsed.thinking,
			listen: parsed.listen,
			toolRuntime,
		});
	}

	// Decide the final runtime cwd before creating cwd-bound runtime services.
	// --session and --resume may select a session from another project, so project-local
	// settings, resources, provider registrations, and models must be resolved only after
	// the target session cwd is known. The startup-cwd settings manager is used only for
	// sessionDir lookup during session selection.
	const envSessionDir = process.env[ENV_SESSION_DIR];
	const sessionDir =
		(parsed.sessionDir ? normalizePath(parsed.sessionDir) : undefined) ??
		(envSessionDir ? expandTildePath(envSessionDir) : undefined) ??
		startupSettingsManager.getSessionDir();
	let sessionManager = await createSessionManager(parsed, cwd, sessionDir, startupSettingsManager, appMode);
	const missingSessionCwdIssue = getMissingSessionCwdIssue(sessionManager, cwd);
	if (missingSessionCwdIssue) {
		if (appMode === "interactive") {
			const selectedCwd = await promptForMissingSessionCwd(missingSessionCwdIssue, startupSettingsManager);
			if (!selectedCwd) {
				process.exit(0);
			}
			sessionManager = SessionManager.open(missingSessionCwdIssue.sessionFile!, sessionDir, selectedCwd);
		} else {
			console.error(chalk.red(new MissingSessionCwdError(missingSessionCwdIssue).message));
			process.exit(1);
		}
	}
	if (parsed.name !== undefined) {
		const name = normalizeSessionName(parsed.name);
		if (name === undefined) {
			console.error(chalk.red("Error: --name requires a non-empty value"));
			process.exit(1);
		}
		sessionManager.appendSessionInfo(name);
	}
	time("createSessionManager");

	const sessionCwd = sessionManager.getCwd();
	const autoTrustOnReloadCwd =
		parsed.projectTrustOverride === undefined && !hasTrustRequiringProjectResources(sessionCwd)
			? sessionCwd
			: undefined;

	// Immediate feedback while the heavy runtime (extensions, models, trust) is
	// created; without it the terminal stays blank and looks stuck (codex-style
	// UI-first startup). Stopped before any other surface writes to stdout.
	const startupLoadingIndicator = createStartupLoadingIndicator({
		writer: (chunk) => process.stdout.write(chunk),
		isTTY: process.stdout.isTTY === true,
		label: `Loading ${APP_NAME}`,
	});
	if (
		shouldShowStartupLoadingIndicator({
			appMode,
			stdoutIsTTY: process.stdout.isTTY === true,
			helpRequested: parsed.help === true,
		})
	) {
		startupLoadingIndicator.start();
		startupLoadingIndicator.setPhase("extensions & models");
	}

	const createRuntime = createCliRuntimeFactory(
		{ parsed, cwd, agentDir, appMode, toolRuntime },
		{ extensionFactories, startupSettingsManager, startupLoadingIndicator },
	);
	time("createRuntime");
	const runtime = await createAgentSessionRuntime(createRuntime, {
		cwd: sessionManager.getCwd(),
		agentDir,
		sessionManager,
	})
		.catch((error: unknown) => {
			// A model that cannot start is the user's to fix, not a crash: one line and its fix (senpi#3333).
			if (!(error instanceof ModelUsabilityBudgetError)) throw error;
			// Stop the spinner first: exit runs before `.finally`, and its line has no newline.
			startupLoadingIndicator.stop();
			console.error(chalk.red(error.message));
			process.exit(1);
		})
		.finally(() => {
			startupLoadingIndicator.stop();
		});
	time("createAgentSessionRuntime");
	if (parsed.printPromptSizes) {
		await printPromptSizes(runtime);
	}
	await prepareSessionOpening(sessionManager, appMode);
	const { services, session, modelFallbackMessage } = runtime;
	const { settingsManager, modelRuntime, resourceLoader } = services;
	setCapabilityOverrides(settingsManager.getTerminalCapabilityOverrides());
	applyHttpProxySettings(settingsManager.getGlobalSettings().httpProxy);
	configureHttpDispatcher(settingsManager.getHttpIdleTimeoutMs());

	const loadedExtensions = resourceLoader.getExtensions().extensions;
	const extensionFlags = loadedExtensions.flatMap((extension) => Array.from(extension.flags.values()));
	if (parsed.help) {
		await printThenExit(() => printHelp(extensionFlags), 0);
	}
	time("extensionFlags");
	// Every full launch refreshes what `--help` reads, so the fast path stays warm without a help
	// run of its own.
	writeHelpFlagsCache({
		scope: helpFlagsScope(parsed, cwd, agentDir, settingsManager.isProjectTrusted()),
		flags: extensionFlags,
		extensionPaths: loadedExtensions.map((extension) => extension.resolvedPath),
	});
	time("helpFlagsCache");

	// Read piped stdin content (if any) - skip for RPC mode which uses stdin for JSON-RPC
	let stdinContent: string | undefined;
	if (appMode !== "rpc") {
		stdinContent = await readPipedStdin(pipedStdinOptions(parsed, process.stderr));
		if (stdinContent !== undefined && appMode === "interactive") {
			appMode = "print";
		}
	}
	time("readPipedStdin");
	// An RPC process always has a parent that watches its exit; every other mode dies unobserved.
	recordProcessLifetime(agentDir, appMode, { supervised: appMode === "rpc" });
	time("recordProcessLifetime");

	const { initialMessage, initialImages, initialTitlePrompt } = await prepareInitialMessage(
		parsed,
		settingsManager.getImageAutoResize(),
		stdinContent,
	);
	time("prepareInitialMessage");
	if (parsed.grokNeo && appMode === "interactive") {
		applyGrokNeoThemeFallback(settingsManager);
	}
	initTheme(settingsManager.getTheme(), appMode === "interactive");
	time("initTheme");

	// Show deprecation warnings in interactive mode
	if (appMode === "interactive" && deprecationWarnings.length > 0) {
		await showDeprecationWarnings(deprecationWarnings);
	}

	time("resolveModelScope");
	reportDiagnostics(runtime.diagnostics);
	// senpi#2395: print/json/RPC runs report a startup thinking clamp on stderr; the TUI shows its own warning.
	const startupThinkingClamp = runtime.session.startupThinkingClamp;
	if (appMode !== "interactive" && startupThinkingClamp) {
		reportDiagnostics([{ type: "warning", message: formatThinkingClampWarning(startupThinkingClamp) }]);
	}
	if (appMode !== "interactive") {
		reportDiagnostics(
			[...(resourceLoader.getAgentsFiles().diagnostics ?? []), ...resourceLoader.getSkills().diagnostics]
				.filter((diagnostic) => diagnostic.type === "warning" && diagnostic.category === "size-limit")
				.map((diagnostic) => ({
					type: "warning" as const,
					message: diagnostic.path ? `${diagnostic.path}: ${diagnostic.message}` : diagnostic.message,
				})),
		);
		reportDiagnostics(
			collectAuthDiagnostics(services.authStorage, "runtime creation", { persistSeen: appMode !== "rpc" }),
		);
	}
	if (runtime.diagnostics.some((diagnostic) => diagnostic.type === "error")) {
		if (runtime.diagnostics.some((diagnostic) => diagnostic.message.includes("Failed to load extension"))) {
			console.error(chalk.yellow(EXTENSION_LOAD_FAILURE_HINT));
		}
		process.exit(1);
	}
	time("createAgentSession");

	if (appMode !== "interactive" && !session.model) {
		console.error(chalk.red(formatNoModelsAvailableMessage()));
		process.exit(1);
	}

	const startupBenchmark = isTruthyEnvFlag(envValue("STARTUP_BENCHMARK"));
	if (startupBenchmark && appMode !== "interactive") {
		console.error(chalk.red("Error: PI_STARTUP_BENCHMARK only supports interactive mode"));
		process.exit(1);
	}

	// RPC refreshes catalogs here in the background; interactive mode starts its refresh after TUI initialization.
	if (!offlineMode && appMode === "rpc") {
		const controller = new AbortController();
		const timeout = setTimeout(() => controller.abort(), 15_000);
		void modelRuntime
			.refresh({ signal: controller.signal })
			.catch(() => {})
			.finally(() => clearTimeout(timeout));
	}

	// Every mode hosts the eval kernel, and a worker thread that is terminated takes its children's exit
	// watchers with it, so single-session modes arm the same reaper the multi-session host runs (#1962). The
	// TUI owns stderr, so interactive mode reaps silently.
	const stopChildReaper = await startHostChildReaper(
		appMode === "interactive" ? () => {} : (message) => void process.stderr.write(`${message}\n`),
	);

	// Subscription limits are known before the first turn (senpi#3684); one-shot print runs never poll.
	if (!offlineMode && (appMode === "rpc" || appMode === "interactive")) {
		startSubscriptionUsagePolling({
			agentDir,
			// The TUI owns stderr in interactive mode, as with the child reaper below.
			report: appMode === "interactive" ? () => {} : (message) => void process.stderr.write(`${message}\n`),
		});
	}

	if (appMode === "rpc") {
		const { runRpcMode } = await import("./modes/rpc/rpc-mode.ts");
		printTimings();
		await runRpcMode(runtime, toolRuntime);
	} else if (appMode === "interactive") {
		// Keep the TUI graph out of headless RPC children. This is intentionally at the
		// mode seam: interactive startup still loads the same module before first use.
		const { InteractiveMode } = await import("./modes/interactive/interactive-mode.ts");
		const interactiveMode = new InteractiveMode(runtime, {
			mcpPresenterEnforcement: parsed.mcpPresenterEnforcement,
			migratedProviders,
			authNotices: interactiveAuthNotices(services.authStorage),
			legacyPiEditNotice: legacyPiEditStartupNotice(),
			modelFallbackMessage,
			autoTrustOnReloadCwd,
			initialMessage,
			initialImages,
			initialTitlePrompt,
			initialMessages: parsed.messages,
			verbose: parsed.verbose,
			chrome: parsed.grokNeo ? "grok" : undefined,
			tuiMode: parsed.tuiMode,
			initialThemeSetting: parsed.useTheme,
		});
		if (startupBenchmark) {
			await interactiveMode.init();
			time("interactiveMode.init");
			// Give the TUI's stdin handler a brief chance to consume terminal query replies
			// (Kitty keyboard protocol, device attributes, cell size) before restoring the terminal.
			await new Promise((resolve) => setTimeout(resolve, 150));
			interactiveMode.stop();
			stopThemeWatcher();
			printTimings();
			if (process.stdout.writableLength > 0) {
				await new Promise<void>((resolve) => process.stdout.once("drain", resolve));
			}
			if (process.stderr.writableLength > 0) {
				await new Promise<void>((resolve) => process.stderr.once("drain", resolve));
			}
			// Benchmark runs leave the TUI's terminal handles active, so returning here only parks the
			// loop; the measurement is complete, so the process ends with it.
			process.exit(0);
		}

		printTimings();
		await interactiveMode.run();
	} else {
		printTimings();
		const exitCode = await runPrintMode(runtime, {
			mode: toPrintOutputMode(appMode),
			messages: parsed.messages,
			initialMessage,
			initialImages,
		});
		reportDiagnostics(collectAuthDiagnostics(services.authStorage, "print mode", { persistSeen: true }));
		stopChildReaper();
		stopThemeWatcher();
		restoreStdout();
		if (exitCode !== 0) {
			process.exitCode = exitCode;
		}
		return;
	}
}