@oh-my-pi/pi-coding-agent 3.15.0 → 3.20.0

package/src/lib/worktree/operations.ts

@@ -0,0 +1,216 @@
+import { mkdir } from "node:fs/promises";
+import * as path from "node:path";
+import { WORKTREE_BASE } from "./constants";
+import { WorktreeError, WorktreeErrorCode } from "./errors";
+import { getRepoName, getRepoRoot, git } from "./git";
+
+export interface Worktree {
+	path: string;
+	branch: string | null;
+	head: string;
+	isMain: boolean;
+	isDetached: boolean;
+}
+
+type WorktreePartial = Partial<Worktree> & { isDetached?: boolean };
+
+function finalizeWorktree(entry: WorktreePartial, repoRoot: string): Worktree {
+	const wtPath = entry.path?.trim();
+	if (!wtPath) {
+		throw new Error("Invalid worktree entry");
+	}
+	const branch = entry.isDetached ? null : (entry.branch ?? null);
+	const isDetached = entry.isDetached ?? branch === null;
+	return {
+		path: wtPath,
+		branch,
+		head: entry.head ?? "",
+		isMain: path.resolve(wtPath) === path.resolve(repoRoot),
+		isDetached,
+	};
+}
+
+function parseWorktreeList(output: string, repoRoot: string): Worktree[] {
+	const worktrees: Worktree[] = [];
+	let current: WorktreePartial = {};
+
+	for (const line of output.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			if (current.path) {
+				worktrees.push(finalizeWorktree(current, repoRoot));
+			}
+			current = { path: line.slice(9) };
+			continue;
+		}
+
+		if (line.startsWith("HEAD ")) {
+			current.head = line.slice(5);
+			continue;
+		}
+
+		if (line.startsWith("branch ")) {
+			const raw = line.slice(7);
+			current.branch = raw.startsWith("refs/heads/") ? raw.slice("refs/heads/".length) : raw;
+			continue;
+		}
+
+		if (line === "detached") {
+			current.isDetached = true;
+		}
+	}
+
+	if (current.path) {
+		worktrees.push(finalizeWorktree(current, repoRoot));
+	}
+
+	return worktrees;
+}
+
+/**
+ * Create a new worktree.
+ */
+export async function create(branch: string, options?: { base?: string; path?: string }): Promise<Worktree> {
+	const repoRoot = await getRepoRoot();
+	const repoName = await getRepoName();
+	const targetPath = options?.path ?? path.join(WORKTREE_BASE, repoName, branch);
+	const resolvedTarget = path.resolve(targetPath);
+
+	const existing = await list();
+	const conflict = existing.find((wt) => wt.branch === branch || path.resolve(wt.path) === resolvedTarget);
+	if (conflict) {
+		throw new WorktreeError(`Worktree already exists: ${conflict.path}`, WorktreeErrorCode.WORKTREE_EXISTS);
+	}
+
+	await mkdir(path.dirname(resolvedTarget), { recursive: true });
+
+	const branchExists = (await git(["rev-parse", "--verify", `refs/heads/${branch}`], repoRoot)).code === 0;
+
+	const args = branchExists
+		? ["worktree", "add", resolvedTarget, branch]
+		: ["worktree", "add", "-b", branch, resolvedTarget, options?.base ?? "HEAD"];
+
+	const result = await git(args, repoRoot);
+	if (result.code !== 0) {
+		const stderr = result.stderr.trim();
+		if (stderr.includes("already exists") || stderr.includes("already checked out")) {
+			throw new WorktreeError(stderr || "Worktree already exists", WorktreeErrorCode.WORKTREE_EXISTS);
+		}
+		throw new Error(stderr || "Failed to create worktree");
+	}
+
+	const updated = await list();
+	const created = updated.find((wt) => path.resolve(wt.path) === resolvedTarget);
+	if (!created) {
+		throw new Error("Worktree created but not found in list");
+	}
+
+	return created;
+}
+
+/**
+ * List all worktrees for current repository.
+ */
+export async function list(): Promise<Worktree[]> {
+	const repoRoot = await getRepoRoot();
+	const result = await git(["worktree", "list", "--porcelain"], repoRoot);
+	if (result.code !== 0) {
+		throw new Error(result.stderr.trim() || "Failed to list worktrees");
+	}
+	return parseWorktreeList(result.stdout, repoRoot);
+}
+
+/**
+ * Find a worktree by pattern.
+ */
+export async function find(pattern: string): Promise<Worktree> {
+	const worktrees = await list();
+
+	const exactBranch = worktrees.filter((wt) => wt.branch === pattern);
+	if (exactBranch.length === 1) return exactBranch[0];
+	if (exactBranch.length > 1) {
+		throw new WorktreeError(`Ambiguous worktree: ${pattern}`, WorktreeErrorCode.WORKTREE_NOT_FOUND);
+	}
+
+	const exactDir = worktrees.filter((wt) => path.basename(wt.path) === pattern);
+	if (exactDir.length === 1) return exactDir[0];
+	if (exactDir.length > 1) {
+		throw new WorktreeError(`Ambiguous worktree: ${pattern}`, WorktreeErrorCode.WORKTREE_NOT_FOUND);
+	}
+
+	const partialBranch = worktrees.filter((wt) => wt.branch?.includes(pattern));
+	if (partialBranch.length === 1) return partialBranch[0];
+	if (partialBranch.length > 1) {
+		throw new WorktreeError(`Ambiguous worktree: ${pattern}`, WorktreeErrorCode.WORKTREE_NOT_FOUND);
+	}
+
+	const partialPath = worktrees.filter((wt) => wt.path.includes(pattern));
+	if (partialPath.length === 1) return partialPath[0];
+	if (partialPath.length > 1) {
+		throw new WorktreeError(`Ambiguous worktree: ${pattern}`, WorktreeErrorCode.WORKTREE_NOT_FOUND);
+	}
+
+	throw new WorktreeError(`Worktree not found: ${pattern}`, WorktreeErrorCode.WORKTREE_NOT_FOUND);
+}
+
+/**
+ * Remove a worktree.
+ */
+export async function remove(nameOrPath: string, options?: { force?: boolean }): Promise<void> {
+	const wt = await find(nameOrPath);
+	if (wt.isMain) {
+		throw new WorktreeError("Cannot remove main worktree", WorktreeErrorCode.CANNOT_MODIFY_MAIN);
+	}
+
+	const repoRoot = await getRepoRoot();
+	const args = ["worktree", "remove", wt.path];
+	if (options?.force) args.push("--force");
+
+	const result = await git(args, repoRoot);
+	if (result.code !== 0) {
+		throw new Error(result.stderr.trim() || "Failed to remove worktree");
+	}
+}
+
+/**
+ * Remove worktrees for branches that no longer exist.
+ */
+export async function prune(): Promise<number> {
+	const repoRoot = await getRepoRoot();
+	const worktrees = await list();
+	let removed = 0;
+
+	for (const wt of worktrees) {
+		if (wt.isMain || !wt.branch) continue;
+		const existsResult = await git(["rev-parse", "--verify", `refs/heads/${wt.branch}`], repoRoot);
+		if (existsResult.code === 0) continue;
+
+		const result = await git(["worktree", "remove", wt.path], repoRoot);
+		if (result.code !== 0) {
+			throw new Error(result.stderr.trim() || `Failed to remove worktree: ${wt.path}`);
+		}
+		removed += 1;
+	}
+
+	return removed;
+}
+
+/**
+ * Get the worktree containing the given path.
+ * Returns null if path is not in any worktree.
+ */
+export async function which(targetPath?: string): Promise<Worktree | null> {
+	const worktrees = await list();
+	const resolved = path.resolve(targetPath ?? process.cwd());
+
+	let best: Worktree | null = null;
+	for (const wt of worktrees) {
+		const wtPath = path.resolve(wt.path);
+		if (resolved === wtPath || resolved.startsWith(wtPath + path.sep)) {
+			if (!best || wtPath.length > best.path.length) {
+				best = wt;
+			}
+		}
+	}
+
+	return best;
+}

