@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/clients/attach/extension-dialogs.js

@@ -1,16 +1,15 @@
-// extension-dialogs.ts — the blocking-dialog renderer for `crtr attach` (T5).
+// extension-dialogs.ts — the blocking-dialog renderer for `crtr surface attach` (T5).
 //
 // The broker forwards an extension's user-blocking UI request as an
 // `extension_ui_request` frame (RpcExtensionUIRequest). The viewer renders it
 // with pi's matching exported component and ships the resolved
 // `extension_ui_response` (RpcExtensionUIResponse) back over the socket.
 //
-// Only the 4 blocking methods carry behavior — and they are the only ones the
-// broker ever routes as a request: `makeBrokerUiContext` (broker.ts) no-ops
-// notify/setStatus/setWidget/setTitle/set_editor_text, so those never arrive as
-// a blocking dialog. `isBlockingDialog` lets the caller filter cleanly; for a
-// non-blocking method, `renderDialog` returns an inert handle (no overlay, no
-// response — there is nothing to answer).
+// Only the 4 blocking methods render overlays here. Non-blocking display methods
+// are handled by the viewer before calling `renderDialog` (notify becomes the
+// normal notice line; status/widget/title use dedicated display frames). If one
+// still reaches `renderDialog`, it returns an inert handle — no overlay, no
+// response, because there is nothing to answer.
 //
 // Mapping (mirrors interactive-mode.js): select → ExtensionSelectorComponent;
 // confirm → the SAME selector over ["Yes","No"] (pi has no separate confirm
@@ -22,9 +21,8 @@
 // responding (the response would be a no-op the broker drops by id).
 import { KeybindingsManager, TUI_KEYBINDINGS, } from '@earendil-works/pi-tui';
 import { ExtensionEditorComponent, ExtensionInputComponent, ExtensionSelectorComponent, } from '@earendil-works/pi-coding-agent';
-/** The 4 user-blocking dialog methods. The other 5 RpcExtensionUIRequest methods
- *  are non-blocking display ops (notify/setStatus/setWidget/setTitle/
- *  set_editor_text) the broker never forwards as a request. */
+/** The 4 user-blocking dialog methods. Other RpcExtensionUIRequest methods are
+ *  non-blocking display ops; callers handle them before rendering a dialog. */
 export function isBlockingDialog(req) {
     return (req.method === 'select' ||
         req.method === 'confirm' ||

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

@@ -1,4 +1,4 @@
-// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr attach` (Unit Q).
+// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr surface 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
@@ -13,7 +13,7 @@
 // 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
+// Enter/m/x SHELL `crtr` out-of-process (node focus / node lifecycle close) — the viewer
 // itself never spawns pi or opens a session (the §0 one-writer invariant). It
 // passes its own pane as `crtr node focus --pane <anchor>`: under the
 // one-viewer-per-node model the target's existing viewer is navigated in place,
@@ -64,8 +64,9 @@ export class GraphOverlay {
             return;
         this.scrollTop = 0;
         this.pendingConfirm = undefined;
-        if (this.cursorId === undefined || cNode(this.cursorId) === null)
-            this.cursorId = this.self;
+        // Open with the cursor on the CURRENT (attached) node every time, not wherever
+        // it was left on the last open — the overlay should always default to self.
+        this.cursorId = this.self;
         this.handle = this.tui.showOverlay(this, OVERLAY_OPTIONS);
         this.tui.requestRender();
     }
@@ -275,7 +276,7 @@ export class GraphOverlay {
             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.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'lifecycle', 'close', '--node', target]) };
             this.tui.requestRender();
             return;
         }

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

@@ -64,9 +64,10 @@ export declare class InputController {
     /** Timestamp of the last lone Esc, for double-tap → tree detection (0 = none). */
     private lastEscapeAt;
     constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks);
