@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

package/src/slash-commands/helpers/usage-report.ts

@@ -0,0 +1,162 @@
+import type { UsageLimit, UsageReport } from "@oh-my-pi-zen/pi-ai";
+import { sanitizeText } from "@oh-my-pi-zen/pi-utils";
+import type { OAuthAccountIdentity } from "../../session/auth-storage";
+import type { SlashCommandRuntime } from "../types";
+import { reportMatchesActiveAccount } from "./active-oauth-account";
+import { formatDuration, renderAsciiBar } from "./format";
+
+function formatProviderName(provider: string): string {
+	return provider
+		.split(/[-_]/g)
+		.map(part => (part ? part[0].toUpperCase() + part.slice(1) : ""))
+		.join(" ");
+}
+
+function formatUsageAmount(limit: UsageLimit): string {
+	const amount = limit.amount;
+	const used = amount.used ?? (amount.usedFraction !== undefined ? amount.usedFraction * 100 : undefined);
+	const remainingFraction =
+		amount.remainingFraction ??
+		(amount.usedFraction !== undefined ? Math.max(0, 1 - amount.usedFraction) : undefined);
+	const unit = amount.unit === "percent" ? "%" : ` ${amount.unit}`;
+	const usedText = used === undefined ? "unknown used" : `${used.toFixed(2)}${unit} used`;
+	const remainingText = remainingFraction === undefined ? "" : ` (${(remainingFraction * 100).toFixed(1)}% left)`;
+	return `${usedText}${remainingText}`;
+}
+
+function formatUsageReportAccount(report: UsageReport, limit: UsageLimit, index: number): string {
+	const email = report.metadata?.email;
+	if (typeof email === "string" && email) return email;
+	// Guard metadata values for truthiness before using, then fall back to scope.
+	// ?? won't help here: empty string is not null/undefined, so it would suppress
+	// a valid scoped fallback (e.g. metadata.accountId="" hides limit.scope.accountId).
+	const metaAccountId = report.metadata?.accountId;
+	const accountId = typeof metaAccountId === "string" && metaAccountId ? metaAccountId : limit.scope.accountId;
+	if (typeof accountId === "string" && accountId) return accountId;
+	const metaProjectId = report.metadata?.projectId;
+	const projectId = typeof metaProjectId === "string" && metaProjectId ? metaProjectId : limit.scope.projectId;
+	if (typeof projectId === "string" && projectId) return projectId;
+	return `account ${index + 1}`;
+}
+
+function renderUsageReports(
+	reports: UsageReport[],
+	nowMs: number,
+	resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined,
+): string {
+	const latestFetchedAt = Math.max(...reports.map(report => report.fetchedAt ?? 0));
+	const lines = [`Usage${latestFetchedAt ? ` (${formatDuration(nowMs - latestFetchedAt)} ago)` : ""}`];
+	const grouped = new Map<string, UsageReport[]>();
+	for (const report of reports) {
+		const providerReports = grouped.get(report.provider) ?? [];
+		providerReports.push(report);
+		grouped.set(report.provider, providerReports);
+	}
+
+	for (const [provider, providerReports] of [...grouped.entries()].sort(([left], [right]) =>
+		left.localeCompare(right),
+	)) {
+		lines.push("", formatProviderName(provider));
+		const activeAccount = resolveActiveAccount?.(provider);
+		// Provider-wide disclaimers render once per provider, not per limit.
+		const providerNotes = [...new Set(providerReports.flatMap(report => report.notes ?? []))];
+		for (const note of providerNotes)
+			lines.push(`  ${sanitizeText(note.replace(/[\r\n]+/g, " ").replace(/\t/g, "  "))}`);
+		for (const report of providerReports) {
+			const inUse = reportMatchesActiveAccount(report, activeAccount);
+			const savedResets = report.resetCredits?.availableCount ?? 0;
+			if (savedResets > 0) {
+				const resetLabel =
+					typeof report.metadata?.email === "string"
+						? report.metadata.email
+						: typeof report.metadata?.accountId === "string"
+							? report.metadata.accountId
+							: "account";
+				lines.push(
+					`- ${resetLabel}: ${savedResets} saved rate-limit reset${savedResets === 1 ? "" : "s"} available — /usage reset to spend`,
+				);
+				const credits = report.resetCredits?.credits;
+				if (credits) {
+					for (const credit of credits) {
+						if (credit.expiresAt) {
+							const expiryMs = Date.parse(credit.expiresAt);
+							if (!Number.isNaN(expiryMs)) {
+								const remaining = expiryMs - nowMs;
+								if (remaining > 0) {
+									lines.push(`  expires in ${formatDuration(remaining)} (${credit.expiresAt.slice(0, 10)})`);
+								} else {
+									lines.push(`  expired (${credit.expiresAt.slice(0, 10)})`);
+								}
+							}
+						}
+					}
+				}
+			}
+			if (report.limits.length === 0) {
+				const email = typeof report.metadata?.email === "string" ? report.metadata.email : "account";
+				lines.push(`- ${email}: no limits reported`);
+				continue;
+			}
+			for (let index = 0; index < report.limits.length; index++) {
+				const limit = report.limits[index]!;
+				const window = limit.window?.label ?? limit.scope.windowId;
+				// Skip the tier suffix when the label already names it (e.g. Anthropic's
+				// "Claude 7 Day (Fable)" with scope.tier "fable") — mirrors limitTitle in usage-cli.
+				const tier =
+					limit.scope.tier && !limit.label.toLowerCase().includes(limit.scope.tier.toLowerCase())
+						? ` (${limit.scope.tier})`
+						: "";
+				lines.push(`- ${limit.label}${tier}${window ? ` — ${window}` : ""}`);
+				lines.push(
+					`  ${formatUsageReportAccount(report, limit, index)}: ${formatUsageAmount(limit)}${inUse ? "  ← in use by this session" : ""}`,
+				);
+				lines.push(`  ${renderAsciiBar(limit.amount.usedFraction)}`);
+				if (limit.window?.resetsAt && limit.window.resetsAt > nowMs) {
+					lines.push(`  resets in ${formatDuration(limit.window.resetsAt - nowMs)}`);
+				}
+				if (limit.notes && limit.notes.length > 0)
+					lines.push(
+						`  ${limit.notes.map(n => sanitizeText(n.replace(/[\r\n]+/g, " ").replace(/\t/g, "  "))).join(" • ")}`,
+					);
+			}
+		}
+	}
+	return ["```", ...lines, "```"].join("\n");
+}
+
+/**
+ * Build the `/usage` ACP-mode text. Prefers provider-reported limits when the
+ * session exposes `fetchUsageReports`; otherwise falls back to the local
+ * session-manager tallies.
+ */
+export async function buildUsageReportText(runtime: SlashCommandRuntime): Promise<string> {
+	const provider = runtime.session as SlashCommandRuntime["session"] & {
+		fetchUsageReports?: () => Promise<UsageReport[] | null>;
+	};
+	if (provider.fetchUsageReports) {
+		const reports = await provider.fetchUsageReports();
+		if (reports && reports.length > 0) {
+			const currentProvider = runtime.session.model?.provider;
+			const activeAccount = currentProvider
+				? runtime.session.modelRegistry.authStorage.getOAuthAccountIdentity(
+						currentProvider,
+						runtime.session.sessionId,
+					)
+				: undefined;
+			return renderUsageReports(reports, Date.now(), providerId =>
+				providerId === currentProvider ? activeAccount : undefined,
+			);
+		}
+	}
+
+	const stats = runtime.session.sessionManager.getUsageStatistics();
+	return [
+		"Usage",
+		`Input tokens: ${stats.input}`,
+		`Output tokens: ${stats.output}`,
+		`Cache read tokens: ${stats.cacheRead}`,
+		`Cache write tokens: ${stats.cacheWrite}`,
+		`Premium requests: ${stats.premiumRequests}`,
+		`Cost: $${stats.cost.toFixed(6)}`,
+	].join("\n");
+}

