@north-light/crouter 0.3.154

package/dist/core/broker-client/transport.js

@@ -0,0 +1,26 @@
+// transport.ts — the Transport seam: BrokerClient's broker I/O, abstracted
+// so the SAME correlation/pending/close logic can ride either the LOCAL unix
+// socket (SocketTransport, transport-socket.ts) or a relayed WebSocket to a
+// remote broker (RelayTransport, transport-relay.ts). Both speak the same
+// broker-protocol JSON frames; only how bytes cross the wire differs.
+//
+// A Transport is a pure duplex frame pump — connect (dial), redial (re-dial
+// the SAME target after a drop), send (one client→broker frame), destroy
+// (tear down). It emits 'connect' once the peer is reachable, one 'frame' per
+// decoded broker→client frame, 'error' for a surfaced problem (including a
+// {@link BrokerUnavailableError} when the target has no reachable broker),
+// and 'close' exactly once when the connection is gone. Everything ABOVE this
+// seam — request correlation, the pending map, redial-vs-give-up policy — is
+// BrokerClient's job and never moves into a Transport implementation.
+/** Surfaced when a Transport's target has no reachable broker — locally, no
+ *  socket file / nothing listening; remotely, a relay close signaling "no
+ *  broker for this node". The command catches this to exit non-zero with a
+ *  focus/revive hint — same meaning regardless of which Transport raised it. */
+export class BrokerUnavailableError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`node ${nodeId} has no running broker — focus or revive it first`);
+        this.nodeId = nodeId;
+        this.name = 'BrokerUnavailableError';
+    }
+}

package/dist/core/canvas/__tests__/attention.test.d.ts

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

package/dist/core/canvas/__tests__/attention.test.js