package/src/lib/worktree/session.ts

@@ -0,0 +1,114 @@
+import { mkdir } from "node:fs/promises";
+import * as path from "node:path";
+import { nanoid } from "nanoid";
+import { getRepoRoot, git } from "./git";
+
+export interface WorktreeSession {
+	id: string;
+	branch: string;
+	path: string;
+	scope?: string[];
+	agentId?: string;
+	task?: string;
+	status: SessionStatus;
+	createdAt: number;
+	completedAt?: number;
+}
+
+export type SessionStatus = "creating" | "active" | "completed" | "merging" | "merged" | "failed" | "abandoned";
+
+async function getSessionsFile(): Promise<string> {
+	const repoRoot = await getRepoRoot();
+	const result = await git(["rev-parse", "--git-common-dir"], repoRoot);
+	let gitDir = result.code === 0 ? result.stdout.trim() : "";
+	if (!gitDir) {
+		gitDir = path.join(repoRoot, ".git");
+	}
+	if (!path.isAbsolute(gitDir)) {
+		// Resolve relative git dir from repo root to keep sessions in the common dir.
+		gitDir = path.resolve(repoRoot, gitDir);
+	}
+	await mkdir(gitDir, { recursive: true });
+	return path.join(gitDir, "worktree-sessions.json");
+}
+
+async function loadSessions(): Promise<WorktreeSession[]> {
+	const filePath = await getSessionsFile();
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return [];
+	try {
+		const data = await file.json();
+		if (Array.isArray(data)) {
+			return data as WorktreeSession[];
+		}
+	} catch {
+		return [];
+	}
+	return [];
+}
+
+async function saveSessions(sessions: WorktreeSession[]): Promise<void> {
+	const filePath = await getSessionsFile();
+	await Bun.write(filePath, JSON.stringify(sessions, null, 2));
+}
+
+export async function createSession(params: {
+	branch: string;
+	path: string;
+	scope?: string[];
+	task?: string;
+}): Promise<WorktreeSession> {
+	const sessions = await loadSessions();
+	const session: WorktreeSession = {
+		id: nanoid(10),
+		branch: params.branch,
+		path: params.path,
+		scope: params.scope,
+		task: params.task,
+		status: "creating",
+		createdAt: Date.now(),
+	};
+
+	sessions.push(session);
+	await saveSessions(sessions);
+	return session;
+}
+
+export async function updateSession(id: string, updates: Partial<WorktreeSession>): Promise<void> {
+	const sessions = await loadSessions();
+	const idx = sessions.findIndex((s) => s.id === id);
+	if (idx === -1) return;
+	const current = sessions[idx];
+	sessions[idx] = { ...current, ...updates, id: current.id };
+	await saveSessions(sessions);
+}
+
+export async function getSession(id: string): Promise<WorktreeSession | null> {
+	const sessions = await loadSessions();
+	return sessions.find((s) => s.id === id) ?? null;
+}
+
+export async function listSessions(): Promise<WorktreeSession[]> {
+	return loadSessions();
+}
+
+export async function cleanupSessions(): Promise<number> {
+	const sessions = await loadSessions();
+	let removed = 0;
+
+	const remaining: WorktreeSession[] = [];
+	for (const session of sessions) {
+		const exists = await Bun.file(session.path).exists();
+		if (!exists) {
+			removed += 1;
+			continue;
+		}
+		remaining.push(session);
+	}
+
+	if (removed > 0) {
+		await saveSessions(remaining);
+	}
+
+	return removed;
+}

