@xynogen/pix-runtime 0.10.2 → 0.12.2

package/src/exec.ts

@@ -0,0 +1,365 @@
+/**
+ * exec.ts — run a catalogued binary by name, on any OS.
+ *
+ * Every pix package that starts an external program goes through here, so:
+ *   - the binary comes from the one resolver (binary.json → `<agentDir>/bin` →
+ *     known install dirs → PATH), never a bare-name OS lookup;
+ *   - a missing binary is a {@link BinaryMissingError} with an install hint, and
+ *     the async runners download it first when the catalog has a trusted release;
+ *   - Windows `.cmd`/`.bat` shims (npm, npx, pi) run through `cmd.exe` with
+ *     strict quoting, since Node refuses to spawn them without a shell.
+ *
+ * Callers pass the tool's arguments unchanged; this layer never adds a shell
+ * for real executables.
+ */
+
+import {
+	type ChildProcess,
+	type ChildProcessWithoutNullStreams,
+	type SpawnOptions,
+	type SpawnOptionsWithStdioTuple,
+	type SpawnSyncOptions,
+	type StdioNull,
+	type StdioPipe,
+	spawn,
+	spawnSync,
+} from "node:child_process";
+import { join } from "node:path";
+import type { Readable, Writable } from "node:stream";
+import { type EnsureOptions, ensureTool, type ToolStatus } from "./binaries/ensure.ts";
+import { type LookupOptions, type ResolvedTool, requireTool } from "./binaries/resolve.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+// ── Windows shim quoting ────────────────────────────────────────────────────
+// Ported from cross-spawn (MIT): arguments are quoted for the program's
+// CommandLineToArgvW parsing, then cmd.exe metacharacters are caret-escaped.
+// npm-style shims under node_modules/.bin re-parse their arguments, so they get
+// a second round of caret escaping.
+
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+const CMD_SHIM_IN_BIN = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
+
+/** True when `path` is a batch file that needs `cmd.exe` to run. */
+export function isBatchFile(path: string): boolean {
+	return /\.(cmd|bat)$/i.test(path);
+}
+
+/** Quote one argument for a `cmd.exe /d /s /c "…"` line. */
+export function quoteForCmd(arg: string, doubleEscape = false): string {
+	let out = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+	out = `"${out}"`.replace(CMD_META, "^$1");
+	return doubleEscape ? out.replace(CMD_META, "^$1") : out;
+}
+
+export interface CommandLine {
+	command: string;
+	args: string[];
+	/** Must be passed to spawn so Node does not re-quote the cmd.exe line. */
+	windowsVerbatimArguments?: boolean;
+}
+
+/**
+ * Translate `path args…` into what spawn needs on this host. Real executables
+ * pass through untouched; Windows batch files become one quoted `cmd.exe` line.
+ */
+export function commandLine(
+	path: string,
+	args: readonly string[],
+	host: HostPlatform = currentPlatform(),
+	env: NodeJS.ProcessEnv = process.env,
+): CommandLine {
+	if (host.os !== "win32" || !isBatchFile(path)) return { command: path, args: [...args] };
+	const doubleEscape = CMD_SHIM_IN_BIN.test(path);
+	const line = [
+		path.replace(CMD_META, "^$1"),
+		...args.map((a) => quoteForCmd(a, doubleEscape)),
+	].join(" ");
+	const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+	return {
+		command: env.ComSpec ?? env.COMSPEC ?? join(root, "System32", "cmd.exe"),
+		args: ["/d", "/s", "/c", `"${line}"`],
+		windowsVerbatimArguments: true,
+	};
+}
+
+// ── Runners ─────────────────────────────────────────────────────────────────
+
+export interface ToolExecOptions {
+	cwd?: string;
+	/** Child environment; also where PATH is read for the lookup. Default process.env. */
+	env?: NodeJS.ProcessEnv;
+	/** Kill the child after this many ms (result has `timedOut: true`). */
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	/** Written to stdin, then stdin is closed. */
+	input?: string | Buffer;
+	/** Download progress when the binary is fetched first (async runners only). */
+	onStatus?: (status: ToolStatus) => void;
+	/** Test seam for the host OS. */
+	host?: HostPlatform;
+	/** Cap on captured stdout/stderr bytes each (default 50 MB). */
+	maxBuffer?: number;
+	/** Args are already quoted for the target (cmd.exe `/c` lines); Node must not re-quote. */
+	verbatim?: boolean;
+}
+
+export interface ToolRunResult {
+	/** Exit code, or null when killed by a signal/timeout. */
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	/** Raw stdout for binary output (clipboard images, archives). */
+	stdoutBytes: Buffer;
+	timedOut: boolean;
+	/** Output passed `maxBuffer` and was cut. A zero exit code is then not a complete result. */
+	truncated: boolean;
+	/** The binary that ran and where it was found. */
+	tool: ResolvedTool;
+}
+
+const MAX_BUFFER = 50 * 1024 * 1024;
+/** Time between SIGTERM and SIGKILL, and then before open pipes are dropped. */
+const KILL_GRACE_MS = 1500;
+
+function lookupOpts(opts: ToolExecOptions): LookupOptions {
+	return { env: opts.env, host: opts.host };
+}
+
+/**
+ * Kill a child and its descendants. Windows: `taskkill /T /F` (a cmd.exe wrapper
+ * leaves the shim running otherwise). POSIX: signal the child's process group
+ * (runTool starts it as a group leader), because a descendant that keeps
+ * stdout open would otherwise delay "close" past the timeout.
+ */
+function killTree(
+	child: ChildProcess,
+	host: HostPlatform,
+	env: NodeJS.ProcessEnv,
+	signal: NodeJS.Signals = "SIGTERM",
+): void {
+	if (!child.pid) return;
+	if (host.os === "win32") {
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+		spawnSync(join(root, "System32", "taskkill.exe"), ["/pid", String(child.pid), "/T", "/F"], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		return;
+	}
+	// The group can outlive the leader, so do not skip on child exit.
+	try {
+		process.kill(-child.pid, signal);
+	} catch {
+		// ESRCH: the group is gone. EPERM: not a group we own; fall back to the child.
+		if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+	}
+}
+
+type HostOpt = { host?: HostPlatform };
+type Pipe = StdioPipe;
+type Null = StdioNull;
+/** Child whose piped streams are typed non-null, mirroring Node's spawn overloads. */
+type Piped<I, O, E> = ChildProcess & {
+	stdin: I extends Pipe ? Writable : null;
+	stdout: O extends Pipe ? Readable : null;
+	stderr: E extends Pipe ? Readable : null;
+};
+
+/**
+ * Start a resolved binary with Node's spawn options (stdio, detached, …).
+ * Sync lookup, no download; throws {@link BinaryMissingError} when missing.
+ */
+export function spawnTool<I extends Pipe | Null, O extends Pipe | Null, E extends Pipe | Null>(
+	name: string,
+	args: readonly string[],
+	options: SpawnOptionsWithStdioTuple<I, O, E> & HostOpt,
+): Piped<I, O, E>;
+export function spawnTool(
+	name: string,
+	args?: readonly string[],
+	options?: Omit<SpawnOptions, "stdio"> & HostOpt,
+): ChildProcessWithoutNullStreams;
+export function spawnTool(
+	name: string,
+	args: readonly string[],
+	options: SpawnOptions & HostOpt,
+): ChildProcess;
+export function spawnTool(
+	name: string,
+	args: readonly string[] = [],
+	options: SpawnOptions & HostOpt = {},
+): ChildProcess {
+	const { host: hostOpt, ...spawnOpts } = options;
+	const host = hostOpt ?? currentPlatform();
+	const env = spawnOpts.env ?? process.env;
+	const tool = requireTool(name, { env, host });
+	const line = commandLine(tool.path, args, host, env);
+	return spawn(line.command, line.args, {
+		windowsHide: true,
+		...spawnOpts,
+		windowsVerbatimArguments: line.windowsVerbatimArguments ?? spawnOpts.windowsVerbatimArguments,
+	});
+}
+
+/** Run a resolved child to completion, collecting output. */
+function collect(
+	child: ChildProcess,
+	tool: ResolvedTool,
+	opts: ToolExecOptions,
+	host: HostPlatform,
+) {
+	const env = opts.env ?? process.env;
+	const cap = opts.maxBuffer ?? MAX_BUFFER;
+	return new Promise<ToolRunResult>((resolve, reject) => {
+		const out: Buffer[] = [];
+		const err: Buffer[] = [];
+		let outLen = 0;
+		let errLen = 0;
+		let timedOut = false;
+		let truncated = false;
+		const push = (list: Buffer[], chunk: Buffer, len: number): number => {
+			const room = cap - len;
+			if (chunk.length > room) truncated = true;
+			if (room <= 0) return len;
+			list.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+			return len + Math.min(chunk.length, room);
+		};
+		child.stdout?.on("data", (c: Buffer) => {
+			outLen = push(out, c, outLen);
+		});
+		child.stderr?.on("data", (c: Buffer) => {
+			errLen = push(err, c, errLen);
+		});
+		const escalation: NodeJS.Timeout[] = [];
+		const stop = () => {
+			if (escalation.length > 0) return;
+			killTree(child, host, env);
+			// A child may ignore SIGTERM. A descendant may leave the group and keep a
+			// pipe open. Both would hold "close" forever, so escalate, then drop pipes.
+			escalation.push(
+				setTimeout(() => killTree(child, host, env, "SIGKILL"), KILL_GRACE_MS),
+				setTimeout(() => {
+					child.stdout?.destroy();
+					child.stderr?.destroy();
+				}, KILL_GRACE_MS * 2),
+			);
+		};
+		const timer =
+			opts.timeoutMs && opts.timeoutMs > 0
+				? setTimeout(() => {
+						timedOut = true;
+						stop();
+					}, opts.timeoutMs)
+				: undefined;
+		opts.signal?.addEventListener("abort", stop, { once: true });
+		const done = () => {
+			if (timer) clearTimeout(timer);
+			for (const t of escalation) clearTimeout(t);
+			opts.signal?.removeEventListener("abort", stop);
+		};
+		child.on("error", (e) => {
+			done();
+			reject(e);
+		});
+		child.on("close", (code) => {
+			done();
+			const stdoutBytes = Buffer.concat(out);
+			resolve({
+				code: timedOut ? null : code,
+				stdout: stdoutBytes.toString("utf-8"),
+				stderr: Buffer.concat(err).toString("utf-8"),
+				stdoutBytes,
+				timedOut,
+				truncated,
+				tool,
+			});
+		});
+		// A child may exit without reading stdin (EPIPE). With no listener that is an
+		// uncaught stream error that kills the host. The exit code still reports the
+		// outcome. Other stdin errors come back through child "error" or "close".
+		child.stdin?.on("error", () => {});
+		if (opts.input !== undefined) child.stdin?.end(opts.input);
+		else child.stdin?.end();
+	});
+}
+
+/**
+ * Run `name args…` and capture its output. Downloads the binary first when it
+ * is missing and the catalog has a release for this host (progress via
+ * `onStatus`). Rejects with {@link BinaryMissingError} when it cannot be found.
+ * A non-zero exit resolves normally — check `code`.
+ */
+export async function runTool(
+	name: string,
+	args: readonly string[],
+	opts: ToolExecOptions = {},
+): Promise<ToolRunResult> {
+	const host = opts.host ?? currentPlatform();
+	const ensure: EnsureOptions = {
+		env: opts.env,
+		host,
+		onStatus: opts.onStatus,
+		signal: opts.signal,
+	};
+	const tool = await ensureTool(name, ensure);
+	if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("aborted");
+	const env = opts.env ?? process.env;
+	const line = opts.verbatim
+		? { command: tool.path, args: [...args], windowsVerbatimArguments: true }
+		: commandLine(tool.path, args, host, env);
+	const child = spawn(line.command, line.args, {
+		cwd: opts.cwd,
+		env,
+		stdio: ["pipe", "pipe", "pipe"],
+		// POSIX: own process group, so killTree reaches descendants. On Windows
+		// `detached` opens a new console, and taskkill /T covers the tree.
+		// ponytail: the group also has no controlling terminal, so a tool cannot
+		// prompt on /dev/tty. runTool is for captured, non-interactive runs.
+		// Interactive tools use spawnTool.
+		detached: host.os !== "win32",
+		windowsHide: true,
+		windowsVerbatimArguments: line.windowsVerbatimArguments,
+	});
+	return collect(child, tool, opts, host);
+}
+
+/**
+ * Blocking {@link runTool} for startup probes and sync call sites. Never
+ * downloads; throws {@link BinaryMissingError} when missing.
+ */
+export function runToolSync(
+	name: string,
+	args: readonly string[],
+	opts: Omit<ToolExecOptions, "signal" | "onStatus"> = {},
+): ToolRunResult {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	const tool = requireTool(name, lookupOpts({ ...opts, host }));
+	const line = commandLine(tool.path, args, host, env);
+	const sync: SpawnSyncOptions = {
+		cwd: opts.cwd,
+		env,
+		input: opts.input,
+		timeout: opts.timeoutMs,
+		maxBuffer: opts.maxBuffer ?? MAX_BUFFER,
+		windowsHide: true,
+		windowsVerbatimArguments: line.windowsVerbatimArguments,
+	};
+	const r = spawnSync(line.command, line.args, sync);
+	// Over maxBuffer, spawnSync kills the child and sets ENOBUFS. That throws below,
+	// so a sync result is never truncated.
+	if (r.error && (r.error as NodeJS.ErrnoException).code !== "ETIMEDOUT") throw r.error;
+	const stdoutBytes = Buffer.isBuffer(r.stdout) ? r.stdout : Buffer.from(r.stdout ?? "");
+	const stderr = Buffer.isBuffer(r.stderr) ? r.stderr.toString("utf-8") : String(r.stderr ?? "");
+	const timedOut = (r.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
+	return {
+		code: timedOut ? null : r.status,
+		stdout: stdoutBytes.toString("utf-8"),
+		stderr,
+		stdoutBytes,
+		timedOut,
+		truncated: false,
+		tool,
+	};
+}

package/src/extension.ts

@@ -1,9 +1,16 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type BashOperations,
+	createLocalBashOperations,
+	createLocalPowerShellOperations,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { syncBinaryStore } from "./binaries/store.ts";
 import { bindHerdrNotify } from "./herdr-notify.ts";
 import { bindAgentStateEvents, resetAgentState, resetUnattendedState } from "./herdr-state.ts";
 import { once } from "./once.ts";
 import { registerPixCommand } from "./pix-command.ts";
 import { pixRuntime } from "./runtime.ts";
+import { userShell } from "./user-shell.ts";
 
 /**
  * Runtime extension entry. Idempotent per `pi` instance: registers `/pix` and
@@ -21,16 +28,38 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 		const unbindAgentState = bindAgentStateEvents(pi.events);
 		const unbindHerdrNotify = bindHerdrNotify(pi.events);
 
+		// User `!` commands: PowerShell on Windows, $SHELL on POSIX (zsh gets rc + aliases).
+		const shell = userShell();
+		// Older Pi has no PowerShell backend. Keep Pi's default shell then.
+		const inner =
+			shell?.kind === "powershell"
+				? createLocalPowerShellOperations?.()
+				: shell && createLocalBashOperations({ shellPath: shell.shellPath });
+		if (shell && inner) {
+			const operations: BashOperations = {
+				exec: (command, cwd, options) => inner.exec(shell.wrap(command), cwd, options),
+			};
+			pi.on("user_bash", () => ({ operations }));
+		}
+
 		let initialized = false;
 		pi.on("session_start", async () => {
 			resetUnattendedState(pi.events);
 			if (initialized) {
 				await runtime.reload({ origin: "reload", source: "session_start" });
 			} else {
-				initialized = true;
 				await runtime.init({ origin: "init", source: "session_start" });
+				// Set only on success: a failed init retries init (with migrations) next session.
+				initialized = true;
 			}
 			surfaceDiagnostics(pi, runtime);
+			// binary.json holds overrides only; drop legacy `null` padding, report bad JSON.
+			try {
+				const store = syncBinaryStore();
+				if (store.error) notifyWarning(pi, `pix: ${store.path} is invalid (${store.error})`);
+			} catch {
+				/* read-only agent dir: the Binaries tab still resolves without the file */
+			}
 		});
 
 		pi.on("session_shutdown", async () => {
@@ -47,7 +76,10 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 function surfaceDiagnostics(pi: ExtensionAPI, runtime: ReturnType<typeof pixRuntime>): void {
 	const errors = runtime.diagnostics().filter((d) => d.severity === "error");
 	if (errors.length === 0) return;
+	notifyWarning(pi, `pix config: ${errors.length} issue(s) — see ${runtime.path}`);
+}
+
+function notifyWarning(pi: ExtensionAPI, msg: string): void {
 	const ui = (pi as unknown as { ui?: { notify?(m: string, t?: string): void } }).ui;
-	const msg = `pix config: ${errors.length} issue(s) — see ${runtime.path}`;
 	ui?.notify?.(msg, "warning");
 }

package/src/icon-catalog.ts

@@ -99,6 +99,7 @@ const CATALOG = {
 	// ── paste chips (pix-display) ─────────────────────────────────────────
 	"paste.image": { nerd: "\u{F02E9}", unicode: `\u25A3${VS}`, ascii: "img" },
 	"paste.text": { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "txt" },
+	"paste.prompt": { nerd: "\u{F0D0}", unicode: `\u2726${VS}`, ascii: "pr" },
 
 	// ── model picker (pix-models) ─────────────────────────────────────────
 	"picker.model": { nerd: "\u{F0229}", unicode: `\u25C8${VS}`, ascii: "M" },

package/src/os.ts

@@ -0,0 +1,250 @@
+/**
+ * os.ts — jobs that need a different program on each OS, behind one call.
+ *
+ * Packages ask for the job ("open this URL", "read the clipboard image"); this
+ * module picks the program for the host and runs it through `exec.ts`, so the
+ * binary still comes from binary.json / `<agentDir>/bin` / known dirs / PATH.
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveTool } from "./binaries/resolve.ts";
+import { quoteForCmd, runTool, runToolSync } from "./exec.ts";
+import { tempDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export interface OsOptions {
+	env?: NodeJS.ProcessEnv;
+	host?: HostPlatform;
+}
+
+// ── Open a URL or path ──────────────────────────────────────────────────────
+
+export interface OpenOptions extends OsOptions {
+	/** Browser/app name or path. Default: the OS default handler. */
+	app?: string;
+	timeoutMs?: number;
+}
+
+/** Program + args that open `target` on `host` (exported for tests). */
+export function openCommand(
+	target: string,
+	host: HostPlatform,
+	app?: string,
+): { name: string; args: string[]; verbatim?: boolean } {
+	if (host.os === "darwin") return { name: "open", args: app ? ["-a", app, target] : [target] };
+	if (host.os === "win32") {
+		// `start` is a cmd.exe builtin; "" is its window-title argument.
+		const parts = ["start", '""', ...(app ? [quoteForCmd(app)] : []), quoteForCmd(target)];
+		return { name: "cmd", args: ["/d", "/s", "/c", `"${parts.join(" ")}"`], verbatim: true };
+	}
+	if (host.wsl && !app) {
+		// WSL: hand the target to Windows so the user's default browser opens.
+		return { name: "wslview", args: [target] };
+	}
+	return { name: app ?? "xdg-open", args: [target] };
+}
+
+/**
+ * Open a URL or file with the OS default handler (or `app`). Throws a
+ * BinaryMissingError with an install hint when the opener is missing, or an
+ * Error with the opener's stderr when it exits non-zero.
+ */
+export async function openTarget(target: string, opts: OpenOptions = {}): Promise<void> {
+	const host = opts.host ?? currentPlatform();
+	let cmd = openCommand(target, host, opts.app);
+	if (cmd.name === "wslview" && !resolveTool("wslview", opts))
+		cmd = openCommand(target, { ...host, wsl: false });
+	const result = await runTool(cmd.name, cmd.args, {
+		env: opts.env,
+		host,
+		timeoutMs: opts.timeoutMs ?? 15_000,
+		verbatim: cmd.verbatim,
+	});
+	if (result.code !== 0)
+		throw new Error(result.stderr.trim() || `${cmd.name} exited with code ${result.code}`);
+}
+
+// ── Git ─────────────────────────────────────────────────────────────────────────
+
+export interface GitOptions extends OsOptions {
+	cwd: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	maxBuffer?: number;
+}
+
+/**
+ * `git args…` in `cwd`: stdout on exit 0, null on any git failure (not a
+ * repo, timeout, abort, or output cut at `maxBuffer`). A missing git binary rejects with BinaryMissingError
+ * so the caller can surface the install hint once (pix-pretty warnBinaryMissing).
+ */
+export async function runGit(args: readonly string[], opts: GitOptions): Promise<string | null> {
+	const r = await runTool("git", args, {
+		cwd: opts.cwd,
+		env: opts.env,
+		host: opts.host,
+		timeoutMs: opts.timeoutMs ?? 5_000,
+		signal: opts.signal,
+		maxBuffer: opts.maxBuffer,
+	}).catch((err: unknown) => {
+		if (err instanceof Error && err.name === "BinaryMissingError") throw err;
+		return null;
+	});
+	return r && r.code === 0 && !r.truncated ? r.stdout : null;
+}
+
+// ── Clipboard image ─────────────────────────────────────────────────────────
+
+const LIST_TIMEOUT_MS = 1000;
+const READ_TIMEOUT_MS = 3000;
+const POWERSHELL_TIMEOUT_MS = 5000;
+
+/** Preference order mirrors Pi: PNG first, then other lossless/animated formats. */
+const SUPPORTED_MIME = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+
+export interface ClipboardImage {
+	bytes: Buffer;
+	mimeType: string;
+}
+
+function baseMime(mimeType: string): string {
+	return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function pickPreferredMime(types: readonly string[]): string | null {
+	const normalized = types
+		.map((t) => t.trim())
+		.filter(Boolean)
+		.map((t) => ({ raw: t, base: baseMime(t) }));
+	for (const preferred of SUPPORTED_MIME) {
+		const match = normalized.find((t) => t.base === preferred);
+		if (match) return match.raw;
+	}
+	return normalized.find((t) => t.base.startsWith("image/"))?.raw ?? null;
+}
+
+/** Output bytes when the tool exists and exits 0; null otherwise (probing, never throws). */
+function probe(name: string, args: string[], timeoutMs: number, opts: OsOptions): Buffer | null {
+	if (!resolveTool(name, opts)) return null;
+	try {
+		const r = runToolSync(name, args, { env: opts.env, host: opts.host, timeoutMs });
+		return r.code === 0 ? r.stdoutBytes : null;
+	} catch {
+		return null;
+	}
+}
+
+function lines(buf: Buffer | null): string[] {
+	return buf
+		? buf
+				.toString("utf-8")
+				.split(/\r?\n/)
+				.map((t) => t.trim())
+				.filter(Boolean)
+		: [];
+}
+
+function viaWlPaste(opts: OsOptions): ClipboardImage | null {
+	const selected = pickPreferredMime(
+		lines(probe("wl-paste", ["--list-types"], LIST_TIMEOUT_MS, opts)),
+	);
+	if (!selected) return null;
+	const data = probe("wl-paste", ["--type", selected, "--no-newline"], READ_TIMEOUT_MS, opts);
+	return data?.length ? { bytes: data, mimeType: baseMime(selected) } : null;
+}
+
+function viaXclip(opts: OsOptions): ClipboardImage | null {
+	const targets = lines(
+		probe("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"], LIST_TIMEOUT_MS, opts),
+	);
+	const preferred = targets.length > 0 ? pickPreferredMime(targets) : null;
+	for (const mimeType of preferred ? [preferred, ...SUPPORTED_MIME] : SUPPORTED_MIME) {
+		const data = probe(
+			"xclip",
+			["-selection", "clipboard", "-t", mimeType, "-o"],
+			READ_TIMEOUT_MS,
+			opts,
+		);
+		if (data?.length) return { bytes: data, mimeType: baseMime(mimeType) };
+	}
+	return null;
+}
+
+/** Windows clipboard via PowerShell — native Windows, or from WSL via powershell.exe. */
+function viaPowerShell(host: HostPlatform, opts: OsOptions): ClipboardImage | null {
+	const tmpFile = join(tempDir(), `pix-clip-${randomUUID()}.png`);
+	try {
+		const winPath =
+			host.os === "win32"
+				? tmpFile
+				: lines(probe("wslpath", ["-w", tmpFile], LIST_TIMEOUT_MS, opts))[0];
+		if (!winPath) return null;
+		const script = [
+			"Add-Type -AssemblyName System.Windows.Forms",
+			"Add-Type -AssemblyName System.Drawing",
+			`$path = '${winPath.split("'").join("''")}'`,
+			"$img = [System.Windows.Forms.Clipboard]::GetImage()",
+			"if ($img) { $img.Save($path, [System.Drawing.Imaging.ImageFormat]::Png); Write-Output 'ok' } else { Write-Output 'empty' }",
+		].join("; ");
+		const args = ["-NoProfile", "-STA", "-Command", script];
+		const out = probe("powershell", args, POWERSHELL_TIMEOUT_MS, opts);
+		if (out?.toString("utf-8").trim() !== "ok") return null;
+		const bytes = readFileSync(tmpFile);
+		return bytes.length ? { bytes, mimeType: "image/png" } : null;
+	} catch {
+		return null;
+	} finally {
+		try {
+			unlinkSync(tmpFile);
+		} catch {
+			// best-effort cleanup
+		}
+	}
+}
+
+/**
+ * Read an image from the system clipboard, or null when there is none (or no
+ * clipboard tool). Windows and WSL use PowerShell; Linux uses wl-paste/xclip.
+ * macOS and Termux return null (no dependency-free bridge).
+ */
+export function readClipboardImage(opts: OsOptions = {}): ClipboardImage | null {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	if (host.os === "win32") return viaPowerShell(host, opts);
+	if (host.os !== "linux") return null;
+	const wayland = Boolean(env.WAYLAND_DISPLAY) || env.XDG_SESSION_TYPE === "wayland";
+	let image: ClipboardImage | null = null;
+	if (wayland || host.wsl) image = viaWlPaste(opts) ?? viaXclip(opts);
+	if (!image && host.wsl) image = viaPowerShell(host, opts);
+	if (!image && !wayland) image = viaXclip(opts);
+	return image;
+}
+
+/** {@link readClipboardImage}, spilled to a temp file. Returns the path or null. */
+export function readClipboardImageToFile(opts: OsOptions = {}): string | null {
+	const image = readClipboardImage(opts);
+	if (!image) return null;
+	const ext = extForMime(image.mimeType);
+	const filePath = join(tempDir(), `pix-clipboard-${randomUUID()}.${ext}`);
+	try {
+		writeFileSync(filePath, image.bytes);
+		return filePath;
+	} catch {
+		return null;
+	}
+}
+
+export function extForMime(mimeType: string): string {
+	switch (baseMime(mimeType)) {
+		case "image/jpeg":
+			return "jpg";
+		case "image/webp":
+			return "webp";
+		case "image/gif":
+			return "gif";
+		default:
+			return "png";
+	}
+}