picopilot 0.1.5 → 0.2.0

package/src/engine/pico8/shell.ts

@@ -4,6 +4,8 @@ import {
 	mkdirSync,
 	mkdtempSync,
 	readdirSync,
+	readFileSync,
+	rmSync,
 	statSync,
 } from 'node:fs';
 import {tmpdir} from 'node:os';
@@ -21,8 +23,19 @@ import {
 	type Pico8Result,
 	RECORD_WAV_BASENAME,
 	type RecordOptions,
+	type RecordReport,
 	type RunOptions,
 } from './adapter.js';
+import {
+	DEFAULT_DISPLAY_MODE,
+	type DisplayMode,
+	findExecutable,
+	needsVirtualDisplay,
+	startVirtualDisplay,
+	type VirtualDisplayDeps,
+} from './display.js';
+import {overlayEnv} from '../child-env.js';
+import {killOnAbort} from './cleanup.js';
 import {SentinelWatcher} from './sentinel.js';
 
 /**
@@ -30,13 +43,15 @@ import {SentinelWatcher} from './sentinel.js';
  * delivers stdout chunks (both `stdout` and `stderr` folded in, since PICO-8's
  * `printh` and its own lines can land on either); `onClose` fires when the
  * process exits on its own; `onError` fires on a spawn failure (ENOENT ⇒ PICO-8
- * absent). `kill` terminates the process tree (the backstop / sentinel kill).
+ * absent). `kill` terminates the process tree (the backstop / sentinel kill),
+ * with SIGKILL unless a gentler `signal` is given (the `xvfb-run` fallback is
+ * first sent SIGTERM so Xvfb can remove its lock file and socket).
  */
 export interface Pico8Process {
 	onStdout(cb: (chunk: string) => void): void;
 	onClose(cb: (code: number | null) => void): void;
 	onError(cb: (err: NodeJS.ErrnoException) => void): void;
-	kill(): void;
+	kill(signal?: NodeJS.Signals): void;
 	/**
 	 * Writes raw bytes to the process's stdin, for the `drive` transport (the
 	 * fixed-size command blocks). Absent/undefined when stdin was detached
@@ -95,6 +110,76 @@ export function withPico8Home(args: string[]): string[] {
 	return ['-home', home, ...args];
 }
 
+/**
+ * The environment PICO-8 is spawned with: the parent env overlaid with the
+ * picopilot-resolved values ({@link overlayEnv}). A `-run` session cannot open a
+ * window or an audio device without DISPLAY, HOME, XDG_RUNTIME_DIR, SDL_*, ...
+ */
+export function pico8ChildEnv(
+	resolved: Readonly<Record<string, string | undefined>>,
+	parent: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+	return overlayEnv(resolved, parent);
+}
+
+/**
+ * A private `XDG_RUNTIME_DIR` (mode 0700, one per picopilot process) for a
+ * PICO-8 launched without one. SDL logs "XDG_RUNTIME_DIR is invalid or not set"
+ * otherwise, which is noise in every headless report.
+ */
+let cachedRuntimeDir: string | undefined;
+export function pico8RuntimeDir(): string {
+	if (cachedRuntimeDir !== undefined && existsSync(cachedRuntimeDir)) {
+		return cachedRuntimeDir;
+	}
+	cachedRuntimeDir = mkdtempSync(join(tmpdir(), 'picopilot-xdg-runtime-'));
+	return cachedRuntimeDir;
+}
+
+/** `env` with a private {@link pico8RuntimeDir} filled in when XDG_RUNTIME_DIR is absent. */
+export function withRuntimeDir(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const current = env.XDG_RUNTIME_DIR;
+	if (current !== undefined && current.trim() !== '') return env;
+	return {...env, XDG_RUNTIME_DIR: pico8RuntimeDir()};
+}
+
+/** How many lines of PICO-8's `log.txt` a failed record reports. */
+const LOG_TAIL_LINES = 25;
+
+/** The last lines of PICO-8's `log.txt` in the isolated `-home`, or undefined if absent. */
+export function readPico8LogTail(
+	home: string = pico8HomeDir(),
+	lines: number = LOG_TAIL_LINES,
+): string | undefined {
+	try {
+		const text = readFileSync(join(home, 'log.txt'), 'utf8');
+		const all = text.trimEnd().split('\n');
+		return all.slice(-lines).join('\n');
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Says WHY a record run produced no WAV, from how it ended. The sentinel is the
+ * harness's last act (after `audio_end`), so anything other than a sentinel
+ * means the harness never finished; a sentinel with no WAV means `audio_end`
+ * saved nothing usable.
+ */
+export function explainNoWav(
+	exitReason: ExitReason,
+	ctx: {backstopMs: number; wavDir: string; basename: string},
+): string {
+	switch (exitReason) {
+		case 'timeout':
+			return `the backstop fired after ${ctx.backstopMs}ms before the record harness printed its done-sentinel: the cart never reached audio_end (it failed to load, errored at runtime, or its game loop never ran). See pico8LogTail and printh.`;
+		case 'exit':
+			return 'PICO-8 exited before the record harness printed its done-sentinel: the cart failed to load or crashed, or PICO-8 itself could not start (e.g. no display or audio device). See pico8LogTail and printh.';
+		case 'sentinel':
+			return `the record harness reached its done-sentinel but no non-empty ${ctx.basename}.wav was written to ${ctx.wavDir}: audio_end saved nothing usable (an empty 0-frame capture).`;
+	}
+}
+
 export const spawnRunner: SpawnRunner = (file, args, env, options) => {
 	// `drive` pipes fixed-size command blocks to stdin; `run`/`record` detach it so
 	// the cart never blocks on console input.
@@ -124,12 +209,12 @@ export const spawnRunner: SpawnRunner = (file, args, env, options) => {
 				// A closed stdin (the cart exited) is not fatal to the run.
 			}
 		},
-		kill() {
+		kill(signal = 'SIGKILL') {
 			try {
 				// Negative pid kills the process GROUP (detached), so any child dies too.
-				if (child.pid !== undefined) process.kill(-child.pid, 'SIGKILL');
+				if (child.pid !== undefined) process.kill(-child.pid, signal);
 			} catch {
-				child.kill('SIGKILL'); // fall back to killing just the process
+				child.kill(signal); // fall back to killing just the process
 			}
 		},
 	};
@@ -202,8 +287,24 @@ export interface ShellPico8Options {
 	readonly env: NodeJS.ProcessEnv;
 	/** The spawn runner (defaults to {@link spawnRunner}); tests inject a fake. */
 	readonly spawn?: SpawnRunner;
+	/**
+	 * The display mode for `-run` sessions (ADR-0017; defaults to `auto`). Only
+	 * {@link ShellPico8Adapter.record} consults it: the `-x` paths never need a
+	 * display and never start one.
+	 */
+	readonly display?: DisplayMode;
+	/** The virtual-display dependencies (Xvfb lookup + spawn); tests inject fakes. */
+	readonly virtualDisplay?: VirtualDisplayDeps;
+	/**
+	 * How long a gracefully-ended run (the `xvfb-run` fallback) gets between
+	 * SIGTERM and SIGKILL, in ms (default {@link DEFAULT_KILL_GRACE_MS}).
+	 */
+	readonly killGraceMs?: number;
 }
 
+/** The default SIGTERM-to-SIGKILL grace for a gracefully-ended run. */
+export const DEFAULT_KILL_GRACE_MS = 2_000;
+
 /**
  * The v1 {@link Pico8Adapter}: shells out to the user's native `pico8 -x`
  * (ADR-0006, native path first). It owns the ORCHESTRATION the command should
@@ -217,10 +318,16 @@ export interface ShellPico8Options {
 export class ShellPico8Adapter implements Pico8Adapter {
 	private readonly env: NodeJS.ProcessEnv;
 	private readonly spawnRun: SpawnRunner;
+	private readonly display: DisplayMode;
+	private readonly virtualDisplay: VirtualDisplayDeps;
+	private readonly killGraceMs: number;
 
 	constructor(options: ShellPico8Options) {
+		this.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
 		this.env = options.env;
 		this.spawnRun = options.spawn ?? spawnRunner;
+		this.display = options.display ?? DEFAULT_DISPLAY_MODE;
+		this.virtualDisplay = options.virtualDisplay ?? {};
 	}
 
 	run(options: RunOptions): Promise<Pico8Result> {
@@ -322,24 +429,95 @@ export class ShellPico8Adapter implements Pico8Adapter {
 	}
 
 	record(options: RecordOptions): Promise<Pico8RecordResult> {
+		if (needsVirtualDisplay(this.display, this.env)) {
+			return this.recordOnVirtualDisplay(options);
+		}
+		return this.recordWith(options, 'native');
+	}
+
+	/**
+	 * The record session on a private virtual display (ADR-0017): start Xvfb
+	 * (or fall back to `xvfb-run`), run PICO-8 on it with a dummy SDL audio
+	 * driver (unless the caller chose one; `audio_rec` captures PICO-8's own
+	 * mixer, not the device), and ALWAYS stop the display afterwards, however
+	 * the run ended (sentinel, backstop, crash, spawn failure).
+	 */
+	private async recordOnVirtualDisplay(
+		options: RecordOptions,
+	): Promise<Pico8RecordResult> {
+		const [file] = pico8Candidates(this.env) as [string, ...string[]];
+		// Absent PICO-8 is reported as such BEFORE paying for (or failing on) a
+		// display, and wrapped in xvfb-run a missing binary would not ENOENT.
+		const find = this.virtualDisplay.find ?? findExecutable;
+		if (find(file, this.env) === undefined) return pico8NotFound();
+
+		const started = await startVirtualDisplay(this.env, this.virtualDisplay);
+		if (!started.ok) return started;
+		const vd = started.display;
+		try {
+			const env: NodeJS.ProcessEnv = {...this.env, ...vd.env};
+			const audioDriver = env.SDL_AUDIODRIVER;
+			if (audioDriver === undefined || audioDriver.trim() === '') {
+				env.SDL_AUDIODRIVER = 'dummy';
+			}
+			return await this.recordWith(options, vd.backend, {
+				env,
+				wrap: (f, a) => vd.wrap(f, a),
+				// xvfb-run's Xvfb lives in PICO-8's process group: SIGTERM first so it
+				// removes its /tmp/.X<n>-lock and socket (a SIGKILL leaves them behind).
+				endGracefully: vd.backend === 'xvfb-run',
+			});
+		} finally {
+			await vd.stop();
+		}
+	}
+
+	/** The record launch itself, natively or under a virtual display's env/wrapper. */
+	private recordWith(
+		options: RecordOptions,
+		display: RecordReport['display'],
+		launch?: {
+			env: NodeJS.ProcessEnv;
+			wrap: (file: string, args: string[]) => {file: string; args: string[]};
+			endGracefully?: boolean;
+		},
+	): Promise<Pico8RecordResult> {
 		const [file] = pico8Candidates(this.env) as [string, ...string[]];
 		const basename = options.wavBasename ?? RECORD_WAV_BASENAME;
 		// `-root_path <wavDir>` steers the `audio_end(1)`-to-current-folder WAV into
 		// the isolated temp dir (never ~/Desktop or the carts root). `-run` is a real
 		// A/V session (recording needs audio to capture; `-x` yields an empty WAV).
 		const args = ['-root_path', options.wavDir, '-run', options.cartPath];
+		// The `-home` is shared by every launch in this process: drop the previous
+		// log.txt so a failed record never reports another run's log as its own.
+		rmSync(join(pico8HomeDir(), 'log.txt'), {force: true});
 		return this.orchestrate<Pico8RecordResult>(
 			file,
 			args,
 			{sentinel: options.sentinel, backstopMs: options.backstopMs},
-			(exitReason, printh) => ({
-				ok: true,
-				value: {
-					wavPath: collectWav(options.wavDir, basename),
-					printh,
-					exitReason,
-				},
-			}),
+			(exitReason, printh) => {
+				const wavPath = collectWav(options.wavDir, basename);
+				if (wavPath !== undefined) {
+					return {ok: true, value: {wavPath, printh, exitReason, display}};
+				}
+				const pico8LogTail = readPico8LogTail();
+				return {
+					ok: true,
+					value: {
+						wavPath,
+						printh,
+						exitReason,
+						display,
+						noWavReason: explainNoWav(exitReason, {
+							backstopMs: options.backstopMs,
+							wavDir: options.wavDir,
+							basename,
+						}),
+						...(pico8LogTail !== undefined ? {pico8LogTail} : {}),
+					},
+				};
+			},
+			launch,
 		);
 	}
 
@@ -356,22 +534,72 @@ export class ShellPico8Adapter implements Pico8Adapter {
 		args: string[],
 		opts: {sentinel?: string; backstopMs: number},
 		buildOk: (exitReason: ExitReason, printh: string) => R,
-		spawnOpts?: {stdin?: boolean; onSpawn?: (proc: Pico8Process) => void},
+		spawnOpts?: {
+			stdin?: boolean;
+			onSpawn?: (proc: Pico8Process) => void;
+			/** The child env (defaults to the adapter's); a virtual display adds DISPLAY etc. */
+			env?: NodeJS.ProcessEnv;
+			/** Rewrites the launch (the `xvfb-run` fallback wraps the PICO-8 command). */
+			wrap?: (file: string, args: string[]) => {file: string; args: string[]};
+			/**
+			 * End the run with SIGTERM, then SIGKILL after the grace period, and wait
+			 * for the process to close before resolving (default: an immediate SIGKILL).
+			 */
+			endGracefully?: boolean;
+		},
 	): Promise<R | ReturnType<typeof pico8NotFound>> {
 		const watcher = new SentinelWatcher(opts.sentinel);
 
 		return new Promise<R | ReturnType<typeof pico8NotFound>>((resolve) => {
 			let settled = false;
 			let backstop: NodeJS.Timeout | undefined;
-			const proc = this.spawnRun(file, withPico8Home(args), this.env, {
-				stdin: spawnOpts?.stdin,
-			});
+			const homeArgs = withPico8Home(args);
+			const launch =
+				spawnOpts?.wrap !== undefined
+					? spawnOpts.wrap(file, homeArgs)
+					: {file, args: homeArgs};
+			const proc = this.spawnRun(
+				launch.file,
+				launch.args,
+				withRuntimeDir(spawnOpts?.env ?? this.env),
+				{stdin: spawnOpts?.stdin},
+			);
+
+			// If picopilot itself is stopped mid-run, take PICO-8 down with it.
+			const disposeAbort = killOnAbort(() => proc.kill());
+			let onClosed: (() => void) | undefined;
 
-			const finish = (exitReason: ExitReason): void => {
+			/**
+			 * Ends the run once. `kill` = PICO-8 is still running (sentinel/backstop):
+			 * SIGKILL its group, or for a graceful end SIGTERM it and resolve when it
+			 * has closed (SIGKILL after the grace period).
+			 */
+			const finish = (exitReason: ExitReason, kill = false): void => {
 				if (settled) return;
 				settled = true;
 				if (backstop !== undefined) clearTimeout(backstop);
-				resolve(buildOk(exitReason, watcher.text));
+				let resolved = false;
+				const done = () => {
+					if (resolved) return;
+					resolved = true;
+					// Only now: a signal during the graceful wait must still kill PICO-8.
+					disposeAbort();
+					resolve(buildOk(exitReason, watcher.text));
+				};
+				if (!kill) return done();
+				if (spawnOpts?.endGracefully !== true) {
+					proc.kill();
+					return done();
+				}
+				proc.kill('SIGTERM');
+				const hard = setTimeout(() => {
+					proc.kill();
+					done();
+				}, this.killGraceMs);
+				onClosed = () => {
+					clearTimeout(hard);
+					done();
+				};
 			};
 
 			proc.onError((err) => {
@@ -381,6 +609,7 @@ export class ShellPico8Adapter implements Pico8Adapter {
 				if (settled) return;
 				if (err.code === 'ENOENT') {
 					settled = true;
+					disposeAbort();
 					if (backstop !== undefined) clearTimeout(backstop);
 					resolve(pico8NotFound());
 				} else {
@@ -389,13 +618,14 @@ export class ShellPico8Adapter implements Pico8Adapter {
 			});
 
 			proc.onStdout((chunk) => {
-				if (watcher.push(chunk) && !settled) {
-					proc.kill(); // sentinel matched: end the run promptly
-					finish('sentinel');
-				}
+				// sentinel matched: end the run promptly
+				if (watcher.push(chunk) && !settled) finish('sentinel', true);
 			});
 
-			proc.onClose(() => finish('exit')); // PICO-8 exited on its own
+			proc.onClose(() => {
+				if (onClosed !== undefined) return onClosed();
+				finish('exit'); // PICO-8 exited on its own
+			});
 
 			// For `drive`: write the command blocks to the live stdin now that it is
 			// spawned. A spawn ENOENT resolves via onError before this matters.
@@ -404,8 +634,7 @@ export class ShellPico8Adapter implements Pico8Adapter {
 			// Backstop: a cart that neither signals nor exits gets killed.
 			backstop = setTimeout(() => {
 				if (settled) return;
-				proc.kill();
-				finish('timeout');
+				finish('timeout', true);
 			}, opts.backstopMs);
 		});
 	}

package/src/engine/pico8/virtual-display.process.test.ts

@@ -0,0 +1,206 @@
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {spawn} from 'node:child_process';
+import {createRequire} from 'node:module';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {DONE_SENTINEL} from './adapter.js';
+import {findExecutable} from './display.js';
+import {ShellPico8Adapter} from './shell.js';
+
+/** An absolute `sleep` (the scripts run with a minimal PATH; NixOS has no /bin/sleep). */
+const SLEEP = findExecutable('sleep', process.env) ?? '/bin/sleep';
+
+/**
+ * The no-stray-process guarantee (ADR-0017), proven with REAL processes: a fake
+ * `Xvfb` (a shell script honouring `-displayfd 3`) and a fake `pico8` (a shell
+ * script that prints the sentinel, hangs, or crashes), spawned by the real
+ * spawners. After every record run, BOTH pids must be gone. POSIX-only (sh).
+ */
+
+let dir: string;
+let pidDir: string;
+
+/** Writes an executable shell script. */
+function script(name: string, body: string): string {
+	const path = join(dir, name);
+	writeFileSync(path, `#!/bin/sh\n${body}\n`);
+	chmodSync(path, 0o755);
+	return path;
+}
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-vd-proc-'));
+	pidDir = join(dir, 'pids');
+	mkdirSync(pidDir);
+	// The fake X server: record its pid, report display 77 on fd 3, then idle.
+	script(
+		'Xvfb',
+		`echo $$ > "$FAKE_PID_DIR/xvfb.pid"\necho 77 >&3\nexec ${SLEEP} 15`,
+	);
+	// The fake PICO-8: record its pid and DISPLAY, then behave per FAKE_MODE.
+	script(
+		'pico8',
+		[
+			'echo $$ > "$FAKE_PID_DIR/pico8.pid"',
+			'echo "$DISPLAY" > "$FAKE_PID_DIR/display"',
+			'case "$FAKE_MODE" in',
+			`  sentinel) echo ${DONE_SENTINEL}; exec ${SLEEP} 15;;`,
+			`  hang) exec ${SLEEP} 15;;`,
+			'  crash) exit 3;;',
+			'esac',
+		].join('\n'),
+	);
+});
+
+afterEach(() => {
+	// If an assertion failed before the run cleaned up, never leave the fake
+	// Xvfb / PICO-8 behind (they are `sleep`s, but still strays).
+	for (const name of ['xvfb', 'pico8']) {
+		const pid = readPid(name);
+		if (pid !== undefined && Number.isInteger(pid) && pid > 0) {
+			try {
+				process.kill(pid, 'SIGKILL');
+			} catch {
+				// already gone (the expected case)
+			}
+		}
+	}
+	rmSync(dir, {recursive: true, force: true});
+});
+
+/** Whether a pid is still alive (signal 0 probes without killing). */
+function alive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Waits (bounded) for a pid to disappear; the kernel may lag the kill slightly. */
+async function gone(pid: number): Promise<boolean> {
+	for (let i = 0; i < 100; i++) {
+		if (!alive(pid)) return true;
+		await new Promise((r) => setTimeout(r, 20));
+	}
+	return false;
+}
+
+function readPid(name: string): number | undefined {
+	const p = join(pidDir, `${name}.pid`);
+	if (!existsSync(p)) return undefined;
+	const pid = Number(readFileSync(p, 'utf8').trim());
+	return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+function adapter(mode: string, pico8 = join(dir, 'pico8')) {
+	return new ShellPico8Adapter({
+		display: 'xvfb',
+		env: {
+			PATH: `${dir}:/usr/bin:/bin`,
+			PICO8_PATH: pico8,
+			FAKE_PID_DIR: pidDir,
+			FAKE_MODE: mode,
+		},
+	});
+}
+
+describe.skipIf(process.platform === 'win32')(
+	'virtual display with real processes: nothing is left behind',
+	() => {
+		for (const [mode, backstopMs, exitReason] of [
+			['sentinel', 10_000, 'sentinel'],
+			['hang', 300, 'timeout'],
+			['crash', 10_000, 'exit'],
+		] as const) {
+			it(`${mode}: PICO-8 saw the virtual DISPLAY, and both it and Xvfb are gone`, async () => {
+				const result = await adapter(mode).record({
+					cartPath: join(dir, 'h.p8'),
+					wavDir: dir,
+					backstopMs,
+				});
+				expect(result.ok).toBe(true);
+				if (result.ok) {
+					expect(result.value.exitReason).toBe(exitReason);
+					expect(result.value.display).toBe('Xvfb');
+				}
+				expect(readFileSync(join(pidDir, 'display'), 'utf8').trim()).toBe(
+					':77',
+				);
+				const xvfb = readPid('xvfb');
+				const pico8 = readPid('pico8');
+				expect(xvfb).toBeDefined();
+				expect(pico8).toBeDefined();
+				expect(await gone(xvfb!)).toBe(true);
+				expect(await gone(pico8!)).toBe(true);
+			});
+		}
+
+		it('spawn failure: PICO-8 cannot exec, and Xvfb is still stopped', async () => {
+			// Executable, so the pre-flight lookup finds it, but its interpreter does
+			// not exist, so the spawn itself fails (ENOENT) after Xvfb is up.
+			const broken = join(dir, 'broken-pico8');
+			writeFileSync(broken, '#!/nonexistent/interpreter\n');
+			chmodSync(broken, 0o755);
+			const result = await adapter('sentinel', broken).record({
+				cartPath: join(dir, 'h.p8'),
+				wavDir: dir,
+				backstopMs: 10_000,
+			});
+			expect(!result.ok && result.reason).toBe('pico8-not-found');
+			const xvfb = readPid('xvfb');
+			expect(xvfb).toBeDefined();
+			expect(await gone(xvfb!)).toBe(true);
+		});
+
+		it('picopilot itself killed mid-run (SIGTERM): PICO-8 and Xvfb die with it', async () => {
+			// A separate node process runs the record (hanging cart); we SIGTERM it
+			// once both children are up, as an agent harness or `timeout` would.
+			const tsx = createRequire(import.meta.url).resolve('tsx');
+			const shell = new URL('./shell.ts', import.meta.url).pathname;
+			const code = `
+				const {ShellPico8Adapter} = await import(${JSON.stringify(shell)});
+				await new ShellPico8Adapter({display: 'xvfb', env: ${JSON.stringify({
+					PATH: `${dir}:/usr/bin:/bin`,
+					PICO8_PATH: join(dir, 'pico8'),
+					FAKE_PID_DIR: pidDir,
+					FAKE_MODE: 'hang',
+				})}}).record({cartPath: 'h.p8', wavDir: ${JSON.stringify(dir)}, backstopMs: 60000});
+			`;
+			const child = spawn(
+				process.execPath,
+				['--import', tsx, '--input-type=module', '-e', code],
+				{stdio: 'ignore'},
+			);
+			const exited = new Promise((r) => child.on('exit', r));
+			try {
+				for (let i = 0; i < 250 && readPid('pico8') === undefined; i++) {
+					await new Promise((r) => setTimeout(r, 20));
+				}
+				const xvfb = readPid('xvfb');
+				const pico8 = readPid('pico8');
+				expect(xvfb).toBeDefined();
+				expect(pico8).toBeDefined();
+				child.kill('SIGTERM');
+				await exited;
+				expect(await gone(xvfb!)).toBe(true);
+				expect(await gone(pico8!)).toBe(true);
+			} finally {
+				// Never leave the runner process behind if an assertion failed.
+				if (child.exitCode === null && child.signalCode === null) {
+					child.kill('SIGKILL');
+				}
+			}
+		}, 15_000);
+	},
+);

package/src/engine/shrinko/shell.ts

@@ -41,9 +41,9 @@ export type ChildRunner = (
  * The default {@link ChildRunner}: an `execFile` that captures stdout/stderr and
  * NEVER rejects. A failed spawn (ENOENT) becomes `spawnError`; a nonzero exit
  * becomes a `code`, so both outcomes are data the adapter maps to a structured
- * result. The child inherits ONLY the `env` it is handed (the command layer
- * passes the incur-resolved env, whose `PATH` a test can override) so there is
- * no ambient-environment leak.
+ * result. The child gets exactly the `env` it is handed and reads nothing
+ * ambiently; the command layer builds that env as the parent env overlaid with
+ * the resolved `PATH` (`commands/shrinko-env.ts`), and a test injects its own.
  */
 export const execFileRunner: ChildRunner = (file, args, env) =>
 	new Promise((resolve) => {

package/src/skills/picopilot-audio/SKILL.md

@@ -46,11 +46,7 @@ These steps are wired as CTAs (a merged SFX or song points you at `verify` then
 
 ## `audio render` / `audio record`: get a WAV by RECORDING (ADR-0009)
 
-PICO-8 has NO working offline WAV export (it SIGFPEs upstream), so picopilot gets
-audio-to-WAV the only way that works: by RECORDING a running session
-(`extcmd("audio_rec")`/`audio_end`). Two commands, both PICO-8-gated and both
-REAL-TIME recordings that need a real audio+video session (a developer machine,
-NOT headless CI), NOT deterministic offline exports:
+PICO-8 has NO working offline WAV export (it SIGFPEs upstream), so picopilot gets audio-to-WAV the only way that works: by RECORDING a running session (`extcmd("audio_rec")`/`audio_end`). Two commands, both PICO-8-gated and both REAL-TIME recordings of playback, NOT deterministic offline exports. They work headless (no display, no sound card): PICO-8 records its own mixer, not the audio device, and when there is no display picopilot runs the session on a private virtual display by itself (ADR-0017). You do not need to do anything for that.
 
 - **`picopilot audio render`** injects a THROWAWAY play-harness for a chosen
   target and records it, so you write NO playback code. Pick the target with
@@ -68,9 +64,9 @@ The WAV goes to an isolated dir (`--wav-dir`, default a temp dir), never
 `~/Desktop` or the carts root (the `audio_end(1)`-saves-to-the-current-folder
 trap; picopilot steers it with PICO-8's `root_path`). PICO-8 absent -> a
 structured `pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`), never a
-crash. On a headless machine the recording succeeds but captures NO audio
-(`captured:false` + a nudge to run on a machine with a display + audio device):
-that is honest, not a failure of the recipe.
+crash.
+
+When a recording produces no WAV (`captured:false`), the result says why: `noAudioReason` (the backstop fired before the recorder finished, PICO-8 exited early, or the capture was empty) and `pico8LogTail` (the end of PICO-8's own log, where load errors show up). Read both before retrying; a cart that fails to load never reaches the end of the recording, so run `picopilot verify` on it. If the machine has no display AND no Xvfb, the command fails up front with `display-unavailable`, whose message names the package to install; `picopilot doctor` reports the same thing before you try.
 
 ## `sfx from-mml`: one MML string -> one SFX slot
 

package/src/skills/picopilot-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picopilot-overview
-description: Start here for any PICO-8 cart built with picopilot. The #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
+description: Start here for any PICO-8 cart built with picopilot. Call picopilot doctor first to learn what this machine can do (everything works headless), then the #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
 ---
 
 # picopilot overview
@@ -13,6 +13,14 @@ acceptance gate, so you can build a PICO-8 game and self-correct.
 Load this skill first. Then load the group skill for whatever you are doing:
 `picopilot-code`, `picopilot-art`, `picopilot-audio`, or `picopilot-debug`.
 
+## First on a new machine: `picopilot doctor`
+
+Run `picopilot doctor` before anything else on a machine you have not used yet. It reports what THIS machine can do: whether PICO-8 is found and actually runs (with its version), whether shrinko8 is found, how a PICO-8 audio session would get a display, and the resulting `available` / `unavailable` command lists (each unavailable command says what it is missing). Plan from that list instead of discovering limits by failing.
+
+Every picopilot command works on a machine with no display and no sound card (a server, CI, an agent sandbox). Screenshots, `playtest` and `export` run PICO-8 headless. Audio recording (`audio render`, `audio record`, `run --record-audio`) needs a real PICO-8 session with a window, and picopilot provides one by itself: with the default display mode `auto`, when there is no display it starts a private virtual display for that recording and removes it afterwards. You do not need to set anything up. Only if `doctor` lists the audio commands as unavailable with `missing: display` (or a recording fails with `display-unavailable`) does the machine lack Xvfb; the error names the install command to suggest to the human.
+
+The display mode can be forced with `--display xvfb` (always virtual) or `--display native` (use the current display as-is), also settable as `PICOPILOT_DISPLAY` or `"display"` in `picopilot.json` (when picopilot runs as an MCP server, only `PICOPILOT_DISPLAY` in the server's environment applies). Leave it at `auto` unless a human asks otherwise.
+
 ## The #include discipline (how every picopilot cart is laid out)
 
 - `main.p8` is the cart. Its `__lua__` section is a single line: `#include main.lua`.