@north-light/crouter 0.3.310 → 0.3.312

package/dist/core/__tests__/profile-project-memory-delivery.test.js

@@ -350,11 +350,11 @@ after(() => {
     restore('CRTR_PROFILE_ID', prevProfile);
     restore('CRTR_NODE_ID', prevNode);
 });
-function newNode(kind = 'general') {
-    return spawnNode({ kind, cwd: cwdProject, parent: null, profile_id: profileId }).node_id;
+async function newNode(kind = 'general') {
+    return (await spawnNode({ kind, cwd: cwdProject, parent: null, profile_id: profileId })).node_id;
 }
-test('boot delivery caps every profile project at its relationship, including the one used as cwd', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('boot delivery caps every profile project at its relationship, including the one used as cwd', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     // The control: an uncapped relationship still renders its authored content.
     assert.ok(boot.includes(B.pcontent), `the content-capped project renders its body; got:\n${boot}`);
     // The reported failure. cwd reaches this root before the manifest pointer
@@ -369,22 +369,22 @@ test('boot delivery caps every profile project at its relationship, including th
     assert.match(boot, /[├└]─ t9-pname-doc$/m, `the name-capped doc discloses as a bare name; got:\n${boot}`);
     assert.ok(!boot.includes('When the name project delivers'), 'a name-capped doc discloses no preview line');
 });
-test('surface-entry gates select the rung by node kind while the document gate remains absolute', () => {
+test('surface-entry gates select the rung by node kind while the document gate remains absolute', async () => {
     for (const kind of ['design', 'spec', 'plan', 'developer']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.ok(boot.includes(B.kindSplit), `${kind} receives the content rung; got:\n${boot}`);
     }
     for (const kind of ['general', 'review', 'advisor']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.match(boot, /t9-kind-split {2}# read when: When the node needs this kind-specific guide\./, `${kind} receives the preview rung; got:\n${boot}`);
         assert.ok(!boot.includes(B.kindSplit), `${kind} does not receive the body`);
     }
     for (const kind of ['explore', 'personal-assistant']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.ok(!boot.includes('t9-kind-split'), `${kind} receives no kind-split entry; got:\n${boot}`);
         assert.ok(!boot.includes(B.kindSplit), `${kind} receives no kind-split body`);
     }
-    const developer = renderKnowledgeBlock(newNode('developer'), freshTranscriptTarget());
+    const developer = renderKnowledgeBlock(await newNode('developer'), freshTranscriptTarget());
     assert.ok(!developer.includes('t9-document-gate-wins'), `a failing document gate excludes every entry; got:\n${developer}`);
     assert.ok(!developer.includes(B.documentGateWins), 'a failing document gate excludes its content');
     assert.ok(developer.includes(B.codeCraftIndex), 'the directory document delivers its boot content');
@@ -394,8 +394,8 @@ test('surface-entry gates select the rung by node kind while the document gate r
     // The ancestor listing, not just the doc's own directory.
     assert.match(developer, /sibling {2}# read when: When the dev sibling applies\./, `content delivery exposes the enclosing directory's members too; got:\n${developer}`);
 });
-test('context docs accounting reports content attachment raises from the renderer', () => {
-    const node = newNode('developer');
+test('context docs accounting reports content attachment raises from the renderer', async () => {
+    const node = await newNode('developer');
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const target = { cwd: cwdProject, profileId, nodeId: node };
@@ -431,8 +431,8 @@ test('context docs accounting reports content attachment raises from the rendere
     assert.equal(viewerRecord?.deliveryCause, 'directory listing attached to content delivery');
     plans.dispose();
 });
-test('context docs accounting adds full-view workspace content attachments', () => {
-    const node = newNode();
+test('context docs accounting adds full-view workspace content attachments', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const target = { cwd: outsideProject, profileId, nodeId: node };
@@ -446,8 +446,8 @@ test('context docs accounting adds full-view workspace content attachments', ()
     assert.equal(companion?.final_rung, 'content');
     assert.equal(companion?.delivery_cause, 'memory-read companion of content delivery');
 });
-test('boot content triggers memory-read companions to a deduplicated fixpoint', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('boot content triggers memory-read companions to a deduplicated fixpoint', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     for (const body of [B.companionSource, B.companionA, B.companionB]) {
         assert.equal(boot.split(body).length - 1, 1, `content companion ${body} delivers once; got:\n${boot}`);
     }
@@ -455,8 +455,8 @@ test('boot content triggers memory-read companions to a deduplicated fixpoint',
     // discloses its members exactly as the doc that routed to it did.
     assert.match(boot, /member-1 {2}# read when: When the companion member applies\./, `a content companion exposes its own directory's members; got:\n${boot}`);
 });
-test('one body delivered across both boot partitions renders exactly once', () => {
-    const node = newNode();
+test('one body delivered across both boot partitions renders exactly once', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const state = emptyContextExposureState();
@@ -470,8 +470,8 @@ test('one body delivered across both boot partitions renders exactly once', () =
     const occurrences = (preferences.split(B.crossPartition).length - 1) + (knowledge.split(B.crossPartition).length - 1);
     assert.equal(occurrences, 1, `the companion body renders once across both partitions; got:\n${preferences}\n---\n${knowledge}`);
 });
-test('a node-local doc floors to name only without boot entries', () => {
-    const node = newNode('explore');
+test('a node-local doc floors to name only without boot entries', async () => {
+    const node = await newNode('explore');
     writeDoc(memoryDir(node), 't9-node-local-bootless', bootlessDoc('When the node-local fallback applies', 'BODY-T9-NODE-LOCAL-BOOTLESS'));
     writeDoc(memoryDir(node), 't9-node-local-entry-gated', [
         '---',
@@ -491,8 +491,8 @@ test('a node-local doc floors to name only without boot entries', () => {
     assert.ok(!boot.includes('t9-node-local-entry-gated'), `ineligible boot entries keep a node-local doc absent; got:\n${boot}`);
     assert.ok(!boot.includes('BODY-T9-NODE-LOCAL-ENTRY-GATED'), 'ineligible boot entries disclose no body');
 });
-test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.ok(!boot.includes(B.pnone), 'a none-capped body must not render');
     assert.ok(!boot.includes('pnone'), 'a none-capped store must not appear as a name either — not even its namespace row');
     // Hidden counts are disclosure too: the control project's namespace row proves
@@ -512,7 +512,7 @@ test('a capped nearer candidate yields the shared identity instead of suppressin
     // physical candidates. Automatic delivery filters candidates by the profile
     // cap BEFORE dedupe, so the `none`-capped nearer one drops out and the farther
     // one delivers; a deliberate read stays winner-only on source order.
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.ok(boot.includes(B.dupFar), `the farther uncapped candidate delivers the shared identity; got:\n${boot}`);
     assert.ok(!boot.includes(B.dupNear), 'the none-capped nearer candidate delivers nothing');
     const read = (await readLeaf.run({
@@ -524,14 +524,14 @@ test('a capped nearer candidate yields the shared identity instead of suppressin
     }));
     assert.ok(read.content.includes(B.dupNear) && !read.content.includes(B.dupFar), `a deliberate read resolves the source-order winner; got:\n${read.content}`);
 });
-test('a non-none cap keeps its project precedence and discloses the duplicate at the capped rung', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('a non-none cap keeps its project precedence and discloses the duplicate at the capped rung', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.match(boot, /[├└]─ t9-namedup-doc$/m, `the name-capped project discloses its doc as a bare name; got:\n${boot}`);
     assert.ok(!boot.includes(B.nameFromPname), 'a name-capped doc discloses at `name`, never its body');
     assert.ok(boot.includes(B.nameFromPcontent), 'the content project delivers its own distinct identity in full');
 });
-test('workspace-open clamps each project store the same way boot does', () => {
-    const opened = renderWorkspaceOpenDocs(newNode(), freshTranscriptTarget());
+test('workspace-open clamps each project store the same way boot does', async () => {
+    const opened = renderWorkspaceOpenDocs(await newNode(), freshTranscriptTarget());
     assert.ok(opened.includes(B.pcontent), `the content-capped project delivers its body; got:\n${opened}`);
     assert.ok(!opened.includes(B.ppreview), `the cwd project must not deliver its body; got:\n${opened}`);
     assert.match(opened, /name="ppreview\/t9-ppreview-doc" readWhen="When the cwd project delivers\./, `the cwd project delivers its preview line under its canonical name; got:\n${opened}`);
@@ -539,8 +539,8 @@ test('workspace-open clamps each project store the same way boot does', () => {
     assert.ok(!opened.includes('t9-pnone-doc'), 'the none-capped project delivers nothing at workspace-open');
     assert.ok(!opened.includes(B.sharedFromPnone), 'nor its side of a name collision');
 });
-test('workspace-open answers its listings from the workspace it opened, not the ambient one', () => {
-    const node = newNode();
+test('workspace-open answers its listings from the workspace it opened, not the ambient one', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     // The process cwd is `ppreview`; this workspace is outside the profile
@@ -551,7 +551,7 @@ test('workspace-open answers its listings from the workspace it opened, not the
     assert.match(opened, /\[\[poutside\/t9-ws-guide\/member-1\]\]: When the outside guide member applies\./, `the listing carries that directory's own members; got:\n${opened}`);
 });
 test('memory list and find record synthetic pages without crediting matched documents', async () => {
-    const node = newNode();
+    const node = await newNode();
     process.env['CRTR_NODE_ID'] = node;
     try {
         const listed = await listLeaf.run({
@@ -589,7 +589,7 @@ test('memory list and find record synthetic pages without crediting matched docu
     }
 });
 test('an explicit read after boot content adds no duplicate directory attachments', async () => {
-    const node = newNode('developer');
+    const node = await newNode('developer');
     process.env['CRTR_NODE_ID'] = node;
     try {
         const state = loadContextExposureState(node);
@@ -614,7 +614,7 @@ test('an explicit read after boot content adds no duplicate directory attachment
     }
 });
 test('an explicit `crtr memory read` returns and records the full body a cap withheld', async () => {
-    const node = newNode();
+    const node = await newNode();
     process.env['CRTR_NODE_ID'] = node;
     const state = loadContextExposureState(node);
     const transcript = exposureTarget(state, 'transcript');

package/dist/core/__tests__/spawn-worktree-id-conflict.test.js

@@ -50,7 +50,7 @@ after(async () => {
 });
 test('a --worktree spawn at an already-existing node id throws and leaves NO worktree registered', async () => {
     const nodeId = 'duplicate-id';
-    spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId });
+    await spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId });
     await assert.rejects(() => spawnChild({ kind: 'general', cwd: repoDir, prompt: '', worktree: true, nodeId }));
     assert.ok(!existsSync(managedWorktreePath(nodeId)), 'the conflicting spawn must not leave a worktree checkout directory');
     assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/crtr/${nodeId}`], repoDir).status, 1, 'the conflicting spawn must not leave a registered crtr/<id> branch');
@@ -59,12 +59,12 @@ test('a --worktree spawn at an already-existing node id throws and leaves NO wor
     assert.equal(getNode(nodeId).kind, 'general');
     assert.equal(getNode(nodeId).managed_worktree, undefined);
 });
-test('spawnNode({ nodeId }): a hyphen-less opaque id spawns at the exact given id', () => {
+test('spawnNode({ nodeId }): a hyphen-less opaque id spawns at the exact given id', async () => {
     // Regression for the reviewed opaque-id-contract violation: the old validator
     // required >=2 hyphen segments and rejected a hyphen-less id outright,
     // contradicting the design's "opaque, never parsed for structure" ID scheme
     // that remote and cloud spawns depend on.
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'remote42' });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'remote42' });
     assert.equal(meta.node_id, 'remote42');
     assert.notEqual(getNode('remote42'), null);
 });

package/dist/core/__tests__/warm-claim-preference-snapshot.test.js

@@ -33,7 +33,7 @@ after(() => {
     delete process.env['CRTR_HOME'];
 });
 test('the claim path persists a frozen preference snapshot', async () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     assert.equal(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'a spare mints with nothing frozen');
     await deliverBearingsLive(meta.node_id);
     assert.notEqual(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'claim freezes the snapshot the persona gate requires');

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'] : {};
     }

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

@@ -13,8 +13,8 @@ export interface NodeTelemetry {
 export declare function readNodeTelemetry(nodeId: string): NodeTelemetry;
 /** Format a token count as `Nk` (rounded down to nearest 1 k). */
 export declare function fmtCtx(tokensIn: number | undefined): string;
-export declare function renderTreeFromSource(source: CanvasSource, rootId: string): Promise<string>;
-export declare function renderForestFromSource(source: CanvasSource): Promise<string>;
+export declare function renderTreeFromSource(source: CanvasSource, rootId: string, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>, ticketUnavailable?: string): Promise<string>;
+export declare function renderForestFromSource(source: CanvasSource, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>, ticketUnavailable?: string): Promise<string>;
 export interface DashboardRow {
     node_id: string;
     /** Full display label: explicit handle plus generated description. */
@@ -183,13 +183,13 @@ export declare function dashboardRowFromNodeRow(row: NodeRow, focusedNodeIds: Re
  *  entirely through the source — the openDb-free sibling of `dashboardRows`.
  *  Ticket counts come from ONE `source.ticketCountsForView(rootId)` call (the
  *  API/remote attention projection), never `countTickets` (openDb). */
-export declare function dashboardRowsFromSource(source: CanvasSource, rootId: string): Promise<DashboardRow[]>;
+export declare function dashboardRowsFromSource(source: CanvasSource, rootId: string, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>): Promise<DashboardRow[]>;
 /** CHEAP boot builder over a source — one row per node across the whole canvas,
  *  fields that need no per-node meta/session read. Local API callers may supply
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
  *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
-export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean): Promise<DashboardRow[]>;
+export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean, snapshot?: readonly NodeRow[]): Promise<DashboardRow[]>;
 export declare function enrichRowsFromSource(_source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
 /** goal (initial-prompt.md) and session parts are local disk reads — suppressed
  *  to undefined for a remote source. */

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

@@ -60,9 +60,8 @@ export function fmtCtx(tokensIn) {
 // LOCAL disk reads (telemetry.json / fault.json), valid for a same-host source
 // but meaningless for a truly remote canvas, so both are suppressed when the
 // source is a `RemoteCanvasSource`.
-async function nodeLineFromSource(source, nodeId, indent, connector, remote, tickets) {
-    const node = await source.getNode(nodeId);
-    if (node === null)
+function nodeLineFromSource(node, nodeId, indent, connector, remote, tickets) {
+    if (node === undefined)
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
     const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
@@ -72,12 +71,12 @@ async function nodeLineFromSource(source, nodeId, indent, connector, remote, tic
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
 }
-async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out, remote, tickets) {
+async function walkTreeFromSource(source, nodes, nodeId, indent, isLast, visited, out, remote, tickets) {
     if (visited.has(nodeId))
         return;
     visited.add(nodeId);
     const connector = isLast ? '└─ ' : '├─ ';
-    out.push(await nodeLineFromSource(source, nodeId, indent, connector, remote, tickets));
+    out.push(nodeLineFromSource(nodes.get(nodeId), nodeId, indent, connector, remote, tickets));
     const childIndent = indent + (isLast ? '   ' : '│  ');
     let children;
     try {
@@ -95,22 +94,25 @@ async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out,
             out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
             continue;
         }
-        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out, remote, tickets);
+        await walkTreeFromSource(source, nodes, child.node_id, childIndent, childIsLast, visited, out, remote, tickets);
     }
 }
-export async function renderTreeFromSource(source, rootId) {
+export async function renderTreeFromSource(source, rootId, snapshot, ticketSnapshot, ticketUnavailable) {
     const remote = source instanceof RemoteCanvasSource;
-    const node = await source.getNode(rootId);
-    if (node === null)
+    const nodes = new Map((snapshot ?? await source.listNodes()).map((node) => [node.node_id, node]));
+    const node = nodes.get(rootId);
+    if (node === undefined)
         return `? <missing node: ${rootId}>`;
-    let tickets;
-    let ticketsUnavailable = null;
-    try {
-        tickets = await source.ticketCountsForView(rootId);
-    }
-    catch (err) {
-        tickets = {};
-        ticketsUnavailable = err instanceof Error ? err.message : String(err);
+    let tickets = ticketSnapshot;
+    let ticketsUnavailable = ticketUnavailable ?? null;
+    if (tickets === undefined) {
+        try {
+            tickets = await source.ticketCountsForView(rootId);
+        }
+        catch (err) {
+            tickets = {};
+            ticketsUnavailable = err instanceof Error ? err.message : String(err);
+        }
     }
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
     const asks = tickets[rootId] ?? 0;
@@ -132,14 +134,14 @@ export async function renderTreeFromSource(source, rootId) {
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
         const isLast = i === children.length - 1;
-        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out, remote, tickets);
+        await walkTreeFromSource(source, nodes, child.node_id, '', isLast, visited, out, remote, tickets);
     }
     if (ticketsUnavailable !== null)
         out.push(`Tickets: unavailable (${ticketsUnavailable}).`);
     return out.join('\n');
 }
-export async function renderForestFromSource(source) {
-    const all = await source.listNodes();
+export async function renderForestFromSource(source, snapshot, ticketSnapshot, ticketUnavailable) {
+    const all = snapshot ?? await source.listNodes();
     if (all.length === 0)
         return '(canvas is empty)';
     const roots = all.filter((n) => n.parent === null && (n.status === 'active' || n.status === 'idle'));
@@ -147,7 +149,7 @@ export async function renderForestFromSource(source) {
         return '(no live roots)';
     const parts = [];
     for (const r of roots) {
-        parts.push(await renderTreeFromSource(source, r.node_id));
+        parts.push(await renderTreeFromSource(source, r.node_id, all, ticketSnapshot, ticketUnavailable));
     }
     return parts.join('\n\n');
 }
@@ -563,44 +565,43 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
  *  entirely through the source — the openDb-free sibling of `dashboardRows`.
  *  Ticket counts come from ONE `source.ticketCountsForView(rootId)` call (the
  *  API/remote attention projection), never `countTickets` (openDb). */
-export async function dashboardRowsFromSource(source, rootId) {
+export async function dashboardRowsFromSource(source, rootId, snapshot, ticketSnapshot) {
     const remote = source instanceof RemoteCanvasSource;
-    const tickets = await source.ticketCountsForView(rootId).catch(() => ({}));
+    const tickets = ticketSnapshot ?? await source.ticketCountsForView(rootId).catch(() => ({}));
+    const nodes = new Map((snapshot ?? await source.listNodes()).map((node) => [node.node_id, node]));
     const ids = [rootId, ...(await source.view(rootId))];
-    const rows = [];
-    for (const id of ids) {
-        const node = await source.getNode(id);
-        if (node === null)
-            continue;
+    return ids.flatMap((id) => {
+        const node = nodes.get(id);
+        if (node === undefined)
+            return [];
         const tel = remote ? {} : readNodeTelemetry(id);
-        rows.push({
-            node_id: id,
-            name: fullName(node),
-            handle: node.name,
-            description: node.description,
-            status: node.status,
-            frozen_at: node.frozen_at ?? null,
-            terminal_reason: node.terminal_reason ?? null,
-            kind: node.kind,
-            mode: node.mode,
-            ctx_tokens: tel.tokens_in ?? 0,
-            asks: tickets[id] ?? 0,
-            cwd: node.cwd,
-            profile_id: node.profile_id,
-            created: node.created,
-        });
-    }
-    return rows;
+        return [{
+                node_id: id,
+                name: fullName(node),
+                handle: node.name,
+                description: node.description,
+                status: node.status,
+                frozen_at: node.frozen_at ?? null,
+                terminal_reason: node.terminal_reason ?? null,
+                kind: node.kind,
+                mode: node.mode,
+                ctx_tokens: tel.tokens_in ?? 0,
+                asks: tickets[id] ?? 0,
+                cwd: node.cwd,
+                profile_id: node.profile_id,
+                created: node.created,
+            }];
+    });
 }
 /** CHEAP boot builder over a source — one row per node across the whole canvas,
  *  fields that need no per-node meta/session read. Local API callers may supply
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
  *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
-export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set(), liveOnly = false) {
+export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set(), liveOnly = false, snapshot) {
     const remote = source instanceof RemoteCanvasSource;
     const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;
-    const rows = await source.listNodes(liveOnly ? { status: ['active', 'idle'] } : undefined);
+    const rows = snapshot ?? await source.listNodes(liveOnly ? { status: ['active', 'idle'] } : undefined);
     return rows.map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
 // Lazy enrichment (source-driven) — fold the per-node reads the cheap boot skips

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

@@ -9,6 +9,7 @@ export interface CanvasSource {
     subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
     subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
     ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
@@ -21,6 +22,7 @@ export declare class LocalCanvasSource implements CanvasSource {
     subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
     subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
     ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }

package/dist/core/canvas/source.js

@@ -22,8 +22,11 @@ export class LocalCanvasSource {
     async view(root) {
         return view(root);
     }
+    async ticketCountsForNodes(nodeIds) {
+        return ticketCountsForNodes([...nodeIds]);
+    }
     async ticketCountsForView(root) {
-        return ticketCountsForNodes([root, ...view(root)]);
+        return this.ticketCountsForNodes([root, ...view(root)]);
     }
     async hasActiveLiveSubscription(nodeId) {
         return hasActiveLiveSubscription(nodeId);

package/dist/core/command-hooks/artifact.d.ts

@@ -1,9 +1,15 @@
 import type { PluginManifest } from '../../types.js';
 import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface LifecycleDeclarationCandidate {
+    event: string;
+    op: string;
+    index: number;
+}
 export interface HookArtifactValidation {
     manifestPath?: string;
     executablePath?: string;
     manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
     issues: HookManifestIssue[];
 }
 /** Statically validates the local hook artifact a source plugin ships. */