picopilot 0.2.0 → 0.3.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAoE7B;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,GAAG,CAAC,GAAG,CAqFnC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AA+I7B;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,GAAG,CAAC,GAAG,CAkHnC"}

package/dist/cli.js

@@ -1,4 +1,6 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 import { Cli, z } from 'incur';
 import { registerAudio } from './commands/audio.js';
 import { registerDoctor } from './commands/doctor.js';
@@ -17,13 +19,79 @@ 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 = new Set([
-    'run',
-    'audio record',
-    'audio render',
-    'doctor',
-]);
+/** The config files picopilot searches (first existing wins), relative to the cwd. */
+const CONFIG_FILES = ['picopilot.json'];
+/**
+ * Removes every `--display <v>` / `--display=<v>` from argv and returns the last
+ * value. A `--display` with no value (last token, or followed by another flag)
+ * stays in argv, so incur rejects it instead of it silently eating the next flag.
+ */
+function takeDisplayFlag(argv) {
+    const rest = [];
+    let display;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+        if (a === '--display' && next !== undefined && !next.startsWith('-')) {
+            display = next;
+            i++;
+        }
+        else if (a.startsWith('--display=') && a.length > '--display='.length) {
+            display = a.slice('--display='.length);
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { argv: rest, display };
+}
+/** Resolves a config path the way incur does: `~` is the home dir, else relative to the cwd. */
+function resolveConfigPath(path) {
+    return path === '~' || path.startsWith('~/')
+        ? join(homedir(), path.slice(1))
+        : resolve(path);
+}
+/**
+ * For `--mcp`: the config file incur would have loaded on the CLI. Mirrors
+ * incur's own parsing: `--config <p>` / `--config=<p>` / `--no-config`, the last
+ * one wins, a missing value is an error; else the first existing default file.
+ */
+function loadMcpConfig(argv) {
+    let explicit;
+    let disabled = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        let value;
+        if (a === '--config')
+            value = argv[++i];
+        else if (a.startsWith('--config='))
+            value = a.slice('--config='.length);
+        else if (a === '--no-config') {
+            explicit = undefined;
+            disabled = true;
+            continue;
+        }
+        else
+            continue;
+        if (value === undefined || value === '') {
+            throw new Error('Missing value for flag: --config');
+        }
+        explicit = value;
+        disabled = false;
+    }
+    if (disabled)
+        return undefined;
+    const sink = {};
+    if (explicit !== undefined) {
+        return loadConfig(resolveConfigPath(explicit), sink);
+    }
+    for (const file of CONFIG_FILES) {
+        const path = resolveConfigPath(file);
+        if (existsSync(path))
+            return loadConfig(path, sink);
+    }
+    return undefined;
+}
 /**
  * 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
@@ -82,18 +150,12 @@ export function createCli() {
         // Per-cart policy config (e.g. `allowMapOverlap`); precedence argv > config > defaults.
         config: {
             flag: 'config',
-            files: ['picopilot.json'],
+            files: CONFIG_FILES,
             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).'),
-        }),
+        // The display mode (ADR-0017): `--display` (a per-command option on the
+        // commands that use it, also accepted anywhere on the command line and on
+        // `--mcp`) > PICOPILOT_DISPLAY > picopilot.json `display` > auto.
         env: z.object({
             [DISPLAY_ENV_VAR]: z
                 .string()
@@ -102,35 +164,66 @@ export function createCli() {
         }),
         vars: z.object({
             display: z.enum(DISPLAY_MODES).default(DEFAULT_DISPLAY_MODE),
+            displayError: z.string().optional(),
+            mcpConfig: z.record(z.string(), z.unknown()).optional(),
         }),
+        mcp: {
+            // One MCP tool per command (incur's default is progressive discovery
+            // behind search/call meta-tools); picopilot's surface is small, and the
+            // skills name commands directly.
+            tools: { discovery: 'direct' },
+        },
     });
+    const invocation = { mcp: false };
     cli.use(async (c, next) => {
-        const configured = configSink.display;
+        const configured = invocation.mcp
+            ? invocation.mcpConfig?.[DISPLAY_CONFIG_KEY]
+            : 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,
+            flag: invocation.display,
             env: c.env[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,
-            });
+        if (resolved.ok) {
+            c.set('display', resolved.mode);
+        }
+        else {
+            // Not an error here: only the commands that USE the display mode fail
+            // on a bad value (see resolveCommandDisplay); the rest run as usual.
+            const where = resolved.source === 'flag'
+                ? '--display'
+                : resolved.source === 'env'
+                    ? DISPLAY_ENV_VAR
+                    : `picopilot.json "${DISPLAY_CONFIG_KEY}"`;
+            c.set('displayError', `${where} is "${resolved.value}"; expected one of: ${DISPLAY_MODES.join(', ')}.`);
+        }
+        if (invocation.mcp && invocation.mcpConfig !== undefined) {
+            c.set('mcpConfig', invocation.mcpConfig);
         }
-        c.set('display', resolved.mode);
         await next();
     });
+    // Capture the top-level `--display` (and, for `--mcp`, the config) before
+    // incur parses argv; see {@link Invocation}.
+    const serve = cli.serve.bind(cli);
+    cli.serve = async (argv = process.argv.slice(2), options) => {
+        const taken = takeDisplayFlag(argv);
+        invocation.display = taken.display;
+        invocation.mcp = taken.argv.includes('--mcp');
+        invocation.mcpConfig = undefined;
+        if (invocation.mcp) {
+            try {
+                invocation.mcpConfig = loadMcpConfig(taken.argv);
+            }
+            catch (e) {
+                // A broken config must stop the server visibly, not serve without it.
+                process.stderr.write(`picopilot --mcp: ${e instanceof Error ? e.message : String(e)}\n`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        return serve(taken.argv, options);
+    };
     // 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;

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/audio.d.ts

@@ -8,8 +8,29 @@ import { type Pico8AdapterFactory } from './pico8-env.js';
  */
 export type { Pico8AdapterFactory } from './pico8-env.js';
 /**
- * Registers the `audio` command group (`audio record`, `audio render`) on the
- * root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
+ * The startup margin added to the record window for the default backstop. A
+ * recording is real time, so the backstop must cover PICO-8 startup (a virtual
+ * display, loading the cart) PLUS the whole record window. A fixed 30 s backstop
+ * used to kill any window of ~24 s or more before `audio_end`.
+ */
+export declare const RECORD_STARTUP_MARGIN_MS = 30000;
+/** The least startup time an explicit backstop must leave beyond the window. */
+export declare const RECORD_MIN_STARTUP_MS = 5000;
+/**
+ * The backstop for a record window: the explicit `--backstop-ms` when it leaves
+ * at least {@link RECORD_MIN_STARTUP_MS} for startup, else a refusal; or, when
+ * none is given, the window plus {@link RECORD_STARTUP_MARGIN_MS}.
+ */
+export declare function resolveRecordBackstop(seconds: number, explicit: number | undefined): {
+    ok: true;
+    ms: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Registers the `audio` command group (`audio record`, `audio render`, `audio
+ * analyze`) on the root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
  * session, never an offline export. `adapterFactory` is injected so tests drive
  * the orchestration against a fake runner (no paid binary in CI).
  */

package/dist/commands/audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/commands/audio.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAW7B,OAAO,EAKN,KAAK,mBAAmB,EAExB,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,YAAY,EAAC,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAiYxD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,mBAA2C,GACzD,IAAI,CAEN"}
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/commands/audio.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAkB7B,OAAO,EAKN,KAAK,mBAAmB,EAGxB,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,YAAY,EAAC,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAIxD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAavD;AA6lBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,mBAA2C,GACzD,IAAI,CAEN"}

package/dist/commands/audio.js

@@ -2,16 +2,46 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, } from
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { Cli, z } from 'incur';
+import { analyzeAudio, AudioAnalyzeError, decodeWav, THRESHOLDS, } from '../engine/audio/index.js';
 import { buildRecordHarness, buildRenderHarness, DONE_SENTINEL, HarnessError, } from '../engine/pico8/index.js';
 import { makeReadInclude } from './cart-includes.js';
