@crouton-kit/crouter 0.3.66 → 0.3.68

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

package/dist/core/canvas/render.js

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
 import { jobDir, contextDir } from './paths.js';
 import { countAsks, asksForNodes } from './attention.js';
@@ -174,25 +175,24 @@ export function renderForest() {
     }
     return parts.join('\n\n');
 }
-async function nodeLineFromSource(source, nodeId, indent, connector) {
+async function nodeLineFromSource(source, nodeId, indent, connector, remote) {
     const node = await source.getNode(nodeId);
     if (node === null)
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
-    const hanging = hangingFor(node);
+    const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
-    const tel = readNodeTelemetry(nodeId);
-    const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(nodeId);
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
+    const asks = remote ? 0 : countAsks(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     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) {
+async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out, remote) {
     if (visited.has(nodeId))
         return;
     visited.add(nodeId);
     const connector = isLast ? '└─ ' : '├─ ';
-    out.push(await nodeLineFromSource(source, nodeId, indent, connector));
+    out.push(await nodeLineFromSource(source, nodeId, indent, connector, remote));
     const children = await source.subscriptionsOf(nodeId).catch(() => []);
     const childIndent = indent + (isLast ? '   ' : '│  ');
     for (let i = 0; i < children.length; i++) {
@@ -203,18 +203,18 @@ 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);
+        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out, remote);
     }
 }
 export async function renderTreeFromSource(source, rootId) {
+    const remote = source instanceof RemoteCanvasSource;
     const node = await source.getNode(rootId);
     if (node === null)
         return `? <missing node: ${rootId}>`;
-    const tel = readNodeTelemetry(rootId);
-    const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(rootId);
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
+    const asks = remote ? 0 : countAsks(rootId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    const hanging = hangingFor(node);
+    const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     const out = [];
@@ -224,7 +224,7 @@ 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);
+        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out, remote);
     }
     return out.join('\n');
 }
