@north-light/crouter 0.3.154

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

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

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

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

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

@@ -0,0 +1,241 @@
+// render-remote.test.ts — the safe-defaults contract for `render.ts`'s
+// `*FromSource` functions when given a `RemoteCanvasSource`: every field that
+// would require a local disk/SQLite read (hanging, streaming, viewed, ctx
+// tokens, asks, goal, prompts, lastAssistant) must come back suppressed to
+// its safe default instead of touching this process's local state. Reuses
+// the mock-server harness shape from `remote-canvas-source.test.ts`.
+//
+// This is adversarial, not merely a clean-machine assertion: BEFORE calling
+// the render functions, the test seeds real, CONFLICTING local state for the
+// same node id `a` (a local focus, an active fault, telemetry, a goal file, a
+// session transcript, and a pending human ask) — every historically-broken
+// local read this suppression covers. If the production suppression ever
+// regressed back to consulting local disk/SQLite for a remote source, the
+// assertions below would observe the poisoned values instead of the safe
+// defaults, so a clean-machine run could never mask the regression.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson, deckPath } from '@crouton-kit/humanloop';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
+import { createNode } from '../canvas.js';
+import { closeDb } from '../db.js';
+import { openFocusRow } from '../focuses.js';
+import { jobDir, contextDir, nodeDir } from '../paths.js';
+import { recordFault } from '../../runtime/fault.js';
+function startMockCrtrServer(route) {
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const bodyText = Buffer.concat(chunks).toString('utf8');
+                const parsed = JSON.parse(bodyText);
+                const result = route(parsed.args);
+                res.writeHead(result.status ?? 200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(result.body), stderr: '' }));
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+function meta(id, extra) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...extra,
+    };
+}
+function row(id) {
+    return {
+        node_id: id,
+        name: id,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        cwd: '/tmp/work',
+        host_kind: null,
+        profile_id: null,
+        parent: null,
+        created: new Date().toISOString(),
+        intent: null,
+        waiting_for: null,
+        pi_pid: null,
+        pi_pid_identity: null,
+        window: null,
+        tmux_session: null,
+        pane: null,
+    };
+}
+test('dashboardRowsAllFromSource shows a node watched through its live broker', async () => {
+    const localRow = row('watched');
+    mkdirSync(jobDir('watched'), { recursive: true });
+    writeFileSync(join(jobDir('watched'), 'attach.json'), JSON.stringify({ viewers: 1 }));
+    const source = {
+        getNode: async () => meta('watched'),
+        getRow: async () => localRow,
+        listNodes: async () => [localRow],
+        subscriptionsOf: async () => [],
+        subscribersOf: async () => [],
+        view: async () => [],
+        ticketCountsForView: async () => ({}),
+        hasActiveLiveSubscription: async () => false,
+    };
+    const rows = await dashboardRowsAllFromSource(source);
+    assert.equal(rows[0]?.viewed, true);
+});
+let home;
+let localCwd;
+let sessionFile;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-render-remote-'));
+    localCwd = mkdtempSync(join(tmpdir(), 'crtr-render-remote-cwd-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(nodeDir('poison-ask'), { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(localCwd, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+/** Seed conflicting local state for node id `a` — every local read
+ *  `*FromSource`'s remote suppression is supposed to bypass. Returns the
+ *  poisoned session-file path so the mocked `node inspect show` response can
+ *  point `pi_session_file` at it (the vector a regression would follow). */
+function seedPoisonedLocalState() {
+    // A local node row + a pending ticket under its cwd — poisons `ticketCountsForNodes`.
+    createNode(meta('a', { cwd: localCwd }));
+    const askDir = nodeDir('poison-ask');
+    mkdirSync(askDir, { recursive: true });
+    atomicWriteJson(deckPath(askDir), {
+        title: 'poison',
+        interactions: [{ id: 'q', kind: 'ask', title: 'poison', subtitle: 'This local ticket must not affect the remote rendering.' }],
+    });
+    // A local focus + broker viewer — poison both `viewed` signals.
+    openFocusRow('poison-focus', null, null, 'a');
+    writeFileSync(join(jobDir('a'), 'attach.json'), JSON.stringify({ viewers: 1 }));
+    // A local active fault — poisons `hanging`.
+    recordFault('a', {
+        link: 'viewer↔broker',
+        op: 'poison',
+        kind: 'other',
+        retry: { disposition: 'manual' },
+        message: 'POISON FAULT — local read leaked into remote render',
+    });
+    // Local telemetry — poisons `ctx_tokens`.
+    writeFileSync(join(jobDir('a'), 'telemetry.json'), JSON.stringify({ tokens_in: 999999 }));
+    // A local goal file — poisons `goal`.
+    writeFileSync(join(contextDir('a'), 'initial-prompt.md'), 'POISON GOAL — local read leaked into remote render');
+    // A local session transcript — poisons `prompts`/`lastAssistant`.
+    const sf = join(home, 'poison-session.jsonl');
+    writeFileSync(sf, [
+        JSON.stringify({ type: 'message', message: { role: 'user', content: 'POISON PROMPT' } }),
+        JSON.stringify({ type: 'message', message: { role: 'assistant', content: 'POISON ASSISTANT REPLY' } }),
+    ].join('\n'));
+    return sf;
+}
+test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource suppress every local-read field to its safe default for a RemoteCanvasSource, even with conflicting local state for the same node id', async (t) => {
+    sessionFile = seedPoisonedLocalState();
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
+            return { body: { nodes: [row('a')] } };
+        }
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return {
+                body: {
+                    // pi_session_file points at the poisoned local transcript above — if
+                    // the remote suppression regressed and read it anyway, `prompts`/
+                    // `lastAssistant` below would come back non-empty.
+                    node: meta(args[4], { pi_session_file: sessionFile }),
+                    reports: [],
+                    managers: [],
+                    artifacts: { report: 0, doc: 0, roadmap: 0 },
+                    pending_crons: 0,
+                    paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+                    follow_up: '',
+                },
+            };
+        }
+        return { status: 500, body: {} };
+    });
+    // Register the close BEFORE any assertion runs — a listening server left
+    // open by a thrown assertion keeps this test file's process alive forever
+    // (see the CI-hang postmortem on rebuild-coalescer.test.ts).
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const rows = await dashboardRowsAllFromSource(source);
+    assert.equal(rows.length, 1);
+    const r = rows[0];
+    assert.equal(r.hanging, null, 'local active fault must not leak into a remote row');
+    assert.equal(r.streaming, false);
+    assert.equal(r.viewed, false, 'local focus must not leak into a remote row');
+    await enrichRowsFromSource(source, rows);
+    assert.equal(r.ctx_tokens, 0, 'local telemetry must not leak into a remote row');
+    assert.equal(r.asks, 0, 'a local pending ask for the same node id must not leak into a remote row');
+    assert.equal(r.enriched, true);
+    const previewed = await loadPreviewFromSource(source, r);
+    assert.equal(previewed.goal, undefined, 'a local goal file must not leak into a remote preview');
+    assert.equal(previewed.prompts, undefined, 'a local session transcript must not leak into a remote preview');
+    assert.equal(previewed.lastAssistant, undefined, 'a local session transcript must not leak into a remote preview');
+    assert.equal(previewed.previewLoaded, true);
+});
+// The non-TTY `canvas browse` path (browse/app.ts's `if (!process.stdin.isTTY)`
+// branch) calls `renderForestFromSource(source)` directly — a SEPARATE code
+// path from `dashboardRowsAllFromSource`/`enrichRowsFromSource`/
+// `loadPreviewFromSource` above, with its own remote suppression in
+// `renderTreeFromSource`/`nodeLineFromSource` (render.ts). The poisoned-state
+// test above never exercises it, so a regression that reintroduced local
+// telemetry/ask/fault reads into the static forest renderer specifically would
+// pass that test while still leaking poisoned local state here.
+test('renderForestFromSource suppresses local-read fields (ctx, asks, hanging) for a RemoteCanvasSource, even with conflicting local state for the same node id', async (t) => {
+    const sf = seedPoisonedLocalState();
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
+            return { body: { nodes: [row('a')] } };
+        }
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return {
+                body: {
+                    node: meta(args[4], { pi_session_file: sf }),
+                    reports: [],
+                    managers: [],
+                    artifacts: { report: 0, doc: 0, roadmap: 0 },
+                    pending_crons: 0,
+                    paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+                    follow_up: '',
+                },
+            };
+        }
+        return { status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const out = await renderForestFromSource(source);
+    assert.match(out, /ctx 0k/, 'the remote node must render with the suppressed ctx default, not a real token read');
+    assert.doesNotMatch(out, /⚑/, 'no ask badge — local asks must not leak into the static forest render');
+    assert.doesNotMatch(out, /POISON FAULT/, 'a local active fault must not leak into the static forest render');
+    assert.doesNotMatch(out, /POISON/, 'no poisoned local telemetry/goal/session text may appear anywhere in the output');
+});

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

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

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

