picopilot 0.1.4 → 0.2.0

package/src/engine/gfx/label.ts

@@ -1,5 +1,6 @@
 /**
- * The `__label__` builder: turn a 128x128 image into the hex a `.p8` cart's
+ * The `__label__` builder: turn a 128x128 image (or a PICO-8 screenshot, an
+ * integer upscale of one) into the hex a `.p8` cart's
  * label section holds, so `picopilot export --label <png>` can give a labelless
  * cart a loading splash WITHOUT an interactive PICO-8 (F7) capture.
  *
@@ -9,10 +10,13 @@
  * palette colour, and emits that hex. It is the inverse direction of the
  * palette-accurate PNG RENDER in `render.ts`/`png.ts` (which goes indices -> RGB).
  *
- * It intentionally supports only the PNG subset a caller realistically produces
- * for a 128x128 label: 8-bit, non-interlaced, colour types 2 (RGB) and 6 (RGBA),
- * and (via the palette map) 0/3 are rejected with a clear error rather than
- * guessed at. Anything else fails loud with a structured {@link LabelError}.
+ * It accepts what a caller realistically hands it: a PICO-8 screenshot exactly as
+ * `picopilot run`/`playtest` captured it (384x384 8-bit RGB by default; any
+ * square integer multiple of 128 is sampled back down), or a 128x128 image from
+ * any tool, including palette-indexed (1/2/4/8-bit, the form image tools write
+ * when shrinking a screenshot) and greyscale PNGs. Interlaced PNGs, sizes that
+ * are not a square multiple of 128, and malformed files are rejected, loud, with
+ * a structured {@link LabelError}.
  */
 
 import {inflateSync} from 'node:zlib';
@@ -42,12 +46,37 @@ interface DecodedPng {
 	readonly rgba: Uint8Array;
 }
 
+/** Samples per pixel for each PNG colour type we decode. */
+const CHANNELS: Readonly<Record<number, number>> = {
+	0: 1, // greyscale
+	2: 3, // RGB
+	3: 1, // palette index
+	4: 2, // greyscale + alpha
+	6: 4, // RGBA
+};
+
+/** The bit depths the PNG spec allows per colour type. */
+const ALLOWED_DEPTHS: Readonly<Record<number, readonly number[]>> = {
+	0: [1, 2, 4, 8, 16],
+	2: [8, 16],
+	3: [1, 2, 4, 8],
+	4: [8, 16],
+	6: [8, 16],
+};
+
 /**
- * Decodes an 8-bit, non-interlaced PNG (colour type 2 RGB or 6 RGBA) to RGBA.
+ * Decodes a non-interlaced PNG of any standard colour type and bit depth to
+ * RGBA: truecolour (2) and truecolour+alpha (6) at 8/16 bits, palette-indexed (3)
+ * at 1/2/4/8 bits via its PLTE chunk, and greyscale (0) / greyscale+alpha (4).
  * Uses `node:zlib` inflate for the IDAT stream and applies the five PNG scanline
- * filters. Throws {@link LabelError} for anything outside this subset.
+ * filters. `checkSize` runs on the IHDR dimensions before any pixel work. 16-bit samples keep their high byte (a label is quantised to 16
+ * colours anyway). Interlaced (Adam7) PNGs are rejected: PICO-8 never writes them.
+ * Throws {@link LabelError} for anything outside this set.
  */
