picopilot 0.1.5 → 0.2.0

package/src/cli.test.ts

@@ -0,0 +1,188 @@
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {z} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {createCli} from './cli.js';
+import {displayModeOf} from './commands/pico8-env.js';
+
+/**
+ * The display mode (ADR-0017) is resolved ONCE, globally, by the root CLI:
+ * `--display` > `PICOPILOT_DISPLAY` > picopilot.json `display` > `auto`. A probe
+ * command mounted on the real CLI reports what a command handler sees.
+ */
+
+let dir: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-cli-'));
+});
+afterEach(() => rmSync(dir, {recursive: true, force: true}));
+
+async function probe(
+	argv: string[],
+	env: Record<string, string | undefined> = {},
+	config?: unknown,
+) {
+	const cli = createCli();
+	cli.command('probe-display', {
+		run: (c) => ({display: displayModeOf(c.var)}),
+	});
+	const args = [...argv];
+	if (config !== undefined) {
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(path, JSON.stringify(config));
+		args.push('--config', path);
+	}
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve([...args, '--json'], {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {out: JSON.parse(stdout), exitCode};
+}
+
+describe('display mode resolution through the CLI', () => {
+	it('defaults to auto', async () => {
+		expect((await probe(['probe-display'])).out.display).toBe('auto');
+	});
+
+	it('reads picopilot.json "display"', async () => {
+		const {out} = await probe(['probe-display'], {}, {display: 'native'});
+		expect(out.display).toBe('native');
+	});
+
+	it('PICOPILOT_DISPLAY beats picopilot.json', async () => {
+		const {out} = await probe(
+			['probe-display'],
+			{PICOPILOT_DISPLAY: 'xvfb'},
+			{display: 'native'},
+		);
+		expect(out.display).toBe('xvfb');
+	});
+
+	it('--display beats both, before or after the command', async () => {
+		for (const argv of [
+			['--display', 'native', 'probe-display'],
+			['probe-display', '--display', 'native'],
+		]) {
+			const {out} = await probe(
+				argv,
+				{PICOPILOT_DISPLAY: 'xvfb'},
+				{display: 'xvfb'},
+			);
+			expect(out.display).toBe('native');
+		}
+	});
+
+	it('an invalid PICOPILOT_DISPLAY is an error for a display command, not a silent auto', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['run', join(dir, 'none.p8'), '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {PICOPILOT_DISPLAY: 'xfvb'},
+		});
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('invalid-display-mode');
+		expect(out.message).toContain('PICOPILOT_DISPLAY');
+	});
+
+	it('an invalid value does not break commands that never use the display', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['version', '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {PICOPILOT_DISPLAY: 'xfvb'},
+		});
+		expect(exitCode).toBe(0);
+		expect(JSON.parse(stdout).name).toBe('picopilot');
+	});
+
+	it('--no-config ignores the picopilot.json display key', async () => {
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(path, JSON.stringify({display: 'native'}));
+		// First load it (so a stale value could leak), then disable config.
+		const cli = createCli();
+		cli.command('probe-display', {
+			run: (c) => ({display: displayModeOf(c.var)}),
+		});
+		const outs: string[] = [];
+		for (const argv of [
+			['probe-display', '--config', path, '--json'],
+			['probe-display', '--no-config', '--json'],
+		]) {
+			let stdout = '';
+			await cli.serve(argv, {
+				stdout(s) {
+					stdout += s;
+				},
+				exit() {},
+				env: {},
+			});
+			outs.push(JSON.parse(stdout).display);
+		}
+		expect(outs).toEqual(['native', 'auto']);
+	});
+
+	it('--config naming a missing file is an error', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['version', '--config', join(dir, 'nope.json'), '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {},
+		});
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('not found');
+	});
+
+	it('a per-command config option still loads next to the display key', async () => {
+		// The custom config loader must keep incur's per-command option defaults.
+		const cli = createCli();
+		let seen: unknown;
+		cli.command('probe-opt', {
+			options: z.object({flag: z.boolean().default(false)}),
+			run: (c) => {
+				seen = c.options.flag;
+				return {};
+			},
+		});
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(
+			path,
+			JSON.stringify({
+				display: 'native',
+				commands: {'probe-opt': {options: {flag: true}}},
+			}),
+		);
+		await cli.serve(['probe-opt', '--config', path, '--json'], {
+			stdout() {},
+			exit() {},
+			env: {},
+		});
+		expect(seen).toBe(true);
+	});
+});

