@crouton-kit/crouter 0.3.60 → 0.3.62

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

@@ -5,13 +5,13 @@
 // Component as a BOUNDED, centered modal (~72% of the terminal, themed frame) 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:
+// shown, every key routes to handleInput() — a fold-aware NERDTree of the
+// active CanvasSource 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).
+// canvas-nav). Model/render uses the CanvasSource snapshot built for this
+// overlay; keys are decoded with pi-tui's canonical matchesKey (kitty/CSI-u aware).
 //
 // 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
@@ -21,7 +21,11 @@
 import { execFile } from 'node:child_process';
 import { matchesKey, truncateToWidth } 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';
+import { activeFaultForDisplay } from '../../core/canvas/render.js';
+import { readFault } from '../../core/runtime/fault.js';
+import { faultSummary } from '../../core/canvas/status-glyph.js';
+import { localCanvasSource } from '../../core/canvas/source.js';
+import { beginFrame, navLabel, nodeGlyph, tokensCell, cycleBadge, askBadge, activityCell, focusedNodeIds, shortId, visibleWidth, fillBar, fillWidth, truncate, isAttached, VIEWPORT_FALLBACK_ROWS, DIM, RESET, BOLD, YELLOW, REVERSE, BG_ATTACHED, GREEN, } from '../../core/canvas/nav-model.js';
 // A BOUNDED, centered modal (CTO ruling: not full-bleed). Width/height are capped
 // at ~72% of the terminal; the overlay clips our lines to maxHeight, and render()
 // budgets the panel to the SAME fraction (HEIGHT_PCT) so the framed box is never