-import { createShellAdapterFactory, displayModeOf, displayUnavailableError, PICO8_ENV, pico8NotFoundError, } from './pico8-env.js';
+import { createShellAdapterFactory, DISPLAY_OPTION, displayUnavailableError, PICO8_ENV, pico8NotFoundError, resolveCommandDisplay, } from './pico8-env.js';
 const defaultAdapterFactory = createShellAdapterFactory();
 /**
- * The default record backstop: kill a capture that never signals after this many
- * ms. Larger than `run`'s default because a record window is a real-time playback
- * (up to several seconds) plus PICO-8 startup, not a quick screenshot pass.
+ * The startup margin added to the record window for the default backstop. A
+ * recording is real time, so the backstop must cover PICO-8 startup (a virtual
+ * display, loading the cart) PLUS the whole record window. A fixed 30 s backstop
+ * used to kill any window of ~24 s or more before `audio_end`.
  */
-const DEFAULT_BACKSTOP_MS = 30_000;
+export const RECORD_STARTUP_MARGIN_MS = 30_000;
+/** The least startup time an explicit backstop must leave beyond the window. */
+export const RECORD_MIN_STARTUP_MS = 5_000;
+/**
+ * The backstop for a record window: the explicit `--backstop-ms` when it leaves
+ * at least {@link RECORD_MIN_STARTUP_MS} for startup, else a refusal; or, when
+ * none is given, the window plus {@link RECORD_STARTUP_MARGIN_MS}.
+ */
+export function resolveRecordBackstop(seconds, explicit) {
+    const windowMs = Math.ceil(seconds * 1000);
+    if (explicit === undefined) {
+        return { ok: true, ms: windowMs + RECORD_STARTUP_MARGIN_MS };
+    }
+    const least = windowMs + RECORD_MIN_STARTUP_MS;
+    if (explicit < least) {
+        return {
+            ok: false,
+            message: `--backstop-ms ${explicit} is too small for a ${seconds} s record window: PICO-8 would be killed before the recording ends (it also needs a few seconds to start). Use at least ${least}, or omit --backstop-ms (the default is the window + ${RECORD_STARTUP_MARGIN_MS / 1000} s).`,
+        };
+    }
+    return { ok: true, ms: explicit };
+}
+/** The `--backstop-ms` option both audio subcommands share. */
+const BACKSTOP_OPTION = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(`Safety backstop: kill PICO-8 after this many ms if it never signals. Default: the record window + ${RECORD_STARTUP_MARGIN_MS / 1000} s of startup margin. An explicit value smaller than the window + ${RECORD_MIN_STARTUP_MS / 1000} s is refused.`);
 /** The honest one-liner both `record` and `render` carry (ADR-0009): not offline. */
 const HONEST_CAVEAT = '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). */