-    /** Render a blocking extension dialog and route its answer to the broker.
-     *  Supersedes any dialog already on screen (e.g. a re-route on control
-     *  handoff) by dismissing it first. */
+    /** Render extension UI requests from the broker. Blocking dialogs route their
+     *  answer back to the broker; non-blocking notify requests become the viewer's
+     *  normal notice line. Supersedes any dialog already on screen (e.g. a re-route
+     *  on control handoff) by dismissing it first. */
     attachDialog(req: RpcExtensionUIRequest): void;
     /** Feed the latest engine state so read-only commands (e.g. `/session`) report
      *  current values. Optional; the controller works without it. */

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

@@ -1,4 +1,4 @@
-// input-controller.ts — the input half of `crtr attach` (T6).
+// input-controller.ts — the input half of `crtr surface attach` (T6).
 //
 // Owns the editor's behavior: turns keystrokes + submits into `ClientToBroker`
 // command frames (sent via `hooks.onCommand`), reads pasted clipboard images to
@@ -56,10 +56,17 @@ export class InputController {
         this.hooks = hooks;
         this.wire();
     }
-    /** Render a blocking extension dialog and route its answer to the broker.
-     *  Supersedes any dialog already on screen (e.g. a re-route on control
-     *  handoff) by dismissing it first. */
+    /** Render extension UI requests from the broker. Blocking dialogs route their
+     *  answer back to the broker; non-blocking notify requests become the viewer's
+     *  normal notice line. Supersedes any dialog already on screen (e.g. a re-route
+     *  on control handoff) by dismissing it first. */
     attachDialog(req) {
+        if (req.method === 'notify') {
+            const prefix = req.notifyType === 'error' ? 'Error: ' : req.notifyType === 'warning' ? 'Warning: ' : '';
+            this.notify(`${prefix}${req.message}`);
+            this.tui.requestRender();
+            return;
+        }
         this.dialog?.dismiss();
         this.dialog = renderDialog(this.tui, req, (resp) => {
             this.dialog = undefined;
@@ -292,6 +299,20 @@ export class InputController {
                 return;
             }
         }
+        // `!cmd` / `!!cmd` → run bash in the engine and inject output into context,
+        // WITHOUT starting an agent turn (pi-native `!` semantics). `!!` withholds
+        // the output from the LLM. The broker relays the run as bash_* frames.
+        if (trimmed.startsWith('!')) {
+            const excludeFromContext = trimmed.startsWith('!!');
+            const command = trimmed.slice(excludeFromContext ? 2 : 1).trim();
+            if (command === '')
+                return; // bare `!`/`!!`: nothing to run
+            if (!this.emitDrive({ type: 'bash', command, excludeFromContext }))
+                return;
+            this.editor.addToHistory(trimmed);
+            this.editor.setText('');
+            return;
+        }
         // Submit-while-streaming = steer (pi-native parity): interject into the
         // running turn instead of queueing a fresh prompt. `isStreaming` is the
         // broker snapshot's busy signal; the broker routes `steer` → session.steer()

package/dist/clients/attach/pickers.js

@@ -1,4 +1,4 @@
-// pickers.ts — native interactive pickers for `crtr attach`, built against the
+// pickers.ts — native interactive pickers for `crtr surface attach`, built against the
 // operator-view wire contract (broker read-op `data` frames). Each builder turns
 // a serialized picker payload into the REAL pi `*SelectorComponent`, wired so a
 // selection dispatches the SAME command frame the text-arg slash path sends and

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

@@ -44,13 +44,13 @@ export interface SlashContext {
     /** Open the native /logout provider selector. */
     openLogoutPicker?: () => 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. */
+/** Canvas slash-commands — implemented NATIVE in the viewer, the ONLY live host:
+ *  the broker binds mode:'print', so broker pi-extensions never run their
+ *  interactive (mode==='tui') paths. `/promote` triggers a turn after shelling
+ *  `crtr node promote`; `/resume-node`, `/view`, `/context` each shell a `crtr`
+ *  subcommand via `tmux display-popup` (the viewer runs inside a tmux pane);
+ *  `/graph` toggles the in-process overlay. Exported so the editor folds these
+ *  into the slash autocomplete list. */
 export declare const CANVAS_SLASH_COMMANDS: ReadonlyArray<{
     name: string;
     description: string;

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

@@ -1,4 +1,4 @@
-// slash-commands.ts — builtin slash-command parse + dispatch for `crtr attach` (C6).
+// slash-commands.ts — builtin slash-command parse + dispatch for `crtr surface attach` (C6).
 //
 // Builtin slash commands are NOT engine-interpreted: `session.prompt('/model')`
 // ships "/model" to the LLM as literal text. So the viewer recognizes the 21
@@ -24,18 +24,19 @@
 import { execFile } from 'node:child_process';
 import { BUILTIN_SLASH_COMMANDS } from '../../core/runtime/pi-vendored.js';
 import { surfaceTmuxStyleArgs } from '../../core/runtime/surface-bg.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. */
+/** Canvas slash-commands — implemented NATIVE in the viewer, the ONLY live host:
+ *  the broker binds mode:'print', so broker pi-extensions never run their
+ *  interactive (mode==='tui') paths. `/promote` triggers a turn after shelling
+ *  `crtr node promote`; `/resume-node`, `/view`, `/context` each shell a `crtr`
+ *  subcommand via `tmux display-popup` (the viewer runs inside a tmux pane);
+ *  `/graph` toggles the in-process overlay. Exported so the editor folds these
+ *  into the slash 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' },
+    { name: 'context', description: 'Browse this node + its subscriptions’ context dirs in a read-only nvim popup' },
 ];
 const CANVAS_NAMES = new Set(CANVAS_SLASH_COMMANDS.map((c) => c.name));
 /** Builtins with no Phase-4 engine method — scoped out (review m2). */
@@ -245,19 +246,24 @@ function dispatchCanvasCommand(name, arg, ctx) {
             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`.
+            // 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).
+            // 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);
+        case 'context':
+            // A read-only nvim explorer over this node's + its subscriptions' context
+            // dirs, as a self-contained popup.
+            return openContext(ctx);
         default:
             ctx.notify(`/${name} is not available in attach`);
             return true;
     }
 }
-/** `/promote [kind]` ← canvas-commands.ts. Shells `crtr node promote --json` for
+/** `/promote [kind]` — the live promote path (the broker is headless, so promotion
+ *  has no in-engine command). 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. */
@@ -309,7 +315,7 @@ function promoteNode(arg, ctx) {
         });
     });
 }
-/** `/resume-node` ← canvas-resume.ts. Opens `crtr canvas browse` as a tmux popup,
+/** `/resume-node`. 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) {
@@ -323,8 +329,7 @@ function resumeNode(ctx) {
     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
+/** `/view [name]`. Bare opens the picker; with a name it opens that view directly. Self-contained
  *  popup — no node-focus, no return-pane. */
 function openView(arg, ctx) {
     if (process.env['TMUX'] === undefined) {
@@ -332,10 +337,28 @@ function openView(arg, ctx) {
         return true;
     }
     const name = arg.trim();
-    const cmd = name === '' ? 'crtr view pick' : `crtr view run ${shellQuote(name)}`;
+    const cmd = name === '' ? 'crtr surface view pick' : `crtr surface view run ${shellQuote(name)}`;
     popup(cmd);
     return true;
 }
+/** `/context`. Opens `crtr node inspect context` as a popup — a
+ *  read-only nvim explorer over this node's + its subscriptions' context dirs.
+ *  Self-contained popup — no node-focus, no return-pane. */
+function openContext(ctx) {
+    if (process.env['TMUX'] === undefined) {
+        ctx.notify('/context needs tmux');
+        return true;
+    }
+    // The popup runs server-side and won't reliably inherit CRTR_NODE_ID, so pass
+    // this viewer's node id explicitly (mirrors /promote, /resume-node).
+    const nodeId = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').trim();
+    if (nodeId === '') {
+        ctx.notify('/context: no node to root on (viewer has no node id)');
+        return true;
+    }
+    popup(`crtr node inspect context --node ${shellQuote(nodeId)}`);
+    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. */

package/dist/clients/attach/titled-editor.d.ts

@@ -43,9 +43,13 @@ export declare class TitledEditor extends CustomEditor {
     /** Pre-styled context string painted into the RIGHT of the top border (cwd /
      *  branch / git status). Already colorized by the caller; empty → omitted. */
     info: string;
+    /** Mode badge painted into the bottom-right of the outline. Empty → omitted. */
+    mode: string;
     /** Paint the chip solid so the name reads as a label sitting on the border
      *  rule. Defaults to the reverse-video chip; attach-cmd swaps in a
      *  thinking-colored background (bold white text) on each state update. */
     titleStyle: (s: string) => string;
+    /** Mode badge colorizer, matched to the current mode type. */
+    modeStyle: (s: string) => string;
     render(width: number): string[];
 }

package/dist/clients/attach/titled-editor.js

@@ -1,4 +1,4 @@
-// titled-editor.ts — the `crtr attach` input editor with two bits of chrome pi's
+// titled-editor.ts — the `crtr surface attach` input editor with two bits of chrome pi's
 // stock editor doesn't give us:
 //   1. the session name painted INTO the top border as a solid-background chip,
 //      so it stays pinned to the editor instead of scrolling off as a free badge;
@@ -7,22 +7,26 @@
 // Both are pure render-layer chrome; nothing here touches the socket or session.
 import { CustomEditor } from '@earendil-works/pi-coding-agent';
 import { truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
-/** Per-level border/chip color as a 24-bit RGB triple. Each level ROTATES HUE by
- *  a large step (~35–45°) along a "heat" ramp — indigo → violet → magenta → pink
- *  → red-orange — so adjacent levels are unmistakably different at a glance (a
- *  constant-hue saturation climb read as nearly identical; see #8). All sit at
- *  roughly constant, high-ish lightness so each is vivid on a dark terminal, and
- *  the cool→hot direction maps intuitively onto a climbing thinking budget. (pi
- *  paints its own `thinking*` theme colors off its public palette surface, so we
- *  own this ramp directly — truecolor, not the 16-color ANSI hues, so the hue
- *  sweep actually reads.) `off` falls back to the caller's default border color. */
+/** The thinking color scale is a deliberate cool→warm ramp between a blue and
+ *  its orange complement, evenly spaced across the five active levels so each
+ *  step stays readable without jumping through unrelated hues. `off` falls
+ *  back to the caller's default border color. */
+const THINKING_START = [68, 120, 228]; // blue
+const THINKING_END = [228, 152, 68]; // orange
+function interpolateRgb(start, end, t) {
+    return [
+        Math.round(start[0] + (end[0] - start[0]) * t),
+        Math.round(start[1] + (end[1] - start[1]) * t),
+        Math.round(start[2] + (end[2] - start[2]) * t),
+    ];
+}
 const THINKING_RGB = {
     off: undefined, // default border color
-    minimal: [96, 132, 220], // indigo / cornflower blue
-    low: [150, 110, 214], // violet
-    medium: [200, 98, 196], // magenta
-    high: [224, 102, 142], // pink-red
-    xhigh: [228, 120, 84], // red-orange
+    minimal: interpolateRgb(THINKING_START, THINKING_END, 0 / 4),
+    low: interpolateRgb(THINKING_START, THINKING_END, 1 / 4),
+    medium: interpolateRgb(THINKING_START, THINKING_END, 2 / 4),
+    high: interpolateRgb(THINKING_START, THINKING_END, 3 / 4),
+    xhigh: interpolateRgb(THINKING_START, THINKING_END, 4 / 4),
 };
 /** The default (thinking `off`) title chip: reverse video + a space of padding
  *  each side, so the name reads as a label sitting on the border rule. Used as
@@ -99,10 +103,14 @@ export class TitledEditor extends CustomEditor {
     /** Pre-styled context string painted into the RIGHT of the top border (cwd /
      *  branch / git status). Already colorized by the caller; empty → omitted. */
     info = '';
+    /** Mode badge painted into the bottom-right of the outline. Empty → omitted. */
+    mode = '';
     /** Paint the chip solid so the name reads as a label sitting on the border
      *  rule. Defaults to the reverse-video chip; attach-cmd swaps in a
      *  thinking-colored background (bold white text) on each state update. */
     titleStyle = defaultTitleStyle;
+    /** Mode badge colorizer, matched to the current mode type. */
+    modeStyle = defaultTitleStyle;
     render(width) {
         const lines = super.render(width);
         if ((this.title || this.info) && lines.length > 0) {
@@ -110,6 +118,14 @@ export class TitledEditor extends CustomEditor {
             // border color.
             lines[0] = composeTopBorder(width, this.title, this.info, this.titleStyle, (s) => this.borderColor(s));
         }
+        if (this.mode && lines.length > 0) {
+            const badge = this.modeStyle(this.mode);
+            const badgeWidth = visibleWidth(badge);
+            if (badgeWidth + 2 < width) {
+                const last = lines.length - 1;
+                lines[last] = truncateToWidth(lines[last], width - badgeWidth, '') + badge;
+            }
+        }
         return lines;
     }
 }

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

@@ -46,6 +46,7 @@ export declare class ViewSocketClient extends EventEmitter {
      *  frame in {@link onData}, the request's timeout, or socket teardown. */
     private pending;
     constructor(nodeId: string);
+    private recordSocketFault;
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or
      *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
      *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
@@ -54,7 +55,7 @@ export declare class ViewSocketClient extends EventEmitter {
     /** Reject + clear every in-flight request (socket gone / decode error) so a
      *  picker fetch never hangs past the connection it rode on. */
     private rejectAllPending;
-    /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
     get socketPath(): string;
     /** Open the connection. Wire up listeners; emits `connect` on success or
      *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on

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

@@ -1,4 +1,4 @@
-// view-socket.ts — the socket client half of `crtr attach` (Phase 4, T7).
+// view-socket.ts — the socket client half of `crtr surface attach` (Phase 4, T7).
 //
 // The §0 ONE-WRITER INVARIANT lives in this directory: a viewer has ONLY a
 // socket. ViewSocketClient connects to a node's ALREADY-running headless broker
@@ -20,8 +20,9 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { createConnection } from 'node:net';
-import { join } from 'node:path';
-import { nodeDir } from '../../core/canvas/paths.js';
+import { viewSocketPath } from '../../core/canvas/paths.js';
+import { classify } from '../../core/fault-classifier.js';
+import { clearFault, recordFault } from '../../core/runtime/fault.js';
 import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
 /** How long {@link ViewSocketClient.request} waits for the correlated reply before
  *  rejecting — bounds a pending picker fetch if the broker drops the request
@@ -64,6 +65,18 @@ export class ViewSocketClient extends EventEmitter {
         super();
         this.nodeId = nodeId;
     }
+    recordSocketFault(op, err) {
+        const classified = classify('viewer↔broker', err);
+        recordFault(this.nodeId, {
+            link: 'viewer↔broker',
+            op,
+            kind: classified.kind,
+            retry: op === 'redial'
+                ? { disposition: 'auto', by: 'client' }
+                : { disposition: 'manual' },
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or
      *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
      *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
@@ -98,9 +111,9 @@ export class ViewSocketClient extends EventEmitter {
         }
         this.pending.clear();
     }
-    /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
     get socketPath() {
-        return join(nodeDir(this.nodeId), 'view.sock');
+        return viewSocketPath(this.nodeId);
     }
     /** Open the connection. Wire up listeners; emits `connect` on success or
      *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
@@ -108,9 +121,12 @@ export class ViewSocketClient extends EventEmitter {
     connect() {
         const socket = createConnection(this.socketPath);
         this.socket = socket;
-        socket.on('connect', () => this.emit('connect'));
+        socket.on('connect', () => {
+            clearFault(this.nodeId, { link: 'viewer↔broker' });
+            this.emit('connect');
+        });
         socket.on('data', (chunk) => this.onData(chunk));
-        socket.on('error', (err) => this.onError(err));
+        socket.on('error', (err) => this.onError(err, 'connect'));
         socket.on('close', () => this.onClose());
     }
     /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
@@ -132,16 +148,18 @@ export class ViewSocketClient extends EventEmitter {
                 if (settled)
                     return;
                 settled = true;
+                clearFault(this.nodeId, { link: 'viewer↔broker' });
                 this.emit('connect');
                 resolve();
             });
             socket.on('data', (chunk) => this.onData(chunk));
             socket.on('error', (err) => {
                 if (settled) {
-                    this.onError(err);
+                    this.onError(err, 'redial');
                     return;
                 }
                 settled = true;
+                this.recordSocketFault('redial', err);
                 try {
                     socket.destroy();
                 }
@@ -214,7 +232,8 @@ export class ViewSocketClient extends EventEmitter {
             this.emit('frame', frame);
         }
     }
-    onError(err) {
+    onError(err, op) {
+        this.recordSocketFault(op, err);
         if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
             this.emitError(new BrokerUnavailableError(this.nodeId));
         }

package/dist/clients/web/__tests__/source-cache.test.js

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { isCoalescableSourceRequest } from '../source-cache.js';
+const exec = (args, extra = {}) => ({ kind: 'exec', bin: 'crtr', args, ...extra });
+test('coalesces the idempotent crtr --json reads the SSE burst fans out', () => {
+    // Regression: a single SSE invalidation re-issued human/view/node reads as
+    // duplicate subprocesses because shouldCache only matched `canvas snapshot`.
+    assert.equal(isCoalescableSourceRequest(exec(['canvas', 'snapshot', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['human', 'list', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['surface', 'view', 'list', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'snapshot', 'abc-123', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'show', 'abc-123', '--json'])), true);
+});
+test('does NOT coalesce writes, side-effecting, or target-mismatched requests', () => {
+    // Writes — must never be cached (would drop a mutation).
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'new', '--json'], { stdin: 'prompt' })), false);
+    assert.equal(isCoalescableSourceRequest(exec(['canvas', 'revive', 'abc', '--json'])), false);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'spine', 'msg', 'abc', '--json'], { stdin: 'hi' })), false);
+    // human resolve / deck are on-demand writes, not the cached list read.
+    assert.equal(isCoalescableSourceRequest(exec(['human', 'resolve', 'q1', '--json'])), false);
+    // Any stdin or cwd override disqualifies even an allowlisted command shape.
+    assert.equal(isCoalescableSourceRequest(exec(['canvas', 'snapshot', '--json'], { stdin: 'x' })), false);
+    assert.equal(isCoalescableSourceRequest(exec(['surface', 'view', 'list', '--json'], { cwd: '/elsewhere' })), false);
+    // Non-exec requests are never cacheable.
+    assert.equal(isCoalescableSourceRequest({ kind: 'file', path: '/tmp/x' }), false);
+    assert.equal(isCoalescableSourceRequest({ kind: 'http', method: 'GET', url: 'http://x' }), false);
+    // Non-crtr bin, missing --json, or wrong arity must not match.
+    assert.equal(isCoalescableSourceRequest(exec(['human', 'list', '--json'], { bin: 'sh' })), false);
+    assert.equal(isCoalescableSourceRequest(exec(['human', 'list'])), false);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'snapshot', '--json'])), false);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'show', '--json'])), false);
+});

package/dist/clients/web/dev-server.js

@@ -41,6 +41,7 @@ export async function createDevServer(httpServer) {
             alias: {
                 react: join(nodeModules, 'react'),
                 'react-dom': join(nodeModules, 'react-dom'),
+                '@': shellRoot,
                 // The crtr web runtime is a self-subpath of crouter's own package;
                 // pin it to the built barrel so the shell can import it from any root.
                 '@crouton-kit/crouter/web': join(packageRoot, 'dist', 'web', 'index.js'),

package/dist/clients/web/events.js

@@ -1,11 +1,10 @@
-// events.ts — the `crtr web` realtime push lane (the §7 SSE seam, built for v1).
+// events.ts — the `crtr web` realtime push lane.
 //
-// ONE server-sent-events stream, `GET /__crtr/events`, that carries CHANGE
-// INVALIDATIONS — never data. The shell / its ViewPanes subscribe and, on an
-// event, re-pull through their existing Sources (the bridge) instead of waiting
-// on a fixed poll tick. SSE carries "something in this class changed"; the
-// consumer decides what to re-read. This keeps the event vocabulary tiny and
-// generic and the contract unchanged (a ViewPane still just runs `refresh`).
+// ONE server-sent-events stream, `GET /__crtr/events`, that carries change
+// invalidations — never data. The shell and built-in views subscribe and, on an
+// event, re-pull through their existing bridge reads instead of waiting on a
+// fixed poll tick. SSE carries "something in this class changed"; the consumer
+// decides what to re-read.
 //
 // Event vocabulary (deliberately minimal): { kind: 'nodes' | 'inbox', ts }.
 //   - 'nodes' — the node graph changed (topology, status/intent transitions,
@@ -15,10 +14,9 @@
 //   - 'inbox' — a node's inbox.jsonl gained a message. Source: a recursive watch
 //     on the nodes/ tree, filtered to `inbox.jsonl` writes.
 //
-// WHY these sources (the §7 seam left the event source open): they are the
-// cheapest things that detect node-graph + inbox changes without a daemon hook
-// or a db trigger — pure fs.watch on the two on-disk authorities (canvas.db for
-// the graph, inbox.jsonl appends for messages). No polling, no canvas.db reads.
+// WHY these sources: they are the cheapest things that detect node-graph +
+// inbox changes without a daemon hook or a db trigger — pure fs.watch on the
+// two on-disk authorities (canvas.db for the graph, inbox.jsonl for messages).
 import { watch } from 'node:fs';
 import { crtrHome, nodesRoot, ensureHome } from '../../core/canvas/paths.js';
 /** Coalesce a burst of fs events into one emission per kind. WAL writes and

package/dist/clients/web/server.d.ts

@@ -1,6 +1,7 @@
 export interface WebServerOptions {
     port: number;
     host?: string;
+    token?: string;
     /** --dev: mount a Vite dev server (middleware mode, HMR) for asset serving
      *  instead of the static dist/web-client/ bundle. The bridge + SSE + WS relay
      *  are identical in both modes. */
@@ -12,7 +13,7 @@ export interface RunningWebServer {
     clientDir: string;
     close: () => Promise<void>;
 }
-/** Build + start the unified web server. Binds 127.0.0.1 only (remote access is
- *  out of scope — §9). Resolves once the server is listening. Async because
- *  --dev awaits a Vite middleware server before listening. */
+/** Build + start the unified web server. Binds the requested host/port and
+ *  resolves once the server is listening. Async because --dev awaits a Vite
+ *  middleware server before listening. */
 export declare function startWebServer(opts: WebServerOptions): Promise<RunningWebServer>;