@crouton-kit/crouter 0.3.27 → 0.3.28

package/dist/clients/attach/graph-overlay.js

@@ -0,0 +1,266 @@
+// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr attach` (Unit Q).
+//
+// Native reimplementation of canvas-nav.ts's GRAPH modal as a pi-tui OVERLAY
+// (the viewer has no pi extension host). `tui.showOverlay(this, …)` mounts this
+// Component full-screen and CAPTURES keyboard focus (mirrors extension-dialogs.ts);
+// `OverlayHandle.hide()` tears it down and restores focus to the editor. While
+// shown, every key routes to handleInput() — a fold-aware NERDTree of the local
+// subscription graph with the canvas-nav keymap:
+//   j/k move · h/l fold/ascend-descend · g/G top/bottom · ↵ focus (swap into
+//   this pane) · m focus manager · x kill (y/n confirm) · esc close.
+// `e` is a tmux-menu prefixBind, not a GRAPH key, so it is swallowed (per
+// canvas-nav). All model/render comes from the shared nav-model layer; keys are
+// decoded with pi-tui's canonical matchesKey (kitty/CSI-u aware).
+//
+// Enter/m/x SHELL `crtr` out-of-process (node focus / node close) — the viewer
+// itself never spawns pi or opens a session (the §0 one-writer invariant); it
+// runs inside a tmux pane, so `crtr node focus --pane` swaps the chosen node in.
+import { execFile } from 'node:child_process';
+import { matchesKey } from '@earendil-works/pi-tui';
+import { fullName } from '../../core/canvas/index.js';
+import { beginFrame, cNode, managerOf, sortedChildIds, climbRoot, computeSubtreeActivity, buildGraphModel, renderGraphRow, focusedNodeIds, shortId, visibleWidth, VIEWPORT_FALLBACK_ROWS, DIM, RESET, BOLD, YELLOW, } from '../../core/canvas/nav-model.js';
+const OVERLAY_OPTIONS = { anchor: 'top-left', width: '100%', maxHeight: '100%' };
+// Viewer-specific hint: nav-model's shared GRAPH_HINT advertises "e expand",
+// but that key is the tmux pane-expand prefix-bind canvas-nav installs in its
+// host pane — the attach overlay has no such bind and swallows `e`, so the key
+// would do nothing here. Drop it.
+const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · x kill · m mgr · esc${RESET}`;
+/** Pad `s` out to `width` VISIBLE columns so the overlay line is opaque (no base
+ *  content bleeds through the right edge). Lines already wider are left as-is. */
+function padTo(s, width) {
+    const pad = width - visibleWidth(s);
+    return pad > 0 ? s + ' '.repeat(pad) : s;
+}
+export class GraphOverlay {
+    tui;
+    self;
+    getAsks;
+    handle;
+    /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
+     *  both override the default activity-driven policy and survive open/close. */
+    userExpanded = new Set();
+    userCollapsed = new Set();
+    folds = { userExpanded: this.userExpanded, userCollapsed: this.userCollapsed };
+    /** Cursor as a node id (indices shift as topology changes). */
+    cursorId;
+    /** Viewport scroll offset (row index of the top visible tree row). */
+    scrollTop = 0;
+    /** Transient y/n confirm gate (kill). */
+    pendingConfirm;
+    constructor(tui, self, getAsks) {
+        this.tui = tui;
+        this.self = self;
+        this.getAsks = getAsks;
+    }
+    isOpen() {
+        return this.handle !== undefined;
+    }
+    open() {
+        if (this.handle !== undefined)
+            return;
+        this.scrollTop = 0;
+        this.pendingConfirm = undefined;
+        if (this.cursorId === undefined || cNode(this.cursorId) === null)
+            this.cursorId = this.self;
+        this.handle = this.tui.showOverlay(this, OVERLAY_OPTIONS);
+        this.tui.requestRender();
+    }
+    close() {
+        if (this.handle === undefined)
+            return;
+        this.pendingConfirm = undefined;
+        this.handle.hide();
+        this.handle = undefined;
+        this.tui.requestRender();
+    }
+    toggle() {
+        if (this.handle === undefined)
+            this.open();
+        else
+            this.close();
+    }
+    /** Repaint if shown (the low-rate ask poll calls this). */
+    refresh() {
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    invalidate() {
+        /* no cached render state — rebuilt every render() */
+    }
+    // -------------------------------------------------------------------------
+    render(width) {
+        // Fresh snapshot per paint (mirror canvas-nav's per-frame cache).
+        beginFrame();
+        const asks = this.getAsks();
+        const activity = computeSubtreeActivity(climbRoot(this.self), this.self);
+        const rows = buildGraphModel(this.self, this.folds, activity.expand);
+        // Re-resolve the cursor id → row (it may have vanished under a fold/close).
+        let cursorIdx = rows.findIndex((r) => r.id === this.cursorId);
+        if (cursorIdx < 0) {
+            cursorIdx = rows.findIndex((r) => r.id === this.self);
+            if (cursorIdx < 0)
+                cursorIdx = 0;
+        }
+        this.cursorId = rows[cursorIdx]?.id ?? this.self;
+        // Full-screen budget: 1 title line + 1 footer hint, the rest for tree rows.
+        const totalH = Math.max(6, process.stdout.rows ?? VIEWPORT_FALLBACK_ROWS);
+        const treeArea = Math.max(2, totalH - 2);
+        // Track the cursor within treeArea, reserving ↑/↓ "more" indicators. Up to
+        // 4 passes converge the mutual dependency between window size and indicators
+        // (an indicator steals a tree row → can re-home scrollTop → toggles the other
+        // indicator); see canvas-nav.ts renderGraph for the rationale.
+        let viewportH = treeArea;
+        for (let pass = 0; pass < 4; pass++) {
+            if (cursorIdx < this.scrollTop)
+                this.scrollTop = cursorIdx;
+            if (cursorIdx >= this.scrollTop + viewportH)
+                this.scrollTop = cursorIdx - viewportH + 1;
+            this.scrollTop = Math.max(0, Math.min(this.scrollTop, Math.max(0, rows.length - viewportH)));
+            const fit = treeArea - (this.scrollTop > 0 ? 1 : 0) - (this.scrollTop + viewportH < rows.length ? 1 : 0);
+            if (fit === viewportH)
+                break;
+            viewportH = Math.max(1, fit);
+        }
+        const end = Math.min(rows.length, this.scrollTop + viewportH);
+        const focused = focusedNodeIds();
+        const body = [];
+        if (this.scrollTop > 0)
+            body.push(`${DIM}  ↑ ${this.scrollTop} more${RESET}`);
+        for (let i = this.scrollTop; i < end; i++) {
+            body.push(renderGraphRow(rows[i], i === cursorIdx, focused, activity.activeBelow, asks));
+        }
+        if (end < rows.length)
+            body.push(`${DIM}  ↓ ${rows.length - end} more${RESET}`);
+        while (body.length < treeArea)
+            body.push(''); // fill so the overlay is opaque
+        const title = `${BOLD}⌗ canvas graph${RESET} ${DIM}(${cursorIdx + 1}/${rows.length})${RESET}`;
+        const hint = this.pendingConfirm !== undefined
+            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}y/n${RESET}`
+            : GRAPH_HINT;
+        return [title, ...body, hint].map((line) => padTo(line, width));
+    }
+    // -------------------------------------------------------------------------
+    handleInput(data) {
+        try {
+            this.dispatch(data);
+        }
+        catch {
+            /* a key handler is best-effort; never throw out of the input pump */
+        }
+    }
+    dispatch(data) {
+        // y/n confirm gate takes precedence over everything.
+        if (this.pendingConfirm !== undefined) {
+            if (matchesKey(data, 'y')) {
+                const act = this.pendingConfirm.action;
+                this.pendingConfirm = undefined;
+                act();
+            }
+            else {
+                this.pendingConfirm = undefined; // any other key cancels
+            }
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'escape')) {
+            this.close();
+            return;
+        }
+        const rows = buildGraphModel(this.self, this.folds);
+        let idx = rows.findIndex((r) => r.id === this.cursorId);
+        if (idx < 0)
+            idx = Math.max(0, rows.findIndex((r) => r.id === this.self));
+        const cur = rows[idx];
+        if (matchesKey(data, 'j')) {
+            idx = Math.min(rows.length - 1, idx + 1);
+            this.cursorId = rows[idx]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'k')) {
+            idx = Math.max(0, idx - 1);
+            this.cursorId = rows[idx]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'g')) {
+            this.cursorId = rows[0]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'shift+g')) {
+            this.cursorId = rows[rows.length - 1]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'h')) {
+            if (cur !== undefined && cur.hasKids && !cur.collapsed) {
+                this.userCollapsed.add(cur.id);
+                this.userExpanded.delete(cur.id);
+            }
+            else {
+                const p = managerOf(this.cursorId ?? this.self);
+                if (p !== undefined && rows.some((r) => r.id === p))
+                    this.cursorId = p;
+            }
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'l')) {
+            if (cur !== undefined && cur.collapsed && cur.hasKids) {
+                this.userExpanded.add(cur.id);
+                this.userCollapsed.delete(cur.id);
+            }
+            else if (cur !== undefined && cur.hasKids) {
+                const c = sortedChildIds(cur.id)[0];
+                if (c !== undefined)
+                    this.cursorId = c;
+            }
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, 'enter')) {
+            if (this.cursorId !== undefined)
+                this.focusTarget(this.cursorId);
+            this.close();
+            return;
+        }
+        if (matchesKey(data, 'm')) {
+            const mgr = managerOf(this.self);
+            if (mgr !== undefined) {
+                this.focusTarget(mgr);
+                this.close();
+            }
+            return;
+        }
+        if (matchesKey(data, 'x')) {
+            const target = this.cursorId ?? this.self;
+            const n = cNode(target);
+            const nm = n !== null ? fullName(n) : shortId(target);
+            this.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'close', '--node', target]) };
+            this.tui.requestRender();
+            return;
+        }
+        // Modal: swallow everything else (incl. the `e` tmux-menu bind) so a stray
+        // key never reaches the editor underneath.
+    }
+    // -------------------------------------------------------------------------
+    /** Swap `id` into THIS viewer's tmux pane (mirrors canvas browse's return-pane
+     *  shell). Default --pane is the caller TMUX_PANE; we pass it explicitly when
+     *  set so the focus lands here even if env resolution differs. */
+    focusTarget(id) {
+        const argv = ['node', 'focus', id];
+        const pane = process.env['TMUX_PANE'];
+        if (pane !== undefined && pane !== '')
+            argv.push('--pane', pane);
+        this.shellCrtr(argv);
+    }
+    shellCrtr(argv) {
+        try {
+            execFile('crtr', argv, () => { });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}

package/dist/clients/attach/input-controller.d.ts

@@ -11,6 +11,12 @@ export interface InputControllerHooks {
      *  reports notices up the same way it reports commands. Absent → notices are
      *  dropped silently. */
     onNotice?: (message: string) => void;
+    /** OPTIONAL: the canvas node this viewer is attached to — forwarded to the
+     *  slash context so `/promote` targets it (Unit Q wires it from runAttach). */
+    nodeId?: string;
+    /** OPTIONAL: toggle the GRAPH overlay — forwarded to the slash context so
+     *  `/graph` opens/closes it (Unit Q wires it from runAttach). */
+    onGraph?: () => void;
 }
 export declare class InputController {
     private readonly tui;

package/dist/clients/attach/input-controller.js

@@ -90,6 +90,8 @@ export class InputController {
             notify: (message) => this.notify(message),
             state: this.state,
             cwd: process.cwd(),
+            nodeId: this.hooks.nodeId,
+            onGraph: this.hooks.onGraph,
         };
     }
     handleSubmit(text) {

package/dist/clients/attach/slash-commands.d.ts

@@ -12,7 +12,27 @@ export interface SlashContext {
     state?: BrokerSnapshot['state'];
     /** cwd for the default `/export` path; defaults to `process.cwd()`. */
     cwd?: string;
+    /** The canvas node this viewer is attached to — used by `/promote` (passed
+     *  as `--node`). Falls back to `CRTR_NODE_ID` when absent; if neither is set
+     *  `/promote` notifies and no-ops. (Unit Q wires this from `runAttach`.) */
+    nodeId?: string;
+    /** Toggle the in-process GRAPH overlay (the local subscription-tree view).
+     *  `/graph` is inherently an in-viewer overlay, not a tmux popup, so this unit
+     *  registers `/graph` as a stub that calls this hook. Unit C/Q owns the overlay
+     *  itself and populates this; when absent `/graph` notifies it isn't wired yet. */
+    onGraph?: () => void;
 }
+/** Canvas slash-commands — reimplemented NATIVE in the viewer (the canvas chrome
+ *  pi-extensions cannot load here; see findings-chrome-parity.md Feature 3). Each
+ *  ports the action of its extension: `/promote` ← canvas-commands.ts, `/resume-node`
+ *  ← canvas-resume.ts, `/view` ← canvas-view.ts, `/graph` ← canvas-nav.ts. Three of
+ *  them shell a `crtr` subcommand via `tmux display-popup` (the viewer runs inside a
+ *  tmux pane, so this works exactly as in the extensions); `/graph` is a stub for the
+ *  overlay (Unit C/Q). Exported so Unit Q can fold these into the autocomplete list. */
+export declare const CANVAS_SLASH_COMMANDS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;
 /** True if `text` is a leading-slash command (vs. a normal prompt). */
 export declare function isSlashCommand(text: string): boolean;
 /**
@@ -24,7 +44,8 @@ export declare function isSlashCommand(text: string): boolean;
 export declare function dispatchSlashCommand(text: string, ctx: SlashContext): boolean;
 /** Build slash-command autocomplete entries from the merged command list (the
  *  broker's `get_commands` result, which T7 may inject) — defaults to the
- *  vendored builtins. Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+ *  vendored builtins. The native canvas commands are always appended. Shaped for
+ *  pi-tui's `CombinedAutocompleteProvider`. */
 export declare function slashCommandList(commands?: ReadonlyArray<{
     name: string;
     description?: string;

package/dist/clients/attach/slash-commands.js

@@ -22,7 +22,22 @@
 //
 // SCOPED OUT (review m2 — no engine method): `/login`, `/logout`, `/share`,
 // `/trust` — a brief "not supported in attach" notice, never a frame.
+import { execFile } from 'node:child_process';
 import { BUILTIN_SLASH_COMMANDS } from '../../core/runtime/pi-vendored.js';
+/** Canvas slash-commands — reimplemented NATIVE in the viewer (the canvas chrome
+ *  pi-extensions cannot load here; see findings-chrome-parity.md Feature 3). Each
+ *  ports the action of its extension: `/promote` ← canvas-commands.ts, `/resume-node`
+ *  ← canvas-resume.ts, `/view` ← canvas-view.ts, `/graph` ← canvas-nav.ts. Three of
+ *  them shell a `crtr` subcommand via `tmux display-popup` (the viewer runs inside a
+ *  tmux pane, so this works exactly as in the extensions); `/graph` is a stub for the
+ *  overlay (Unit C/Q). Exported so Unit Q can fold these into the autocomplete list. */
+export const CANVAS_SLASH_COMMANDS = [
+    { name: 'graph', description: 'Toggle the canvas GRAPH view (your local subscription tree)' },
+    { name: 'promote', description: 'Promote this node to an orchestrator — /promote, or /promote <kind> to specialize' },
+    { name: 'resume-node', description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node' },
+    { name: 'view', description: 'Open a view in a popup — bare for the picker, or /view <name> to open that view directly' },
+];
+const CANVAS_NAMES = new Set(CANVAS_SLASH_COMMANDS.map((c) => c.name));
 /** Builtins with no Phase-4 engine method — scoped out (review m2). */
 const SCOPED_OUT = new Set(['login', 'logout', 'share', 'trust']);
 /** Valid `/settings thinking` levels — the `SetThinkingLevelFrame['level']`
@@ -60,6 +75,10 @@ export function dispatchSlashCommand(text, ctx) {
         ctx.notify(`/${name} is not supported in attach (Phase 4)`);
         return true;
     }
+    // Canvas commands (reimplemented native in the viewer) — handled before the
+    // builtin gate since they are neither pi builtins nor engine-extension commands.
+    if (CANVAS_NAMES.has(name))
+        return dispatchCanvasCommand(name, arg, ctx);
     // Unknown to us AND not a builtin → let the engine's extension runner have it.
     if (!BUILTIN_NAMES.has(name))
         return false;
@@ -140,15 +159,153 @@ export function dispatchSlashCommand(text, ctx) {
             return true;
     }
 }
+/** Append the native canvas commands to a command list, skipping any already
+ *  present (so they survive whatever list Unit Q feeds in — builtins, or the
+ *  broker's `get_commands` result). The four canvas commands are viewer-owned,
+ *  so they are always surfaced in autocomplete regardless of the source list. */
+function withCanvasCommands(commands) {
+    const seen = new Set(commands.map((c) => c.name));
+    return [...commands, ...CANVAS_SLASH_COMMANDS.filter((c) => !seen.has(c.name))];
+}
 /** Build slash-command autocomplete entries from the merged command list (the
  *  broker's `get_commands` result, which T7 may inject) — defaults to the
- *  vendored builtins. Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+ *  vendored builtins. The native canvas commands are always appended. Shaped for
+ *  pi-tui's `CombinedAutocompleteProvider`. */
 export function slashCommandList(commands = BUILTIN_SLASH_COMMANDS) {
-    return commands.map((c) => ({ name: c.name, description: c.description }));
+    return withCanvasCommands(commands).map((c) => ({ name: c.name, description: c.description }));
 }
 /** Same list as flat autocomplete items (value/label/description). */
 export function commandAutocompleteItems(commands = BUILTIN_SLASH_COMMANDS) {
-    return commands.map((c) => ({ value: `/${c.name}`, label: `/${c.name}`, description: c.description }));
+    return withCanvasCommands(commands).map((c) => ({ value: `/${c.name}`, label: `/${c.name}`, description: c.description }));
+}
+// ---------------------------------------------------------------------------
+// Canvas commands — native reimplementations of the canvas chrome extensions.
+// ---------------------------------------------------------------------------
+/** Dispatch one of the four native canvas commands. Always returns `true` (the
+ *  command is viewer-owned — never forwarded to the engine as a prompt). */
+function dispatchCanvasCommand(name, arg, ctx) {
+    switch (name) {
+        case 'graph':
+            // `/graph` is inherently the in-process GRAPH overlay (canvas-nav.ts
+            // `toggleGraph`), NOT a tmux popup. The overlay is Unit C/Q's surface; this
+            // unit registers the command + autocomplete entry and triggers the overlay
+            // via the `onGraph` hook the integration unit wires in.
+            if (ctx.onGraph)
+                ctx.onGraph();
+            else
+                ctx.notify('The GRAPH overlay is not wired into the viewer yet');
+            return true;
+        case 'promote':
+            promoteNode(arg, ctx);
+            return true;
+        case 'resume-node':
+            // ← canvas-resume.ts: open the full-screen canvas navigator as a popup; on
+            // Enter it focuses the chosen node back into THIS pane via `crtr node focus`.
+            return resumeNode(ctx);
+        case 'view':
+            // ← canvas-view.ts: bare `/view` opens the picker, `/view <name>` opens that
+            // view directly — each as a self-contained popup (no node-focus, no return-pane).
+            return openView(arg, ctx);
+        default:
+            ctx.notify(`/${name} is not available in attach`);
+            return true;
+    }
+}
+/** `/promote [kind]` ← canvas-commands.ts. Shells `crtr node promote --json` for
+ *  this node (out-of-process), notifies the result, then triggers a turn so the
+ *  persona injector steers in the new-role guidance at the turn boundary — exactly
+ *  as the node would by running the command itself. */
+function promoteNode(arg, ctx) {
+    const nodeId = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').trim();
+    if (nodeId === '') {
+        ctx.notify('/promote: no node to promote (viewer has no node id)');
+        return;
+    }
+    const kind = arg.trim().toLowerCase();
+    ctx.notify(kind ? `Promoting → ${kind}…` : 'Promoting…');
+    const argv = ['node', 'promote', '--node', nodeId, '--json'];
+    if (kind !== '')
+        argv.push('--kind', kind);
+    execFile('crtr', argv, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        // On a non-zero exit crtr still prints the structured error to stdout, so
+        // prefer its `message` over the raw throw.
+        let result = null;
+        let errMsg = null;
+        try {
+            result = JSON.parse(stdout);
+        }
+        catch {
+            result = null;
+        }
+        if (err && result === null) {
+            const out = typeof err.stdout === 'string' ? err.stdout : '';
+            try {
+                const payload = JSON.parse(out);
+                errMsg = typeof payload.message === 'string' ? payload.message : null;
+            }
+            catch {
+                errMsg = null;
+            }
+            if (errMsg === null)
+                errMsg = err.message;
+        }
+        if (result === null) {
+            ctx.notify(`promote failed: ${errMsg ?? 'unknown error'}`);
+            return;
+        }
+        const rmPath = (result.roadmap_path ?? '').trim();
+        ctx.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`);
+        // Trigger a turn so the persona injector (canvas-stophook turn_end) fires and
+        // delivers the new-role guidance — the viewer's only turn-trigger is `prompt`.
+        ctx.send({
+            type: 'prompt',
+            text: 'You have just been promoted to an orchestrator. Your new-role guidance is arriving — read it, author your roadmap, and start delegating.',
+        });
+    });
+}
+/** `/resume-node` ← canvas-resume.ts. Opens `crtr canvas browse` as a tmux popup,
+ *  scoped to this node's cwd; on Enter it focuses the chosen node back into this
+ *  pane via `crtr node focus --pane` (which `canvas browse` shells). */
+function resumeNode(ctx) {
+    const origPane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] === undefined || origPane === undefined || origPane === '') {
+        ctx.notify('/resume-node needs tmux');
+        return true;
+    }
+    const cwd = shellQuote(ctx.cwd ?? process.cwd());
+    const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}`;
+    popup(cmd);
+    return true;
+}
+/** `/view [name]` ← canvas-view.ts. Bare opens the picker (`crtr view pick`);
+ *  `/view <name>` opens that view directly (`crtr view run <name>`). Self-contained
+ *  popup — no node-focus, no return-pane. */
+function openView(arg, ctx) {
+    if (process.env['TMUX'] === undefined) {
+        ctx.notify('/view needs tmux');
+        return true;
+    }
+    const name = arg.trim();
+    const cmd = name === '' ? 'crtr view pick' : `crtr view run ${shellQuote(name)}`;
+    popup(cmd);
+    return true;
+}
+/** Open `cmd` as a fire-and-forget tmux display-popup (same geometry as the canvas
+ *  extensions). tmux runs the trailing string through `sh -c`; the popup owns its
+ *  screen and closes itself when the command exits, dropping back to this pane. */
+function popup(cmd) {
+    try {
+        execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => {
+            /* best-effort: popup is self-contained */
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Single-quote a string for safe interpolation into a `sh -c` command line. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 // ---------------------------------------------------------------------------
 function usage(ctx, form) {

package/dist/clients/attach/view-socket.d.ts

@@ -1,8 +1,18 @@
 import { EventEmitter } from 'node:events';
+import type { NodeRow } from '../../core/canvas/types.js';
 import { type BrokerToClient, type ClientToBroker } from '../../core/runtime/broker-protocol.js';
 /** Surfaced when the node has no reachable broker at connect time (no socket
  *  file, or a stale socket with nothing listening). The command catches this to
  *  exit non-zero with a focus/revive hint. */
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same `view.sock` while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
+ *  terminal — an idle-release node revives on its next inbox wake, so keep
+ *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
 export declare class BrokerUnavailableError extends Error {
     readonly nodeId: string;
     constructor(nodeId: string);
@@ -24,7 +34,7 @@ export interface ViewSocketClient {
 export declare class ViewSocketClient extends EventEmitter {
     private readonly nodeId;
     private socket;
-    private readonly decoder;
+    private decoder;
     private closeEmitted;
     constructor(nodeId: string);
     /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
@@ -33,6 +43,14 @@ export declare class ViewSocketClient extends EventEmitter {
      *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
      *  failure. Idempotent guard is the caller's job — call once. */
     connect(): void;
+    /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
+     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
+     *  from the dead stream must not corrupt the new one) and resets the close
+     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
+     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
+     *  post-connect error flows through the normal `onError`→`close` path. */
+    redial(): Promise<void>;
     /** Encode + write one client→broker frame. No-op on a dead/absent socket
      *  (a `close` event drives teardown); never throws. */
     send(frame: ClientToBroker): void;

package/dist/clients/attach/view-socket.js

@@ -9,12 +9,14 @@
 // what keeps a broker alive, not attach). It also never uses pi's `RpcClient`
 // (which would spawn its own engine).
 //
-// No reconnect: a dropped broker means the engine's turn-cycle settled and the
-// broker disposed+exited; a fresh focus re-runs attach. On EOF/close → emit
-// `close` (the caller renders "broker gone" + exits). On a connect-time
-// ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the command exits non-zero
-// with a clear message. Decode is bounded by `CLIENT_READ_CAPS`; a broker that
-// somehow sends an oversized frame surfaces as a clean error+exit, not a crash.
+// Reconnect: a dropped broker emits `close`; the caller's reconnect supervisor
+// decides whether to re-dial (a yield/revive keeps the SAME `view.sock` path —
+// `redial()` re-establishes the socket on it) or give up ("broker gone"). On a
+// connect-time ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the FIRST
+// connect exits non-zero with a clear message; the same codes during a redial
+// reject the redial promise as retryable. Decode is bounded by
+// `CLIENT_READ_CAPS`; a broker that somehow sends an oversized frame surfaces as
+// a clean error+exit, not a crash.
 import { EventEmitter } from 'node:events';
 import { createConnection } from 'node:net';
 import { join } from 'node:path';
@@ -23,6 +25,19 @@ import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from
 /** Surfaced when the node has no reachable broker at connect time (no socket
  *  file, or a stale socket with nothing listening). The command catches this to
  *  exit non-zero with a focus/revive hint. */
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same `view.sock` while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
+ *  terminal — an idle-release node revives on its next inbox wake, so keep
+ *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+export function reconnectShouldGiveUp(row) {
+    if (row === null)
+        return true;
+    return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+}
 export class BrokerUnavailableError extends Error {
     nodeId;
     constructor(nodeId) {
@@ -55,6 +70,46 @@ export class ViewSocketClient extends EventEmitter {
         socket.on('error', (err) => this.onError(err));
         socket.on('close', () => this.onClose());
     }
+    /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
+     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
+     *  from the dead stream must not corrupt the new one) and resets the close
+     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
+     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
+     *  post-connect error flows through the normal `onError`→`close` path. */
+    redial() {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const socket = createConnection(this.socketPath);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.emit('connect');
+                resolve();
+            });
+            socket.on('data', (chunk) => this.onData(chunk));
+            socket.on('error', (err) => {
+                if (settled) {
+                    this.onError(err);
+                    return;
+                }
+                settled = true;
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            socket.on('close', () => this.onClose());
+        });
+    }
     /** Encode + write one client→broker frame. No-op on a dead/absent socket
      *  (a `close` event drives teardown); never throws. */
     send(frame) {