package/src/slash-commands/marketplace-install-parser.ts

@@ -0,0 +1,99 @@
+const USAGE = "Usage: /marketplace install [--force] [--scope user|project] <name@marketplace>";
+
+export interface MarketplaceInstallArgs {
+	force: boolean;
+	scope: "user" | "project";
+	installSpec: string;
+}
+
+/**
+ * Parse the argument string following `/marketplace install`.
+ *
+ * Returns either the parsed args or an `{ error }` object whose message is
+ * suitable for direct display to the user via `ctx.showStatus`.
+ *
+ * Accepted flags (any order):
+ *   --force                 Force-reinstall even if already installed
+ *   --scope user|project    Installation scope (default: user)
+ *
+ * Exactly one positional argument is required: `name@marketplace`.
+ */
+export function parseMarketplaceInstallArgs(rest: string): MarketplaceInstallArgs | { error: string } {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let force = false;
+	let scope: "user" | "project" = "user";
+	let installSpec = "";
+
+	for (let i = 0; i < tokens.length; i++) {
+		if (tokens[i] === "--force") {
+			force = true;
+		} else if (tokens[i] === "--scope" && i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+			const s = tokens[++i];
+			if (s === "user" || s === "project") {
+				scope = s;
+			} else {
+				return { error: `Invalid --scope value: "${s}". Must be "user" or "project".` };
+			}
+		} else if (tokens[i] === "--scope") {
+			// --scope with no value, or next token is another flag
+			return { error: '--scope requires a value: "user" or "project".' };
+		} else if (tokens[i].startsWith("-")) {
+			return { error: `Unknown flag: "${tokens[i]}". ${USAGE}` };
+		} else {
+			if (installSpec) {
+				return { error: `Unexpected argument: "${tokens[i]}". ${USAGE}` };
+			}
+			installSpec = tokens[i];
+		}
+	}
+
+	if (!installSpec.includes("@")) {
+		return { error: USAGE };
+	}
+
+	return { force, scope, installSpec };
+}
+
+// ── Shared scope+id parser for uninstall / upgrade / enable / disable ───────
+
+export interface PluginScopeArgs {
+	pluginId: string;
+	scope?: "user" | "project";
+}
+
+/**
+ * Parse `[--scope user|project] <name@marketplace>` for commands that accept a
+ * single plugin ID and an optional scope flag.
+ *
+ * Returns parsed args or `{ error }` ready for `ctx.showStatus`.
+ */
+export function parsePluginScopeArgs(rest: string, usageHint: string): PluginScopeArgs | { error: string } {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let scope: "user" | "project" | undefined;
+	let pluginId = "";
+
+	for (let i = 0; i < tokens.length; i++) {
+		if (tokens[i] === "--scope" && i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+			const s = tokens[++i];
+			if (s === "user" || s === "project") {
+				scope = s;
+			} else {
+				return { error: `Invalid --scope value: "${s}". Must be "user" or "project".` };
+			}
+		} else if (tokens[i] === "--scope") {
+			return { error: '--scope requires a value: "user" or "project".' };
+		} else if (tokens[i].startsWith("-")) {
+			return { error: `Unknown flag: "${tokens[i]}". ${usageHint}` };
+		} else if (pluginId) {
+			return { error: `Unexpected argument: "${tokens[i]}". ${usageHint}` };
+		} else {
+			pluginId = tokens[i];
+		}
+	}
+
+	if (!pluginId) {
+		return { error: usageHint };
+	}
+
+	return { pluginId, scope };
+}

