@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/clients/attach/canvas-panels.js

@@ -12,7 +12,7 @@
 // caller owns the Containers and the refresh trigger. beginFrame() memoizes the
 // canvas.db reads for this one build pass (mirrors canvas-nav's per-frame cache),
 // so a whole panel rebuild is a single fan-out of disk/db reads.
-import { beginFrame, cNode, managerOf, liveReports, climbRoot, computeSubtreeActivity, navLabel, coloredGlyph, truncate, tokensCell, cycleBadge, childBadge, liveBelowBadge, askBadge, activityCell, YELLOW, RESET, } from '../../core/canvas/nav-model.js';
+import { beginFrame, cNode, managerOf, liveReports, climbRoot, computeSubtreeActivity, navLabel, nodeGlyph, truncate, tokensCell, cycleBadge, childBadge, liveBelowBadge, askBadge, activityCell, YELLOW, RESET, } from '../../core/canvas/nav-model.js';
 /** Column widths for the aligned panel rows (visible columns). name is sized to
  *  the widest label across BOTH panels (capped); kind is wide enough for the
  *  longest persona kind (`orchestrator` = 12) so real kinds never truncate;
@@ -57,7 +57,7 @@ export function buildCanvasPanelLines(nodeId, asks, palette) {
         const kind = faint(nameCell(n?.kind ?? '', KIND_W));
         const tokens = muted(padStartVisible(tokensCell(id), TOK_W));
         const badges = `${cycleBadge(n)}${childBadge(n)}${liveBelowBadge(n, activity.activeBelow)}${askBadge(id, asks)}${activityCell(id, n)}`;
-        return truncate(` ${coloredGlyph(n)} ${name}  ${kind} ${tokens}${badges}`);
+        return truncate(` ${nodeGlyph(n)} ${name}  ${kind} ${tokens}${badges}`);
     };
     // --- managers panel (↑) ---
     const managers = [];

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

@@ -50,6 +50,8 @@ export declare class ChatView {
     private streamingComponent;
     /** Tool-call id → its execution component, for the duration of the call. */
     private readonly pendingTools;
+    /** The `!` bash component currently streaming (between bash_start and bash_end). */
+    private bashComponent;
     /** The single active activity loader (working/compaction/retry), if any. */
     private activityLoader;
     /** While true, `append` skips re-pinning the status container (bulk rebuild). */
@@ -78,6 +80,14 @@ export declare class ChatView {
      *  the container, so the loop covers it too). Returns the new HIDDEN state. */
     toggleThinking(): boolean;
     handleEvent(event: AgentSessionEvent): void;
+    bashStart(command: string, excludeFromContext?: boolean): void;
+    bashOutput(chunk: string): void;
+    bashEnd(result: {
+        exitCode: number | undefined;
+        cancelled: boolean;
+        truncated: boolean;
+        fullOutputPath?: string;
+    }): void;
     private addMessageToChat;
     /** Default-path tool component (toolDef undefined → builtin/default rendering). */
     private makeToolComponent;

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

