@crouton-kit/crouter 0.3.66 → 0.3.67

package/dist/core/canvas/browse/rebuild-coalescer.js

@@ -0,0 +1,61 @@
+// rebuild-coalescer.ts — single-flight + debounce coalescing for a burst of
+// SSE-triggered rebuilds (`canvas browse`'s remote path — see app.ts).
+//
+// A remote `RemoteEventStream` `nodes`/`inbox` event means "invalidate + re-pull
+// the tree", which for a remote source costs one `node inspect list` plus N
+// `node inspect show` round trips. A burst of events (several nodes changing at
+// once) must NOT fan into one overlapping rebuild per event — it must collapse
+// to one rebuild per burst. This module is the pure, TTY-free coalescing policy
+// so it can be unit-tested without the raw-mode stdin loop in app.ts:
+//
+//   - `trigger()` debounces a burst into ONE rebuild call after `debounceMs` of
+//     quiet.
+//   - if a rebuild is already in flight when the debounce fires (or another
+//     trigger lands mid-rebuild), it does NOT launch an overlapping rebuild —
+//     it marks exactly one trailing rebuild to run immediately after the
+//     in-flight one finishes.
+//
+// Net effect: N events in a burst → 1 rebuild (or, if the burst spans an
+// in-flight rebuild, 2: the one already running + one trailing catch-up) —
+// never N overlapping rebuilds.
+export function createCoalescedRebuilder(rebuild, debounceMs = 200) {
+    let timer;
+    let inFlight = false;
+    let pending = false;
+    const run = () => {
+        inFlight = true;
+        void rebuild().finally(() => {
+            inFlight = false;
+            if (pending) {
+                // A trailing catch-up was armed while this rebuild ran — fire it
+                // immediately (no further debounce: the just-finished rebuild WAS the
+                // quiet period), collapsing every event that landed mid-flight into
+                // exactly one follow-up rebuild, not one per event.
+                pending = false;
+                run();
+            }
+        });
+    };
+    const trigger = () => {
+        if (inFlight) {
+            // Already rebuilding — mark one trailing catch-up instead of starting a
+            // second overlapping rebuild or re-arming the debounce timer (which
+            // would keep pushing the catch-up back on every further event).
+            pending = true;
+            return;
+        }
+        if (timer !== undefined)
+            return; // already debounced in this quiet window
+        timer = setTimeout(() => {
+            timer = undefined;
+            run();
+        }, debounceMs);
+    };
+    const stop = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    return { trigger, stop };
+}

package/dist/core/canvas/browse/render.d.ts

@@ -29,6 +29,10 @@ export interface RenderState {
      *  a descendant) is actively streaming. Holds the node id being confirmed; the
      *  footer becomes the y/n prompt. null/undefined = no pending confirm. */
     pendingClose?: string | null;
+    /** Set when the source is a remote canvas: mutation/focus keys (`x`/`K`/Enter)
+     *  are disabled, so the footer drops their hints instead of advertising a
+     *  dead action. undefined/false = local, byte-identical footer. */
+    readOnly?: boolean;
 }
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints

package/dist/core/canvas/browse/render.js

@@ -479,7 +479,9 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
         const footer = state.search
             ? '⏎ commit  Esc cancel  ⌫ delete'
-            : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
+            : state.readOnly === true
+                ? '↑↓ move  →/← tree  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit  — read-only remote canvas'
+                : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
         lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     }
     // Assemble: home, each line cleared to EOL, then clear below.

package/dist/core/canvas/nav-model.d.ts

