@crouton-kit/crouter 0.3.66 → 0.3.68

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

@@ -0,0 +1,87 @@
+// remote-canvas-target.test.ts — config normalization for
+// `remoteCanvas.targets.<name>` (`../config.ts`'s normalizeRemoteCanvasTarget,
+// exercised through the public readConfig/updateConfig surface — it isn't
+// exported directly) plus `resolveRemoteCanvasTarget`'s error paths
+// (`../view/remote-canvas-target.ts`). The one load-bearing invariant here:
+// an error message about a missing/unknown target must never leak a token
+// substring, even though it's guiding the agent toward the exact command
+// that would set one.
+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 { readConfig, updateConfig } from '../config.js';
+import { setRelayToken } from '../secrets.js';
+import { getRemoteCanvasTarget, resolveRemoteCanvasTarget } from '../view/remote-canvas-target.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-remote-target-'));
+    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('normalizeRemoteCanvasTarget accepts a valid relayTokenRef entry', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    const target = getRemoteCanvasTarget('cloud', 'user');
+    assert.deepEqual(target, { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' });
+});
+test('normalizeRemoteCanvasTarget drops an entry missing relayTokenRef instead of throwing', () => {
+    updateConfig('user', (cfg) => {
+        // Bypass the RemoteCanvasTarget type to write a malformed raw entry, the
+        // same way a hand-edited config.json could.
+        cfg.remoteCanvas.targets['broken'] = { previewEndpoint: 'https://x.preview.bl.run' };
+    });
+    const cfg = readConfig('user');
+    assert.equal(cfg.remoteCanvas.targets['broken'], undefined);
+});
+test('normalizeRemoteCanvasTarget drops an entry with an empty previewEndpoint', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['broken'] = { previewEndpoint: '', relayTokenRef: 'x' };
+    });
+    assert.equal(readConfig('user').remoteCanvas.targets['broken'], undefined);
+});
+test('resolveRemoteCanvasTarget on an unknown name throws a usage error that never contains a token substring', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'super-secret-token', 'user');
+    assert.throws(() => resolveRemoteCanvasTarget('no-such-target', 'user'), (err) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /no remote canvas target named 'no-such-target'/);
+        assert.match(err.message, /configured: cloud/);
+        assert.ok(!err.message.includes('super-secret-token'));
+        return true;
+    });
+});
+test('resolveRemoteCanvasTarget on a target with no stored token throws without leaking a token substring', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    // Deliberately no setRelayToken call — the secret was never stored.
+    assert.throws(() => resolveRemoteCanvasTarget('cloud', 'user'), (err) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /has no stored relay token/);
+        return true;
+    });
+});
+test('resolveRemoteCanvasTarget on a fully configured target returns the RelayTarget with the real token', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'super-secret-token', 'user');
+    const relay = resolveRemoteCanvasTarget('cloud', 'user');
+    assert.deepEqual(relay, { previewEndpoint: 'https://x.preview.bl.run', relayToken: 'super-secret-token' });
+});

package/dist/core/__tests__/revive.test.js

@@ -34,9 +34,11 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
 import { createNode, subscribe } from '../canvas/canvas.js';
 import { readInboxSince } from '../feed/inbox.js';
-import { closeDb } from '../canvas/db.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { canvasDbPath } from '../canvas/paths.js';
 import { buildPiArgv } from '../runtime/launch.js';
 import { headlessBrokerHost } from '../runtime/host.js';
 import { resumeArgs, reviveNode } from '../runtime/revive.js';
@@ -350,3 +352,70 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         await h.dispose();
     }
 });
