@crouton-kit/crouter 0.3.66 → 0.3.67

package/dist/core/canvas/__tests__/render-remote.test.d.ts

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

package/dist/core/canvas/__tests__/render-remote.test.js

@@ -0,0 +1,221 @@
+// render-remote.test.ts — the safe-defaults contract for `render.ts`'s
+// `*FromSource` functions when given a `RemoteCanvasSource`: every field that
+// would require a local disk/SQLite read (hanging, streaming, viewed, ctx
+// tokens, asks, goal, prompts, lastAssistant) must come back suppressed to
+// its safe default instead of touching this process's local state. Reuses
+// the mock-server harness shape from `remote-canvas-source.test.ts`.
+//
+// This is adversarial, not merely a clean-machine assertion: BEFORE calling
+// the render functions, the test seeds real, CONFLICTING local state for the
+// same node id `a` (a local focus, an active fault, telemetry, a goal file, a
+// session transcript, and a pending human ask) — every historically-broken
+// local read this suppression covers. If the production suppression ever
+// regressed back to consulting local disk/SQLite for a remote source, the
+// assertions below would observe the poisoned values instead of the safe
+// defaults, so a clean-machine run could never mask the regression.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson, deckPath } from '@crouton-kit/humanloop';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
+import { createNode } from '../canvas.js';
+import { closeDb } from '../db.js';
+import { openFocusRow } from '../focuses.js';
+import { jobDir, contextDir } from '../paths.js';
+import { recordFault } from '../../runtime/fault.js';
+import { interactionsRoot } from '../../artifact.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 row(id) {
+    return {
+        node_id: id,
+        name: id,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        cwd: '/tmp/work',
+        host_kind: null,
+        profile_id: null,
+        parent: null,
+        created: new Date().toISOString(),
+        intent: null,
+        pi_pid: null,
+        pi_pid_identity: null,
+        window: null,
+        tmux_session: null,
+        pane: null,
+    };
+}
+let home;
+let localCwd;
+let sessionFile;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-render-remote-'));
+    localCwd = mkdtempSync(join(tmpdir(), 'crtr-render-remote-cwd-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(localCwd), { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(localCwd), { 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
+ *  `*FromSource`'s remote suppression is supposed to bypass. Returns the
+ *  poisoned session-file path so the mocked `node inspect show` response can
+ *  point `pi_session_file` at it (the vector a regression would follow). */
+function seedPoisonedLocalState() {
+    // A local node row + a pending ask under its cwd — poisons `asksForNodes`.
+    createNode(meta('a', { cwd: localCwd }));
+    const askDir = join(interactionsRoot(localCwd), 'poison-ask');
+    mkdirSync(askDir, { recursive: true });
+    atomicWriteJson(deckPath(askDir), {
+        source: { nodeId: 'a' },
+        interactions: [{ id: 'q', kind: 'ask', title: 'poison' }],
+    });
+    // A local focus — poisons `viewed`.
+    openFocusRow('poison-focus', null, null, 'a');
+    // A local active fault — poisons `hanging`.
+    recordFault('a', {
+        link: 'viewer↔broker',
+        op: 'poison',
+        kind: 'other',
+        retry: { disposition: 'manual' },
+        message: 'POISON FAULT — local read leaked into remote render',
+    });
+    // Local telemetry — poisons `ctx_tokens`.
+    writeFileSync(join(jobDir('a'), 'telemetry.json'), JSON.stringify({ tokens_in: 999999 }));
+    // A local goal file — poisons `goal`.
+    writeFileSync(join(contextDir('a'), 'initial-prompt.md'), 'POISON GOAL — local read leaked into remote render');
+    // A local session transcript — poisons `prompts`/`lastAssistant`.
+    const sf = join(home, 'poison-session.jsonl');
+    writeFileSync(sf, [
+        JSON.stringify({ type: 'message', message: { role: 'user', content: 'POISON PROMPT' } }),
+        JSON.stringify({ type: 'message', message: { role: 'assistant', content: 'POISON ASSISTANT REPLY' } }),
+    ].join('\n'));
+    return sf;
+}
+test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource suppress every local-read field to its safe default for a RemoteCanvasSource, even with conflicting local state for the same node id', async () => {
+    sessionFile = seedPoisonedLocalState();
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
+            return { body: { nodes: [row('a')] } };
+        }
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return {
+                body: {
+                    // pi_session_file points at the poisoned local transcript above — if
+                    // the remote suppression regressed and read it anyway, `prompts`/
+                    // `lastAssistant` below would come back non-empty.
+                    node: meta(args[4], { pi_session_file: sessionFile }),
+                    reports: [],
+                    managers: [],
+                    artifacts: { report: 0, doc: 0, roadmap: 0 },
+                    pending_triggers: 0,
+                    paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+                    follow_up: '',
+                },
+            };
+        }
+        return { status: 500, body: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const rows = await dashboardRowsAllFromSource(source);
+    assert.equal(rows.length, 1);
+    const r = rows[0];
+    assert.equal(r.hanging, null, 'local active fault must not leak into a remote row');
+    assert.equal(r.streaming, false);
+    assert.equal(r.viewed, false, 'local focus must not leak into a remote row');
+    await enrichRowsFromSource(source, rows);
+    assert.equal(r.ctx_tokens, 0, 'local telemetry must not leak into a remote row');
+    assert.equal(r.asks, 0, 'a local pending ask for the same node id must not leak into a remote row');
+    assert.equal(r.enriched, true);
+    const previewed = await loadPreviewFromSource(source, r);
+    assert.equal(previewed.goal, undefined, 'a local goal file must not leak into a remote preview');
+    assert.equal(previewed.prompts, undefined, 'a local session transcript must not leak into a remote preview');
+    assert.equal(previewed.lastAssistant, undefined, 'a local session transcript must not leak into a remote preview');
+    assert.equal(previewed.previewLoaded, true);
+    await server.close();
+});
+// The non-TTY `canvas browse` path (browse/app.ts's `if (!process.stdin.isTTY)`
+// branch) calls `renderForestFromSource(source)` directly — a SEPARATE code
+// path from `dashboardRowsAllFromSource`/`enrichRowsFromSource`/
+// `loadPreviewFromSource` above, with its own remote suppression in
+// `renderTreeFromSource`/`nodeLineFromSource` (render.ts). The poisoned-state
+// test above never exercises it, so a regression that reintroduced local
+// telemetry/ask/fault reads into the static forest renderer specifically would
+// pass that test while still leaking poisoned local state here.
+test('renderForestFromSource suppresses local-read fields (ctx, asks, hanging) for a RemoteCanvasSource, even with conflicting local state for the same node id', async () => {
+    const sf = seedPoisonedLocalState();
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
+            return { body: { nodes: [row('a')] } };
+        }
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return {
+                body: {
+                    node: meta(args[4], { pi_session_file: sf }),
+                    reports: [],
+                    managers: [],
+                    artifacts: { report: 0, doc: 0, roadmap: 0 },
+                    pending_triggers: 0,
+                    paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+                    follow_up: '',
+                },
+            };
+        }
+        return { status: 500, body: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const out = await renderForestFromSource(source);
+    assert.match(out, /ctx 0k/, 'the remote node must render with the suppressed ctx default, not a real token read');
+    assert.doesNotMatch(out, /⚑/, 'no ask badge — local asks must not leak into the static forest render');
+    assert.doesNotMatch(out, /POISON FAULT/, 'a local active fault must not leak into the static forest render');
+    assert.doesNotMatch(out, /POISON/, 'no poisoned local telemetry/goal/session text may appear anywhere in the output');
+    await server.close();
+});