@@ -468,14 +468,16 @@ export function dashboardRows(rootId) {
  *  a deterministic canvas-home path, so it tracks last-message recency without a meta
  *  read. Falls back to `created`'s epoch when a node never ran a turn (no telemetry).
  *  Never throws. */
-function sessionMtime(nodeId, created) {
-    try {
-        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
-        if (st !== undefined)
-            return st.mtimeMs;
-    }
-    catch {
-        /* fall through to created */
+function sessionMtime(nodeId, created, remote = false) {
+    if (!remote) {
+        try {
+            const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+            if (st !== undefined)
+                return st.mtimeMs;
+        }
+        catch {
+            /* fall through to created */
+        }
     }
     const t = Date.parse(created);
     return Number.isNaN(t) ? 0 : t;
@@ -500,11 +502,11 @@ function sessionMtime(nodeId, created) {
  */
 export function dashboardRowsAll() {
     const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    return listNodes().map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
+    return listNodes().map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, false));
 }
-function dashboardRowFromNodeRow(row, focusedNodeIds) {
+function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     const live = row.status === 'active' || row.status === 'idle';
-    const hanging = activeFaultForDisplay(row, readFault(row.node_id));
+    const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
     return {
         node_id: row.node_id,
         name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
@@ -516,15 +518,20 @@ function dashboardRowFromNodeRow(row, focusedNodeIds) {
         cwd: row.cwd,
         created: row.created,
         lifecycle: row.lifecycle,
-        mtimeMs: sessionMtime(row.node_id, row.created),
-        streaming: hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+        mtimeMs: sessionMtime(row.node_id, row.created, remote),
+        streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,
-        viewed: focusedNodeIds.has(row.node_id),
+        viewed: remote ? false : focusedNodeIds.has(row.node_id),
     };
 }
+/** 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 async function dashboardRowsAllFromSource(source) {
-    const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
+    const remote = source instanceof RemoteCanvasSource;
+    const focusedNodeIds = remote ? new Set() : new Set(listFocuses().map((f) => f.node_id));
+    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
 // ---------------------------------------------------------------------------
 // Lazy enrichment API — fold the expensive per-node reads into rows on demand,
@@ -565,16 +572,23 @@ export function enrichRows(rows) {
         row.enriched = true;
     }
 }
-export async function enrichRowsFromSource(source, rows) {
+/** 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 async function enrichRowsFromSource(source, rows, remoteAsks) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)
         return;
-    const asks = asksForNodes(todo.map((r) => r.node_id));
+    const remote = source instanceof RemoteCanvasSource;
+    const asks = remote ? (remoteAsks ?? {}) : asksForNodes(todo.map((r) => r.node_id));
     await Promise.all(todo.map(async (row) => {
         const meta = await source.getNode(row.node_id);
         if (meta !== null)
             row.name = fullName(meta);
-        row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
+        row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = asks[row.node_id] ?? 0;
         row.enriched = true;
     }));
@@ -595,14 +609,19 @@ export function loadPreview(row) {
     row.previewLoaded = true;
     return row;
 }
+/** goal (initial-prompt.md) and session parts are local disk reads — suppressed
+ *  to undefined for a remote source. */
 export async function loadPreviewFromSource(source, row) {
     if (row.previewLoaded === true)
         return row;
-    row.goal = readGoalText(row.node_id);
-    const meta = await source.getNode(row.node_id);
-    const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
-    row.prompts = prompts;
-    row.lastAssistant = lastAssistant;
+    const remote = source instanceof RemoteCanvasSource;
+    row.goal = remote ? undefined : readGoalText(row.node_id);
+    if (!remote) {
+        const meta = await source.getNode(row.node_id);
+        const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
+        row.prompts = prompts;
+        row.lastAssistant = lastAssistant;
+    }
     row.previewLoaded = true;
     return row;
 }

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

@@ -1,4 +1,5 @@
 import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+import type { Scope } from '../../types.js';
 export interface CanvasSource {
     getNode(nodeId: string): Promise<NodeMeta | null>;
     getRow(nodeId: string): Promise<NodeRow | null>;
@@ -24,3 +25,11 @@ export declare class LocalCanvasSource implements CanvasSource {
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
 export declare const localCanvasSource: CanvasSource;
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export declare function resolveCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}): CanvasSource;

package/dist/core/canvas/source.js

@@ -1,5 +1,8 @@
 import { getNode, getRow, listNodes, subscriptionsOf, subscribersOf, view, hasActiveLiveSubscription, } from './canvas.js';
 import { asksForNodes } from './attention.js';
+import { readState } from '../config.js';
+import { resolveRemoteCanvasTarget } from '../view/remote-canvas-target.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
 export class LocalCanvasSource {
     async getNode(nodeId) {
         return getNode(nodeId);
@@ -27,3 +30,15 @@ export class LocalCanvasSource {
     }
 }
 export const localCanvasSource = new LocalCanvasSource();
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export function resolveCanvasSource(opts) {
+    const scope = opts?.scope ?? 'user';
+    const name = opts?.canvasName ?? readState(scope).activeCanvas ?? null;
+    if (!name)
+        return localCanvasSource;
+    const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(name, scope);
+    return new RemoteCanvasSource(previewEndpoint, relayToken);
+}

package/dist/core/command.d.ts

@@ -56,6 +56,17 @@ export interface BranchDef {
     rootEntry?: RootEntry;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
+    /** Opt this branch out of the tree model entirely: every token after this
+     *  branch's name is forwarded VERBATIM (raw argv, not the `--json`-filtered
+     *  tokens) to an external binary via spawn, with stdio inherited and the
+     *  child's exit code propagated. A deliberate, documented exception for
+     *  wrapping an external CLI whose own schema crtr cannot and must not
+     *  duplicate (see `crtr capture`) — not a general escape hatch. A
+     *  passthrough branch should declare no children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }
 export interface RootDef {
@@ -81,6 +92,10 @@ export declare function defineBranch(opts: {
     help: BranchHelp;
     rootEntry?: RootEntry;
     slash?: SlashSpec;
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }): BranchDef;
 /** Walk the whole tree and collect every node's SlashSpec (depth-first). Used