-function decodePng(bytes: Uint8Array): DecodedPng {
+function decodePng(
+	bytes: Uint8Array,
+	checkSize: (width: number, height: number) => void = () => {},
+): DecodedPng {
 	for (let i = 0; i < PNG_SIGNATURE.length; i++) {
 		if (bytes[i] !== PNG_SIGNATURE[i]) {
 			throw new LabelError('not-a-png', 'not a PNG file (bad signature)');
@@ -60,6 +89,7 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 	let bitDepth = 0;
 	let colourType = 0;
 	let interlace = 0;
+	let palette: Uint8Array | undefined;
 	const idat: Uint8Array[] = [];
 
 	const readU32 = (p: number): number =>
@@ -88,6 +118,8 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 			bitDepth = bytes[dataStart + 8]!;
 			colourType = bytes[dataStart + 9]!;
 			interlace = bytes[dataStart + 12]!;
+		} else if (type === 'PLTE') {
+			palette = bytes.subarray(dataStart, dataEnd);
 		} else if (type === 'IDAT') {
 			idat.push(bytes.subarray(dataStart, dataEnd));
 		} else if (type === 'IEND') {
@@ -96,18 +128,28 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 		off = dataEnd + 4; // skip the 4-byte CRC
 	}
 
+	const channels = CHANNELS[colourType];
 	if (
-		bitDepth !== 8 ||
-		interlace !== 0 ||
-		(colourType !== 2 && colourType !== 6)
+		channels === undefined ||
+		!ALLOWED_DEPTHS[colourType]!.includes(bitDepth) ||
+		interlace !== 0
 	) {
 		throw new LabelError(
 			'unsupported-png',
-			`unsupported PNG: need 8-bit non-interlaced RGB or RGBA (got bitDepth=${bitDepth}, colourType=${colourType}, interlace=${interlace})`,
+			`unsupported PNG: need a non-interlaced greyscale, RGB, RGBA or palette-indexed image (got bitDepth=${bitDepth}, colourType=${colourType}, interlace=${interlace})`,
 		);
 	}
+	if (colourType === 3 && (palette === undefined || palette.length < 3)) {
+		throw new LabelError(
+			'unsupported-png',
+			'palette-indexed PNG has no PLTE chunk',
+		);
+	}
+
+	// Reject a wrong-sized image from its header alone, before inflating and
+	// decoding pixels we would throw away.
+	checkSize(width, height);
 
-	const channels = colourType === 6 ? 4 : 3;
 	const compressed = Buffer.concat(idat.map((c) => Buffer.from(c)));
 	let raw: Buffer;
 	try {
@@ -119,33 +161,57 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 		);
 	}
 
-	const stride = width * channels;
+	const bitsPerPixel = channels * bitDepth;
+	const stride = Math.ceil((width * bitsPerPixel) / 8);
+	// Filter byte distance: bytes per complete pixel, at least 1 (sub-byte depths).
+	const bpp = Math.max(1, bitsPerPixel >> 3);
+	if (raw.length < height * (stride + 1)) {
+		throw new LabelError(
+			'truncated-png',
+			`PNG image data too short for ${width}x${height}`,
+		);
+	}
+
+	// Reads sample `i` (0-based within the scanline) scaled to 0..255.
+	const maxSample = (1 << Math.min(bitDepth, 8)) - 1;
+	const sampleAt = (line: Uint8Array, i: number): number => {
+		if (bitDepth === 16) return line[i * 2]!;
+		if (bitDepth === 8) return line[i]!;
+		const bit = i * bitDepth;
+		const v = (line[bit >> 3]! >> (8 - bitDepth - (bit & 7))) & maxSample;
+		return v;
+	};
+	// Palette indices must stay raw; greyscale samples are scaled to 0..255.
+	const scaleGrey = (v: number): number =>
+		bitDepth >= 8 ? v : Math.round((v * 255) / maxSample);
+
 	const rgba = new Uint8Array(width * height * 4);
-	const prev = new Uint8Array(stride);
+	let prev = new Uint8Array(stride);
+	let line = new Uint8Array(stride);
 	let src = 0;
 	for (let y = 0; y < height; y++) {
 		const filter = raw[src++]!;
-		const line = new Uint8Array(stride);
 		for (let x = 0; x < stride; x++) {
 			const rawByte = raw[src++]!;
-			const a = x >= channels ? line[x - channels]! : 0; // left
+			const a = x >= bpp ? line[x - bpp]! : 0; // left
 			const b = prev[x]!; // up
-			const c = x >= channels ? prev[x - channels]! : 0; // up-left
-			let val = rawByte;
+			const c = x >= bpp ? prev[x - bpp]! : 0; // up-left
+			let val: number;
 			switch (filter) {
 				case 0:
+					val = rawByte;
 					break; // None
 				case 1:
-					val = (rawByte + a) & 0xff;
+					val = rawByte + a;
 					break; // Sub
 				case 2:
-					val = (rawByte + b) & 0xff;
+					val = rawByte + b;
 					break; // Up
 				case 3:
-					val = (rawByte + ((a + b) >> 1)) & 0xff;
+					val = rawByte + ((a + b) >> 1);
 					break; // Average
 				case 4:
-					val = (rawByte + paeth(a, b, c)) & 0xff;
+					val = rawByte + paeth(a, b, c);
 					break; // Paeth
 				default:
 					throw new LabelError(
@@ -153,18 +219,38 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 						`unsupported PNG scanline filter ${filter}`,
 					);
 			}
-			line[x] = val;
+			line[x] = val & 0xff;
 		}
 		// Expand this decoded scanline into RGBA.
 		for (let x = 0; x < width; x++) {
 			const s = x * channels;
 			const d = (y * width + x) * 4;
-			rgba[d] = line[s]!;
-			rgba[d + 1] = line[s + 1]!;
-			rgba[d + 2] = line[s + 2]!;
-			rgba[d + 3] = channels === 4 ? line[s + 3]! : 255;
+			if (colourType === 3) {
+				const p = sampleAt(line, s) * 3;
+				if (p + 2 >= palette!.length) {
+					throw new LabelError(
+						'unsupported-png',
+						`palette index ${p / 3} is outside the PLTE chunk`,
+					);
+				}
+				rgba[d] = palette![p]!;
+				rgba[d + 1] = palette![p + 1]!;
+				rgba[d + 2] = palette![p + 2]!;
+				rgba[d + 3] = 255;
+			} else if (colourType === 0 || colourType === 4) {
+				const g = scaleGrey(sampleAt(line, s));
+				rgba[d] = g;
+				rgba[d + 1] = g;
+				rgba[d + 2] = g;
+				rgba[d + 3] = colourType === 4 ? sampleAt(line, s + 1) : 255;
+			} else {
+				rgba[d] = sampleAt(line, s);
+				rgba[d + 1] = sampleAt(line, s + 1);
+				rgba[d + 2] = sampleAt(line, s + 2);
+				rgba[d + 3] = colourType === 6 ? sampleAt(line, s + 3) : 255;
+			}
 		}
-		prev.set(line);
+		[prev, line] = [line, prev];
 	}
 
 	return {width, height, rgba};
@@ -201,26 +287,46 @@ export function nearestPaletteIndex(r: number, g: number, b: number): number {
 
 const HEX = '0123456789abcdef';
 
+/**
+ * The integer scale of a PICO-8-shaped screenshot: `k` when the image is exactly
+ * `(128*k)x(128*k)` (128x128 is `k = 1`), else `undefined`. PICO-8's
+ * `extcmd("screen")` writes a pixel-exact upscale (3x by default, 384x384; the
+ * factor follows its `screenshot_scale` config), so any square integer multiple
+ * is a screenshot we can sample straight back down.
+ */
+function labelScale(width: number, height: number): number | undefined {
+	if (width !== height || width < LABEL_SIZE || width % LABEL_SIZE !== 0) {
+		return undefined;
+	}
+	return width / LABEL_SIZE;
+}
+
 /**
  * Builds the `__label__` hex body (128 rows of 128 nibbles, newline-joined, with
- * a trailing newline) from a 128x128 PNG. Each pixel is mapped to its nearest
- * PICO-8 palette colour. The PNG MUST be exactly 128x128 ({@link LABEL_SIZE});
- * anything else is a {@link LabelError} (`wrong-size`) so a mis-sized image fails
- * loud instead of being silently cropped or stretched.
+ * a trailing newline) from a PNG. Each pixel is mapped to its nearest PICO-8
+ * palette colour. The PNG must be 128x128 ({@link LABEL_SIZE}) or an exact square
+ * integer multiple of it (256x256, 384x384, ...: a PICO-8 screenshot), which is
+ * downscaled by nearest-neighbour sampling (the centre of each `k x k` block).
+ * Any other size is a {@link LabelError} (`wrong-size`) so a mis-sized image
+ * fails loud instead of being silently cropped or stretched.
  */
 export function labelHexFromPng(pngBytes: Uint8Array): string {
-	const {width, height, rgba} = decodePng(pngBytes);
-	if (width !== LABEL_SIZE || height !== LABEL_SIZE) {
-		throw new LabelError(
-			'wrong-size',
-			`label image must be ${LABEL_SIZE}x${LABEL_SIZE}, got ${width}x${height}`,
-		);
-	}
+	const {width, height, rgba} = decodePng(pngBytes, (w, h) => {
+		if (labelScale(w, h) === undefined) {
+			throw new LabelError(
+				'wrong-size',
+				`label image must be ${LABEL_SIZE}x${LABEL_SIZE} or an exact multiple of it (256x256, 384x384, 512x512, ...), got ${w}x${h}`,
+			);
+		}
+	});
+	const scale = labelScale(width, height)!;
+	const centre = scale >> 1;
 	const rows: string[] = [];
 	for (let y = 0; y < LABEL_SIZE; y++) {
 		let row = '';
+		const sy = y * scale + centre;
 		for (let x = 0; x < LABEL_SIZE; x++) {
-			const d = (y * LABEL_SIZE + x) * 4;
+			const d = (sy * width + x * scale + centre) * 4;
 			row += HEX[nearestPaletteIndex(rgba[d]!, rgba[d + 1]!, rgba[d + 2]!)];
 		}
 		rows.push(row);

package/src/engine/pico8/adapter.ts

@@ -12,6 +12,8 @@
  * a normal, well-signposted boundary (US #14, #19), mirroring shrinko-not-found.
  */
 
+import type {DisplayUnavailable, VirtualDisplayBackend} from './display.js';
+
 /** The remedy string in a pico8-not-found result: how the user makes `run` work. */
 export const PICO8_REMEDY = 'set PICO8_PATH or install PICO-8' as const;
 
@@ -75,6 +77,23 @@ export interface RecordReport {
 	readonly wavPath: string | undefined;
 	readonly printh: string;
 	readonly exitReason: ExitReason;
+	/**
+	 * Which display the `-run` session used (ADR-0017): `native` (the caller's
+	 * own DISPLAY/WAYLAND_DISPLAY, or none) or a private virtual display (`Xvfb`
+	 * spawned directly, or the `xvfb-run` fallback). Omitted by fakes.
+	 */
+	readonly display?: 'native' | VirtualDisplayBackend;
+	/**
+	 * Set only when `wavPath` is undefined: WHY no WAV was captured (the backstop
+	 * fired before the done-sentinel, PICO-8 exited early, or the sentinel was
+	 * reached but the WAV was missing/empty), so a silent failure always says why.
+	 */
+	readonly noWavReason?: string;
+	/**
+	 * Set only when `wavPath` is undefined: the tail of PICO-8's own `log.txt`
+	 * from the isolated `-home` (load errors, SDL/audio init failures).
+	 */
+	readonly pico8LogTail?: string;
 }
 
 /** A successful audio-record call carrying the {@link RecordReport}. */
@@ -132,7 +151,8 @@ export interface DriveOptions {
  * The result {@link Pico8Adapter.record} returns: a {@link RecordReport} or the
  * structured {@link Pico8NotFound} (PICO-8 absent), mirroring {@link Pico8Result}.
  */
-export type Pico8RecordResult = Pico8RecordOk | Pico8NotFound;
+export type Pico8RecordResult =
+	Pico8RecordOk | Pico8NotFound | DisplayUnavailable;
 
 /**
  * Options for a single {@link Pico8Adapter.record} (ADR-0009). The recorded cart
@@ -256,8 +276,10 @@ export interface Pico8Adapter {
 	 * `-x`, which mixes no audio and yields an empty WAV, ADR-0009), streams
 	 * stdout, ends on the sentinel (backstop as the net), and collects the WAV the
 	 * cooperating cart wrote via `audio_rec`/`audio_end(1)`. Returns
-	 * {@link Pico8NotFound} when PICO-8 is not installed. Live capture is a
-	 * manual/opt-in tier; CI drives a fake runner + the absent boundary.
+	 * {@link Pico8NotFound} when PICO-8 is not installed, and
+	 * {@link DisplayUnavailable} when the session needs a display, there is none,
+	 * and no Xvfb is installed to provide a virtual one (ADR-0017). CI drives a
+	 * fake runner + fake Xvfb; a live capture needs the paid binary.
 	 */
 	record(options: RecordOptions): Promise<Pico8RecordResult>;
 

package/src/engine/pico8/cleanup.test.ts

@@ -0,0 +1,28 @@
+import {afterEach, describe, expect, it} from 'vitest';
+import {killOnAbort} from './cleanup.js';
+
+/** The kill-on-abort registry: one listener per event, however many runs. */
+describe('killOnAbort', () => {
+	const disposers: (() => void)[] = [];
+	afterEach(() => {
+		for (const d of disposers.splice(0)) d();
+	});
+
+	it('many concurrent runs add ONE listener per signal, removed when all end', () => {
+		const before = process.listenerCount('SIGTERM');
+		for (let i = 0; i < 20; i++) disposers.push(killOnAbort(() => {}));
+		expect(process.listenerCount('SIGTERM')).toBe(before + 1);
+		expect(process.listenerCount('exit')).toBeGreaterThan(0);
+		for (const d of disposers.splice(0)) d();
+		expect(process.listenerCount('SIGTERM')).toBe(before);
+	});
+
+	it('kills every pending run on exit, and a disposed run is not killed', () => {
+		const killed: number[] = [];
+		const d1 = killOnAbort(() => killed.push(1));
+		disposers.push(killOnAbort(() => killed.push(2)));
+		d1();
+		process.emit('exit', 0);
+		expect(killed).toEqual([2]);
+	});
+});

package/src/engine/pico8/cleanup.ts

@@ -0,0 +1,76 @@
+/**
+ * Kill-on-abort for child processes picopilot owns while a run is in flight
+ * (the PICO-8 process group, a private Xvfb). Normal endings (sentinel,
+ * backstop, crash) are handled by the run itself; this covers picopilot being
+ * stopped mid-run: `process.exit`, an uncaught throw, or SIGINT / SIGTERM /
+ * SIGHUP sent to picopilot alone (an agent harness or `timeout` killing it).
+ * Without it, a detached PICO-8 or an Xvfb would outlive picopilot.
+ *
+ * `kill` must be synchronous (it runs inside an `exit` handler). On a signal,
+ * the hook kills, then re-raises the signal with picopilot's handler removed so
+ * the default behaviour (terminate) still happens, unless some other listener
+ * owns that signal (an MCP server, a test runner), which then decides.
+ */
+
+const SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+/**
+ * The kill functions of every run in flight. ONE listener per event serves them
+ * all (installed while the set is non-empty), so many concurrent runs (an MCP
+ * server) never trip Node's MaxListeners warning.
+ */
+const pending = new Set<() => void>();
+const signalHandlers = new Map<NodeJS.Signals, () => void>();
+
+function killAll(): void {
+	for (const kill of [...pending]) {
+		pending.delete(kill);
+		try {
+			kill();
+		} catch {
+			// best effort: the process may already be gone
+		}
+	}
+}
+
+function onExit(): void {
+	killAll();
+}
+
+function install(): void {
+	process.on('exit', onExit);
+	for (const signal of SIGNALS) {
+		const handler = () => {
+			killAll();
+			uninstall();
+			// Re-raise for the default behaviour (terminate) unless another listener
+			// (an MCP server, a test runner) owns this signal.
+			if (process.listenerCount(signal) === 0) {
+				process.kill(process.pid, signal);
+			}
+		};
+		signalHandlers.set(signal, handler);
+		process.on(signal, handler);
+	}
+}
+
+function uninstall(): void {
+	process.removeListener('exit', onExit);
+	for (const [signal, handler] of signalHandlers) {
+		process.removeListener(signal, handler);
+	}
+	signalHandlers.clear();
+}
+
+/** Registers `kill` to run if picopilot exits or is signalled; returns the disposer. */
+export function killOnAbort(kill: () => void): () => void {
+	let entry: (() => void) | undefined = () => kill();
+	if (pending.size === 0) install();
+	pending.add(entry);
+	return () => {
+		if (entry === undefined) return;
+		pending.delete(entry);
+		entry = undefined;
+		if (pending.size === 0) uninstall();
+	};
+}

package/src/engine/pico8/display.test.ts

@@ -0,0 +1,210 @@
+import {describe, expect, it} from 'vitest';
+import {
+	detectVirtualDisplayBackend,
+	needsVirtualDisplay,
+	resolveDisplayMode,
+	startVirtualDisplay,
+	type XvfbSpawner,
+} from './display.js';
+import {FakeXvfb} from './fake-xvfb.test-support.js';
+
+/**
+ * The display-mode seam (ADR-0017) is tested WITHOUT a real X server: the
+ * resolution + decision tables are pure, and Xvfb is a fake process that the
+ * test makes report a display number, exit early, or hang.
+ */
+
+describe('resolveDisplayMode: flag > env > config > default', () => {
+	const cases: {
+		name: string;
+		flag?: string;
+		env?: string;
+		config?: unknown;
+		mode: string;
+		source: string;
+	}[] = [
+		{name: 'nothing set', mode: 'auto', source: 'default'},
+		{name: 'config only', config: 'native', mode: 'native', source: 'config'},
+		{name: 'env only', env: 'xvfb', mode: 'xvfb', source: 'env'},
+		{name: 'flag only', flag: 'native', mode: 'native', source: 'flag'},
+		{
+			name: 'env beats config',
+			env: 'xvfb',
+			config: 'native',
+			mode: 'xvfb',
+			source: 'env',
+		},
+		{
+			name: 'flag beats env and config',
+			flag: 'auto',
+			env: 'xvfb',
+			config: 'native',
+			mode: 'auto',
+			source: 'flag',
+		},
+		{
+			name: 'an empty env value is unset',
+			env: '  ',
+			config: 'xvfb',
+			mode: 'xvfb',
+			source: 'config',
+		},
+	];
+	for (const c of cases) {
+		it(c.name, () => {
+			expect(
+				resolveDisplayMode({flag: c.flag, env: c.env, config: c.config}),
+			).toEqual({ok: true, mode: c.mode, source: c.source});
+		});
+	}
+
+	it('reports an unknown value instead of silently falling back', () => {
+		expect(resolveDisplayMode({env: 'xfvb', config: 'native'})).toEqual({
+			ok: false,
+			source: 'env',
+			value: 'xfvb',
+		});
+		expect(resolveDisplayMode({config: 42})).toEqual({
+			ok: false,
+			source: 'config',
+			value: '42',
+		});
+	});
+});
+
+describe('needsVirtualDisplay: the auto decision', () => {
+	const table: [string, NodeJS.ProcessEnv, boolean, boolean, boolean][] = [
+		// [name, env, auto, xvfb, native]
+		['no display at all', {}, true, true, false],
+		['X11 DISPLAY set', {DISPLAY: ':0'}, false, true, false],
+		['Wayland only', {WAYLAND_DISPLAY: 'wayland-0'}, false, true, false],
+		['both set', {DISPLAY: ':0', WAYLAND_DISPLAY: 'w'}, false, true, false],
+		['empty DISPLAY counts as none', {DISPLAY: ''}, true, true, false],
+	];
+	for (const [name, env, auto, xvfb, native] of table) {
+		it(name, () => {
+			expect(needsVirtualDisplay('auto', env)).toBe(auto);
+			expect(needsVirtualDisplay('xvfb', env)).toBe(xvfb);
+			expect(needsVirtualDisplay('native', env)).toBe(native);
+		});
+	}
+});
+
+describe('detectVirtualDisplayBackend', () => {
+	it('prefers Xvfb over xvfb-run, and reports none when neither exists', () => {
+		const has =
+			(...names: string[]) =>
+			(n: string) =>
+				names.includes(n) ? `/bin/${n}` : undefined;
+		expect(detectVirtualDisplayBackend({}, has('Xvfb', 'xvfb-run'))).toBe(
+			'Xvfb',
+		);
+		expect(detectVirtualDisplayBackend({}, has('xvfb-run'))).toBe('xvfb-run');
+		expect(detectVirtualDisplayBackend({}, has())).toBeUndefined();
+	});
+});
+
+const onlyXvfb = (n: string) => (n === 'Xvfb' ? '/fake/Xvfb' : undefined);
+
+describe('startVirtualDisplay: direct Xvfb with -displayfd', () => {
+	it('spawns Xvfb -displayfd and sets DISPLAY to the number it reports', async () => {
+		const xvfb = new FakeXvfb();
+		let spawned: {file: string; args: string[]} | undefined;
+		const spawnXvfb: XvfbSpawner = (file, args) => {
+			spawned = {file, args};
+			setImmediate(() => xvfb.reportDisplay(37));
+			return xvfb;
+		};
+		const started = await startVirtualDisplay({}, {find: onlyXvfb, spawnXvfb});
+		expect(started.ok).toBe(true);
+		if (!started.ok) return;
+		expect(spawned?.file).toBe('/fake/Xvfb');
+		expect(spawned?.args).toContain('-displayfd');
+		// No fixed display number: the server picks one (no races between runs).
+		expect(spawned?.args.some((a) => /^:\d+$/.test(a))).toBe(false);
+		expect(started.display.backend).toBe('Xvfb');
+		expect(started.display.env).toEqual({DISPLAY: ':37'});
+		expect(started.display.wrap('pico8', ['-run', 'c.p8'])).toEqual({
+			file: 'pico8',
+			args: ['-run', 'c.p8'],
+		});
+		await started.display.stop();
+		expect(xvfb.signals).toContain('SIGTERM');
+		expect(xvfb.exited).toBe(true);
+	});
+
+	it('escalates to SIGKILL when Xvfb ignores SIGTERM', async () => {
+		const xvfb = new FakeXvfb();
+		xvfb.exitOnTerm = false;
+		const started = await startVirtualDisplay(
+			{},
+			{
+				find: onlyXvfb,
+				stopGraceMs: 10,
+				spawnXvfb: () => {
+					setImmediate(() => xvfb.reportDisplay(1));
+					return xvfb;
+				},
+			},
+		);
+		if (!started.ok) throw new Error('expected a display');
+		await started.display.stop();
+		expect(xvfb.signals).toEqual(['SIGTERM', 'SIGKILL']);
+		expect(xvfb.exited).toBe(true);
+	});
+
+	it('is display-unavailable (with stderr) when Xvfb exits before reporting', async () => {
+		const xvfb = new FakeXvfb();
+		const started = await startVirtualDisplay(
+			{},
+			{
+				find: onlyXvfb,
+				spawnXvfb: () => {
+					setImmediate(() => {
+						xvfb.writeStderr('Fatal server error: no screens\n');
+						xvfb.exit(1);
+					});
+					return xvfb;
+				},
+			},
+		);
+		expect(started.ok).toBe(false);
+		if (started.ok) return;
+		expect(started.reason).toBe('display-unavailable');
+		expect(started.detail).toContain('no screens');
+	});
+
+	it('kills Xvfb and is display-unavailable when it never reports a display', async () => {
+		const xvfb = new FakeXvfb();
+		const started = await startVirtualDisplay(
+			{},
+			{find: onlyXvfb, startTimeoutMs: 20, spawnXvfb: () => xvfb},
+		);
+		expect(started.ok).toBe(false);
+		expect(xvfb.exited).toBe(true); // never left behind
+	});
+});
+
+describe('startVirtualDisplay: xvfb-run fallback and absence', () => {
+	it('wraps the command in xvfb-run -a when only xvfb-run exists', async () => {
+		const started = await startVirtualDisplay(
+			{},
+			{find: (n) => (n === 'xvfb-run' ? '/fake/xvfb-run' : undefined)},
+		);
+		if (!started.ok) throw new Error('expected xvfb-run');
+		expect(started.display.backend).toBe('xvfb-run');
+		const w = started.display.wrap('pico8', ['-run', 'c.p8']);
+		expect(w.file).toBe('/fake/xvfb-run');
+		expect(w.args[0]).toBe('-a');
+		expect(w.args.slice(-3)).toEqual(['pico8', '-run', 'c.p8']);
+	});
+
+	it('is display-unavailable with a remedy naming Xvfb when nothing is installed', async () => {
+		const started = await startVirtualDisplay({}, {find: () => undefined});
+		expect(started.ok).toBe(false);
+		if (started.ok) return;
+		expect(started.reason).toBe('display-unavailable');
+		expect(started.remedy).toMatch(/Xvfb/);
+		expect(started.remedy).toMatch(/desktop/);
+	});
+});