package/src/slash-commands/types.ts

@@ -0,0 +1,137 @@
+import type { Settings } from "../config/settings";
+import type { InteractiveModeContext } from "../modes/types";
+import type { AgentSession } from "../session/agent-session";
+import type { SessionManager } from "../session/session-manager";
+
+/** Declarative subcommand definition for commands like /mcp. */
+export interface SubcommandDef {
+	name: string;
+	description: string;
+	/** Usage hint shown as dim ghost text, e.g. "<name> [--scope project|user]". */
+	usage?: string;
+}
+
+/** Declarative builtin slash command metadata used by autocomplete and help UI. */
+export interface BuiltinSlashCommand {
+	name: string;
+	aliases?: string[];
+	description: string;
+	/** Subcommands for dropdown completion (e.g. /mcp add, /mcp list). */
+	subcommands?: SubcommandDef[];
+	/** Static inline hint when command takes a simple argument (no subcommands). */
+	inlineHint?: string;
+	/** TUI-only dynamic status text for command-name autocomplete. Static `description` remains canonical for ACP/help. */
+	getTuiAutocompleteDescription?: (runtime: TuiSlashCommandRuntime) => string | undefined;
+}
+
+/** Parsed slash-command text after stripping the leading "/". */
+export interface ParsedSlashCommand {
+	name: string;
+	args: string;
+	text: string;
+}
+
+/**
+ * Result returned by a slash-command handler.
+ *
+ * - `undefined` (and the implicit `void` return) — command was handled and
+ *   consumed; no further input. Handlers may simply omit a `return` rather than
+ *   building `{ consumed: true }`; `void` is accepted in the handler signatures
+ *   below so the contract typechecks under TypeScript 5.x (which does not
+ *   coerce `() => void` to `() => T | undefined`) as well as 6.x / tsgo.
+ * - `{ consumed: true }` — explicit equivalent of the above (ACP shape).
+ * - `{ prompt: string }` — command handled, pass `prompt` through as the new
+ *   user input (e.g. `/force <tool> <prompt>` keeps `<prompt>` as the message).
+ */
+export type SlashCommandResult = undefined | { consumed: true } | { prompt: string };
+
+/**
+ * Runtime visible to slash-command handlers that run in text/ACP mode.
+ *
+ * Both the TUI dispatcher (when invoking a `handle` via its adapter) and the
+ * ACP dispatcher pass this shape. Implementations MUST NOT depend on TUI-only
+ * state (editor, selectors, status line).
+ */
+export interface SlashCommandRuntime {
+	session: AgentSession;
+	sessionManager: SessionManager;
+	settings: Settings;
+	cwd: string;
+	/** Emit text to the operator. TUI maps to `ctx.showStatus`, ACP to `sessionUpdate`. */
+	output: (text: string) => Promise<void> | void;
+	/** Re-advertise the available command list (no-op outside ACP). */
+	refreshCommands: () => Promise<void> | void;
+	/**
+	 * Reload plugin state (caches, slash command registry, project registries)
+	 * and re-emit available commands. Used by `/reload-plugins`, `/move`, and
+	 * `/marketplace`/`/plugins` mutations so the session sees a consistent view
+	 * after plugin or project-scope changes.
+	 */
+	reloadPlugins: () => Promise<void>;
+	notifyTitleChanged?: () => Promise<void> | void;
+	notifyConfigChanged?: () => Promise<void> | void;
+}
+
+/**
+ * Runtime visible to TUI-only handlers (`handleTui`). Carries the interactive
+ * mode context. Intentionally narrower than `SlashCommandRuntime` so existing
+ * callers can keep building it from just `{ ctx }`; when the TUI dispatcher
+ * needs to invoke a `handle` (no `handleTui` override), it synthesizes a
+ * `SlashCommandRuntime` from `ctx`.
+ */
+export interface TuiSlashCommandRuntime {
+	ctx: InteractiveModeContext;
+}
+
+/** Unified slash-command spec consumed by both TUI and ACP dispatchers. */
+export interface SlashCommandSpec extends BuiltinSlashCommand {
+	/** When false, the dispatcher refuses to handle invocations that include arguments. */
+	allowArgs?: boolean;
+	/**
+	 * ACP-specific override for `description`. Used by `ACP_BUILTIN_SLASH_COMMANDS`
+	 * when building `available_commands_update` payloads so the client receives
+	 * mode-appropriate copy (e.g. `/dump` advertises "Return full transcript as
+	 * plain text" in ACP rather than the TUI's clipboard-centric copy).
+	 */
+	acpDescription?: string;
+	/**
+	 * ACP-specific override for the advertised input hint. `subcommands`-only
+	 * specs that historically advertised `<subcommand>` / `[on|off|status]` /
+	 * `info|delete` to ACP clients carry the hint here so the unification does
+	 * not silently drop it from `available_commands_update`.
+	 */
+	acpInputHint?: string;
+	/**
+	 * Text/ACP-mode handler. The same body is invoked from the ACP dispatcher
+	 * and, via the TUI adapter, when no `handleTui` override is provided.
+	 *
+	 * Expressed as a union of two function types — one returning a
+	 * `SlashCommandResult`, one returning `void` — so handlers that simply
+	 * `return` (or omit the return) typecheck under TypeScript 5.x as well as
+	 * 6.x / tsgo. TS 5.x does not coerce a `() => void` value into a
+	 * `() => T | undefined` slot, so the two return shapes must be siblings
+	 * rather than a `T | void` union inside one function type (which Biome's
+	 * `noConfusingVoidType` also rejects).
+	 */
+	handle?:
+		| ((
+				command: ParsedSlashCommand,
+				runtime: SlashCommandRuntime,
+		  ) => SlashCommandResult | Promise<SlashCommandResult>)
+		| ((command: ParsedSlashCommand, runtime: SlashCommandRuntime) => void | Promise<void>);
+	/**
+	 * TUI-only handler that supersedes `handle` when both are present. Use for
+	 * selectors, wizards, dashboards, and anything else that requires
+	 * `InteractiveModeContext`. See `handle` for the rationale behind the
+	 * function-type union shape.
+	 */
+	handleTui?:
+		| ((
+				command: ParsedSlashCommand,
+				runtime: TuiSlashCommandRuntime,
+		  ) => SlashCommandResult | Promise<SlashCommandResult>)
+		| ((command: ParsedSlashCommand, runtime: TuiSlashCommandRuntime) => void | Promise<void>);
+}
+
+/** Result returned by `executeAcpBuiltinSlashCommand`. */
+export type AcpBuiltinSlashCommandResult = false | { consumed: true } | { prompt: string };