package/src/lib/worktree/stats.ts

@@ -0,0 +1,67 @@
+import { git } from "./git";
+
+export interface WorktreeStats {
+	additions: number;
+	deletions: number;
+	untracked: number;
+	modified: number;
+	staged: number;
+}
+
+/**
+ * Get diff statistics for a worktree.
+ */
+export async function getStats(worktreePath: string): Promise<WorktreeStats> {
+	const diffResult = await git(["diff", "HEAD", "--shortstat"], worktreePath);
+
+	let additions = 0;
+	let deletions = 0;
+
+	const statsLine = diffResult.stdout.trim();
+	if (statsLine) {
+		const insertMatch = statsLine.match(/(\d+) insertion/);
+		const deleteMatch = statsLine.match(/(\d+) deletion/);
+		if (insertMatch) additions = parseInt(insertMatch[1], 10);
+		if (deleteMatch) deletions = parseInt(deleteMatch[1], 10);
+	}
+
+	const untrackedResult = await git(["ls-files", "--others", "--exclude-standard"], worktreePath);
+	const untracked = untrackedResult.stdout.trim() ? untrackedResult.stdout.trim().split("\n").length : 0;
+
+	const statusResult = await git(["status", "--porcelain"], worktreePath);
+	let modified = 0;
+	let staged = 0;
+
+	for (const line of statusResult.stdout.split("\n")) {
+		if (!line) continue;
+		const index = line[0];
+		const worktree = line[1];
+		if (index !== " " && index !== "?") staged += 1;
+		if (worktree !== " " && worktree !== "?") modified += 1;
+	}
+
+	return { additions, deletions, untracked, modified, staged };
+}
+
+/**
+ * Format stats for display.
+ * Returns "clean" or "+N -M ?U" format.
+ */
+export function formatStats(stats: WorktreeStats): string {
+	if (
+		stats.additions === 0 &&
+		stats.deletions === 0 &&
+		stats.untracked === 0 &&
+		stats.modified === 0 &&
+		stats.staged === 0
+	) {
+		return "clean";
+	}
+
+	const parts: string[] = [];
+	if (stats.additions > 0) parts.push(`+${stats.additions}`);
+	if (stats.deletions > 0) parts.push(`-${stats.deletions}`);
+	if (stats.untracked > 0) parts.push(`?${stats.untracked}`);
+
+	return parts.join(" ") || "clean";
+}

