picopilot 0.0.0 → 0.1.0

package/dist/engine/pico8/session-daemon-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-daemon-entry.js","sourceRoot":"","sources":["../../../src/engine/pico8/session-daemon-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAEpD,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/engine/pico8/session-daemon-main.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The playtest session DAEMON ENTRYPOINT (ADR-0011, prd US #6): the small
+ * detached process `playtest start` spawns to OWN a live driven PICO-8 for a
+ * session's lifetime. It is invoked via the hidden `playtest __daemon` verb (so it
+ * re-uses the exact same executable/loader the parent ran under, dev `tsx` or
+ * built `dist`), reads its config from JSON on argv, spawns PICO-8 on the
+ * throwaway driven cart with a LIVE stdin, and hands the process to
+ * {@link serveSession} to answer verbs over the session socket.
+ *
+ * PICO-8 ABSENT: the spawn ENOENTs, so the daemon writes a `pico8-not-found`
+ * marker file into the session dir and exits; the `start` client polls for either
+ * the socket (ready) or that marker (absent) and maps the marker to the same
+ * structured `pico8-not-found` boundary as `run`/`audio render`. This keeps the
+ * absent path structured WITHOUT the parent ever launching PICO-8 itself (the
+ * `pico8 --help` footgun is never touched).
+ */
+import type { SessionPaths } from './supervisor.js';
+/** The marker file the daemon writes into the session dir when PICO-8 is absent. */
+export declare const PICO8_NOT_FOUND_MARKER: "pico8-not-found";
+/** The daemon's launch config, passed as a single JSON argument. */
+export interface DaemonConfig {
+    readonly id: string;
+    readonly paths: SessionPaths;
+    /** Absolute path to the throwaway driven cart to run live. */
+    readonly cartPath: string;
+    /** The screenshot basename the driven cart names each SHOT. */
+    readonly shotBasename: string;
+    /** Idle-reap window in ms. */
+    readonly idleTimeoutMs: number;
+    /** Per-command ACK deadline in ms. */
+    readonly ackTimeoutMs: number;
+}
+/**
+ * Runs the daemon from its JSON config: spawns PICO-8 live on the driven cart and
+ * serves the session, or writes the pico8-not-found marker and exits on ENOENT.
+ * Exported so a test can drive it with an injected spawner (no real binary).
+ */
+export declare function runDaemon(config: DaemonConfig, env?: NodeJS.ProcessEnv, spawn?: import("./shell.js").SpawnRunner): void;
+/**
+ * The daemon process main: reads the JSON config from `argv[0]` and runs. Called
+ * by the hidden `playtest __daemon <configJson>` verb in a detached child.
+ */
+export declare function daemonMain(argv: readonly string[]): void;
+//# sourceMappingURL=session-daemon-main.d.ts.map

package/dist/engine/pico8/session-daemon-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-daemon-main.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/session-daemon-main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAElD,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAG,iBAA0B,CAAC;AAEjE,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,MAAM,EAAE,YAAY,EACpB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,KAAK,mCAAc,GACjB,IAAI,CAiCN;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAQxD"}

package/dist/engine/pico8/session-daemon-main.js