@@ -37,6 +67,82 @@ function chooseWavDir(given) {
 }
 /** The env schema both audio subcommands share (locates the binary). */
 const AUDIO_ENV = PICO8_ENV;
+/** The structured analysis of a recording (`audio analyze`, `--analyze`). */
+const ANALYSIS_OUTPUT = z.object({
+    sampleRate: z.number(),
+    durationSeconds: z.number(),
+    skippedSeconds: z
+        .number()
+        .describe('Seconds skipped at the start (PICO-8 startup).'),
+    analyzedSeconds: z.number(),
+    loudness: z.object({
+        meanRms: z
+            .number()
+            .describe(`Mean RMS of 2048-sample frames (0-1). Accepted game music: 0.07-0.10; over ${THRESHOLDS.loudMeanRms} warns.`),
+        medianRms: z.number(),
+        peakFrameRms: z.number().describe('The loudest frame.'),
+        peakFrameAtSeconds: z
+            .number()
+            .describe('When the loudest frame starts (s from file start).'),
+        peakSample: z.number().describe('99.9th-percentile absolute sample.'),
+        silentPercent: z.number().describe('Share of silent frames (%).'),
+    }),
+    brightness: z.object({
+        centroidHz: z
+            .number()
+            .describe(`Median spectral centroid (Hz). Accepted: under 500; over ${THRESHOLDS.shrillCentroidHz} is shrill.`),
+        above2kHzPercent: z
+            .number()
+            .describe(`Share of energy above 2 kHz (%). Accepted: about 0.2; over ${THRESHOLDS.shrillAbove2kHzPercent} is shrill.`),
+    }),
+    dynamicRangeDb: z
+        .number()
+        .describe(`p90 - p10 of frame level, silence excluded (dB). Accepted: 7-8; under ${THRESHOLDS.flatRangeDb} is monotonous.`),
+    profile: z.object({
+        stepSeconds: z.number(),
+        rms: z.array(z.number()),
+        sparkline: z.string().describe('The loudness profile as a bar chart.'),
+    }),
+    loop: z
+        .object({
+        seconds: z.number().nullable(),
+        confidence: z.number().optional(),
+        reason: z.string().optional(),
+    })
+        .describe('The repetition length (needs the loop to appear twice in the recording).'),
+    against: z
+        .object({ referenceRms: z.number(), musicOverReferenceDb: z.number() })
+        .optional(),
+    warnings: z
+        .array(z.object({ code: z.string(), message: z.string() }))
+        .describe('Plain-language findings; empty = nothing flagged.'),
+});
+/** The `--analyze` option of record/render. */
+const ANALYZE_OPTION = z
+    .boolean()
+    .default(false)
+    .describe('Also analyze the captured WAV (loudness, brightness, dynamic range, profile, loop length, warnings), as `audio analyze` does.');
+/**
+ * Analyzes a captured WAV for `--analyze`, or explains why it could not. Never
+ * fails the recording itself.
+ */
+function analyzeCapture(wavPath, kind) {
+    if (wavPath === undefined)
+        return undefined;
+    try {
+        // An SFX render starts recording on the frame the SFX starts: skip
+        // nothing, or a short SFX would be measured on its silent tail only.
+        return {
+            analysis: analyzeAudio(decodeWav(readFileSync(wavPath)), {
+                kind,
+                skipSeconds: kind === 'sfx' ? 0 : 1,
+            }),
+        };
+    }
+    catch (e) {
+        return { analysisError: e instanceof Error ? e.message : String(e) };
+    }
+}
 /** The structured output shape shared by `record` and `render`. */
 const AUDIO_OUTPUT = z.object({
     wav: z
@@ -68,6 +174,11 @@ const AUDIO_OUTPUT = z.object({
         .string()
         .optional()
         .describe("When no WAV was captured: the tail of PICO-8's own log.txt (load errors, SDL init failures)."),
+    analysis: ANALYSIS_OUTPUT.optional().describe('With --analyze: the analysis of the captured WAV.'),
+    analysisError: z
+        .string()
+        .optional()
+        .describe('With --analyze: why the WAV could not be analyzed.'),
 });
 /**
  * The advisory CTA when a record/render run captured NO audio. The report's
@@ -120,7 +231,7 @@ function recordOutput(report, harness) {
  */
 function buildAudioGroup(adapterFactory) {
     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 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.',
+        description: 'Get a WAV out of a cart by RECORDING a running session (ADR-0009), and measure it. PICO-8 has no working offline WAV export, so `record` and `render` 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) and require PICO-8. `analyze` measures a WAV (loudness, brightness, dynamics, loop length) and needs nothing.',
     });
     // --- audio record <cart> ---------------------------------------------------
     audio.command('record', {
@@ -145,12 +256,9 @@ function buildAudioGroup(adapterFactory) {
                 .string()
                 .default(DONE_SENTINEL)
                 .describe('The stdout line that ends the recording.'),
-            backstopMs: z
-                .number()
-                .int()
-                .positive()
-                .default(DEFAULT_BACKSTOP_MS)
-                .describe('Safety backstop: kill PICO-8 after this many ms if it never signals.'),
+            backstopMs: BACKSTOP_OPTION,
+            analyze: ANALYZE_OPTION,
+            display: DISPLAY_OPTION,
         }),
         env: AUDIO_ENV,
         output: AUDIO_OUTPUT,
@@ -187,24 +295,40 @@ function buildAudioGroup(adapterFactory) {
                 }
                 throw e;
             }
+            const backstop = resolveRecordBackstop(harness.seconds, options.backstopMs);
+            if (!backstop.ok) {
+                return error({
+                    code: 'audio-backstop-too-small',
+                    message: backstop.message,
+                    exitCode: 1,
+                });
+            }
             // The throwaway harness cart + the WAV both live in the isolated dir, so a
             // record run never mutates the user's cart or writes outside the temp dir.
             const wavDir = chooseWavDir(options.wavDir);
             const harnessCart = join(wavDir, 'record-harness.p8');
             writeFileSync(harnessCart, harness.cartText);
+            const display = resolveCommandDisplay(options.display, vars);
+            if (!display.ok)
+                return error(display.error);
             const adapter = adapterFactory(env, {
-                display: displayModeOf(vars),
+                display: display.mode,
             });
             const result = await adapter.record({
                 cartPath: harnessCart,
                 wavDir,
                 wavBasename: harness.wavBasename,
                 sentinel: options.sentinel,
-                backstopMs: options.backstopMs,
+                backstopMs: backstop.ms,
             });
             if (!result.ok)
                 return error(recordFailure('audio record', result));
-            const out = recordOutput(result.value, harness);
+            const out = {
+                ...recordOutput(result.value, harness),
+                ...(options.analyze
+                    ? analyzeCapture(result.value.wavPath, 'music')
+                    : {}),
+            };
             return ok(out, out.captured ? undefined : { cta: noAudioCta(out.noAudioReason) });
         },
     });
