@crouton-kit/crouter 0.3.66 → 0.3.68

package/dist/core/canvas/__tests__/remote-event-stream.test.js

@@ -0,0 +1,144 @@
+// remote-event-stream.test.ts — `RemoteEventStream` (`../remote-event-stream.ts`),
+// a manual SSE client over `/__crtr/events`. Covers the wire parse (only
+// known `kind`s fire listeners; comments/pings/unknown kinds are silently
+// ignored) and that `stop()` actually halts the reconnect loop rather than
+// leaving it retrying forever in the background.
+//
+// Reconnect/backoff timing uses an INJECTABLE backoff (`RemoteEventStreamOptions`)
+// so these tests run against a small, fast backoff window instead of the
+// production 1s→30s one, and every wait is a condition-poll on an observed
+// request/event count (`waitFor`) rather than a fixed wall-clock sleep —
+// less flaky under scheduler variance, and fast.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { RemoteEventStream } from '../remote-event-stream.js';
+function startSseServer(onRequest) {
+    return new Promise((resolve) => {
+        let hits = 0;
+        const requests = [];
+        const server = createServer((req, res) => {
+            hits += 1;
+            requests.push({ method: req.method, url: req.url ?? '', headers: req.headers });
+            onRequest(res, req);
+        });
+        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}`,
+                hitCount: () => hits,
+                requests,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+/** Poll `predicate` until it's true, or throw after `timeoutMs` — used in
+ *  place of a fixed sleep so tests assert on the OBSERVED condition (a
+ *  request landed, an event fired) rather than a guessed timing window. */
+async function waitFor(predicate, timeoutMs = 2000, intervalMs = 5) {
+    const deadline = Date.now() + timeoutMs;
+    while (!predicate()) {
+        if (Date.now() > deadline)
+            throw new Error(`waitFor: condition not met within ${timeoutMs}ms`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+test('a listener fires once per known-kind SSE event, and never for a ping or an unknown kind', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.write(': connected\n\n');
+        res.write('data: {"kind":"nodes"}\n\n');
+        res.write(': ping\n\n');
+        res.write('data: {"kind":"bogus"}\n\n');
+        res.end();
+    });
+    const stream = new RemoteEventStream(server.url, 'tok');
+    const seen = [];
+    stream.subscribe((kind) => seen.push(kind));
+    stream.start();
+    await waitFor(() => seen.length > 0);
+    stream.stop();
+    assert.deepEqual(seen, ['nodes']);
+    await server.close();
+});
+test('the SSE connection carries the token ONLY in the Authorization header — not in the URL or any other header', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.end();
+    });
+    // A token that cannot collide with a hostname/port (unlike 'tok', which is a
+    // substring of numeric-looking noise) so a pass here can't be a coincidence —
+    // no header, including Host, is permitted to carry it.
+    const token = 'secret-sse-token-value';
+    const stream = new RemoteEventStream(server.url, token);
+    stream.start();
+    await waitFor(() => server.requests.length > 0);
+    stream.stop();
+    assert.equal(server.requests.length, 1);
+    const req = server.requests[0];
+    assert.equal(req.method, 'GET');
+    assert.equal(req.url, '/__crtr/events');
+    assert.equal(req.headers['authorization'], `Bearer ${token}`);
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (k.toLowerCase() === 'authorization')
+            continue;
+        assert.ok(!String(v).includes(token), `header ${k} must not carry the token`);
+    }
+    assert.ok(!req.url.includes(token));
+    await server.close();
+});
+test('stop() cancels a pending reconnect timer — no zombie loop survives a stop()+start() cycle', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(500);
+        res.end();
+    });
+    // A small injected backoff (200ms, not production's 1s) — the test asserts
+    // the SAME relative-timing invariant (a stopped loop's dangling reconnect
+    // timer must not fire) but the deliberate gap below (half the backoff)
+    // between the stale deadline and the new deadline is kept proportionally
+    // wide enough that ordinary event-loop/scheduler jitter can't flip it.
+    const BACKOFF = 200;
+    const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    stream.start();
+    // t≈0: first request fires+fails, backoff(BACKOFF) scheduled → stale deadline ≈ BACKOFF.
+    await waitFor(() => server.hitCount() >= 1);
+    assert.equal(server.hitCount(), 1);
+    // Deliberate mid-backoff gap (half the window) before stop()+start(), so the
+    // stale deadline (hit1 + BACKOFF) and the new loop's own deadline
+    // (hit2 + BACKOFF) land ~BACKOFF/2 apart — the window this test inspects.
+    await new Promise((r) => setTimeout(r, BACKOFF / 2));
+    stream.stop();
+    stream.start();
+    await waitFor(() => server.hitCount() >= 2);
+    assert.equal(server.hitCount(), 2, 'restart fires its own immediate request');
+    // Wait past the STALE timer's deadline (~BACKOFF from the first request) but
+    // well before the NEW loop's own deadline (~BACKOFF from the second,
+    // later, request). A dangling old-loop timer (bug) would add a 3rd hit in
+    // this window; a cleared one (fixed) leaves it at 2.
+    await new Promise((r) => setTimeout(r, BACKOFF * 0.7));
+    assert.equal(server.hitCount(), 2, "no zombie request from the stopped loop's dangling timer");
+    stream.stop();
+    await server.close();
+});
+test('stop() halts the reconnect loop — no further requests after it is called', async () => {
+    const server = await startSseServer((res) => {
+        // Every connection is refused immediately (no SSE headers, just a close)
+        // so the client's loop falls into its backoff-and-retry path.
+        res.writeHead(500);
+        res.end();
+    });
+    const BACKOFF = 20;
+    const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    stream.start();
+    await waitFor(() => server.hitCount() >= 1);
+    const hitsAtStop = server.hitCount();
+    stream.stop();
+    // The reconnect backoff is BACKOFF ms; wait well past it and confirm no new
+    // connection was attempted — proves the loop actually stopped rather than
+    // continuing to retry in the background after stop() returned.
+    await new Promise((r) => setTimeout(r, BACKOFF * 5));
+    assert.equal(server.hitCount(), hitsAtStop);
+    await server.close();
+});

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>;