+// ---------------------------------------------------------------------------
+// Duplicate-broker leak (live-incident regression): reviveNode's guard-check-
+// then-launch-then-recordPid critical section must be a single atomic write
+// transaction, so a concurrent reviveNode call for the SAME node (a second OS
+// process racing this one against the same canvas.db, e.g. a retried web-relay
+// revive under socket thrash) cannot read the same stale pid, launch its own
+// broker, and overwrite this call's freshly-recorded pid — leaking this call's
+// broker as an untracked live process. Proven here by holding a competing raw
+// write transaction open on a SECOND connection to the same db file before
+// calling reviveNode: with the fix, reviveNode's own BEGIN IMMEDIATE cannot
+// acquire the write lock while the other connection holds it, so it fails
+// closed (throws) rather than silently interleaving with the held lock and
+// corrupting the guard's read-then-write. Releasing the competing lock lets an
+// identical reviveNode call proceed and record a fresh pid normally — the
+// serialization is transient contention, not a permanent wedge.
+// ---------------------------------------------------------------------------
+test('reviveNode\'s guard-check-through-recordPid section is one atomic write transaction (duplicate-broker-leak regression)', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-lock' });
+    let contender;
+    try {
+        const sessionFile = join(home, 'sessions', 'crtr-revive-lock.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const stalePid = deadPid();
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: stalePid,
+            pi_session_id: 'uuid-lock',
+            pi_session_file: sessionFile,
+        });
+        // Shorten THIS test's connection's busy_timeout (default 5000ms, db.ts) so
+        // the contended call below fails fast instead of waiting out the real
+        // production window — it's the ACQUIRING side's timeout that governs how
+        // long `BEGIN IMMEDIATE` waits, not the holder's.
+        openDb().exec('PRAGMA busy_timeout = 200;');
+        // A second raw connection to the SAME db file holds an exclusive write
+        // transaction open — modeling a concurrent reviveNode call (a different OS
+        // process, in the real incident) that already won the race and is mid-launch.
+        contender = new DatabaseSync(canvasDbPath());
+        contender.exec('BEGIN IMMEDIATE');
+        assert.throws(() => reviveNode(M, { resume: true }), /locked|busy/i, 'a reviveNode call cannot acquire the write lock while a concurrent revive holds it — no interleaved double-launch');
+        assert.equal(h.node(M).pi_pid, stalePid, 'blocked-out call recorded nothing — the held pid is untouched');
+        // Release the contender's lock — an identical reviveNode call now proceeds
+        // normally, exactly like the uncontended case.
+        contender.exec('COMMIT');
+        contender.close();
+        contender = undefined;
+        reviveNode(M, { resume: true });
+        const after = h.node(M);
+        assert.notEqual(after.pi_pid, stalePid, 'once uncontended, revive proceeds and records a fresh pid');
+        assert.equal(after.cycles, 1, 'the uncontended revive bumped the cycle counter');
+    }
+    finally {
+        if (contender !== undefined) {
+            try {
+                contender.exec('ROLLBACK');
+            }
+            catch { /* best-effort */ }
+            try {
+                contender.close();
+            }
+            catch { /* best-effort */ }
+        }
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/secrets.test.d.ts

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

package/dist/core/__tests__/secrets.test.js

@@ -0,0 +1,55 @@
+// secrets.test.ts — the 0600 relay-token store (`../secrets.ts`). Covers the
+// round-trip (set/get/delete) and the one load-bearing invariant a JSON
+// config file doesn't get for free: the file is written 0600, not the
+// process's default umask-derived mode.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, statSync, existsSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readSecrets, writeSecrets, getRelayToken, setRelayToken, deleteRelayToken, fingerprint } from '../secrets.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-secrets-'));
+    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('a scope with no secrets.json yet reads as empty', () => {
+    assert.deepEqual(readSecrets('user'), { relayTokens: {} });
+    assert.equal(getRelayToken('cloud', 'user'), undefined);
+});
+test('set/get/delete round-trip a token by ref', () => {
+    setRelayToken('cloud', 'sekret-token-value', 'user');
+    assert.equal(getRelayToken('cloud', 'user'), 'sekret-token-value');
+    deleteRelayToken('cloud', 'user');
+    assert.equal(getRelayToken('cloud', 'user'), undefined);
+});
+test('writeSecrets writes secrets.json 0600, even over a pre-existing looser-mode file', () => {
+    writeSecrets('user', { relayTokens: { a: 'x' } });
+    const p = join(home, '.crouter', 'secrets.json');
+    assert.ok(existsSync(p));
+    assert.equal(statSync(p).mode & 0o777, 0o600);
+    // Re-write over an existing file that had a looser mode — chmodSync must
+    // re-tighten it, not just rely on the initial writeFileSync mode.
+    chmodSync(p, 0o644);
+    assert.equal(statSync(p).mode & 0o777, 0o644);
+    writeSecrets('user', { relayTokens: { a: 'x', b: 'y' } });
+    assert.equal(statSync(p).mode & 0o777, 0o600);
+});
+test('fingerprint is the sha256(token) hex prefix — pinned, so a reversible encoding fails', () => {
+    assert.equal(fingerprint('sekret-token-value'), '662bda51b31e');
+    assert.notEqual(fingerprint('a-different-token'), fingerprint('sekret-token-value'));
+    assert.match(fingerprint('sekret-token-value'), /^[0-9a-f]{12}$/);
+    assert.ok(!fingerprint('sekret-token-value').includes('sekret-token-value'));
+});

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

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

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

@@ -0,0 +1,371 @@
+// remote-canvas-source.test.ts — `RemoteCanvasSource` (`../remote-canvas-source.ts`)
+// over its real wire contract: a POST to `/__crtr/source` carrying
+// `{kind:'exec', bin, args}` (see `../../view/transport-remote.ts`), bearer-
+// authed. Mirrors `src/clients/attach/__tests__/transport-relay.test.ts`'s
+// `startMockRelay` shape — a plain `node:http` server standing in for the
+// remote canvas's `/__crtr/source` endpoint, recording every request so
+// assertions land on the wire (argv shape, token placement), not just
+// behavior.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { dashboardRowsAllFromSource, renderForestFromSource } from '../render.js';
+/** Stand up a bare `node:http` server on an ephemeral loopback port — the
+ *  `/__crtr/source` endpoint a `RemoteCanvasSource` POSTs to. `route` decides
+ *  the response per captured argv; every request is recorded first so a test
+ *  can assert on the raw wire (headers, body) independent of what `route`
+ *  returns. */
+function startMockCrtrServer(route) {
+    return new Promise((resolve) => {
+        const requests = [];
+        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);
+                // Reject any request that does not match the exec-only shelling contract
+                // (`{kind:'exec', bin:'crtr'}`) instead of silently routing it —
+                // RemoteCanvasSource must never send anything else over this wire.
+                if (parsed.kind !== 'exec' || parsed.bin !== 'crtr') {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, exitCode: 1, stdout: '', stderr: `unexpected request shape: kind=${parsed.kind} bin=${parsed.bin}` }));
+                    return;
+                }
+                requests.push({
+                    authHeader: req.headers.authorization,
+                    url: req.url ?? '',
+                    method: req.method,
+                    headers: req.headers,
+                    rawBody: bodyText,
+                    kind: parsed.kind,
+                    bin: parsed.bin,
+                    args: parsed.args,
+                });
+                const result = route(parsed.args);
+                if (result.kind === 'json') {
+                    res.writeHead(result.status ?? 200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(result.body), stderr: '' }));
+                }
+                else {
+                    res.writeHead(result.status, { 'content-type': result.contentType ?? 'text/plain' });
+                    res.end(result.body);
+                }
+            });
+        });
+        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}`,
+                requests,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+function meta(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function showResponse(id, reports = []) {
+    return {
+        node: meta(id),
+        reports: reports.map((r) => ({ node_id: r.node_id, name: r.node_id, kind: 'general', status: 'active', active: r.active })),
+        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: '',
+    };
+}
+test('every request POSTs argv leading with --json, and the token appears ONLY in the Authorization header', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[0] === '--json' && args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return { kind: 'json', body: showResponse(args[4]) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'secret-relay-token');
+    await source.getNode('a');
+    assert.equal(server.requests.length, 1);
+    const req = server.requests[0];
+    assert.equal(req.method, 'POST');
+    assert.equal(req.url, '/__crtr/source');
+    assert.equal(req.authHeader, 'Bearer secret-relay-token');
+    assert.equal(req.kind, 'exec', 'RemoteCanvasSource must only ever send the exec contract');
+    assert.equal(req.bin, 'crtr', 'RemoteCanvasSource must only ever shell the existing crtr binary, never an ad-hoc command');
+    assert.deepEqual(req.args.slice(0, 4), ['--json', 'node', 'inspect', 'show']);
+    assert.ok(!req.url.includes('secret-relay-token'));
+    assert.ok(!JSON.stringify(req.args).includes('secret-relay-token'));
+    assert.ok(!req.rawBody.includes('secret-relay-token'), 'the raw POST body must not carry the token');
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (k.toLowerCase() === 'authorization')
+            continue;
+        assert.ok(!String(v).includes('secret-relay-token'), `header ${k} must not carry the token`);
+    }
+});
+test('getNode/getRow project the show response correctly', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show')
+            return { kind: 'json', body: showResponse('a') };
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const node = await source.getNode('a');
+    assert.equal(node?.node_id, 'a');
+    assert.equal(node?.status, 'active');
+    const row = await source.getRow('a');
+    assert.equal(row?.node_id, 'a');
+    assert.equal(row?.kind, 'general');
+    assert.equal(row?.host_kind, null);
+    assert.equal(row?.profile_id, null);
+});
+test('listNodes passes --status only when a filter is given', async (t) => {
+    const seenArgs = [];
+    const server = await startMockCrtrServer((args) => {
+        seenArgs.push(args);
+        const nodes = [];
+        return { kind: 'json', body: { nodes } };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    await source.listNodes();
+    assert.deepEqual(seenArgs[0], ['--json', 'node', 'inspect', 'list']);
+    await source.listNodes({ status: 'active' });
+    assert.deepEqual(seenArgs[1], ['--json', 'node', 'inspect', 'list', '--status', 'active']);
+    await source.listNodes({ status: ['active', 'idle'] });
+    assert.deepEqual(seenArgs[2], ['--json', 'node', 'inspect', 'list', '--status', 'active,idle']);
+});
+test('subscriptionsOf/subscribersOf map reports/managers with created: \'\'', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            return {
+                kind: 'json',
+                body: {
+                    ...showResponse(args[4], [{ node_id: 'child', active: true }]),
+                    managers: [{ node_id: 'boss', name: 'boss', kind: 'general', status: 'active', active: false }],
+                },
+            };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const subs = await source.subscriptionsOf('a');
+    assert.deepEqual(subs, [{ node_id: 'child', active: true, created: '' }]);
+    const managers = await source.subscribersOf('a');
+    assert.deepEqual(managers, [{ node_id: 'boss', active: false, created: '' }]);
+});
+test('view BFS traverses subscriptionsOf and is cycle-safe', async (t) => {
+    // root -> a -> b -> a (cycle back to a).
+    const graph = {
+        root: [{ node_id: 'a', active: true }],
+        a: [{ node_id: 'b', active: true }],
+        b: [{ node_id: 'a', active: true }],
+    };
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            const id = args[4];
+            return { kind: 'json', body: showResponse(id, graph[id] ?? []) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const result = await source.view('root');
+    assert.deepEqual([...result].sort(), ['a', 'b']);
+});
+test('a 500 response, a non-JSON body, and a non-zero exitCode all degrade gracefully instead of throwing', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args.includes('http500'))
+            return { kind: 'json', status: 500, body: {} };
+        if (args.includes('badjson'))
+            return { kind: 'raw', status: 200, body: 'not json', contentType: 'application/json' };
+        if (args.includes('nonzero-exit')) {
+            // stdout is syntactically valid JSON that WOULD be accepted if execJson
+            // ignored exitCode — the assertion below only passes because the
+            // nonzero exitCode is honored and this payload is discarded.
+            const poisoned = JSON.stringify({ counts: { 'nonzero-exit': 7 } });
+            return { kind: 'raw', status: 200, body: JSON.stringify({ ok: true, exitCode: 1, stdout: poisoned, stderr: 'boom' }), contentType: 'application/json' };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    assert.equal(await source.getNode('http500'), null);
+    assert.deepEqual(await source.listNodes(), []);
+    assert.deepEqual(await source.askCountsForView('badjson'), {});
+    assert.deepEqual(await source.askCountsForView('nonzero-exit'), {});
+});
+test('malformed success JSON (exit 0, wrong shape) degrades cleanly instead of returning a shape a consumer would crash on', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            const id = args[4];
+            if (id === 'empty-object')
+                return { kind: 'json', body: {} };
+            if (id === 'null-node')
+                return { kind: 'json', body: { node: null, reports: [], managers: [] } };
+            if (id === 'reports-not-array')
+                return { kind: 'json', body: { node: meta('a'), reports: 'nope', managers: [] } };
+            if (id === 'node-missing-id')
+                return { kind: 'json', body: { node: { name: 'a' }, reports: [], managers: [] } };
+            return { kind: 'json', body: showResponse(id) };
+        }
+        if (args[3] === 'list') {
+            return { kind: 'json', body: { nodes: 'not-an-array' } };
+        }
+        if (args[2] === 'attention') {
+            return { kind: 'json', body: { counts: 'not-an-object' } };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // `{}` — no `node` key at all. Without shape validation this would cast
+    // through as a truthy "valid" RemoteShowResponse (an object with `.node ===
+    // undefined`), and a consumer like `node inspect show`'s remote passthrough
+    // branch (src/commands/node.ts) treats any non-null return as found, then
+    // its renderer dereferences fields on `undefined` and throws.
+    assert.equal(await source.getNode('empty-object'), null, 'a shape with no node key must degrade to null, not a malformed object');
+    assert.equal(await source.rawShow('empty-object'), null);
+    assert.equal(await source.getNode('null-node'), null, '`node: null` must degrade to null');
+    assert.deepEqual(await source.subscriptionsOf('reports-not-array'), [], 'a non-array reports field must degrade to []');
+    assert.equal(await source.getNode('node-missing-id'), null, 'a node object missing node_id must degrade to null');
+    // `listNodes()` with a non-array `nodes` field must degrade to [], never
+    // throw or return the malformed value.
+    assert.deepEqual(await source.listNodes(), []);
+    // `askCountsForView()` with a non-object `counts` field must degrade to {}.
+    assert.deepEqual(await source.askCountsForView('root'), {});
+});
+function fullNodeRow(id, over = {}) {
+    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,
+        ...over,
+    };
+}
+test('listNodes drops malformed row elements (null, missing required fields) instead of casting them through', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'list') {
+            return {
+                kind: 'json',
+                body: { nodes: [null, { node_id: 'partial-only' }, fullNodeRow('good')] },
+            };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const nodes = await source.listNodes();
+    assert.deepEqual(nodes.map((n) => n.node_id), ['good'], 'a null element and a row missing required string fields must both be dropped, leaving only the well-formed row');
+});
+test('isValidShowResponse rejects a payload missing/malformed on artifacts/pending_triggers/paths/follow_up (Phase 3 review Minor 2)', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] !== 'show')
+            return { kind: 'json', status: 500, body: {} };
+        const id = args[4];
+        const valid = showResponse(id);
+        switch (id) {
+            case 'missing-artifacts': {
+                const { artifacts: _artifacts, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'artifacts-wrong-type':
+                return { kind: 'json', body: { ...valid, artifacts: { report: '0', doc: 0, roadmap: 0 } } };
+            case 'missing-pending-triggers': {
+                const { pending_triggers: _pt, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'paths-session-file-undefined': {
+                const { session_file: _sf, ...restPaths } = valid.paths;
+                return { kind: 'json', body: { ...valid, paths: restPaths } };
+            }
+            case 'paths-session-file-null':
+                return { kind: 'json', body: { ...valid, paths: { ...valid.paths, session_file: null } } };
+            case 'missing-follow-up': {
+                const { follow_up: _fu, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'fully-valid':
+                return { kind: 'json', body: valid };
+            default:
+                return { kind: 'json', status: 500, body: {} };
+        }
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    assert.equal(await source.rawShow('missing-artifacts'), null, 'a payload with no artifacts key must degrade to null');
+    assert.equal(await source.rawShow('artifacts-wrong-type'), null, 'artifacts.report as a string must degrade to null');
+    assert.equal(await source.rawShow('missing-pending-triggers'), null, 'a payload with no pending_triggers key must degrade to null');
+    assert.equal(await source.rawShow('paths-session-file-undefined'), null, 'paths.session_file entirely absent (not null) must degrade to null');
+    assert.notEqual(await source.rawShow('paths-session-file-null'), null, 'paths.session_file explicitly null (no session yet) must be ACCEPTED');
+    assert.equal(await source.rawShow('missing-follow-up'), null, 'a payload with no follow_up key must degrade to null');
+    assert.notEqual(await source.rawShow('fully-valid'), null, 'the tightened validator must not false-reject the real, fully-valid shape');
+});
+test('a malformed row element does not crash the browse snapshot path (dashboardRowsAllFromSource / renderForestFromSource)', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'list') {
+            return { kind: 'json', body: { nodes: [null, { node_id: 'partial-only' }, fullNodeRow('good')] } };
+        }
+        if (args[3] === 'show') {
+            return { kind: 'json', body: showResponse('good') };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // `browse/app.ts`'s `rebuildSnapshot` calls `listNodes()` and dereferences
+    // `n.parent`/`n.kind`/`n.node_id` on every row, and `dashboardRowsAllFromSource`
+    // reaches the same shape via `dashboardRowFromNodeRow` — both rely on
+    // `listNodes()` having already dropped the malformed `null` element.
+    const rows = await dashboardRowsAllFromSource(source);
+    assert.deepEqual(rows.map((r) => r.node_id), ['good']);
+    const forest = await renderForestFromSource(source);
+    assert.ok(forest.includes('good'));
+});
+test('cache coalescing: two getNode calls inside the TTL hit the server once; invalidate() busts it', async (t) => {
+    let hitCount = 0;
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            hitCount += 1;
+            return { kind: 'json', body: showResponse(args[4]) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    await source.getNode('a');
+    await source.getNode('a');
+    assert.equal(hitCount, 1);
+    source.invalidate();
+    await source.getNode('a');
+    assert.equal(hitCount, 2);
+});

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

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