@@ -19,8 +19,10 @@ export declare const YELLOW = "\u001B[33m";
 export declare const CYAN = "\u001B[36m";
 export declare const GRAY = "\u001B[90m";
 /** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
- *  outranks the base status glyph. */
-export declare function nodeGlyph(node: NodeMeta | null): string;
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export declare function nodeGlyph(node: NodeMeta | null, remote?: boolean): string;
 /** Visible width, ignoring ANSI escapes. */
 export declare function visibleWidth(s: string): number;
 /** Truncate to `max` VISIBLE columns: escape sequences are copied through
@@ -59,11 +61,14 @@ export interface Telemetry {
 export declare function readTelemetry(nodeId: string): Telemetry;
 export declare function fmtTokens(n: number): string;
 /** The context-window cell — live window fill rounded to the nearest 1k (the same
- *  figure pi's footer shows), NOT a per-turn token delta. */
-export declare function tokensCell(id: string): string;
+ *  figure pi's footer shows), NOT a per-turn token delta. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export declare function tokensCell(id: string, remote?: boolean): string;
 /** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
- *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
-export declare function activityCell(id: string, node: NodeMeta | null): string;
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export declare function activityCell(id: string, node: NodeMeta | null, remote?: boolean): string;
 /** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
 export declare function cycleBadge(node: NodeMeta | null): string;
 /** Short on-screen label: the explicit handle when set, else the pi-generated
@@ -71,10 +76,14 @@ export declare function cycleBadge(node: NodeMeta | null): string;
  *  the nav chrome shows just the first so rows stay compact. */
 export declare function navLabel(node: NodeMeta | null, id: string): string;
 export declare function shortId(id: string): string;
-/** Node ids currently shown in a tmux focus viewport. Built once per render. */
-export declare function focusedNodeIds(): Set<string>;
-/** True when a human is watching `id` right now (tmux focus or broker viewer). */
-export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>): boolean;
+/** Node ids currently shown in a tmux focus viewport. Built once per render.
+ *  `remote` skips the local `listFocuses()` SQLite read entirely and reports
+ *  none focused (a remote node id may collide with a local one). */
+export declare function focusedNodeIds(remote?: boolean): Set<string>;
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>, remote?: boolean): boolean;
 export declare function fetchAsksMap(rootId: string): Record<string, number>;
 /** First manager (by created) — the UP step for the ancestry spine. */
 export declare function managerOf(id: string): string | undefined;

package/dist/core/canvas/nav-model.js

