@crouton-kit/crouter 0.3.66 → 0.3.68

package/dist/build-root.js

@@ -11,6 +11,7 @@ const SUBTREE_LOADERS = {
     memory: async () => (await import('./commands/memory.js')).registerMemory(),
     profile: async () => (await import('./commands/profile.js')).registerProfile(),
     search: async () => (await import('./commands/search.js')).registerSearch(),
+    capture: async () => (await import('./commands/capture.js')).registerCapture(),
     pkg: async () => (await import('./commands/pkg.js')).registerPkg(),
     human: async () => (await import('./commands/human.js')).registerHuman(),
     sys: async () => (await import('./commands/sys.js')).registerSys(),

package/dist/builtin-memory/05-kinds/developer/00-base.md

@@ -17,4 +17,4 @@ You are an implementation agent. Your job is to **implement this feature or chan
 
 Work directly. Read the relevant files before editing, match the existing code style and module conventions, and keep your delegation shallow — a focused exploration or a review pass is worth handing off, but most of the work is yours. Throw errors early; no silent fallbacks. Break things correctly rather than patching them badly; prefer clean, breaking changes over backwards-compat hacks in pre-production code.
 
-Done means **provably correct against the spec's acceptance criteria** — not "it builds," not "the tests pass." Green output proves the code ran, not that it does what was asked; check the result against each acceptance criterion yourself. On a load-bearing change, get it critiqued by something other than you before calling it done — spawn a reviewer on the diff and fold in what it finds. And if the change outgrows what one window can finish well — many files, several phases, a design that keeps moving — promote yourself into a developer orchestrator and decompose it rather than grinding past the edge of your context.
+Done means **provably correct against the spec's acceptance criteria** — not "it builds," not "the tests pass." Green output proves the code ran, not that it does what was asked; check the result against each acceptance criterion yourself. On a load-bearing change, get it critiqued by something other than you before calling it done — spawn a reviewer on the diff and fold in what it finds. But validate judiciously: a delegate's green report is settled evidence — don't re-run a suite or re-read a diff that already cleared its gate; check only what changed since. And if the change outgrows what one window can finish well — many files, several phases, a design that keeps moving — promote yourself into a developer orchestrator and decompose it rather than grinding past the edge of your context.

package/dist/builtin-memory/05-kinds/developer/01-orchestrator.md

@@ -12,4 +12,6 @@ Before you shape the roadmap, read `crtr memory read development` for the roadma
 
 Stay flexible, not waterfall. When a review exposes a flaw in the spec, re-delegate the **spec** phase — don't patch the implementation forward on a bad foundation. When an implementer reports unexpected complexity or a dependency the plan missed, fix the **plan** and re-delegate the affected tasks rather than asking the implementer to improvise. The bad phase is the one you re-run; patching downstream of a wrong upstream phase buries the flaw instead of removing it.
 
+Validate judiciously — trust the agent. A gate that already ran green is settled evidence: when a child reports its build clean, its suite passing, or a reviewer reports the diff read, take the report and move on — do not re-run the same suite, rebuild the same tree, or re-read the same code to reassure yourself. Attach each new check to what *changed* since the last green gate (the fix diff, the new tests), never the whole feature from scratch; re-verify a report only when it is internally inconsistent or contradicted by evidence, not on general suspicion. Redundant re-validation burns whole windows and adds no information — the second identical green proves nothing the first didn't.
+
 Post-implementation review is not one generic "review this" pass — it is several distinct perspectives, each its own assessment: does this **reuse** what the codebase already provides rather than reinventing it, is the **quality** sound, is it **efficient**, and are the **tests** real rather than green theatre. Hand each lens to its own reviewer so it assesses independently. Size the reviewer to the surface: a small focused diff goes to a single `review` worker; a whole feature's worth of files goes to a `review` orchestrator that fans the lenses across it and returns one verdict.

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

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

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

@@ -0,0 +1,371 @@
+// 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 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 { dispatchSlashCommand, slashCommandList } from '../slash-commands.js';
+import { resolveInitialMode, requestModeSwitch, tagAttachPane, untagAttachPane, reapOnDetach, } from '../attach-cmd.js';
+import { buildCanvasPanelLines } from '../canvas-panels.js';
+import { GraphOverlay } from '../graph-overlay.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_triggers: 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 () => {
+    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: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // 'root' has 'a' as a live report → row('a') renders into `reports`.
+    const { reports } = await buildCanvasPanelLines('root', {}, IDENTITY_PALETTE, source);
+    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}`);
+    assert.ok(!line.includes(BG_ATTACHED), `a local focus/attach must not paint a remote row as attached: ${line}`);
+    await server.close();
+});
+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 () => {
+    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: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const { tui } = fakeTui();
+    const overlay = new GraphOverlay(tui, 'root', () => ({}), IDENTITY_PALETTE, 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 y/n kill confirm — render() would show it in the hint.
+    overlay.handleInput('x');
+    const afterX = overlay.render(100).join('\n');
+    assert.ok(!afterX.includes('y/n'), `x must not arm a kill 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');
+    await server.close();
+});
+// ---------------------------------------------------------------------------
+// Phase 3 review 2 — the ENCLOSING attach viewer (slash commands, pane tag,
+// detach-reap, Alt+M 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+M 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+M 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');
+});
+test('reapOnDetach never reaps a local node for a remote attach even on an id collision, and is unchanged for local', () => {
+    let reaped = [];
+    const reap = (nodeId) => {
+        reaped.push(nodeId);
+    };
+    reaped = [];
+    reapOnDetach(true, 'a', reap);
+    assert.deepEqual(reaped, [], 'remote detach must never reap a local node, even one colliding with the remote id');
+    reaped = [];
+    reapOnDetach(false, 'a', reap);
+    assert.deepEqual(reaped, ['a'], 'local detach-reap must still fire unchanged');
+});

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

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

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