@@ -0,0 +1,97 @@
+// attention.test.ts — tickets are keyed by their human bridge node directory.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson, deckPath } from '@crouton-kit/humanloop';
+import { createNode } from '../canvas.js';
+import { closeDb } from '../db.js';
+import { nodeDir } from '../paths.js';
+import { countTickets, ticketCountsForNodes, pendingTicketsForView, invalidateTicketCounts } from '../attention.js';
+function meta(id, cwd, extra) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...extra,
+    };
+}
+function seedDeck(bridgeId) {
+    const dir = nodeDir(bridgeId);
+    mkdirSync(dir, { recursive: true });
+    atomicWriteJson(deckPath(dir), {
+        title: bridgeId,
+        interactions: [{ id: 'q', title: bridgeId, subtitle: 'Acknowledge this ticket so the request can proceed.', options: [] }],
+    });
+}
+function bridge(id, parent, cwd) {
+    createNode(meta(id, cwd, { kind: 'human', parent }));
+}
+let home;
+let sharedCwd;
+let soloCwd;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-attention-'));
+    sharedCwd = mkdtempSync(join(tmpdir(), 'crtr-attention-shared-'));
+    soloCwd = mkdtempSync(join(tmpdir(), 'crtr-attention-solo-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    invalidateTicketCounts();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    for (const d of [home, sharedCwd, soloCwd])
+        rmSync(d, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('ticketCountsForNodes follows bridge parents even when asking nodes share a cwd', () => {
+    createNode(meta('a', sharedCwd));
+    createNode(meta('b', sharedCwd));
+    createNode(meta('c', soloCwd));
+    bridge('ha1', 'a', sharedCwd);
+    bridge('ha2', 'a', sharedCwd);
+    bridge('hb', 'b', sharedCwd);
+    bridge('hc', 'c', soloCwd);
+    seedDeck('ha1');
+    seedDeck('ha2');
+    seedDeck('hb');
+    seedDeck('hc');
+    assert.deepEqual(ticketCountsForNodes(['a', 'b', 'c']), { a: 2, b: 1, c: 1 });
+});
+test('countTickets counts only tickets asked by that node', () => {
+    createNode(meta('a', sharedCwd));
+    createNode(meta('b', sharedCwd));
+    bridge('ha', 'a', sharedCwd);
+    bridge('hb', 'b', sharedCwd);
+    seedDeck('ha');
+    seedDeck('hb');
+    assert.equal(countTickets('a'), 1);
+    assert.equal(countTickets('b'), 1);
+});
+test('every requested id is present with 0 when it has no tickets', () => {
+    createNode(meta('a', sharedCwd));
+    createNode(meta('c', soloCwd));
+    bridge('ha', 'a', sharedCwd);
+    seedDeck('ha');
+    assert.deepEqual(ticketCountsForNodes(['a', 'c']), { a: 1, c: 0 });
+});
+test('pendingTicketsForView returns the asking node rather than a cwd bucket', () => {
+    createNode(meta('a', sharedCwd));
+    createNode(meta('b', sharedCwd));
+    bridge('ha', 'a', sharedCwd);
+    bridge('hb', 'b', sharedCwd);
+    seedDeck('ha');
+    seedDeck('hb');
+    assert.deepEqual(pendingTicketsForView('a').map(({ node_id, count }) => ({ node_id, count })), [
+        { node_id: 'a', count: 1 },
+    ]);
+});

package/dist/core/canvas/__tests__/human-work-outbox.test.d.ts

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

package/dist/core/canvas/__tests__/human-work-outbox.test.js

@@ -0,0 +1,123 @@
+// human-work-outbox.test.ts — permanent storage compatibility invariants:
+// legacy follow-up receipts remain retryable and prune-safe, while Visual work
+// is uniquely bound and invisible to old follow-up selectors.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { createNode, getRow, pruneNodes } from '../canvas.js';
+import { closeDb, MIGRATIONS, migrate, openDb } from '../db.js';
+import { nodeDir } from '../paths.js';
+import { pushFinal } from '../../feed/feed.js';
+import { claimVisualWork, getFollowUpWorkRow, getVisualWorkByRequest, listPendingFollowUpWork, reconcileFollowUpWork, reconcileVisualWork, } from '../human-work-outbox.js';
+let home;
+const DAY = 86_400_000;
+const old = () => new Date(Date.now() - 30 * DAY).toISOString();
+const now = () => new Date().toISOString();
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: now(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function insertLegacyFollowUp(nodeId, dir, root, requestId) {
+    openDb()
+        .prepare('INSERT INTO consult_outbox (node_id, dir, root, request_id, status, final_report, updated_at) VALUES (?, ?, ?, ?, ?, NULL, ?)')
+        .run(nodeId, dir, root, requestId, 'armed', now());
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-work-outbox-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('a v18 follow-up row upgrades with its follow_up default', () => {
+    mkdirSync(home, { recursive: true });
+    const db = new DatabaseSync(join(home, 'v18-canvas.db'));
+    try {
+        for (const migration of MIGRATIONS.slice(0, 18))
+            migration(db);
+        db.exec('PRAGMA user_version = 18');
+        db.prepare("INSERT INTO consult_outbox (node_id, dir, root, request_id, status, updated_at) VALUES ('legacy-node', '/ticket', '/root', 'legacy-request', 'armed', '2026-01-01T00:00:00.000Z')").run();
+        migrate(db);
+        const row = db.prepare("SELECT work_kind, status FROM consult_outbox WHERE node_id = 'legacy-node'").get();
+        assert.equal(row.work_kind, 'follow_up');
+        assert.equal(row.status, 'armed');
+    }
+    finally {
+        db.close();
+    }
+});
+test('legacy follow-up insert, feed promotion, and reconciliation retain their receipt behavior', async () => {
+    const root = join(home, 'unregistered-root');
+    const dir = join(root, 'ticket-1');
+    mkdirSync(dir, { recursive: true });
+    createNode(node('fork-1', { status: 'dead' }));
+    insertLegacyFollowUp('fork-1', dir, root, 'req-1');
+    reconcileFollowUpWork();
+    const retryable = getFollowUpWorkRow('fork-1');
+    assert.ok(retryable !== null);
+    assert.equal(retryable.status, 'armed', 'a rejected follow-up publish stays retryable');
+    createNode(node('fork-2', { created: old() }));
+    insertLegacyFollowUp('fork-2', dir, root, 'req-2');
+    await pushFinal('fork-2', 'follow-up result');
+    assert.equal(getFollowUpWorkRow('fork-2')?.status, 'pending');
+    assert.deepEqual(listPendingFollowUpWork().map((row) => row.node_id), ['fork-2']);
+    const result = pruneNodes({ ttlDays: 14 });
+    assert.deepEqual(result.pruned, [], 'a legacy pending receipt preserves its node and report payload');
+    assert.ok(getRow('fork-2') !== null);
+    assert.ok(existsSync(nodeDir('fork-2')));
+});
+test('Visual claims are unique and legacy armed/pending selectors are blind to them', () => {
+    const root = join(home, 'root');
+    const dir = join(root, 'ticket-visual');
+    mkdirSync(dir, { recursive: true });
+    insertLegacyFollowUp('follow-up-1', dir, root, 'follow-up-request');
+    const binding = {
+        nodeId: 'visual-1',
+        dir,
+        root,
+        requestId: 'visual-request',
+        interactionId: 'interaction-1',
+        generationId: 'generation-1',
+        interactionSnapshot: '{"id":"interaction-1","body":"Visualize this"}',
+        handlerCommand: '/absolute/crtr',
+        handlerArgs: ['human', '_visual'],
+        claimToken: 'claim-token',
+    };
+    assert.equal(claimVisualWork(binding).created, true);
+    assert.equal(claimVisualWork({ ...binding, nodeId: 'unused-duplicate-node' }).created, false);
+    assert.throws(() => claimVisualWork({ ...binding, nodeId: 'conflicting-node', generationId: 'generation-2' }), /conflicting Visual work claim/);
+    assert.throws(() => openDb()
+        .prepare("INSERT INTO consult_outbox (node_id, dir, root, request_id, work_kind, status, updated_at) VALUES (?, ?, ?, ?, 'visual', 'visual_armed', ?)")
+        .run('duplicate-visual-node', dir, root, binding.requestId, now()), /UNIQUE constraint failed/);
+    assert.equal(getVisualWorkByRequest(dir, binding.requestId)?.status, 'visual_armed');
+    createNode(node('visual-1', {
+        status: 'canceled',
+        human_work_target: { work_kind: 'visual', dir, request_id: binding.requestId, root },
+        private_fork_phase: 'fork_pending',
+    }));
+    reconcileVisualWork();
+    assert.equal(getVisualWorkByRequest(dir, binding.requestId)?.status, 'visual_armed', 'the deliberate inert pre-launch fork remains launchable');
+    const legacy = openDb()
+        .prepare("SELECT node_id FROM consult_outbox WHERE status IN ('armed', 'pending') ORDER BY node_id")
+        .all();
+    assert.deepEqual(legacy.map((row) => row.node_id), ['follow-up-1']);
+    assert.deepEqual(listPendingFollowUpWork(), []);
+});

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,372 @@
+// 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/core/broker-client/__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_crons: 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.ticketCountsForView('badjson'), {});
+    assert.deepEqual(await source.ticketCountsForView('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(), []);
+    // `ticketCountsForView()` with a non-object `counts` field must degrade to {}.
+    assert.deepEqual(await source.ticketCountsForView('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,
+        waiting_for: 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_crons/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-crons': {
+                const { pending_crons: _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-crons'), null, 'a payload with no pending_crons 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 {};