@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/__tests__/daemon-liveness.test.js

@@ -4,9 +4,10 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { createNode, getNode } from '../canvas/canvas.js';
+import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { appendInbox } from '../feed/inbox.js';
+import { markBusy, clearBusy } from '../runtime/busy.js';
 import { superviseTick, isPidAlive, livenessVerdict, } from '../../daemon/crtrd.js';
 let home;
 function node(id, over = {}) {
@@ -149,8 +150,9 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
         spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
         // The window is alive, but the node is anchored on that dead pane. Under the
         // old window-keyed liveness this node would read healthy (window alive + live
-        // pid). Pane-keyed: the pane is gone → the crash branch fires. pi_session_id
-        // is set so it's a clean crash, not a boot-failure push.
+        // pid). Pane-keyed: the pane is gone → the gone-branch fires. The node is
+        // MID-GENERATION (busy marker present — agent_start touched it, agent_end
+        // never cleared it), so the gone-branch routes to crash → 'dead'.
         createNode(node('G', {
             pane: dead,
             tmux_session: session,
@@ -159,8 +161,61 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
             pi_session_id: 'booted',
             intent: null,
         }));
+        markBusy('G'); // pane killed inside a turn → genuine mid-run crash
         await superviseTick();
-        assert.equal(getNode('G').status, 'dead', 'a gone pane fires the gone-branch even with a live window + pid');
+        assert.equal(getNode('G').status, 'dead', 'a gone pane mid-generation fires the gone-branch → crash (dead)');
+        clearBusy('G');
+    });
+});
+// ---------------------------------------------------------------------------
+// Gone-pane routing: a pane-gone node in the crash branch is no longer an
+// unconditional 'dead'. It routes on what the node was DOING at pane-kill time:
+//   • mid-generation (busy marker PRESENT)               → crash  ('dead')
+//   • finished its turn, awaiting nothing live           → finalize ('done')
+//   • finished its turn, still awaiting a LIVE child     → crash  ('dead'), for now
+// (The mid-generation → dead leg is covered by node 'G' above.)
+// ---------------------------------------------------------------------------
+test('pane gone + booted + busy ABSENT + no live subscription → finalize (done): the pane was closed to dismiss a finished node', { skip: !hasTmux() }, async () => {
+    await withLivePane('fin1', async (session, window) => {
+        const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
+        const dead = (sp.stdout ?? '').trim();
+        spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
+        // Booted (pi_session_id set), no busy marker (agent_end cleared it → the turn
+        // finished), and no subscription to any live node. Closing the pane was a
+        // dismissal of a node that already did its own work → finalize to 'done'.
+        createNode(node('FIN', {
+            pane: dead,
+            tmux_session: session,
+            window,
+            pi_pid: process.pid,
+            pi_session_id: 'booted',
+            intent: null,
+        }));
+        // no markBusy: the turn ended cleanly.
+        await superviseTick();
+        assert.equal(getNode('FIN').status, 'done', 'a finished, unsubscribed node whose pane was closed finalizes to done');
+    });
+});
+test('pane gone + booted + busy ABSENT but AWAITING a LIVE child → crash (dead), for now', { skip: !hasTmux() }, async () => {
+    await withLivePane('fin2', async (session, window) => {
+        const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
+        const dead = (sp.stdout ?? '').trim();
+        spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
+        // A live child the parent is subscribed to: hasActiveLiveSubscription === true.
+        createNode(node('CHILD', { status: 'active', pi_session_id: 'booted' }));
+        createNode(node('PARENT', {
+            pane: dead,
+            tmux_session: session,
+            window,
+            pi_pid: process.pid,
+            pi_session_id: 'booted',
+            intent: null,
+        }));
+        subscribe('PARENT', 'CHILD', true); // active subscription to a LIVE node
+        // Parent finished its turn (no busy marker) but is still awaiting a live
+        // child → NOT a finalize. Routes to crash ('dead') for now.
+        await superviseTick();
+        assert.equal(getNode('PARENT').status, 'dead', 'a finished node still awaiting a live child crashes (dead), not finalizes');
     });
 });
 // ---------------------------------------------------------------------------

package/dist/core/__tests__/dead-pane-regression.test.js

