@oh-my-pi/pi-coding-agent 1.341.0 → 2.1.1337

package/src/modes/interactive/components/user-message.ts

@@ -1,5 +1,5 @@
 import { Container, Markdown, Spacer } from "@oh-my-pi/pi-tui";
-import { getMarkdownTheme, theme } from "../theme/theme.js";
+import { getMarkdownTheme, theme } from "../theme/theme";
 
 /**
  * Component that renders a user message

package/src/modes/interactive/components/welcome.ts

@@ -1,6 +1,6 @@
 import { type Component, visibleWidth } from "@oh-my-pi/pi-tui";
-import { APP_NAME } from "../../../config.js";
-import { theme } from "../theme/theme.js";
+import { APP_NAME } from "../../../config";
+import { theme } from "../theme/theme";
 
 export interface RecentSession {
 	name: string;

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

@@ -23,40 +23,40 @@ import {
 	TUI,
 	visibleWidth,
 } from "@oh-my-pi/pi-tui";
-import { getAuthPath, getDebugLogPath } from "../../config.js";
-import type { AgentSession, AgentSessionEvent } from "../../core/agent-session.js";
-import type { CustomToolSessionEvent, LoadedCustomTool } from "../../core/custom-tools/index.js";
-import type { HookUIContext } from "../../core/hooks/index.js";
-import { createCompactionSummaryMessage } from "../../core/messages.js";
-import { getRecentSessions, type SessionContext, SessionManager } from "../../core/session-manager.js";
-import { loadSkills } from "../../core/skills.js";
-import { loadProjectContextFiles } from "../../core/system-prompt.js";
-import { generateSessionTitle, setTerminalTitle } from "../../core/title-generator.js";
-import type { TruncationResult } from "../../core/tools/truncate.js";
-import { getChangelogPath, parseChangelog } from "../../utils/changelog.js";
-import { copyToClipboard, readImageFromClipboard } from "../../utils/clipboard.js";
-import { ArminComponent } from "./components/armin.js";
-import { AssistantMessageComponent } from "./components/assistant-message.js";
-import { BashExecutionComponent } from "./components/bash-execution.js";
-import { BorderedLoader } from "./components/bordered-loader.js";
-import { BranchSummaryMessageComponent } from "./components/branch-summary-message.js";
-import { CompactionSummaryMessageComponent } from "./components/compaction-summary-message.js";
-import { CustomEditor } from "./components/custom-editor.js";
-import { DynamicBorder } from "./components/dynamic-border.js";
-import { FooterComponent } from "./components/footer.js";
-import { HookEditorComponent } from "./components/hook-editor.js";
-import { HookInputComponent } from "./components/hook-input.js";
-import { HookMessageComponent } from "./components/hook-message.js";
-import { HookSelectorComponent } from "./components/hook-selector.js";
-import { ModelSelectorComponent } from "./components/model-selector.js";
-import { OAuthSelectorComponent } from "./components/oauth-selector.js";
-import { SessionSelectorComponent } from "./components/session-selector.js";
-import { SettingsSelectorComponent } from "./components/settings-selector.js";
-import { ToolExecutionComponent } from "./components/tool-execution.js";
-import { TreeSelectorComponent } from "./components/tree-selector.js";
-import { UserMessageComponent } from "./components/user-message.js";
-import { UserMessageSelectorComponent } from "./components/user-message-selector.js";
-import { WelcomeComponent } from "./components/welcome.js";
+import { getAuthPath, getDebugLogPath } from "../../config";
+import type { AgentSession, AgentSessionEvent } from "../../core/agent-session";
+import type { CustomToolSessionEvent, LoadedCustomTool } from "../../core/custom-tools/index";
+import type { HookUIContext } from "../../core/hooks/index";
+import { createCompactionSummaryMessage } from "../../core/messages";
+import { getRecentSessions, type SessionContext, SessionManager } from "../../core/session-manager";
+import { loadSkills } from "../../core/skills";
+import { loadProjectContextFiles } from "../../core/system-prompt";
+import { generateSessionTitle, setTerminalTitle } from "../../core/title-generator";
+import type { TruncationResult } from "../../core/tools/truncate";
+import { getChangelogPath, parseChangelog } from "../../utils/changelog";
+import { copyToClipboard, readImageFromClipboard } from "../../utils/clipboard";
+import { ArminComponent } from "./components/armin";
+import { AssistantMessageComponent } from "./components/assistant-message";
+import { BashExecutionComponent } from "./components/bash-execution";
+import { BorderedLoader } from "./components/bordered-loader";
+import { BranchSummaryMessageComponent } from "./components/branch-summary-message";
+import { CompactionSummaryMessageComponent } from "./components/compaction-summary-message";
+import { CustomEditor } from "./components/custom-editor";
+import { DynamicBorder } from "./components/dynamic-border";
+import { FooterComponent } from "./components/footer";
+import { HookEditorComponent } from "./components/hook-editor";
+import { HookInputComponent } from "./components/hook-input";
+import { HookMessageComponent } from "./components/hook-message";
+import { HookSelectorComponent } from "./components/hook-selector";
+import { ModelSelectorComponent } from "./components/model-selector";
+import { OAuthSelectorComponent } from "./components/oauth-selector";
+import { SessionSelectorComponent } from "./components/session-selector";
+import { SettingsSelectorComponent } from "./components/settings-selector";
+import { ToolExecutionComponent } from "./components/tool-execution";
+import { TreeSelectorComponent } from "./components/tree-selector";
+import { UserMessageComponent } from "./components/user-message";
+import { UserMessageSelectorComponent } from "./components/user-message-selector";
+import { WelcomeComponent } from "./components/welcome";
 import {
 	getAvailableThemes,
 	getEditorTheme,
@@ -65,7 +65,7 @@ import {
 	setTheme,
 	type Theme,
 	theme,
-} from "./theme/theme.js";
+} from "./theme/theme";
 
 /** Interface for components that can be expanded/collapsed */
 interface Expandable {
@@ -185,7 +185,7 @@ export class InteractiveMode {
 		const slashCommands: SlashCommand[] = [
 			{ name: "settings", description: "Open settings menu" },
 			{ name: "model", description: "Select model (opens selector UI)" },
-			{ name: "export", description: "Export session to HTML file" },
+			{ name: "export", description: "Export session to HTML file or clipboard (--copy)" },
 			{ name: "share", description: "Share session as a secret GitHub gist" },
 			{ name: "copy", description: "Copy last agent message to clipboard" },
 			{ name: "session", description: "Show session info and stats" },
@@ -216,9 +216,15 @@ export class InteractiveMode {
 			description: cmd.description ?? "(hook command)",
 		}));
 
+		// Convert custom commands (TypeScript) to SlashCommand format
+		const customCommands: SlashCommand[] = this.session.customCommands.map((loaded) => ({
+			name: loaded.command.name,
+			description: `${loaded.command.description} (${loaded.source})`,
+		}));
+
 		// Setup autocomplete
 		const autocompleteProvider = new CombinedAutocompleteProvider(
-			[...slashCommands, ...fileSlashCommands, ...hookCommands],
+			[...slashCommands, ...fileSlashCommands, ...hookCommands, ...customCommands],
 			process.cwd(),
 			fdPath,
 		);
@@ -745,7 +751,7 @@ export class InteractiveMode {
 				return;
 			}
 			if (text.startsWith("/export")) {
-				this.handleExportCommand(text);
+				await this.handleExportCommand(text);
 				this.editor.setText("");
 				return;
 			}
@@ -867,6 +873,19 @@ export class InteractiveMode {
 				}
 			}
 