package/src/ssh/__tests__/connection-manager-args.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getRemoteHostDir } from "@oh-my-pi-zen/pi-utils";
+import {
+	buildRemoteCommand,
+	extractProbePayload,
+	findProbeMarker,
+	getHostInfo,
+	HOST_PROBE_MARKER,
+	osFromUname,
+	parseHostInfo,
+	type SSHConnectionTarget,
+	type SSHHostShell,
+	TRANSFER_PROBE_MARKER,
+} from "../connection-manager";
+import { buildSshTarget, sanitizeHostName } from "../utils";
+
+const TARGET: SSHConnectionTarget = { name: "h", host: "h" };
+
+describe("buildRemoteCommand stdin handling", () => {
+	it("includes -n by default so ssh reads stdin from /dev/null", async () => {
+		const args = await buildRemoteCommand(TARGET, "cat");
+		expect(args).toContain("-n");
+	});
+
+	it("omits -n when allowStdin is set so the remote command reads piped stdin", async () => {
+		const args = await buildRemoteCommand(TARGET, "cat", { allowStdin: true });
+		expect(args).not.toContain("-n");
+	});
+});
+
+describe("buildSshTarget argument-injection guard", () => {
+	it("rejects a host that begins with '-' (ssh would parse it as an option)", () => {
+		expect(() => buildSshTarget(undefined, "-oProxyCommand=touch /tmp/pwned")).toThrow(/must not begin with/);
+	});
+
+	it("rejects a username that begins with '-'", () => {
+		expect(() => buildSshTarget("-oProxyCommand=x", "host")).toThrow(/must not begin with/);
+	});
+
+	it("renders a normal destination unchanged", () => {
+		expect(buildSshTarget("user", "host")).toBe("user@host");
+		expect(buildSshTarget(undefined, "host")).toBe("host");
+	});
+
+	it("rejects a dash-leading host through the real buildRemoteCommand path", async () => {
+		await expect(buildRemoteCommand({ name: "x", host: "-oProxyCommand=x" }, "cat")).rejects.toThrow(
+			/must not begin with/,
+		);
+	});
+});
+
+describe("ssh host shell classification", () => {
+	it("treats fish/csh/tcsh as non-POSIX (unknown) and keeps real sh-family as sh", async () => {
+		// parseHostInfo re-runs parseShell on the stored shell field, so getHostInfo
+		// exercises the classifier through a public seam. The ensurePosixRemote
+		// whitelist then refuses anything that isn't sh/bash/zsh.
+		const cases: Array<[string, SSHHostShell]> = [
+			["/usr/bin/fish", "unknown"],
+			["/bin/csh", "unknown"],
+			["/bin/tcsh", "unknown"],
+			["/bin/dash", "sh"],
+			["/bin/sh", "sh"],
+			["/usr/bin/bash", "bash"],
+			["/usr/bin/zsh", "zsh"],
+		];
+		for (const [shellValue, expected] of cases) {
+			const name = `omp-shellclf-${crypto.randomUUID()}`;
+			const file = path.join(getRemoteHostDir(), `${sanitizeHostName(name)}.json`);
+			await Bun.write(file, JSON.stringify({ version: 3, os: "linux", shell: shellValue, compatEnabled: false }));
+			try {
+				const info = await getHostInfo(name);
+				expect(info?.shell).toBe(expected);
+			} finally {
+				await fs.promises.rm(file, { force: true });
+			}
+		}
+	});
+});
+
+describe("extractProbePayload (host probe framing)", () => {
+	it("returns the text after the first marker line, ignoring login banners", async () => {
+		// Real-world failure shape: noisy dotfiles print a banner before the
+		// echo we asked for, so the legacy first-line parser would have read
+		// `Last login: ...` and classified the host as unknown (#3719).
+		const stdout = [
+			"Last login: Wed Mar 19 09:14:22 2025 from 10.0.0.1",
+			"Welcome to fancybox 1.0",
+			`${HOST_PROBE_MARKER}linux-gnu|/bin/bash|5.2.21`,
+		].join("\n");
+		expect(extractProbePayload(stdout, "")).toBe("linux-gnu|/bin/bash|5.2.21");
+	});
+
+	it("falls back to stderr when the payload only shows up there", async () => {
+		// Some shells redirect every echo to stderr after a dotfile error; the
+		// parser needs to recover the marker line from either stream.
+		const stderr = `noise\n${HOST_PROBE_MARKER}darwin|/bin/zsh|\n`;
+		expect(extractProbePayload("", stderr)).toBe("darwin|/bin/zsh|");
+	});
+
+	it("returns null when no marker line is present", async () => {
+		expect(extractProbePayload("just login banner\n", "and stderr noise\n")).toBeNull();
+	});
+});
+
+describe("findProbeMarker (transfer-shell probe recovery)", () => {
+	it("returns the tail after the marker when it appears in stdout", () => {
+		// Happy path: `sh -lc 'printf "PI_TRANSFER_OK|"; uname -s'` lands in
+		// stdout. The tail is the uname output the caller uses to refine OS.
+		const stdout = `${TRANSFER_PROBE_MARKER}Linux\n`;
+		expect(findProbeMarker(stdout, "", TRANSFER_PROBE_MARKER)).toBe("Linux\n");
+	});
+
+	it("falls back to stderr when a broken dotfile swaps fd 1/2", () => {
+		// Some remotes have dotfiles that redirect every shell write to stderr.
+		// The transfer probe must still recognize the marker so ssh:// doesn't
+		// refuse a POSIX-capable host (#3722 review).
+		const stderr = `dotfile noise\n${TRANSFER_PROBE_MARKER}Darwin\n`;
+		expect(findProbeMarker("", stderr, TRANSFER_PROBE_MARKER)).toBe("Darwin\n");
+	});
+
+	it("prefers stdout over stderr when the marker is in both", () => {
+		// Order matters: stdout is the canonical path, stderr is the rescue.
+		// A reordering bug would silently use stale stderr fragments first.
+		const stdout = `${TRANSFER_PROBE_MARKER}Linux`;
+		const stderr = `${TRANSFER_PROBE_MARKER}stale`;
+		expect(findProbeMarker(stdout, stderr, TRANSFER_PROBE_MARKER)).toBe("Linux");
+	});
+
+	it("returns null when the marker is in neither stream", () => {
+		expect(findProbeMarker("noise", "more noise", TRANSFER_PROBE_MARKER)).toBeNull();
+	});
+});
+
+describe("osFromUname (transfer-shell probe OS recovery)", () => {
+	it("classifies common POSIX uname payloads", () => {
+		// The markerless host-info fallback uses the transfer-shell probe's
+		// uname output to avoid returning a durable `os: "unknown"` when csh/tcsh
+		// killed the first marker probe before it could echo anything (#3722 review).
+		expect(osFromUname("Linux")).toBe("linux");
+		expect(osFromUname("GNU/Linux")).toBe("linux");
+		expect(osFromUname("Darwin")).toBe("macos");
+	});
+
+	it("classifies Windows compat unames as windows so ssh:// still refuses them", () => {
+		expect(osFromUname("MINGW64_NT-10.0")).toBe("windows");
+		expect(osFromUname("MSYS_NT-10.0")).toBe("windows");
+		expect(osFromUname("CYGWIN_NT-10.0")).toBe("windows");
+	});
+
+	it("returns undefined when uname is not recognized", () => {
+		expect(osFromUname("")).toBeUndefined();
+		expect(osFromUname("SunOS")).toBeUndefined();
+	});
+});
+
+describe("parseHostInfo transferShell handling", () => {
+	it("round-trips a verified transferShell value", () => {
+		// Cache writers persist `transferShell` so callers don't re-probe
+		// every session; parseHostInfo must thread it back through (#3719).
+		const parsed = parseHostInfo({
+			version: 4,
+			os: "linux",
+			shell: "unknown",
+			transferShell: "bash",
+			compatEnabled: false,
+		});
+		expect(parsed?.transferShell).toBe("bash");
+	});
+
+	it("drops a transferShell value outside the sh/bash/zsh allowlist", () => {
+		// Anything we couldn't have probed (fish, csh, garbage) must not slip
+		// into the cache and bypass the ssh:// transfer guard.
+		const parsed = parseHostInfo({
+			version: 4,
+			os: "linux",
+			shell: "sh",
+			transferShell: "fish",
+			compatEnabled: false,
+		});
+		expect(parsed?.transferShell).toBeUndefined();
+	});
+
+	it("returns transferShell undefined when the field is missing", () => {
+		// A pre-v4 cache file lacks transferShell entirely; the parsed value
+		// must be undefined so shouldRefreshHostInfo treats it as stale.
+		const parsed = parseHostInfo({ version: 3, os: "linux", shell: "sh", compatEnabled: false });
+		expect(parsed?.transferShell).toBeUndefined();
+	});
+});