package/src/cli.ts

@@ -1,5 +1,7 @@
-import {Cli} from 'incur';
+import {readFileSync} from 'node:fs';
+import {Cli, z} from 'incur';
 import {registerAudio} from './commands/audio.js';
+import {registerDoctor} from './commands/doctor.js';
 import {registerExport} from './commands/export.js';
 import {registerGfx} from './commands/gfx.js';
 import {registerInit} from './commands/init.js';
@@ -13,8 +15,58 @@ import {registerSfx} from './commands/sfx.js';
 import {registerTokens} from './commands/tokens.js';
 import {registerVerify} from './commands/verify.js';
 import {registerVersion} from './commands/version.js';
+import {
+	DEFAULT_DISPLAY_MODE,
+	DISPLAY_CONFIG_KEY,
+	DISPLAY_ENV_VAR,
+	DISPLAY_MODES,
+	resolveDisplayMode,
+} from './engine/pico8/display.js';
 import {VERSION} from './version.js';
 
+/** The commands that use the display mode (they start a `-run` session, or report on it). */
+const DISPLAY_COMMANDS: ReadonlySet<string> = new Set([
+	'run',
+	'audio record',
+	'audio render',
+	'doctor',
+]);
+
+/**
+ * Reads a picopilot.json for incur's config layer AND captures its top-level
+ * {@link DISPLAY_CONFIG_KEY}. incur only maps per-command `options` from the
+ * config file; the display mode is a GLOBAL setting, so the loader hands the
+ * value to the display middleware through `sink`.
+ */
+function loadConfig(
+	path: string | undefined,
+	sink: {display?: unknown},
+): Record<string, unknown> | undefined {
+	sink.display = undefined;
+	if (path === undefined) return undefined;
+	let raw: string;
+	try {
+		raw = readFileSync(path, 'utf8');
+	} catch (e) {
+		// incur only hands the loader an existing file unless --config named one.
+		if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+			throw new Error(`Config file not found: ${path}`);
+		}
+		throw e;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(`Invalid JSON config file: ${path}`);
+	}
+	if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(`Config file must hold a JSON object: ${path}`);
+	}
+	sink.display = (parsed as Record<string, unknown>)[DISPLAY_CONFIG_KEY];
+	return parsed as Record<string, unknown>;
+}
+
 /**
  * Builds the root picopilot CLI.
  *
@@ -28,6 +80,7 @@ import {VERSION} from './version.js';
  * CLI and drive it with `cli.serve(argv, { stdout, exit, env })` DI overrides.
  */
 export function createCli(): Cli.Cli {
+	const configSink: {display?: unknown} = {};
 	const cli = Cli.create('picopilot', {
 		version: VERSION,
 		description: 'An agent-first toolchain for PICO-8 game development.',
@@ -39,23 +92,76 @@ export function createCli(): Cli.Cli {
 		config: {
 			flag: 'config',
 			files: ['picopilot.json'],
+			loader: async (path) => loadConfig(path, configSink),
 		},
+		// The display mode (ADR-0017) is global: it applies to every command that
+		// starts a PICO-8 `-run` session. Precedence: --display > PICOPILOT_DISPLAY
+		// > picopilot.json `display` > auto.
+		globals: z.object({
+			display: z
+				.enum(DISPLAY_MODES)
+				.optional()
+				.describe(
+					'How PICO-8 -run sessions (audio record/render, run --record-audio) get a display: auto (default: a private virtual display only when there is none), xvfb (always virtual), native (as-is). Also PICOPILOT_DISPLAY or picopilot.json "display" (under --mcp, only PICOPILOT_DISPLAY applies).',
+				),
+		}),
+		env: z.object({
+			[DISPLAY_ENV_VAR]: z
+				.string()
+				.optional()
+				.describe('Display mode: auto | xvfb | native (below --display).'),
+		}),
+		vars: z.object({
+			display: z.enum(DISPLAY_MODES).default(DEFAULT_DISPLAY_MODE),
+		}),
+	});
+
+	cli.use(async (c, next) => {
+		const configured = configSink.display;
+		configSink.display = undefined; // never leak into a later invocation
+		const resolved = resolveDisplayMode({
+			// incur's MCP transport passes no globals (and loads no config file), so
+			// under `--mcp` only PICOPILOT_DISPLAY applies.
+			flag: c.globals?.display,
+			env: (c.env as Record<string, string | undefined>)[DISPLAY_ENV_VAR],
+			config: configured,
+		});
+		if (!resolved.ok) {
+			// A bad value only fails the commands that use it; the rest run as usual.
+			if (!DISPLAY_COMMANDS.has(c.command)) return next();
+			// (An invalid --display never gets here: incur's enum rejects it first.)
+			const where =
+				resolved.source === 'env'
+					? DISPLAY_ENV_VAR
+					: `picopilot.json "${DISPLAY_CONFIG_KEY}"`;
+			return c.error({
+				code: 'invalid-display-mode',
+				message: `${where} is "${resolved.value}"; expected one of: ${DISPLAY_MODES.join(', ')}.`,
+				exitCode: 1,
+			});
+		}
+		c.set('display', resolved.mode);
+		await next();
 	});
 
-	registerVersion(cli);
-	registerInit(cli);
-	registerGfx(cli);
-	registerTokens(cli);
-	registerLint(cli);
-	registerMinify(cli);
-	registerVerify(cli);
-	registerRun(cli);
-	registerExport(cli);
-	registerServe(cli);
-	registerPlaytest(cli);
-	registerSfx(cli);
-	registerMusic(cli);
-	registerAudio(cli);
+	// The register* helpers take the untyped Cli: the display var is read through
+	// `displayModeOf`, so they do not depend on this CLI's generics.
+	const root = cli as unknown as Cli.Cli;
+	registerVersion(root);
+	registerDoctor(root);
+	registerInit(root);
+	registerGfx(root);
+	registerTokens(root);
+	registerLint(root);
+	registerMinify(root);
+	registerVerify(root);
+	registerRun(root);
+	registerExport(root);
+	registerServe(root);
+	registerPlaytest(root);
+	registerSfx(root);
+	registerMusic(root);
+	registerAudio(root);
 
-	return cli;
+	return root;
 }

package/src/commands/audio.test.ts

@@ -19,7 +19,7 @@ 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 {type Pico8AdapterFactory, registerAudio} from './audio.js';
 
 const HEADER = 'pico-8 cartridge // http://www.pico-8.com\nversion 42\n';
@@ -290,3 +290,66 @@ describe('audio: honest help text (record-based, NOT an offline export)', () =>
 		expect(lower).toContain('offline export');
 	});
 });