+			// Custom commands (TypeScript slash commands) - route through session.prompt()
+			if (text.startsWith("/") && this.session.customCommands.length > 0) {
+				const spaceIndex = text.indexOf(" ");
+				const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+				const hasCustomCommand = this.session.customCommands.some((c) => c.command.name === commandName);
+				if (hasCustomCommand) {
+					this.editor.addToHistory(text);
+					this.editor.setText("");
+					await this.session.prompt(text);
+					return;
+				}
+			}
+
 			// Queue regular messages if agent is streaming
 			if (this.session.isStreaming) {
 				await this.session.queueMessage(text);
@@ -1232,6 +1251,14 @@ export class InteractiveMode {
 				this.chatContainer.addChild(component);
 				break;
 			}
+			case "fileMention": {
+				// Render compact file mention display
+				for (const file of message.files) {
+					const text = `${theme.fg("dim", "⎿ ")}${theme.fg("muted", "Read")} ${theme.fg("accent", file.path)} ${theme.fg("dim", `(${file.lineCount} lines)`)}`;
+					this.chatContainer.addChild(new Text(text, 0, 0));
+				}
+				break;
+			}
 			case "user": {
 				const textContent = this.getUserMessageText(message);
 				if (textContent) {
@@ -2081,12 +2108,29 @@ export class InteractiveMode {
 	// Command handlers
 	// =========================================================================
 
-	private handleExportCommand(text: string): void {
+	private async handleExportCommand(text: string): Promise<void> {
 		const parts = text.split(/\s+/);
-		const outputPath = parts.length > 1 ? parts[1] : undefined;
+		const arg = parts.length > 1 ? parts[1] : undefined;
+
+		// Check for clipboard export
+		if (arg === "--copy" || arg === "clipboard" || arg === "copy") {
+			try {
+				const formatted = this.session.formatSessionAsText();
+				if (!formatted) {
+					this.showError("No messages to export yet.");
+					return;
+				}
+				await copyToClipboard(formatted);
+				this.showStatus("Session copied to clipboard");
+			} catch (error: unknown) {
+				this.showError(`Failed to copy session: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+			return;
+		}
 
+		// HTML file export
 		try {
-			const filePath = this.session.exportToHtml(outputPath);
+			const filePath = await this.session.exportToHtml(arg);
 			this.showStatus(`Session exported to: ${filePath}`);
 		} catch (error: unknown) {
 			this.showError(`Failed to export session: ${error instanceof Error ? error.message : "Unknown error"}`);
@@ -2109,7 +2153,7 @@ export class InteractiveMode {
 		// Export to a temp file
 		const tmpFile = path.join(os.tmpdir(), "session.html");
 		try {
-			this.session.exportToHtml(tmpFile);
+			await this.session.exportToHtml(tmpFile);
 		} catch (error: unknown) {
 			this.showError(`Failed to export session: ${error instanceof Error ? error.message : "Unknown error"}`);
 			return;

package/src/modes/interactive/theme/theme.ts

@@ -5,7 +5,11 @@ import { type Static, Type } from "@sinclair/typebox";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import chalk from "chalk";
 import { highlight, supportsLanguage } from "cli-highlight";
-import { getCustomThemesDir, getThemesDir } from "../../../config.js";
+import { getCustomThemesDir } from "../../../config";
+import { logger } from "../../../core/logger";
+// Embed theme JSON files at build time
+import darkThemeJson from "./dark.json" with { type: "json" };
+import lightThemeJson from "./light.json" with { type: "json" };
 
 // ============================================================================
 // Types & Schema
@@ -449,18 +453,12 @@ export class Theme {
 // Theme Loading
 // ============================================================================
 
-let BUILTIN_THEMES: Record<string, ThemeJson> | undefined;
+const BUILTIN_THEMES: Record<string, ThemeJson> = {
+	dark: darkThemeJson as ThemeJson,
+	light: lightThemeJson as ThemeJson,
+};
 
 function getBuiltinThemes(): Record<string, ThemeJson> {
-	if (!BUILTIN_THEMES) {
-		const themesDir = getThemesDir();
-		const darkPath = path.join(themesDir, "dark.json");
-		const lightPath = path.join(themesDir, "light.json");
-		BUILTIN_THEMES = {
-			dark: JSON.parse(fs.readFileSync(darkPath, "utf-8")) as ThemeJson,
-			light: JSON.parse(fs.readFileSync(lightPath, "utf-8")) as ThemeJson,
-		};
-	}
 	return BUILTIN_THEMES;
 }
 
@@ -590,8 +588,8 @@ export function initTheme(themeName?: string, enableWatcher: boolean = false): v
 		if (enableWatcher) {
 			startThemeWatcher();
 		}
-	} catch (_error) {
-		// Theme is invalid - fall back to dark theme silently
+	} catch (err) {
+		logger.debug("Theme loading failed, falling back to dark theme", { error: String(err) });
 		currentThemeName = "dark";
 		theme = loadTheme("dark");
 		// Don't start watcher for fallback theme
@@ -654,8 +652,8 @@ function startThemeWatcher(): void {
 						if (onThemeChangeCallback) {
 							onThemeChangeCallback();
 						}
-					} catch (_error) {
-						// Ignore errors (file might be in invalid state while being edited)
+					} catch (err) {
+						logger.debug("Theme reload error during file change", { error: String(err) });
 					}
 				}, 100);
 			} else if (eventType === "rename") {
@@ -675,8 +673,8 @@ function startThemeWatcher(): void {
 				}, 100);
 			}
 		});
-	} catch (_error) {
-		// Ignore errors starting watcher
+	} catch (err) {
+		logger.debug("Failed to start theme watcher", { error: String(err) });
 	}
 }
 

package/src/modes/print-mode.ts

@@ -7,7 +7,8 @@
  */
 
 import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
-import type { AgentSession } from "../core/agent-session.js";
+import type { AgentSession } from "../core/agent-session";
+import { logger } from "../core/logger";
 
 /**
  * Run in print (single-shot) mode.
@@ -70,8 +71,8 @@ export async function runPrintMode(
 						},
 					},
 				);
-			} catch (_err) {
-				// Silently ignore tool errors
+			} catch (err) {
+				logger.warn("Tool onSession error", { error: String(err) });
 			}
 		}
 	}

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

@@ -7,10 +7,10 @@
 import type { AgentEvent, AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import type { Subprocess } from "bun";
-import type { SessionStats } from "../../core/agent-session.js";
-import type { BashResult } from "../../core/bash-executor.js";
-import type { CompactionResult } from "../../core/compaction/index.js";
-import type { RpcCommand, RpcResponse, RpcSessionState } from "./rpc-types.js";
+import type { SessionStats } from "../../core/agent-session";
+import type { BashResult } from "../../core/bash-executor";
+import type { CompactionResult } from "../../core/compaction/index";
+import type { RpcCommand, RpcResponse, RpcSessionState } from "./rpc-types";
 
 // ============================================================================
 // Types

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

@@ -11,13 +11,14 @@
  * - Hook UI: Hook UI requests are emitted, client responds with hook_ui_response
  */
 
-import type { AgentSession } from "../../core/agent-session.js";
-import type { HookUIContext } from "../../core/hooks/index.js";
-import { theme } from "../interactive/theme/theme.js";
-import type { RpcCommand, RpcHookUIRequest, RpcHookUIResponse, RpcResponse, RpcSessionState } from "./rpc-types.js";
+import type { AgentSession } from "../../core/agent-session";
+import type { HookUIContext } from "../../core/hooks/index";
+import { logger } from "../../core/logger";
+import { theme } from "../interactive/theme/theme";
+import type { RpcCommand, RpcHookUIRequest, RpcHookUIResponse, RpcResponse, RpcSessionState } from "./rpc-types";
 
 // Re-export types for consumers
-export type { RpcCommand, RpcHookUIRequest, RpcHookUIResponse, RpcResponse, RpcSessionState } from "./rpc-types.js";
+export type { RpcCommand, RpcHookUIRequest, RpcHookUIResponse, RpcResponse, RpcSessionState } from "./rpc-types";
 
 /**
  * Run in RPC mode.
@@ -220,8 +221,8 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 						},
 					},
 				);
-			} catch (_err) {
-				// Silently ignore tool errors
+			} catch (err) {
+				logger.warn("Tool onSession error", { error: String(err) });
 			}
 		}
 	}
@@ -231,6 +232,9 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 		output(event);
 	});
 
+	// Serialize prompt commands to prevent concurrent execution
+	let activePrompt: Promise<void> | null = null;
+
 	// Handle a single command
 	const handleCommand = async (command: RpcCommand): Promise<RpcResponse> => {
 		const id = command.id;
@@ -241,13 +245,18 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			// =================================================================
 
 			case "prompt": {
-				// Don't await - events will stream
-				// Hook commands and file slash commands are handled in session.prompt()
-				session
+				// Serialize prompts to prevent concurrent execution
+				if (activePrompt) {
+					await activePrompt;
+				}
+				activePrompt = session
 					.prompt(command.message, {
 						images: command.images,
 					})
-					.catch((e) => output(error(id, "prompt", e.message)));
+					.catch((e) => output(error(id, "prompt", e.message)))
+					.finally(() => {
+						activePrompt = null;
+					});
 				return success(id, "prompt");
 			}
 
@@ -392,7 +401,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			}
 
 			case "export_html": {
-				const path = session.exportToHtml(command.outputPath);
+				const path = await session.exportToHtml(command.outputPath);
 				return success(id, "export_html", { path });
 			}
 
@@ -462,6 +471,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					const response = parsed as RpcHookUIResponse;
 					const pending = pendingHookRequests.get(response.id);
 					if (pending) {
+						// Atomic delete: remove before resolve to prevent double-resolution
 						pendingHookRequests.delete(response.id);
 						pending.resolve(response);
 					}

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

@@ -7,9 +7,9 @@
 
 import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, Model } from "@oh-my-pi/pi-ai";
-import type { SessionStats } from "../../core/agent-session.js";
-import type { BashResult } from "../../core/bash-executor.js";
-import type { CompactionResult } from "../../core/compaction/index.js";
+import type { SessionStats } from "../../core/agent-session";
+import type { BashResult } from "../../core/bash-executor";
+import type { CompactionResult } from "../../core/compaction/index";
 
 // ============================================================================
 // RPC Commands (stdin)

package/src/utils/changelog.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync } from "node:fs";
 
 export interface ChangelogEntry {
 	major: number;
@@ -96,4 +96,4 @@ export function getNewEntries(entries: ChangelogEntry[], lastVersion: string): C
 }
 
 // Re-export getChangelogPath from paths.ts for convenience
-export { getChangelogPath } from "../config.js";
+export { getChangelogPath } from "../config";

package/src/utils/clipboard.ts

@@ -1,4 +1,4 @@
-import { platform } from "os";
+import { platform } from "node:os";
 
 async function spawnWithTimeout(cmd: string[], input: string, timeoutMs: number): Promise<void> {
 	const proc = Bun.spawn(cmd, { stdin: "pipe" });

package/src/utils/shell-snapshot.ts

@@ -0,0 +1,218 @@
+/**
+ * Shell environment snapshot for preserving user aliases, functions, and options.
+ *
+ * Creates a snapshot file that captures the user's shell environment from their
+ * .bashrc/.zshrc, which can be sourced before each command to provide a familiar
+ * shell experience.
+ */
+
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+let cachedSnapshotPath: string | null = null;
+let cleanupRegistered = false;
+
+/**
+ * Get the user's shell config file path.
+ */
+function getShellConfigFile(shell: string): string {
+	const home = homedir();
+	if (shell.includes("zsh")) return join(home, ".zshrc");
+	if (shell.includes("bash")) return join(home, ".bashrc");
+	return join(home, ".profile");
+}
+
+/**
+ * Generate the snapshot creation script.
+ * This script sources the user's rc file and extracts functions, aliases, and options.
+ * Matches Claude Code's snapshot generation logic.
+ */
+function generateSnapshotScript(shell: string, snapshotPath: string, rcFile: string): string {
+	const hasRcFile = existsSync(rcFile);
+	const isZsh = shell.includes("zsh");
+
+	// Escape the snapshot path for shell
+	const escapedPath = snapshotPath.replace(/'/g, "'\\''");
+
+	// Function extraction differs between bash and zsh
+	const functionScript = isZsh
+		? `
+echo "# Functions" >> "$SNAPSHOT_FILE"
+# Force autoload all functions first
+typeset -f > /dev/null 2>&1
+# Get user function names - filter system/private ones
+typeset +f 2>/dev/null | grep -vE '^(_|__)' | while read func; do
+   typeset -f "$func" >> "$SNAPSHOT_FILE" 2>/dev/null
+done
+`
+		: `
+echo "# Functions" >> "$SNAPSHOT_FILE"
+# Force autoload all functions first
+declare -f > /dev/null 2>&1
+# Get user function names - filter system/private ones, use base64 for special chars
+declare -F 2>/dev/null | cut -d' ' -f3 | grep -vE '^(_|__)' | while read func; do
+   encoded_func=$(declare -f "$func" | base64)
+   echo "eval \\"\\$(echo '$encoded_func' | base64 -d)\\" > /dev/null 2>&1" >> "$SNAPSHOT_FILE"
+done
+`;
+
+	// Shell options extraction
+	const optionsScript = isZsh
+		? `
+echo "# Shell Options" >> "$SNAPSHOT_FILE"
+setopt 2>/dev/null | sed 's/^/setopt /' | head -n 1000 >> "$SNAPSHOT_FILE"
+`
+		: `
+echo "# Shell Options" >> "$SNAPSHOT_FILE"
+shopt -p 2>/dev/null | head -n 1000 >> "$SNAPSHOT_FILE"
+set -o 2>/dev/null | grep "on" | awk '{print "set -o " $1}' | head -n 1000 >> "$SNAPSHOT_FILE"
+echo "shopt -s expand_aliases" >> "$SNAPSHOT_FILE"
+`;
+
+	return `
+SNAPSHOT_FILE='${escapedPath}'
+
+# Source user's rc file if it exists
+${hasRcFile ? `source "${rcFile}" < /dev/null 2>/dev/null` : "# No user config file to source"}
+
+# Create/clear the snapshot file
+echo "# Shell snapshot - generated by pi agent" >| "$SNAPSHOT_FILE"
+
+# Unalias everything first to avoid conflicts when sourced
+echo "unalias -a 2>/dev/null || true" >> "$SNAPSHOT_FILE"
+
+${functionScript}
+
+${optionsScript}
+
+# Export aliases (limit to 1000)
+echo "# Aliases" >> "$SNAPSHOT_FILE"
+# Filter out winpty aliases on Windows to avoid "stdin is not a tty" errors
+if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+   alias 2>/dev/null | grep -v "='winpty " | sed 's/^alias //g' | sed 's/^/alias -- /' | head -n 1000 >> "$SNAPSHOT_FILE"
+else
+   alias 2>/dev/null | sed 's/^alias //g' | sed 's/^/alias -- /' | head -n 1000 >> "$SNAPSHOT_FILE"
+fi
+
+# Export PATH
+echo "export PATH='$PATH'" >> "$SNAPSHOT_FILE"
+
+# Verify snapshot was created
+if [ ! -f "$SNAPSHOT_FILE" ]; then
+   echo "Error: Snapshot file was not created" >&2
+   exit 1
+fi
+`.trim();
+}
+
+/**
+ * Create a shell snapshot, caching the result.
+ * Returns the path to the snapshot file, or null if creation failed.
+ */
+export async function getOrCreateSnapshot(
+	shell: string,
+	env: Record<string, string | undefined>,
+): Promise<string | null> {
+	// Return cached snapshot if valid
+	if (cachedSnapshotPath && existsSync(cachedSnapshotPath)) {
+		return cachedSnapshotPath;
+	}
+
+	// Skip on Windows (no .bashrc in standard location)
+	if (process.platform === "win32") {
+		return null;
+	}
+
+	const rcFile = getShellConfigFile(shell);
+
+	// Create snapshot directory
+	const snapshotDir = join(tmpdir(), "pi-shell-snapshots");
+	try {
+		mkdirSync(snapshotDir, { recursive: true });
+	} catch {
+		return null;
+	}
+
+	// Generate unique snapshot path
+	const timestamp = Date.now();
+	const random = Math.random().toString(36).substring(2, 8);
+	const shellName = shell.includes("zsh") ? "zsh" : shell.includes("bash") ? "bash" : "sh";
+	const snapshotPath = join(snapshotDir, `snapshot-${shellName}-${timestamp}-${random}.sh`);
+
+	// Generate and execute snapshot script
+	const script = generateSnapshotScript(shell, snapshotPath, rcFile);
+
+	try {
+		const result = Bun.spawnSync([shell, "-l", "-c", script], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe",
+			env,
+			timeout: 10000, // 10 second timeout
+		});
+
+		if (result.exitCode === 0 && existsSync(snapshotPath)) {
+			cachedSnapshotPath = snapshotPath;
+			registerCleanup();
+			return snapshotPath;
+		}
+	} catch {
+		// Snapshot creation failed, proceed without it
+	}
+
+	return null;
+}
+
+/**
+ * Get the command prefix to source the snapshot.
+ * Returns empty string if no snapshot available.
+ */
+export function getSnapshotSourceCommand(snapshotPath: string | null): string {
+	if (!snapshotPath) return "";
+	// Escape for shell
+	const escaped = snapshotPath.replace(/'/g, "'\\''");
+	return `source '${escaped}' 2>/dev/null && `;
+}
+
+/**
+ * Register cleanup handler to delete snapshot on process exit.
+ */
+function registerCleanup(): void {
+	if (cleanupRegistered) return;
+	cleanupRegistered = true;
+
+	const cleanup = () => {
+		if (cachedSnapshotPath && existsSync(cachedSnapshotPath)) {
+			try {
+				unlinkSync(cachedSnapshotPath);
+			} catch {
+				// Ignore cleanup errors
+			}
+		}
+	};
+
+	process.on("exit", cleanup);
+	process.on("SIGINT", () => {
+		cleanup();
+		process.exit(130);
+	});
+	process.on("SIGTERM", () => {
+		cleanup();
+		process.exit(143);
+	});
+}
+
+/**
+ * Clear the cached snapshot (for testing or forced refresh).
+ */
+export function clearSnapshotCache(): void {
+	if (cachedSnapshotPath && existsSync(cachedSnapshotPath)) {
+		try {
+			unlinkSync(cachedSnapshotPath);
+		} catch {
+			// Ignore
+		}
+	}
+	cachedSnapshotPath = null;
+}