package/src/ssh/__tests__/connection-manager-timeout.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Regression for #4232: `runSshSync` / `runSshCaptureSync` sit on the
+ * `ensureHostInfo` → `probeHostInfo` / `ensureConnection` path that runs before
+ * `SshTool.execute` applies the user's command timeout. Previously they invoked
+ * `ssh` through `$`ssh ${args}`.quiet().nothrow()` with no timeout and no
+ * abort signal, so an unreachable host or wedged control-master hung forever.
+ *
+ * The contract now is: each helper is bounded by `timeoutMs`, aborts a stalled
+ * child, and returns a failure result (`exitCode !== 0`, non-empty
+ * `stderr`) instead of throwing or blocking.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { _sshHelpersForTests } from "../connection-manager";
+
+const { runSshSync, runSshCaptureSync } = _sshHelpersForTests;
+
+let binDir: string;
+let originalPath: string | undefined;
+
+beforeAll(async () => {
+	binDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-ssh-timeout-"));
+	// Fake `ssh` that traps SIGTERM and sleeps far past any test bound.
+	// Simulates a wedged control-master / unreachable host.
+	const fake = path.join(binDir, "ssh");
+	await fs.writeFile(fake, "#!/usr/bin/env bash\ntrap '' TERM\nsleep 300\n", { mode: 0o755 });
+	originalPath = process.env.PATH;
+	process.env.PATH = `${binDir}${path.delimiter}${originalPath ?? ""}`;
+});
+
+afterAll(async () => {
+	if (originalPath === undefined) delete process.env.PATH;
+	else process.env.PATH = originalPath;
+	await fs.rm(binDir, { recursive: true, force: true });
+});
+
+describe("SSH pre-command helpers bound their own runtime (#4232)", () => {
+	it("runSshSync returns a failure result within the timeout on a wedged host", async () => {
+		const timeoutMs = 200;
+		const started = Date.now();
+		const result = await runSshSync(["-o", "BatchMode=yes", "unreachable", "true"], timeoutMs);
+		const elapsed = Date.now() - started;
+
+		expect(elapsed).toBeLessThan(5_000);
+		// timeout → aborted child, so exit code is null (aborted) or non-zero.
+		expect(result.exitCode).not.toBe(0);
+	}, 10_000);
+
+	it("runSshCaptureSync returns a failure result within the timeout on a wedged host", async () => {
+		const timeoutMs = 200;
+		const started = Date.now();
+		const result = await runSshCaptureSync(["-o", "BatchMode=yes", "unreachable", "true"], timeoutMs);
+		const elapsed = Date.now() - started;
+
+		expect(elapsed).toBeLessThan(5_000);
+		expect(result.exitCode).not.toBe(0);
+		expect(result.stdout).toBe("");
+	}, 10_000);
+});