@@ -73,6 +73,8 @@ export class ChatView {
     streamingComponent;
     /** Tool-call id → its execution component, for the duration of the call. */
     pendingTools = new Map();
+    /** The `!` bash component currently streaming (between bash_start and bash_end). */
+    bashComponent;
     /** The single active activity loader (working/compaction/retry), if any. */
     activityLoader;
     /** While true, `append` skips re-pinning the status container (bulk rebuild). */
@@ -382,6 +384,27 @@ export class ChatView {
         this.tui.requestRender();
     }
     // -------------------------------------------------------------------------
+    // `!` bash live stream (broker bash_start/bash_output/bash_end frames). Mirrors
+    // pi interactive mode's `!` handling: create the component on start, stream
+    // chunks into it, mark complete on end. The persisted `bashExecution` message
+    // also rides the next snapshot, so this only drives the LIVE view.
+    // -------------------------------------------------------------------------
+    bashStart(command, excludeFromContext) {
+        const component = new BashExecutionComponent(command, this.tui, excludeFromContext);
+        this.bashComponent = component;
+        this.append(component);
+        this.tui.requestRender();
+    }
+    bashOutput(chunk) {
+        this.bashComponent?.appendOutput(chunk);
+        this.tui.requestRender();
+    }
+    bashEnd(result) {
+        this.bashComponent?.setComplete(result.exitCode, result.cancelled, result.truncated ? { truncated: true } : undefined, result.fullOutputPath);
+        this.bashComponent = undefined;
+        this.tui.requestRender();
+    }
+    // -------------------------------------------------------------------------
     // Rebuild path (ports addMessageToChat, interactive-mode.js:2483).
     // -------------------------------------------------------------------------
     addMessageToChat(message) {

package/dist/clients/attach/config-load.d.ts

@@ -63,11 +63,15 @@ export interface AttachPalette {
     error: (s: string) => string;
     /** Warning / transient notices. Same constraint as `error` → ANSI yellow. */
     warning: (s: string) => string;
-    /** Editor border when the input is in shell/bash mode (leading `!`). pi paints
-     *  this from its `bashMode` theme color (default `green`), which pi does NOT
-     *  re-export through its public surface — so, like `error`/`warning`, this is
-     *  the semantically-correct ANSI green, not an ad-hoc hardcode. */
+    /** Editor border for a SINGLE-`!` bash command (output IS added to the agent's
+     *  context). Dull/normal ANSI green — pi paints shell mode from its `bashMode`
+     *  theme color (default `green`), which pi does NOT re-export through its public
+     *  surface, so like `error`/`warning` this is the semantically-correct ANSI green. */
     bashMode: (s: string) => string;
+    /** Editor border for a `!!` bash command (output is HIDDEN from the agent).
+     *  BRIGHT ANSI green, so the more consequential "agent won't see this" form
+     *  reads as visually hotter than the plain `!`. */
+    bashModeAlt: (s: string) => string;
 }
 /**
  * Build the attach chrome's color palette from the LIVE theme. Call AFTER

package/dist/clients/attach/config-load.js

@@ -206,6 +206,7 @@ const FAINT = (s) => `\x1b[2m${s}\x1b[22m`;
 const RED = (s) => `\x1b[31m${s}\x1b[39m`;
 const YELLOW = (s) => `\x1b[33m${s}\x1b[39m`;
 const GREEN = (s) => `\x1b[32m${s}\x1b[39m`;
+const BRIGHT_GREEN = (s) => `\x1b[92m${s}\x1b[39m`;
 /**
  * Build the attach chrome's color palette from the LIVE theme. Call AFTER
  * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
@@ -237,6 +238,7 @@ export function attachPalette() {
         error: RED,
         warning: YELLOW,
         bashMode: GREEN,
+        bashModeAlt: BRIGHT_GREEN,
         surface: (line) => `${bgOn}${line.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[49m`,
     };
 }

package/dist/clients/attach/extension-dialogs.d.ts

@@ -6,9 +6,8 @@ import type { RpcExtensionUIRequest, RpcExtensionUIResponse } from '../../core/r
 export interface DialogHandle {
     dismiss(): void;
 }
-/** 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 declare function isBlockingDialog(req: RpcExtensionUIRequest): boolean;
 /**
  * Render a blocking extension dialog as a focused overlay over `tui`, and resolve

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

@@ -5,12 +5,11 @@
 // 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

@@ -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();
     }

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

@@ -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/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

@@ -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,7 +329,7 @@ function resumeNode(ctx) {
     popup(cmd);
     return true;
 }
-/** `/view [name]` ← canvas-view.ts. Bare opens the picker (`crtr view pick`);
+/** `/view [name]`. 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) {
@@ -336,6 +342,24 @@ function openView(arg, ctx) {
     popup(cmd);
     return true;
 }
+/** `/context`. Opens `crtr node 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 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.js

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

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

@@ -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.d.ts

@@ -0,0 +1 @@
+export {};

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(['view', 'list', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['node', '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', '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(['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', '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>;