@@ -0,0 +1,77 @@
+// source-resolve.test.ts — `resolveCanvasSource` (`../source.ts`), the
+// --canvas > activeCanvas > local precedence a command's read path goes
+// through. The one invariant worth pinning: the local case returns the SAME
+// `localCanvasSource` singleton by identity, not a structurally-equal copy —
+// callers that hold onto a source reference (e.g. `canvas browse`'s
+// `instanceof RemoteCanvasSource` checks) depend on that.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveCanvasSource, localCanvasSource } from '../source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { updateConfig, updateState } from '../../config.js';
+import { setRelayToken } from '../../secrets.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-source-resolve-'));
+    process.env['HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('no --canvas and no activeCanvas resolves to the local singleton by identity', () => {
+    const source = resolveCanvasSource();
+    assert.equal(source, localCanvasSource);
+});
+test('an explicit canvasName wins over local, even with no activeCanvas set', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'tok', 'user');
+    const source = resolveCanvasSource({ canvasName: 'cloud' });
+    assert.ok(source instanceof RemoteCanvasSource);
+    assert.notEqual(source, localCanvasSource);
+});
+test('the durable activeCanvas selection is honored when no explicit canvasName is passed', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'tok', 'user');
+    updateState('user', (s) => {
+        s.activeCanvas = 'cloud';
+    });
+    const source = resolveCanvasSource();
+    assert.ok(source instanceof RemoteCanvasSource);
+});
+test('an explicit --canvas wins over a different durable activeCanvas selection', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud-a'] = { previewEndpoint: 'https://a.preview.bl.run', relayTokenRef: 'cloud-a' };
+        cfg.remoteCanvas.targets['cloud-b'] = { previewEndpoint: 'https://b.preview.bl.run', relayTokenRef: 'cloud-b' };
+    });
+    setRelayToken('cloud-a', 'tok-a', 'user');
+    setRelayToken('cloud-b', 'tok-b', 'user');
+    updateState('user', (s) => {
+        s.activeCanvas = 'cloud-a';
+    });
+    const source = resolveCanvasSource({ canvasName: 'cloud-b' });
+    assert.ok(source instanceof RemoteCanvasSource);
+    assert.equal(source.previewEndpoint, 'https://b.preview.bl.run');
+});
+test('activeCanvas set to null (explicit local) falls back to the local singleton', () => {
+    updateState('user', (s) => {
+        s.activeCanvas = null;
+    });
+    const source = resolveCanvasSource();
+    assert.equal(source, localCanvasSource);
+});

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