@@ -38,6 +42,7 @@ export class GraphOverlay {
     self;
     getAsks;
     palette;
+    source;
     handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
      *  both override the default activity-driven policy and survive open/close. */
@@ -50,11 +55,14 @@ export class GraphOverlay {
     scrollTop = 0;
     /** Transient y/n confirm gate (kill). */
     pendingConfirm;
-    constructor(tui, self, getAsks, palette) {
+    snapshot;
+    snapshotSeq = 0;
+    constructor(tui, self, getAsks, palette, source = localCanvasSource) {
         this.tui = tui;
         this.self = self;
         this.getAsks = getAsks;
         this.palette = palette;
+        this.source = source;
     }
     isOpen() {
         return this.handle !== undefined;
@@ -68,7 +76,7 @@ export class GraphOverlay {
         // 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();
+        this.refresh();
     }
     close() {
         if (this.handle === undefined)
@@ -86,19 +94,182 @@ export class GraphOverlay {
     }
     /** Repaint if shown (the low-rate ask poll calls this). */
     refresh() {
-        if (this.handle !== undefined)
+        if (this.handle === undefined)
+            return;
+        const seq = ++this.snapshotSeq;
+        void this.buildSnapshot().then((snapshot) => {
+            if (seq !== this.snapshotSeq)
+                return;
+            this.snapshot = snapshot;
+            this.tui.requestRender();
+        }).catch((err) => {
+            this.logAsyncFailure('graph overlay refresh failed', err);
             this.tui.requestRender();
+        });
     }
     invalidate() {
-        /* no cached render state — rebuilt every render() */
+        this.refresh();
     }
     // -------------------------------------------------------------------------
+    async buildSnapshot() {
+        beginFrame();
+        const nodes = new Map();
+        const childIds = new Map();
+        const sortedChildIds = new Map();
+        const managerOf = new Map();
+        const activeBelow = new Map();
+        const node = async (id) => {
+            if (nodes.has(id))
+                return nodes.get(id) ?? null;
+            let v;
+            try {
+                v = await this.source.getNode(id);
+            }
+            catch {
+                v = null;
+            }
+            nodes.set(id, v);
+            return v;
+        };
+        const children = async (id) => {
+            const hit = childIds.get(id);
+            if (hit !== undefined)
+                return hit;
+            let refs;
+            try {
+                refs = await this.source.subscriptionsOf(id);
+            }
+            catch {
+                refs = [];
+            }
+            const out = [];
+            for (const ref of refs) {
+                if ((await node(ref.node_id))?.kind !== 'human')
+                    out.push(ref.node_id);
+            }
+            childIds.set(id, out);
+            return out;
+        };
+        const manager = async (id) => {
+            if (managerOf.has(id))
+                return managerOf.get(id);
+            let mgr;
+            try {
+                mgr = (await this.source.subscribersOf(id))[0]?.node_id;
+            }
+            catch {
+                mgr = undefined;
+            }
+            managerOf.set(id, mgr);
+            return mgr;
+        };
+        const climbRoot = async (self) => {
+            let cur = self;
+            const seen = new Set([cur]);
+            for (;;) {
+                const mgr = await manager(cur);
+                if (mgr === undefined || seen.has(mgr))
+                    break;
+                seen.add(mgr);
+                cur = mgr;
+            }
+            return cur;
+        };
+        const rank = async (id) => {
+            switch ((await node(id))?.status) {
+                case 'active': return 0;
+                case 'idle': return 1;
+                case 'done': return 2;
+                case 'canceled': return 3;
+                case 'dead': return 4;
+                default: return 5;
+            }
+        };
+        const sortedChildren = async (id) => {
+            const cached = sortedChildIds.get(id);
+            if (cached !== undefined)
+                return cached;
+            const ids = [...await children(id)];
+            const ranks = new Map();
+            await Promise.all(ids.map(async (cid) => { ranks.set(cid, await rank(cid)); }));
+            ids.sort((a, b) => (ranks.get(a) ?? 99) - (ranks.get(b) ?? 99));
+            sortedChildIds.set(id, ids);
+            return ids;
+        };
+        const expand = new Set();
+        const seenActivity = new Set();
+        const visitActivity = async (id) => {
+            const selfActive = (await node(id))?.status === 'active';
+            if (seenActivity.has(id))
+                return { active: selfActive ? 1 : 0, reveal: selfActive || id === this.self };
+            seenActivity.add(id);
+            let below = 0;
+            let childReveal = false;
+            for (const c of await children(id)) {
+                const r = await visitActivity(c);
+                below += r.active;
+                if (r.reveal)
+                    childReveal = true;
+            }
+            activeBelow.set(id, below);
+            if (childReveal)
+                expand.add(id);
+            return { active: below + (selfActive ? 1 : 0), reveal: childReveal || selfActive || id === this.self };
+        };
+        await visitActivity(await climbRoot(this.self));
+        const rows = [];
+        const visited = new Set();
+        const walk = async (id, prefix, isRoot, isLast) => {
+            if (visited.has(id)) {
+                const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+                rows.push({ id, hasKids: false, isSelf: id === this.self, branch: prefix + connector, cycle: true, collapsed: false });
+                return;
+            }
+            visited.add(id);
+            const kids = await sortedChildren(id);
+            const folded = this.folds.userExpanded.has(id) ? false : this.folds.userCollapsed.has(id) ? true : !expand.has(id);
+            const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+            rows.push({ id, hasKids: kids.length > 0, isSelf: id === this.self, branch: prefix + connector, cycle: false, collapsed: folded });
+            if (folded)
+                return;
+            const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
+            for (let i = 0; i < kids.length; i++)
+                await walk(kids[i], childPrefix, false, i === kids.length - 1);
+        };
+        await walk(await climbRoot(this.self), '', true, true);
+        return { rows, activeBelow, nodes, childIds, sortedChildIds, managerOf, focused: focusedNodeIds() };
+    }
+    renderSnapshotRow(snapshot, r, isCursor, asks) {
+        const wrap = (line, attached) => isCursor ? fillBar(line, fillWidth(), REVERSE)
+            : attached ? fillBar(line, fillWidth(), BG_ATTACHED)
+                : truncate(line);
+        if (r.cycle) {
+            const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
+            return wrap(line, false);
+        }
+        const node = snapshot.nodes.get(r.id) ?? null;
+        const dot = nodeGlyph(node);
+        const rawName = navLabel(node, r.id);
+        const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
+        const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
+        const tokens = `${DIM}${tokensCell(r.id)}${RESET}`;
+        const expandable = r.hasKids && r.collapsed;
+        const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
+        const cycle = cycleBadge(node);
+        const childCount = snapshot.childIds.get(r.id)?.length ?? 0;
+        const child = node !== null && childCount > 0 ? ` ${DIM}⤳${childCount}${RESET}` : '';
+        const below = node !== null && node.status !== 'active' && (snapshot.activeBelow.get(node.node_id) ?? 0) > 0
+            ? ` ${GREEN}⇣${snapshot.activeBelow.get(node.node_id) ?? 0}${RESET}`
+            : '';
+        const fault = node !== null ? activeFaultForDisplay(node, readFault(r.id)) : null;
+        const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
+        const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycle}${child}${below}${askBadge(r.id, asks)}${activityCell(r.id, node)}${faultSuffix}`;
+        return wrap(line, isAttached(r.id, node, snapshot.focused));
+    }
     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);
+        const rows = this.snapshot?.rows ?? [];
         // 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) {
@@ -133,18 +304,20 @@ export class GraphOverlay {
             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));
+            const snapshot = this.snapshot;
+            body.push(snapshot !== undefined ? this.renderSnapshotRow(snapshot, rows[i], i === cursorIdx, 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 title = rows.length > 0
+            ? `${BOLD}⌗ canvas graph${RESET} ${DIM}(${cursorIdx + 1}/${rows.length})${RESET}`
+            : `${BOLD}⌗ canvas graph${RESET} ${DIM}(loading)${RESET}`;
         const hint = this.pendingConfirm !== undefined
             ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}y/n${RESET}`
             : GRAPH_HINT;
@@ -205,7 +378,8 @@ export class GraphOverlay {
             this.close();
             return;
         }
-        const rows = buildGraphModel(this.self, this.folds);
+        const snapshot = this.snapshot;
+        const rows = snapshot?.rows ?? [];
         let idx = rows.findIndex((r) => r.id === this.cursorId);
         if (idx < 0)
             idx = Math.max(0, rows.findIndex((r) => r.id === this.self));
@@ -236,26 +410,28 @@ export class GraphOverlay {
             if (cur !== undefined && cur.hasKids && !cur.collapsed) {
                 this.userCollapsed.add(cur.id);
                 this.userExpanded.delete(cur.id);
+                this.refresh();
             }
             else {
-                const p = managerOf(this.cursorId ?? this.self);
+                const p = snapshot?.managerOf.get(this.cursorId ?? this.self);
                 if (p !== undefined && rows.some((r) => r.id === p))
                     this.cursorId = p;
+                this.tui.requestRender();
             }
-            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);
+                this.refresh();
             }
             else if (cur !== undefined && cur.hasKids) {
-                const c = sortedChildIds(cur.id)[0];
+                const c = snapshot?.sortedChildIds.get(cur.id)?.[0];
                 if (c !== undefined)
                     this.cursorId = c;
+                this.tui.requestRender();
             }
-            this.tui.requestRender();
             return;
         }
         if (matchesKey(data, 'enter')) {
@@ -265,7 +441,7 @@ export class GraphOverlay {
             return;
         }
         if (matchesKey(data, 'm')) {
-            const mgr = managerOf(this.self);
+            const mgr = snapshot?.managerOf.get(this.self);
             if (mgr !== undefined) {
                 this.focusTarget(mgr);
                 this.close();
@@ -274,7 +450,7 @@ export class GraphOverlay {
         }
         if (matchesKey(data, 'x')) {
             const target = this.cursorId ?? this.self;
-            const n = cNode(target);
+            const n = snapshot?.nodes.get(target) ?? null;
             const nm = n !== null ? fullName(n) : shortId(target);
             this.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'lifecycle', 'close', '--node', target]) };
             this.tui.requestRender();
@@ -289,6 +465,9 @@ export class GraphOverlay {
      *  `id` has no viewer yet a fresh one splits beside this pane; if it already has
      *  one, that viewer is navigated in place (this pane is left as-is). We pass
      *  TMUX_PANE explicitly so the anchor is THIS pane even if env resolution differs. */
+    logAsyncFailure(label, err) {
+        process.stderr.write(`[crtr attach] ${label}: ${String(err?.message ?? err)}\n`);
+    }
     focusTarget(id) {
         const argv = ['node', 'focus', id];
         const pane = process.env['TMUX_PANE'];

package/dist/clients/attach/transport-relay.d.ts

@@ -0,0 +1,51 @@
+import { EventEmitter } from 'node:events';
+import type { ClientToBroker } from '../../core/runtime/broker-protocol.js';
+import { type Transport } from './transport.js';
+/** A resolved remote canvas target — see `remote-canvas-target.ts` for how
+ *  this is assembled from config + the token's env var, never from argv. */
+export interface RelayTarget {
+    /** The preview endpoint origin, e.g. `https://<hash>.preview.bl.run`. */
+    previewEndpoint: string;
+    /** The raw relay/bearer token. NEVER logged, NEVER echoed. */
+    relayToken: string;
+}
+export declare class RelayTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly target;
+    private ws;
+    private closeEmitted;
+    /** One redial fault line per reconnect EPISODE, not per attempt — mirrors
+     *  SocketTransport. */
+    private redialFaultRecorded;
+    constructor(nodeId: string, target: RelayTarget);
+    private get url();
+    private recordRelayFault;
+    private dial;
+    connect(): void;
+    /** Re-dial the SAME `wss://<previewEndpoint>/node/<id>` — the preview
+     *  endpoint is the stable anchor remotely, as `view.sock` is locally. */
+    redial(): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private onMessage;
+    private onError;
+    /** WS close codes mirror the SAME semantics the browser relay client
+     *  (`clients/web/web-client/broker-client.ts`'s `onclose` / `src/web/
+     *  transport-stream.ts`'s `classifyClose`): 1008 invalid id, or a 1011 whose
+     *  REASON starts with "no running broker"/"no node " (the relay's exact
+     *  wording — `src/clients/web/server.ts`), are the terminal "gone" signals —
+     *  surfaced as BrokerUnavailableError so the reconnect supervisor's normal
+     *  give-up path applies uniformly across transports. `fault-classifier.ts`'s
+     *  `classify` is consulted only for the 1008/protocol case (parity with the
+     *  browser client), NOT for 1011 — `classifyWsClose`'s 1011 case answers "is
+     *  this reason connection-shaped", the OPPOSITE question from "is the
+     *  broker/node gone", so branching on its `kind` here previously inverted
+     *  the gone/not-gone decision (a real bug caught by the mock-relay test, see
+     *  `transport-relay.test.ts`). Everything else (1006 abnormal, 1000 normal,
+     *  or an unrecognized 1011 reason) is a transient/expected drop the caller
+     *  may redial. */
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    private emitError;
+}

package/dist/clients/attach/transport-relay.js

@@ -0,0 +1,196 @@
+// transport-relay.ts — the REMOTE Transport: a relayed WebSocket straight to
+// `wss://<previewEndpoint>/node/<id>`, through the in-guest model-auth-front
+// (bearer-gated on the home's relay token), to the SAME `/node/<id>` handler
+// `crtr surface web serve` already exposes for the browser client
+// (`src/clients/web/server.ts`). One JSON frame per WS message, both
+// directions — no FrameDecoder needed (WS preserves message boundaries).
+//
+// Deliberately NOT the Hearth CP relay: the CP hard-pins its WS upstream to
+// the home's single `home_agent_target`, so it can only ever reach the home
+// node (findings-remote-attach-feasibility.md D1). model-auth-front does not
+// pin — it forwards path verbatim — so this is the only route that reaches an
+// arbitrary node id, which is what makes multi-node remote attach possible.
+//
+// The relay token is the SAME in-guest credential model-auth-front already
+// gates on; holding it is the in-guest trust tier, not a new one. Callers
+// must keep it off argv/shell history (see `remote-canvas-target.ts`) — this
+// transport only ever sends it as a request header, never logs it.
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+import { classify } from '../../core/fault-classifier.js';
+import { clearFault, recordFault } from '../../core/runtime/fault.js';
+import { BrokerUnavailableError } from './transport.js';
+function relayUrl(target, nodeId) {
+    const url = new URL(target.previewEndpoint);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
+    url.pathname = `/node/${encodeURIComponent(nodeId)}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+export class RelayTransport extends EventEmitter {
+    nodeId;
+    target;
+    ws;
+    closeEmitted = false;
+    /** One redial fault line per reconnect EPISODE, not per attempt — mirrors
+     *  SocketTransport. */
+    redialFaultRecorded = false;
+    constructor(nodeId, target) {
+        super();
+        this.nodeId = nodeId;
+        this.target = target;
+    }
+    get url() {
+        return relayUrl(this.target, this.nodeId);
+    }
+    recordRelayFault(op, err) {
+        if (op === 'redial') {
+            if (this.redialFaultRecorded)
+                return;
+            this.redialFaultRecorded = true;
+        }
+        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),
+        });
+    }
+    dial() {
+        const ws = new WebSocket(this.url, {
+            headers: { authorization: `Bearer ${this.target.relayToken}` },
+            perMessageDeflate: false,
+        });
+        this.ws = ws;
+        return ws;
+    }
+    connect() {
+        const ws = this.dial();
+        ws.on('open', () => {
+            this.redialFaultRecorded = false;
+            clearFault(this.nodeId, { link: 'viewer↔broker' });
+            this.emit('connect');
+        });
+        ws.on('message', (data) => this.onMessage(data));
+        ws.on('error', (err) => this.onError(err, 'connect'));
+        ws.on('close', (code, reason) => this.onClose(code, reason.toString()));
+    }
+    /** Re-dial the SAME `wss://<previewEndpoint>/node/<id>` — the preview
+     *  endpoint is the stable anchor remotely, as `view.sock` is locally. */
+    redial() {
+        this.destroy();
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const ws = this.dial();
+            let settled = false;
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.redialFaultRecorded = false;
+                clearFault(this.nodeId, { link: 'viewer↔broker' });
+                this.emit('connect');
+                resolve();
+            });
+            ws.on('message', (data) => this.onMessage(data));
+            ws.on('error', (err) => {
+                if (settled) {
+                    this.onError(err, 'redial');
+                    return;
+                }
+                settled = true;
+                this.recordRelayFault('redial', err);
+                try {
+                    ws.terminate();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            ws.on('close', (code, reason) => {
+                if (!settled)
+                    return; // the 'error' handler above already rejected
+                this.onClose(code, reason.toString());
+            });
+        });
+    }
+    send(frame) {
+        const ws = this.ws;
+        if (ws === undefined || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    destroy() {
+        const ws = this.ws;
+        if (ws !== undefined && ws.readyState <= WebSocket.OPEN) {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    onMessage(data) {
+        let frame;
+        try {
+            frame = JSON.parse(data.toString());
+        }
+        catch {
+            // A malformed frame must never crash the client — drop it (parity with
+            // the local FrameDecoder's own bad-JSON handling).
+            return;
+        }
+        this.emit('frame', frame);
+    }
+    onError(err, op) {
+        this.recordRelayFault(op, err);
+        this.emitError(new Error(`relay transport error: ${err.message}`));
+        // 'close' follows 'error'; teardown converges there.
+    }
+    /** WS close codes mirror the SAME semantics the browser relay client
+     *  (`clients/web/web-client/broker-client.ts`'s `onclose` / `src/web/
+     *  transport-stream.ts`'s `classifyClose`): 1008 invalid id, or a 1011 whose
+     *  REASON starts with "no running broker"/"no node " (the relay's exact
+     *  wording — `src/clients/web/server.ts`), are the terminal "gone" signals —
+     *  surfaced as BrokerUnavailableError so the reconnect supervisor's normal
+     *  give-up path applies uniformly across transports. `fault-classifier.ts`'s
+     *  `classify` is consulted only for the 1008/protocol case (parity with the
+     *  browser client), NOT for 1011 — `classifyWsClose`'s 1011 case answers "is
+     *  this reason connection-shaped", the OPPOSITE question from "is the
+     *  broker/node gone", so branching on its `kind` here previously inverted
+     *  the gone/not-gone decision (a real bug caught by the mock-relay test, see
+     *  `transport-relay.test.ts`). Everything else (1006 abnormal, 1000 normal,
+     *  or an unrecognized 1011 reason) is a transient/expected drop the caller
+     *  may redial. */
+    onClose(code, reason) {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        const classified = classify('viewer↔broker', { code, reason });
+        const gone = code === 1008 ||
+            classified.kind === 'protocol' ||
+            (code === 1011 && (/^no running broker/.test(reason) || /^no node /.test(reason)));
+        if (gone) {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        this.emit('close');
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

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

@@ -0,0 +1,29 @@
+import { EventEmitter } from 'node:events';
+import { type ClientToBroker } from '../../core/runtime/broker-protocol.js';
+import { type Transport } from './transport.js';
+export declare class SocketTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private socket;
+    private decoder;
+    private closeEmitted;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    private redialFaultRecorded;
+    constructor(nodeId: string);
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath(): string;
+    private recordSocketFault;
+    connect(): void;
+    /** Re-establish the socket after a broker exit, on the SAME stable
+     *  `view.sock` path. Installs a FRESH FrameDecoder (a half-frame from the
+     *  dead stream must not corrupt the new one). */
+    redial(): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private onData;
+    private onError;
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    private emitError;
+}