@north-light/crouter 0.3.154

package/dist/clients/attach/__tests__/attach-chrome-remote.test.js

@@ -0,0 +1,467 @@
+// attach-chrome-remote.test.ts — the safe-defaults contract for the attach
+// chrome (buildCanvasPanelLines + GraphOverlay) when the `canvasSource` is a
+// RemoteCanvasSource, i.e. `crtr surface attach --canvas <name>`.
+//
+// Adversarial, not merely a clean-machine assertion (mirrors
+// core/canvas/__tests__/render-remote.test.ts): BEFORE rendering, this test
+// seeds real, CONFLICTING local state for node id `a` — a poisoned telemetry
+// reading (context tokens + a live-activity cue), an active fault, a local
+// tmux focus, and a broker attach.json marking it human-watched — every
+// historically-broken local read the remote suppression in nav-model.ts is
+// supposed to bypass. If the production suppression ever regressed back to
+// consulting local disk/SQLite for a remote id, the rendered lines below would
+// carry the poisoned tokens/glyph/background instead of the safe defaults, so
+// a clean-machine run could never mask the regression.
+//
+// Also proves the read-only contract: GraphOverlay's Enter/m/x key handlers
+// must no-op against a remote graph row instead of shelling local
+// `crtr surface node focus` / `crtr node lifecycle close`.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RemoteCanvasSource } from '../../../core/canvas/remote-canvas-source.js';
+import { createNode } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { openFocusRow } from '../../../core/canvas/focuses.js';
+import { jobDir } from '../../../core/canvas/paths.js';
+import { recordFault } from '../../../core/runtime/fault.js';
+import { BG_ATTACHED } from '../../../core/canvas/nav-model.js';
+import { resolveKeybindings } from '../../../core/keybindings/index.js';
+import { dispatchSlashCommand, slashCommandList } from '../slash/dispatch.js';
+import { resolveInitialMode, requestModeSwitch } from '../session/mode.js';
+import { tagAttachPane, untagAttachPane } from '../session/pane-tag.js';
+import { createMemoryRefRefreshCoordinator } from '../session/editor-inventory.js';
+import { InputController } from '../input/controller.js';
+import { buildCanvasPanelLines } from '../chrome/canvas-panels.js';
+import { GraphOverlay } from '../overlays/graph.js';
+function startMockCrtrServer(route) {
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const bodyText = Buffer.concat(chunks).toString('utf8');
+                const parsed = JSON.parse(bodyText);
+                const result = route(parsed.args);
+                res.writeHead(result.status ?? 200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(result.body), stderr: '' }));
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+function meta(id, extra) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...extra,
+    };
+}
+function show(node, reports, managers) {
+    return {
+        node,
+        reports: reports.map((id) => ({ node_id: id, name: id, kind: 'general', status: 'active', active: true })),
+        managers: managers.map((id) => ({ node_id: id, name: id, kind: 'general', status: 'active', active: true })),
+        artifacts: { report: 0, doc: 0, roadmap: 0 },
+        pending_crons: 0,
+        paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+        follow_up: '',
+    };
+}
+const IDENTITY_PALETTE = {
+    accent: (s) => s,
+    active: (s) => s,
+    info: (s) => s,
+    muted: (s) => s,
+    faint: (s) => s,
+    border: (s) => s,
+    bold: (s) => s,
+    error: (s) => s,
+    warning: (s) => s,
+    bashMode: (s) => s,
+    bashModeAlt: (s) => s,
+    surface: (s) => s,
+};
+/** A fake `TUI` carrying just what `GraphOverlay` touches: `showOverlay` (a
+ *  no-op handle) and `requestRender`. GraphOverlay's key handlers only shell
+ *  `crtr` (via execFile) and toggle local overlay/handle state — they never
+ *  reach into the real TUI beyond these two calls. */
+function fakeTui() {
+    let renders = 0;
+    const tui = {
+        showOverlay: () => ({
+            hide: () => { },
+            setHidden: () => { },
+            isHidden: () => false,
+            focus: () => { },
+            unfocus: () => { },
+            isFocused: () => true,
+        }),
+        requestRender: () => { renders++; },
+    };
+    return { tui, renderCount: () => renders };
+}
+let home;
+let localCwd;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-attach-chrome-remote-'));
+    localCwd = mkdtempSync(join(tmpdir(), 'crtr-attach-chrome-remote-cwd-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(localCwd, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+/** Seed conflicting local state for node id `a` — every local read the
+ *  attach-chrome remote suppression is supposed to bypass. */
+function seedPoisonedLocalState() {
+    createNode(meta('a', { cwd: localCwd }));
+    // A local focus — poisons focusedNodeIds()/isAttached's fast path.
+    openFocusRow('poison-focus', null, null, 'a');
+    // A broker attach.json — poisons isAttached's slow path.
+    writeFileSync(join(jobDir('a'), 'attach.json'), JSON.stringify({ viewers: 1 }));
+    // An active, manually-retried fault — poisons nodeGlyph's hanging overlay.
+    recordFault('a', {
+        link: 'viewer↔broker',
+        op: 'poison',
+        kind: 'other',
+        retry: { disposition: 'manual' },
+        message: 'POISON FAULT — local read leaked into remote attach chrome',
+    });
+    // Local telemetry — poisons tokensCell + activityCell.
+    writeFileSync(join(jobDir('a'), 'telemetry.json'), JSON.stringify({
+        context_tokens: 999_999,
+        last_activity: 'POISON ACTIVITY — local read leaked into remote attach chrome',
+    }));
+}
+test('buildCanvasPanelLines suppresses every local-read adornment for a RemoteCanvasSource, even with conflicting local state for the same node id', async (t) => {
+    seedPoisonedLocalState();
+    const rootMeta = meta('root');
+    const aMeta = meta('a'); // the REMOTE node's meta — unrelated to the poisoned local NodeMeta above
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            const id = args[4];
+            if (id === 'root')
+                return { body: show(rootMeta, ['a'], []) };
+            if (id === 'a')
+                return { body: show(aMeta, [], ['root']) };
+        }
+        return { status: 500, body: {} };
+    });
+    // Register the close BEFORE any assertion runs — a listening server left
+    // open by a thrown assertion keeps this test file's process alive forever
+    // (see the CI-hang postmortem on rebuild-coalescer.test.ts).
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // The roster excludes the attached root because it is already identified by
+    // the editor, leaving its one live child 'a'. The poisoned local node id is
+    // 'a', so the load-bearing assertions target that rendered row.
+    const { reports, reportIds } = await buildCanvasPanelLines('root', {}, IDENTITY_PALETTE, source);
+    assert.deepEqual(reportIds, ['a'], 'roster omits the node already open in the editor');
+    assert.equal(reports.length, 1);
+    const line = reports[0];
+    assert.ok(!line.includes('1000k'), `local telemetry (999999 tokens) must not leak into a remote row: ${line}`);
+    assert.ok(!line.includes('POISON'), `poisoned local text must never appear in a remote row: ${line}`);
+    assert.ok(!line.includes('⚠'), `a local active fault must not surface as the hanging glyph on a remote row: ${line}`);
+    // A child's parent remains in the below-editor roster with an ↑ prefix, which
+    // distinguishes it from the ↓ rows for reports.
+    const childPanels = await buildCanvasPanelLines('a', {}, IDENTITY_PALETTE, source);
+    assert.deepEqual(childPanels.reportIds, ['root']);
+    assert.equal(childPanels.reports.length, 1);
+    assert.match(childPanels.reports[0], /↑.*root/);
+    assert.match(reports[0], /↓.*a/);
+});
+test('GraphOverlay suppresses every local-read adornment for a RemoteCanvasSource AND makes Enter/m/x no-ops, even with conflicting local state for the same node id', async (t) => {
+    seedPoisonedLocalState();
+    const rootMeta = meta('root');
+    const aMeta = meta('a');
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            const id = args[4];
+            if (id === 'root')
+                return { body: show(rootMeta, ['a'], []) };
+            if (id === 'a')
+                return { body: show(aMeta, [], ['root']) };
+        }
+        return { status: 500, body: {} };
+    });
+    // Register the close BEFORE any assertion runs — see the note above.
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const { tui } = fakeTui();
+    const overlay = new GraphOverlay(tui, 'root', () => ({}), IDENTITY_PALETTE, resolveKeybindings(), source);
+    overlay.open();
+    // buildSnapshot() is async (chased through the mock server); poll for it to land.
+    for (let i = 0; i < 100 && overlay.snapshot === undefined; i++) {
+        await new Promise((r) => setImmediate(r));
+    }
+    assert.notEqual(overlay.snapshot, undefined, 'snapshot never built');
+    const lines = overlay.render(100).join('\n');
+    assert.ok(!lines.includes('1000k'), `local telemetry must not leak into the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes('POISON'), `poisoned local text must never appear in the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes('⚠'), `a local active fault must not surface as the hanging glyph in the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes(BG_ATTACHED), `a local focus/attach must not paint a remote row as attached in the graph overlay: ${lines}`);
+    // Footer hint must drop the focus/kill/mgr hints in remote mode.
+    assert.ok(!lines.includes('kill'), `remote overlay footer must not advertise kill: ${lines}`);
+    assert.ok(!lines.includes('focus') && !lines.includes('mgr'), `remote overlay footer must not advertise focus/mgr: ${lines}`);
+    // Enter must NOT close the overlay (a local `close()` is the observable
+    // effect of a real `focusTarget` dispatch) — it must no-op instead.
+    overlay.handleInput('\r');
+    assert.equal(overlay.isOpen(), true, 'Enter must not act (close) on a remote graph row');
+    // x must NOT arm the close confirm on a remote row. The confirmation UI never
+    // literally contains legacy `y/n`, so assert the real state directly:
+    // pendingConfirm stays unset and no `kill …?` accept/cancel prompt renders.
+    overlay.handleInput('x');
+    assert.equal(overlay.pendingConfirm, undefined, 'x must not arm pendingConfirm on a remote graph row');
+    const afterX = overlay.render(100).join('\n');
+    assert.ok(!afterX.includes('kill'), `x must not surface a kill confirm prompt on a remote graph row: ${afterX}`);
+    assert.ok(!/accept|cancel/.test(afterX), `x must not surface an accept/cancel confirm on a remote graph row: ${afterX}`);
+    // m must NOT close the overlay either (it would focusTarget the manager).
+    overlay.handleInput('m');
+    assert.equal(overlay.isOpen(), true, 'm must not act (close) on a remote graph row');
+});
+// ---------------------------------------------------------------------------
+// Phase 3 review 2 — the ENCLOSING attach viewer (slash commands, pane tag,
+// detach-reap, Alt+Shift+P mode-switch), not just the GraphOverlay/panel rendering
+// the fix above already covers. Same adversarial shape: seed colliding LOCAL
+// state for the remote node id `a`, then assert the remote path never touches
+// it — and, symmetrically, that the LOCAL path is byte-for-byte unchanged
+// (every guard below defaults to acting exactly as before when `remote` is
+// `false`).
+// ---------------------------------------------------------------------------
+function fakeSlashContext(remote, nodeId) {
+    const notices = [];
+    const sent = [];
+    const ctx = {
+        send: (frame) => sent.push(frame),
+        notify: (m) => notices.push(m),
+        cwd: '/tmp/does-not-matter',
+        // Explicit empty string (not `undefined`) so promoteNode/openContext's
+        // `ctx.nodeId ?? process.env['CRTR_NODE_ID']` fallback can NEVER pick up
+        // this test process's own real CRTR_NODE_ID (this test runs INSIDE a live
+        // crtr node) — the local-mode assertions below must reach the real
+        // no-node-id early return, never an accidental real `crtr node promote`
+        // against ourselves.
+        nodeId: '',
+        remote,
+    };
+    return { ctx, notices, sent };
+}
+test('slash autocomplete structurally omits the local-only native canvas commands (/promote, /resume-node, /context) in remote mode, and keeps them in local mode', () => {
+    const remoteNames = slashCommandList(undefined, true).map((c) => c.name);
+    assert.ok(!remoteNames.includes('promote'), `remote autocomplete must not offer /promote: ${remoteNames.join(',')}`);
+    assert.ok(!remoteNames.includes('resume-node'), `remote autocomplete must not offer /resume-node: ${remoteNames.join(',')}`);
+    assert.ok(!remoteNames.includes('context'), `remote autocomplete must not offer /context: ${remoteNames.join(',')}`);
+    // Remote-safe canvas commands stay offered.
+    assert.ok(remoteNames.includes('graph'), 'remote autocomplete must still offer /graph (already remote-safe)');
+    assert.ok(remoteNames.includes('view'), 'remote autocomplete must still offer /view (self-contained popup)');
+    // Local (remote=false, the default) is unchanged — all five canvas commands.
+    const localNames = slashCommandList().map((c) => c.name);
+    for (const name of ['graph', 'promote', 'resume-node', 'view', 'context']) {
+        assert.ok(localNames.includes(name), `local autocomplete must still offer /${name}: ${localNames.join(',')}`);
+    }
+});
+test('dispatchSlashCommand no-ops /promote, /resume-node, /context in remote mode instead of shelling a local crtr command', () => {
+    const { ctx, notices, sent } = fakeSlashContext(true, 'a');
+    for (const cmd of ['/promote', '/resume-node', '/context', '/promote orchestrator']) {
+        notices.length = 0;
+        const handled = dispatchSlashCommand(cmd, ctx);
+        assert.equal(handled, true, `${cmd} must be handled (native, never forwarded to the engine as a prompt)`);
+        assert.equal(notices.length, 1, `${cmd} must notify exactly once (the remote-unsafe notice), got: ${JSON.stringify(notices)}`);
+        assert.match(notices[0], /not available for a remote attach/, `${cmd} must notify the remote-unsafe message, not proceed into its local handler: ${notices[0]}`);
+    }
+    assert.equal(sent.length, 0, 'no command frame must ever be sent for a gated remote canvas command');
+    // /graph and /view are UNaffected by the remote gate (graph is already
+    // remote-safe via GraphOverlay's own `remote` handling; view is self-
+    // contained). Neither reaches the remote-unsafe notice.
+    notices.length = 0;
+    ctx.onGraph = () => notices.push('graph-toggled');
+    dispatchSlashCommand('/graph', ctx);
+    assert.deepEqual(notices, ['graph-toggled'], '/graph must still work normally in remote mode');
+});
+test('dispatchSlashCommand leaves the LOCAL (non-remote) path for /promote, /resume-node, /context byte-for-byte unchanged', () => {
+    const { ctx, notices } = fakeSlashContext(false, '');
+    // No TMUX in this test process (a headless `node --test` run), so
+    // /resume-node and /context hit their OWN "needs tmux" notices — proving
+    // dispatch reached their real local handlers, not our new remote gate.
+    const savedTmux = process.env['TMUX'];
+    const savedTmuxPane = process.env['TMUX_PANE'];
+    delete process.env['TMUX'];
+    delete process.env['TMUX_PANE'];
+    try {
+        notices.length = 0;
+        dispatchSlashCommand('/promote', ctx);
+        assert.deepEqual(notices, ['/promote: no node to promote (viewer has no node id)']);
+        notices.length = 0;
+        dispatchSlashCommand('/resume-node', ctx);
+        assert.deepEqual(notices, ['/resume-node needs tmux']);
+        notices.length = 0;
+        dispatchSlashCommand('/context', ctx);
+        assert.deepEqual(notices, ['/context needs tmux']);
+    }
+    finally {
+        if (savedTmux !== undefined)
+            process.env['TMUX'] = savedTmux;
+        else
+            delete process.env['TMUX'];
+        if (savedTmuxPane !== undefined)
+            process.env['TMUX_PANE'] = savedTmuxPane;
+        else
+            delete process.env['TMUX_PANE'];
+    }
+});
+test('resolveInitialMode/requestModeSwitch never touch the local mode-switch read/write for a remote attach, and are unchanged for local', () => {
+    let reads = 0;
+    const readMode = (_cwd, _nodeId) => {
+        reads++;
+        return 'plan'; // poisoned value — must never surface for remote
+    };
+    assert.equal(resolveInitialMode('/tmp/cwd', 'a', true, readMode), 'normal', 'remote must always start normal');
+    assert.equal(reads, 0, 'remote must never read the local mode-switch current file');
+    assert.equal(resolveInitialMode('/tmp/cwd', 'a', false, readMode), 'plan', 'local must read through unchanged');
+    assert.equal(reads, 1, 'local must call the injected local reader exactly once');
+    let writes = 0;
+    let lastWrite;
+    const writeRequest = (cwd, nodeId, mode) => {
+        writes++;
+        lastWrite = { cwd, nodeId, mode };
+    };
+    const remoteOk = requestModeSwitch('/tmp/cwd', 'a', true, 'spec', writeRequest);
+    assert.equal(remoteOk, false, 'remote Alt+Shift+P must no-op (return false)');
+    assert.equal(writes, 0, 'remote must never write the local mode-switch request file');
+    const localOk = requestModeSwitch('/tmp/cwd', 'a', false, 'spec', writeRequest);
+    assert.equal(localOk, true, 'local Alt+Shift+P must still write through');
+    assert.equal(writes, 1, 'local must call the injected local writer exactly once');
+    assert.deepEqual(lastWrite, { cwd: '/tmp/cwd', nodeId: 'a', mode: 'spec' });
+});
+test('tagAttachPane/untagAttachPane never tag/untag the pane for a remote attach, and are unchanged for local', () => {
+    let calls = [];
+    const setOpt = (pane, name, value) => {
+        calls.push([pane, name, value]);
+    };
+    calls = [];
+    tagAttachPane(true, '%3', 'a', setOpt);
+    assert.deepEqual(calls, [], 'remote must never tag the pane with @crtr_node');
+    calls = [];
+    tagAttachPane(false, '%3', 'a', setOpt);
+    assert.deepEqual(calls, [['%3', '@crtr_node', 'a']], 'local tag must still fire unchanged');
+    calls = [];
+    untagAttachPane(true, '%3', setOpt);
+    assert.deepEqual(calls, [], 'remote must never untag the pane');
+    calls = [];
+    untagAttachPane(false, '%3', setOpt);
+    assert.deepEqual(calls, [['%3', '@crtr_node', '']], 'local untag must still fire unchanged');
+    // No pane resolved (outside tmux) — unaffected either way.
+    calls = [];
+    tagAttachPane(false, undefined, 'a', setOpt);
+    assert.deepEqual(calls, [], 'no pane to tag when outside tmux');
+});
+// ---------------------------------------------------------------------------
+// T3 — memory-ref inventory lifecycle/race (design: inline memory references,
+// terminal integration) and the input-layer whitespace-preservation contract.
+// ---------------------------------------------------------------------------
+test('createMemoryRefRefreshCoordinator: a stale reply from a superseded reset cannot overwrite a newer inventory, and malformed/rejected replies degrade to empty without throwing', async () => {
+    const snapshots = [];
+    const engineNameSnapshots = [];
+    const setMemoryRefs = (refs, engineLeadingCommandNames) => {
+        snapshots.push(refs);
+        engineNameSnapshots.push(engineLeadingCommandNames);
+    };
+    const pending = [];
+    const request = () => new Promise((resolve, reject) => { pending.push({ resolve, reject }); });
+    const coordinator = createMemoryRefRefreshCoordinator(setMemoryRefs, request);
+    const flush = async () => { await Promise.resolve(); await Promise.resolve(); };
+    // First reset (e.g. the initial welcome) — clears synchronously, then waits
+    // on its correlated request.
+    coordinator.reset();
+    assert.deepEqual(snapshots, [[]], 'first reset clears the inventory immediately');
+    assert.deepEqual(engineNameSnapshots, [[]], 'the engine-command inventory clears alongside refs, synchronously');
+    const firstRequest = pending[0];
+    // A second reset — a reconnect's fresh welcome, or an explicit /reload —
+    // supersedes it BEFORE the first reply lands: clears again and issues its
+    // own request.
+    coordinator.reset();
+    assert.deepEqual(snapshots, [[], []], 'a superseding reset clears the inventory again immediately');
+    const secondRequest = pending[1];
+    // The SECOND (latest) request resolves first — its refs AND engine-command
+    // names must both be installed (Major 6 — broker's `engineLeadingCommandNames`
+    // propagates through the coordinator alongside `refs`, not just `refs` alone).
+    const latestRefs = [{ name: 'dev', kind: 'knowledge', scope: 'project', shortForm: 'dev docs' }];
+    const latestEngineNames = ['reload'];
+    secondRequest.resolve({
+        type: 'data',
+        id: 'latest',
+        kind: 'list_memory_refs',
+        refs: latestRefs,
+        engineLeadingCommandNames: latestEngineNames,
+    });
+    await flush();
+    assert.deepEqual(snapshots.at(-1), latestRefs, 'the latest reset\'s reply installs its refs');
+    assert.deepEqual(engineNameSnapshots.at(-1), latestEngineNames, 'the latest reset\'s reply installs its engine-command names');
+    // The FIRST (now-stale) request's reply arrives late — it must be dropped,
+    // never overwriting the newer inventory the second reset already installed.
+    const staleRefs = [{ name: 'stale', kind: 'knowledge', scope: 'project', shortForm: 'stale' }];
+    firstRequest.resolve({ type: 'data', id: 'stale', kind: 'list_memory_refs', refs: staleRefs, engineLeadingCommandNames: ['stale-cmd'] });
+    await flush();
+    assert.equal(snapshots.length, 3, 'a stale reply from a superseded reset must never install refs');
+    assert.deepEqual(snapshots.at(-1), latestRefs, 'the newer inventory must survive a late stale reply');
+    assert.deepEqual(engineNameSnapshots.at(-1), latestEngineNames, 'the newer engine-command inventory must survive a late stale reply too');
+    // A malformed reply (wrong `kind`) degrades to the already-empty inventory.
+    coordinator.reset();
+    const thirdRequest = pending[2];
+    thirdRequest.resolve({ type: 'data', id: 'malformed', kind: 'dequeue', steering: [], followUp: [] });
+    await flush();
+    assert.deepEqual(snapshots.at(-1), [], 'a malformed-kind reply must never install refs');
+    assert.deepEqual(engineNameSnapshots.at(-1), [], 'a malformed-kind reply must never install engine-command names');
+    // A rejected request (timeout) degrades silently too — no retry, no throw.
+    coordinator.reset();
+    const fourthRequest = pending[3];
+    fourthRequest.reject(new Error('request timed out'));
+    await flush();
+    assert.deepEqual(snapshots.at(-1), [], 'a rejected request must never throw and must stay empty');
+    assert.deepEqual(engineNameSnapshots.at(-1), [], 'a rejected request must never throw and engine-command names must stay empty');
+});
+test('InputController.handleSubmit sends the prompt frame with the exact typed leading/trailing whitespace, even though emptiness/slash classification uses a trimmed view', () => {
+    const sent = [];
+    const fakeEditor = {
+        onSubmit: undefined,
+        onEscape: undefined,
+        onPasteImage: undefined,
+        onPasteImagePath: undefined,
+        onAction: () => { },
+        addToHistory: () => { },
+        setText: () => { },
+        getText: () => '',
+        insertTextAtCursor: () => { },
+    };
+    new InputController({}, fakeEditor, { matches: () => false }, { onCommand: (frame) => sent.push(frame), onDialogResponse: () => { } });
+    fakeEditor.onSubmit('  hello world  ');
+    assert.deepEqual(sent, [{ type: 'prompt', text: '  hello world  ' }], 'the sent prompt frame must keep the human\'s exact leading/trailing whitespace');
+    // Emptiness classification reads the TRIMMED view — whitespace-only input
+    // must never submit a frame.
+    sent.length = 0;
+    fakeEditor.onSubmit('   \n  ');
+    assert.deepEqual(sent, [], 'a whitespace-only submit must not send a frame');
+});

package/dist/clients/attach/__tests__/attach-keybindings.test.d.ts

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

package/dist/clients/attach/__tests__/attach-keybindings.test.js

@@ -0,0 +1,141 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveKeybindings } from '../../../core/keybindings/index.js';
+import { detachHint, inboxOpenHint, dispatchAttachBinding, matchesAttachBinding, refreshAttachBindingSnapshot, } from '../session/bindings.js';
+import { GraphOverlay } from '../overlays/graph.js';
+const PALETTE = {
+    accent: (s) => s,
+    active: (s) => s,
+    info: (s) => s,
+    muted: (s) => s,
+    faint: (s) => s,
+    border: (s) => s,
+    bold: (s) => s,
+    error: (s) => s,
+    warning: (s) => s,
+    bashMode: (s) => s,
+    bashModeAlt: (s) => s,
+    surface: (s) => s,
+};
+function fakeTui() {
+    return {
+        showOverlay: () => ({ hide: () => { } }),
+        requestRender: () => { },
+    };
+}
+test('attach input dispatches only the current configured action', () => {
+    const bindings = resolveKeybindings({
+        'crtr.attach.detach': ['ctrl+x'],
+        'crtr.attach.clear-or-detach': [],
+        'crtr.attach.graph.toggle': [],
+        'crtr.mode.cycle': ['alt+x'],
+        'crtr.attach.model-ladder.next': ['alt+z'],
+        'crtr.attach.model-ladder.previous': ['alt+y'],
+        'crtr.attach.command.inspect': ['alt+shift+h'],
+        'crtr.attach.file-review': [],
+    });
+    const calls = [];
+    const actions = {
+        'crtr.attach.detach': () => calls.push('detach'),
+        'crtr.attach.clear-or-detach': () => calls.push('clear'),
+        'crtr.attach.graph.toggle': () => calls.push('graph'),
+        'crtr.mode.cycle': () => calls.push('mode'),
+        'crtr.attach.model-ladder.next': () => calls.push('ladder'),
+        'crtr.attach.model-ladder.previous': () => calls.push('ladder-back'),
+        'crtr.attach.command.inspect': () => calls.push('inspect'),
+        'crtr.attach.file-review': () => calls.push('review'),
+    };
+    assert.equal(dispatchAttachBinding(bindings, '\x18', actions), true);
+    assert.equal(dispatchAttachBinding(bindings, '\x04', actions), false, 'old detach must not reach the listener action');
+    assert.equal(dispatchAttachBinding(bindings, '\x1bg', actions), false, 'disabled graph must not reach the listener action');
+    assert.equal(dispatchAttachBinding(bindings, '\x1bx', actions), true);
+    assert.equal(dispatchAttachBinding(bindings, '\x1bP', actions), false, 'old mode key must not reach the listener action');
+    assert.equal(dispatchAttachBinding(bindings, '\x1bz', actions), true);
+    assert.equal(dispatchAttachBinding(bindings, '\x1bm', actions), false, 'old ladder key must not reach the listener action');
+    assert.equal(dispatchAttachBinding(bindings, '\x1by', actions), true);
+    assert.equal(dispatchAttachBinding(bindings, '\x1bM', actions), false, 'old ladder-back key must not reach the listener action');
+    assert.equal(dispatchAttachBinding(bindings, '\x1b[72;4u', actions), true);
+    assert.deepEqual(calls, ['detach', 'mode', 'ladder', 'ladder-back', 'inspect']);
+    assert.equal(detachHint(bindings), 'Ctrl+X', 'disabled clear-or-detach must fall back to enabled detach');
+    const noDetach = resolveKeybindings({ 'crtr.attach.detach': [], 'crtr.attach.clear-or-detach': [] });
+    assert.equal(detachHint(noDetach), undefined, 'a disabled pair must not render "Disabled to detach"');
+});
+test('closed-inbox footer hint resolves the configured inbox shortcut(s)', () => {
+    // Default: alt+i renders as the configured shortcut plus 'inbox'.
+    assert.equal(inboxOpenHint(resolveKeybindings()), 'Alt+I inbox');
+    // Custom single key.
+    assert.equal(inboxOpenHint(resolveKeybindings({ 'crtr.tmux.inbox.toggle': ['alt+j'] })), 'Alt+J inbox');
+    // Multiple gestures join with ' / ' (crouter's formatBinding convention).
+    assert.equal(inboxOpenHint(resolveKeybindings({ 'crtr.tmux.inbox.toggle': ['alt+i', 'alt+j'] })), 'Alt+I / Alt+J inbox');
+    // Disabled: omit the shortcut clause and fall back to the CLI affordance,
+    // never render the word "Disabled".
+    const disabled = inboxOpenHint(resolveKeybindings({ 'crtr.tmux.inbox.toggle': [] }));
+    assert.equal(disabled, 'hl inbox open');
+    assert.doesNotMatch(disabled, /Disabled/);
+});
+test('attach startup and reload replace the dispatch/GRAPH snapshots and install each tmux snapshot', () => {
+    const first = resolveKeybindings({ 'crtr.attach.detach': ['ctrl+x'], 'crtr.graph.focus': ['f'] });
+    const second = resolveKeybindings({
+        'crtr.attach.detach': ['ctrl+z'],
+        'crtr.graph.focus': ['r'],
+        'crtr.graph.revive': [],
+    });
+    const snapshots = [first, second];
+    const graphSnapshots = [];
+    const installed = [];
+    let active = refreshAttachBindingSnapshot(() => snapshots.shift(), (bindings) => graphSnapshots.push(bindings), () => true, (bindings) => installed.push(bindings));
+    assert.equal(matchesAttachBinding(active, 'crtr.attach.detach', '\x18'), true, 'startup snapshot drives attach dispatch');
+    assert.equal(active.gestures('crtr.graph.focus')[0], 'f', 'startup snapshot reaches GRAPH');
+    active = refreshAttachBindingSnapshot(() => snapshots.shift(), (bindings) => graphSnapshots.push(bindings), () => true, (bindings) => installed.push(bindings));
+    assert.equal(matchesAttachBinding(active, 'crtr.attach.detach', '\x18'), false, 'reload replaces the old attach snapshot');
+    assert.equal(matchesAttachBinding(active, 'crtr.attach.detach', '\x1a'), true, 'reload dispatches through the new attach snapshot');
+    assert.equal(active.gestures('crtr.graph.focus')[0], 'r', 'reload replaces GRAPH bindings too');
+    assert.deepEqual(graphSnapshots, [first, second]);
+    assert.deepEqual(installed, [first, second], 'the unified tmux installer receives startup and reload snapshots');
+});
+test('GRAPH navigation and hints use effective bindings rather than default literals', () => {
+    const bindings = resolveKeybindings({
+        'crtr.graph.down': ['z'],
+        'crtr.graph.up': [],
+        'crtr.graph.focus': ['f'],
+        'crtr.graph.close-subtree': [],
+        'crtr.graph.dismiss': ['q'],
+        'crtr.graph.confirm.accept': ['t'],
+        'crtr.graph.confirm.cancel': ['c'],
+    });
+    const overlay = new GraphOverlay(fakeTui(), 'a', () => ({}), PALETTE, bindings, {});
+    const internal = overlay;
+    internal.cursorId = 'a';
+    internal.snapshot = {
+        rows: [
+            { id: 'a', hasKids: false, isSelf: true, branch: '', cycle: false, collapsed: false },
+            { id: 'b', hasKids: false, isSelf: false, branch: '', cycle: false, collapsed: false },
+        ],
+        activeBelow: new Map(),
+        nodes: new Map([['a', null], ['b', null]]),
+        childIds: new Map(),
+        sortedChildIds: new Map(),
+        managerOf: new Map(),
+        focused: new Set(),
+    };
+    overlay.handleInput('j');
+    assert.equal(internal.cursorId, 'a', 'replaced default must stop matching');
+    overlay.handleInput('z');
+    assert.equal(internal.cursorId, 'b', 'replacement must drive navigation');
+    const rendered = overlay.render(58).join('\n');
+    // Bare printable keys render exactly as they must be typed (lowercase),
+    // never uppercased into a shift chord the matcher would reject.
+    assert.match(rendered, /f focus/, 'narrow GRAPH footer must prioritize remapped local focus');
+    assert.match(rendered, /q dismiss/, 'narrow GRAPH footer must prioritize remapped dismiss');
+    assert.doesNotMatch(rendered, /close/);
+    assert.doesNotMatch(rendered, /j down/);
+    assert.doesNotMatch(rendered, /Disabled/);
+    let closed = 0;
+    internal.pendingConfirm = { label: 'close b?', action: () => { closed++; } };
+    assert.match(overlay.render(80).join('\n'), /t accept · c cancel/);
+    overlay.handleInput('y');
+    assert.equal(closed, 0, 'replaced accept default must stop confirming');
+    internal.pendingConfirm = { label: 'close b?', action: () => { closed++; } };
+    overlay.handleInput('t');
+    assert.equal(closed, 1, 'replacement must confirm close');
+});

package/dist/clients/attach/__tests__/attach-remote-readonly.test.d.ts

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