@@ -0,0 +1,19 @@
+export interface TicketEntry {
+    node_id: string;
+    name: string;
+    cwd: string;
+    count: number;
+}
+/** Drop the cached walk. Callers that swap the canvas home out from under a live
+ *  process (tests, and any in-process home switch) must call this: the cache is
+ *  keyed only by time, so a stale window would otherwise serve the old home's
+ *  counts. */
+export declare function invalidateTicketCounts(): void;
+/** Count pending tickets asked by one node. */
+export declare function countTickets(nodeId: string): number;
+/** Pending tickets for every reachable asking node, including the root. */
+export declare function pendingTicketsForView(rootId: string): TicketEntry[];
+/** Per-node pending ticket counts for an explicit node set. */
+export declare function ticketCountsForNodes(ids: string[]): Record<string, number>;
+/** Pending tickets across the entire canvas, attributed to asking nodes. */
+export declare function ticketsAcrossCanvas(): TicketEntry[];

package/dist/core/canvas/attention.js

@@ -0,0 +1,87 @@
+// attention.ts — pending human-ticket counters across the canvas.
+//
+// Every ticket is a direct child of the single registered `<canvas>/nodes` root,
+// named for its terminal human bridge node. The bridge's parent is the asking
+// node, so storage identity and attribution come from the canvas graph rather
+// than duplicated attribution fields in deck/review data.
+import { basename } from 'node:path';
+import { scanInbox } from '@crouton-kit/humanloop';
+import { nodesRoot } from './paths.js';
+import { getNode, listNodes, view } from './canvas.js';
+function askingNodeId(ticketDir) {
+    const bridge = getNode(basename(ticketDir));
+    if (bridge === null)
+        return null;
+    return bridge.parent ?? bridge.node_id;
+}
+/** `scanInbox` walks EVERY node dir under `<canvas>/nodes` (thousands on a large
+ *  canvas, ~50ms) and returns the same map for every caller in a moment, yet the
+ *  per-node/per-view count reads fan out — the canvas browser alone asks once per
+ *  forest root (hundreds of calls per snapshot). Uncached, that serialized
+ *  crtrd's single-threaded event loop behind minutes of identical disk walks and
+ *  stalled the browse open. One walk per window serves the whole burst; a ticket
+ *  raised or answered inside the window badges on the next one (the viewers that
+ *  read this poll on a multi-second cadence). */
+const TICKET_COUNT_TTL_MS = 1000;
+let ticketCountCache = null;
+/** Drop the cached walk. Callers that swap the canvas home out from under a live
+ *  process (tests, and any in-process home switch) must call this: the cache is
+ *  keyed only by time, so a stale window would otherwise serve the old home's
+ *  counts. */
+export function invalidateTicketCounts() {
+    ticketCountCache = null;
+}
+function ticketCounts() {
+    const now = Date.now();
+    if (ticketCountCache !== null && now - ticketCountCache.at < TICKET_COUNT_TTL_MS) {
+        return ticketCountCache.counts;
+    }
+    const counts = new Map();
+    try {
+        for (const ticket of scanInbox([nodesRoot()])) {
+            const nodeId = askingNodeId(ticket.dir);
+            if (nodeId !== null)
+                counts.set(nodeId, (counts.get(nodeId) ?? 0) + 1);
+        }
+    }
+    catch {
+        // Humanloop unavailable or an absent root has no display consequence.
+    }
+    ticketCountCache = { at: Date.now(), counts };
+    return counts;
+}
+/** Count pending tickets asked by one node. */
+export function countTickets(nodeId) {
+    return ticketCounts().get(nodeId) ?? 0;
+}
+/** Pending tickets for every reachable asking node, including the root. */
+export function pendingTicketsForView(rootId) {
+    const counts = ticketCounts();
+    const entries = [];
+    for (const id of [rootId, ...view(rootId)]) {
+        const node = getNode(id);
+        const count = counts.get(id) ?? 0;
+        if (node !== null && count > 0)
+            entries.push({ node_id: id, name: node.name, cwd: node.cwd, count });
+    }
+    return entries;
+}
+/** Per-node pending ticket counts for an explicit node set. */
+export function ticketCountsForNodes(ids) {
+    const found = ticketCounts();
+    const counts = {};
+    for (const id of ids)
+        counts[id] = found.get(id) ?? 0;
+    return counts;
+}
+/** Pending tickets across the entire canvas, attributed to asking nodes. */
+export function ticketsAcrossCanvas() {
+    const counts = ticketCounts();
+    const entries = [];
+    for (const node of listNodes()) {
+        const count = counts.get(node.node_id) ?? 0;
+        if (count > 0)
+            entries.push({ node_id: node.node_id, name: node.name, cwd: node.cwd, count });
+    }
+    return entries;
+}