@@ -245,12 +369,9 @@ function buildAudioGroup(adapterFactory) {
                 .string()
                 .default(DONE_SENTINEL)
                 .describe('The stdout line that ends the recording.'),
-            backstopMs: z
-                .number()
-                .int()
-                .positive()
-                .default(DEFAULT_BACKSTOP_MS)
-                .describe('Safety backstop: kill PICO-8 after this many ms if it never signals.'),
+            backstopMs: BACKSTOP_OPTION,
+            analyze: ANALYZE_OPTION,
+            display: DISPLAY_OPTION,
         }),
         env: AUDIO_ENV,
         output: AUDIO_OUTPUT,
@@ -299,30 +420,122 @@ function buildAudioGroup(adapterFactory) {
                 }
                 throw e;
             }
+            const backstop = resolveRecordBackstop(harness.seconds, options.backstopMs);
+            if (!backstop.ok) {
+                return error({
+                    code: 'audio-backstop-too-small',
+                    message: backstop.message,
+                    exitCode: 1,
+                });
+            }
             const wavDir = chooseWavDir(options.wavDir);
             const harnessCart = join(wavDir, 'render-harness.p8');
             writeFileSync(harnessCart, harness.cartText);
+            const display = resolveCommandDisplay(options.display, vars);
+            if (!display.ok)
+                return error(display.error);
             const adapter = adapterFactory(env, {
-                display: displayModeOf(vars),
+                display: display.mode,
             });
             const result = await adapter.record({
                 cartPath: harnessCart,
                 wavDir,
                 wavBasename: harness.wavBasename,
                 sentinel: options.sentinel,
-                backstopMs: options.backstopMs,
+                backstopMs: backstop.ms,
             });
             if (!result.ok)
                 return error(recordFailure('audio render', result));