package/dist/core/canvas/__tests__/source-resolve.test.d.ts

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

package/dist/core/canvas/__tests__/source-resolve.test.js

@@ -0,0 +1,77 @@
+// source-resolve.test.ts — `resolveCanvasSource` (`../source.ts`), the
+// --canvas > activeCanvas > local precedence a command's read path goes
+// through. The one invariant worth pinning: the local case returns the SAME
+// `localCanvasSource` singleton by identity, not a structurally-equal copy —
+// callers that hold onto a source reference (e.g. `canvas browse`'s
+// `instanceof RemoteCanvasSource` checks) depend on that.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveCanvasSource, localCanvasSource } from '../source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { updateConfig, updateState } from '../../config.js';
+import { setRelayToken } from '../../secrets.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-source-resolve-'));
+    process.env['HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('no --canvas and no activeCanvas resolves to the local singleton by identity', () => {
+    const source = resolveCanvasSource();
+    assert.equal(source, localCanvasSource);
+});
+test('an explicit canvasName wins over local, even with no activeCanvas set', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'tok', 'user');
+    const source = resolveCanvasSource({ canvasName: 'cloud' });
+    assert.ok(source instanceof RemoteCanvasSource);
+    assert.notEqual(source, localCanvasSource);
+});
+test('the durable activeCanvas selection is honored when no explicit canvasName is passed', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'tok', 'user');
+    updateState('user', (s) => {
+        s.activeCanvas = 'cloud';
+    });
+    const source = resolveCanvasSource();
+    assert.ok(source instanceof RemoteCanvasSource);
+});
+test('an explicit --canvas wins over a different durable activeCanvas selection', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud-a'] = { previewEndpoint: 'https://a.preview.bl.run', relayTokenRef: 'cloud-a' };
+        cfg.remoteCanvas.targets['cloud-b'] = { previewEndpoint: 'https://b.preview.bl.run', relayTokenRef: 'cloud-b' };
+    });
+    setRelayToken('cloud-a', 'tok-a', 'user');
+    setRelayToken('cloud-b', 'tok-b', 'user');
+    updateState('user', (s) => {
+        s.activeCanvas = 'cloud-a';
+    });
+    const source = resolveCanvasSource({ canvasName: 'cloud-b' });
+    assert.ok(source instanceof RemoteCanvasSource);
+    assert.equal(source.previewEndpoint, 'https://b.preview.bl.run');
+});
+test('activeCanvas set to null (explicit local) falls back to the local singleton', () => {
+    updateState('user', (s) => {
+        s.activeCanvas = null;
+    });
+    const source = resolveCanvasSource();
+    assert.equal(source, localCanvasSource);
+});