package/dist/core/canvas/boot-id.d.ts

@@ -0,0 +1,6 @@
+/** The Linux kernel's per-boot identity at `/proc/sys/kernel/random/boot_id` —
+ *  a fresh random UUID minted on every kernel boot, or null when unreadable
+ *  (non-Linux dev, or the file is absent). Exact when present: a microVM
+ *  recreate boots a new kernel (new id); a plain daemon restart within the same
+ *  boot leaves it identical. */
+export declare function readKernelBootId(): string | null;

package/dist/core/canvas/boot-id.js

@@ -0,0 +1,26 @@
+// boot-id.ts — the PURE kernel-boot-identity reader, split out of boot.ts so the
+// low-level liveness probe (`canvas/pid.ts`) can import it WITHOUT dragging in
+// boot.ts's `openDb` persistence machinery. boot.ts's boot-change reconciler
+// persists the last-seen identity in canvas.db (hence its top-level `openDb`
+// import); `readKernelBootId` itself is a plain `/proc` read with zero db reach,
+// and `pid.ts` needs only that. Keeping it here means `pid.ts` (and everything
+// that imports it down — including the CLI's daemon-liveness front door) stays
+// canvas.db-free.
+//
+// PURITY: Node built-ins only. Never `core/canvas/db.js` or any db-touching
+// module.
+import { readFileSync } from 'node:fs';
+/** The Linux kernel's per-boot identity at `/proc/sys/kernel/random/boot_id` —
+ *  a fresh random UUID minted on every kernel boot, or null when unreadable
+ *  (non-Linux dev, or the file is absent). Exact when present: a microVM
+ *  recreate boots a new kernel (new id); a plain daemon restart within the same
+ *  boot leaves it identical. */
+export function readKernelBootId() {
+    try {
+        const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        return id.length > 0 ? id : null;
+    }
+    catch {
+        return null; // non-Linux, or unreadable — fall back to the wall-clock epoch
+    }
+}