@xynogen/pix-runtime 0.10.1 → 0.12.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,17 +17,12 @@ See `DESIGN.md` for the full contract.
 - Typed, path-filtered change events.
 - One-time migration of legacy unversioned config and the `optimizer.json`
   sidecar.
-- The `/pix` shared-settings command.
-
-## Install
-
-```bash
-pi install npm:@xynogen/pix-runtime
-```
-
-Standalone-installable: importing an accessor lazily creates the singleton even
-without the extension factory. Installed via `pix-core` it registers `/pix` and
-session hooks once.
+- The `/pix` shared-settings command, with **Settings** and **Binaries** tabs.
+- One catalog, resolver and downloader for every external command pix runs
+  (`binaries`), plus shared `paths` and `platform` helpers.
+- **User shell** — user `!` commands run through PowerShell on Windows (pwsh 7,
+  else 5.1), and through `$SHELL` on Linux/macOS (zsh sources `.zshrc` so
+  aliases expand).
 
 ## Usage
 
@@ -74,6 +69,176 @@ Collapse policy helpers:
 import { shouldCollapse, collapseDelayMs } from "@xynogen/pix-runtime/collapse";
 ```
 
+## Paths and platform
+
+```ts
+import { agentDir, binDir, cacheDir, homeDir, projectDir, tempDir } from "@xynogen/pix-runtime/paths";
+import { currentPlatform, hostPlatform } from "@xynogen/pix-runtime/platform";
+
+agentDir();   // PI_CODING_AGENT_DIR (~-expanded) or ~/.pi/agent, same as Pi's getAgentDir
+binDir();     // <agentDir>/bin, the folder where Pi downloads fd/rg and pix downloads its tools
+cacheDir();   // $XDG_CACHE_HOME/pi or ~/.cache/pi (never relies on HOME alone)
+projectDir(cwd); // <cwd>/.pi, Pi's project config dir. projectDir() gives the relative .pi
+tempDir();    // os.tmpdir(): TMPDIR on POSIX, TEMP/TMP on Windows. Shared, so delete only your own entries
+currentPlatform(); // { os, arch, libc?, wsl, termux, exe }
+```
+
+Every helper takes an optional env, so tests can use a temporary agent dir.
+
+## Binaries
+
+Every external command a pix package runs is listed in one catalog
+(`src/binaries/catalog.ts`). The catalog records which packages use each
+command, which OS needs it, an install hint, and, for a few commands, a trusted
+GitHub release.
+
+```ts
+import { ensureTool, requireTool, resolveTool } from "@xynogen/pix-runtime/binaries";
+
+resolveTool("git");                   // sync, no network: { path, source } | undefined
+requireTool("ssh");                   // same, but throws BinaryMissingError with the install hint
+await ensureTool("hunk", { onStatus }); // downloads into <agentDir>/bin when missing
+```
+
+**Resolve order:** `binary.json` path → `<agentDir>/bin` → known install dirs (`system`, e.g. Git Bash on Windows) → PATH. `ensureTool`
+then downloads if the catalog has a release for this host.
+
+If `binary.json` names a file that doesn't exist, the entry is **broken**. pix
+never silently falls back to another copy.
+
+| Downloaded when missing | Source | Checksum |
+|---|---|---|
+| `rtk` (Windows, Linux, macOS) | `rtk-ai/rtk` latest release | `checksums.txt` |
+| `hunk` (Windows, Linux, macOS) | `modem-dev/hunk` latest release | `SHA256SUMS` |
+| `aria2c` (Windows only) | official `aria2/aria2` release | none published |
+| `ffmpeg` (Windows, Linux, ~120 MB) | `BtbN/FFmpeg-Builds` lgpl | `checksums.sha256` |
+
+Everything else, including `rg`, is only checked and never downloaded.
+Pi itself downloads `rg` and `fd`. pix does not run `fd`, so the catalog does not list it.
+
+The downloader:
+
+- finds the latest version through the `/releases/latest` redirect;
+- extracts with the system `tar`/`unzip`;
+- works in a unique temp folder and cleans it up afterwards;
+- shares one download between concurrent calls for the same binary;
+- respects `PI_OFFLINE`.
+
+Progress is reported only through `onStatus`. Use
+`reportToolStatus(ctx.ui)` from `@xynogen/pix-pretty/tool-status` so every
+package shows downloads the same way.
+
+### Running a binary — `./exec`
+
+Packages never start a catalogued binary by bare name. `./exec` resolves it
+through the order above, then runs it:
+
+```ts
+import { runTool, runToolSync, spawnTool } from "@xynogen/pix-runtime/exec";
+
+const r = await runTool("git", ["status", "--porcelain"], { cwd, timeoutMs: 2_000 });
+// { code, stdout, stderr, stdoutBytes, timedOut, tool: { path, source } }
+
+const child = spawnTool("ssh", args, { stdio: ["ignore", "pipe", "pipe"] }); // Node ChildProcess
+const sync = runToolSync("npm", ["root", "-g"], { timeoutMs: 10_000 });
+```
+
+- `runTool` downloads first when the binary is missing and has a recipe
+  (progress via `onStatus`). `spawnTool` and `runToolSync` never download.
+- A missing binary throws `BinaryMissingError` with the install hint. A
+  non-zero exit resolves normally, so check `code`.
+- Windows `.cmd`/`.bat` shims (`npm`, `npx`, `pi`) run through
+  `cmd.exe /d /s /c` with strict quoting, since Node cannot spawn them
+  directly. Spaces, quotes, `&|<>^%` and parentheses survive intact.
+- Timeouts and aborts kill the whole process tree on Windows
+  (`taskkill /T`), so a wrapped shim does not keep running.
+
+### OS jobs — `./os`
+
+Jobs that need a different program on each OS sit behind one call. Each
+program still resolves through `binary.json`:
+
+```ts
+import { openTarget, readClipboardImage, runGit } from "@xynogen/pix-runtime/os";
+
+await openTarget(url, { app: process.env.BROWSER }); // open / cmd start / xdg-open / wslview
+const img = readClipboardImage();                    // PowerShell (Windows, WSL) / wl-paste / xclip
+const branch = await runGit(["branch", "--show-current"], { cwd }); // stdout | null
+```
+
+`runGit` returns `null` for any git failure (not a repo, timeout, abort) but
+rejects with `BinaryMissingError` when git itself is missing. Background
+features pass that to `warnBinaryMissing(ctx.ui, err)` from
+`@xynogen/pix-pretty/tool-status`, which shows one warning per binary per
+session, pointing at the `/pix` Binaries tab.
+
+`scripts/binaries.test.ts` fails CI when a package starts a catalogued binary
+by bare name.
+
+### Audio — `./audio`
+
+One job per function. Callers never see a program name or an OS branch.
+ffmpeg does every job it can on Linux (PulseAudio/PipeWire), macOS
+(AVFoundation/AudioToolbox) and Windows (DirectShow). ffmpeg has no audio
+output on Windows, so playback there uses the built-in PowerShell MediaPlayer.
+
+```ts
+import { listMicrophones, playAudio, startRecording } from "@xynogen/pix-runtime/audio";
+
+const mics = await listMicrophones();    // first entry is "default". No ffmpeg: only "default"
+const rec = startRecording("default", { onLevel, onExit, onStatus }); // mono 16 kHz wav
+await rec.stop();                         // rec.path is the wav. { meterOnly: true } writes nothing
+await playAudio(file, { signal });        // resolves when the sound ends
+```
+
+### Safe output paths — `./safe-path`
+
+`validateOutputPath(absPath)` checks a model-chosen write target before the
+write. It rejects null bytes, system dirs (`/etc`, `/proc` … or
+`C:\Windows`, `Program Files`), secret dirs under home (`.ssh`, `.aws`,
+`.gnupg`, GitHub CLI), symlinks and Windows junctions, existing directories,
+and paths with no writable ancestor. Matching is per path segment, and
+case-insensitive on Windows.
+
+### `~/.pi/agent/binary.json`
+
+This file is user configuration. It holds only the binaries you override. The
+file does not exist until you set a path. The `/pix` Binaries tab shows the
+full catalog of what pix depends on.
+
+```json
+{
+  "$version": 1,
+  "ffmpeg": "D:/tools/ffmpeg/bin/ffmpeg.exe"
+}
+```
+
+- A missing entry (or `null`) means automatic: pix looks in `bin`, then known install dirs, then PATH, then downloads.
+- A path means pix always uses exactly that file.
+
+pix writes to the file only in two cases:
+
+- when you edit or reset a path in the `/pix` Binaries tab (reset removes the entry);
+- to remove legacy `null` entries for catalog binaries from an older file.
+
+Paths pix finds on its own are never written to it. Keys pix doesn't know are
+kept. If the file contains invalid JSON, pix reports it and leaves the file
+unchanged.
+
+### `/pix` → Binaries tab
+
+Press **Tab** / **Shift+Tab** to switch between Settings and Binaries. Each row
+shows a status icon with a text label (ok / missing / broken / not used on this
+OS), the resolved path, where it was found, and its version. Selecting a row
+also shows which packages use it.
+
+| Key | Action |
+|---|---|
+| **enter** | install (downloadable, missing) or re-check |
+| **e** | set a path (saved to `binary.json`) |
+| **d** | reset the entry to automatic (removes it from `binary.json`) |
+| **r** | re-check all entries |
+
 ## Agent state and herdr notifications
 
 ### Agent-state coordinator
@@ -160,3 +325,33 @@ const { runtime, cleanup } = createIsolatedRuntime();
 // ... exercise runtime against a temp agent dir ...
 cleanup();
 ```