@@ -0,0 +1,71 @@
+/**
+ * The playtest session DAEMON ENTRYPOINT (ADR-0011, prd US #6): the small
+ * detached process `playtest start` spawns to OWN a live driven PICO-8 for a
+ * session's lifetime. It is invoked via the hidden `playtest __daemon` verb (so it
+ * re-uses the exact same executable/loader the parent ran under, dev `tsx` or
+ * built `dist`), reads its config from JSON on argv, spawns PICO-8 on the
+ * throwaway driven cart with a LIVE stdin, and hands the process to
+ * {@link serveSession} to answer verbs over the session socket.
+ *
+ * PICO-8 ABSENT: the spawn ENOENTs, so the daemon writes a `pico8-not-found`
+ * marker file into the session dir and exits; the `start` client polls for either
+ * the socket (ready) or that marker (absent) and maps the marker to the same
+ * structured `pico8-not-found` boundary as `run`/`audio render`. This keeps the
+ * absent path structured WITHOUT the parent ever launching PICO-8 itself (the
+ * `pico8 --help` footgun is never touched).
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pico8NotFound } from './adapter.js';
+import { serveSession } from './session-daemon.js';
+import { spawnRunner, pico8Candidates, withPico8Home } from './shell.js';
+/** The marker file the daemon writes into the session dir when PICO-8 is absent. */
+export const PICO8_NOT_FOUND_MARKER = 'pico8-not-found';
+/**
+ * Runs the daemon from its JSON config: spawns PICO-8 live on the driven cart and
+ * serves the session, or writes the pico8-not-found marker and exits on ENOENT.
+ * Exported so a test can drive it with an injected spawner (no real binary).
+ */
+export function runDaemon(config, env = process.env, spawn = spawnRunner) {
+    const [file] = pico8Candidates(env);
+    // Live session: `-desktop <shotDir>` for SHOT captures, `-x` headless, stdin
+    // piped so the daemon can send fixed-size command blocks per verb.
+    const args = ['-desktop', config.paths.shotDir, '-x', config.cartPath];
+    // `-home <isolated>` so PICO-8's config/data tree lands in a throwaway dir, not
+    // the caller's CWD (matches the shell adapter's spawn sites).
+    const proc = spawn(file, withPico8Home(args), env, { stdin: true });
+    // A spawn ENOENT means PICO-8 is absent (a bad PICO8_PATH surfaces the same
+    // way): leave the structured marker the `start` client polls for, then exit.
+    // This can only happen at spawn time (a launched binary does not ENOENT later),
+    // so it is unambiguously the absent boundary, not a mid-session fault.
+    proc.onError((err) => {
+        if (err.code === 'ENOENT') {
+            writeFileSync(join(config.paths.dir, PICO8_NOT_FOUND_MARKER), JSON.stringify(pico8NotFound()));
+            process.exit(0);
+        }
+        process.exit(1);
+    });
+    serveSession({
+        id: config.id,
+        paths: config.paths,
+        process: proc,
+        shotBasename: config.shotBasename,
+        idleTimeoutMs: config.idleTimeoutMs,
+        ackTimeoutMs: config.ackTimeoutMs,
+        onExit: () => process.exit(0),
+    });
+}
+/**
+ * The daemon process main: reads the JSON config from `argv[0]` and runs. Called
+ * by the hidden `playtest __daemon <configJson>` verb in a detached child.
+ */
+export function daemonMain(argv) {
+    const raw = argv[0];
+    if (raw === undefined) {
+        process.stderr.write('playtest daemon: missing config\n');
+        process.exit(2);
+    }
+    const config = JSON.parse(raw);
+    runDaemon(config);
+}
+//# sourceMappingURL=session-daemon-main.js.map

package/dist/engine/pico8/session-daemon-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-daemon-main.js","sourceRoot":"","sources":["../../../src/engine/pico8/session-daemon-main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,aAAa,EAAC,MAAM,SAAS,CAAC;AACtC,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAC,WAAW,EAAE,eAAe,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAGvE,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAA0B,CAAC;AAgBjE;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACxB,MAAoB,EACpB,MAAyB,OAAO,CAAC,GAAG,EACpC,KAAK,GAAG,WAAW;IAEnB,MAAM,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,GAAG,CAA0B,CAAC;IAC7D,6EAA6E;IAC7E,mEAAmE;IACnE,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvE,gFAAgF;IAChF,8DAA8D;IAC9D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC;IAElE,4EAA4E;IAC5E,6EAA6E;IAC7E,gFAAgF;IAChF,uEAAuE;IACvE,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACpB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,aAAa,CACZ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,sBAAsB,CAAC,EAC9C,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC,CAC/B,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,YAAY,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;KAC7B,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IAC/C,SAAS,CAAC,MAAM,CAAC,CAAC;AACnB,CAAC"}

