@north-light/crouter 0.3.310 → 0.3.311

package/dist/commands/__tests__/integration/dashboard-snapshot.test.d.ts

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

package/dist/commands/__tests__/integration/dashboard-snapshot.test.js

@@ -0,0 +1,212 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { createNode, subscribe } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { apiSocketPath } from '../../../core/canvas/paths.js';
+import { Router } from '../../../daemon/api/router.js';
+import { createApiServer } from '../../../daemon/api/server.js';
+function node(id, parent) {
+    return {
+        node_id: id,
+        name: `${id}-handle`,
+        description: `${id} task`,
+        created: new Date().toISOString(),
+        cwd: '/tmp/dashboard-test',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent,
+    };
+}
+function runCanvas(home, command, extraEnv = {}) {
+    return new Promise((resolve, reject) => {
+        const args = ['--conditions=crtr-src', '--import', 'tsx/esm', 'src/cli.ts', '--json', ...command];
+        const child = spawn(process.execPath, args, {
+            cwd: process.cwd(),
+            env: {
+                ...process.env,
+                ...extraEnv,
+                CRTR_HOME: home,
+                CRTR_NO_DAEMON_AUTOSTART: '1',
+                CRTR_NO_AUTO_INIT: '1',
+                CRTR_NO_AUTO_UPDATE: '1',
+                CRTR_NO_EXPORTS: '1',
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}
+function runDashboard(home, root, extraEnv) {
+    return runCanvas(home, ['canvas', 'dashboard', ...(root === undefined ? [] : ['--root', root])], extraEnv);
+}
+/** The capability this file exists for: a dashboard render issues a fixed
+ *  number of requests whatever the graph's size, and never reads one node at
+ *  a time. Which order those requests go out in is an implementation detail —
+ *  the scoped and full renders already differ there. */
+function assertSnapshotReads(requests, label) {
+    assert.equal(requests.length, 3, `${label} issued ${requests.length} requests: ${requests.join(' ')}`);
+    assert.ok(!requests.some((url) => /^\/v1\/nodes\/./.test(url)), `${label} made a per-node read: ${requests.join(' ')}`);
+}
+function startMockRemoteCanvas(route) {
+    return new Promise((resolve) => {
+        const requests = [];
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                const { args } = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                requests.push(args);
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(route(args)), stderr: '' }));
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                requests,
+                close: () => new Promise((done) => server.close(() => done())),
+            });
+        });
+    });
+}
+test('canvas dashboard renders scoped and full cycles from one node snapshot without per-node API reads', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-dashboard-'));
+    const home = join(root, 'canvas');
+    mkdirSync(home, { recursive: true });
+    const previousHome = process.env['CRTR_HOME'];
+    const originalHandle = Router.prototype.handle;
+    const requests = [];
+    try {
+        process.env['CRTR_HOME'] = home;
+        closeDb();
+        createNode(node('root', null));
+        createNode(node('left', 'root'));
+        createNode(node('right', 'root'));
+        createNode(node('shared', 'left'));
+        subscribe('root', 'left');
+        subscribe('root', 'right');
+        subscribe('left', 'shared');
+        subscribe('right', 'shared');
+        subscribe('shared', 'left');
+        Router.prototype.handle = async function (req, res) {
+            requests.push(req.url ?? '');
+            await originalHandle.call(this, req, res);
+        };
+        const server = createApiServer();
+        await server.ready;
+        assert.ok(existsSync(apiSocketPath()), 'the isolated API socket is bound before the CLI starts');
+        t.after(async () => {
+            Router.prototype.handle = originalHandle;
+            await server.close();
+        });
+        for (let i = 0; i < 32; i++) {
+            const id = `worker-${i}`;
+            createNode(node(id, i === 0 ? 'shared' : `worker-${i - 1}`));
+            subscribe(i === 0 ? 'shared' : `worker-${i - 1}`, id);
+        }
+        requests.length = 0;
+        const large = await runDashboard(home, 'root');
+        assert.equal(large.code, 0, large.stderr);
+        const largeOutput = JSON.parse(large.stdout);
+        assert.equal(largeOutput.nodes, 36);
+        assert.equal(largeOutput.rows.length, 36);
+        assert.equal(new Set(largeOutput.rows.map((row) => row.node_id)).size, 36, 'shared descendants remain one row each');
+        assert.ok(largeOutput.rows.every((row) => row.ctx_tokens === 0 && row.asks === 0), 'the emitted row fields remain populated from the snapshot');
+        assert.match(largeOutput.tree, /worker-31-handle worker-31 task \[developer\/base\] ctx 0k/);
+        assertSnapshotReads(requests, 'the scoped dashboard');
+        requests.length = 0;
+        const full = await runDashboard(home);
+        assert.equal(full.code, 0, full.stderr);
+        const fullOutput = JSON.parse(full.stdout);
+        assert.equal(fullOutput.nodes, 36);
+        assert.equal(fullOutput.rows.length, 36);
+        assert.match(fullOutput.tree, /root-handle root task \[developer\/base\] ctx 0k/);
+        assert.match(fullOutput.tree, /↺ <cycle: left>/);
+        assert.match(fullOutput.tree, /↺ <cycle: shared>/);
+        assertSnapshotReads(requests, 'the full dashboard');
+        Router.prototype.handle = async function (req, res) {
+            requests.push(req.url ?? '');
+            if (req.url === '/v1/canvas/attention/counts') {
+                res.writeHead(503, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'unavailable' }));
+                return;
+            }
+            await originalHandle.call(this, req, res);
+        };
+        requests.length = 0;
+        const degradedDashboard = await runDashboard(home);
+        assert.equal(degradedDashboard.code, 0, degradedDashboard.stderr);
+        const degradedOutput = JSON.parse(degradedDashboard.stdout);
+        assert.ok(degradedOutput.rows.every((row) => row.asks === 0), 'unavailable ticket counts render as default badges');
+        assert.match(degradedOutput.tree, /worker-31-handle worker-31 task/, 'the dashboard keeps its topology when ticket counts fail');
+        const roster = await runCanvas(home, ['canvas', 'roster']);
+        assert.equal(roster.code, 0, roster.stderr);
+        const rosterOutput = JSON.parse(roster.stdout);
+        assert.ok(rosterOutput.edges.some((edge) => edge.from_id === 'root' && edge.to_id === 'left'), 'the roster retains authoritative edges when ticket counts fail');
+        assert.deepEqual(rosterOutput.subscriptions['root'], ['left', 'right']);
+    }
+    finally {
+        Router.prototype.handle = originalHandle;
+        closeDb();
+        if (previousHome === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = previousHome;
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('canvas dashboard reads full-forest ticket counts from the selected remote canvas', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-dashboard-remote-'));
+    const home = join(root, 'canvas');
+    const userHome = join(root, 'user');
+    const remote = await startMockRemoteCanvas((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
+            return { nodes: [node('root', null), node('child', 'root')] };
+        }
+        if (args[1] === 'canvas' && args[2] === 'attention') {
+            return { counts: { root: 2, child: 3 } };
+        }
+        if (args[1] === 'canvas' && args[2] === 'roster') {
+            return { edges: [{ from_id: 'root', to_id: 'child', active: true, created: '' }] };
+        }
+        throw new Error(`unexpected remote command: ${args.join(' ')}`);
+    });
+    t.after(() => remote.close());
+    try {
+        mkdirSync(join(userHome, '.crouter'), { recursive: true });
+        writeFileSync(join(userHome, '.crouter', 'config.json'), JSON.stringify({
+            remoteCanvas: { targets: { remote: { previewEndpoint: remote.url, relayTokenRef: 'remote' } } },
+        }));
+        writeFileSync(join(userHome, '.crouter', 'state.json'), JSON.stringify({ activeCanvas: 'remote' }));
+        writeFileSync(join(userHome, '.crouter', 'secrets.json'), JSON.stringify({ relayTokens: { remote: 'test-token' } }));
+        const result = await runDashboard(home, undefined, { HOME: userHome });
+        assert.equal(result.code, 0, result.stderr);
+        const output = JSON.parse(result.stdout);
+        assert.deepEqual(output.rows.map((row) => ({ node_id: row.node_id, asks: row.asks })), [
+            { node_id: 'root', asks: 2 },
+            { node_id: 'child', asks: 3 },
+        ]);
+        assert.match(output.tree, /⚑2/);
+        assert.match(output.tree, /⚑3/);
+        // The mock route throws on any command it does not recognise, so this only
+        // has to pin that topology comes from one roster call rather than one per edge.
+        assert.equal(remote.requests.length, 3, `remote issued ${remote.requests.length} commands: ${remote.requests.map((args) => args.join(' ')).join(' | ')}`);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/commands/api-client.d.ts

@@ -76,6 +76,7 @@ export declare class ApiCanvasSource implements CanvasSource {
      * be per-node. Request only this view's ids: using the
      * enriched full-canvas snapshot for a five-second viewer poll blocked crtrd
      * behind metadata and telemetry reads for every historical node. */
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
     ticketCountsForView(root: string): Promise<Record<string, number>>;
     /** True when `nodeId` has at least one active (`active` edge flag, not just a
      *  live subscriber) subscription to a node that is currently live

package/dist/commands/api-client.js

@@ -247,9 +247,11 @@ export class ApiCanvasSource {
      * be per-node. Request only this view's ids: using the
      * enriched full-canvas snapshot for a five-second viewer poll blocked crtrd
      * behind metadata and telemetry reads for every historical node. */
+    async ticketCountsForNodes(nodeIds) {
+        return (await this.client.attentionCounts([...nodeIds])).counts;
+    }
     async ticketCountsForView(root) {
-        const ids = [root, ...await this.view(root)];
-        return (await this.client.attentionCounts(ids)).counts;
+        return this.ticketCountsForNodes([root, ...await this.view(root)]);
     }
     /** True when `nodeId` has at least one active (`active` edge flag, not just a
      *  live subscriber) subscription to a node that is currently live

package/dist/commands/canvas-roster.js

@@ -23,6 +23,12 @@ export const canvasRosterLeaf = defineLeaf({
                 required: true,
                 constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.',
             },
+            {
+                name: 'edges',
+                type: 'object[]',
+                required: true,
+                constraint: 'Subscription edges with from_id, to_id, active, and created fields.',
+            },
         ],
         outputKind: 'object',
         effects: [
@@ -38,25 +44,26 @@ export const canvasRosterLeaf = defineLeaf({
         // (`GET /v1/canvas/roster`). Attention counts stay a SEPARATE bounded read
         // (`POST /v1/canvas/attention/counts`) — never folded into the roster query
         // itself, which must stay indexed-scan-only.
+        const dto = await cliClient().canvasRoster().catch((err) => rethrowAsCliError(err));
+        const ids = dto.nodes.map((n) => n.node_id);
+        let counts = {};
         try {
-            const dto = await cliClient().canvasRoster();
-            const ids = dto.nodes.map((n) => n.node_id);
-            const counts = ids.length > 0 ? (await cliClient().attentionCounts(ids)).counts : {};
-            const nodes = dto.nodes.map((n) => ({ ...n, attention_count: counts[n.node_id] ?? 0 }));
-            const subscriptions = {};
-            for (const n of dto.nodes)
-                subscriptions[n.node_id] = [];
-            for (const e of dto.edges) {
-                const list = subscriptions[e.from_id];
-                if (list !== undefined)
-                    list.push(e.to_id);
-                else
-                    subscriptions[e.from_id] = [e.to_id];
-            }
-            return { generated_at: dto.generated_at, nodes, subscriptions };
+            counts = ids.length > 0 ? (await cliClient().attentionCounts(ids)).counts : {};
+        }
+        catch {
+            // Ticket counts decorate the authoritative roster topology.
         }
-        catch (err) {
-            rethrowAsCliError(err);
+        const nodes = dto.nodes.map((n) => ({ ...n, attention_count: counts[n.node_id] ?? 0 }));
+        const subscriptions = {};
+        for (const n of dto.nodes)
+            subscriptions[n.node_id] = [];
+        for (const e of dto.edges) {
+            const list = subscriptions[e.from_id];
+            if (list !== undefined)
+                list.push(e.to_id);
+            else
+                subscriptions[e.from_id] = [e.to_id];
         }
+        return { generated_at: dto.generated_at, nodes, subscriptions, edges: dto.edges };
     },
 });

package/dist/commands/dashboard.js

@@ -7,7 +7,7 @@
 // Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { cliClient, cliCanvasSource } from './api-client.js';
+import { cliCanvasSource } from './api-client.js';
 import { renderTreeFromSource, renderForestFromSource, dashboardRowsFromSource, dashboardRowsAllFromSource, enrichRowsFromSource, } from '../core/canvas/render-source.js';
 // dashboard show — the main leaf
 export const dashboardLeaf = defineLeaf({
@@ -37,40 +37,47 @@ export const dashboardLeaf = defineLeaf({
     run: async (input) => {
         const rootId = input['root'];
         const source = cliCanvasSource();
+        const allNodes = await source.listNodes();
         if (rootId !== undefined) {
-            // Scoped to a single root — validate the node exists (via the daemon API).
-            const node = await source.getNode(rootId);
-            if (node === null) {
+            if (!allNodes.some((node) => node.node_id === rootId)) {
                 throw new InputError({
                     error: 'not_found',
                     message: `no node: ${rootId}`,
                     next: 'List nodes with `crtr node inspect list` to find a valid id.',
                 });
             }
-            const rows = await dashboardRowsFromSource(source, rootId);
+            let asks = {};
+            let ticketsUnavailable;
+            try {
+                asks = await source.ticketCountsForView(rootId);
+            }
+            catch (err) {
+                ticketsUnavailable = err instanceof Error ? err.message : String(err);
+            }
+            const rows = await dashboardRowsFromSource(source, rootId, allNodes, asks);
             return {
-                tree: await renderTreeFromSource(source, rootId),
+                tree: await renderTreeFromSource(source, rootId, allNodes, asks, ticketsUnavailable),
                 nodes: rows.length,
                 rows,
             };
         }
         // Full forest: all nodes on the canvas.
-        const allNodes = await source.listNodes();
         // dashboardRowsAllFromSource is the cheap-boot builder: ctx_tokens/asks are 0
         // and `name` is the handle only until enriched. The JSON consumer wants the
         // real values, so fold the deferred fields in before emitting (the rendered
         // TREE is unaffected). Ask counts are per-node: attention follows each human
-        // bridge's parent relation. The daemon's canvas snapshot carries that count
-        // (`attention_count`, server-side `enrichRows`), so read it straight off the
-        // roster.
-        const rows = await dashboardRowsAllFromSource(source);
-        const snapshot = await cliClient().canvasSnapshot();
-        const asks = {};
-        for (const n of snapshot.nodes)
-            asks[n.node_id] = n.attention_count;
+        // bridge's parent relation, so fetch all displayed counts in one batch.
+        const rows = await dashboardRowsAllFromSource(source, new Set(), false, allNodes);
+        let asks = {};
+        try {
+            asks = await source.ticketCountsForNodes(allNodes.map((node) => node.node_id));
+        }
+        catch {
+            // Ticket counts decorate the dashboard; the source snapshot remains authoritative.
+        }
         await enrichRowsFromSource(source, rows, asks);
         return {
-            tree: await renderForestFromSource(source),
+            tree: await renderForestFromSource(source, allNodes, asks),
             nodes: allNodes.length,
             rows,
         };

package/dist/core/__tests__/cron-timeout-descendants.test.d.ts

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

package/dist/core/__tests__/cron-timeout-descendants.test.js

@@ -0,0 +1,102 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/cron-timeout-descendants.test.ts
+//
+// #1037: a cron descendant living outside the shell's own process group held
+// the run's output pipes open, and settlement waited on those pipes. Teardown
+// signalled the group and moved on, so the timeout was recorded only when the
+// descendant finally exited by itself — 732 seconds for a 240-second timeout
+// in the field. Teardown must reap the tree it captured by ancestry, and the
+// record must wait for those processes to be dead rather than merely quiet.
+//
+// GNU `timeout` is the wrapper that produced the field report, but nothing
+// here is specific to it: a detached child reproduces the same shape on any
+// platform, so this never skips.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { armCron, getCron } from '../canvas/crons.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { executeCron } from '../../daemon/cron-run.js';
+// The shell starts a live intermediate that keeps a detached grandchild in a
+// process group of its own. The grandchild inherits the cron's stdout and
+// stderr and ignores TERM, so the pipes stay open until something kills it.
+const INTERMEDIATE = `
+const { spawn } = require('node:child_process');
+spawn(process.execPath, [process.argv[2], process.argv[3]], { detached: true, stdio: 'inherit' }).unref();
+setInterval(() => {}, 1000);
+`;
+const DESCENDANT = `
+process.on('SIGTERM', () => {});
+require('node:fs').writeFileSync(process.argv[2], String(process.pid));
+setInterval(() => {}, 1000);
+`;
+let home;
+let realHome;
+let marker;
+let command;
+function arm(overrides) {
+    armCron({
+        name: overrides.cron_id,
+        created_by: null,
+        fire_at: new Date(Date.now() - 1_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: null,
+        cancel_on_wake: false,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 1,
+        overlap: 'skip',
+        on_output: 'silent',
+        sink: '{}',
+        tier: 'normal',
+        ...overrides,
+    });
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-cron-timeout-descendants-'));
+    realHome = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+    marker = join(home, 'descendant.pid');
+    const intermediate = join(home, 'intermediate.cjs');
+    const descendant = join(home, 'descendant.cjs');
+    writeFileSync(intermediate, INTERMEDIATE);
+    writeFileSync(descendant, DESCENDANT);
+    // Two statements, so the shell stays alive as the tree's root rather than
+    // exec-replacing itself with the intermediate.
+    command = `${JSON.stringify(process.execPath)} ${JSON.stringify(intermediate)} ${JSON.stringify(descendant)} ${JSON.stringify(marker)}; printf 'shell survived\\n'`;
+});
+after(() => {
+    if (existsSync(marker)) {
+        const stranded = Number.parseInt(readFileSync(marker, 'utf8').trim(), 10);
+        if (Number.isInteger(stranded) && stranded > 0 && isPidAlive(stranded)) {
+            try {
+                process.kill(stranded, 'SIGKILL');
+            }
+            catch {
+                // It exited between the liveness probe and the signal.
+            }
+        }
+    }
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (realHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = realHome;
+});
+test('a TERM-ignoring descendant outside the shell process group is reaped before the timeout is recorded', async () => {
+    arm({ cron_id: 'timeout-descendants', command });
+    const record = await executeCron(getCron('timeout-descendants'), { outOfBand: true });
+    assert.ok(record !== null, 'the run settles instead of hanging on held pipes');
+    assert.equal(record.exit_code, -1, 'the configured deadline is recorded as a timeout');
+    assert.ok(record.duration_ms < 5_000, `settlement is bounded by the deadline and teardown, got ${record.duration_ms}ms`);
+    const descendant = Number.parseInt(readFileSync(marker, 'utf8').trim(), 10);
+    assert.ok(Number.isInteger(descendant) && descendant > 0, 'the scenario actually started an out-of-group descendant');
+    assert.equal(isPidAlive(descendant), false, 'the descendant is dead, not merely detached from the pipes it was holding');
+});

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

@@ -116,17 +116,19 @@ test('every request POSTs argv leading with --json, and the token appears ONLY i
         assert.ok(!String(v).includes('secret-relay-token'), `header ${k} must not carry the token`);
     }
 });
-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 }],
-    };
+test('view reads the batched roster topology and is cycle-safe', async (t) => {
     const server = await startMockCrtrServer((args) => {
-        if (args[3] === 'show') {
-            const id = args[4];
-            return { kind: 'json', body: showResponse(id, graph[id] ?? []) };
+        if (args[1] === 'canvas' && args[2] === 'roster') {
+            return {
+                kind: 'json',
+                body: {
+                    edges: [
+                        { from_id: 'root', to_id: 'a', active: true, created: '' },
+                        { from_id: 'a', to_id: 'b', active: true, created: '' },
+                        { from_id: 'b', to_id: 'a', active: true, created: '' },
+                    ],
+                },
+            };
         }
         return { kind: 'json', status: 500, body: {} };
     });
@@ -134,8 +136,17 @@ test('view BFS traverses subscriptionsOf and is cycle-safe', async (t) => {
     const source = new RemoteCanvasSource(server.url, 'tok');
     const result = await source.view('root');
     assert.deepEqual([...result].sort(), ['a', 'b']);
+    assert.equal(server.requests.length, 1, 'the whole traversal shares one roster request');
+});
+test('topology failures surface instead of rendering an empty remote graph', async (t) => {
+    const server = await startMockCrtrServer(() => ({ kind: 'json', status: 500, body: {} }));
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    await assert.rejects(source.subscriptionsOf('root'), /remote canvas topology is unavailable/);
+    await assert.rejects(source.subscriptionsOf('other-root'), /remote canvas topology is unavailable/);
+    assert.equal(server.requests.length, 1, 'a failed roster read is shared across roots for the cache TTL');
 });
-test('a 500 response, a non-JSON body, and a non-zero exitCode all degrade gracefully instead of throwing', async (t) => {
+test('a 500 response, a non-JSON body, and a non-zero exitCode degrade optional reads gracefully', async (t) => {
     const server = await startMockCrtrServer((args) => {
         if (args.includes('http500'))
             return { kind: 'json', status: 500, body: {} };
@@ -159,6 +170,8 @@ test('a 500 response, a non-JSON body, and a non-zero exitCode all degrade grace
 });
 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[1] === 'canvas' && args[2] === 'roster')
+            return { kind: 'json', body: { edges: [] } };
         if (args[3] === 'show') {
             const id = args[4];
             if (id === 'empty-object')

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

@@ -46,10 +46,13 @@ export declare class RemoteCanvasSource implements CanvasSource {
     private readonly exec;
     private nodeCache;
     private rosterCache;
+    private topologyCache;
     private viewCache;
     constructor(previewEndpoint: string, relayToken: string);
     private execJson;
     private fetchShow;
+    private topology;
+    private loadTopology;
     /** The full passthrough object `node inspect show` produces — used by
      *  `nodeShow`'s remote branch (`src/commands/node/inspect.ts`) to return the exact
      *  same shape a local read would, without re-deriving it. */
@@ -62,6 +65,7 @@ export declare class RemoteCanvasSource implements CanvasSource {
     subscriptionsOf(id: string): Promise<SubscriptionRef[]>;
     subscribersOf(id: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
     ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(id: string): Promise<boolean>;
 }

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

@@ -76,6 +76,13 @@ function isValidNeighborEntry(x) {
  *  lifecycle fields local/API-backed row renderers dereference unguarded;
  *  the remaining nullable runtime
  *  fields (host_kind, parent, pi_pid, ...) are left to cast through as-is. */
+function isValidRosterEdge(x) {
+    return (isPlainObject(x) &&
+        typeof x['from_id'] === 'string' &&
+        typeof x['to_id'] === 'string' &&
+        typeof x['active'] === 'boolean' &&
+        typeof x['created'] === 'string');
+}
 function isValidNodeRow(x) {
     if (!isPlainObject(x))
         return false;
@@ -94,6 +101,7 @@ export class RemoteCanvasSource {
     exec;
     nodeCache = new Map();
     rosterCache = new Map();
+    topologyCache = null;
     viewCache = new Map();
     constructor(previewEndpoint, relayToken) {
         this.previewEndpoint = previewEndpoint;
@@ -134,6 +142,46 @@ export class RemoteCanvasSource {
         this.nodeCache.set(id, { value: res, at: Date.now() });
         return res;
     }
+    topology() {
+        if (this.topologyCache !== null && Date.now() - this.topologyCache.at < CACHE_TTL_MS)
+            return this.topologyCache.value;
+        const request = this.loadTopology();
+        this.topologyCache = { value: request, at: Date.now() };
+        return request;
+    }
+    async loadTopology() {
+        const response = await this.exec('crtr', ['--json', 'canvas', 'roster']);
+        if (!response.ok || (response.exitCode !== undefined && response.exitCode !== 0)) {
+            throw new Error('remote canvas topology is unavailable');
+        }
+        let raw;
+        try {
+            raw = JSON.parse(response.stdout.trim());
+        }
+        catch {
+            throw new Error('remote canvas topology is invalid');
+        }
+        if (!isPlainObject(raw) || !Array.isArray(raw['edges']) || !raw['edges'].every(isValidRosterEdge)) {
+            throw new Error('remote canvas topology is invalid');
+        }
+        const edges = raw['edges'];
+        const topology = { subscriptions: new Map(), subscribers: new Map() };
+        for (const edge of edges) {
+            const subscription = { node_id: edge.to_id, active: edge.active, created: edge.created };
+            const subscriber = { node_id: edge.from_id, active: edge.active, created: edge.created };
+            const subscriptions = topology.subscriptions.get(edge.from_id);
+            if (subscriptions === undefined)
+                topology.subscriptions.set(edge.from_id, [subscription]);
+            else
+                subscriptions.push(subscription);
+            const subscribers = topology.subscribers.get(edge.to_id);
+            if (subscribers === undefined)
+                topology.subscribers.set(edge.to_id, [subscriber]);
+            else
+                subscribers.push(subscriber);
+        }
+        return topology;
+    }
     /** The full passthrough object `node inspect show` produces — used by
      *  `nodeShow`'s remote branch (`src/commands/node/inspect.ts`) to return the exact
      *  same shape a local read would, without re-deriving it. */
@@ -186,12 +234,10 @@ export class RemoteCanvasSource {
         return nodes;
     }
     async subscriptionsOf(id) {
-        const reports = (await this.fetchShow(id))?.reports ?? [];
-        return reports.map((r) => ({ node_id: r.node_id, active: r.active, created: '' }));
+        return (await this.topology()).subscriptions.get(id) ?? [];
     }
     async subscribersOf(id) {
-        const managers = (await this.fetchShow(id))?.managers ?? [];
-        return managers.map((r) => ({ node_id: r.node_id, active: r.active, created: '' }));
+        return (await this.topology()).subscribers.get(id) ?? [];
     }
     async view(root) {
         const cached = this.viewCache.get(root);
@@ -214,9 +260,15 @@ export class RemoteCanvasSource {
         this.viewCache.set(root, { value: out, at: Date.now() });
         return out;
     }
+    async ticketCountsForNodes(nodeIds) {
+        // The `canvas attention map` transport's `counts` values mean all pending
+        // human tickets (page/review), not just asks.
+        if (nodeIds.length === 0)
+            return {};
+        const res = await this.execJson(['canvas', 'attention', 'map', '--nodes', nodeIds.join(',')]);
+        return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
+    }
     async ticketCountsForView(root) {
-        // The `canvas attention map` transport is unchanged; its `counts` values now
-        // mean all pending human tickets (page/review), not just asks.
         const res = await this.execJson(['canvas', 'attention', 'map', '--view', root]);
         return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
     }