picopilot 0.0.0 → 0.1.0

package/dist/engine/pico8/shell.js

@@ -0,0 +1,324 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, statSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { EXPORT_HTML_NAME, pico8NotFound, RECORD_WAV_BASENAME, } from './adapter.js';
+import { SentinelWatcher } from './sentinel.js';
+/**
+ * The default {@link SpawnRunner}: `spawn` with stdin detached (`ignore`) so the
+ * cart never blocks on console input, stdout/stderr piped for the sentinel
+ * watch. A spawn failure surfaces via `onError` (ENOENT ⇒ absent). `kill` sends
+ * SIGKILL to the whole tree (`detached` + negative pid) so a hung PICO-8 dies.
+ */
+/**
+ * An isolated directory to hand PICO-8 as its `-home`, so it writes its config /
+ * data tree (`config.txt`, `log.txt`, `sdl_controllers.txt`, `backup/`, `carts/`,
+ * `bbs/`, `cdata/`, `cstore/`, `plates/`) THERE and never litters the caller's
+ * CWD. Without `-home`, PICO-8 creates that tree in whatever directory it was
+ * spawned from, e.g. a user's repo root (see
+ * work/notes/observations/pico8-appimage-writes-config-into-cwd.md). Verified:
+ * `-home <dir>` fully redirects every one of those files/dirs.
+ *
+ * One dir per process, created lazily under the OS temp dir and reused by every
+ * launch (run/drive/export/record/session). It is throwaway config, so OS temp
+ * cleanup reclaims it; picopilot never needs its contents.
+ */
+let cachedHome;
+export function pico8HomeDir() {
+    if (cachedHome !== undefined && existsSync(cachedHome))
+        return cachedHome;
+    cachedHome = mkdtempSync(join(tmpdir(), 'picopilot-pico8-home-'));
+    return cachedHome;
+}
+/**
+ * Prepend `-home <isolatedDir>` to a PICO-8 arg list so its config/data never
+ * land in the CWD. Applied at every spawn site.
+ */
+export function withPico8Home(args) {
+    const home = pico8HomeDir();
+    mkdirSync(home, { recursive: true });
+    return ['-home', home, ...args];
+}
+export const spawnRunner = (file, args, env, options) => {
+    // `drive` pipes fixed-size command blocks to stdin; `run`/`record` detach it so
+    // the cart never blocks on console input.
+    const stdin = options?.stdin === true ? 'pipe' : 'ignore';
+    const child = spawn(file, args, {
+        env,
+        stdio: [stdin, 'pipe', 'pipe'],
+        detached: true,
+    });
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    return {
+        onStdout(cb) {
+            child.stdout?.on('data', cb);
+            child.stderr?.on('data', cb);
+        },
+        onClose(cb) {
+            child.on('close', cb);
+        },
+        onError(cb) {
+            child.on('error', cb);
+        },
+        writeStdin(bytes) {
+            try {
+                child.stdin?.write(Buffer.from(bytes));
+            }
+            catch {
+                // A closed stdin (the cart exited) is not fatal to the run.
+            }
+        },
+        kill() {
+            try {
+                // Negative pid kills the process GROUP (detached), so any child dies too.
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL'); // fall back to killing just the process
+            }
+        },
+    };
+};
+/** The candidate ways to launch PICO-8, tried in order: `PICO8_PATH`, then `pico8` on `PATH`. */
+export function pico8Candidates(env) {
+    const fromEnv = env.PICO8_PATH?.trim();
+    return fromEnv !== undefined && fromEnv.length > 0
+        ? [fromEnv, 'pico8']
+        : ['pico8'];
+}
+/**
+ * The files an export produced in `outDir`, absolute + sorted. PICO-8 writes the
+ * `<name>.html` shell and the `<name>.js` runtime payload; we return every file
+ * present so the report is faithful even if a future PICO-8 adds siblings.
+ */
+function collectExportFiles(outDir) {
+    if (!existsSync(outDir))
+        return [];
+    return readdirSync(outDir)
+        .sort()
+        .map((f) => join(outDir, f))
+        .filter((p) => {
+        try {
+            return statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** PNG files a run produced in its `-desktop` dir, sorted for deterministic order. */
+function collectScreenshots(shotDir) {
+    if (!existsSync(shotDir))
+        return [];
+    return readdirSync(shotDir)
+        .filter((f) => f.toLowerCase().endsWith('.png'))
+        .sort()
+        .map((f) => join(shotDir, f));
+}
+/**
+ * The WAV a record run produced in its `wavDir`, or `undefined`. Prefers the
+ * expected `<basename>.wav` (what the harness named via `set_filename`); falls
+ * back to any single `.wav` present. A well-formed but EMPTY WAV (a headless
+ * `-x` capture yields a 44-byte 0-frame RIFF header, ADR-0009) is treated as
+ * "no usable WAV" so a silent capture is not reported as a real recording.
+ */
+function collectWav(wavDir, basename) {
+    if (!existsSync(wavDir))
+        return undefined;
+    const wavs = readdirSync(wavDir).filter((f) => f.toLowerCase().endsWith('.wav'));
+    if (wavs.length === 0)
+        return undefined;
+    const expected = `${basename}.wav`;
+    const chosen = wavs.includes(expected) ? expected : wavs.sort()[0];
+    const path = join(wavDir, chosen);
+    // A 44-byte RIFF header with no PCM data is the empty/silent (headless) WAV.
+    try {
+        if (statSync(path).size <= 44)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return path;
+}
+/**
+ * The v1 {@link Pico8Adapter}: shells out to the user's native `pico8 -x`
+ * (ADR-0006, native path first). It owns the ORCHESTRATION the command should
+ * not hand-roll: launch, stream stdout, kill on the done-sentinel, arm the
+ * backstop, and collect screenshots + printh + exit reason into one result.
+ *
+ * PICO-8 absent (the first candidate ENOENTs and there is no fallback) returns
+ * the structured {@link pico8NotFound} value, never a throw or a hang. That
+ * absent path is the CI-testable one; live runs are a manual/opt-in tier.
+ */
+export class ShellPico8Adapter {
+    env;
+    spawnRun;
+    constructor(options) {
+        this.env = options.env;
+        this.spawnRun = options.spawn ?? spawnRunner;
+    }
+    run(options) {
+        const [file] = pico8Candidates(this.env);
+        const args = [
+            '-desktop',
+            options.shotDir,
+            '-x',
+            options.cartPath,
+            // One-shot scripted input (the cart reads it via stat(6)); omitted if absent.
+            ...(options.input !== undefined ? ['-p', options.input] : []),
+        ];
+        return this.orchestrate(file, args, options, (exitReason, printh) => ({
+            ok: true,
+            value: {
+                screenshots: collectScreenshots(options.shotDir),
+                printh,
+                exitReason,
+            },
+        }));
+    }
+    /**
+     * Records a running cart's audio to a WAV (ADR-0009). Launches PICO-8 in a
+     * REAL A/V session (`-run`, NOT the headless `-x` that mixes no audio) and
+     * controls the WAV location with `-root_path <wavDir>`, because
+     * `extcmd("audio_end", 1)` saves to PICO-8's CURRENT folder, not `-desktop`
+     * (the `audio_end(1)` trap). The cooperating cart (a harness for `record`, or
+     * the whole render harness) does the `audio_rec`/`audio_end`/sentinel dance; we
+     * watch the sentinel, arm the backstop, and collect `<basename>.wav` from the
+     * isolated `wavDir`. Live capture is a manual/opt-in tier; the absent path is
+     * the CI-testable one.
+     */
+    /**
+     * Drives a throwaway cart through scripted input and captures live gameplay
+     * (ADR-0011). Launches `-desktop <shotDir> -x <cart>` with a LIVE stdin, writes
+     * the whole encoded FIXED-SIZE command block stream up front (the one-shot; the
+     * cart drains one block per frame and screenshots at the SHOT points), watches
+     * the sentinel, arms the backstop, and collects the SHOT PNGs + printh + exit
+     * reason. Returns {@link pico8NotFound} when PICO-8 is absent. Live capture is a
+     * manual/opt-in tier; the absent path is the CI-testable one.
+     */
+    drive(options) {
+        const [file] = pico8Candidates(this.env);
+        const args = ['-desktop', options.shotDir, '-x', options.cartPath];
+        return this.orchestrate(file, args, { sentinel: options.sentinel, backstopMs: options.backstopMs }, (exitReason, printh) => ({
+            ok: true,
+            value: {
+                screenshots: collectScreenshots(options.shotDir),
+                printh,
+                exitReason,
+            },
+        }), { stdin: true, onSpawn: (proc) => proc.writeStdin?.(options.blocks) });
+    }
+    /**
+     * Exports the cart as a PICO-8 HTML bundle over the HEADLESS `-x` path (no
+     * display needed: `pico8 <cart> -export <outDir>/<name> -x` runs the cart, writes
+     * `<name>.html` + `<name>.js`, and exits). PICO-8 derives both file names from
+     * the `.html` name, so passing `index.html` yields a directly-serveable pair.
+     * A labelless cart prints "please capture a label first" and still exports (a
+     * blank splash), surfaced as `labelWarning`. PICO-8 absent -> {@link pico8NotFound}.
+     */
+    export(options) {
+        const [file] = pico8Candidates(this.env);
+        const htmlName = options.htmlName ?? EXPORT_HTML_NAME;
+        const outPath = join(options.outDir, htmlName);
+        // `-export <name>.html` is a load-and-export command; `-x` makes it headless
+        // (run the cart, perform the export, exit) so no window/display is needed.
+        const args = ['-export', outPath, '-x', options.cartPath];
+        return this.orchestrate(file, args, 
+        // The export has no cooperative done-sentinel; `-x` exits on its own when
+        // finished, and the backstop is the net for a cart that hangs at boot.
+        { backstopMs: options.backstopMs }, (_exitReason, printh) => {
+            const files = collectExportFiles(options.outDir);
+            const htmlPath = files.find((p) => p.endsWith('.html'));
+            const jsPath = files.find((p) => p.endsWith('.js'));
+            return {
+                ok: true,
+                value: {
+                    htmlPath,
+                    jsPath,
+                    files,
+                    // PICO-8 warns when the cart has no `__label__` to embed as the splash.
+                    labelWarning: /please capture a label first/i.test(printh),
+                },
+            };
+        });
+    }
+    record(options) {
+        const [file] = pico8Candidates(this.env);
+        const basename = options.wavBasename ?? RECORD_WAV_BASENAME;
+        // `-root_path <wavDir>` steers the `audio_end(1)`-to-current-folder WAV into
+        // the isolated temp dir (never ~/Desktop or the carts root). `-run` is a real
+        // A/V session (recording needs audio to capture; `-x` yields an empty WAV).
+        const args = ['-root_path', options.wavDir, '-run', options.cartPath];
+        return this.orchestrate(file, args, { sentinel: options.sentinel, backstopMs: options.backstopMs }, (exitReason, printh) => ({
+            ok: true,
+            value: {
+                wavPath: collectWav(options.wavDir, basename),
+                printh,
+                exitReason,
+            },
+        }));
+    }
+    /**
+     * The shared launch/sentinel-watch/backstop/collect loop behind both
+     * {@link run} and {@link record}. `buildOk` turns the exit reason + captured
+     * stdout into the command-specific success value; a spawn ENOENT with no
+     * fallback resolves the structured {@link pico8NotFound}. `printh` for `run` is
+     * filled by the caller from the run report path (kept out of `buildOk` there so
+     * the two report shapes stay distinct).
+     */
+    orchestrate(file, args, opts, buildOk, spawnOpts) {
+        const watcher = new SentinelWatcher(opts.sentinel);
+        return new Promise((resolve) => {
+            let settled = false;
+            let backstop;
+            const proc = this.spawnRun(file, withPico8Home(args), this.env, {
+                stdin: spawnOpts?.stdin,
+            });
+            const finish = (exitReason) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (backstop !== undefined)
+                    clearTimeout(backstop);
+                resolve(buildOk(exitReason, watcher.text));
+            };
+            proc.onError((err) => {
+                // A spawn ENOENT ⇒ PICO-8 is absent (a bad PICO8_PATH surfaces as absence
+                // with the same remedy, not a silent fall-through). Any other spawn error
+                // is a failed run, not a crash.
+                if (settled)
+                    return;
+                if (err.code === 'ENOENT') {
+                    settled = true;
+                    if (backstop !== undefined)
+                        clearTimeout(backstop);
+                    resolve(pico8NotFound());
+                }
+                else {
+                    finish('exit');
+                }
+            });
+            proc.onStdout((chunk) => {
+                if (watcher.push(chunk) && !settled) {
+                    proc.kill(); // sentinel matched: end the run promptly
+                    finish('sentinel');
+                }
+            });
+            proc.onClose(() => finish('exit')); // PICO-8 exited on its own
+            // For `drive`: write the command blocks to the live stdin now that it is
+            // spawned. A spawn ENOENT resolves via onError before this matters.
+            spawnOpts?.onSpawn?.(proc);
+            // Backstop: a cart that neither signals nor exits gets killed.
+            backstop = setTimeout(() => {
+                if (settled)
+                    return;
+                proc.kill();
+                finish('timeout');
+            }, opts.backstopMs);
+        });
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/engine/pico8/shell.js.map

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

package/dist/engine/pico8/supervisor.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The playtest SESSION SUPERVISOR (ADR-0011, prd US #6): the daemon that keeps a
+ * driven PICO-8 process ALIVE + PAUSED across the agent's separate CLI turns, and
+ * the client the per-verb sub-invocations use to address it BY ID.
+ *
+ * The problem this solves: `playtest step <id>` / `input <id>` / `shot <id>` are
+ * SEPARATE process invocations, but the driven PICO-8 must survive between them
+ * (staying alive + paused). A one-shot CLI process cannot hold another process's
+ * pipe, so `start` spawns a small DETACHED daemon that owns the live process + its
+ * stdin/stdout (via {@link DriveSession}) and listens on a per-session Unix domain
+ * socket; each later verb CONNECTS to that socket, sends its request, and gets the
+ * structured result back. The session is addressed by an id = the socket + a
+ * session dir under a controlled temp base (never `~/Desktop`, never the carts
+ * root).
+ *
+ * Lifecycle robustness (US #6 acceptance):
+ *  - ORPHAN reaping: the daemon self-reaps after an IDLE timeout (no verb within
+ *    the window), so a session whose agent never `stop`s it does not leak a live
+ *    PICO-8 forever. `stop <id>` tears it down promptly.
+ *  - PICO-8 dying mid-session surfaces as a STRUCTURED error (via
+ *    {@link SessionError}), not a hang; the next verb reports `process-dead`.
+ *  - `start` with PICO-8 ABSENT returns the same structured `pico8-not-found`
+ *    boundary as `run`/`audio render`.
+ *
+ * ONE session per id (the id IS the socket). Multiple concurrent sessions ARE
+ * allowed (distinct ids/dirs/daemons); the tool does not serialize them, an agent
+ * that wants isolation uses distinct ids (the default id is random, so parallel
+ * `start`s never collide).
+ *
+ * The pure, CI-testable pieces (the id/path registry, the request/response codec)
+ * live here alongside the IO daemon; the live daemon end-to-end is the
+ * manual/opt-in tier. The handshake core it drives ({@link DriveSession}) is
+ * separately unit-tested against a fake process.
+ */
+/** The controlled base dir all session dirs live under (never `~/Desktop`). */
+export declare const SESSION_BASE_DIRNAME: "picopilot-playtest-sessions";
+/**
+ * The default IDLE-reap window: a daemon with no verb for this long tears its
+ * session (and the live PICO-8) down, so an orphaned session (the agent walked
+ * away without `stop`) cannot leak a process indefinitely. Every verb resets it.
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
+/** The session verbs a client can send the daemon over the socket. */
+export type SessionVerb = 'input' | 'step' | 'shot' | 'stop' | 'status';
+/** A request sent from a verb sub-invocation to the session daemon. */
+export type SessionRequest = {
+    readonly verb: 'input';
+    readonly held: number;
+} | {
+    readonly verb: 'step';
+    readonly frames: number;
+} | {
+    readonly verb: 'shot';
+} | {
+    readonly verb: 'stop';
+} | {
+    readonly verb: 'status';
+};
+/** A structured daemon response: either an ok payload or a structured error. */
+export type SessionResponse = {
+    readonly ok: true;
+    readonly value: SessionResponseValue;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** The ok payload shape (a superset; each verb fills the relevant fields). */
+export interface SessionResponseValue {
+    /** The session id. */
+    readonly id: string;
+    /** Total frames advanced so far. */
+    readonly frame: number;
+    /** The ACK line the cart printed for this command (settled-frame proof). */
+    readonly ack?: string;
+    /** For `shot`: the absolute screenshot path the cart just wrote. */
+    readonly screenshot?: string;
+    /** For `shot`: the basename the cart named the capture. */
+    readonly shotName?: string;
+    /** Whether the session is still alive after this verb. */
+    readonly alive: boolean;
+}
+/**
+ * Encodes a request/response as a single newline-terminated JSON frame (the
+ * socket protocol). Newline-framed so a reader can split a stream into whole
+ * messages; kept pure so the codec is unit-tested without a socket.
+ */
+export declare function encodeFrame(msg: SessionRequest | SessionResponse): string;
+/**
+ * A stateful frame decoder mirroring {@link encodeFrame}: feed it raw socket
+ * chunks, it yields whole parsed messages (buffering partial lines). Typed loose
+ * (`T`) because a client decodes responses and the daemon decodes requests.
+ */
+export declare class FrameDecoder<T> {
+    private buffer;
+    push(chunk: string): T[];
+}
+/** A resolved session's on-disk layout (all under the controlled base). */
+export interface SessionPaths {
+    /** The session id (also the dir name under the base). */
+    readonly id: string;
+    /** The session dir: `<base>/<id>`. */
+    readonly dir: string;
+    /** The Unix domain socket the daemon listens on. */
+    readonly socket: string;
+    /** The `-desktop` dir PICO-8 writes SHOT screenshots into. */
+    readonly shotDir: string;
+    /** The pidfile written by the daemon (for reap/liveness checks). */
+    readonly pidfile: string;
+}
+/**
+ * The session REGISTRY: the pure id/path logic mapping a session id to its
+ * on-disk layout under a controlled base dir. No IO beyond the base-dir join, so
+ * the id validation + path derivation are unit-tested. The daemon and the client
+ * both resolve a session THROUGH this, so they agree on where the socket is.
+ */
+export declare class SessionRegistry {
+    readonly base: string;
+    constructor(base?: string);
+    /** A fresh random session id (short, filesystem-safe, collision-free enough). */
+    static freshId(): string;
+    /**
+     * Validates a caller-supplied id: filesystem-safe, no path traversal, so an id
+     * can never escape the controlled base. Returns the id or throws a plain Error
+     * (the command maps it to a structured refusal).
+     */
+    static validateId(id: string): string;
+    /** Resolves a session id to its {@link SessionPaths} under the base. */
+    resolve(id: string): SessionPaths;
+    /** Creates the session dir + shot dir (idempotent), returning the paths. */
+    create(id: string): SessionPaths;
+    /** The ids of all sessions with a dir present under the base (for listing/reap). */
+    list(): string[];
+    /** Removes a session's whole dir (the reap/cleanup, after the daemon exits). */
+    remove(id: string): void;
+}
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/engine/pico8/supervisor.d.ts.map

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

package/dist/engine/pico8/supervisor.js

@@ -0,0 +1,140 @@
+/**
+ * The playtest SESSION SUPERVISOR (ADR-0011, prd US #6): the daemon that keeps a
+ * driven PICO-8 process ALIVE + PAUSED across the agent's separate CLI turns, and
+ * the client the per-verb sub-invocations use to address it BY ID.
+ *
+ * The problem this solves: `playtest step <id>` / `input <id>` / `shot <id>` are
+ * SEPARATE process invocations, but the driven PICO-8 must survive between them
+ * (staying alive + paused). A one-shot CLI process cannot hold another process's
+ * pipe, so `start` spawns a small DETACHED daemon that owns the live process + its
+ * stdin/stdout (via {@link DriveSession}) and listens on a per-session Unix domain
+ * socket; each later verb CONNECTS to that socket, sends its request, and gets the
+ * structured result back. The session is addressed by an id = the socket + a
+ * session dir under a controlled temp base (never `~/Desktop`, never the carts
+ * root).
+ *
+ * Lifecycle robustness (US #6 acceptance):
+ *  - ORPHAN reaping: the daemon self-reaps after an IDLE timeout (no verb within
+ *    the window), so a session whose agent never `stop`s it does not leak a live
+ *    PICO-8 forever. `stop <id>` tears it down promptly.
+ *  - PICO-8 dying mid-session surfaces as a STRUCTURED error (via
+ *    {@link SessionError}), not a hang; the next verb reports `process-dead`.
+ *  - `start` with PICO-8 ABSENT returns the same structured `pico8-not-found`
+ *    boundary as `run`/`audio render`.
+ *
+ * ONE session per id (the id IS the socket). Multiple concurrent sessions ARE
+ * allowed (distinct ids/dirs/daemons); the tool does not serialize them, an agent
+ * that wants isolation uses distinct ids (the default id is random, so parallel
+ * `start`s never collide).
+ *
+ * The pure, CI-testable pieces (the id/path registry, the request/response codec)
+ * live here alongside the IO daemon; the live daemon end-to-end is the
+ * manual/opt-in tier. The handshake core it drives ({@link DriveSession}) is
+ * separately unit-tested against a fake process.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** The controlled base dir all session dirs live under (never `~/Desktop`). */
+export const SESSION_BASE_DIRNAME = 'picopilot-playtest-sessions';
+/**
+ * The default IDLE-reap window: a daemon with no verb for this long tears its
+ * session (and the live PICO-8) down, so an orphaned session (the agent walked
+ * away without `stop`) cannot leak a process indefinitely. Every verb resets it.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Encodes a request/response as a single newline-terminated JSON frame (the
+ * socket protocol). Newline-framed so a reader can split a stream into whole
+ * messages; kept pure so the codec is unit-tested without a socket.
+ */
+export function encodeFrame(msg) {
+    return `${JSON.stringify(msg)}\n`;
+}
+/**
+ * A stateful frame decoder mirroring {@link encodeFrame}: feed it raw socket
+ * chunks, it yields whole parsed messages (buffering partial lines). Typed loose
+ * (`T`) because a client decodes responses and the daemon decodes requests.
+ */
+export class FrameDecoder {
+    buffer = '';
+    push(chunk) {
+        this.buffer += chunk;
+        const out = [];
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, nl);
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line.trim().length > 0)
+                out.push(JSON.parse(line));
+        }
+        return out;
+    }
+}
+/**
+ * The session REGISTRY: the pure id/path logic mapping a session id to its
+ * on-disk layout under a controlled base dir. No IO beyond the base-dir join, so
+ * the id validation + path derivation are unit-tested. The daemon and the client
+ * both resolve a session THROUGH this, so they agree on where the socket is.
+ */
+export class SessionRegistry {
+    base;
+    constructor(base) {
+        this.base = base ?? join(tmpdir(), SESSION_BASE_DIRNAME);
+    }
+    /** A fresh random session id (short, filesystem-safe, collision-free enough). */
+    static freshId() {
+        return `s-${randomBytes(6).toString('hex')}`;
+    }
+    /**
+     * Validates a caller-supplied id: filesystem-safe, no path traversal, so an id
+     * can never escape the controlled base. Returns the id or throws a plain Error
+     * (the command maps it to a structured refusal).
+     */
+    static validateId(id) {
+        if (!/^[A-Za-z0-9._-]{1,64}$/.test(id) || id === '.' || id === '..') {
+            throw new Error(`invalid session id "${id}": use 1-64 chars of [A-Za-z0-9._-]`);
+        }
+        return id;
+    }
+    /** Resolves a session id to its {@link SessionPaths} under the base. */
+    resolve(id) {
+        SessionRegistry.validateId(id);
+        const dir = join(this.base, id);
+        return {
+            id,
+            dir,
+            socket: join(dir, 'sock'),
+            shotDir: join(dir, 'shots'),
+            pidfile: join(dir, 'pid'),
+        };
+    }
+    /** Creates the session dir + shot dir (idempotent), returning the paths. */
+    create(id) {
+        const paths = this.resolve(id);
+        mkdirSync(paths.shotDir, { recursive: true });
+        return paths;
+    }
+    /** The ids of all sessions with a dir present under the base (for listing/reap). */
+    list() {
+        if (!existsSync(this.base))
+            return [];
+        return readdirSync(this.base)
+            .filter((name) => {
+            try {
+                return statSync(join(this.base, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+            .sort();
+    }
+    /** Removes a session's whole dir (the reap/cleanup, after the daemon exits). */
+    remove(id) {
+        const { dir } = this.resolve(id);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/engine/pico8/supervisor.js.map

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

package/dist/engine/scaffold/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The static content `picopilot init` scaffolds: the `#include`-discipline
+ * `main.p8` (built through the cart model), the editable `main.lua`, the curated
+ * `AGENTS.md` PICO-8 reference, and the `picopilot.json` config. See
+ * `scaffold.ts` for the single scaffolding model and why these are the files.
+ */
+export { agentsMd, LUA_INCLUDE_LINE, mainLua, mainP8, picopilotJson, type ScaffoldFile, scaffoldFiles, } from './scaffold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/scaffold/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACN,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,MAAM,EACN,aAAa,EACb,KAAK,YAAY,EACjB,aAAa,GACb,MAAM,eAAe,CAAC"}

package/dist/engine/scaffold/index.js

@@ -0,0 +1,8 @@
+/**
+ * The static content `picopilot init` scaffolds: the `#include`-discipline
+ * `main.p8` (built through the cart model), the editable `main.lua`, the curated
+ * `AGENTS.md` PICO-8 reference, and the `picopilot.json` config. See
+ * `scaffold.ts` for the single scaffolding model and why these are the files.
+ */
+export { agentsMd, LUA_INCLUDE_LINE, mainLua, mainP8, picopilotJson, scaffoldFiles, } from './scaffold.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/scaffold/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACN,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,MAAM,EACN,aAAa,EAEb,aAAa,GACb,MAAM,eAAe,CAAC"}