package/src/main.ts

@@ -15,9 +15,8 @@ import { selectSession } from "./cli/session-picker";
 import { parseUpdateArgs, printUpdateHelp, runUpdateCommand } from "./cli/update-cli";
 import { findConfigFile, getModelsPath, VERSION } from "./config";
 import type { AgentSession } from "./core/agent-session";
-import type { LoadedCustomTool } from "./core/custom-tools/index";
 import { exportFromFile } from "./core/export-html/index";
-import type { HookUIContext } from "./core/index";
+import type { ExtensionUIContext } from "./core/index";
 import type { ModelRegistry } from "./core/model-registry";
 import { parseModelPattern, resolveModelScope, type ScopedModel } from "./core/model-resolver";
 import { type CreateAgentSessionOptions, createAgentSession, discoverAuthStorage, discoverModels } from "./core/sdk";
@@ -26,7 +25,7 @@ import { SettingsManager } from "./core/settings-manager";
 import { resolvePromptInput } from "./core/system-prompt";
 import { printTimings, time } from "./core/timings";
 import { allTools } from "./core/tools/index";
-import { runMigrations } from "./migrations";
+import { runMigrations, showDeprecationWarnings } from "./migrations";
 import { InteractiveMode, installTerminalCrashHandlers, runPrintMode, runRpcMode } from "./modes/index";
 import { initTheme, stopThemeWatcher } from "./modes/interactive/theme/theme";
 import { getChangelogPath, getNewEntries, parseChangelog } from "./utils/changelog";
@@ -59,22 +58,13 @@ async function runInteractiveMode(
 	migratedProviders: string[],
 	versionCheckPromise: Promise<string | undefined>,
 	initialMessages: string[],
-	customTools: LoadedCustomTool[],
-	setToolUIContext: (uiContext: HookUIContext, hasUI: boolean) => void,
+	setExtensionUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void,
 	lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined,
 	initialMessage?: string,
 	initialImages?: ImageContent[],
 	fdPath: string | undefined = undefined,
 ): Promise<void> {
-	const mode = new InteractiveMode(
-		session,
-		version,
-		changelogMarkdown,
-		customTools,
-		setToolUIContext,
-		lspServers,
-		fdPath,
-	);
+	const mode = new InteractiveMode(session, version, changelogMarkdown, setExtensionUIContext, lspServers, fdPath);
 
 	await mode.init();
 
@@ -127,7 +117,10 @@ async function runInteractiveMode(
 	}
 }
 