+
+describe('audio record/render: headless (ADR-0017)', () => {
+	it('record inlines `#include main.lua` so the harness loads from the temp wavDir', async () => {
+		writeFileSync(cartPath, `${HEADER}__lua__\n#include main.lua\n`);
+		writeFileSync(
+			join(dir, 'main.lua'),
+			'function _update() from_main=1 end\n',
+		);
+		const seen: {record?: RecordOptions} = {};
+		await runAudio(
+			() => stubAdapter(recorded(undefined), seen),
+			['audio', 'record', cartPath, '--json'],
+		);
+		const harness = readFileSync(seen.record!.cartPath, 'utf8');
+		expect(harness).not.toMatch(/#include/);
+		expect(harness).toContain('from_main=1');
+	});
+
+	for (const sub of [
+		['audio', 'record'],
+		['audio', 'render', '--sfx', '0'],
+	]) {
+		it(`${sub.join(' ')}: display-unavailable is a structured error naming the fix`, async () => {
+			const {stdout, exitCode} = await runAudio(
+				() => stubAdapter(displayUnavailable('no display, no Xvfb')),
+				[
+					...sub.slice(0, 2),
+					cartPath,
+					...sub.slice(2),
+					'--json',
+					'--full-output',
+				],
+			);
+			expect(exitCode).not.toBe(0);
+			const out = JSON.parse(stdout);
+			expect(out.error.code).toBe('display-unavailable');
+			expect(out.meta.cta.description).toMatch(/install Xvfb/);
+		});
+	}
+
+	it('a run with no WAV reports noAudioReason, pico8LogTail and the display used', async () => {
+		const {stdout} = await runAudio(
+			() =>
+				stubAdapter({
+					ok: true,
+					value: {
+						wavPath: undefined,
+						printh: '',
+						exitReason: 'timeout',
+						display: 'Xvfb',
+						noWavReason: 'the backstop fired',
+						pico8LogTail: 'could not include main.lua',
+					},
+				}),
+			['audio', 'record', cartPath, '--json'],
+		);
+		const out = JSON.parse(stdout);
+		expect(out.captured).toBe(false);
+		expect(out.display).toBe('Xvfb');
+		expect(out.noAudioReason).toBe('the backstop fired');
+		expect(out.pico8LogTail).toContain('main.lua');
+	});
+});

package/src/commands/audio.ts

@@ -14,21 +14,28 @@ import {
 	buildRenderHarness,
 	DONE_SENTINEL,
 	HarnessError,
-	type Pico8Adapter,
+	type Pico8RecordResult,
 	type RenderTarget,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+import {
+	createShellAdapterFactory,
+	displayModeOf,
+	displayUnavailableError,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+	pico8NotFoundError,
+} from './pico8-env.js';
 
 /**
  * Injects the PICO-8 adapter the audio commands use (defaults to the shell
  * adapter over native `pico8 -run`). Mirrors `run`'s `Pico8AdapterFactory` seam:
  * a test passes a fake to drive the record orchestration + the absent path
- * WITHOUT the paid binary, and to isolate the child `env`.
+ * 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 record backstop: kill a capture that never signals after this many
@@ -39,7 +46,7 @@ const DEFAULT_BACKSTOP_MS = 30_000;
 
 /** The honest one-liner both `record` and `render` carry (ADR-0009): not offline. */
 const HONEST_CAVEAT =
-	'This is a REAL-TIME recording of playback (needs a real audio+video session, not headless), NOT a deterministic offline export.';
+	'This is a REAL-TIME recording of playback in a -run session, NOT a deterministic offline export. Works headless: with no display, picopilot runs the session on a private virtual display (ADR-0017, --display).';
 
 /** Resolves a path argument to an absolute path (relative to cwd). */
 function resolvePath(p: string): string {
@@ -64,14 +71,8 @@ function chooseWavDir(given: string | undefined): string {
 	return dir;
 }
 
-/** The env schema both audio subcommands share (locates the binary, in isolation). */
-const AUDIO_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`.'),
-});
+/** The env schema both audio subcommands share (locates the binary). */
+const AUDIO_ENV = PICO8_ENV;
 
 /** The structured output shape shared by `record` and `render`. */
 const AUDIO_OUTPUT = z.object({
@@ -79,7 +80,7 @@ const AUDIO_OUTPUT = z.object({
 		.string()
 		.optional()
 		.describe(
-			'Absolute path of the recorded WAV, or omitted if no audio was captured (e.g. a headless session with no audio device).',
+			'Absolute path of the recorded WAV, or omitted if no audio was captured (see noAudioReason).',
 		),
 	captured: z
 		.boolean()
@@ -98,41 +99,60 @@ const AUDIO_OUTPUT = z.object({
 		.number()
 		.describe('The record window in seconds the capture ran for.'),
 	printh: z.string().describe('Captured stdout from the session.'),
+	display: z
+		.enum(['native', 'Xvfb', 'xvfb-run'])
+		.optional()
+		.describe(
+			'Which display the -run session used: native, or a private virtual display (Xvfb / xvfb-run).',
+		),
+	noAudioReason: z
+		.string()
+		.optional()
+		.describe(
+			'When no WAV was captured: why (backstop fired / PICO-8 exited before the done-sentinel / empty capture).',
+		),
+	pico8LogTail: z
+		.string()
+		.optional()
+		.describe(
+			"When no WAV was captured: the tail of PICO-8's own log.txt (load errors, SDL init failures).",
+		),
 });
 
-/** The message a `pico8-not-found` error carries (mirrors `run`): exact remedy + needs. */
-function pico8NotFoundMessage(notFound: {
-	remedy: string;
-	needs: readonly string[];
-}): string {
-	return `PICO-8 is not installed. ${notFound.remedy} (needs: ${notFound.needs.join(', ')})`;
-}
-
 /**
- * The advisory CTA when a record/render run captured NO audio (a headless /
- * no-audio-device session): the orchestration worked, there is just nothing to
- * hear (ADR-0009's live-tier caveat), so it is a nudge, not a hard error.
+ * The advisory CTA when a record/render run captured NO audio. The report's
+ * `noAudioReason` + `pico8LogTail` say why; this points at the next step.
  */
-function noAudioCta(caveat: string) {
+function noAudioCta(reason: string | undefined) {
 	return {
-		description: `No audio was captured (${caveat}) Recording needs a real audio+video session:`,
+		description: `No audio was captured${reason !== undefined ? ` (${reason})` : ''}. Next:`,
 		commands: [
 			{
-				command: 'audio render --sfx <n>',
+				command: 'verify',
 				description:
-					'Run on a developer machine with a display + audio device (not headless CI).',
+					'Run the static gate: a cart that fails to load or errors never reaches audio_end.',
+			},
+			{
+				command: 'doctor',
+				description: 'Check PICO-8 and display capabilities on this machine.',
 			},
 		],
 	};
 }
 
+/** Maps a failed record result onto the structured `error(...)` payload. */
+function recordFailure(
+	what: string,
+	result: Exclude<Pico8RecordResult, {ok: true}>,
+) {
+	return result.reason === 'display-unavailable'
+		? displayUnavailableError(what, result)
+		: pico8NotFoundError(result);
+}
+
 /** Shapes an adapter record report into the structured output object. */
 function recordOutput(
-	report: {
-		wavPath: string | undefined;
-		printh: string;
-		exitReason: 'sentinel' | 'timeout' | 'exit';
-	},
+	report: Extract<Pico8RecordResult, {ok: true}>['value'],
 	harness: {seconds: number; description: string},
 ) {
 	return {
@@ -142,6 +162,13 @@ function recordOutput(
 		target: harness.description,
 		seconds: harness.seconds,
 		printh: report.printh,
+		...(report.display !== undefined ? {display: report.display} : {}),
+		...(report.noWavReason !== undefined
+			? {noAudioReason: report.noWavReason}
+			: {}),
+		...(report.pico8LogTail !== undefined
+			? {pico8LogTail: report.pico8LogTail}
+			: {}),
 	};
 }
 
@@ -154,7 +181,7 @@ function recordOutput(
 function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 	const audio = Cli.create('audio', {
 		description:
-			'Get a WAV out of a cart by RECORDING a running session (ADR-0009). PICO-8 has no working offline WAV export, so both commands are REAL-TIME recordings that need a real audio+video session (not headless), NOT deterministic offline exports. Requires PICO-8.',
+			'Get a WAV out of a cart by RECORDING a running session (ADR-0009). PICO-8 has no working offline WAV export, so both commands are REAL-TIME recordings of a -run session, NOT deterministic offline exports. They work headless: with no display, picopilot runs the session on a private virtual display (ADR-0017). Requires PICO-8.',
 	});
 
 	// --- audio record <cart> ---------------------------------------------------
@@ -203,7 +230,7 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				options: {seconds: 4},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			const cartPath = resolvePath(args.cart);
 			if (!existsSync(cartPath)) {
 				return error({
@@ -215,9 +242,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 
 			let harness: ReturnType<typeof buildRecordHarness>;
 			try {
+				// `#include`s are inlined against the SOURCE cart's folder: the harness
+				// runs from the isolated wavDir, where `main.lua` does not exist.
 				harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
 					seconds: options.seconds,
 					sentinel: options.sentinel,
+					readInclude: makeReadInclude(cartPath),
 				});
 			} catch (e) {
 				if (e instanceof HarnessError) {
@@ -232,7 +262,9 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 			const harnessCart = join(wavDir, 'record-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				wavDir,
@@ -241,18 +273,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				backstopMs: options.backstopMs,
 			});
 
-			if (!result.ok) {
-				return error({
-					code: 'pico8-not-found',
-					message: pico8NotFoundMessage(result),
-					exitCode: 1,
-				});
-			}
+			if (!result.ok) return error(recordFailure('audio record', result));
 
 			const out = recordOutput(result.value, harness);
 			return ok(
 				out,
-				out.captured ? undefined : {cta: noAudioCta(HONEST_CAVEAT)},
+				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
 			);
 		},
 	});
@@ -324,7 +350,7 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				options: {pattern: 2, seconds: 6},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			if (options.sfx !== undefined && options.pattern !== undefined) {
 				return error({
 					code: 'ambiguous-target',
@@ -368,7 +394,9 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 			const harnessCart = join(wavDir, 'render-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				wavDir,
@@ -377,18 +405,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				backstopMs: options.backstopMs,
 			});
 
-			if (!result.ok) {
-				return error({
-					code: 'pico8-not-found',
-					message: pico8NotFoundMessage(result),
-					exitCode: 1,
-				});
-			}
+			if (!result.ok) return error(recordFailure('audio render', result));
 
 			const out = recordOutput(result.value, harness);
 			return ok(
 				out,
-				out.captured ? undefined : {cta: noAudioCta(HONEST_CAVEAT)},
+				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
 			);
 		},
 	});