@@ -0,0 +1,151 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/dead-pane-regression.test.ts
+//
+// PLACEMENT-FAMILY DEAD-PANE REGRESSION GUARD.
+//
+// The bug (fixed this session, committed in HEAD `src/core/spawn.ts`): the
+// `human` command tree opens its humanloop TUI in a tmux pane via
+// `spawnAndDetach` (a `split-window` into the CURRENT window). The canvas
+// runtime arms `remain-on-exit on` at the WINDOW scope on a node's vehicle /
+// focus window (the F3 freeze, `runtime/tmux.ts` setRemainOnExit). A
+// `split-window` pane opened into such a window INHERITS the `on`, so when the
+// TUI worker (`crtr human _run`) exits 0 (clean), tmux keeps the pane around as
+// a dead "[Exited]" pane instead of destroying it — a lingering dead pane.
+//
+// The fix: after the split, `spawnAndDetach` forces `remain-on-exit off` at PANE
+// scope on the new pane (`set-option -p -t <pane> remain-on-exit off`). That
+// destroys the pane on a clean exit WITHOUT touching the window's value (so a
+// focus freeze still works) or the user's global config.
+//
+// This file drives the REAL production `spawnAndDetach` against a REAL but
+// isolated tmux session — no mocks. It is ADDITIVE: it adds no harness/fixture
+// capability and edits no production file. The canvas harness
+// (`helpers/harness.ts`) cannot reach this path — it drives canvas nodes via
+// `openNodeWindow` (new-window backstage), never the `spawnAndDetach`
+// split-window/human-pane path — so the tmux drivers below are LOCAL to this
+// file (candidates for harness consolidation: a `splitDetachPane` + pane-scoped
+// `paneAlive`/`paneIsDead`/`waitForPaneGone` keyed on a raw %pane id).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { hasTmux } from './helpers/harness.js';
+import { spawnAndDetach } from '../spawn.js';
+const SKIP = !hasTmux();
+// --- LOCAL tmux drivers (keyed on a raw %pane id, not a canvas node) --------
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+/** Every pane in the session (across windows) with its dead flag. */
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id} #{pane_dead}']);
+    if (r.code !== 0)
+        return [];
+    return r.out
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [id, dead] = l.split(' ');
+        return { id: id, dead: dead === '1' };
+    });
+}
+function paneAlive(session, pane) {
+    return sessionPanes(session).some((p) => p.id === pane && !p.dead);
+}
+function paneExists(session, pane) {
+    return sessionPanes(session).some((p) => p.id === pane);
+}
+function paneIsDead(session, pane) {
+    return sessionPanes(session).find((p) => p.id === pane)?.dead ?? false;
+}
+async function waitUntil(probe, label, timeoutMs = 15_000, intervalMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (probe())
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`waitUntil timed out: ${label}`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+test('dead-pane regression: spawnAndDetach into a remain-on-exit-ON window is DESTROYED on clean exit', { skip: SKIP ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
+    const session = `crtr-deadpane-${process.pid}-${Date.now().toString(36)}`;
+    const origTmux = process.env['TMUX'];
+    let tmuxOverridden = false;
+    try {
+        // --- isolated session on whatever server the current env targets -------
+        const created = tmux(['new-session', '-d', '-s', session, '-c', process.cwd(), 'sleep 100000']);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        const info = tmux([
+            'display-message', '-p', '-t', `${session}:`,
+            '#{pane_id}\t#{window_id}\t#{socket_path}',
+        ]);
+        assert.equal(info.code, 0, `display-message failed: ${info.err}`);
+        const [basePane, baseWindow, socketPath] = info.out.split('\t');
+        assert.ok(basePane && baseWindow && socketPath, `parsed session info: ${info.out}`);
+        // --- arm the BUG PRECONDITION: window default remain-on-exit ON --------
+        // (mirrors the canvas runtime's F3 freeze on a node's vehicle/focus window).
+        const armed = tmux(['set-window-option', '-t', baseWindow, 'remain-on-exit', 'on']);
+        assert.equal(armed.code, 0, `arm window remain-on-exit on failed: ${armed.err}`);
+        assert.equal(tmux(['show-window-options', '-t', baseWindow, 'remain-on-exit']).out, 'remain-on-exit on', 'precondition: the window into which we split has remain-on-exit ON');
+        // spawnAndDetach gates on isInTmux() (Boolean(process.env.TMUX)) and shells
+        // `tmux` with no -L, so point TMUX at THIS session's socket — both our
+        // helpers and spawnAndDetach then drive the same server holding `session`.
+        process.env['TMUX'] = `${socketPath},0,0`;
+        tmuxOverridden = true;
+        // ====================================================================
+        // MAIN — the REAL production spawnAndDetach split into the ON window.
+        // ====================================================================
+        const res = spawnAndDetach({
+            command: 'sleep 1', // a clean-exiting (status 0) worker — stands in for `crtr human _run`
+            cwd: process.cwd(),
+            placement: 'split-h',
+            killAfterSeconds: 0, // no self-kill of the originating pane
+            targetPane: basePane, // pin the split to our isolated window (never the user's pane)
+        });
+        assert.equal(res.status, 'spawned', `spawnAndDetach should spawn: ${res.message}`);
+        const pane = res.paneId;
+        assert.ok(pane && pane.startsWith('%'), `spawnAndDetach returned a %pane id: ${pane}`);
+        // (a) the pane landed alive in the remain-on-exit-ON window.
+        assert.equal(paneAlive(session, pane), true, 'spawned pane is alive right after the split');
+        // (b) THE FIX: the spawned pane carries a PANE-SCOPED remain-on-exit OFF
+        //     override — the exact line under regression
+        //     (`set-option -p -t <pane> remain-on-exit off`). If a refactor drops
+        //     it, this fails loudly.
+        assert.equal(tmux(['show-options', '-p', '-t', pane, 'remain-on-exit']).out, 'remain-on-exit off', 'FIX present: pane-scoped remain-on-exit OFF on the spawnAndDetach pane');
+        // (c) the override is pane-scoped only — the WINDOW value is untouched, so
+        //     a real focus-freeze on this window still works.
+        assert.equal(tmux(['show-window-options', '-t', baseWindow, 'remain-on-exit']).out, 'remain-on-exit on', 'window remain-on-exit untouched (override is pane-scoped, focus freeze intact)');
+        // (d) THE GUARANTEE: on the worker's CLEAN exit the pane is DESTROYED,
+        //     never lingering as a dead [Exited] pane.
+        await waitUntil(() => !paneExists(session, pane), 'spawnAndDetach pane destroyed on clean exit');
+        assert.equal(paneExists(session, pane), false, 'spawnAndDetach pane DESTROYED on clean exit (not lingering)');
+        // ====================================================================
+        // CONTROL — prove the guard is NON-VACUOUS: the SAME split WITHOUT the
+        // pane-scoped override (i.e. pre-fix behavior) lingers as a dead pane.
+        // ====================================================================
+        const ctl = tmux([
+            'split-window', '-h', '-d', '-P', '-F', '#{pane_id}',
+            '-t', basePane, '-c', process.cwd(), 'sleep 1',
+        ]);
+        assert.equal(ctl.code, 0, `control split failed: ${ctl.err}`);
+        const ctlPane = ctl.out;
+        assert.ok(ctlPane.startsWith('%'), `control pane id: ${ctlPane}`);
+        // No pane-scoped override → inherits the window's remain-on-exit ON →
+        // after its clean exit the pane is kept as DEAD rather than destroyed.
+        await waitUntil(() => paneIsDead(session, ctlPane), 'control pane reaches dead state after clean exit');
+        assert.equal(paneExists(session, ctlPane), true, 'CONTROL: un-fixed pane LINGERS (still listed) after clean exit');
+        assert.equal(paneIsDead(session, ctlPane), true, 'CONTROL: the lingering pane is DEAD — confirms remain-on-exit ON causes the exact bug the fix prevents');
+    }
+    finally {
+        // Tear down on the SAME server the session lives on (TMUX still points there),
+        // then restore the original TMUX env.
+        tmux(['kill-session', '-t', session]);
+        if (tmuxOverridden) {
+            if (origTmux === undefined)
+                delete process.env['TMUX'];
+            else
+                process.env['TMUX'] = origTmux;
+        }
+        assert.equal(spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0, false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/fixtures/fake-pi-host.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/core/__tests__/fixtures/fake-pi-host.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// fake-pi-host.ts — a deterministic stand-in for the pi LLM vehicle.
+//
+// This is NOT an LLM and NOT a mock of the extensions. It is the real pi
+// vehicle's place in the system, occupied by a tiny event driver that loads the
+// REAL canvas extensions (the `-e <path>` modules the runtime put in our argv)
+// and fires REAL lifecycle events under harness control, so the real hooks
+// drive real canvas state across the process boundary.
+//
+// The runtime exec's us exactly where it would exec `pi`, via the CRTR_PI_BINARY
+// seam in piCommand (src/core/runtime/tmux.ts). We therefore receive:
+//   • argv:  -e <ext> … -n <label> [--session <path>] [--model …] [--tools …]
+//            [--append-system-prompt <file>] [<kickoff prompt>]   (buildPiArgv)
+//   • env:   CRTR_NODE_ID, CRTR_KIND, CRTR_MODE, CRTR_LIFECYCLE, CRTR_HOME,
+//            CRTR_PARENT_NODE_ID, CRTR_ROOT_SESSION, CRTR_FRONT_DOOR  (tmux -e)
+//
+// Run under tsx (so the `-e` paths resolve to the same .ts modules the CLI
+// referenced when launched via `node --import tsx/esm src/cli.ts`).
+//
+// Control channel (one-way, polled file under the node dir):
+//   <CRTR_HOME>/nodes/<id>/fake-pi.cmd   — harness writes one JSON command
+//   <CRTR_HOME>/nodes/<id>/fake-pi.ack   — host appends an ack per command
+// Proof / observability the harness reads:
+//   <CRTR_HOME>/nodes/<id>/fake-pi.boot.json     — argv + env + loaded exts (latest boot)
+//   <CRTR_HOME>/nodes/<id>/fake-pi.boots.jsonl    — append-only, one line per boot
+//   <CRTR_HOME>/nodes/<id>/fake-pi.events.jsonl   — append-only, one line per fired event
+//   <CRTR_HOME>/nodes/<id>/fake-pi.injected.jsonl — every sendUserMessage
+//   <CRTR_HOME>/nodes/<id>/fake-pi.error          — any boot/import failure
+import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync, } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const env = process.env;
+const nodeId = (env['CRTR_NODE_ID'] ?? '').trim();
+const home = (env['CRTR_HOME'] ?? '').trim();
+const rawArgv = process.argv.slice(2); // everything after `node host.ts`
+function recordError(msg) {
+    try {
+        if (home && nodeId) {
+            const dir = join(home, 'nodes', nodeId);
+            mkdirSync(dir, { recursive: true });
+            appendFileSync(join(dir, 'fake-pi.error'), msg + '\n');
+        }
+    }
+    catch {
+        /* best effort */
+    }
+    try {
+        process.stderr.write('[fake-pi] ' + msg + '\n');
+    }
+    catch {
+        /* ignore */
+    }
+}
+function fail(msg) {
+    recordError(msg);
+    process.exit(17);
+}
+if (nodeId === '')
+    fail('CRTR_NODE_ID missing in env');
+if (home === '')
+    fail('CRTR_HOME missing in env');
+const nodeDir = join(home, 'nodes', nodeId);
+mkdirSync(nodeDir, { recursive: true });
+// --- parse the argv the runtime built (buildPiArgv → piCommand) ------------
+const extPaths = [];
+let sessionArg;
+let label;
+let prompt;
+for (let i = 0; i < rawArgv.length; i++) {
+    const a = rawArgv[i];
+    if (a === '-e')
+        extPaths.push(rawArgv[++i]);
+    else if (a === '-n')
+        label = rawArgv[++i];
+    else if (a === '--session')
+        sessionArg = rawArgv[++i];
+    else if (a === '--model' || a === '--tools' || a === '--append-system-prompt' || a === '--fork')
+        i++;
+    else if (!a.startsWith('-'))
+        prompt = a; // positional kickoff (fresh start only)
+}
+const resuming = sessionArg !== undefined;
+const sessionId = sessionArg ?? `fake-sess-${nodeId}-${Date.now()}`;
+const sessionFile = join(nodeDir, 'fake-session.jsonl');
+if (!existsSync(sessionFile))
+    writeFileSync(sessionFile, '');
+const handlers = {};
+let shutdownRequested = false;
+let streaming = false;
+const injected = [];
+function recordInjected(rec) {
+    injected.push(rec);
+    try {
+        appendFileSync(join(nodeDir, 'fake-pi.injected.jsonl'), JSON.stringify({ ...rec, ts: Date.now() }) + '\n');
+    }
+    catch {
+        /* best effort */
+    }
+}
+// The faithful pi vehicle surface — the union of every method the 7 canvas
+// extensions call at register time. `on` + `sendUserMessage` carry the
+// lifecycle behavior under test; the rest are recording stubs so the chrome
+// extensions (context-intro renderer, commands/nav slash-commands, goal-capture
+// session name) register without throwing, exactly as they would against real pi.
+const pi = {
+    on(event, h) {
+        (handlers[event] ??= []).push(h);
+    },
+    sendUserMessage(content, options) {
+        recordInjected({ content, deliverAs: options?.deliverAs });
+    },
+    sendMessage(message, options) {
+        recordInjected({ content: JSON.stringify(message), deliverAs: options?.deliverAs });
+    },
+    registerMessageRenderer(_customType, _renderer) {
+        /* spike: no-op recording stub */
+    },
+    registerCommand(_name, _options) {
+        /* spike: no-op recording stub */
+    },
+    registerShortcut(_shortcut, _options) {
+        /* spike: no-op recording stub */
+    },
+    setSessionName(_name) {
+        /* spike: no-op recording stub */
+    },
+};
+let eventSeq = 0;
+// Append a durable record of every fired event BEFORE its handlers run. This is
+// the harness's robust "the host received my command and is dispatching it"
+// signal — it survives even when a handler tears the process down mid-flight
+// (e.g. agent_end→reviveInPlace does respawn-pane -k on our own pane), which is
+// exactly the case where an after-the-fact ack would be lost.
+function recordEvent(event, ev) {
+    try {
+        const reason = ev?.reason;
+        appendFileSync(join(nodeDir, 'fake-pi.events.jsonl'), JSON.stringify({ seq: ++eventSeq, event, reason: reason ?? null, ts: Date.now() }) + '\n');
+    }
+    catch {
+        /* best effort */
+    }
+}
+async function fire(event, ev, ctx) {
+    recordEvent(event, ev);
+    for (const h of handlers[event] ?? []) {
+        try {
+            await h(ev, ctx);
+        }
+        catch (e) {
+            recordError(`handler ${event} threw: ${String(e)}`);
+        }
+    }
+}
+// The minimum fake-ctx shape (union across both focus extensions), all
+// dereferenced defensively by the hooks (ctx?.x?.()).
+const ctx = {
+    sessionManager: {
+        getSessionId: () => sessionId,
+        getSessionFile: () => sessionFile,
+    },
+    getContextUsage: () => ({ tokens: 1000 }),
+    shutdown: () => {
+        shutdownRequested = true;
+    },
+    isIdle: () => !streaming,
+    abort: () => {
+        /* spike: no-op */
+    },
+};
+// --- load the REAL extension modules from the -e paths ----------------------
+const loaded = [];
+const failedExt = [];
+for (const p of extPaths) {
+    try {
+        const mod = await import(pathToFileURL(p).href);
+        const reg = (mod['default'] ?? mod['register']);
+        if (typeof reg === 'function') {
+            reg(pi);
+            loaded.push(p);
+        }
+        else {
+            failedExt.push(`${p} (no default export fn)`);
+        }
+    }
+    catch (e) {
+        failedExt.push(`${p} :: ${String(e)}`);
+        recordError(`import ${p} failed: ${String(e)}`);
+    }
+}
+// --- session_start: the real boot-confirm hook captures session id + pid -----
+await fire('session_start', { reason: resuming ? 'resume' : 'startup' }, ctx);
+// --- the boot proof the harness asserts on ----------------------------------
+const boot = {
+    pid: process.pid,
+    nodeId,
+    home,
+    rawArgv,
+    extPaths,
+    loaded,
+    failedExt,
+    sessionId,
+    sessionFile,
+    resuming,
+    label: label ?? null,
+    prompt: prompt ?? null,
+    env: {
+        CRTR_NODE_ID: env['CRTR_NODE_ID'] ?? null,
+        CRTR_KIND: env['CRTR_KIND'] ?? null,
+        CRTR_MODE: env['CRTR_MODE'] ?? null,
+        CRTR_LIFECYCLE: env['CRTR_LIFECYCLE'] ?? null,
+        CRTR_NODE_CWD: env['CRTR_NODE_CWD'] ?? null,
+        CRTR_HOME: env['CRTR_HOME'] ?? null,
+        CRTR_PARENT_NODE_ID: env['CRTR_PARENT_NODE_ID'] ?? null,
+        CRTR_ROOT_SESSION: env['CRTR_ROOT_SESSION'] ?? null,
+        CRTR_FRONT_DOOR: env['CRTR_FRONT_DOOR'] ?? null,
+    },
+    injectedDuringBoot: injected.slice(),
+};
+writeFileSync(join(nodeDir, 'fake-pi.boot.json'), JSON.stringify(boot, null, 2));
+// Append-only boot log so the harness can count re-boots (a resume after an
+// idle-release wake, or a fresh pi after a refresh-yield reviveInPlace).
+try {
+    appendFileSync(join(nodeDir, 'fake-pi.boots.jsonl'), JSON.stringify(boot) + '\n');
+}
+catch {
+    /* best effort */
+}
+// --- control loop: poll for one harness command at a time -------------------
+const cmdFile = join(nodeDir, 'fake-pi.cmd');
+const ackFile = join(nodeDir, 'fake-pi.ack');
+function ack(id, body) {
+    try {
+        appendFileSync(ackFile, JSON.stringify({ id, ...body, ts: Date.now() }) + '\n');
+    }
+    catch {
+        /* best effort */
+    }
+}
+async function doShutdown() {
+    // A clean pi /quit. The stophook's session_shutdown handler resolves a still-
+    // active node to done (markCleanExitDone → finalize). Mirrors real pi exiting.
+    await fire('session_shutdown', { reason: 'quit' }, ctx);
+    ack('shutdown', { ok: true });
+    clearInterval(timer);
+    process.exit(0);
+}
+async function dispatch(cmd) {
+    const id = cmd.id ?? cmd.cmd ?? 'cmd';
+    switch (cmd.cmd) {
+        case 'shutdown':
+            await doShutdown();
+            break;
+        case 'stop':
+            streaming = false;
+            await fire('agent_end', {
+                messages: [
+                    { role: 'assistant', stopReason: cmd.reason ?? 'stop', content: [{ type: 'text', text: cmd.text ?? '' }] },
+                ],
+            }, ctx);
+            ack(id, { ok: true });
+            break;
+        case 'turn':
+            streaming = true;
+            await fire('agent_start', {}, ctx);
+            streaming = false;
+            await fire('turn_end', { message: { role: 'assistant', usage: { input: 10, output: 5 }, model: 'fake' } }, ctx);
+            await fire('agent_end', { messages: [{ role: 'assistant', stopReason: 'stop', content: [{ type: 'text', text: cmd.text ?? '' }] }] }, ctx);
+            ack(id, { ok: true });
+            break;
+        default:
+            ack(id, { ok: false, error: `unknown cmd: ${String(cmd.cmd)}` });
+    }
+}
+async function step() {
+    if (shutdownRequested) {
+        await doShutdown();
+        return;
+    }
+    if (!existsSync(cmdFile))
+        return;
+    let cmd = null;
+    try {
+        cmd = JSON.parse(readFileSync(cmdFile, 'utf8'));
+    }
+    catch {
+        cmd = null;
+    }
+    try {
+        unlinkSync(cmdFile);
+    }
+    catch {
+        /* ignore */
+    }
+    if (cmd)
+        await dispatch(cmd);
+    if (shutdownRequested)
+        await doShutdown();
+}
+const timer = setInterval(() => {
+    void step().catch((e) => recordError(`step: ${String(e)}`));
+}, 100);