@@ -0,0 +1,191 @@
+// attach-remote-readonly.test.ts — Phase 3 review Major 1: a REMOTE attach
+// (`crtr surface attach --canvas <name>`) must be a strictly VIEW-ONLY
+// surface. Three defenses are proven independently here:
+//
+//   A. slash-commands.ts's REMOTE_SAFE_BUILTIN_NAMES gate — a remote attach
+//      never even dispatches a mutating builtin slash command.
+//   B. input-controller.ts's central `emitCommand` choke point — even if a
+//      caller somehow got past A, the REAL InputController (constructed
+//      against fakes, not stubbed out) never lets a drive frame reach
+//      `hooks.onCommand`, for every input path (submit, `!bash`, Esc-abort,
+//      and every direct keybinding).
+//   C. attach-cmd.ts's `resolveHelloRole` — the hello handshake always
+//      claims 'observer' for a remote attach, regardless of `--observer`.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { dispatchSlashCommand } from '../slash-commands.js';
+import { InputController } from '../input-controller.js';
+import { resolveHelloRole } from '../attach-cmd.js';
+// ---------------------------------------------------------------------------
+// Half A — slash-command gate
+// ---------------------------------------------------------------------------
+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',
+        nodeId,
+        remote,
+    };
+    return { ctx, notices, sent };
+}
+const MUTATING_BUILTINS = [
+    '/new', '/compact', '/name test', '/model', '/resume', '/fork', '/tree',
+    '/settings', '/share', '/clone', '/import', '/reload', '/scoped-models',
+    '/login', '/logout', '/export',
+];
+test('dispatchSlashCommand blocks every mutating/wrong-host builtin in remote mode, never sending a frame', () => {
+    const { ctx, notices, sent } = fakeSlashContext(true, 'a');
+    for (const cmd of MUTATING_BUILTINS) {
+        notices.length = 0;
+        const handled = dispatchSlashCommand(cmd, ctx);
+        assert.equal(handled, true, `${cmd} must be handled (blocked, never forwarded to the engine as a prompt)`);
+        assert.equal(notices.length, 1, `${cmd} must notify exactly once, got: ${JSON.stringify(notices)}`);
+        assert.match(notices[0], /not available for a remote attach/, `${cmd} must produce the remote-block notice, got: ${notices[0]}`);
+    }
+    assert.equal(sent.length, 0, 'no command frame must ever reach ctx.send for a blocked remote builtin');
+});
+test('the same builtins dispatch normally in local mode (remote unaffected proof)', () => {
+    const { ctx, sent } = fakeSlashContext(false, '');
+    assert.equal(dispatchSlashCommand('/name a-new-name', ctx), true);
+    assert.equal(dispatchSlashCommand('/new', ctx), true);
+    const types = sent.map((f) => f.type);
+    assert.ok(types.includes('set_session_name'), `expected set_session_name in local mode, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('new_session'), `expected new_session in local mode, got ${JSON.stringify(types)}`);
+});
+test('/copy /session /changelog /hotkeys /quit remain reachable in remote mode (not blocked by the gate)', () => {
+    const { ctx, notices } = fakeSlashContext(true, 'a');
+    notices.length = 0;
+    ctx.state = { model: 'test-model' };
+    dispatchSlashCommand('/session', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]), `/session must not hit the remote-block notice, got: ${notices[0]}`);
+    notices.length = 0;
+    dispatchSlashCommand('/changelog', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]));
+    notices.length = 0;
+    dispatchSlashCommand('/hotkeys', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]));
+    notices.length = 0;
+    let copied = false;
+    ctx.onCopy = () => { copied = true; };
+    dispatchSlashCommand('/copy', ctx);
+    assert.equal(copied, true, '/copy must reach its onCopy hook in remote mode');
+    notices.length = 0;
+    let quit = false;
+    ctx.onQuit = () => { quit = true; };
+    dispatchSlashCommand('/quit', ctx);
+    assert.equal(quit, true, '/quit must reach its onQuit hook in remote mode');
+});
+// ---------------------------------------------------------------------------
+// Half B — InputController's central emitCommand gate, against a REAL
+// InputController built from minimal fakes.
+// ---------------------------------------------------------------------------
+function fakeEditor() {
+    const actions = new Map();
+    let text = '';
+    const history = [];
+    const obj = {
+        onSubmit: undefined,
+        onEscape: undefined,
+        onPasteImage: undefined,
+        onAction: (name, cb) => { actions.set(name, cb); },
+        getText: () => text,
+        setText: (t) => { text = t; },
+        addToHistory: (t) => { history.push(t); },
+        insertTextAtCursor: (t) => { text += t; },
+    };
+    return { obj, actions, setText: (t) => { text = t; } };
+}
+function fakeTui() {
+    return {
+        requestRender: () => { },
+        setFocus: () => { },
+        showOverlay: () => ({ hide: () => { } }),
+        start: () => { },
+        stop: () => { },
+    };
+}
+function buildController(remote) {
+    const sent = [];
+    const notices = [];
+    const editor = fakeEditor();
+    const tui = fakeTui();
+    const ic = new InputController(tui, editor.obj, {}, {
+        onCommand: (f) => sent.push(f),
+        onDialogResponse: () => { },
+        onNotice: (m) => notices.push(m),
+        remote,
+    });
+    return { ic, editor, sent, notices };
+}
+test('InputController never emits a drive frame to onCommand when remote is true — every input path', () => {
+    const { ic, editor, sent, notices } = buildController(true);
+    // 1. Text submission → would have been `prompt`.
+    editor.setText('');
+    editor.obj.onSubmit('hello');
+    assert.equal(sent.length, 0);
+    // 2. `!` bash → would have been `bash`.
+    editor.setText('');
+    editor.obj.onSubmit('!ls');
+    assert.equal(sent.length, 0);
+    // 3. Esc while streaming → would have been `abort`.
+    ic.setState({ isStreaming: true });
+    editor.obj.onEscape();
+    assert.equal(sent.length, 0);
+    // 4. Direct keybindings → new_session, cycle_model×2, cycle_thinking.
+    editor.actions.get('app.session.new')();
+    editor.actions.get('app.model.cycleForward')();
+    editor.actions.get('app.model.cycleBackward')();
+    editor.actions.get('app.thinking.cycle')();
+    assert.equal(sent.length, 0, `remote InputController must never emit a frame, got: ${JSON.stringify(sent)}`);
+    // 5. The gate must have actually fired (proves the hooks weren't simply
+    // never wired — a real block happened).
+    assert.ok(notices.some((n) => /Read-only remote attach/.test(n)), `expected a "Read-only remote attach" notice, got: ${JSON.stringify(notices)}`);
+    // 6. `app.message.dequeue` → handleDequeue's own remote guard (a second
+    // frame type, `dequeue`, not covered by the direct-keybinding block above).
+    notices.length = 0;
+    editor.actions.get('app.message.dequeue')();
+    assert.equal(sent.length, 0, `remote dequeue must never emit a frame, got: ${JSON.stringify(sent)}`);
+    assert.ok(notices.some((n) => /Read-only remote attach/.test(n)), `expected a "Read-only remote attach" notice from dequeue, got: ${JSON.stringify(notices)}`);
+});
+test('InputController emits the SAME drive frames normally when remote is false (local unaffected proof)', () => {
+    const { ic, editor, sent, notices } = buildController(false);
+    editor.setText('');
+    editor.obj.onSubmit('hello');
+    editor.setText('');
+    editor.obj.onSubmit('!ls');
+    ic.setState({ isStreaming: true });
+    editor.obj.onEscape();
+    editor.actions.get('app.session.new')();
+    editor.actions.get('app.model.cycleForward')();
+    editor.actions.get('app.model.cycleBackward')();
+    editor.actions.get('app.thinking.cycle')();
+    // `app.message.dequeue` locally never hits the remote guard (it falls
+    // through to the "not available in this viewer" branch since the fake
+    // hooks supply no `onRequest`) — proves handleDequeue's remote check is
+    // remote-conditional, not an unconditional block.
+    notices.length = 0;
+    editor.actions.get('app.message.dequeue')();
+    assert.ok(!notices.some((n) => /Read-only remote attach/.test(n)), `local dequeue must not hit the read-only remote notice, got: ${JSON.stringify(notices)}`);
+    const types = sent.map((f) => f.type);
+    assert.ok(types.includes('prompt'), `expected prompt, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('bash'), `expected bash, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('abort'), `expected abort, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('new_session'), `expected new_session, got ${JSON.stringify(types)}`);
+    assert.equal(types.filter((t) => t === 'cycle_model').length, 2, `expected two cycle_model frames, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('cycle_thinking'), `expected cycle_thinking, got ${JSON.stringify(types)}`);
+});
+// ---------------------------------------------------------------------------
+// Half C — hello role
+// ---------------------------------------------------------------------------
+test('resolveHelloRole always claims observer for remote, regardless of --observer', () => {
+    assert.equal(resolveHelloRole(true, false), 'observer');
+    assert.equal(resolveHelloRole(true, true), 'observer');
+    assert.equal(resolveHelloRole(false, false), 'controller');
+    assert.equal(resolveHelloRole(false, true), 'observer');
+});

package/dist/clients/attach/__tests__/transport-relay.test.js

@@ -7,10 +7,14 @@
 // NOT-gone counterparts), and a non-101 handshake response (bad token) not
 // hanging connect().
 import assert from 'node:assert/strict';
-import test from 'node:test';
+import test, { after, before } from 'node:test';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { WebSocketServer } from 'ws';
 import { RelayTransport } from '../transport-relay.js';
 import { BrokerUnavailableError } from '../transport.js';
+import { jobDir } from '../../../core/canvas/paths.js';
 /** Stand up a bare `ws` server on an ephemeral loopback port — the "relay" a
  *  RelayTransport dials. Records the Authorization header + accepted sockets
  *  of every connection so a test can assert on the wire, not just behavior. */
@@ -153,6 +157,39 @@ test('an immediate post-upgrade 1011 "no node <id>" close is still caught by a l
     transport.destroy();
     await new Promise((res) => wss.close(() => res()));
 });
+// --- Phase 3 review Major 3: RelayTransport must never write LOCAL fault
+// state keyed by a REMOTE node id (it is only ever constructed for --canvas
+// attach; there is no legitimate local use case). ---
+let faultTestHome;
+before(() => {
+    faultTestHome = mkdtempSync(join(tmpdir(), 'crtr-transport-relay-fault-'));
+    process.env['CRTR_HOME'] = faultTestHome;
+});
+after(() => {
+    rmSync(faultTestHome, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('RelayTransport never writes local fault state for the remote node id, even on a connect failure', async () => {
+    const nodeId = 'remote-fault-test-node';
+    const wss = new WebSocketServer({
+        port: 0,
+        verifyClient: (_info, cb) => cb(false, 401, 'unauthorized'),
+    });
+    await new Promise((resolve) => wss.once('listening', resolve));
+    const addr = wss.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const transport = new RelayTransport(nodeId, {
+        previewEndpoint: `http://127.0.0.1:${port}`,
+        relayToken: 'bad-token',
+    });
+    await new Promise((resolve) => {
+        transport.once('error', () => resolve());
+        transport.connect();
+    });
+    assert.equal(existsSync(join(jobDir(nodeId), 'fault')), false, 'a remote relay connect failure must never write a LOCAL fault file keyed by the remote node id');
+    transport.destroy();
+    await new Promise((res) => wss.close(() => res()));
+});
 test('a non-101 handshake response (401, bad token) rejects connect() with a clear error, not a hang', async () => {
     const wss = new WebSocketServer({
         port: 0,