@crouton-kit/crouter 0.3.65 → 0.3.67

package/dist/core/canvas/pid.js

@@ -60,50 +60,92 @@ export function isPidAlive(pid) {
     }
     return !isZombie(pid);
 }
-/** Like `isPidAlive`, but guards a RECORDED node pid against PID REUSE using the
- *  launch-time identity baseline (`pi_pid_identity`, captured by `recordPid`).
- *  On a heavily-forking host — esp. Linux, where low pids recycle fast — a
- *  broker's recorded pid can be reused by an unrelated process after the broker
- *  dies; a bare `isPidAlive` then reports the STRANGER as "our broker alive",
- *  wedging every daemon supervise/revive decision (the daemon never revives a
- *  row that looks alive; `reviveNode`'s double-launch guard never relaunches).
- *  Returns false the instant the pid's CURRENT identity is POSITIVELY known to
- *  differ from `expectedIdentity` (the recycle case). Fail-open everywhere else
- *  — no baseline (legacy row / capture failed at launch), `ps` probe failure, or
- *  a pid present-but-unreadable — exactly matching `captureTeardownSnapshot`'s
- *  discipline: a MISMATCH is the ONLY thing that reads dead, never an absence of
- *  evidence. */
-export function isRecordedPidAlive(pid, expectedIdentity) {
+/** Split a `composeIdentity` fingerprint (`lstart` or `lstart#ticks`) into its
+ *  coarse (`lstart`, second-granular, portable) and fine (`ticks`, Linux-only
+ *  jiffies, best-effort) parts. `#` never appears in `lstart` itself (a `ps`
+ *  timestamp), so the first `#` unambiguously separates them. */
+function splitIdentity(identity) {
+    const i = identity.indexOf('#');
+    return i === -1 ? { base: identity, ticks: undefined } : { base: identity.slice(0, i), ticks: identity.slice(i + 1) };
+}
+/** THE single precision-aware identity compare, used EVERYWHERE two
+ *  `composeIdentity` fingerprints are compared (this module's own
+ *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and
+ *  `killProcessTreePids`'s reuse check) — centralized so no call site can
+ *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
+ *  fix).
+ *
+ *  The hazard this closes: `composeIdentity` appends the `#<ticks>` Linux
+ *  discriminator only when `/proc/<pid>/stat` happens to be readable at
+ *  capture time — so the SAME live process can be recorded plain `lstart` on
+ *  one capture and `lstart#ticks` on another (a transient `/proc` read
+ *  failure, or capturing on a platform/container without procfs). A naive
+ *  `===` then reads that as a reuse (different string) and reports `dead` for
+ *  a broker that never actually died — the false-DEAD direction, which can
+ *  make `reviveNode`'s double-launch guard wrongly relaunch a SECOND broker
+ *  onto a still-live session.
+ *
+ *  Rule: split both on `#`. Bases (`lstart`) differ → definitely NOT a match
+ *  (different process, or the same pid reused in a different second). Bases
+ *  match and BOTH carry a `#ticks` suffix → match iff the suffixes are equal
+ *  (this still catches genuine same-second reuse, the case `procStartTicks`
+ *  exists for). Bases match and EITHER lacks the suffix → coarse-vs-fine,
+ *  can't distinguish → MATCH (fail-open to same-process, matching this
+ *  module's universal discipline: only a POSITIVE mismatch counts as reuse,
+ *  never an absence of evidence). */
+export function identitiesMatch(a, b) {
+    const ia = splitIdentity(a);
+    const ib = splitIdentity(b);
+    if (ia.base !== ib.base)
+        return false;
+    if (ia.ticks !== undefined && ib.ticks !== undefined)
+        return ia.ticks === ib.ticks;
+    return true;
+}
+export function recordedPidLiveness(pid, expectedIdentity) {
     const debug = Boolean(process.env.CRTR_DEBUG_PID_LIVENESS);
     const alive = isPidAlive(pid);
     if (!alive) {
         if (debug)
-            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'isPidAlive=false → dead', false);
-        return false; // gone/zombie → dead (unchanged path)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'isPidAlive=false → dead', 'dead');
+        return 'dead'; // gone/zombie → dead (unchanged path)
     }
     if (expectedIdentity == null) {
         if (debug)
-            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'no baseline → trust isPidAlive', true);
-        return true; // no baseline → trust isPidAlive (legacy behavior)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'no baseline → trust isPidAlive', 'alive');
+        return 'alive'; // no baseline → trust isPidAlive (legacy behavior)
     }
     const current = capturePidIdentities([pid]);
     if (current == null) {
         if (debug)
-            logPidLivenessDecision(pid, alive, expectedIdentity, 'probe-null', 'ps probe failed → fail-open alive', true);
-        return true; // probe itself failed → fail-open
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'probe-null', 'ps probe failed → indeterminate', 'indeterminate');
+        return 'indeterminate'; // probe itself failed → we don't know (THE fix: was fail-open alive)
     }
     const actual = current.get(pid);
     if (actual === undefined) {
         if (debug)
-            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-entry', 'no identity row for pid (race) → fail-open alive', true);
-        return true; // present but no identity row (race) → fail-open
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-entry', 'no identity row for pid (race) → dead', 'dead');
+        return 'dead'; // isPidAlive said alive but it's gone now → dead
     }
