@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/__tests__/detach-focus.test.js

@@ -0,0 +1,206 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/detach-focus.test.ts
+//
+// GAP CLOSE (flagship-lifecycle.test.ts coverage boundary): "node demote
+// --detach (A3: orphaned-focus-row hazard)". An END-TO-END test that drives the
+// REAL `crtr node demote --detach` verb (subprocess, AS the node) — the actual
+// Alt+C → D menu path — against a live fake-pi node genuinely FOCUSED in a user
+// viewport, and
+// proves the three things the A3 hazard is about:
+//   (a) lifecycle flips terminal IN PLACE,
+//   (b) the still-running pi's pane is RELOCATED to the backstage crtr session
+//       (the pi keeps generating off-screen, not killed),
+//   (c) the focus row it occupied is CLOSED — no orphaned/phantom viewport row
+//       lingering on the relocated %pane_id (Invariant P / Invariant F5).
+//
+// This is the harness-driven counterpart to placement-focus.test.ts's
+// `detachToBackground` unit (which calls the function directly): here the FLIP
+// and the detach both go through the real CLI leaf (node.ts nodeDemote →
+// setLifecycle), so the whole `crtr node demote --detach` wiring — the Alt+C → D
+// menu path — is exercised. Modeled on live-mutation.test.ts (harness +
+// `crtr node demote` + firstPaneOf) and
+// placement-focus.test.ts (user/back sessions + focus-row asserts).
+//
+// NOTE — the SIBLING focused-finish→manager-TAKEOVER path is NOT added here: the
+// harness mints its root via in-process createNode (never a real bootRoot — see
+// flagship S1), so a manager is always a paneless, never-booted row. Driving B
+// through agent_end's done-branch (h.finish) with such a manager would only ever
+// hit handFocusToManager's "live-but-paneless inline root → false" guard
+// (closeFocusToShell), never a genuine takeover; a LIVE-backstage or dormant
+// idle-release manager swap is unreachable through the harness. That swap is
+// unit-covered in placement-teardown.test.ts (MAJOR 1 + the dormant idle-release
+// case), so it is deliberately not re-driven here.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { setPresence, getNode } from '../canvas/canvas.js';
+import { openFocusRow, getFocusByNode, getFocusByPane, listFocuses } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { markBusy } from '../runtime/busy.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+function tmuxOut(args) {
+    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
+}
+/** The first %pane_id of a tmux window (spawn records window+session, not pane). */
+function firstPaneOf(window) {
+    const r = spawnSync('tmux', ['list-panes', '-t', window, '-F', '#{pane_id}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0] ?? null;
+}
+/** A pane's CURRENT session/window (display-message on its durable %id). */
+function paneLoc(pane) {
+    const out = tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}\t#{window_id}']);
+    const [session, window] = out.split('\t');
+    if (!session || !window)
+        return null;
+    return { session, window };
+}
+function paneSessionReal(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}']);
+}
+function paneExistsReal(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{pane_id}']) === pane;
+}
+// ===========================================================================
+// `crtr node demote --detach` on a FOCUSED node (A3 gap close; Alt+C → D).
+// ===========================================================================
+test('node demote --detach on a FOCUSED node: flips terminal, relocates the pane to the backstage, CLOSES the focus row (A3 — no orphaned focus row)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-detach-focus' });
+    const user = `crtr-detach-user-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        // A resident root + a live terminal child B (born into the backstage =
+        // h.session, the harness's CRTR_NODE_SESSION). B holds an active live sub
+        // to nothing extra — it just needs to be a live, focusable terminal node.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const b0 = h.node(B);
+        assert.equal(b0.lifecycle, 'terminal', 'B born terminal');
+        assert.equal(b0.status, 'active', 'B active after boot');
+        // Resolve B's live %pane_id from its window (the spawn path records only
+        // window+session; pane is null until a reconcile/focus).
+        const bPane = firstPaneOf(b0.window);
+        assert.ok(typeof bPane === 'string' && bPane !== '', 'B has a live pane');
+        // --- Put B into a USER viewport, FOCUSED. Create a separate user session
+        //     and break B's live pi pane out into it (the pi keeps running; the
+        //     %id survives the break), then anchor its presence + open a focus row.
+        //     This is the genuine "focused in a user pane" precondition — distinct
+        //     from the backstage (h.session) the detach will relocate it back to.
+        spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600'], { stdio: 'ignore' });
+        assert.equal(spawnSync('tmux', ['break-pane', '-d', '-a', '-s', bPane, '-t', `${user}:`]).status, 0, 'B pane broke out into the user viewport (pi kept alive)');
+        const moved = paneLoc(bPane);
+        assert.equal(moved?.session, user, 'B pane physically in the user session now');
+        assert.equal(paneExistsReal(bPane), true, "B's pi is still alive after the move");
+        closeDb();
+        setPresence(B, { pane: bPane, tmux_session: user, window: moved.window });
+        openFocusRow('f-detach', bPane, user, B);
+        assert.equal(getFocusByNode(B)?.focus_id, 'f-detach', 'precondition: B is FOCUSED in the user viewport');
+        // B must read as GENERATING for the backstage-park path: isGenerating now
+        // gates the break-pane (Bug 1 / Invariant P) on the mid-turn busy marker
+        // AND a live pi_pid. The boot only recorded pi_pid (session_start); no turn
+        // fired, so set the busy marker to model an agent genuinely mid-turn —
+        // otherwise the new gate would RELEASE B (the non-generating path below).
+        markBusy(B);
+        // --- Drive the REAL verb on the FOCUSED node. The subprocess inherits
+        //     CRTR_NODE_SESSION = h.session (the backstage), so detachToBackground
+        //     breaks the pane back into h.session.
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
+        assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
+        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        closeDb();
+        const b = getNode(B);
+        // (a) lifecycle flipped to terminal IN PLACE.
+        assert.equal(b.lifecycle, 'terminal', '(a) B lifecycle=terminal after the flip');
+        assert.equal(b.status, 'active', "(a) detach does NOT end the pi — B stays active");
+        // (b) the still-running pane was RELOCATED to the backstage crtr session
+        //     (NOT killed): the pi keeps generating off-screen.
+        assert.equal(paneExistsReal(bPane), true, "(b) B's pi keeps generating (pane alive, relocated not killed)");
+        assert.equal(paneSessionReal(bPane), h.session, '(b) B pane relocated to the backstage crtr session');
+        assert.equal(b.tmux_session, h.session, "(b) B's LOCATION followed the pane to the backstage");
+        // (c) the focus row is CLOSED — no orphaned/phantom viewport (A3 hazard).
+        assert.equal(getFocusByNode(B), null, '(c) B no longer occupies any focus (row CLOSED — Invariant P)');
+        assert.equal(getFocusByPane(bPane), null, '(c) NO phantom focus resolves on the relocated %id');
+        assert.equal(listFocuses().length, 0, '(c) no dangling focus rows remain');
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// Bug 1 (Invariant P / detach-idle-node): `crtr node demote --detach` on a
+// NON-GENERATING focused node must NOT park it alive in the backstage — it must
+// be RELEASED to dormant and its pane reaped.
+//
+// The backstage holds ONLY generating-but-unfocused nodes (Invariant P).
+// detachToBackground used to break-pane to the backstage UNCONDITIONALLY, with no
+// generating-ness check: a resident root parked idle between turns (pi alive,
+// idle, NOT mid-turn) detached via Alt+C → D became unfocused + pi-alive-idle +
+// holding a backstage pane forever — nothing re-enters agent_end to release it
+// and, with no live subscription, nothing wakes it → a leaked live-idle pi that
+// never reaps. The fix gates the break-pane on isGenerating() and RELEASES a
+// non-generating node to dormant instead (mirrors retargetFocus's parked-viewer
+// release on focus-away).
+//
+// This drives the SAME real verb as the happy-path test above, but on a node
+// with NO busy marker (not mid-turn). isGenerating() = busy && pidAlive, so a
+// freshly-booted node (pi_pid recorded at session_start, no turn fired) reads as
+// NOT generating.
+// ===========================================================================
+test('node demote --detach on a NON-GENERATING focused node: RELEASES to dormant (idle + idle-release), reaps the pane, closes the focus row — NOT parked in the backstage (Bug 1 — Invariant P)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-detach-idle' });
+    const user = `crtr-detach-idle-user-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        // A resident root + a live terminal child B. B is freshly booted: pi alive
+        // (pi_pid recorded at session_start), status active, and — critically — NO
+        // busy marker, since no turn ever fired. It is parked idle, not mid-turn:
+        // exactly the non-generating occupant Bug 1 is about.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const b0 = h.node(B);
+        assert.equal(b0.status, 'active', 'B active after boot');
+        const bPane = firstPaneOf(b0.window);
+        assert.ok(typeof bPane === 'string' && bPane !== '', 'B has a live pane');
+        // --- Put B into a USER viewport, FOCUSED (same precondition as the happy
+        //     path), but DO NOT mark it busy: it stays NOT generating.
+        spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600'], { stdio: 'ignore' });
+        assert.equal(spawnSync('tmux', ['break-pane', '-d', '-a', '-s', bPane, '-t', `${user}:`]).status, 0, 'B pane broke out into the user viewport (pi kept alive)');
+        const moved = paneLoc(bPane);
+        assert.equal(moved?.session, user, 'B pane physically in the user session now');
+        assert.equal(paneExistsReal(bPane), true, "B's pi is alive (parked idle, not mid-turn)");
+        closeDb();
+        setPresence(B, { pane: bPane, tmux_session: user, window: moved.window });
+        openFocusRow('f-detach-idle', bPane, user, B);
+        assert.equal(getFocusByNode(B)?.focus_id, 'f-detach-idle', 'precondition: B is FOCUSED, NON-generating');
+        // --- Drive the REAL verb on the non-generating focused node.
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
+        assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
+        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        closeDb();
+        const b = getNode(B);
+        // (b) RELEASED to dormant — idle + intent='idle-release' (revivable via inbox
+        //     / re-focus), NOT left active in the backstage.
+        assert.equal(b.status, 'idle', '(b) B released to dormant (status idle)');
+        assert.equal(b.intent, 'idle-release', "(b) B's intent is idle-release (daemon revives on inbox)");
+        // (c) the pane is REAPED / presence nulled — NOT relocated to the backstage
+        //     crtr session. The leaked live-idle pi must be gone.
+        assert.equal(paneExistsReal(bPane), false, '(c) B pane reaped (NOT parked alive in the backstage)');
+        assert.equal(b.pane, null, "(c) B's presence pane is nulled");
+        assert.equal(b.tmux_session, null, "(c) B's presence session is nulled (NOT the backstage crtr session)");
+        // (a) the focus row is CLOSED — no orphaned/phantom viewport.
+        assert.equal(getFocusByNode(B), null, '(a) B no longer occupies any focus (row CLOSED — Invariant P)');
+        assert.equal(getFocusByPane(bPane), null, '(a) NO phantom focus resolves on the reaped %id');
+        assert.equal(listFocuses().length, 0, '(a) no dangling focus rows remain');
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/draw-style.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/draw-style.test.js