package/dist/engine/pico8/session-daemon.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The playtest session DAEMON runtime + CLIENT (ADR-0011, prd US #6). This is the
+ * IO half of the supervisor: the daemon LISTENS on a session's Unix domain socket
+ * and drives a live {@link DriveSession} on behalf of each verb sub-invocation;
+ * the {@link SessionClient} CONNECTS to that socket to send a verb and read back
+ * the structured response.
+ *
+ * The daemon owns the live process the whole session, so the game stays ALIVE +
+ * PAUSED between the agent's turns. It self-reaps on an IDLE timeout (the orphan
+ * path) and on `stop`. The live daemon end-to-end is the manual/opt-in tier; the
+ * pure pieces it composes (the handshake {@link DriveSession}, the registry, the
+ * frame codec) are unit-tested without a real socket or binary.
+ */
+import type { Pico8Process } from './shell.js';
+import { type SessionPaths, type SessionRequest, type SessionResponse } from './supervisor.js';
+/**
+ * A client for a running session daemon: connects to its socket, sends ONE verb
+ * request, awaits the single response, and closes. Each `playtest step/input/shot
+ * /stop` sub-invocation makes exactly one of these round-trips.
+ */
+export declare class SessionClient {
+    private readonly socketPath;
+    constructor(socketPath: string);
+    /**
+     * Sends `request` to the daemon and resolves its {@link SessionResponse}. A
+     * connection failure (no daemon / dead socket) rejects with a plain Error the
+     * command maps to `playtest-session-not-found`.
+     */
+    send(request: SessionRequest): Promise<SessionResponse>;
+}
+/** Whether a session daemon is reachable (its socket exists). */
+export declare function sessionExists(paths: SessionPaths): boolean;
+/**
+ * Spawns the session DAEMON as a DETACHED background process that outlives this
+ * (the `start`) invocation, so the driven PICO-8 stays alive across the agent's
+ * separate verb turns. It re-invokes the current executable + `execArgv` (so the
+ * daemon runs under the SAME loader, dev `tsx` or built node) on the daemon entry
+ * file, passing the config as a single JSON arg. `unref` + `detached` cut it free
+ * from this process's lifetime; its stdio is ignored (the daemon talks over the
+ * session socket, not this process's pipes).
+ */
+export declare function spawnSessionDaemon(config: import('./session-daemon-main.js').DaemonConfig): void;
+/** Options for {@link serveSession}. */
+export interface ServeSessionOptions {
+    readonly id: string;
+    readonly paths: SessionPaths;
+    /** The live driven process to own for this session (spawned by the caller). */
+    readonly process: Pico8Process;
+    /** The screenshot basename the driven cart names each SHOT (matches transform). */
+    readonly shotBasename: string;
+    /** Idle-reap window (defaults to {@link DEFAULT_IDLE_TIMEOUT_MS}). */
+    readonly idleTimeoutMs?: number;
+    /** Per-command ACK deadline forwarded to {@link DriveSession}. */
+    readonly ackTimeoutMs?: number;
+    /** Called when the daemon has fully torn down (for the process to exit). */
+    readonly onExit?: () => void;
+}
+/**
+ * Runs the session daemon: wraps the live process in a {@link DriveSession},
+ * listens on the session socket, and dispatches each incoming verb request to the
+ * handshake (send-command -> wait-ack -> respond). Resets an IDLE-reap timer on
+ * every verb, so an orphaned session tears down on its own. Returns the net
+ * server so the caller (the daemon entrypoint) can await its lifetime.
+ */
+export declare function serveSession(options: ServeSessionOptions): {
+    close: () => void;
+};
+//# sourceMappingURL=session-daemon.d.ts.map

package/dist/engine/pico8/session-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-daemon.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/session-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7C,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,MAAM,iBAAiB,CAAC;AAEzB;;;;GAIG;AACH,qBAAa,aAAa;IACb,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,MAAM;IAE/C;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CA6BvD;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE1D;AAWD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,OAAO,0BAA0B,EAAE,YAAY,GACrD,IAAI,CAON;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAC3D,KAAK,EAAE,MAAM,IAAI,CAAC;CAClB,CA0IA"}

package/dist/engine/pico8/session-daemon.js