-    const result = actual === expectedIdentity; // different identity → REUSED → dead
+    const matches = identitiesMatch(actual, expectedIdentity);
     if (debug)
-        logPidLivenessDecision(pid, alive, expectedIdentity, 'value', result ? 'identity matches expected → alive' : 'identity differs from expected → REUSED → dead', result, actual);
-    return result;
+        logPidLivenessDecision(pid, alive, expectedIdentity, 'value', matches ? 'identity matches expected → alive' : 'identity differs from expected → REUSED → dead', matches ? 'alive' : 'dead', actual);
+    return matches ? 'alive' : 'dead';
+}
+/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
+ *  every pre-existing signalling caller stays behavior-identical: `dead` is
+ *  the ONLY thing that reads false. `indeterminate` (can't confirm either
+ *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
+ *  uncertainty, matching this module's universal discipline (a POSITIVE
+ *  mismatch is the only thing that changes behavior, never an absence of
+ *  evidence). Callers that need to distinguish "confirmed alive" from
+ *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
+ *  alive risks silently skipping a needed relaunch) must call
+ *  `recordedPidLiveness` directly instead of this adapter. */
+export function isRecordedPidAlive(pid, expectedIdentity) {
+    return recordedPidLiveness(pid, expectedIdentity) !== 'dead';
 }
-/** Diagnostic-only decision trace for `isRecordedPidAlive`, gated entirely
+/** Diagnostic-only decision trace for `recordedPidLiveness`, gated entirely
  *  behind `CRTR_DEBUG_PID_LIVENESS` — callers must check the env var
  *  themselves before calling this so the (tiny) formatting cost is paid ONLY
  *  when the env var is set; this function does no env check of its own.
@@ -129,7 +171,7 @@ function logPidLivenessDecision(pid, isPidAliveResult, expectedIdentity, probeOu
         `branch=${JSON.stringify(branch)}`,
         `returned=${returned}`,
     ];
-    process.stderr.write(`[isRecordedPidAlive] ${parts.join(' ')}\n`);
+    process.stderr.write(`[recordedPidLiveness] ${parts.join(' ')}\n`);
 }
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of
@@ -339,7 +381,9 @@ export function captureTeardownSnapshot(rootPid, expectedIdentity) {
     if (table === null)
         return { tree: [rootPid], identities: null, reused: false };
     const currentRootIdentity = table.identities.get(rootPid);
-    const reused = expectedIdentity != null && currentRootIdentity !== undefined && currentRootIdentity !== expectedIdentity;
+    const reused = expectedIdentity != null &&
+        currentRootIdentity !== undefined &&
+        !identitiesMatch(currentRootIdentity, expectedIdentity);
     if (reused)
         return { tree: [], identities: null, reused: true };
     const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)];
@@ -407,7 +451,7 @@ export function killProcessTreePids(pids, signal = 'SIGTERM', identities) {
         if (identities != null && current != null) {
             const expected = identities.get(pid);
             const actual = current.get(pid);
-            const reused = expected !== undefined && actual !== undefined && actual !== expected;
+            const reused = expected !== undefined && actual !== undefined && !identitiesMatch(actual, expected);
             if (reused)
                 continue;
         }

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>;