@north-light/crouter 0.3.154

package/dist/core/broker-client/client.js

@@ -0,0 +1,189 @@
+// client.ts — THE broker protocol client. Every Node process that talks to a
+// node's broker over `view.sock` uses this one class: the `crtr surface attach`
+// viewer, `core/view/stream-local`, `auth-reload`, `model-swap`, and the
+// human-prompt dequeue path. (The browser has its own module under
+// `clients/web/web-client/` until that is made isomorphic — see the target
+// architecture note; `daemon/api/bridge.ts` is a byte relay, not a client.)
+//
+// The §0 ONE-WRITER INVARIANT lives here: a client has ONLY a Transport
+// (`transport.ts`) to an ALREADY-running headless broker — locally over its
+// unix socket (`SocketTransport`, `nodeDir(id)/view.sock`), or remotely over a
+// relayed WebSocket to the Blaxel preview endpoint (`RelayTransport`,
+// `transport-relay.ts`). BrokerClient NEVER spawns pi, NEVER opens the session
+// `.jsonl`, NEVER constructs an engine — if the broker is not running, connect
+// fails and the caller exits (focus/revive is what keeps a broker alive, not
+// attach). It also never uses pi's `RpcClient` (which would spawn its own
+// engine).
+//
+// Everything in this file is transport-agnostic: request correlation (the
+// pending map), the reconnect give-up predicate, and close handling are the
+// SAME regardless of which Transport is plugged in at construction — only the
+// wire differs. See `transport.ts` for the seam contract. Fault recording
+// (`viewer↔broker` canvas fault rows) belongs to the transport that can
+// produce a dial error, and lives in `SocketTransport`.
+//
+// Reconnect: a dropped broker emits `close`; the caller's reconnect supervisor
+// decides whether to re-dial (a yield/revive keeps the SAME target — a local
+// `view.sock` path, or a remote preview endpoint — `redial()` re-establishes
+// the connection to it) or give up ("broker gone"). A connect-time
+// unavailable-broker signal surfaces as `BrokerUnavailableError` so the FIRST
+// connect exits non-zero with a clear message; the same signal during a
+// redial rejects the redial promise as retryable.
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { SocketTransport } from './transport-socket.js';
+export { BrokerUnavailableError } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport } from './transport-relay.js';
+/** How long {@link BrokerClient.request} waits for the correlated reply before
+ *  rejecting — bounds a pending picker fetch if the broker drops the request
+ *  (it should always reply with `data` or a correlated `error`). */
+const REQUEST_TIMEOUT_MS = 10_000;
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same target while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
+ *  terminal — an idle-release node revives on its next inbox wake, so keep
+ *  trying (the supervisor waits at a relaxed cadence for as long as the row
+ *  stays live). Local canvas rows only — a remote target has no local row, so
+ *  callers driving a remote attach must not consult this (see viewer.ts). */
+export function reconnectShouldGiveUp(row) {
+    if (row === null)
+        return true;
+    return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+}
+export class BrokerClient extends EventEmitter {
+    nodeId;
+    transport;
+    emitUnmatchedDataFrames;
+    closeEmitted = false;
+    /** Tracks live connect↔close state so {@link request} can fail fast on a
+     *  dead/absent connection rather than parking a promise the reply will
+     *  never reach (transport-agnostic mirror of the old socket.destroyed
+     *  check). A post-close request lands here too — {@link rejectAllPending}
+     *  already ran by the time this flips false. */
+    connected = false;
+    /** The last transport-level error message, so a close can reject any
+     *  in-flight requests with the precise reason (e.g. an oversized-frame
+     *  overflow) instead of a generic one. Cleared on every fresh connect. */
+    lastTransportError;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
+    pending = new Map();
+    constructor(nodeId, options = {}) {
+        super();
+        this.nodeId = nodeId;
+        this.emitUnmatchedDataFrames = options.emitUnmatchedDataFrames ?? false;
+        this.transport = options.transport ?? new SocketTransport(nodeId);
+        this.transport.on('connect', () => {
+            this.closeEmitted = false;
+            this.connected = true;
+            this.lastTransportError = undefined;
+            this.emit('connect');
+        });
+        this.transport.on('frame', (frame) => this.onFrame(frame));
+        this.transport.on('error', (err) => {
+            this.lastTransportError = err.message;
+            this.emitError(err);
+        });
+        this.transport.on('close', () => this.onClose());
+    }
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or transport teardown). Mints
+     *  the `id`, sends `{...frame, id}`, and parks a resolver consumed by
+     *  {@link onFrame}. The reply is narrowed by the caller on its `kind`. */
+    request(frame) {
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            if (!this.connected) {
+                reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${frame.type}' timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ ...frame, id });
+        });
+    }
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
+    rejectAllPending(reason) {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+    /** Open the connection. Emits `connect` on success or `error` (a
+     *  {@link BrokerUnavailableError} when the target has no reachable broker)
+     *  on failure. Idempotent guard is the caller's job — call once. */
+    connect() {
+        this.transport.connect();
+    }
+    /** Re-establish the connection after a broker exit (a yield→revive cycle),
+     *  to the SAME target. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on a retryable dial failure. */
+    redial() {
+        return this.transport.redial();
+    }
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
+    send(frame) {
+        this.transport.send(frame);
+    }
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
+    close() {
+        this.transport.destroy();
+    }
+    onFrame(frame) {
+        // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
+        // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
+        // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
+        // frame is ALWAYS a reply, so by default it is swallowed unconditionally —
+        // even a late post-timeout one (no pending entry) is dropped, never leaked
+        // to the router; `emitUnmatchedDataFrames` opts a caller into seeing those.
+        // An `error` is correlated only when its `id` matches an in-flight request;
+        // an uncorrelated error still flows through.
+        if (frame.type === 'data') {
+            const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+            if (entry) {
+                this.pending.delete(frame.id);
+                clearTimeout(entry.timer);
+                entry.resolve(frame);
+            }
+            else if (this.emitUnmatchedDataFrames) {
+                this.emit('frame', frame);
+            }
+            return;
+        }
+        if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+            const entry = this.pending.get(frame.id);
+            this.pending.delete(frame.id);
+            clearTimeout(entry.timer);
+            entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+            return;
+        }
+        this.emit('frame', frame);
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        this.connected = false;
+        this.rejectAllPending(this.lastTransportError ?? 'broker connection closed');
+        this.emit('close');
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

package/dist/core/broker-client/index.d.ts

@@ -0,0 +1 @@
+export { BrokerClient, BrokerUnavailableError, reconnectShouldGiveUp, RelayTransport, SocketTransport, type BrokerClientOptions, type ReadOpRequest, type RelayTarget, type Transport, } from './client.js';

package/dist/core/broker-client/index.js

@@ -0,0 +1,13 @@
+// core/broker-client — the ONE `view.sock` protocol client for Node processes.
+//
+// `client.ts` owns the protocol (request correlation, the pending map, close
+// handling, the reconnect give-up predicate); `transport.ts` is the seam, with
+// two implementations — `transport-socket.ts` (local unix socket) and
+// `transport-relay.ts` (remote wss via the preview endpoint). The wire format
+// itself stays in `core/runtime/broker-protocol.ts`, which both the broker and
+// every client share.
+//
+// Nothing here reads or writes canvas state: a caller that needs the graph goes
+// to crtrd `/v1`, and a caller that needs a surface goes to tmux placement. That
+// is what keeps this module importable from a CLI leaf (V-1).
+export { BrokerClient, BrokerUnavailableError, reconnectShouldGiveUp, RelayTransport, SocketTransport, } from './client.js';

package/dist/core/broker-client/transport-relay.d.ts

@@ -0,0 +1,51 @@
+import { EventEmitter } from 'node:events';
+import type { ClientToBroker } from '../runtime/broker-protocol.js';
+import { type Transport } from './transport.js';
+/** A resolved remote canvas target — see `core/view/remote-canvas-target.ts` for how
+ *  this is assembled from config (`relayTokenRef`) plus the 0600 secrets store
+ *  via `resolveRemoteCanvasTarget`. This transport itself never takes the
+ *  token from argv — `canvas config add --relay-token -` is the only accepted
+ *  form for writing a token to the store — stdin-only, never argv; that is a
+ *  one-time config-write path, not this call. */
+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;
+    constructor(nodeId: string, target: RelayTarget);
+    private get url();
+    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/core/broker-client/transport-relay.js

@@ -0,0 +1,169 @@
+// 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 `core/view/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 '../fault-classifier.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;
+    constructor(nodeId, target) {
+        super();
+        this.nodeId = nodeId;
+        this.target = target;
+    }
+    get url() {
+        return relayUrl(this.target, this.nodeId);
+    }
+    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.emit('connect');
+        });
+        ws.on('message', (data) => this.onMessage(data));
+        ws.on('error', (err) => this.onError(err));
+        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.emit('connect');
+                resolve();
+            });
+            ws.on('message', (data) => this.onMessage(data));
+            ws.on('error', (err) => {
+                if (settled) {
+                    this.onError(err);
+                    return;
+                }
+                settled = true;
+                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) {
+        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/core/broker-client/transport-socket.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from 'node:events';
+import { type ClientToBroker } from '../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;
+}

package/dist/core/broker-client/transport-socket.js

@@ -0,0 +1,164 @@
+// transport-socket.ts — the LOCAL unix-socket Transport. This is the ORIGINAL
+// view-socket wire logic (node:net + the bounded FrameDecoder), unchanged in
+// behavior, extracted behind the `Transport` interface so BrokerClient can
+// also ride a `RelayTransport` (transport-relay.ts).
+//
+// Connects to a node's ALREADY-running headless broker over its unix socket
+// (`nodeDir(id)/view.sock`). NEVER spawns pi, NEVER opens the session
+// `.jsonl` — if the broker is not running, connect fails with a
+// BrokerUnavailableError.
+import { EventEmitter } from 'node:events';
+import { createConnection } from 'node:net';
+import { viewSocketPath } from '../canvas/paths.js';
+import { classify } from '../fault-classifier.js';
+import { clearFault, recordFault } from '../runtime/fault.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../runtime/broker-protocol.js';
+import { BrokerUnavailableError } from './transport.js';
+export class SocketTransport extends EventEmitter {
+    nodeId;
+    socket;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    redialFaultRecorded = false;
+    constructor(nodeId) {
+        super();
+        this.nodeId = nodeId;
+    }
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath() {
+        return viewSocketPath(this.nodeId);
+    }
+    recordSocketFault(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),
+        });
+    }
+    connect() {
+        const socket = createConnection(this.socketPath);
+        this.socket = socket;
+        socket.on('connect', () => {
+            this.redialFaultRecorded = false;
+            clearFault(this.nodeId, { link: 'viewer↔broker' });
+            this.emit('connect');
+        });
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('error', (err) => this.onError(err, 'connect'));
+        socket.on('close', () => this.onClose());
+    }
+    /** 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() {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const socket = createConnection(this.socketPath);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.redialFaultRecorded = false;
+                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, 'redial');
+                    return;
+                }
+                settled = true;
+                this.recordSocketFault('redial', err);
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            socket.on('close', () => this.onClose());
+        });
+    }
+    send(frame) {
+        const sock = this.socket;
+        if (sock === undefined || sock.destroyed)
+            return;
+        try {
+            sock.write(encodeFrame(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    destroy() {
+        const sock = this.socket;
+        if (sock !== undefined && !sock.destroyed) {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    onData(chunk) {
+        let frames;
+        try {
+            frames = this.decoder.push(chunk);
+        }
+        catch (err) {
+            // A broker that somehow emits an oversized frame (or a corrupt stream):
+            // clean error + drop, never a crash. The 'close' that follows destroy()
+            // is what rejects any in-flight BrokerClient requests.
+            const msg = err instanceof FrameOverflowError
+                ? `broker sent an oversized frame (${err.message}) — disconnecting`
+                : `failed to decode a broker frame: ${String(err)}`;
+            this.emitError(new Error(msg));
+            this.destroy();
+            return;
+        }
+        for (const raw of frames)
+            this.emit('frame', raw);
+    }
+    onError(err, op) {
+        this.recordSocketFault(op, err);
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        else {
+            this.emitError(new Error(`view socket error: ${err.message}`));
+        }
+        // 'close' typically follows 'error'; teardown converges there.
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        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/core/broker-client/transport.d.ts

@@ -0,0 +1,32 @@
+import type { EventEmitter } from 'node:events';
+import type { BrokerToClient, ClientToBroker } from '../runtime/broker-protocol.js';
+export interface Transport extends EventEmitter {
+    /** Open the connection. Emits 'connect' on success, 'error' on a fatal
+     *  connect-time failure. Call once. */
+    connect(): void;
+    /** Re-establish the connection to the SAME target after a drop. Resolves on
+     *  a fresh 'connect'; rejects on a retryable dial failure (the caller's
+     *  reconnect supervisor decides whether to try again). */
+    redial(): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent connection;
+     *  never throws. */
+    send(frame: ClientToBroker): void;
+    /** Tear down the connection. 'close' fires if it has not already. */
+    destroy(): void;
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+/** Surfaced when a Transport's target has no reachable broker — locally, no
+ *  socket file / nothing listening; remotely, a relay close signaling "no
+ *  broker for this node". The command catches this to exit non-zero with a
+ *  focus/revive hint — same meaning regardless of which Transport raised it. */
+export declare class BrokerUnavailableError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}