@@ -0,0 +1,264 @@
+/**
+ * The playtest session DAEMON runtime + CLIENT (ADR-0011, prd US #6). This is the
+ * IO half of the supervisor: the daemon LISTENS on a session's Unix domain socket
+ * and drives a live {@link DriveSession} on behalf of each verb sub-invocation;
+ * the {@link SessionClient} CONNECTS to that socket to send a verb and read back
+ * the structured response.
+ *
+ * The daemon owns the live process the whole session, so the game stays ALIVE +
+ * PAUSED between the agent's turns. It self-reaps on an IDLE timeout (the orphan
+ * path) and on `stop`. The live daemon end-to-end is the manual/opt-in tier; the
+ * pure pieces it composes (the handshake {@link DriveSession}, the registry, the
+ * frame codec) are unit-tested without a real socket or binary.
+ */
+import { spawn } from 'node:child_process';
+import { createConnection, createServer } from 'node:net';
+import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DriveSession, SessionError, } from './session.js';
+import { DEFAULT_IDLE_TIMEOUT_MS, encodeFrame, FrameDecoder, } from './supervisor.js';
+/**
+ * A client for a running session daemon: connects to its socket, sends ONE verb
+ * request, awaits the single response, and closes. Each `playtest step/input/shot
+ * /stop` sub-invocation makes exactly one of these round-trips.
+ */
+export class SessionClient {
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    /**
+     * Sends `request` to the daemon and resolves its {@link SessionResponse}. A
+     * connection failure (no daemon / dead socket) rejects with a plain Error the
+     * command maps to `playtest-session-not-found`.
+     */
+    send(request) {
+        return new Promise((resolve, reject) => {
+            const decoder = new FrameDecoder();
+            let settled = false;
+            const sock = createConnection(this.socketPath);
+            sock.setEncoding('utf8');
+            sock.on('connect', () => sock.write(encodeFrame(request)));
+            sock.on('data', (chunk) => {
+                const [msg] = decoder.push(chunk);
+                if (msg !== undefined && !settled) {
+                    settled = true;
+                    resolve(msg);
+                    sock.end();
+                }
+            });
+            sock.on('error', (err) => {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            });
+            sock.on('close', () => {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error('daemon closed the connection with no response'));
+                }
+            });
+        });
+    }
+}
+/** Whether a session daemon is reachable (its socket exists). */
+export function sessionExists(paths) {
+    return existsSync(paths.socket);
+}
+/** Resolves the sibling daemon-entry module (`.ts` in dev, `.js` when built). */
+function daemonEntryPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // This module and the entry are compiled/loaded together, so the extension
+    // here (`.ts` under tsx, `.js` under dist) is the entry's extension too.
+    const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+    return join(here, `session-daemon-entry${ext}`);
+}
+/**
+ * Spawns the session DAEMON as a DETACHED background process that outlives this
+ * (the `start`) invocation, so the driven PICO-8 stays alive across the agent's
+ * separate verb turns. It re-invokes the current executable + `execArgv` (so the
+ * daemon runs under the SAME loader, dev `tsx` or built node) on the daemon entry
+ * file, passing the config as a single JSON arg. `unref` + `detached` cut it free
+ * from this process's lifetime; its stdio is ignored (the daemon talks over the
+ * session socket, not this process's pipes).
+ */
+export function spawnSessionDaemon(config) {
+    const child = spawn(process.execPath, [...process.execArgv, daemonEntryPath(), JSON.stringify(config)], { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+/**
+ * Runs the session daemon: wraps the live process in a {@link DriveSession},
+ * listens on the session socket, and dispatches each incoming verb request to the
+ * handshake (send-command -> wait-ack -> respond). Resets an IDLE-reap timer on
+ * every verb, so an orphaned session tears down on its own. Returns the net
+ * server so the caller (the daemon entrypoint) can await its lifetime.
+ */
+export function serveSession(options) {
+    const session = new DriveSession({
+        process: options.process,
+        shotBasename: options.shotBasename,
+        ackTimeoutMs: options.ackTimeoutMs,
+    });
+    const idleMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    let idleTimer;
+    let tornDown = false;
+    const teardown = () => {
+        if (tornDown)
+            return;
+        tornDown = true;
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        try {
+            session.stop();
+        }
+        catch {
+            // best-effort; the process kill below is the real backstop
+        }
+        try {
+            server.close();
+        }
+        catch {
+            // ignore
+        }
+        // Reap the WHOLE session dir (socket + pidfile + driven cart + shots), so an
+        // idle/orphan teardown leaves nothing behind, not just the socket. (The CLI
+        // `stop` also sweeps the dir; doing it here covers the no-`stop` orphan path.)
+        try {
+            rmSync(options.paths.dir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        options.onExit?.();
+    };
+    const armIdle = () => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(teardown, idleMs);
+        idleTimer.unref?.();
+    };
+    const handle = async (req) => {
+        armIdle();
+        try {
+            switch (req.verb) {
+                case 'input': {
+                    const r = await session.input(req.held);
+                    return ok(options.id, { frame: r.frame, ack: r.ack, alive: true });
+                }
+                case 'step': {
+                    // A frames span may exceed one byte; the daemon issues it as repeated
+                    // single-byte steps, each awaiting its own STEP-DONE ack, so the total
+                    // is exact and lossless regardless of size.
+                    let last = { frame: session.frame, ack: '' };
+                    let remaining = Math.max(0, Math.floor(req.frames));
+                    while (remaining > 0) {
+                        const chunk = Math.min(remaining, 0xff);
+                        last = await session.step(chunk);
+                        remaining -= chunk;
+                    }
+                    return ok(options.id, {
+                        frame: last.frame,
+                        ack: last.ack,
+                        alive: true,
+                    });
+                }
+                case 'shot': {
+                    const r = await session.shot();
+                    const screenshot = collectShot(options.paths.shotDir, r.shotName);
+                    return ok(options.id, {
+                        frame: r.frame,
+                        ack: r.ack,
+                        shotName: r.shotName,
+                        screenshot,
+                        alive: true,
+                    });
+                }
+                case 'status': {
+                    return ok(options.id, {
+                        frame: session.frame,
+                        alive: !session.isDead,
+                    });
+                }
+                case 'stop': {
+                    // The connection handler tears the daemon down AFTER this response has
+                    // flushed to the client (so `stop` returns cleanly, no close-race).
+                    return ok(options.id, { frame: session.frame, alive: false });
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof SessionError) {
+                return { ok: false, code: e.code, message: e.message };
+            }
+            return {
+                ok: false,
+                code: 'playtest-session-error',
+                message: e instanceof Error ? e.message : String(e),
+            };
+        }
+    };
+    const server = createServer((sock) => {
+        sock.setEncoding('utf8');
+        const decoder = new FrameDecoder();
+        sock.on('data', (chunk) => {
+            for (const req of decoder.push(chunk)) {
+                const isStop = req.verb === 'stop';
+                void handle(req).then((res) => {
+                    try {
+                        // Flush the response, THEN (for `stop`) end the socket and tear the
+                        // daemon down, so the client always reads the stop reply first.
+                        sock.write(encodeFrame(res), () => {
+                            if (isStop) {
+                                sock.end();
+                                teardown();
+                            }
+                        });
+                    }
+                    catch {
+                        if (isStop)
+                            teardown();
+                    }
+                });
+            }
+        });
+        sock.on('error', () => {
+            /* a dropped client is not fatal to the daemon */
+        });
+    });
+    // If the driven process dies, the next verb reports it (process-dead); we do
+    // NOT auto-teardown here, so the agent can still `stop`/`status` and get the
+    // structured error rather than a vanished socket.
+    server.listen(options.paths.socket, () => {
+        writeFileSync(options.paths.pidfile, String(process.pid));
+        armIdle();
+    });
+    return { close: teardown };
+}
+/** Builds an ok {@link SessionResponse} from a partial value + the id. */
+function ok(id, partial) {
+    return { ok: true, value: { id, ...partial } };
+}
+/**
+ * Resolves the absolute path of the screenshot a SHOT just produced in the
+ * `-desktop` dir. The cart named it `<shotName>` (basename) and PICO-8 appends
+ * `.png`; if the exact file is not yet visible (a filesystem race) it falls back
+ * to the most-recent PNG, so the caller still gets a path to read.
+ */
+function collectShot(shotDir, shotName) {
+    const exact = join(shotDir, `${shotName}.png`);
+    if (existsSync(exact))
+        return exact;
+    try {
+        const pngs = readdirSync(shotDir)
+            .filter((f) => f.toLowerCase().endsWith('.png'))
+            .sort();
+        const last = pngs.at(-1);
+        return last !== undefined ? join(shotDir, last) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-daemon.js.map

package/dist/engine/pico8/session-daemon.js.map

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

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

@@ -0,0 +1,140 @@
+/**
+ * The RESUMABLE playtest SESSION handshake core (ADR-0011, prd US #6): the pure,
+ * CI-testable half of the "A" live model. It keeps a single driven PICO-8 process
+ * ALIVE and PAUSED between the agent's turns and drives it one command at a time
+ * over the verified transport: write a FIXED-SIZE command block, WAIT for the
+ * cart's ACK line on stdout, then return. The handshake (not wall-clock spacing)
+ * is what makes stepping deterministic and lossless, so the agent always acts on
+ * a SETTLED, known frame.
+ *
+ * This module owns ONLY the send -> wait-ack -> return logic against the
+ * {@link Pico8Process} seam (the same seam the one-shot `drive` uses), so every
+ * path (a completed step, a lost/late ack, the process dying mid-command) is
+ * unit-tested against a FAKE process WITHOUT the paid binary. The daemon that
+ * spawns the real process and exposes the session to separate CLI invocations by
+ * id lives in `supervisor.ts`; a live multi-turn session is the manual/opt-in
+ * tier. The cart-side transform is reused UNCHANGED from `drive.ts`.
+ */
+import type { Pico8Process } from './shell.js';
+/**
+ * A structured reason a session command could not complete (a boundary, not a
+ * crash). Surfaced by the supervisor/command as incur's `error({code,...})`.
+ */
+export type SessionErrorCode = 
+/** No ACK arrived within the deadline (the lost/late-ack path). */
+'playtest-session-ack-timeout'
+/** PICO-8 exited (crashed/quit) while a command was in flight or between them. */
+ | 'playtest-session-process-dead'
+/** A command was issued after the session was already stopped/closed. */
+ | 'playtest-session-closed';
+/** A structured session-command failure (never a raw throw across the seam). */
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    constructor(code: SessionErrorCode, message: string);
+}
+/**
+ * How long a single command waits for its ACK before it is declared lost (the
+ * lost/late-ack path). Generous: a STEP of many frames takes real time at 30fps,
+ * plus PICO-8 scheduling jitter, but a hung/dead cart must not wall the session
+ * forever. The supervisor's process-death signal (see {@link DriveSession}) ends
+ * a command EARLY when the process dies, so this only fires for a truly stuck
+ * cart.
+ */
+export declare const DEFAULT_ACK_TIMEOUT_MS = 15000;
+/** The result of one completed session command (the structured per-verb envelope). */
+export interface StepResult {
+    /** The total frames advanced across the session's lifetime so far. */
+    readonly frame: number;
+    /** The ACK line the cart printed for this command (the settled-frame proof). */
+    readonly ack: string;
+}
+/** The result of a `shot` command: the frame + the basename the cart named it. */
+export interface ShotResult extends StepResult {
+    /** The screenshot basename the cart queued (`<basename><n>`), for collection. */
+    readonly shotName: string;
+}
+/** Options for a {@link DriveSession}. */
+export interface DriveSessionOptions {
+    /** The already-spawned live driven process (owned by the caller/supervisor). */
+    readonly process: Pico8Process;
+    /** Per-command ACK deadline (defaults to {@link DEFAULT_ACK_TIMEOUT_MS}). */
+    readonly ackTimeoutMs?: number;
+    /**
+     * The screenshot basename the driven cart's SHOT names each capture (matches
+     * the transform's `shotBasename`); the session reports `<basename><n>`.
+     */
+    readonly shotBasename: string;
+}
+/**
+ * The live-session handshake engine (ADR-0011, US #6). Wraps ONE driven
+ * {@link Pico8Process} and exposes the agent's verbs: {@link input} (set the
+ * held-buttons byte), {@link step} (advance exactly N frames), {@link shot}
+ * (capture the frozen current frame), {@link stop} (tear the session down). Each
+ * verb WRITES a single fixed-size command block and AWAITS the cart's ACK before
+ * resolving, so the process stays alive + paused between verbs and the caller
+ * always acts on a settled frame. Between the ACK and the next verb the game is
+ * frozen (its callbacks skipped, a stable framebuffer), so a {@link shot} always
+ * captures exactly the intended moment.
+ *
+ * The engine is transport-agnostic: it talks to the {@link Pico8Process} seam,
+ * so the send/wait/return + lost-ack + process-death paths are unit-tested
+ * against a FAKE process with no real binary. The supervisor supplies a REAL
+ * spawned process for a live session (the manual/opt-in tier).
+ */
+export declare class DriveSession {
+    private readonly proc;
+    private readonly reader;
+    private readonly ackTimeoutMs;
+    private readonly shotBasename;
+    private frames;
+    private shotIndex;
+    /** Set once the process dies; every in-flight + future command rejects. */
+    private dead;
+    private closed;
+    private readonly deathWaiters;
+    constructor(options: DriveSessionOptions);
+    /** Total frames the session has advanced so far. */
+    get frame(): number;
+    /** Whether the underlying process has died (crashed/quit). */
+    get isDead(): boolean;
+    private markDead;
+    /**
+     * Sets the per-frame HELD-buttons byte for the upcoming steps (US #6: inject
+     * input between turns). Writes an INPUT block and awaits its ACK. The held
+     * level persists until the next INPUT (the cart holds it), and `btnp` edges
+     * are reconstructed cart-side from the held sequence.
+     */
+    input(held: number): Promise<StepResult>;
+    /**
+     * Advances EXACTLY `frames` frames then pauses (US #6, US #4). Writes a STEP
+     * block and awaits the STEP-DONE ack, which the cart prints only when the
+     * frame budget reaches 0, so the returned result means the N frames ACTUALLY
+     * ran and the game is now paused on a settled frame. `frames` must fit one
+     * byte (the block's arg); larger spans are issued as repeated steps by the
+     * caller.
+     */
+    step(frames: number): Promise<StepResult>;
+    /**
+     * Captures the current (paused, frozen) frame (US #6, US #5). Writes a SHOT
+     * block and awaits its ACK; the cart renders the frozen state once then
+     * screenshots it, so the capture is exactly the intended moment. Returns the
+     * `<basename><n>` the cart named it, which the supervisor collects from the
+     * `-desktop` dir.
+     */
+    shot(): Promise<ShotResult>;
+    /**
+     * Tears the session down: writes a QUIT block (the cart prints the sentinel so
+     * the launcher kills PICO-8), then kills the process as the backstop. Does NOT
+     * await an ACK (QUIT ends the cart), and is idempotent + safe on a dead
+     * process. After `stop`, every verb rejects with `playtest-session-closed`.
+     */
+    stop(): void;
+    /**
+     * The core handshake: write one command block, then race the ACK line against
+     * the timeout and the process-death signal. A missing ACK within the deadline
+     * is the structured lost/late-ack error; a process that dies mid-command is the
+     * structured process-dead error. Never a hang, never a silent success.
+     */
+    private send;
+}
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,gBAAgB;AAC3B,mEAAmE;AACjE,8BAA8B;AAChC,kFAAkF;GAChF,+BAA+B;AACjC,yEAAyE;GACvE,yBAAyB,CAAC;AAE7B,gFAAgF;AAChF,qBAAa,YAAa,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;gBACpB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM;CAKnD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,sFAAsF;AACtF,MAAM,WAAW,UAAU;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC7C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AA6DD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IACnC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAK;IACtB,2EAA2E;IAC3E,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;gBAEvC,OAAO,EAAE,mBAAmB;IASxC,oDAAoD;IACpD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8DAA8D;IAC9D,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,OAAO,CAAC,QAAQ;IAMhB;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAK9C;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAO/C;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAOjC;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAaZ;;;;;OAKG;YACW,IAAI;CA+DlB"}