@oh-my-pi/pi-coding-agent 3.33.0 → 3.35.0

package/src/core/sdk.ts

@@ -27,8 +27,8 @@
  */
 
 import { join } from "node:path";
-import type { Model } from "@mariozechner/pi-ai";
 import { Agent, type AgentTool, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Model } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import chalk from "chalk";
 // Import discovery to register all providers on startup
@@ -37,6 +37,7 @@ import { loadSync as loadCapability } from "../capability/index";
 import { type Rule, ruleCapability } from "../capability/rule";
 import { getAgentDir, getConfigDirPaths } from "../config";
 import { initializeWithSettings } from "../discovery";
+import { registerAsyncCleanup } from "../modes/cleanup";
 import { AgentSession } from "./agent-session";
 import { AuthStorage } from "./auth-storage";
 import {
@@ -67,6 +68,8 @@ import { SessionManager } from "./session-manager";
 import { type Settings, SettingsManager, type SkillsSettings } from "./settings-manager";
 import { loadSkills as loadSkillsInternal, type Skill } from "./skills";
 import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal } from "./slash-commands";
+import { closeAllConnections } from "./ssh/connection-manager";
+import { unmountAll } from "./ssh/sshfs-mount";
 import {
 	buildSystemPrompt as buildSystemPromptInternal,
 	loadProjectContextFiles as loadContextFilesInternal,
@@ -83,6 +86,7 @@ import {
 	createGrepTool,
 	createLsTool,
 	createReadTool,
+	createSshTool,
 	createTools,
 	createWriteTool,
 	filterRulebookRules,
@@ -204,6 +208,7 @@ export {
 	// Individual tool factories (for custom usage)
 	createReadTool,
 	createBashTool,
+	createSshTool,
 	createEditTool,
 	createWriteTool,
 	createGrepTool,
@@ -399,6 +404,23 @@ function isCustomTool(tool: CustomTool | ToolDefinition): tool is CustomTool {
 
 const TOOL_DEFINITION_MARKER = Symbol("__isToolDefinition");
 
+let sshCleanupRegistered = false;
+
+async function cleanupSshResources(): Promise<void> {
+	const results = await Promise.allSettled([closeAllConnections(), unmountAll()]);
+	for (const result of results) {
+		if (result.status === "rejected") {
+			logger.warn("SSH cleanup failed", { error: String(result.reason) });
+		}
+	}
+}
+
+function registerSshCleanup(): void {
+	if (sshCleanupRegistered) return;
+	sshCleanupRegistered = true;
+	registerAsyncCleanup(() => cleanupSshResources());
+}
+
 function customToolToDefinition(tool: CustomTool): ToolDefinition {
 	const definition: ToolDefinition & { [TOOL_DEFINITION_MARKER]: true } = {
 		name: tool.name,
@@ -471,7 +493,7 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
  * const { session } = await createAgentSession();
  *
  * // With explicit model
- * import { getModel } from '@mariozechner/pi-ai';
+ * import { getModel } from '@oh-my-pi/pi-ai';
  * const { session } = await createAgentSession({
  *   model: getModel('anthropic', 'claude-opus-4-5'),
  *   thinkingLevel: 'high',
@@ -498,6 +520,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const agentDir = options.agentDir ?? getDefaultAgentDir();
 	const eventBus = options.eventBus ?? createEventBus();
 
+	registerSshCleanup();
+
 	// Use provided or create AuthStorage and ModelRegistry
 	const authStorage = options.authStorage ?? (await discoverAuthStorage(agentDir));
 	const modelRegistry = options.modelRegistry ?? (await discoverModels(authStorage, agentDir));
@@ -609,6 +633,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const contextFiles = options.contextFiles ?? discoverContextFiles(cwd, agentDir);
 	time("discoverContextFiles");
 
+	let agent: Agent;
+	let session: AgentSession;
+
 	const toolSession: ToolSession = {
 		cwd,
 		hasUI: options.hasUI ?? false,
@@ -619,6 +646,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getSessionFile: () => sessionManager.getSessionFile() ?? null,
 		getSessionSpawns: () => options.spawns ?? "*",
 		getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
+		getActiveModelString: () => {
+			const activeModel = agent?.state.model;
+			return activeModel ? formatModelString(activeModel) : undefined;
+		},
 		settings: settingsManager,
 	};
 
@@ -758,8 +789,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		extensionRunner = new ExtensionRunner(extensionsResult.extensions, cwd, sessionManager, modelRegistry);
 	}
 
-	let agent: Agent;
-	let session: AgentSession;
 	const getSessionContext = () => ({
 		sessionManager,
 		modelRegistry,

package/src/core/session-manager.ts

@@ -1,6 +1,6 @@
 import { basename, join, resolve } from "node:path";
-import type { ImageContent, Message, TextContent, Usage } from "@mariozechner/pi-ai";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, Message, TextContent, Usage } from "@oh-my-pi/pi-ai";
 import { nanoid } from "nanoid";
 import { getAgentDir as getDefaultAgentDir } from "../config";
 import { resizeImage } from "../utils/image-resize";
@@ -1338,6 +1338,21 @@ export class SessionManager {
 		return this.leafId ? this.byId.get(this.leafId) : undefined;
 	}
 
+	/**
+	 * Get the most recent model role from the current session path.
+	 * Returns undefined if no model change has been recorded.
+	 */
+	getLastModelChangeRole(): string | undefined {
+		let current = this.getLeafEntry();
+		while (current) {
+			if (current.type === "model_change") {
+				return current.role ?? "default";
+			}
+			current = current.parentId ? this.byId.get(current.parentId) : undefined;
+		}
+		return undefined;
+	}
+
 	getEntry(id: string): SessionEntry | undefined {
 		return this.byId.get(id);
 	}

package/src/core/settings-manager.ts

@@ -371,7 +371,8 @@ export class SettingsManager {
 	private settingsPath: string | null;
 	private cwd: string | null;
 	private globalSettings: Settings;
-	private settings: Settings;
+	private overrides: Settings;
+	private settings!: Settings;
 	private persist: boolean;
 
 	private constructor(settingsPath: string | null, cwd: string | null, initialSettings: Settings, persist: boolean) {
@@ -379,8 +380,8 @@ export class SettingsManager {
 		this.cwd = cwd;
 		this.persist = persist;
 		this.globalSettings = initialSettings;
-		const projectSettings = this.loadProjectSettings();
-		this.settings = normalizeSettings(deepMergeSettings(this.globalSettings, projectSettings));
+		this.overrides = {};
+		this.rebuildSettings();
 
 		// Apply environment variables from settings
 		this.applyEnvironmentVariables();
@@ -474,9 +475,17 @@ export class SettingsManager {
 		return SettingsManager.migrateSettings(merged as Record<string, unknown>);
 	}
 
+	private rebuildSettings(projectSettings?: Settings): void {
+		const resolvedProjectSettings = projectSettings ?? this.loadProjectSettings();
+		this.settings = normalizeSettings(
+			deepMergeSettings(deepMergeSettings(this.globalSettings, resolvedProjectSettings), this.overrides),
+		);
+	}
+
 	/** Apply additional overrides on top of current settings */
 	applyOverrides(overrides: Partial<Settings>): void {
-		this.settings = normalizeSettings(deepMergeSettings(this.settings, overrides));
+		this.overrides = deepMergeSettings(this.overrides, overrides);
+		this.rebuildSettings();
 	}
 
 	private save(): void {
@@ -491,9 +500,9 @@ export class SettingsManager {
 			// Save only global settings (project settings are read-only)
 			writeFileSync(this.settingsPath, JSON.stringify(this.globalSettings, null, 2), "utf-8");
 
-			// Re-merge project settings into active settings
+			// Re-merge project settings into active settings (preserve overrides)
 			const projectSettings = this.loadProjectSettings();
-			this.settings = normalizeSettings(deepMergeSettings(this.globalSettings, projectSettings));
+			this.rebuildSettings(projectSettings);
 		} catch (error) {
 			console.error(`Warning: Could not save settings file: ${error}`);
 		}
@@ -523,6 +532,11 @@ export class SettingsManager {
 			this.globalSettings.modelRoles = {};
 		}
 		this.globalSettings.modelRoles[role] = model;
+
+		if (this.overrides.modelRoles && this.overrides.modelRoles[role] !== undefined) {
+			this.overrides.modelRoles[role] = model;
+		}
+
 		this.save();
 	}
 

package/src/core/ssh/connection-manager.ts

@@ -0,0 +1,466 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "../../config";
+import { logger } from "../logger";
+
+export interface SSHConnectionTarget {
+	name: string;
+	host: string;
+	username?: string;
+	port?: number;
+	keyPath?: string;
+	compat?: boolean;
+}
+
+export type SSHHostOs = "windows" | "linux" | "macos" | "unknown";
+export type SSHHostShell = "cmd" | "powershell" | "bash" | "zsh" | "sh" | "unknown";
+
+export interface SSHHostInfo {
+	version: number;
+	os: SSHHostOs;
+	shell: SSHHostShell;
+	compatShell?: "bash" | "sh";
+	compatEnabled: boolean;
+}
+
+const CONTROL_DIR = join(homedir(), CONFIG_DIR_NAME, "ssh-control");
+const CONTROL_PATH = join(CONTROL_DIR, "%h.sock");
+const HOST_INFO_DIR = join(homedir(), CONFIG_DIR_NAME, "remote-host");
+const HOST_INFO_VERSION = 2;
+
+const activeHosts = new Map<string, SSHConnectionTarget>();
+const pendingConnections = new Map<string, Promise<void>>();
+const hostInfoCache = new Map<string, SSHHostInfo>();
+
+function ensureControlDir(): void {
+	if (!existsSync(CONTROL_DIR)) {
+		mkdirSync(CONTROL_DIR, { recursive: true, mode: 0o700 });
+	}
+	try {
+		chmodSync(CONTROL_DIR, 0o700);
+	} catch (err) {
+		logger.debug("SSH control dir chmod failed", { path: CONTROL_DIR, error: String(err) });
+	}
+}
+
+function ensureHostInfoDir(): void {
+	if (!existsSync(HOST_INFO_DIR)) {
+		mkdirSync(HOST_INFO_DIR, { recursive: true, mode: 0o700 });
+	}
+	try {
+		chmodSync(HOST_INFO_DIR, 0o700);
+	} catch (err) {
+		logger.debug("SSH host info dir chmod failed", { path: HOST_INFO_DIR, error: String(err) });
+	}
+}
+
+function sanitizeHostName(name: string): string {
+	const sanitized = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
+	return sanitized.length > 0 ? sanitized : "host";
+}
+
+function getHostInfoPath(name: string): string {
+	return join(HOST_INFO_DIR, `${sanitizeHostName(name)}.json`);
+}
+
+function validateKeyPermissions(keyPath?: string): void {
+	if (!keyPath) return;
+	if (!existsSync(keyPath)) {
+		throw new Error(`SSH key not found: ${keyPath}`);
+	}
+	const stats = statSync(keyPath);
+	if (!stats.isFile()) {
+		throw new Error(`SSH key is not a file: ${keyPath}`);
+	}
+	const mode = stats.mode & 0o777;
+	if ((mode & 0o077) !== 0) {
+		throw new Error(`SSH key permissions must be 600 or stricter: ${keyPath}`);
+	}
+}
+
+function buildSshTarget(host: SSHConnectionTarget): string {
+	return host.username ? `${host.username}@${host.host}` : host.host;
+}
+
+function buildCommonArgs(host: SSHConnectionTarget): string[] {
+	const args = [
+		"-o",
+		"ControlMaster=auto",
+		"-o",
+		`ControlPath=${CONTROL_PATH}`,
+		"-o",
+		"ControlPersist=3600",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		"StrictHostKeyChecking=accept-new",
+	];
+
+	if (host.port) {
+		args.push("-p", String(host.port));
+	}
+	if (host.keyPath) {
+		args.push("-i", host.keyPath);
+	}
+
+	return args;
+}
+
+function decodeOutput(buffer?: Uint8Array): string {
+	if (!buffer || buffer.length === 0) return "";
+	return new TextDecoder().decode(buffer).trim();
+}
+
+function runSshSync(args: string[]): { exitCode: number | null; stderr: string } {
+	const result = Bun.spawnSync(["ssh", ...args], {
+		stdin: "ignore",
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+
+	return { exitCode: result.exitCode, stderr: decodeOutput(result.stderr) };
+}
+
+function runSshCaptureSync(args: string[]): { exitCode: number | null; stdout: string; stderr: string } {
+	const result = Bun.spawnSync(["ssh", ...args], {
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	return {
+		exitCode: result.exitCode,
+		stdout: decodeOutput(result.stdout),
+		stderr: decodeOutput(result.stderr),
+	};
+}
+
+function ensureSshBinary(): void {
+	if (!Bun.which("ssh")) {
+		throw new Error("ssh binary not found on PATH");
+	}
+}
+
+function parseOs(value: unknown): SSHHostOs | null {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	switch (normalized) {
+		case "windows":
+			return "windows";
+		case "linux":
+			return "linux";
+		case "macos":
+		case "darwin":
+			return "macos";
+		case "unknown":
+			return "unknown";
+		default:
+			return null;
+	}
+}
+
+function parseShell(value: unknown): SSHHostShell | null {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	if (!normalized) return "unknown";
+	if (normalized.includes("bash")) return "bash";
+	if (normalized.includes("zsh")) return "zsh";
+	if (normalized.includes("pwsh") || normalized.includes("powershell")) return "powershell";
+	if (normalized.includes("cmd.exe") || normalized === "cmd") return "cmd";
+	if (normalized.endsWith("sh") || normalized.includes("/sh")) return "sh";
+	return "unknown";
+}
+
+function parseCompatShell(value: unknown): "bash" | "sh" | undefined {
+	if (value === "bash" || value === "sh") return value;
+	return undefined;
+}
+
+function applyCompatOverride(host: SSHConnectionTarget, info: SSHHostInfo): SSHHostInfo {
+	const compatShell =
+		info.compatShell ??
+		(info.os === "windows" && info.shell === "bash"
+			? "bash"
+			: info.os === "windows" && info.shell === "sh"
+				? "sh"
+				: undefined);
+	const compatEnabled = host.compat === false ? false : info.os === "windows" && compatShell !== undefined;
+	if (host.compat === true && !compatShell) {
+		logger.warn("SSH compat requested but no compatible shell detected", {
+			host: host.name,
+			shell: info.shell,
+		});
+	}
+	return { ...info, version: info.version ?? 0, compatShell, compatEnabled };
+}
+
+function parseHostInfo(value: unknown): SSHHostInfo | null {
+	if (!value || typeof value !== "object") return null;
+	const record = value as Record<string, unknown>;
+	const os = parseOs(record.os) ?? "unknown";
+	const shell = parseShell(record.shell) ?? "unknown";
+	const compatShell = parseCompatShell(record.compatShell);
+	const compatEnabled = typeof record.compatEnabled === "boolean" ? record.compatEnabled : false;
+	const version = typeof record.version === "number" ? record.version : 0;
+	return {
+		version,
+		os,
+		shell,
+		compatShell,
+		compatEnabled,
+	};
+}
+
+function shouldRefreshHostInfo(host: SSHConnectionTarget, info: SSHHostInfo): boolean {
+	if (info.version !== HOST_INFO_VERSION) return true;
+	if (info.os === "unknown") return true;
+	if (info.os !== "windows" && info.compatEnabled) return true;
+	if (info.os === "windows" && info.compatEnabled && !info.compatShell) return true;
+	if (info.os === "windows" && info.compatShell === "bash" && info.shell === "unknown") return true;
+	if (host.compat === true && info.os === "windows" && !info.compatShell) return true;
+	return false;
+}
+
+function loadHostInfoFromDisk(host: SSHConnectionTarget): SSHHostInfo | undefined {
+	const path = getHostInfoPath(host.name);
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = parseHostInfo(JSON.parse(raw));
+		if (!parsed) return undefined;
+		const resolved = applyCompatOverride(host, parsed);
+		hostInfoCache.set(host.name, resolved);
+		return resolved;
+	} catch (err) {
+		logger.warn("Failed to load SSH host info", { host: host.name, error: String(err) });
+		return undefined;
+	}
+}
+
+function loadHostInfoFromDiskByName(hostName: string): SSHHostInfo | undefined {
+	const path = getHostInfoPath(hostName);
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = parseHostInfo(JSON.parse(raw));
+		if (!parsed) return undefined;
+		return parsed;
+	} catch (err) {
+		logger.warn("Failed to load SSH host info", { host: hostName, error: String(err) });
+		return undefined;
+	}
+}
+
+async function persistHostInfo(host: SSHConnectionTarget, info: SSHHostInfo): Promise<void> {
+	try {
+		ensureHostInfoDir();
+		const path = getHostInfoPath(host.name);
+		const payload = { ...info, version: HOST_INFO_VERSION };
+		hostInfoCache.set(host.name, payload);
+		await Bun.write(path, JSON.stringify(payload, null, 2), { createPath: true });
+	} catch (err) {
+		logger.warn("Failed to persist SSH host info", { host: host.name, error: String(err) });
+	}
+}
+
+async function probeHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
+	const command = 'echo "$OSTYPE|$SHELL|$BASH_VERSION" 2>/dev/null || echo "%OS%|%COMSPEC%|"';
+	const result = runSshCaptureSync(buildRemoteCommand(host, command));
+	if (result.exitCode !== 0 && !result.stdout) {
+		logger.debug("SSH host probe failed", { host: host.name, error: result.stderr });
+		const fallback: SSHHostInfo = {
+			version: HOST_INFO_VERSION,
+			os: "unknown",
+			shell: "unknown",
+			compatShell: undefined,
+			compatEnabled: false,
+		};
+		hostInfoCache.set(host.name, fallback);
+		return fallback;
+	}
+
+	const output = (result.stdout || result.stderr).split("\n")[0]?.trim() ?? "";
+	const [rawOs = "", rawShell = "", rawBash = ""] = output.split("|");
+	const ostype = rawOs.trim();
+	const shellRaw = rawShell.trim();
+	const bashVersion = rawBash.trim();
+	const outputLower = output.toLowerCase();
+	const osLower = ostype.toLowerCase();
+	const shellLower = shellRaw.toLowerCase();
+	const unexpandedPosixVars =
+		output.includes("$OSTYPE") || output.includes("$SHELL") || output.includes("$BASH_VERSION");
+	const windowsDetected =
+		osLower.includes("windows") ||
+		osLower.includes("msys") ||
+		osLower.includes("cygwin") ||
+		osLower.includes("mingw") ||
+		outputLower.includes("windows_nt") ||
+		outputLower.includes("comspec") ||
+		shellLower.includes("cmd") ||
+		shellLower.includes("powershell") ||
+		unexpandedPosixVars ||
+		output.includes("%OS%");
+
+	let os: SSHHostOs = "unknown";
+	if (windowsDetected) {
+		os = "windows";
+	} else if (osLower.includes("darwin")) {
+		os = "macos";
+	} else if (osLower.includes("linux") || osLower.includes("gnu")) {
+		os = "linux";
+	}
+
+	let shell: SSHHostShell = "unknown";
+	if (shellLower.includes("bash")) {
+		shell = "bash";
+	} else if (shellLower.includes("zsh")) {
+		shell = "zsh";
+	} else if (shellLower.includes("pwsh") || shellLower.includes("powershell")) {
+		shell = "powershell";
+	} else if (shellLower.includes("cmd.exe") || shellLower === "cmd") {
+		shell = "cmd";
+	} else if (shellLower.endsWith("sh") || shellLower.includes("/sh")) {
+		shell = "sh";
+	} else if (os === "windows" && !shellLower) {
+		shell = "cmd";
+	}
+
+	const hasBash = !unexpandedPosixVars && (Boolean(bashVersion) || shell === "bash");
+	let compatShell: SSHHostInfo["compatShell"];
+	if (os === "windows" && host.compat !== false) {
+		const bashProbe = runSshCaptureSync(buildRemoteCommand(host, 'bash -lc "echo OMP_BASH_OK"'));
+		if (bashProbe.exitCode === 0 && bashProbe.stdout.includes("OMP_BASH_OK")) {
+			compatShell = "bash";
+		} else {
+			const shProbe = runSshCaptureSync(buildRemoteCommand(host, 'sh -lc "echo OMP_SH_OK"'));
+			if (shProbe.exitCode === 0 && shProbe.stdout.includes("OMP_SH_OK")) {
+				compatShell = "sh";
+			}
+		}
+	} else if (os === "windows" && hasBash) {
+		compatShell = "bash";
+	} else if (os === "windows" && shell === "sh") {
+		compatShell = "sh";
+	}
+	const compatEnabled = host.compat === false ? false : os === "windows" && compatShell !== undefined;
+
+	const info: SSHHostInfo = applyCompatOverride(host, {
+		version: HOST_INFO_VERSION,
+		os,
+		shell,
+		compatShell,
+		compatEnabled,
+	});
+
+	hostInfoCache.set(host.name, info);
+	await persistHostInfo(host, info);
+	return info;
+}
+
+export function getHostInfo(hostName: string): SSHHostInfo | undefined {
+	return hostInfoCache.get(hostName) ?? loadHostInfoFromDiskByName(hostName);
+}
+
+export function getHostInfoForHost(host: SSHConnectionTarget): SSHHostInfo | undefined {
+	const cached = hostInfoCache.get(host.name);
+	if (cached) {
+		const resolved = applyCompatOverride(host, cached);
+		if (resolved !== cached) hostInfoCache.set(host.name, resolved);
+		return resolved;
+	}
+	return loadHostInfoFromDisk(host);
+}
+
+export async function ensureHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
+	const cached = hostInfoCache.get(host.name);
+	if (cached) {
+		const resolved = applyCompatOverride(host, cached);
+		hostInfoCache.set(host.name, resolved);
+		if (!shouldRefreshHostInfo(host, resolved)) return resolved;
+	}
+	const fromDisk = loadHostInfoFromDisk(host);
+	if (fromDisk && !shouldRefreshHostInfo(host, fromDisk)) return fromDisk;
+	await ensureConnection(host);
+	const current = hostInfoCache.get(host.name);
+	if (current && !shouldRefreshHostInfo(host, current)) return current;
+	return probeHostInfo(host);
+}
+
+export function buildRemoteCommand(host: SSHConnectionTarget, command: string): string[] {
+	validateKeyPermissions(host.keyPath);
+	return [...buildCommonArgs(host), buildSshTarget(host), command];
+}
+
+export async function ensureConnection(host: SSHConnectionTarget): Promise<void> {
+	const key = host.name;
+	const pending = pendingConnections.get(key);
+	if (pending) {
+		await pending;
+		return;
+	}
+
+	const promise = (async () => {
+		ensureSshBinary();
+		ensureControlDir();
+		validateKeyPermissions(host.keyPath);
+
+		const target = buildSshTarget(host);
+		const check = runSshSync(["-O", "check", ...buildCommonArgs(host), target]);
+		if (check.exitCode === 0) {
+			activeHosts.set(key, host);
+			if (!hostInfoCache.has(key) && !loadHostInfoFromDisk(host)) {
+				await probeHostInfo(host);
+			}
+			return;
+		}
+
+		const start = runSshSync(["-M", "-N", "-f", ...buildCommonArgs(host), target]);
+		if (start.exitCode !== 0) {
+			const detail = start.stderr ? `: ${start.stderr}` : "";
+			throw new Error(`Failed to start SSH master for ${target}${detail}`);
+		}
+
+		activeHosts.set(key, host);
+		if (!hostInfoCache.has(key) && !loadHostInfoFromDisk(host)) {
+			await probeHostInfo(host);
+		}
+	})();
+
+	pendingConnections.set(key, promise);
+	try {
+		await promise;
+	} finally {
+		pendingConnections.delete(key);
+	}
+}
+
+function closeConnectionInternal(host: SSHConnectionTarget): void {
+	const target = buildSshTarget(host);
+	runSshSync(["-O", "exit", ...buildCommonArgs(host), target]);
+}
+
+export async function closeConnection(hostName: string): Promise<void> {
+	const host = activeHosts.get(hostName);
+	if (!host) {
+		closeConnectionInternal({ name: hostName, host: hostName });
+		return;
+	}
+	closeConnectionInternal(host);
+	activeHosts.delete(hostName);
+}
+
+export async function closeAllConnections(): Promise<void> {
+	for (const [name, host] of Array.from(activeHosts.entries())) {
+		closeConnectionInternal(host);
+		activeHosts.delete(name);
+	}
+}
+
+export function getControlPathTemplate(): string {
+	return CONTROL_PATH;
+}
+
+export function getControlDir(): string {
+	return CONTROL_DIR;
+}