@@ -0,0 +1,258 @@
+// Bug-regression test for the crtr TUI Draw style encoding.
+//
+// Observed bug (canvas + linkedin views, 2026-06-07): view code set Style.fg to a
+// color NAME ('green'/'cyan'/'red') instead of an SGR parameter ('32'/'36'/'31').
+// With color ON, styleSpan emitted `\x1b[greenm` — an invalid CSI the terminal
+// eats as a control op, printing the tail ('reenm') as literal garbage. The
+// monitor's status glyphs/flags rendered as garbage on any color terminal (the
+// non-TTY/NO_COLOR path was unaffected because fg is gated behind `color`).
+//
+// Root-cause fix: styleSpan now only emits fg/bg when the value is a valid SGR
+// parameter string (digits + semicolons); a bad value degrades to no-color
+// instead of emitting a broken escape. These tests lock that guarantee.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/draw-style.test.ts
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { styleSpan, isSgrParams, createDraw } from '../tui/draw.js';
+import { drawChrome } from '../tui/host.js';
+const ESC = '\x1b[';
+const ON = { color: true, color256: true };
+const OFF = { color: false, color256: false };
+const SIZE = { cols: 80, rows: 24 };
+/** Strip the harmless framing CSIs the serializer emits (cursor home / clear),
+ *  so any REMAINING `\x1b[` not followed by an SGR param digit/semicolon is a
+ *  broken SGR escape — the exact bug class (`\x1b[greenm`). */
+function hasInvalidCsi(frame) {
+    const stripped = frame.replace(/\x1b\[[HJK]/g, '').replace(/[\r\n]/g, '');
+    return /\x1b\[[^0-9;]/.test(stripped);
+}
+/** Any 8-bit color SGR (fg 30-37/90-97, or 256-color bg) present in the frame. */
+function hasColorSgr(frame) {
+    return /\x1b\[(3[0-9]|9[0-7])m/.test(frame) || /\x1b\[48;5;/.test(frame);
+}
+function baseChrome(over = {}) {
+    return { status: null, banner: null, busy: false, loaded: true, lastRefresh: Date.now(), tick: 0, subtitle: null, mode: null, ...over };
+}
+const MANIFEST = {
+    id: 't', title: 'Test View', subtitle: '3 unread', description: 'd',
+    keymap: [
+        { keys: 'j/k', label: 'move' }, { keys: 'enter', label: 'open' },
+        { keys: 'r', label: 'reply' }, { keys: 'g', label: 'refresh' }, { keys: 'q', label: 'quit' },
+    ],
+};
+describe('styleSpan: SGR encoding (bug-regression)', () => {
+    test('a valid numeric fg emits a well-formed CSI', () => {
+        const out = styleSpan('●', { fg: '32', bold: true }, true, '');
+        assert.ok(out.includes(`${ESC}32m`), 'should contain \\x1b[32m');
+        assert.ok(out.includes(`${ESC}1m`), 'bold still emitted');
+    });
+    test('a color NAME fg degrades to no-color — never emits a broken escape', () => {
+        const out = styleSpan('●', { fg: 'green' }, true, '');
+        // The bug: \x1b[greenm. Assert no CSI is followed by a non-digit/semicolon.
+        assert.ok(!/\x1b\[[^0-9;]/.test(out), 'no invalid CSI introducer');
+        assert.ok(!out.includes('green'), 'the bad token never leaks into output');
+    });
+    test('a color NAME bg degrades to no-color', () => {
+        const out = styleSpan('x', { bg: 'red' }, true, '');
+        assert.ok(!/\x1b\[[^0-9;]/.test(out), 'no invalid CSI introducer');
+        assert.ok(!out.includes('red'), 'the bad token never leaks into output');
+    });
+    test('a valid 256-color bg index emits 48;5;N', () => {
+        const out = styleSpan('x', { bg: '236' }, true, '');
+        assert.ok(out.includes(`${ESC}48;5;236m`), 'should contain \\x1b[48;5;236m');
+    });
+    test('compound SGR params (e.g. "1;36") are valid', () => {
+        assert.equal(isSgrParams('1;36'), true);
+        assert.equal(isSgrParams('236'), true);
+        assert.equal(isSgrParams('green'), false);
+        assert.equal(isSgrParams(''), false);
+    });
+    test('structural styles (bold/dim/reverse) are unaffected by color gating', () => {
+        const out = styleSpan('x', { fg: 'green', dim: true }, true, '');
+        assert.ok(out.includes(`${ESC}2m`), 'dim still emitted even when fg is rejected');
+    });
+});
+// ── New Draw primitives — same bug class (no invalid CSI; bad value degrades) ──
+describe('spansRight: SGR encoding (bug-regression)', () => {
+    test('valid numeric fg → well-formed CSI, no broken escape', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        draw.spansRight(0, 80, [{ text: 'ready', style: { fg: '32', bold: true } }]);
+        const f = frame();
+        assert.ok(f.includes(`${ESC}32m`), 'emits \\x1b[32m');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('a color NAME fg degrades — no broken escape, name not leaked', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        draw.spansRight(0, 80, [{ text: 'x', style: { fg: 'green' } }]);
+        const f = frame();
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI introducer');
+        assert.ok(!f.includes('green'), 'the bad token never leaks');
+    });
+    test('over-maxWidth groups left-clip with a leading … (no overflow, no garbage)', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        draw.spansRight(0, 80, [{ text: 'abcdefghij', style: { dim: true } }], 4);
+        const f = frame();
+        assert.ok(f.includes('…'), 'leading ellipsis present');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+});
+describe('vline: SGR encoding + mono fallback (bug-regression)', () => {
+    test('renders a dim rule with no invalid CSI (color on)', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        draw.vline(40, 0, 10);
+        const f = frame();
+        assert.ok(f.includes('│'), 'default │ glyph present');
+        assert.ok(f.includes(`${ESC}2m`), 'dim emitted');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('ASCII fallback ch and mono caps both stay well-formed', () => {
+        const { draw, frame } = createDraw(SIZE, OFF);
+        draw.vline(40, 0, 10, '|');
+        const f = frame();
+        assert.ok(f.includes('|'), 'ASCII fallback | present');
+        assert.ok(!hasColorSgr(f), 'no color SGR when caps.color is off');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+});
+describe('ListItemRow.right: SGR encoding (bug-regression)', () => {
+    test('right group + cursor-row base merge → no invalid CSI', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        /** @type {ListItemRow[]} */
+        const items = [
+            { spans: [{ text: 'Ada Lovelace', style: { bold: true } }], right: [{ text: '2h', style: { fg: '90' } }] },
+            { spans: [{ text: 'Grace Hopper' }], right: [{ text: '4h', style: { fg: '90' } }] },
+        ];
+        const res = draw.list({ row: 2, col: 0, width: 80, height: 5 }, items, 0, 0);
+        const f = frame();
+        assert.equal(res.scroll, 0);
+        assert.ok(f.includes('2h') && f.includes('4h'), 'right-flushed timestamps drawn');
+        assert.ok(f.includes(`${ESC}48;5;236m`), 'cursor-row 236-bg highlight present');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('a color NAME fg in the right group degrades, not leaks', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        const items = [{ spans: [{ text: 'x' }], right: [{ text: 'y', style: { fg: 'cyan' } }] }];
+        draw.list({ row: 0, col: 0, width: 80, height: 2 }, items, 0, 0);
+        const f = frame();
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+        assert.ok(!f.includes('cyan'), 'the bad token never leaks');
+    });
+});
+// ── Chrome — every new element survives the bug class + has a mono fallback ──
+describe('drawChrome: SGR encoding + mono fallback (bug-regression)', () => {
+    const states = [
+        ['working', baseChrome({ busy: true, status: 'Loading…' })],
+        ['blocked', baseChrome({ banner: { msg: 'Send rejected', level: 'error' } })],
+        ['attention', baseChrome({ banner: { msg: 'Log in, then press r', level: 'action' } })],
+        ['ready', baseChrome({ status: '5 conversations' })],
+        ['idle', baseChrome({ loaded: false, lastRefresh: 0 })],
+        ['info-banner', baseChrome({ banner: { msg: 'Throttling — waiting', level: 'info' } })],
+    ];
+    for (const [name, chrome] of states) {
+        test(`state "${name}" never emits a broken escape (color on)`, () => {
+            const { draw, frame } = createDraw(SIZE, ON);
+            drawChrome(draw, SIZE, MANIFEST, chrome);
+            assert.ok(!hasInvalidCsi(frame()), 'no invalid CSI');
+        });
+    }
+    test('mono fallback: no color SGR when caps.color is off, glyphs/words still render', () => {
+        const { draw, frame } = createDraw(SIZE, OFF);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ busy: true, status: 'Loading…' }));
+        const f = frame();
+        assert.ok(!hasColorSgr(f), 'no color SGR emitted in mono');
+        assert.ok(f.includes('▎'), 'state rail glyph always drawn');
+        assert.ok(f.includes('working'), 'state WORD carries meaning in mono');
+        assert.ok(f.includes(`${ESC}1m`), 'structural bold still emitted');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('every banner level renders its glyph with no broken escape', () => {
+        for (const [level, glyph] of [['info', 'ℹ'], ['action', '▸'], ['error', '✗']]) {
+            const { draw, frame } = createDraw(SIZE, ON);
+            drawChrome(draw, SIZE, MANIFEST, baseChrome({ banner: { msg: 'm', level } }));
+            const f = frame();
+            assert.ok(f.includes(glyph), `${level} banner glyph ${glyph} present`);
+            assert.ok(!hasInvalidCsi(f), `${level} banner: no invalid CSI`);
+        }
+    });
+    test('keymap overflow degrades to keys-only on a narrow screen, still well-formed', () => {
+        const narrow = { cols: 28, rows: 24 };
+        const { draw, frame } = createDraw(narrow, ON);
+        drawChrome(draw, narrow, MANIFEST, baseChrome({ status: 'a very long status line here' }));
+        const f = frame();
+        assert.ok(f.includes('q'), 'q quit hint survives overflow');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI under overflow');
+    });
+});
+// ── Dynamic subtitle (host.setSubtitle) — same bug class + mono fallback ──
+describe('drawChrome subtitle: SGR encoding + mono fallback (bug-regression)', () => {
+    test('a dynamic subtitle overrides manifest.subtitle, dim, no broken escape', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ subtitle: '7 unread' }));
+        const f = frame();
+        assert.ok(f.includes('7 unread'), 'dynamic subtitle rendered');
+        assert.ok(!f.includes('3 unread'), 'dynamic value overrides the static manifest subtitle');
+        assert.ok(f.includes(`${ESC}2m`), 'subtitle is dim (structural)');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('null subtitle falls back to the manifest default', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ subtitle: null }));
+        const f = frame();
+        assert.ok(f.includes('3 unread'), 'manifest.subtitle shown when dynamic is null');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('mono fallback: subtitle text renders dim with no color SGR', () => {
+        const { draw, frame } = createDraw(SIZE, OFF);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ subtitle: '7 unread' }));
+        const f = frame();
+        assert.ok(f.includes('7 unread'), 'subtitle text still renders in mono');
+        assert.ok(!hasColorSgr(f), 'no color SGR emitted for the subtitle in mono');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+});
+// ── Mode chip (host.setMode) — same bug class, mono fallback, precedence ──
+describe('drawChrome mode chip: SGR encoding + mono fallback (bug-regression)', () => {
+    test('compose mode → ✎ compose in yellow (33), no broken escape', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ mode: 'compose' }));
+        const f = frame();
+        assert.ok(f.includes('✎') && f.includes('compose'), 'mode glyph + word present');
+        assert.ok(f.includes(`${ESC}33m`), 'compose-accent yellow 33 emitted');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('react mode → ☺ react reuses the compose-accent yellow (33)', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ mode: 'react' }));
+        const f = frame();
+        assert.ok(f.includes('☺') && f.includes('react'), 'react glyph + word present');
+        assert.ok(f.includes(`${ESC}33m`), 'react reuses yellow 33');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('mono fallback: mode chip is glyph + bold word, no color SGR', () => {
+        const { draw, frame } = createDraw(SIZE, OFF);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ mode: 'compose' }));
+        const f = frame();
+        assert.ok(f.includes('✎'), 'glyph carries the mode in mono');
+        assert.ok(f.includes('compose'), 'mode word carries meaning in mono');
+        assert.ok(f.includes(`${ESC}1m`), 'bold still emitted (mono carrier)');
+        assert.ok(!hasColorSgr(f), 'no color SGR emitted in mono');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('precedence: an explicit mode WINS the chip over the derived busy/working state', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        // busy would derive `working`; the explicit mode must override it.
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ busy: true, mode: 'compose' }));
+        const f = frame();
+        assert.ok(f.includes('compose'), 'mode word shown');
+        assert.ok(!f.includes('working'), 'derived working chip suppressed by the mode override');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+    test('null mode returns to the derived chip (ready when loaded)', () => {
+        const { draw, frame } = createDraw(SIZE, ON);
+        drawChrome(draw, SIZE, MANIFEST, baseChrome({ mode: null }));
+        const f = frame();
+        assert.ok(f.includes('ready'), 'derived ready chip shown when no mode set');
+        assert.ok(!hasInvalidCsi(f), 'no invalid CSI');
+    });
+});