-            const out = recordOutput(result.value, harness);
+            const out = {
+                ...recordOutput(result.value, harness),
+                ...(options.analyze
+                    ? analyzeCapture(result.value.wavPath, target.kind === 'sfx' ? 'sfx' : 'music')
+                    : {}),
+            };
             return ok(out, out.captured ? undefined : { cta: noAudioCta(out.noAudioReason) });
         },
     });
+    // --- audio analyze <wav> ----------------------------------------------------
+    audio.command('analyze', {
+        description: `Measure a WAV (from \`audio render\` / \`audio record\`) so a model that cannot hear can judge it: loudness (mean/peak RMS, loudest moment), brightness (spectral centroid, energy above 2 kHz), dynamic range, a loudness profile per half second, and the loop length, plus plain-language warnings (loud, shrill, monotonous, spikes, repetitive). Skips the first second by default (as the calibration did); thresholds are for music, \`--kind sfx\` keeps only the checks that apply to a one-shot sound. --against <sfx.wav> compares the music's loudness with a rendered SFX, so the music sits under the SFX. Pure TypeScript: needs neither PICO-8 nor Python.`,
+        args: z.object({
+            wav: z.string().describe('The WAV file to analyze.'),
+        }),
+        options: z.object({
+            skip: z.coerce
+                .number()
+                .min(0)
+                .default(1)
+                .describe('Seconds to skip at the start (default 1, as in the calibration; use 0 for an SFX render). Ignored when the WAV is too short for it.'),
+            kind: z
+                .enum(['music', 'sfx'])
+                .default('music')
+                .describe('music: every warning; sfx: a one-shot sound, only near-silent / near-clipping (the music thresholds do not apply).'),
+            against: z
+                .string()
+                .optional()
+                .describe('A reference SFX WAV (e.g. from `audio render --sfx 7`): report the music level relative to it and warn when the music is not quieter.'),
+        }),
+        output: ANALYSIS_OUTPUT,
+        examples: [
+            {
+                description: 'Analyze a rendered song',
+                args: { wav: '/tmp/picopilot-audio-x/picopilot-audio.wav' },
+            },
+            {
+                description: 'Check the music sits under an SFX',
+                args: { wav: 'music.wav' },
+                options: { against: 'explosion.wav' },
+            },
+        ],
+        run({ args, options, error, ok }) {
+            const read = (p) => {
+                const abs = resolvePath(p);
+                if (!existsSync(abs)) {
+                    throw new AudioAnalyzeError('audio-analyze-bad-wav', `no WAV at ${abs}`);
+                }
+                return decodeWav(readFileSync(abs));
+            };
+            let analysis;
+            try {
+                analysis = analyzeAudio(read(args.wav), {
+                    skipSeconds: options.skip,
+                    kind: options.kind,
+                    ...(options.against !== undefined
+                        ? { against: read(options.against) }
+                        : {}),
+                });
+            }
+            catch (e) {
+                if (e instanceof AudioAnalyzeError) {
+                    return error({ code: e.code, message: e.message, exitCode: 1 });
+                }
+                throw e;
+            }
+            return ok(analysis, analysis.warnings.length > 0
+                ? {
+                    cta: {
+                        description: 'Fix the flagged issues in the score, then measure again:',
+                        commands: [
+                            {
+                                command: 'music from-score --file <score.json>',
+                                description: 'Rewrite the music.',
+                            },
+                            {
+                                command: 'audio render --pattern <n> --analyze',
+                                description: 'Record and analyze it again.',
+                            },
+                        ],
+                    },
+                }
+                : undefined);
+        },
+    });
     return audio;
 }
 /**
- * Registers the `audio` command group (`audio record`, `audio render`) on the
- * root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
+ * Registers the `audio` command group (`audio record`, `audio render`, `audio
+ * analyze`) on the root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
  * session, never an offline export. `adapterFactory` is injected so tests drive
  * the orchestration against a fake runner (no paid binary in CI).
  */