@oh-my-pi/pi-coding-agent 16.2.2 → 16.2.4

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

@@ -2,7 +2,18 @@ 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/pi-utils";
-import { buildRemoteCommand, getHostInfo, type SSHConnectionTarget, type SSHHostShell } from "../connection-manager";
+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" };
@@ -67,3 +78,114 @@ describe("ssh host shell classification", () => {
 		}
 	});
 });
+
+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__/file-transfer-posix-guard.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "bun:test";
 import type { SSHConnectionTarget } from "../connection-manager";
 import * as connectionManager from "../connection-manager";
-import { readRemoteFile, writeRemoteFile } from "../file-transfer";
+import { listRemoteDir, readRemoteFile, statRemotePath, writeRemoteFile } from "../file-transfer";
 
 describe("ssh file-transfer POSIX guard", () => {
 	afterEach(() => {
@@ -13,7 +13,7 @@ describe("ssh file-transfer POSIX guard", () => {
 		// without opening a real SSH connection and before any command is spawned.
 		const ensureConnectionSpy = vi.spyOn(connectionManager, "ensureConnection").mockResolvedValue(undefined);
 		const ensureHostInfoSpy = vi.spyOn(connectionManager, "ensureHostInfo").mockResolvedValue({
-			version: 2,
+			version: 4,
 			os: "windows",
 			shell: "powershell",
 			compatEnabled: false,
@@ -27,42 +27,79 @@ describe("ssh file-transfer POSIX guard", () => {
 		expect(ensureHostInfoSpy).toHaveBeenCalled();
 	});
 
-	it("rejects a non-POSIX login shell (csh/tcsh/fish classify as non-sh) before any transfer", async () => {
-		// csh/tcsh history-expand `!`, and fish can't parse our POSIX source; all
-		// classify as a non-sh shell, so the guard must refuse them before any spawn.
+	it("rejects a non-Windows remote with no verified transferShell", async () => {
+		// No transferShell means the capability probe never confirmed any of
+		// sh/bash/zsh works. The guard refuses regardless of `shell` because the
+		// real ssh:// contract is "did we verify a POSIX shell works", not
+		// "what name did the login shell self-report" (#3719).
 		vi.spyOn(connectionManager, "ensureConnection").mockResolvedValue(undefined);
 		vi.spyOn(connectionManager, "ensureHostInfo").mockResolvedValue({
-			version: 3,
+			version: 4,
 			os: "linux",
 			shell: "unknown",
 			compatEnabled: false,
 		});
-		const target: SSHConnectionTarget = { name: "fishbox", host: "fishbox" };
-		await expect(readRemoteFile(target, "/etc/hosts", { maxBytes: 1024 })).rejects.toThrow(/non-POSIX login shell/);
-		await expect(writeRemoteFile(target, "/tmp/x", new Uint8Array([1]), {})).rejects.toThrow(/non-POSIX login shell/);
+		const target: SSHConnectionTarget = { name: "noshell", host: "noshell" };
+		await expect(readRemoteFile(target, "/etc/hosts", { maxBytes: 1024 })).rejects.toThrow(/no verified POSIX shell/);
+		await expect(writeRemoteFile(target, "/tmp/x", new Uint8Array([1]), {})).rejects.toThrow(
+			/no verified POSIX shell/,
+		);
 	});
 
-	it("allows a POSIX login shell (sh/bash/zsh) to run the transfer commands directly", async () => {
-		// A POSIX login shell runs our snippets verbatim; the guard must let it through.
-		// Reject at buildRemoteCommand to capture the command before any real ssh spawn.
+	it("dispatches transfer commands through the verified transferShell, not the login shell", async () => {
+		// The bug fix: if the login shell is fish/csh/tcsh, the legacy guard
+		// would refuse the host — but allowing it isn't enough on its own.
+		// OpenSSH still hands our snippets to `$SHELL -c`, so a fish login
+		// shell would choke on `if [ … ]; then …`. Every transfer command
+		// must be wrapped in `<transferShell> -c '…'` to force parsing
+		// under the shell we verified can run it (#3719).
 		vi.spyOn(connectionManager, "ensureConnection").mockResolvedValue(undefined);
 		vi.spyOn(connectionManager, "ensureHostInfo").mockResolvedValue({
-			version: 3,
+			version: 4,
 			os: "linux",
-			shell: "sh",
+			// Login shell is fish; only `transferShell` indicates a working POSIX shell.
+			shell: "unknown",
+			transferShell: "bash",
 			compatEnabled: false,
 		});
 		const buildSpy = vi
 			.spyOn(connectionManager, "buildRemoteCommand")
 			.mockRejectedValue(new Error("stop-before-spawn"));
-		const target: SSHConnectionTarget = { name: "shbox", host: "shbox" };
+		const target: SSHConnectionTarget = { name: "fishbox", host: "fishbox" };
 
 		await expect(readRemoteFile(target, "/etc/hosts", { maxBytes: 1024 })).rejects.toThrow(/stop-before-spawn/);
 		await expect(writeRemoteFile(target, "/tmp/x", new Uint8Array([1]), {})).rejects.toThrow(/stop-before-spawn/);
+		await expect(statRemotePath(target, "/etc/hosts")).rejects.toThrow(/stop-before-spawn/);
+		await expect(listRemoteDir(target, "/etc")).rejects.toThrow(/stop-before-spawn/);
 
-		// Reached buildRemoteCommand → the guard allowed the POSIX shell. Commands are
-		// sent verbatim (no `sh -c` wrapper); write keeps its stdin staging.
-		expect(buildSpy.mock.calls[0]?.[1]).toContain("head -c 1025");
+		// Each dispatch must start with `bash -c '…'` and embed the original
+		// POSIX snippet inside the quoted command. Read also drops `-n`
+		// (allowStdin: true) because cat-staging needs stdin streaming.
+		const dispatches = buildSpy.mock.calls.map(call => call[1] as string);
+		expect(dispatches[0]).toMatch(/^bash -c '.*head -c 1025/);
+		expect(dispatches[1]).toMatch(/^bash -c '.*cat > /);
 		expect(buildSpy.mock.calls[1]?.[2]).toMatchObject({ allowStdin: true });
+		expect(dispatches[2]).toMatch(/^bash -c '.*if \[ -d /);
+		expect(dispatches[3]).toMatch(/^bash -c '.*LC_ALL=C ls -1Ap /);
+	});
+
+	it("uses sh -c when transferShell is sh (the most universal POSIX fallback)", async () => {
+		// Belt-and-suspenders: the common happy path with a sh-family login
+		// shell still routes through `sh -c` to keep one dispatch shape.
+		vi.spyOn(connectionManager, "ensureConnection").mockResolvedValue(undefined);
+		vi.spyOn(connectionManager, "ensureHostInfo").mockResolvedValue({
+			version: 4,
+			os: "linux",
+			shell: "sh",
+			transferShell: "sh",
+			compatEnabled: false,
+		});
+		const buildSpy = vi
+			.spyOn(connectionManager, "buildRemoteCommand")
+			.mockRejectedValue(new Error("stop-before-spawn"));
+		const target: SSHConnectionTarget = { name: "shbox", host: "shbox" };
+
+		await expect(readRemoteFile(target, "/etc/hosts", { maxBytes: 1024 })).rejects.toThrow(/stop-before-spawn/);
+		expect(buildSpy.mock.calls[0]?.[1]).toMatch(/^sh -c '.*head -c 1025/);
 	});
 });

package/src/ssh/connection-manager.ts

@@ -25,6 +25,15 @@ export interface SSHHostInfo {
 	version: number;
 	os: SSHHostOs;
 	shell: SSHHostShell;
+	/**
+	 * Shell name OMP verified can execute the POSIX transfer snippets
+	 * (`head`/`cat`/`mv`/`test`/`ls`) `ssh://` uses. Probed by running
+	 * `sh -lc` / `bash -lc` / `zsh -lc` against the remote and keeping the
+	 * first one that round-trips a known marker. Independent of `shell`
+	 * (the self-reported login shell), which may be noisy, exotic, or simply
+	 * mis-classified — only `transferShell` gates ssh:// transfers.
+	 */
+	transferShell?: "sh" | "bash" | "zsh";
 	compatShell?: "bash" | "sh";
 	compatEnabled: boolean;
 }
@@ -32,7 +41,7 @@ export interface SSHHostInfo {
 const CONTROL_DIR = getSshControlDir();
 const CONTROL_PATH = path.join(CONTROL_DIR, "%C.sock");
 const HOST_INFO_DIR = getRemoteHostDir();
-const HOST_INFO_VERSION = 3;
+const HOST_INFO_VERSION = 4;
 
 const activeHosts = new Map<string, SSHConnectionTarget>();
 const pendingConnections = new Map<string, Promise<void>>();
@@ -166,6 +175,11 @@ function parseCompatShell(value: unknown): "bash" | "sh" | undefined {
 	return undefined;
 }
 
+function parseTransferShell(value: unknown): SSHHostInfo["transferShell"] {
+	if (value === "sh" || value === "bash" || value === "zsh") return value;
+	return undefined;
+}
+
 function applyCompatOverride(host: SSHConnectionTarget, info: SSHHostInfo): SSHHostInfo {
 	const compatShell =
 		info.compatShell ??
@@ -184,18 +198,26 @@ function applyCompatOverride(host: SSHConnectionTarget, info: SSHHostInfo): SSHH
 	return { ...info, version: info.version ?? 0, compatShell, compatEnabled };
 }
 
-function parseHostInfo(value: unknown): SSHHostInfo | null {
+/**
+ * Parse a raw cache-file value (or any unknown) into a normalized
+ * {@link SSHHostInfo}, dropping fields that don't pass the per-field guards.
+ * Exported so cache-layer round-tripping (incl. the new `transferShell`
+ * field, #3719) is testable without touching disk.
+ */
+export 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 transferShell = parseTransferShell(record.transferShell);
 	const compatEnabled = typeof record.compatEnabled === "boolean" ? record.compatEnabled : false;
 	const version = typeof record.version === "number" ? record.version : 0;
 	return {
 		version,
 		os,
 		shell,
+		transferShell,
 		compatShell,
 		compatEnabled,
 	};
@@ -208,6 +230,11 @@ function shouldRefreshHostInfo(host: SSHConnectionTarget, info: SSHHostInfo): bo
 	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;
+	// A non-Windows host with no verified POSIX transfer shell is ambiguous —
+	// either the probe never ran capability checks, or every candidate failed.
+	// Re-probe rather than letting the ssh:// transfer guard reject it on a
+	// stale `shell: "unknown"` classification (#3719).
+	if (info.os !== "windows" && !info.transferShell) return true;
 	return false;
 }
 
@@ -252,15 +279,99 @@ async function persistHostInfo(host: SSHConnectionTarget, info: SSHHostInfo): Pr
 	}
 }
 
+/**
+ * Frame marker emitted by the remote OS/shell probe. The probe wraps its
+ * payload in this prefix so the parser can ignore startup-file noise (banners,
+ * `motd`, login messages, `Last login: …`) instead of trusting only the first
+ * line of stdout. See #3719.
+ */
+export const HOST_PROBE_MARKER = "PI_HOST_PROBE=";
+
+/** Marker for the transfer-shell capability probe. */
+export const TRANSFER_PROBE_MARKER = "PI_TRANSFER_OK|";
+
+/** sh / bash / zsh, in the order we'll try as `transferShell` candidates. */
+const TRANSFER_SHELL_CANDIDATES = ["sh", "bash", "zsh"] as const;
+
+/**
+ * Find the first line of `stdout`/`stderr` that begins with `marker` and
+ * return everything after it. Used by the SSH host probe so noisy login
+ * dotfiles can't corrupt OS/shell classification by emitting text on the
+ * first line of `ssh` output.
+ *
+ * Returns `null` when no marker line is found in either stream.
+ */
+export function extractProbePayload(stdout: string, stderr: string, marker = HOST_PROBE_MARKER): string | null {
+	for (const blob of [stdout, stderr]) {
+		if (!blob) continue;
+		for (const line of blob.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed.startsWith(marker)) {
+				return trimmed.slice(marker.length);
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Find `marker` anywhere in `stdout` or `stderr` and return everything that
+ * follows it, scanning stdout first. Returns `null` when the marker is in
+ * neither stream.
+ *
+ * Used by the transfer-shell capability probe. Some remotes have broken
+ * login dotfiles that swap fd 1/2, so the marker can land on stderr even
+ * though the probe ran the printf successfully (matches the host-info
+ * probe's stderr fallback). See #3719.
+ */
+export function findProbeMarker(stdout: string, stderr: string, marker: string): string | null {
+	for (const blob of [stdout, stderr]) {
+		if (!blob) continue;
+		const idx = blob.indexOf(marker);
+		if (idx !== -1) return blob.slice(idx + marker.length);
+	}
+	return null;
+}
+
+/** Classify a POSIX-ish `uname -s` payload from the transfer-shell probe. */
+export function osFromUname(value: string): SSHHostOs | undefined {
+	const uname = value.toLowerCase();
+	if (uname.includes("darwin")) return "macos";
+	if (uname.includes("linux") || uname.includes("gnu")) return "linux";
+	if (uname.includes("mingw") || uname.includes("msys") || uname.includes("cygwin") || uname.includes("windows")) {
+		return "windows";
+	}
+	return undefined;
+}
+
+async function probeTransferShell(
+	host: SSHConnectionTarget,
+): Promise<{ shell: SSHHostInfo["transferShell"]; uname: string }> {
+	for (const candidate of TRANSFER_SHELL_CANDIDATES) {
+		// `printf` is POSIX and emits no trailing newline, so we can pin the
+		// marker right against the uname output and split on it cleanly.
+		const remote = `${candidate} -lc 'printf "${TRANSFER_PROBE_MARKER}"; uname -s 2>/dev/null || true'`;
+		const probe = await runSshCaptureSync(await buildRemoteCommand(host, remote));
+		if (probe.exitCode !== 0) continue;
+		const tail = findProbeMarker(probe.stdout, probe.stderr, TRANSFER_PROBE_MARKER);
+		if (tail === null) continue;
+		return { shell: candidate, uname: tail.trim() };
+	}
+	return { shell: undefined, uname: "" };
+}
+
 async function probeHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
-	const command = 'echo "$OSTYPE|$SHELL|$BASH_VERSION" 2>/dev/null || echo "%OS%|%COMSPEC%|"';
+	const command = `echo "${HOST_PROBE_MARKER}$OSTYPE|$SHELL|$BASH_VERSION" 2>/dev/null || echo "${HOST_PROBE_MARKER}%OS%|%COMSPEC%|"`;
 	const result = await runSshCaptureSync(await buildRemoteCommand(host, command));
-	if (result.exitCode !== 0 && !result.stdout) {
+	const payload = extractProbePayload(result.stdout, result.stderr);
+	if (payload === null) {
 		logger.debug("SSH host probe failed", { host: host.name, error: result.stderr });
+		const transferProbe = await probeTransferShell(host);
 		const fallback: SSHHostInfo = {
 			version: HOST_INFO_VERSION,
-			os: "unknown",
+			os: transferProbe.shell ? (osFromUname(transferProbe.uname) ?? "unknown") : "unknown",
 			shell: "unknown",
+			transferShell: transferProbe.shell,
 			compatShell: undefined,
 			compatEnabled: false,
 		};
@@ -268,27 +379,26 @@ async function probeHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
 		return fallback;
 	}
 
-	const output = (result.stdout || result.stderr).split("\n")[0]?.trim() ?? "";
-	const [rawOs = "", rawShell = "", rawBash = ""] = output.split("|");
+	const [rawOs = "", rawShell = "", rawBash = ""] = payload.split("|");
 	const ostype = rawOs.trim();
 	const shellRaw = rawShell.trim();
 	const bashVersion = rawBash.trim();
-	const outputLower = output.toLowerCase();
+	const payloadLower = payload.toLowerCase();
 	const osLower = ostype.toLowerCase();
 	const shellLower = shellRaw.toLowerCase();
 	const unexpandedPosixVars =
-		output.includes("$OSTYPE") || output.includes("$SHELL") || output.includes("$BASH_VERSION");
+		payload.includes("$OSTYPE") || payload.includes("$SHELL") || payload.includes("$BASH_VERSION");
 	const windowsDetected =
 		osLower.includes("windows") ||
 		osLower.includes("msys") ||
 		osLower.includes("cygwin") ||
 		osLower.includes("mingw") ||
-		outputLower.includes("windows_nt") ||
-		outputLower.includes("comspec") ||
+		payloadLower.includes("windows_nt") ||
+		payloadLower.includes("comspec") ||
 		shellLower.includes("cmd") ||
 		shellLower.includes("powershell") ||
 		unexpandedPosixVars ||
-		output.includes("%OS%");
+		payload.includes("%OS%");
 
 	let os: SSHHostOs = "unknown";
 	if (windowsDetected) {
@@ -305,6 +415,22 @@ async function probeHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
 		shell = "cmd";
 	}
 
+	// For any non-Windows host (including `unknown`, which is often a misclassified
+	// POSIX remote with noisy login output) verify a working transfer shell by
+	// running `sh -lc` / `bash -lc` / `zsh -lc` against it. The first one whose
+	// printf round-trips becomes `transferShell`; ssh:// gates on this rather
+	// than the self-reported login-shell name (#3719).
+	let transferShell: SSHHostInfo["transferShell"];
+	if (os !== "windows") {
+		const probe = await probeTransferShell(host);
+		transferShell = probe.shell;
+		// `uname -s` from the same probe lets us recover the OS when the first
+		// probe couldn't classify it (e.g. the remote silently nuked `$OSTYPE`).
+		if (transferShell && os === "unknown") {
+			os = osFromUname(probe.uname) ?? os;
+		}
+	}
+
 	const hasBash = !unexpandedPosixVars && (Boolean(bashVersion) || shell === "bash");
 	let compatShell: SSHHostInfo["compatShell"];
 	if (os === "windows" && host.compat !== false) {
@@ -328,6 +454,7 @@ async function probeHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
 		version: HOST_INFO_VERSION,
 		os,
 		shell,
+		transferShell,
 		compatShell,
 		compatEnabled,
 	});

package/src/ssh/file-transfer.ts

@@ -8,20 +8,24 @@
  */
 import { ptree } from "@oh-my-pi/pi-utils";
 import { buildRemoteCommand, ensureConnection, ensureHostInfo, type SSHConnectionTarget } from "./connection-manager";
-import { quotePosixPath } from "./utils";
+import { quotePosixPath, wrapInPosixShell } from "./utils";
 
 /** Per-operation timeout for remote transfers (matches the ssh tool's grep window). */
 const DEFAULT_TIMEOUT_MS = 30_000;
 
 /**
- * Ensure the ControlMaster connection and restrict transfers to remotes whose
- * *login* shell runs our POSIX snippets directly. OpenSSH hands each command to
- * `$SHELL -c`, so the login shell must be POSIX: Windows (cmd/powershell) can't
- * drive `head`/`cat`/`mv`, and csh/tcsh apply `!` history expansion to the
- * command line. `ensureHostInfo` classifies those (and fish) as a non-sh shell,
- * so accept only sh, bash, and zsh; anything else is refused here.
+ * Ensure the ControlMaster connection and pick the verified POSIX shell to
+ * run transfer commands under. Returns the shell name so the caller can
+ * wrap its snippet in `<shell> -c '…'`; OpenSSH otherwise hands the command
+ * to the user's login shell, which on fish/csh/tcsh hosts can't parse our
+ * `if [ … ]; then …` constructs (#3719).
+ *
+ * Windows hosts are refused up front — `ssh://` runs `head`/`cat`/`mv`/`test`
+ * directly and cmd/powershell can't drive those. Everywhere else, we require
+ * a non-empty `transferShell` (set by `probeHostInfo` after `sh -lc` /
+ * `bash -lc` / `zsh -lc` round-trips a marker against the remote).
  */
-async function ensurePosixRemote(target: SSHConnectionTarget): Promise<void> {
+async function ensurePosixRemote(target: SSHConnectionTarget): Promise<"sh" | "bash" | "zsh"> {
 	await ensureConnection(target);
 	const info = await ensureHostInfo(target);
 	if (info.os === "windows") {
@@ -29,11 +33,12 @@ async function ensurePosixRemote(target: SSHConnectionTarget): Promise<void> {
 			`ssh://: ${target.name} is a Windows host; ssh:// supports POSIX remotes only (head/cat/mv) — use the ssh tool for Windows hosts`,
 		);
 	}
-	if (info.shell !== "sh" && info.shell !== "bash" && info.shell !== "zsh") {
+	if (!info.transferShell) {
 		throw new Error(
-			`ssh://: ${target.name} uses a non-POSIX login shell (${info.shell}); ssh:// read/write needs sh, bash, or zsh — use the ssh tool for this host`,
+			`ssh://: ${target.name} has no verified POSIX shell for ssh:// read/write — none of sh/bash/zsh round-tripped a capability probe (use the ssh tool for this host)`,
 		);
 	}
+	return info.transferShell;
 }
 
 export interface RemoteFileReadOptions {
@@ -67,9 +72,9 @@ export async function readRemoteFile(
 	remotePath: string,
 	opts: RemoteFileReadOptions,
 ): Promise<RemoteFileReadResult> {
-	await ensurePosixRemote(target);
+	const shell = await ensurePosixRemote(target);
 	const command = `head -c ${opts.maxBytes + 1} ${quotePosixPath(remotePath)}`;
-	const args = await buildRemoteCommand(target, command);
+	const args = await buildRemoteCommand(target, wrapInPosixShell(shell, command));
 	using child = ptree.spawn(["ssh", ...args], {
 		signal: ptree.combineSignals(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
 	});
@@ -110,7 +115,7 @@ export async function writeRemoteFile(
 	content: Uint8Array,
 	opts: RemoteFileWriteOptions,
 ): Promise<void> {
-	await ensurePosixRemote(target);
+	const shell = await ensurePosixRemote(target);
 	if (remotePath.endsWith("/")) {
 		throw new Error("ssh://: destination is a directory path (trailing '/'); ssh:// write requires a file path");
 	}
@@ -135,7 +140,7 @@ export async function writeRemoteFile(
 		`elif [ -e ${dest} ] && [ ! -L ${dest} ]; then echo 'ssh://: destination is a special file (not a regular file)' >&2; exit 1; ` +
 		`else mv "$t" ${dest}; fi; ` +
 		`}`;
-	const args = await buildRemoteCommand(target, command, { allowStdin: true });
+	const args = await buildRemoteCommand(target, wrapInPosixShell(shell, command), { allowStdin: true });
 	using child = ptree.spawn(["ssh", ...args], {
 		stdin: content,
 		signal: ptree.combineSignals(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
@@ -155,10 +160,10 @@ export async function statRemotePath(
 	remotePath: string,
 	opts: { signal?: AbortSignal; timeoutMs?: number } = {},
 ): Promise<RemotePathKind> {
-	await ensurePosixRemote(target);
+	const shell = await ensurePosixRemote(target);
 	const p = quotePosixPath(remotePath);
 	const command = `if [ -d ${p} ]; then echo directory; elif [ -f ${p} ]; then echo file; elif [ -e ${p} ]; then echo other; else echo missing; fi`;
-	const args = await buildRemoteCommand(target, command);
+	const args = await buildRemoteCommand(target, wrapInPosixShell(shell, command));
 	using child = ptree.spawn(["ssh", ...args], {
 		signal: ptree.combineSignals(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
 	});
@@ -188,9 +193,9 @@ export async function listRemoteDir(
 	remotePath: string,
 	opts: { signal?: AbortSignal; timeoutMs?: number } = {},
 ): Promise<RemoteDirEntry[]> {
-	await ensurePosixRemote(target);
+	const shell = await ensurePosixRemote(target);
 	const command = `LC_ALL=C ls -1Ap -- ${quotePosixPath(remotePath)}`;
-	const args = await buildRemoteCommand(target, command);
+	const args = await buildRemoteCommand(target, wrapInPosixShell(shell, command));
 	using child = ptree.spawn(["ssh", ...args], {
 		signal: ptree.combineSignals(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
 	});

package/src/ssh/ssh-executor.ts

@@ -4,6 +4,7 @@ import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { buildRemoteCommand, ensureConnection, ensureHostInfo, type SSHConnectionTarget } from "./connection-manager";
 import { hasSshfs, mountRemote } from "./sshfs-mount";
+import { wrapInPosixShell } from "./utils";
 
 export interface SSHExecutorOptions {
 	/** Timeout in milliseconds */
@@ -78,18 +79,6 @@ function createAbortWaiter(
 	return { promise, cleanup: () => signal.removeEventListener("abort", onAbort) };
 }
 
-function quoteForCompatShell(command: string): string {
-	if (command.length === 0) {
-		return "''";
-	}
-	const escaped = command.replace(/'/g, "'\\''");
-	return `'${escaped}'`;
-}
-
-function buildCompatCommand(shell: "bash" | "sh", command: string): string {
-	return `${shell} -c ${quoteForCompatShell(command)}`;
-}
-
 export async function executeSSH(
 	host: SSHConnectionTarget,
 	command: string,
@@ -108,7 +97,7 @@ export async function executeSSH(
 	if (options?.compatEnabled) {
 		const info = await ensureHostInfo(host);
 		if (info.compatShell) {
-			resolvedCommand = buildCompatCommand(info.compatShell, command);
+			resolvedCommand = wrapInPosixShell(info.compatShell, command);
 		} else {
 			logger.warn("SSH compat enabled without detected compat shell", { host: host.name });
 		}

package/src/ssh/utils.ts

@@ -30,3 +30,22 @@ export function quotePosixPath(value: string): string {
 	if (value.length === 0) return "''";
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
+
+/**
+ * Wrap a POSIX command in `<shell> -c '<command>'` so it runs under the
+ * named shell rather than whatever `$SHELL` happens to be on the remote.
+ *
+ * Used by the `ssh://` transfer helpers and the Windows compat dispatch:
+ * OpenSSH passes our snippets to `<login-shell> -c`, so a remote whose
+ * login shell is fish/csh/tcsh (or cmd/powershell on Windows compat)
+ * can't parse `if [ … ]; then …`. Wrapping forces parsing under the
+ * shell OMP actually verified can run the snippet.
+ *
+ * `-c` (not `-lc`): the transfer snippets only call absolute POSIX
+ * builtins (`head`/`cat`/`mv`/`test`/`ls`/`mkdir`/`rm`/`dirname`) and
+ * don't need login-profile setup. Capability *probing* still uses
+ * `-lc` to mirror the user's real environment.
+ */
+export function wrapInPosixShell(shell: "sh" | "bash" | "zsh", command: string): string {
+	return `${shell} -c ${quotePosixPath(command)}`;
+}