@@ -63,11 +63,16 @@ function streamingFor(node) {
     return isBusy(node.node_id);
 }
 /** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
- *  outranks the base status glyph. */
-export function nodeGlyph(node) {
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export function nodeGlyph(node, remote = false) {
     if (node === null)
         return '?';
-    const v = resolveNodeVisual(node.status, { streaming: streamingFor(node), hanging: hangingFor(node) });
+    const v = resolveNodeVisual(node.status, {
+        streaming: remote ? false : streamingFor(node),
+        hanging: remote ? null : hangingFor(node),
+    });
     return `${ESC}${v.color}m${v.glyph}${RESET}`;
 }
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
@@ -205,13 +210,18 @@ export function fmtTokens(n) {
     return n < 1_000 ? `${n}` : `${Math.round(n / 1_000)}k`;
 }
 /** The context-window cell — live window fill rounded to the nearest 1k (the same
- *  figure pi's footer shows), NOT a per-turn token delta. */
-export function tokensCell(id) {
-    return fmtTokens(readTelemetry(id).context_tokens ?? 0);
+ *  figure pi's footer shows), NOT a per-turn token delta. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export function tokensCell(id, remote = false) {
+    return fmtTokens(remote ? 0 : (readTelemetry(id).context_tokens ?? 0));
 }
 /** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
- *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
-export function activityCell(id, node) {
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export function activityCell(id, node, remote = false) {
+    if (remote)
+        return '';
     if (node?.status !== 'active')
         return '';
     const a = (readTelemetry(id).last_activity ?? '').trim();
@@ -248,8 +258,12 @@ export function shortId(id) {
 //                 (src/core/runtime/broker.ts). Trusted only while the node is
 //                 'active': a broker crash can leave a stale file.
 // ---------------------------------------------------------------------------
-/** Node ids currently shown in a tmux focus viewport. Built once per render. */
-export function focusedNodeIds() {
+/** Node ids currently shown in a tmux focus viewport. Built once per render.
+ *  `remote` skips the local `listFocuses()` SQLite read entirely and reports
+ *  none focused (a remote node id may collide with a local one). */
+export function focusedNodeIds(remote = false) {
+    if (remote)
+        return new Set();
     try {
         return new Set(listFocuses().map((f) => f.node_id));
     }
@@ -257,8 +271,12 @@ export function focusedNodeIds() {
         return new Set();
     }
 }
-/** True when a human is watching `id` right now (tmux focus or broker viewer). */
-export function isAttached(id, node, focused) {
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export function isAttached(id, node, focused, remote = false) {
+    if (remote)
+        return false;
     if (focused.has(id))
         return true;
     if (node?.status !== 'active')

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

@@ -0,0 +1,62 @@
+import type { CanvasSource } from './source.js';
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+/** The exact JSON shape `crtr --json node inspect show <id>` emits (see
+ *  `nodeShow`'s `run`, `src/commands/node.ts`) — mirrored here, not imported,
+ *  to avoid a commands→canvas value dependency. */
+export interface RemoteShowResponse {
+    node: NodeMeta;
+    reports: {
+        node_id: string;
+        name: string;
+        kind: string;
+        status: string;
+        active: boolean;
+    }[];
+    managers: {
+        node_id: string;
+        name: string;
+        kind: string;
+        status: string;
+        active: boolean;
+    }[];
+    artifacts: {
+        report: number;
+        doc: number;
+        roadmap: number;
+    };
+    pending_triggers: number;
+    paths: {
+        context_dir: string;
+        reports_dir: string;
+        session_file: string | null;
+    };
+    follow_up: string;
+}
+export declare class RemoteCanvasSource implements CanvasSource {
+    private readonly previewEndpoint;
+    private readonly relayToken;
+    private readonly exec;
+    private nodeCache;
+    private rosterCache;
+    private viewCache;
+    constructor(previewEndpoint: string, relayToken: string);
+    /** Drops every cached entry — called on a `RemoteEventStream` `'nodes'` (or
+     *  `'inbox'`) event so the next read re-fetches fresh state. */
+    invalidate(): void;
+    private execJson;
+    private fetchShow;
+    /** The full passthrough object `node inspect show` produces — used by
+     *  `nodeShow`'s remote branch (`src/commands/node.ts`) to return the exact
+     *  same shape a local read would, without re-deriving it. */
+    rawShow(id: string): Promise<RemoteShowResponse | null>;
+    getNode(id: string): Promise<NodeMeta | null>;
+    getRow(id: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(id: string): Promise<SubscriptionRef[]>;
+    subscribersOf(id: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    askCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(id: string): Promise<boolean>;
+}

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

@@ -0,0 +1,222 @@
+// remote-canvas-source.ts — a CanvasSource backed by a remote canvas over the
+// relay-token-authed `/__crtr/source` transport (see `transport-remote.ts`).
+// Every method shells out to an EXISTING `crtr --json <subcommand>` in-guest —
+// no new in-guest command, no remote SQLite read, no drive-plane verb. A
+// short-TTL cache coalesces the fan-out a single browse/inspect frame would
+// otherwise make into the same node.
+import { createRemoteExec } from '../view/transport-remote.js';
+const CACHE_TTL_MS = 1000;
+// ---------------------------------------------------------------------------
+// Remote JSON shape validation.
+//
+// `execJson<T>` parses stdout and casts it to T with NO structural check — a
+// remote subprocess that exits 0 with a wrong shape (e.g. `{}`, `{node:null}`)
+// would otherwise pass through as a "valid" T. `fetchShow`/`listNodes`/
+// `askCountsForView` validate before caching/returning; on a shape mismatch
+// they degrade exactly like the existing network-failure path (null/[]/{}),
+// never a malformed object a caller might dereference.
+// ---------------------------------------------------------------------------
+function isPlainObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function isValidShowResponse(x) {
+    if (!isPlainObject(x))
+        return false;
+    const node = x['node'];
+    if (!isPlainObject(node) || typeof node['node_id'] !== 'string')
+        return false;
+    if (!Array.isArray(x['reports']) || !Array.isArray(x['managers']))
+        return false;
+    const artifacts = x['artifacts'];
+    if (!isPlainObject(artifacts) ||
+        typeof artifacts['report'] !== 'number' ||
+        typeof artifacts['doc'] !== 'number' ||
+        typeof artifacts['roadmap'] !== 'number')
+        return false;
+    if (typeof x['pending_triggers'] !== 'number')
+        return false;
+    const paths = x['paths'];
+    if (!isPlainObject(paths) ||
+        typeof paths['context_dir'] !== 'string' ||
+        typeof paths['reports_dir'] !== 'string' ||
+        (paths['session_file'] !== null && typeof paths['session_file'] !== 'string'))
+        return false;
+    if (typeof x['follow_up'] !== 'string')
+        return false;
+    return true;
+}
+/** A `reports`/`managers` entry (`RemoteShowResponse`) — validated per-element
+ *  because `isValidShowResponse` only checks the array wrapper. Without this,
+ *  a malformed neighbor (`null`, `{}`) survives into `subscriptionsOf`/
+ *  `subscribersOf`'s `.map()` and node.ts's remote `show` passthrough render,
+ *  both of which dereference `.node_id`/`.active` unguarded. */
+function isValidNeighborEntry(x) {
+    return (isPlainObject(x) &&
+        typeof x['node_id'] === 'string' &&
+        typeof x['name'] === 'string' &&
+        typeof x['kind'] === 'string' &&
+        typeof x['status'] === 'string' &&
+        typeof x['active'] === 'boolean');
+}
+/** A `NodeRow` element from `node inspect list`'s `nodes` array — validated
+ *  per-element because a remote success payload can be `{nodes:[null]}` (the
+ *  outer array check alone lets that through). Requires the string identity/
+ *  lifecycle fields browse's tree-building code dereferences unguarded
+ *  (`browse/app.ts`'s `rebuildSnapshot`); the remaining nullable runtime
+ *  fields (host_kind, parent, pi_pid, ...) are left to cast through as-is. */
+function isValidNodeRow(x) {
+    if (!isPlainObject(x))
+        return false;
+    return (typeof x['node_id'] === 'string' &&
+        typeof x['name'] === 'string' &&
+        typeof x['kind'] === 'string' &&
+        typeof x['mode'] === 'string' &&
+        typeof x['lifecycle'] === 'string' &&
+        typeof x['status'] === 'string' &&
+        typeof x['cwd'] === 'string' &&
+        typeof x['created'] === 'string');
+}
+export class RemoteCanvasSource {
+    previewEndpoint;
+    relayToken;
+    exec;
+    nodeCache = new Map();
+    rosterCache = new Map();
+    viewCache = new Map();
+    constructor(previewEndpoint, relayToken) {
+        this.previewEndpoint = previewEndpoint;
+        this.relayToken = relayToken;
+        this.exec = createRemoteExec(previewEndpoint, relayToken);
+    }
+    /** Drops every cached entry — called on a `RemoteEventStream` `'nodes'` (or
+     *  `'inbox'`) event so the next read re-fetches fresh state. */
+    invalidate() {
+        this.nodeCache.clear();
+        this.rosterCache.clear();
+        this.viewCache.clear();
+    }
+    async execJson(args) {
+        let raw;
+        try {
+            raw = await this.exec('crtr', ['--json', ...args]);
+        }
+        catch {
+            return null;
+        }
+        if (!raw.ok)
+            return null;
+        if (raw.exitCode !== undefined && raw.exitCode !== 0)
+            return null;
+        try {
+            return JSON.parse(raw.stdout.trim());
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchShow(id) {
+        const cached = this.nodeCache.get(id);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const raw = await this.execJson(['node', 'inspect', 'show', id]);
+        // Sanitize reports/managers elements here (not just the outer array shape)
+        // so both consumers — subscriptionsOf/subscribersOf's `.map()` below AND
+        // node.ts's remote `show` passthrough render — see only well-formed
+        // neighbor entries, never a malformed one they'd dereference unguarded.
+        const res = isValidShowResponse(raw)
+            ? { ...raw, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
+            : null;
+        this.nodeCache.set(id, { value: res, at: Date.now() });
+        return res;
+    }
+    /** The full passthrough object `node inspect show` produces — used by
+     *  `nodeShow`'s remote branch (`src/commands/node.ts`) to return the exact
+     *  same shape a local read would, without re-deriving it. */
+    async rawShow(id) {
+        return this.fetchShow(id);
+    }
+    async getNode(id) {
+        return (await this.fetchShow(id))?.node ?? null;
+    }
+    async getRow(id) {
+        const n = (await this.fetchShow(id))?.node;
+        if (!n)
+            return null;
+        return {
+            node_id: n.node_id,
+            name: n.name,
+            kind: n.kind,
+            mode: n.mode,
+            lifecycle: n.lifecycle,
+            status: n.status,
+            cwd: n.cwd,
+            host_kind: n.host_kind ?? null,
+            profile_id: n.profile_id ?? null,
+            parent: n.parent ?? null,
+            created: n.created,
+            intent: n.intent ?? null,
+            pi_pid: n.pi_pid ?? null,
+            pi_pid_identity: n.pi_pid_identity ?? null,
+            window: n.window ?? null,
+            tmux_session: n.tmux_session ?? null,
+            pane: n.pane ?? null,
+        };
+    }
+    async listNodes(filter) {
+        const key = JSON.stringify(filter?.status ?? null);
+        const cached = this.rosterCache.get(key);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const args = ['node', 'inspect', 'list'];
+        if (filter?.status) {
+            args.push('--status', (Array.isArray(filter.status) ? filter.status : [filter.status]).join(','));
+        }
+        const res = await this.execJson(args);
+        const rawNodes = isPlainObject(res) && Array.isArray(res['nodes']) ? res['nodes'] : [];
+        const nodes = rawNodes.filter(isValidNodeRow);
+        this.rosterCache.set(key, { value: nodes, at: Date.now() });
+        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: '' }));
+    }
+    async subscribersOf(id) {
+        const managers = (await this.fetchShow(id))?.managers ?? [];
+        return managers.map((r) => ({ node_id: r.node_id, active: r.active, created: '' }));
+    }
+    async view(root) {
+        const cached = this.viewCache.get(root);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const seen = new Set([root]);
+        const out = [];
+        const queue = (await this.subscriptionsOf(root)).map((s) => s.node_id);
+        while (queue.length > 0) {
+            const id = queue.shift();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push(id);
+            for (const s of await this.subscriptionsOf(id)) {
+                if (!seen.has(s.node_id))
+                    queue.push(s.node_id);
+            }
+        }
+        this.viewCache.set(root, { value: out, at: Date.now() });
+        return out;
+    }
+    async askCountsForView(root) {
+        const res = await this.execJson(['canvas', 'attention', 'map', '--view', root]);
+        return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
+    }
+    async hasActiveLiveSubscription(id) {
+        const subs = (await this.subscriptionsOf(id)).filter((s) => s.active);
+        for (const s of subs) {
+            const row = await this.getRow(s.node_id);
+            if (row && (row.status === 'active' || row.status === 'idle'))
+                return true;
+        }
+        return false;
+    }
+}

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

@@ -0,0 +1,24 @@
+export type RemoteEventKind = 'nodes' | 'inbox';
+export interface RemoteEventStreamOptions {
+    /** Initial reconnect backoff (ms). Default 1000; injectable so tests don't
+     *  have to wait out the production backoff window. */
+    initialBackoffMs?: number;
+    /** Reconnect backoff cap (ms). Default 30_000. */
+    backoffCapMs?: number;
+}
+export declare class RemoteEventStream {
+    private readonly previewEndpoint;
+    private readonly relayToken;
+    private controller;
+    private stopped;
+    private readonly listeners;
+    private readonly initialBackoffMs;
+    private backoffMs;
+    private readonly BACKOFF_CAP_MS;
+    private reconnectTimer;
+    constructor(previewEndpoint: string, relayToken: string, opts?: RemoteEventStreamOptions);
+    subscribe(fn: (kind: RemoteEventKind) => void): () => void;
+    start(): void;
+    stop(): void;
+    private loop;
+}

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

@@ -0,0 +1,94 @@
+// remote-event-stream.ts — a Node SSE client over a remote canvas's
+// `/__crtr/events` endpoint, driving cache invalidation + re-render for a
+// remote-backed `canvas browse`/viewer. No new npm dependency: Node 18+
+// `fetch` returns a web-standard `ReadableStream` body, read manually with
+// `getReader()` + `TextDecoder` and split on the SSE `\n\n` event delimiter.
+export class RemoteEventStream {
+    previewEndpoint;
+    relayToken;
+    controller;
+    stopped = false;
+    listeners = new Set();
+    initialBackoffMs;
+    backoffMs;
+    BACKOFF_CAP_MS;
+    reconnectTimer;
+    constructor(previewEndpoint, relayToken, opts = {}) {
+        this.previewEndpoint = previewEndpoint;
+        this.relayToken = relayToken;
+        this.initialBackoffMs = opts.initialBackoffMs ?? 1000;
+        this.backoffMs = this.initialBackoffMs;
+        this.BACKOFF_CAP_MS = opts.backoffCapMs ?? 30_000;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    start() {
+        this.stopped = false;
+        void this.loop();
+    }
+    stop() {
+        this.stopped = true;
+        this.controller?.abort();
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    async loop() {
+        while (!this.stopped) {
+            this.controller = new AbortController();
+            try {
+                const res = await fetch(new URL('/__crtr/events', this.previewEndpoint), {
+                    headers: { authorization: `Bearer ${this.relayToken}` },
+                    signal: this.controller.signal,
+                });
+                if (!res.ok || !res.body)
+                    throw new Error(`events ${res.status}`);
+                this.backoffMs = this.initialBackoffMs; // reset on a successful connect
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buf = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buf += decoder.decode(value, { stream: true });
+                    let idx;
+                    while ((idx = buf.indexOf('\n\n')) >= 0) {
+                        const rawEvent = buf.slice(0, idx);
+                        buf = buf.slice(idx + 2);
+                        for (const line of rawEvent.split('\n')) {
+                            if (!line.startsWith('data:'))
+                                continue; // skip comments (: ping, : connected)
+                            try {
+                                const payload = JSON.parse(line.slice(5).trim());
+                                if (payload.kind === 'nodes' || payload.kind === 'inbox') {
+                                    for (const l of this.listeners)
+                                        l(payload.kind);
+                                }
+                                // unknown kind → silently ignored (forward-compat)
+                            }
+                            catch {
+                                // malformed data line — ignore
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // connection error/abort — fall through to backoff+retry unless stopped
+            }
+            if (this.stopped)
+                return;
+            await new Promise((resolve) => {
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = undefined;
+                    resolve();
+                }, this.backoffMs);
+            });
+            this.backoffMs = Math.min(this.backoffMs * 2, this.BACKOFF_CAP_MS);
+        }
+    }
+}

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

@@ -119,6 +119,10 @@ export declare function dashboardRows(rootId: string): DashboardRow[];
  * viewport on demand. See {@link enrichRow}, {@link enrichRows}, {@link loadPreview}.
  */
 export declare function dashboardRowsAll(): DashboardRow[];
+/** A remote source provides only graph structure (the 8 CanvasSource methods);
+ *  every other per-node field below is a local disk/SQLite read and is suppressed
+ *  to a safe default for a remote source — `listFocuses()` (SQLite) is skipped
+ *  entirely rather than queried and discarded. */
 export declare function dashboardRowsAllFromSource(source: CanvasSource): Promise<DashboardRow[]>;
 /** Fold the cheap-boot row's deferred fields in for ONE row: the full label
  *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
@@ -129,11 +133,19 @@ export declare function enrichRow(row: DashboardRow): DashboardRow;
  *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
  *  Use this for a whole viewport / the full forest; mutates each row in place. */
 export declare function enrichRows(rows: DashboardRow[]): void;
-export declare function enrichRowsFromSource(source: CanvasSource, rows: DashboardRow[]): Promise<void>;
+/** Telemetry (ctx tokens) is a local disk read, so it is suppressed to 0 for a
+ *  remote source. Ask counts are suppressed to 0 UNLESS the caller supplies
+ *  `remoteAsks` — a pre-fetched `askCountsForView` map (one call per forest
+ *  root; the caller's job, since the right root set is a browse/snapshot
+ *  concern, not this per-row enrichment loop's). See `runBrowse`'s
+ *  `remoteAskCounts`, fetched once per snapshot rebuild, not per flush. */
+export declare function enrichRowsFromSource(source: CanvasSource, rows: DashboardRow[], remoteAsks?: Record<string, number>): Promise<void>;
 /** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
  *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
  *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
  *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
  *  warm the prompt super-search corpus), never on the boot path. */
 export declare function loadPreview(row: DashboardRow): DashboardRow;
+/** goal (initial-prompt.md) and session parts are local disk reads — suppressed
+ *  to undefined for a remote source. */
 export declare function loadPreviewFromSource(source: CanvasSource, row: DashboardRow): Promise<DashboardRow>;