@crouton-kit/crouter 0.3.66 → 0.3.68

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

@@ -11,9 +11,11 @@ import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
 import { localCanvasSource } from '../source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { createCoalescedRebuilder } from './rebuild-coalescer.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -26,8 +28,22 @@ function viewportHeight(rowsTotal, search, previewOn) {
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
     return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
 }
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export function wireEventStreamRebuild(eventStream, rebuild) {
+    const rebuilder = createCoalescedRebuilder(rebuild);
+    const unsubscribe = eventStream.subscribe(() => rebuilder.trigger());
+    eventStream.start();
+    return { rebuilder, unsubscribe };
+}
 export async function runBrowse(opts = {}) {
     const source = opts.source ?? localCanvasSource;
+    const isRemote = source instanceof RemoteCanvasSource;
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
@@ -35,18 +51,41 @@ export async function runBrowse(opts = {}) {
     }
     // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
     // session, so `node focus` refuses them; they are never a navigation/resume
-    // target (mirrors the node focus guard).
-    const rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
-    const nodeRows = await source.listNodes();
-    const rootIds = nodeRows
-        .filter((n) => n.parent === null && n.kind !== 'human')
-        .map((n) => n.node_id);
-    const childIds = new Map();
-    await Promise.all(nodeRows.map(async (n) => {
-        childIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
-    }));
-    const tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
-    const totalNodes = tree.nodes.size;
+    // target (mirrors the node focus guard). Factored into a function so the SSE
+    // listener below can re-pull the tree on a `nodes`/`inbox` event instead of
+    // recomputing over a stale snapshot.
+    let rows;
+    let nodeRows;
+    let rootIds;
+    let childIds;
+    let tree;
+    let totalNodes;
+    // Remote-only: pending-ask counts per node, merged from one
+    // `askCountsForView` call per forest root (RemoteCanvasSource.askCountsForView
+    // already shells a single `canvas attention map --view <root>` per root, same
+    // cost class as the per-node `subscriptionsOf` fan-out this snapshot already
+    // does below) — fetched once per snapshot rebuild, not per flush/keystroke, so
+    // enrichRowsFromSource's per-row loop stays a pure sync-shaped map lookup.
+    let remoteAskCounts = {};
+    const rebuildSnapshot = async () => {
+        rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
+        nodeRows = await source.listNodes();
+        rootIds = nodeRows
+            .filter((n) => n.parent === null && n.kind !== 'human')
+            .map((n) => n.node_id);
+        const nextChildIds = new Map();
+        await Promise.all(nodeRows.map(async (n) => {
+            nextChildIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
+        }));
+        childIds = nextChildIds;
+        tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
+        totalNodes = tree.nodes.size;
+        if (isRemote) {
+            const maps = await Promise.all(rootIds.map((root) => source.askCountsForView(root).catch(() => ({}))));
+            remoteAskCounts = Object.assign({}, ...maps);
+        }
+    };
+    await rebuildSnapshot();
     // Default cwd scope = the dir browse was launched from (the request). The popup
     // / command passes --cwd; resolve it so it compares cleanly against stored cwds.
     // null when unknown → All dirs (the toggle's other state).
@@ -82,10 +121,43 @@ export async function runBrowse(opts = {}) {
             restoreTerminal();
         }
         catch { /* best-effort */ }
+        unsubscribeEventStream?.();
+        rebuilder?.stop();
+        opts.eventStream?.stop();
     };
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
+    // Remote-only live invalidation: `canvas browse` has no local fs-watch/poll to
+    // replace (there is none — this is a one-shot snapshot TUI, re-rendering only
+    // on keystrokes). This is net-new plumbing for the remote case only: when a
+    // pre-built RemoteEventStream is threaded in (canvas-browse.ts, once it has
+    // already resolved the target's credentials), a `nodes`/`inbox` SSE event
+    // invalidates the remote source's cache and triggers the same recompute +
+    // coalesced repaint a keystroke would. The local (no eventStream) path is
+    // untouched.
+    let unsubscribeEventStream;
+    let rebuilder;
+    if (opts.eventStream !== undefined) {
+        if (source instanceof RemoteCanvasSource)
+            source.invalidate();
+        // `trigger()` debounces a burst into one rebuild, and single-flights it
+        // against an already-in-flight rebuild — see wireEventStreamRebuild above.
+        const wired = wireEventStreamRebuild(opts.eventStream, async () => {
+            try {
+                if (source instanceof RemoteCanvasSource)
+                    source.invalidate();
+                await rebuildSnapshot();
+                recompute(curRow()?.id);
+                scheduleFlush();
+            }
+            catch (err) {
+                logAsyncFailure('SSE rebuild failed', err);
+            }
+        });
+        rebuilder = wired.rebuilder;
+        unsubscribeEventStream = wired.unsubscribe;
+    }
     const logAsyncFailure = (label, err) => {
         process.stderr.write(`[crtr browse] ${label}: ${String(err?.message ?? err)}\n`);
     };
@@ -154,7 +226,7 @@ export async function runBrowse(opts = {}) {
             if (r !== undefined)
                 slice.push(r);
         }
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         const cur = curRow();
         if (cur !== undefined) {
             const r = rowOf(cur.id);
@@ -166,6 +238,7 @@ export async function runBrowse(opts = {}) {
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
             residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            readOnly: isRemote,
         }, size, caps);
         process.stdout.write(frame);
     };
@@ -459,7 +532,10 @@ export async function runBrowse(opts = {}) {
         }
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'x') {
+            if (isRemote)
+                return;
             if (row === undefined) {
                 scheduleFlush();
                 return;
@@ -510,7 +586,10 @@ export async function runBrowse(opts = {}) {
         // waiting out the 5-min auto-revive grace. Shells `node lifecycle revive <id>
         // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'K') {
+            if (isRemote)
+                return;
             if (row !== undefined) {
                 const r = rowOf(row.id);
                 if (r?.hanging != null)
@@ -519,8 +598,11 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        // Resume.
+        // Resume. No-op against a remote canvas — mutations/focus are disabled
+        // (footer says so).
         if (key.return) {
+            if (isRemote)
+                return;
             if (row !== undefined)
                 selectAndFocus(row.id);
             return;
@@ -566,7 +648,7 @@ export async function runBrowse(opts = {}) {
             return;
         const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
         const slice = warmRows.slice(warmIdx, end);
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
         warmIdx = end;
         // A live search may match the freshly-warmed prompts → recompute + repaint.

package/dist/core/canvas/browse/rebuild-coalescer.d.ts

@@ -0,0 +1,7 @@
+export interface CoalescedRebuilder {
+    /** Called on every SSE event. Cheap — only schedules/marks work. */
+    trigger: () => void;
+    /** Cancels any pending debounce timer (does not abort an in-flight rebuild). */
+    stop: () => void;
+}
+export declare function createCoalescedRebuilder(rebuild: () => Promise<void>, debounceMs?: number): CoalescedRebuilder;

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