package/dist/core/canvas/browse/__tests__/rebuild-coalescer.test.d.ts

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

package/dist/core/canvas/browse/__tests__/rebuild-coalescer.test.js

@@ -0,0 +1,117 @@
+// rebuild-coalescer.test.ts — proves `createCoalescedRebuilder` (`../rebuild-coalescer.ts`)
+// collapses a burst of triggers into ONE rebuild call, and single-flights a
+// trigger that lands while a rebuild is already in flight into exactly one
+// trailing rebuild rather than a second overlapping one. This is the fix for
+// the N+1-per-event amplification `canvas browse`'s remote SSE path used to
+// have (see app.ts) — WITHOUT the coalescer (i.e. calling `rebuild()` directly
+// on every trigger), these assertions fail: a burst of 5 triggers would count
+// 5 rebuild calls, not 1.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCoalescedRebuilder } from '../rebuild-coalescer.js';
+import { wireEventStreamRebuild } from '../app.js';
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    return { promise, resolve };
+}
+test('a burst of triggers within the debounce window collapses into ONE rebuild call', async () => {
+    let calls = 0;
+    const rebuilder = createCoalescedRebuilder(async () => { calls += 1; }, 30);
+    // Five triggers fired synchronously, well inside the debounce window.
+    for (let i = 0; i < 5; i++)
+        rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 100));
+    assert.equal(calls, 1, 'a burst of 5 triggers must produce exactly 1 rebuild, not 5');
+});
+test('a trigger landing while a rebuild is in flight coalesces into exactly one trailing rebuild', async () => {
+    let calls = 0;
+    const gate = deferred();
+    const rebuilder = createCoalescedRebuilder(async () => {
+        calls += 1;
+        if (calls === 1)
+            await gate.promise; // hold the first rebuild "in flight"
+    }, 10);
+    rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 30)); // let the debounce fire and the first rebuild start
+    assert.equal(calls, 1, 'the first rebuild should now be in flight');
+    // A burst of events lands WHILE the rebuild is running — must coalesce into
+    // exactly one trailing rebuild, never one overlapping rebuild per event.
+    rebuilder.trigger();
+    rebuilder.trigger();
+    rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(calls, 1, 'events during an in-flight rebuild must not start an overlapping rebuild yet');
+    gate.resolve(); // let the first rebuild finish
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(calls, 2, 'exactly one trailing rebuild must run after the in-flight one finished — not 3');
+});
+test('stop() cancels a pending debounce timer so no rebuild fires', async () => {
+    let calls = 0;
+    const rebuilder = createCoalescedRebuilder(async () => { calls += 1; }, 20);
+    rebuilder.trigger();
+    rebuilder.stop();
+    await new Promise((r) => setTimeout(r, 60));
+    assert.equal(calls, 0, 'stop() must cancel the debounced rebuild before it fires');
+});
+// Integration-shaped proof: drive the coalescer with a rebuild function that
+// actually hits a remote-canvas-shaped mock server (the same shelling contract
+// RemoteCanvasSource uses), and count SERVER request rounds — not just JS call
+// counts — across a burst of SSE-style triggers.
+test('a burst of SSE-style triggers produces ONE round of remote requests, not N', async () => {
+    const { createServer } = await import('node:http');
+    const { RemoteCanvasSource } = await import('../../remote-canvas-source.js');
+    let hits = 0;
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            hits += 1;
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
+    const rebuilder = createCoalescedRebuilder(async () => {
+        source.invalidate();
+        await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
+    }, 20);
+    for (let i = 0; i < 6; i++)
+        rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 80));
+    assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
+    await new Promise((r) => server.close(() => r()));
+});
+// Integration proof for browse/app.ts's ACTUAL wiring — not the coalescer
+// helper in isolation. Every test above instantiates `createCoalescedRebuilder`
+// directly, which would stay green even if `app.ts` invoked a per-event
+// rebuild without ever calling the coalescer. This test instead drives
+// `wireEventStreamRebuild`, the exported function `runBrowse` calls to set up
+// its SSE handler, with a fake event stream shaped like the real
+// `RemoteEventStream` (subscribe/start only, no network) — if
+// `wireEventStreamRebuild` is ever changed to call `rebuild` directly per
+// event instead of routing through the coalescer, this test goes red.
+test('wireEventStreamRebuild (the exported app.ts SSE handler) routes a burst of events through the coalescer, not one rebuild per event', async () => {
+    let calls = 0;
+    const listeners = new Set();
+    const fakeEventStream = {
+        subscribe: (fn) => {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+        start: () => { },
+    };
+    const { unsubscribe } = wireEventStreamRebuild(fakeEventStream, async () => { calls += 1; });
+    // A burst of 6 simulated SSE events, well inside the coalescer's debounce
+    // window (default 200ms) — must collapse into ONE rebuild round.
+    for (let i = 0; i < 6; i++) {
+        for (const fn of listeners)
+            fn('nodes');
+    }
+    await new Promise((r) => setTimeout(r, 260));
+    assert.equal(calls, 1, 'a burst of 6 events through the app.ts wiring must produce exactly 1 rebuild, not 6 — if this fails, app.ts stopped routing SSE events through the coalescer');
+    unsubscribe();
+});

package/dist/core/canvas/browse/app.d.ts

@@ -1,6 +1,20 @@
 import { type CanvasSource } from '../source.js';
+import type { RemoteEventStream } from '../remote-event-stream.js';
+import { type CoalescedRebuilder } from './rebuild-coalescer.js';
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export declare function wireEventStreamRebuild(eventStream: Pick<RemoteEventStream, 'subscribe' | 'start'>, rebuild: () => Promise<void>): {
+    rebuilder: CoalescedRebuilder;
+    unsubscribe: () => void;
+};
 export declare function runBrowse(opts?: {
     returnPane?: string;
     cwd?: string;
     source?: CanvasSource;
+    eventStream?: RemoteEventStream;
 }): Promise<void>;

package/dist/core/canvas/browse/app.js

@@ -11,9 +11,11 @@ import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
 import { localCanvasSource } from '../source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { createCoalescedRebuilder } from './rebuild-coalescer.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -26,8 +28,22 @@ function viewportHeight(rowsTotal, search, previewOn) {
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
     return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
 }
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export function wireEventStreamRebuild(eventStream, rebuild) {
+    const rebuilder = createCoalescedRebuilder(rebuild);
+    const unsubscribe = eventStream.subscribe(() => rebuilder.trigger());
+    eventStream.start();
+    return { rebuilder, unsubscribe };
+}
 export async function runBrowse(opts = {}) {
     const source = opts.source ?? localCanvasSource;
+    const isRemote = source instanceof RemoteCanvasSource;
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
@@ -35,18 +51,41 @@ export async function runBrowse(opts = {}) {
     }
     // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
     // session, so `node focus` refuses them; they are never a navigation/resume
-    // target (mirrors the node focus guard).
-    const rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
-    const nodeRows = await source.listNodes();
-    const rootIds = nodeRows
-        .filter((n) => n.parent === null && n.kind !== 'human')
-        .map((n) => n.node_id);
-    const childIds = new Map();
-    await Promise.all(nodeRows.map(async (n) => {
-        childIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
-    }));
-    const tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
-    const totalNodes = tree.nodes.size;
+    // target (mirrors the node focus guard). Factored into a function so the SSE
+    // listener below can re-pull the tree on a `nodes`/`inbox` event instead of
+    // recomputing over a stale snapshot.
+    let rows;
+    let nodeRows;
+    let rootIds;
+    let childIds;
+    let tree;
+    let totalNodes;
+    // Remote-only: pending-ask counts per node, merged from one
+    // `askCountsForView` call per forest root (RemoteCanvasSource.askCountsForView
+    // already shells a single `canvas attention map --view <root>` per root, same
+    // cost class as the per-node `subscriptionsOf` fan-out this snapshot already
+    // does below) — fetched once per snapshot rebuild, not per flush/keystroke, so
+    // enrichRowsFromSource's per-row loop stays a pure sync-shaped map lookup.
+    let remoteAskCounts = {};
+    const rebuildSnapshot = async () => {
+        rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
+        nodeRows = await source.listNodes();
+        rootIds = nodeRows
+            .filter((n) => n.parent === null && n.kind !== 'human')
+            .map((n) => n.node_id);
+        const nextChildIds = new Map();
+        await Promise.all(nodeRows.map(async (n) => {
+            nextChildIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
+        }));
+        childIds = nextChildIds;
+        tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
+        totalNodes = tree.nodes.size;
+        if (isRemote) {
+            const maps = await Promise.all(rootIds.map((root) => source.askCountsForView(root).catch(() => ({}))));
+            remoteAskCounts = Object.assign({}, ...maps);
+        }
+    };
+    await rebuildSnapshot();
     // Default cwd scope = the dir browse was launched from (the request). The popup
     // / command passes --cwd; resolve it so it compares cleanly against stored cwds.
     // null when unknown → All dirs (the toggle's other state).
@@ -82,10 +121,43 @@ export async function runBrowse(opts = {}) {
             restoreTerminal();
         }
         catch { /* best-effort */ }
+        unsubscribeEventStream?.();
+        rebuilder?.stop();
+        opts.eventStream?.stop();
     };
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
+    // Remote-only live invalidation: `canvas browse` has no local fs-watch/poll to
+    // replace (there is none — this is a one-shot snapshot TUI, re-rendering only
+    // on keystrokes). This is net-new plumbing for the remote case only: when a
+    // pre-built RemoteEventStream is threaded in (canvas-browse.ts, once it has
+    // already resolved the target's credentials), a `nodes`/`inbox` SSE event
+    // invalidates the remote source's cache and triggers the same recompute +
+    // coalesced repaint a keystroke would. The local (no eventStream) path is
+    // untouched.
+    let unsubscribeEventStream;
+    let rebuilder;
+    if (opts.eventStream !== undefined) {
+        if (source instanceof RemoteCanvasSource)
+            source.invalidate();
+        // `trigger()` debounces a burst into one rebuild, and single-flights it
+        // against an already-in-flight rebuild — see wireEventStreamRebuild above.
+        const wired = wireEventStreamRebuild(opts.eventStream, async () => {
+            try {
+                if (source instanceof RemoteCanvasSource)
+                    source.invalidate();
+                await rebuildSnapshot();
+                recompute(curRow()?.id);
+                scheduleFlush();
+            }
+            catch (err) {
+                logAsyncFailure('SSE rebuild failed', err);
+            }
+        });
+        rebuilder = wired.rebuilder;
+        unsubscribeEventStream = wired.unsubscribe;
+    }
     const logAsyncFailure = (label, err) => {
         process.stderr.write(`[crtr browse] ${label}: ${String(err?.message ?? err)}\n`);
     };
@@ -154,7 +226,7 @@ export async function runBrowse(opts = {}) {
             if (r !== undefined)
                 slice.push(r);
         }
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         const cur = curRow();
         if (cur !== undefined) {
             const r = rowOf(cur.id);
@@ -166,6 +238,7 @@ export async function runBrowse(opts = {}) {
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
             residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            readOnly: isRemote,
         }, size, caps);
         process.stdout.write(frame);
     };