-async function prepareInitialMessage(parsed: Args): Promise<{
+async function prepareInitialMessage(
+	parsed: Args,
+	autoResizeImages: boolean,
+): Promise<{
 	initialMessage?: string;
 	initialImages?: ImageContent[];
 }> {
@@ -135,7 +128,7 @@ async function prepareInitialMessage(parsed: Args): Promise<{
 		return {};
 	}
 
-	const { text, images } = await processFileArguments(parsed.fileArgs);
+	const { text, images } = await processFileArguments(parsed.fileArgs, { autoResizeImages });
 
 	let initialMessage: string;
 	if (parsed.messages.length > 0) {
@@ -215,6 +208,7 @@ async function buildSessionOptions(
 	scopedModels: ScopedModel[],
 	sessionManager: SessionManager | undefined,
 	modelRegistry: ModelRegistry,
+	settingsManager: SettingsManager,
 ): Promise<CreateAgentSessionOptions> {
 	const options: CreateAgentSessionOptions = {};
 
@@ -229,7 +223,7 @@ async function buildSessionOptions(
 
 	// Model from CLI (--model) - uses same fuzzy matching as --models
 	if (parsed.model) {
-		const available = await modelRegistry.getAvailable();
+		const available = modelRegistry.getAvailable();
 		const { model, warning } = parseModelPattern(parsed.model, available);
 		if (warning) {
 			console.warn(chalk.yellow(`Warning: ${warning}`));
@@ -276,16 +270,20 @@ async function buildSessionOptions(
 	// Skills
 	if (parsed.noSkills) {
 		options.skills = [];
+	} else if (parsed.skills && parsed.skills.length > 0) {
+		// Override includeSkills in settingsManager for this session
+		settingsManager.applyOverrides({
+			skills: {
+				...settingsManager.getSkillsSettings(),
+				includeSkills: parsed.skills,
+			},
+		});
 	}
 
-	// Additional hook paths from CLI
-	if (parsed.hooks && parsed.hooks.length > 0) {
-		options.additionalHookPaths = parsed.hooks;
-	}
-
-	// Additional custom tool paths from CLI
-	if (parsed.customTools && parsed.customTools.length > 0) {
-		options.additionalCustomToolPaths = parsed.customTools;
+	// Additional extension paths from CLI
+	const cliExtensionPaths = [...(parsed.extensions ?? []), ...(parsed.hooks ?? [])];
+	if (cliExtensionPaths.length > 0) {
+		options.additionalExtensionPaths = cliExtensionPaths;
 	}
 
 	return options;
@@ -320,12 +318,12 @@ export async function main(args: string[]) {
 		return;
 	}
 
-	// Run migrations
-	const { migratedAuthProviders: migratedProviders } = runMigrations();
+	// Run migrations (pass cwd for project-local migrations)
+	const { migratedAuthProviders: migratedProviders, deprecationWarnings } = await runMigrations(process.cwd());
 
 	// Create AuthStorage and ModelRegistry upfront
-	const authStorage = discoverAuthStorage();
-	const modelRegistry = discoverModels(authStorage);
+	const authStorage = await discoverAuthStorage();
+	const modelRegistry = await discoverModels(authStorage);
 	time("discoverModels");
 
 	const parsed = parseArgs(args);
@@ -366,14 +364,13 @@ export async function main(args: string[]) {
 	}
 
 	const cwd = process.cwd();
-	const { initialMessage, initialImages } = await prepareInitialMessage(parsed);
+	const settingsManager = SettingsManager.create(cwd);
+	time("SettingsManager.create");
+	const { initialMessage, initialImages } = await prepareInitialMessage(parsed, settingsManager.getImageAutoResize());
 	time("prepareInitialMessage");
 	const isInteractive = !parsed.print && parsed.mode === undefined;
 	const mode = parsed.mode || "text";
 
-	const settingsManager = SettingsManager.create(cwd);
-	time("SettingsManager.create");
-
 	// Initialize discovery system with settings for provider persistence
 	const { initializeWithSettings } = await import("./discovery");
 	initializeWithSettings(settingsManager);
@@ -392,6 +389,11 @@ export async function main(args: string[]) {
 	initTheme(settingsManager.getTheme(), isInteractive, settingsManager.getSymbolPreset());
 	time("initTheme");
 
+	// Show deprecation warnings in interactive mode
+	if (isInteractive && deprecationWarnings.length > 0) {
+		await showDeprecationWarnings(deprecationWarnings);
+	}
+
 	let scopedModels: ScopedModel[] = [];
 	const modelPatterns = parsed.models ?? settingsManager.getEnabledModels();
 	if (modelPatterns && modelPatterns.length > 0) {
@@ -420,9 +422,16 @@ export async function main(args: string[]) {
 		sessionManager = await SessionManager.open(selectedPath);
 	}
 
-	const sessionOptions = await buildSessionOptions(parsed, scopedModels, sessionManager, modelRegistry);
+	const sessionOptions = await buildSessionOptions(
+		parsed,
+		scopedModels,
+		sessionManager,
+		modelRegistry,
+		settingsManager,
+	);
 	sessionOptions.authStorage = authStorage;
 	sessionOptions.modelRegistry = modelRegistry;
+	sessionOptions.settingsManager = settingsManager;
 	sessionOptions.hasUI = isInteractive;
 
 	// Handle CLI --api-key as runtime override (not persisted)
@@ -435,9 +444,25 @@ export async function main(args: string[]) {
 	}
 
 	time("buildSessionOptions");
-	const { session, customToolsResult, modelFallbackMessage, lspServers } = await createAgentSession(sessionOptions);
+	const { session, extensionsResult, modelFallbackMessage, lspServers } = await createAgentSession(sessionOptions);
 	time("createAgentSession");
 
+	// Re-parse CLI args with extension flags and apply values
+	if (session.extensionRunner) {
+		const extFlags = session.extensionRunner.getFlags();
+		if (extFlags.size > 0) {
+			const flagDefs = new Map<string, { type: "boolean" | "string" }>();
+			for (const [name, flag] of extFlags) {
+				flagDefs.set(name, { type: flag.type });
+			}
+			const reparsed = parseArgs(args, flagDefs);
+			for (const [name, value] of reparsed.unknownFlags) {
+				session.extensionRunner.setFlagValue(name, value);
+			}
+		}
+	}
+	time("applyExtensionFlags");
+
 	if (!isInteractive && !session.model) {
 		console.error(chalk.red("No models available."));
 		console.error(chalk.yellow("\nSet an API key environment variable:"));
@@ -489,8 +514,7 @@ export async function main(args: string[]) {
 			migratedProviders,
 			versionCheckPromise,
 			parsed.messages,
-			customToolsResult.tools,
-			customToolsResult.setUIContext,
+			extensionsResult.setUIContext,
 			lspServers,
 			initialMessage,
 			initialImages,

package/src/migrations.ts

@@ -4,22 +4,28 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import chalk from "chalk";
 import { getAgentDir } from "./config";
 
 /**
  * Migrate PI_* environment variables to OMP_* equivalents.
  * If PI_XX is set and OMP_XX is not, set OMP_XX to PI_XX's value.
  * This provides backwards compatibility for users with existing PI_* env vars.
+ *
+ * @returns Array of PI_* env var names that were migrated
  */
-export function migrateEnvVars(): void {
+export function migrateEnvVars(): string[] {
+	const migrated: string[] = [];
 	for (const [key, value] of Object.entries(process.env)) {
 		if (key.startsWith("PI_") && value !== undefined) {
 			const ompKey = `OMP_${key.slice(3)}`; // PI_FOO -> OMP_FOO
 			if (process.env[ompKey] === undefined) {
 				process.env[ompKey] = value;
+				migrated.push(key);
 			}
 		}
 	}
+	return migrated;
 }
 
 /**
@@ -122,9 +128,7 @@ export function migrateSessionsFromAgentRoot(): void {
 			const correctDir = join(agentDir, "sessions", safePath);
 
 			// Create directory if needed
-			if (!existsSync(correctDir)) {
-				mkdirSync(correctDir, { recursive: true });
-			}
+			mkdirSync(correctDir, { recursive: true });
 
 			// Move the file
 			const fileName = file.split("/").pop() || file.split("\\").pop();
@@ -142,15 +146,41 @@ export function migrateSessionsFromAgentRoot(): void {
 /**
  * Run all migrations. Called once on startup.
  *
+ * @param _cwd - Current working directory (reserved for future project-local migrations)
  * @returns Object with migration results
  */
-export function runMigrations(): { migratedAuthProviders: string[] } {
+export async function runMigrations(_cwd: string): Promise<{
+	migratedAuthProviders: string[];
+	deprecationWarnings: string[];
+}> {
 	// First: migrate env vars (before anything else reads them)
-	migrateEnvVars();
+	const migratedEnvVars = migrateEnvVars();
 
 	// Then: run data migrations
 	const migratedAuthProviders = migrateAuthToAuthJson();
 	migrateSessionsFromAgentRoot();
 
-	return { migratedAuthProviders };
+	// Collect deprecation warnings
+	const deprecationWarnings: string[] = [];
+	if (migratedEnvVars.length > 0) {
+		for (const envVar of migratedEnvVars) {
+			const ompVar = `OMP_${envVar.slice(3)}`;
+			deprecationWarnings.push(`${envVar} is deprecated. Use ${ompVar} instead.`);
+		}
+	}
+
+	return { migratedAuthProviders, deprecationWarnings };
+}
+
+/**
+ * Display deprecation warnings to the user in interactive mode.
+ *
+ * @param warnings - Array of deprecation warning messages
+ */
+export async function showDeprecationWarnings(warnings: string[]): Promise<void> {
+	console.log(chalk.yellow("\n⚠ Deprecation Warnings:"));
+	for (const warning of warnings) {
+		console.log(chalk.yellow(`  • ${warning}`));
+	}
+	console.log();
 }