package/dist/core/__tests__/fixtures/c3-custom-provider-ext.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/core/__tests__/fixtures/c3-custom-provider-ext.js

@@ -0,0 +1,18 @@
+export default function (pi) {
+    pi.registerProvider('c3prov', {
+        baseUrl: 'https://example.invalid',
+        apiKey: 'c3-test-key',
+        api: 'anthropic-messages',
+        models: [
+            {
+                id: 'c3model',
+                name: 'C3 Custom Model',
+                reasoning: false,
+                input: ['text'],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: 1000,
+                maxTokens: 100,
+            },
+        ],
+    });
+}

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -0,0 +1,138 @@
+/** Test seam (M-1 regression): a FRESH-start kickoff prompt carrying this token
+ *  makes the fake engine THROW inside bindExtensions BEFORE it fires
+ *  session_start — the exact failure mode that records no pid and no session, so
+ *  the broker exits(1) and the daemon must surface a boot failure rather than
+ *  strand the node. Carried on the prompt (not a global env) so it is per-spawn. */
+export declare const FAIL_BEFORE_SESSION_START = "__FAIL_BEFORE_SESSION_START__";
+export declare class SessionManager {
+    readonly sessionId: string;
+    readonly sessionFile: string;
+    readonly resumed: boolean;
+    private constructor();
+    /** Fresh start: a brand-new session whose .jsonl lives under the node dir
+     *  (created empty if missing, like fake-pi-host). */
+    static create(_cwd: string): SessionManager;
+    /** Resume: round-trip the .jsonl PATH the revive passed via `--session`. */
+    static open(path: string): SessionManager;
+    getSessionId(): string;
+    getSessionFile(): string;
+}
+type Handler = (ev: unknown, ctx: unknown) => void | Promise<void>;
+interface BindExtensionsOpts {
+    uiContext: BrokerUiContext;
+    mode: string;
+    shutdownHandler?: () => void;
+}
+/** The slice of the broker's ExtensionUIContext we exercise (the only blocking
+ *  dialog scenario 7 drives). */
+interface BrokerUiContext {
+    confirm?: (title: string, message: string, opts?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }) => Promise<boolean>;
+}
+/** The slice of a loaded SDK extension we drive: its path + the handler map the
+ *  SDK's createExtensionAPI populated as the extension called pi.on(event, …)
+ *  during the loader's reload(). */
+interface LoadedExtension {
+    path: string;
+    handlers: Map<string, Handler[]>;
+}
+/** The shared extension runtime the SDK's loader built (createExtensionRuntime).
+ *  Its action methods start as `notInitialized` throwers; the REAL session's
+ *  bindCore swaps them for working impls bound to the live session — we replicate
+ *  the minimal slice (sendUserMessage/sendMessage/setSessionName) so the already-
+ *  registered handlers (e.g. the inbox-watcher) deliver instead of throwing. */
+interface ExtRuntime {
+    assertActive: () => void;
+    sendUserMessage: (content: string, options?: {
+        deliverAs?: string;
+    }) => void;
+    sendMessage: (message: unknown, options?: {
+        deliverAs?: string;
+    }) => void;
+    setSessionName: (name: string) => void;
+    [k: string]: unknown;
+}
+/** The minimal slice of the REAL DefaultResourceLoader the broker hands to
+ *  createAgentSession: getExtensions() returns the already-loaded (jiti) canvas
+ *  extensions + their shared runtime. */
+interface ResourceLoader {
+    getExtensions(): {
+        extensions: LoadedExtension[];
+        errors?: unknown[];
+        runtime: ExtRuntime;
+    };
+}
+declare class FakeSession {
+    private readonly sm;
+    private readonly loader;
+    private readonly dir;
+    private extensions;
+    private readonly injected;
+    private uiContext;
+    private shutdownHandler;
+    private streaming;
+    private disposed;
+    private eventSeq;
+    private timer;
+    private readonly listeners;
+    private readonly messageLog;
+    constructor(sm: SessionManager, loader: ResourceLoader | undefined);
+    get messages(): unknown[];
+    get sessionId(): string;
+    get sessionFile(): string | undefined;
+    get model(): {
+        id: string;
+    } | undefined;
+    get isStreaming(): boolean;
+    getSessionStats(): Record<string, unknown>;
+    setSessionName(_name: string): void;
+    prompt(text: string, _options?: unknown): Promise<void>;
+    steer(_text: string): Promise<void>;
+    followUp(_text: string): Promise<void>;
+    abort(): Promise<void>;
+    subscribe(listener: (event: unknown) => void): () => void;
+    /** Fan one typed AgentSessionEvent out to every broker subscriber. A throwing
+     *  listener is recorded, never propagated (mirrors the broker's m7 try/catch). */
+    private emit;
+    /** Emit a realistic streaming assistant turn on the subscribe channel:
+     *  agent_start → turn_start → message_start → message_update×N →
+     *  tool_execution_start/update/end → message_end → turn_end → agent_end. Drives
+     *  G1 (controller prompt relay), G3 (produce-while-detached, accrues messageLog),
+     *  and G8 (a fast event stream — `updates`/`padBytes` size the flood that sheds a
+     *  stalled viewer at the broker HWM). A per-update setImmediate yield lets a
+     *  fast viewer drain between frames so only the stalled one trips the HWM. */
+    private emitTurn;
+    dispose(): void;
+    bindExtensions(opts: BindExtensionsOpts): Promise<void>;
+    private recordInjected;
+    private buildCtx;
+    private recordEvent;
+    private fire;
+    private step;
+    private dispatch;
+    private runDialog;
+}
+interface FakeServices {
+    resourceLoader: ResourceLoader;
+    modelRegistry: {
+        find: (provider: string, id: string) => undefined;
+    };
+}
+export declare function createAgentSessionServices(options: {
+    cwd: string;
+    agentDir?: string;
+    resourceLoaderOptions?: {
+        additionalExtensionPaths?: string[];
+        appendSystemPrompt?: string[];
+    };
+}): Promise<FakeServices>;
+export declare function createAgentSessionFromServices(options: {
+    services: FakeServices;
+    sessionManager: SessionManager;
+}): Promise<{
+    session: FakeSession;
+}>;
+export declare const VERSION = "0.78.1";
+export {};