@@ -459,7 +532,10 @@ export async function runBrowse(opts = {}) {
         }
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'x') {
+            if (isRemote)
+                return;
             if (row === undefined) {
                 scheduleFlush();
                 return;
@@ -510,7 +586,10 @@ export async function runBrowse(opts = {}) {
         // waiting out the 5-min auto-revive grace. Shells `node lifecycle revive <id>
         // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'K') {
+            if (isRemote)
+                return;
             if (row !== undefined) {
                 const r = rowOf(row.id);
                 if (r?.hanging != null)
@@ -519,8 +598,11 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        // Resume.
+        // Resume. No-op against a remote canvas — mutations/focus are disabled
+        // (footer says so).
         if (key.return) {
+            if (isRemote)
+                return;
             if (row !== undefined)
                 selectAndFocus(row.id);
             return;
@@ -566,7 +648,7 @@ export async function runBrowse(opts = {}) {
             return;
         const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
         const slice = warmRows.slice(warmIdx, end);
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
         warmIdx = end;
         // A live search may match the freshly-warmed prompts → recompute + repaint.

package/dist/core/canvas/browse/rebuild-coalescer.d.ts

@@ -0,0 +1,7 @@
+export interface CoalescedRebuilder {
+    /** Called on every SSE event. Cheap — only schedules/marks work. */
+    trigger: () => void;
+    /** Cancels any pending debounce timer (does not abort an in-flight rebuild). */
+    stop: () => void;
+}
+export declare function createCoalescedRebuilder(rebuild: () => Promise<void>, debounceMs?: number): CoalescedRebuilder;