picopilot 0.1.5 → 0.2.0

package/src/commands/playtest.ts

@@ -22,12 +22,16 @@ import {
 	SessionRegistry,
 	sessionExists,
 	SHOT_BASENAME,
-	ShellPico8Adapter,
 	spawnSessionDaemon,
 	type SessionRequest,
 	type SessionResponse,
 	type SessionResponseValue,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 import {makeReadInclude} from './cart-includes.js';
 
 /**
@@ -36,10 +40,9 @@ import {makeReadInclude} from './cart-includes.js';
  * stub to drive the drive-orchestration + the absent path WITHOUT the paid
  * binary, and to isolate the child `env` (its `PICO8_PATH`/`PATH`).
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /**
  * The default backstop: kill a driven cart that never signals/exits after this
@@ -219,13 +222,7 @@ function buildPlaytestGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 }
 
 /** The env schema the whole `playtest` group shares (locates the binary, isolated). */
-const PLAYTEST_ENV = z.object({
-	PICO8_PATH: z
-		.string()
-		.optional()
-		.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-	PATH: z.string().optional().describe('Used to locate `pico8`.'),
-});
+const PLAYTEST_ENV = PICO8_ENV;
 
 /**
  * The ONE-SHOT root handler (unchanged behaviour from the one-shot task): build

package/src/commands/run.test.ts

@@ -1,5 +1,11 @@
 import {execFileSync} from 'node:child_process';
-import {existsSync, mkdtempSync, readdirSync, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
 import {homedir, tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {Cli} from 'incur';
@@ -11,7 +17,8 @@ import type {
 	RecordOptions,
 	RunOptions,
 } from '../engine/pico8/index.js';
-import {pico8NotFound} from '../engine/pico8/index.js';
+import {displayUnavailable, pico8NotFound} from '../engine/pico8/index.js';
+import {createShellAdapterFactory} from './pico8-env.js';
 import {type Pico8AdapterFactory, registerRun} from './run.js';
 
 /** A trivial valid cart the command reads (existence + a path to hand the adapter). */
@@ -268,3 +275,104 @@ describe('picopilot run: cart-not-found (picopilot-side error, distinct from pic
 		expect(snap()).toEqual(before); // same entries: an absent dir stays absent, a present one unchanged
 	});
 });