+
+## Install
+
+```bash
+pi install npm:@xynogen/pix-runtime
+```
+
+> Foundation library. Feature packages install it as a dependency. Install it directly only when you build your own extension on it.
+
+Standalone-installable: importing an accessor lazily creates the singleton even
+without the extension factory. Installed via `pix-core` it registers `/pix` and
+session hooks once.
+
+## Full distro
+
+This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.
+
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.10.1",
+	"version": "0.12.2",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",
@@ -22,6 +22,7 @@
 	"exports": {
 		".": "./src/index.ts",
 		"./atomic-write": "./src/atomic-write.ts",
+		"./binaries": "./src/binaries/index.ts",
 		"./config": "./src/runtime.ts",
 		"./sections": "./src/sections/index.ts",
 		"./collapse": "./src/collapse.ts",
@@ -29,7 +30,13 @@
 		"./io": "./src/io.ts",
 		"./lfid": "./src/lfid.ts",
 		"./once": "./src/once.ts",
+		"./paths": "./src/paths.ts",
+		"./platform": "./src/platform.ts",
 		"./testing": "./src/testing.ts",
+		"./exec": "./src/exec.ts",
+		"./os": "./src/os.ts",
+		"./audio": "./src/audio.ts",
+		"./safe-path": "./src/safe-path.ts",
 		"./which": "./src/which.ts"
 	},
 	"keywords": [

package/src/audio.ts

@@ -0,0 +1,298 @@
+/**
+ * audio.ts — microphones, recording and playback, one job per function.
+ *
+ * Packages ask for the job ("list microphones", "record", "play this file") and
+ * never see a program name or an OS branch. ffmpeg does every job it can:
+ * PulseAudio/PipeWire on Linux, AVFoundation/AudioToolbox on macOS, DirectShow
+ * on Windows. ffmpeg has no audio output on Windows, so playback there uses the
+ * built-in PowerShell MediaPlayer. No other audio binary exists.
+ */
+
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { type EnsureOptions, ensureTool, type ToolStatus } from "./binaries/ensure.ts";
+import { BinaryMissingError, lookupTool, resolveTool } from "./binaries/resolve.ts";
+import { runTool, runToolSync, spawnTool } from "./exec.ts";
+import type { OsOptions } from "./os.ts";
+import { tempDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export interface Microphone {
+	/** Device id for {@link startRecording}. "default" follows the system default. */
+	id: string;
+	/** Readable name, e.g. "Headset - Nokia E1200 ANC". */
+	label: string;
+}
+
+const SYSTEM_DEFAULT: Microphone = { id: "default", label: "System default" };
+
+/** The first entry names the system default input when the OS reports one. */
+function withDefault(inputs: Microphone[], system?: string): Microphone[] {
+	return [
+		{ id: "default", label: system ? `System default (${system})` : "System default" },
+		...inputs,
+	];
+}
+
+// ── Device lists (ffmpeg output parsers) ────────────────────────────────────
+
+/** "Built-in Audio Analog Stereo" → "Built-in Audio". The channel layout is noise here. */
+function product(description: string): string {
+	return description.replace(/\s+(Analog|Digital)?\s*(Mono|Stereo|Surround[\s\d.]*)$/i, "").trim();
+}
+
+/**
+ * Readable label: "<kind> - <product>", like a desktop sound menu.
+ * ponytail: ffmpeg gives only the name and description, not the form factor or
+ * port, so the kind is "Headset" for Bluetooth and "Microphone" otherwise.
+ */
+export function microphoneLabel(id: string, description: string): string {
+	const name = product(description || id);
+	// "... Digital Microphone" already names its kind. Skip the prefix.
+	if (/microphone|headset|webcam|\bmic\b/i.test(name)) return name;
+	return `${id.startsWith("bluez_") ? "Headset" : "Microphone"} - ${name}`;
+}
+
+/**
+ * Linux: `ffmpeg -sources pulse` (stdout), without output monitors.
+ * Rows look like `* <name> [<description>] (none)`. `*` marks the system default.
+ */
+export function parsePulseSources(output: string): Microphone[] {
+	let system: string | undefined;
+	const inputs: Microphone[] = [];
+	for (const [, star, id = "", description = ""] of output.matchAll(/^(\*)?\s*(\S+) \[(.*)\]/gm)) {
+		// An output monitor records what plays, not a microphone.
+		if (id.endsWith(".monitor")) continue;
+		const mic = { id, label: microphoneLabel(id, description) };
+		if (star) system = mic.label;
+		inputs.push(mic);
+	}
+	return withDefault(inputs, system);
+}
+
+/** Windows: `ffmpeg -list_devices true -f dshow -i dummy` (stderr). */
+export function parseDshowDevices(output: string): Microphone[] {
+	const names = [...output.matchAll(/"([^"]+)" \(audio\)/g)].map((m) => m[1] as string);
+	return withDefault(
+		names.map((name) => ({ id: name, label: name })),
+		names[0],
+	);
+}
+
+/** macOS: `ffmpeg -f avfoundation -list_devices true -i ""` (stderr), audio section only. */
+export function parseAvfoundationDevices(output: string): Microphone[] {
+	const audio = output.split(/AVFoundation audio devices:/)[1] ?? "";
+	const names = [...audio.matchAll(/\] \[\d+\] (.+?)(?:\s+\[uid:.*)?$/gm)].map((m) =>
+		(m[1] as string).trim(),
+	);
+	return withDefault(names.map((name) => ({ id: name, label: name })));
+}
+
+const LIST: Partial<Record<HostPlatform["os"], string[]>> = {
+	linux: ["-hide_banner", "-nostdin", "-sources", "pulse"],
+	win32: ["-hide_banner", "-nostdin", "-list_devices", "true", "-f", "dshow", "-i", "dummy"],
+	darwin: ["-hide_banner", "-nostdin", "-f", "avfoundation", "-list_devices", "true", "-i", ""],
+};
+
+/**
+ * Microphones for a picker. The first entry is always "default". Never
+ * downloads ffmpeg: without it, only the default shows.
+ */
+export async function listMicrophones(opts: OsOptions = {}): Promise<Microphone[]> {
+	const host = opts.host ?? currentPlatform();
+	const args = LIST[host.os];
+	if (!args || !resolveTool("ffmpeg", { ...opts, host })) return [SYSTEM_DEFAULT];
+	const r = await runTool("ffmpeg", args, { env: opts.env, host, timeoutMs: 5000 });
+	// -sources prints to stdout. The dshow and avfoundation lists exit 1 and print to stderr.
+	if (host.os === "linux") return r.code === 0 ? parsePulseSources(r.stdout) : [SYSTEM_DEFAULT];
+	return host.os === "win32" ? parseDshowDevices(r.stderr) : parseAvfoundationDevices(r.stderr);
+}
+
+// ── Recording ───────────────────────────────────────────────────────────────
+
+/**
+ * ffmpeg input args (`-f … -i …`) that record `device`. Sync, so a recording
+ * still starts on the keypress. dshow has no default device, so on Windows
+ * "default" maps to the first audio input (one ~0.3 s device scan).
+ */
+export function microphoneInput(device: string, opts: OsOptions = {}): string[] {
+	const host = opts.host ?? currentPlatform();
+	if (host.os === "linux") return ["-f", "pulse", "-i", device];
+	// avfoundation takes "<video>:<audio>". An empty video part records audio only.
+	if (host.os === "darwin") return ["-f", "avfoundation", "-i", `:${device}`];
+	if (host.os !== "win32") throw new Error(`microphone recording is not supported on ${host.os}`);
+	let name = device;
+	if (name === "default") {
+		const r = runToolSync("ffmpeg", LIST.win32 ?? [], { env: opts.env, host, timeoutMs: 5000 });
+		name = parseDshowDevices(r.stderr)[1]?.id ?? "";
+		if (!name) throw new Error("no microphone found (ffmpeg dshow lists no audio input)");
+	}
+	return ["-f", "dshow", "-i", `audio=${name}`];
+}
+
+const LEVEL_FILTER = "astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level";
+
+/** Mono 16 kHz wav with a per-frame RMS level on stderr. No `output` means meter only. */
+export function recordArgs(input: readonly string[], output?: string): string[] {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"info",
+		...input,
+		"-ac",
+		"1",
+		"-ar",
+		"16000",
+		"-af",
+		LEVEL_FILTER,
+		...(output ? ["-y", output] : ["-f", "null", "-"]),
+	];
+}
+
+/** The latest RMS level in dB from ffmpeg's log, or undefined for silence (-inf). */
+export function parseRmsDb(output: string): number | undefined {
+	const matches = [
+		...output.matchAll(/(?:RMS level dB:\s*|lavfi\.astats\.Overall\.RMS_level=)(-?\d+(?:\.\d+)?)/g),
+	];
+	const value = matches.at(-1)?.[1];
+	return value === undefined ? undefined : Number(value);
+}
+
+export interface RecordOptions extends OsOptions {
+	/** Input level in dB, about once per audio frame. */
+	onLevel?: (db: number) => void;
+	/** ffmpeg stopped before `stop()`, for example on a bad device. */
+	onExit?: (error: Error) => void;
+	/** Download progress when ffmpeg is missing. */
+	onStatus?: (s: ToolStatus) => void;
+	/** Meter only: stream the level and write nothing to disk. */
+	meterOnly?: boolean;
+}
+
+export interface Recording {
+	/** The wav file. Empty for a meter-only session. */
+	path: string;
+	/** Stop, wait for the file to close, and give the last level in dB. */
+	stop(): Promise<number | undefined>;
+}
+
+/**
+ * Recording starts on a keypress and must not block. A missing but
+ * downloadable ffmpeg starts a visible background download, and this call
+ * throws and asks the user to try again when the download ends.
+ */
+function requireFfmpeg(purpose: string, opts: OsOptions & Pick<EnsureOptions, "onStatus">): void {
+	if (resolveTool("ffmpeg", opts)) return;
+	const hit = lookupTool("ffmpeg", opts);
+	if (hit.state === "missing" && hit.downloadable) {
+		void ensureTool("ffmpeg", opts).catch(() => undefined);
+		throw new Error(
+			`${purpose} needs ffmpeg — downloading it now (~120 MB); try again when it finishes.`,
+		);
+	}
+	throw new BinaryMissingError("ffmpeg", hit.state, hit.hint, `${purpose} needs ffmpeg`);
+}
+
+/** Keep the end of the ffmpeg log for the error message. The level meter writes a line per frame. */
+const STDERR_TAIL = 4096;
+
+/** Record `device` to a temp wav, or only meter it with `meterOnly`. Call `stop()` to end. */
+export function startRecording(device: string, opts: RecordOptions = {}): Recording {
+	requireFfmpeg(opts.meterOnly ? "The microphone test" : "Microphone recording", opts);
+	const path = opts.meterOnly ? "" : join(tempDir(), `pix-stt-${randomUUID()}.wav`);
+	const child = spawnTool("ffmpeg", recordArgs(microphoneInput(device, opts), path || undefined), {
+		env: opts.env,
+		host: opts.host,
+		stdio: ["pipe", "ignore", "pipe"],
+	});
+	let stderr = "";
+	let lastLevel: number | undefined;
+	child.stderr.on("data", (data) => {
+		const text = String(data);
+		stderr = (stderr + text).slice(-STDERR_TAIL);
+		const level = parseRmsDb(text);
+		if (level === undefined) return;
+		lastLevel = level;
+		opts.onLevel?.(level);
+	});
+	let stopping = false;
+	const exit = new Promise<void>((resolve, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code) =>
+			code === 0 ? resolve() : reject(new Error(stderr.trim() || `ffmpeg exited ${code}`)),
+		);
+	});
+	exit.then(
+		() =>
+			stopping ? undefined : opts.onExit?.(new Error("ffmpeg stopped before the recording ended")),
+		(error: Error) => (stopping ? undefined : opts.onExit?.(error)),
+	);
+	// An exited ffmpeg closes stdin. A late write must not crash Pi with EPIPE.
+	child.stdin.on("error", () => undefined);
+	return {
+		path,
+		async stop() {
+			stopping = true;
+			if (child.exitCode === null && child.signalCode === null) {
+				// "q" makes ffmpeg finish the wav header. A kill would leave a broken file.
+				child.stdin.write("q");
+				child.stdin.end();
+			}
+			await exit.catch((error) => {
+				if (!opts.meterOnly) throw error;
+			});
+			return lastLevel;
+		},
+	};
+}
+
+// ── Playback ────────────────────────────────────────────────────────────────
+
+/**
+ * Windows: WPF MediaPlayer plays mp3/wav with no extra install.
+ * ponytail: waits NaturalDuration + 200 ms. If the end cuts off, raise the pad.
+ */
+function mediaPlayerScript(path: string): string {
+	return [
+		"Add-Type -AssemblyName PresentationCore",
+		"$p = New-Object System.Windows.Media.MediaPlayer",
+		`$p.Open([uri]'${path.replace(/'/g, "''")}')`,
+		"for ($i = 0; -not $p.NaturalDuration.HasTimeSpan -and $i -lt 200; $i++) { Start-Sleep -Milliseconds 50 }",
+		"if (-not $p.NaturalDuration.HasTimeSpan) { exit 1 }",
+		"$p.Play()",
+		"Start-Sleep -Milliseconds ($p.NaturalDuration.TimeSpan.TotalMilliseconds + 200)",
+		"$p.Close()",
+	].join("; ");
+}
+
+/** `[program, ...args]` that plays `path` once on `host`, or undefined when the OS has no player. */
+export function playCommand(path: string, host: HostPlatform): string[] | undefined {
+	// -re sends samples at the real rate, so ffmpeg exits when the sound ends.
+	const ffmpeg = ["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "error", "-re", "-i", path];
+	if (host.os === "linux") return [...ffmpeg, "-f", "pulse", "pix"];
+	if (host.os === "darwin") return [...ffmpeg, "-f", "audiotoolbox", "-"];
+	if (host.os === "win32")
+		return ["powershell", "-NoProfile", "-NonInteractive", "-Command", mediaPlayerScript(path)];
+	return undefined;
+}
+
+export interface PlayOptions extends OsOptions {
+	signal?: AbortSignal;
+	/** Download progress when ffmpeg is missing. */
+	onStatus?: (s: ToolStatus) => void;
+}
+
+/** Play an audio file once. Resolves when playback ends. */
+export async function playAudio(path: string, opts: PlayOptions = {}): Promise<void> {
+	const host = opts.host ?? currentPlatform();
+	const [name, ...args] = playCommand(path, host) ?? [];
+	if (!name) throw new Error(`audio playback is not supported on ${host.os}`);
+	const r = await runTool(name, args, {
+		env: opts.env,
+		host,
+		signal: opts.signal,
+		onStatus: opts.onStatus,
+	});
+	if (r.code !== 0)
+		throw new Error(r.stderr.trim() || `${name} exited with code ${r.code ?? "unknown"}`);
+}