+
+describe('picopilot run --record-audio: an #include cart produces a loadable harness', () => {
+	it('inlines the cart includes into the harness it hands the record pass', async () => {
+		writeFileSync(
+			cartPath,
+			'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\n#include main.lua\n',
+		);
+		writeFileSync(
+			join(dir, 'main.lua'),
+			'function _update() hello_from_main=1 end\n',
+		);
+		const seen: {recordOptions?: RecordOptions} = {};
+		const {exitCode} = await runRun(
+			() => stubAdapter(ranWith('sentinel'), seen),
+			['run', cartPath, '--record-audio', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const harness = readFileSync(seen.recordOptions!.cartPath, 'utf8');
+		expect(harness).not.toMatch(/#include/);
+		expect(harness).toContain('hello_from_main=1');
+	});
+});
+
+describe('picopilot run --record-audio: failures are explained, never silent', () => {
+	it('surfaces noAudioReason + pico8LogTail when no WAV was captured', async () => {
+		const {stdout} = await runRun(
+			() =>
+				stubAdapter(ranWith('sentinel'), undefined, {
+					ok: true,
+					value: {
+						wavPath: undefined,
+						printh: '',
+						exitReason: 'timeout',
+						noWavReason: 'the backstop fired before the done-sentinel',
+						pico8LogTail: 'syntax error',
+					},
+				}),
+			['run', cartPath, '--record-audio', '--json'],
+		);
+		const out = JSON.parse(stdout);
+		expect(out.audioCaptured).toBe(false);
+		expect(out.noAudioReason).toMatch(/backstop/);
+		expect(out.pico8LogTail).toBe('syntax error');
+	});
+
+	it('display-unavailable is a structured error whose CTA names the fix', async () => {
+		const {stdout, exitCode} = await runRun(
+			() =>
+				stubAdapter(
+					ranWith('sentinel'),
+					undefined,
+					displayUnavailable('no DISPLAY and no Xvfb'),
+				),
+			['run', cartPath, '--record-audio', '--json', '--full-output'],
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.error.code).toBe('display-unavailable');
+		expect(out.error.message).toMatch(/Xvfb/);
+		expect(JSON.stringify(out.meta?.cta ?? out.cta)).toMatch(/install Xvfb/);
+	});
+});
+
+describe('picopilot run: the PICO-8 child inherits the parent environment', () => {
+	it('DISPLAY, HOME and XDG_RUNTIME_DIR from the parent reach the spawn; PICO8_PATH comes from the resolved env', async () => {
+		let spawnedEnv: NodeJS.ProcessEnv | undefined;
+		const factory = createShellAdapterFactory({
+			parentEnv: {
+				DISPLAY: ':5',
+				HOME: '/home/agent',
+				XDG_RUNTIME_DIR: '/run/user/1000',
+				SDL_AUDIODRIVER: 'pulseaudio',
+				PICO8_PATH: '/parent/pico8',
+			},
+			spawn: (_file, _args, env) => {
+				spawnedEnv = env;
+				return {
+					onStdout(cb) {
+						setImmediate(() => cb('__PICOPILOT_DONE__\n'));
+					},
+					onClose() {},
+					onError() {},
+					kill() {},
+				};
+			},
+		});
+		const {exitCode} = await runRun(factory, ['run', cartPath, '--json'], {
+			PICO8_PATH: '/resolved/pico8',
+			PATH: '/usr/bin',
+		});
+		expect(exitCode).toBe(0);
+		expect(spawnedEnv).toMatchObject({
+			DISPLAY: ':5',
+			HOME: '/home/agent',
+			XDG_RUNTIME_DIR: '/run/user/1000',
+			SDL_AUDIODRIVER: 'pulseaudio',
+			PICO8_PATH: '/resolved/pico8',
+			PATH: '/usr/bin',
+		});
+	});
+});

package/src/commands/run.ts

@@ -12,20 +12,25 @@ import {
 	buildRecordHarness,
 	DONE_SENTINEL,
 	HarnessError,
-	type Pico8Adapter,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+import {
+	createShellAdapterFactory,
+	displayModeOf,
+	displayUnavailableError,
+	PICO8_ENV,
+	pico8NotFoundError,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 
 /**
  * Injects the PICO-8 adapter `run` uses (defaults to the shell adapter over
  * native `pico8 -x`). Mirrors the shrinko `adapterFactory` seam: a test passes a
- * stub to drive the sentinel/backstop/absent paths without the paid binary, and
- * to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ * stub to drive the sentinel/backstop/absent paths without the paid binary.
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /** The default backstop: kill a cart that never signals/exits after this many ms. */
 const DEFAULT_BACKSTOP_MS = 15_000;
@@ -95,18 +100,12 @@ export function registerRun(
 				.boolean()
 				.default(false)
 				.describe(
-					"Also capture a WAV of the run's audio alongside the screenshots (ADR-0009). A REAL-TIME recording that needs a real audio+video session (a separate -run pass, NOT the headless screenshot pass), never an offline export.",
+					"Also capture a WAV of the run's audio alongside the screenshots (ADR-0009). A REAL-TIME recording in a separate -run pass (not the headless screenshot pass), never an offline export. Works headless: with no display, picopilot runs that pass on a private virtual display (ADR-0017, --display).",
 				),
 		}),
-		// incur resolves these from the (test-overridable) env source and hands
-		// them to the child, so PICO8_PATH/PATH locate the binary in isolation.
-		env: z.object({
-			PICO8_PATH: z
-				.string()
-				.optional()
-				.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-			PATH: z.string().optional().describe('Used to locate `pico8`.'),
-		}),
+		// incur resolves these from the (test-overridable) env source; the child
+		// gets the parent env with them overlaid (DISPLAY, HOME, ... pass through).
+		env: PICO8_ENV,
 		output: z.object({
 			screenshots: z
 				.array(z.string())
@@ -131,6 +130,24 @@ export function registerRun(
 				.describe(
 					'Whether a non-empty WAV was captured (false unless --record-audio ran and produced audio).',
 				),
+			audioDisplay: z
+				.enum(['native', 'Xvfb', 'xvfb-run'])
+				.optional()
+				.describe(
+					'With --record-audio: which display the -run pass used (native, or a private virtual display).',
+				),
+			noAudioReason: z
+				.string()
+				.optional()
+				.describe(
+					'With --record-audio and no WAV: why (backstop fired / PICO-8 exited before the done-sentinel / empty capture).',
+				),
+			pico8LogTail: z
+				.string()
+				.optional()
+				.describe(
+					"With --record-audio and no WAV: the tail of PICO-8's own log.txt (load errors, SDL init failures).",
+				),
 		}),
 		examples: [
 			{description: 'Run main.p8'},
@@ -141,7 +158,7 @@ export function registerRun(
 				options: {shotDir: './shots'},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			const cartPath = isAbsolute(args.cart)
 				? args.cart
 				: resolve(process.cwd(), args.cart);
@@ -166,7 +183,9 @@ export function registerRun(
 					: mkdtempSync(join(tmpdir(), 'picopilot-run-'));
 			if (!existsSync(shotDir)) mkdirSync(shotDir, {recursive: true});
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.run({
 				cartPath,
 				shotDir,
@@ -194,10 +213,16 @@ export function registerRun(
 			// uses. The WAV lands in the isolated shotDir alongside the screenshots.
 			let wav: string | undefined;
 			let audioCaptured = false;
+			let noAudioReason: string | undefined;
+			let pico8LogTail: string | undefined;
+			let audioDisplay: 'native' | 'Xvfb' | 'xvfb-run' | undefined;
 			if (options.recordAudio) {
 				try {
+					// `#include`s are inlined (resolved against the SOURCE cart's folder):
+					// the harness runs from shotDir, where `main.lua` does not exist.
 					const harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
 						sentinel: options.sentinel,
+						readInclude: makeReadInclude(cartPath),
 					});
 					const harnessCart = join(shotDir, 'record-audio-harness.p8');
 					writeFileSync(harnessCart, harness.cartText);
@@ -208,16 +233,26 @@ export function registerRun(
 						sentinel: options.sentinel,
 						backstopMs: options.backstopMs,
 					});
-					if (rec.ok) {
-						wav = rec.value.wavPath;
-						audioCaptured = rec.value.wavPath !== undefined;
+					if (!rec.ok) {
+						// pico8-not-found is impossible here (the screenshot pass above would
+						// have returned it); display-unavailable is the real case: the -run
+						// pass needs a display, there is none, and no Xvfb to make one.
+						return error(
+							rec.reason === 'display-unavailable'
+								? displayUnavailableError('run --record-audio', rec)
+								: pico8NotFoundError(rec),
+						);
 					}
-					// A record-pass pico8-not-found is impossible here: the screenshot
-					// pass above already returned pico8-not-found if PICO-8 were absent.
+					wav = rec.value.wavPath;
+					audioCaptured = rec.value.wavPath !== undefined;
+					noAudioReason = rec.value.noWavReason;
+					pico8LogTail = rec.value.pico8LogTail;
+					audioDisplay = rec.value.display;
 				} catch (e) {
 					if (!(e instanceof HarnessError)) throw e;
 					// A harness-build failure (unparseable cart) leaves audioCaptured false;
 					// the screenshot run's report still stands.
+					noAudioReason = `the record harness could not be built: ${e.message}`;
 				}
 			}
 
@@ -277,6 +312,9 @@ export function registerRun(
 					shotDir,
 					wav,
 					audioCaptured,
+					...(audioDisplay !== undefined ? {audioDisplay} : {}),
+					...(noAudioReason !== undefined ? {noAudioReason} : {}),
+					...(pico8LogTail !== undefined ? {pico8LogTail} : {}),
 				},
 				cta === undefined ? undefined : {cta},
 			);

package/src/commands/serve.ts

@@ -13,8 +13,12 @@ import {
 	EXPORT_HTML_NAME,
 	type Pico8Adapter,
 	type Pico8ExportResult,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 import {prepareLabeledCart} from './label-cart.js';
 
 /**
@@ -22,10 +26,9 @@ import {prepareLabeledCart} from './label-cart.js';
  * seam as `export`/`run`: a test passes a stub so the export step needs no paid
  * binary, and the child `env` (`PICO8_PATH`/`PATH`) stays isolated.
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /**
  * Injects the HTTP-server factory `serve` binds. The default is a zero-dep
@@ -206,13 +209,7 @@ export function registerServe(
 					'Safety backstop for the export step (and the --label-frame capture run).',
 				),
 		}),
-		env: z.object({
-			PICO8_PATH: z
-				.string()
-				.optional()
-				.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-			PATH: z.string().optional().describe('Used to locate `pico8`.'),
-		}),
+		env: PICO8_ENV,
 		output: z.object({
 			url: z.string().describe('The local URL to open in a browser.'),
 			port: z.number().describe('The port the server bound to.'),

package/src/commands/shrinko-env.test.ts

@@ -0,0 +1,68 @@
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {Cli} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import type {ChildRunner} from '../engine/shrinko/index.js';
+import {createShellShrinkoFactory} from './shrinko-env.js';
+import {registerTokens} from './tokens.js';
+
+/**
+ * shrinko8 is a Python tool: a `pip install --user` copy is found through HOME
+ * (user site-packages), so the child must inherit the parent environment, with
+ * the command's resolved PATH overlaid (the same rule as the PICO-8 child,
+ * ADR-0017).
+ */
+
+let dir: string;
+let cartPath: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-shrinko-env-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(
+		cartPath,
+		'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n',
+	);
+});
+afterEach(() => rmSync(dir, {recursive: true, force: true}));
+
+describe('shrinko child env', () => {
+	it('HOME and the rest of the parent env reach shrinko; PATH comes from the resolved env', async () => {
+		let seen: NodeJS.ProcessEnv | undefined;
+		const run: ChildRunner = async (_file, _args, env) => {
+			seen = env;
+			return {
+				code: 0,
+				stdout: 'tokens: 3 0%\nchars: 11 0%\ncompressed: 20 0%\n',
+				stderr: '',
+				spawnError: undefined,
+			};
+		};
+		const cli = Cli.create('picopilot', {version: '0.0.0'});
+		registerTokens(
+			cli,
+			createShellShrinkoFactory({
+				parentEnv: {
+					HOME: '/home/agent',
+					PYTHONUSERBASE: '/home/agent/.local',
+					PATH: '/parent/bin',
+				},
+				run,
+			}),
+		);
+		let stdout = '';
+		await cli.serve(['tokens', cartPath, '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit() {},
+			env: {PATH: '/resolved/bin'},
+		});
+		expect(JSON.parse(stdout).tokens).toBe(3);
+		expect(seen).toMatchObject({
+			HOME: '/home/agent',
+			PYTHONUSERBASE: '/home/agent/.local',
+			PATH: '/resolved/bin',
+		});
+	});
+});

package/src/commands/shrinko-env.ts

@@ -0,0 +1,40 @@
+import {overlayEnv} from '../engine/child-env.js';
+import {
+	type ChildRunner,
+	type ShrinkoAdapter,
+	ShellShrinkoAdapter,
+} from '../engine/shrinko/index.js';
+
+/**
+ * Builds the {@link ShrinkoAdapter} a shrinko-backed command uses, given the
+ * incur-resolved env (its `PATH`). A test passes its own factory to swap in a
+ * stub adapter (the seam-swap contract).
+ */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+
+/** Dependencies for {@link createShellShrinkoFactory}, injectable for tests. */
+export interface ShellShrinkoFactoryDeps {
+	/** The parent environment shrinko inherits (defaults to `process.env`). */
+	readonly parentEnv?: NodeJS.ProcessEnv;
+	/** The child runner (defaults to the real `execFile`). */
+	readonly run?: ChildRunner;
+}
+
+/**
+ * The default shrinko factory: the shell adapter over a user-installed
+ * shrinko8, whose child env is the parent env overlaid with the command's
+ * resolved `PATH`. shrinko8 is a Python tool, so a `pip install --user` copy is
+ * only found when HOME (user site-packages) reaches the child.
+ */
+export function createShellShrinkoFactory(
+	deps: ShellShrinkoFactoryDeps = {},
+): ShrinkoAdapterFactory {
+	return (env) =>
+		new ShellShrinkoAdapter({
+			env: overlayEnv(
+				env as Record<string, string | undefined>,
+				deps.parentEnv ?? process.env,
+			),
+			run: deps.run,
+		});
+}

package/src/commands/tokens.ts

@@ -5,16 +5,19 @@ import {type Cli, z} from 'incur';
 import {
 	type ShrinkoAdapter,
 	ShrinkoParseError,
-	ShellShrinkoAdapter,
 } from '../engine/shrinko/index.js';
+import {
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** PICO-8's Lua token budget. A cart over this will not load in PICO-8 (US #3). */
 export const TOKEN_BUDGET = 8192;
 
 /**
  * Builds the {@link ShrinkoAdapter} a command uses, given the incur-resolved
- * env. The default is the shell-out {@link ShellShrinkoAdapter}, whose child
- * process inherits ONLY this `env` (its `PATH` is the test isolation lever).
+ * env. The default is the shell-out `ShellShrinkoAdapter`, whose child process
+ * gets the parent env with this resolved `PATH` overlaid (see `shrinko-env.ts`).
  *
  * A test passes its own factory to {@link registerTokens} to SWAP a stub
  * adapter (the seam-swap contract): the command's public output/exit must be
@@ -22,10 +25,10 @@ export const TOKEN_BUDGET = 8192;
  * seam, because the command only ever talks to the {@link ShrinkoAdapter}
  * interface.
  */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * Registers `picopilot tokens` (US #3), the first shrinko-backed command.

package/src/commands/verify.ts

@@ -6,8 +6,11 @@ import {Cart, CartParseError} from '../engine/cart/index.js';
 import {
 	type ShrinkoAdapter,
 	ShrinkoParseError,
-	ShellShrinkoAdapter,
 } from '../engine/shrinko/index.js';
+import {
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 import {TOKEN_BUDGET} from './tokens.js';
 
 /**
@@ -29,10 +32,10 @@ export const VERIFY_SCOPE =
 export const GATE_INCAPABLE_EXIT = 2;
 
 /** See {@link ShrinkoAdapterFactory} in `tokens.ts` — verify reuses the same seam. */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * The result of the integrity check: the cart parses AND round-trips

package/src/engine/child-env.ts

@@ -0,0 +1,22 @@
+/**
+ * The environment an external tool (PICO-8, shrinko8) is spawned with: the
+ * PARENT environment overlaid with the values a command RESOLVED (incur parses
+ * only the keys a command declares, e.g. PICO8_PATH / PATH). Handing the child
+ * just that parsed subset strips everything else it needs: DISPLAY, HOME,
+ * XDG_RUNTIME_DIR and SDL_* for PICO-8 (ADR-0017), HOME / PYTHONUSERBASE for a
+ * `pip install --user` shrinko8. An `undefined` resolved value never erases a
+ * parent value.
+ *
+ * `parent` is a parameter (the command layer defaults it to `process.env`; it is
+ * never read here) so tests inject a controlled environment.
+ */
+export function overlayEnv(
+	resolved: Readonly<Record<string, string | undefined>>,
+	parent: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+	const env: NodeJS.ProcessEnv = {...parent};
+	for (const [key, value] of Object.entries(resolved)) {
+		if (value !== undefined) env[key] = value;
+	}
+	return env;
+}

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]);
+	});
+});