@north-light/crouter 0.3.154

package/dist/core/bash-jobs.js

@@ -0,0 +1,150 @@
+// File-backed control plane for bash commands that have been handed off by the
+// canvas bash valve. The valve starts every command in one of these directories;
+// the prefix menu requests backgrounding by creating job.bg. Keeping that signal
+// on disk means the command can outlive its pi process and still report its exit.
+import { randomBytes } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function bashJobsDir(contextDir) {
+    return join(contextDir, 'jobs');
+}
+export function bashJobPaths(contextDir, jobId) {
+    const dir = join(bashJobsDir(contextDir), jobId);
+    return {
+        jobId,
+        dir,
+        cmdSh: join(dir, 'cmd.sh'),
+        jobLog: join(dir, 'job.log'),
+        jobExit: join(dir, 'job.exit'),
+        jobBg: join(dir, 'job.bg'),
+    };
+}
+/** Mint a fresh job id — `${Date.now()}-${hex}`. The sole minting site; the
+ * valve calls this instead of building the literal inline so the epoch-ms
+ * prefix is a real contract shared with its parser (jobStartedAtMs), not an
+ * incidental string format. */
+export function newBashJobId() {
+    return `${Date.now()}-${randomBytes(4).toString('hex')}`;
+}
+/** Parse the start epoch (ms) out of a job id's prefix. undefined unless the
+ * id is exactly `<finite-number>-<nonempty-suffix>` — defensive against a
+ * hand-created directory that doesn't follow the newBashJobId contract,
+ * including one with no separator at all (`indexOf('-') === -1` must not
+ * silently parse as a truncated prefix). */
+export function jobStartedAtMs(jobId) {
+    const sep = jobId.indexOf('-');
+    if (sep <= 0 || sep === jobId.length - 1)
+        return undefined;
+    const n = Number(jobId.slice(0, sep));
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Render an elapsed duration the way every bash-handoff surface (the valve's
+ * notice, the `node bash background` result/toast, and the attach cockpit)
+ * shows it: `<60s -> "12s"`; `60s-59m -> "3m 40s"`; `>=60m -> "1h 04m"`. */
+export function formatBashElapsed(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const totalMinutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (totalMinutes < 60)
+        return `${totalMinutes}m ${String(seconds).padStart(2, '0')}s`;
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return `${hours}h ${String(minutes).padStart(2, '0')}m`;
+}
+/** Every live backgrounded bash job for this node — job.bg present, job.exit
+ * absent — whether handed off by the menu or auto-backgrounded at the valve's
+ * deadline. Read-only; never mutates. Distinct from (and shares no code path
+ * with) the foreground-only `runningBashJobs` above: that scanner deliberately
+ * EXCLUDES job.bg, this one REQUIRES it, so reusing one for the other would
+ * corrupt foreground-admission semantics. Skips malformed/partially-written
+ * directories. Returns oldest-first by startedAtMs. */
+export function activeBackgroundBashJobs(contextDir) {
+    let entries;
+    try {
+        entries = readdirSync(bashJobsDir(contextDir));
+    }
+    catch {
+        return [];
+    }
+    const jobs = [];
+    for (const jobId of entries) {
+        const paths = bashJobPaths(contextDir, jobId);
+        if (!existsSync(paths.jobBg) || existsSync(paths.jobExit))
+            continue;
+        const startedAtMs = jobStartedAtMs(jobId);
+        if (startedAtMs === undefined)
+            continue;
+        let command;
+        try {
+            command = readFileSync(paths.cmdSh, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        jobs.push({ jobId, command, startedAtMs, logPath: paths.jobLog });
+    }
+    return jobs.sort((a, b) => a.startedAtMs - b.startedAtMs);
+}
+/** Every still-foreground bash command for this node. A completed command has
+ * job.exit; an already-backgrounded one has job.bg and must not be selected a
+ * second time. Invalid or concurrently-removed directories are ignored. */
+function runningBashJobs(contextDir) {
+    let entries;
+    try {
+        entries = readdirSync(bashJobsDir(contextDir));
+    }
+    catch {
+        return [];
+    }
+    return entries.flatMap((jobId) => {
+        const paths = bashJobPaths(contextDir, jobId);
+        return existsSync(paths.cmdSh) && existsSync(paths.jobLog) && !existsSync(paths.jobExit) && !existsSync(paths.jobBg)
+            ? [paths]
+            : [];
+    });
+}
+/** The start time (ms epoch) of the OLDEST still-foreground bash command for
+ * this node, or undefined when none is running. This is the authoritative
+ * source for the attach viewer's R4 "background it" footer hint: it reads the
+ * exact same on-disk contract the valve writes (a job directory exists with
+ * no job.bg and no job.exit while the command is running in the foreground,
+ * and the valve deletes the directory the moment the command finishes or is
+ * aborted — see canvas-bash-valve.ts), so a fresh or reconnected attach (which
+ * has no memory of a broker-relayed tool-execution event) sees exactly what's
+ * really running, and a viewer never needs its own call-id tracking that could
+ * go stale across a broker/session replacement. */
+export function oldestRunningBashJobStartedAtMs(contextDir) {
+    let oldest;
+    for (const paths of runningBashJobs(contextDir)) {
+        const startedAtMs = jobStartedAtMs(paths.jobId);
+        if (startedAtMs === undefined)
+            continue;
+        if (oldest === undefined || startedAtMs < oldest)
+            oldest = startedAtMs;
+    }
+    return oldest;
+}
+/** Request immediate handoff for every bash command still waiting on pi. The
+ * valve observes job.bg within one poll, resolves the tool call, and leaves its
+ * detached supervisor to notify the node when the real command exits. */
+export function backgroundRunningBashJobs(contextDir) {
+    const backgrounded = [];
+    for (const paths of runningBashJobs(contextDir)) {
+        try {
+            // A job may exit or be claimed by another prefix press between the scan
+            // and this write. Recheck the two terminal/control files so that stale
+            // candidates never masquerade as a successful handoff.
+            if (existsSync(paths.jobExit) || existsSync(paths.jobBg))
+                continue;
+            writeFileSync(paths.jobBg, '');
+            backgrounded.push(paths);
+        }
+        catch {
+            // The valve owns cleanup; a concurrently removed directory is simply no
+            // longer a running command to hand off.
+        }
+    }
+    return backgrounded;
+}

package/dist/core/bootstrap.d.ts

@@ -0,0 +1,5 @@
+export declare const OFFICIAL_MARKETPLACE_NAME = "crouter-official-marketplace";
+export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs/crouter-official-marketplace.git";
+export declare const OFFICIAL_MARKETPLACE_REF = "main";
+export declare function ensureOfficialMarketplace(argv: string[]): void;
+export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -0,0 +1,98 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js';
+import { ensureDir, pathExists, removePath, nowIso } from './fs-utils.js';
+import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
+import { clone } from './git.js';
+import { readMarketplaceManifest } from './manifest.js';
+import { CRTR_DIR_NAME } from '../types.js';
+export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
+export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
+export const OFFICIAL_MARKETPLACE_REF = 'main';
+const SKIP_SUBCOMMANDS = new Set([
+    'help',
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+]);
+function shouldSkipForArgv(argv) {
+    const sub = argv[2];
+    if (sub === undefined)
+        return true;
+    return SKIP_SUBCOMMANDS.has(sub);
+}
+export function ensureOfficialMarketplace(argv) {
+    try {
+        if (process.env.CRTR_NO_BOOTSTRAP === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        const state = readState('user');
+        if (state.bootstrap_done === true)
+            return;
+        const cfg = readConfig('user');
+        if (cfg.marketplaces[OFFICIAL_MARKETPLACE_NAME] !== undefined) {
+            updateState('user', (s) => {
+                s.bootstrap_done = true;
+            });
+            return;
+        }
+        const root = userScopeRoot();
+        ensureScopeInitialized('user', root);
+        const mktsDir = join(root, 'marketplaces');
+        ensureDir(mktsDir);
+        const dest = join(mktsDir, OFFICIAL_MARKETPLACE_NAME);
+        if (pathExists(dest)) {
+            removePath(dest);
+        }
+        clone(OFFICIAL_MARKETPLACE_URL, dest, { depth: 1, ref: OFFICIAL_MARKETPLACE_REF });
+        const manifest = readMarketplaceManifest(dest);
+        if (manifest === null) {
+            removePath(dest);
+            return;
+        }
+        updateConfig('user', (c) => {
+            c.marketplaces[OFFICIAL_MARKETPLACE_NAME] = {
+                url: OFFICIAL_MARKETPLACE_URL,
+                ref: OFFICIAL_MARKETPLACE_REF,
+                installed_at: nowIso(),
+            };
+        });
+        updateState('user', (s) => {
+            s.bootstrap_done = true;
+        });
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: bootstrap error: ${msg}\n`);
+        }
+    }
+}
+export function ensureProjectScope(argv) {
+    try {
+        if (process.env.CRTR_NO_AUTO_INIT === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        // Already inside a project scope (here or in an ancestor) — nothing to do.
+        if (findProjectScopeRoot() !== null)
+            return;
+        const cwd = process.cwd();
+        // Never auto-init at $HOME — that path is reserved for the user scope.
+        if (cwd === homedir())
+            return;
+        const projectRoot = join(cwd, CRTR_DIR_NAME);
+        if (projectRoot === userScopeRoot())
+            return;
+        ensureScopeInitialized('project', projectRoot);
+        resetScopeCache();
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: project-init error: ${msg}\n`);
+        }
+    }
+}

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

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

package/dist/core/broker-client/__tests__/transport-relay.test.js

@@ -0,0 +1,213 @@
+// transport-relay.test.ts — mock-relay coverage for RelayTransport
+// (`../transport-relay.ts`), the REMOTE half of the Transport seam.
+// Fast tier: a plain `ws` WebSocketServer standing in for model-auth-front's
+// relay, no pi boot, no broker. Exercises exactly what the handoff doc
+// flagged as unverified: the Authorization header, the one-JSON-frame-per-
+// WS-message wire, the 1011/1008 "gone" close-code classification (and its
+// NOT-gone counterparts), and a non-101 handshake response (bad token) not
+// hanging connect().
+import assert from 'node:assert/strict';
+import test, { after, before } from 'node:test';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { RelayTransport } from '../transport-relay.js';
+import { BrokerUnavailableError } from '../transport.js';
+import { jobDir } from '../../canvas/paths.js';
+/** Stand up a bare `ws` server on an ephemeral loopback port — the "relay" a
+ *  RelayTransport dials. Records the Authorization header + accepted sockets
+ *  of every connection so a test can assert on the wire, not just behavior. */
+function startMockRelay() {
+    return new Promise((resolve) => {
+        const wss = new WebSocketServer({ port: 0 });
+        const authHeaders = [];
+        const sockets = [];
+        wss.on('connection', (ws, req) => {
+            authHeaders.push(req.headers.authorization ?? '');
+            sockets.push(ws);
+        });
+        wss.once('listening', () => {
+            const addr = wss.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                target: { previewEndpoint: `http://127.0.0.1:${port}`, relayToken: 'test-token' },
+                authHeaders,
+                sockets,
+                close: () => new Promise((res) => wss.close(() => res())),
+            });
+        });
+    });
+}
+/** Race connect/error the SAME way `viewer.ts`'s runAttach does, cleaning
+ *  up whichever listener didn't fire so later `once('error', ...)` assertions
+ *  in the same test see only the events they're meant to. */
+function connectTransport(transport) {
+    return new Promise((resolve, reject) => {
+        const onConnect = () => {
+            transport.off('error', onError);
+            resolve();
+        };
+        const onError = (err) => {
+            transport.off('connect', onConnect);
+            reject(err);
+        };
+        transport.once('connect', onConnect);
+        transport.once('error', onError);
+        transport.connect();
+    });
+}
+test('RelayTransport sends Authorization: Bearer <token> on connect', async () => {
+    const relay = await startMockRelay();
+    const transport = new RelayTransport('node-auth', relay.target);
+    await connectTransport(transport);
+    assert.equal(relay.authHeaders[0], 'Bearer test-token');
+    transport.destroy();
+    await relay.close();
+});
+test('RelayTransport round-trips one JSON frame per WS message, both directions', async () => {
+    const relay = await startMockRelay();
+    const transport = new RelayTransport('node-echo', relay.target);
+    await connectTransport(transport);
+    // server → client: one broker-protocol frame, one WS message.
+    const ack = { type: 'ack', for: 'hello', ok: true, detail: 'welcome' };
+    const framePromise = new Promise((resolve) => transport.once('frame', resolve));
+    relay.sockets[0].send(JSON.stringify(ack));
+    assert.deepEqual(await framePromise, ack);
+    // client → server: send() produces exactly one WS text message per frame.
+    const hello = { type: 'hello', role: 'controller', client_id: 'c1' };
+    const serverMessages = [];
+    relay.sockets[0].on('message', (data) => serverMessages.push(JSON.parse(data.toString())));
+    transport.send(hello);
+    await new Promise((r) => setTimeout(r, 50));
+    assert.deepEqual(serverMessages, [hello]);
+    transport.destroy();
+    await relay.close();
+});
+test('a 1011 close with "no running broker for <id>" surfaces BrokerUnavailableError', async () => {
+    const relay = await startMockRelay();
+    const transport = new RelayTransport('node-gone', relay.target);
+    await connectTransport(transport);
+    const errorPromise = new Promise((resolve) => transport.once('error', resolve));
+    relay.sockets[0].close(1011, 'no running broker for node-gone');
+    const err = await errorPromise;
+    assert.ok(err instanceof BrokerUnavailableError, `expected BrokerUnavailableError, got ${err}`);
+    await relay.close();
+});
+test('a 1000 normal close does NOT surface BrokerUnavailableError', async () => {
+    const relay = await startMockRelay();
+    const transport = new RelayTransport('node-normal', relay.target);
+    await connectTransport(transport);
+    let sawError;
+    transport.on('error', (err) => {
+        sawError = err;
+    });
+    const closePromise = new Promise((resolve) => transport.once('close', resolve));
+    relay.sockets[0].close(1000, 'normal');
+    await closePromise;
+    assert.equal(sawError, undefined);
+    await relay.close();
+});
+test('an immediate post-upgrade 1011 "no node <id>" close is still caught by a listener installed BEFORE connect() is dialed', async () => {
+    // Mirrors server.ts's bridgeConnection exactly: the relay ACCEPTS the WS
+    // upgrade unconditionally, then discovers synchronously (no data exchange,
+    // no delay from app logic) that the node doesn't exist and closes 1011 —
+    // in the SAME tick the 'connection' handler runs. This is the ordering that
+    // broke `viewer.ts`'s original startup race: the transport's 'connect'
+    // (WS 'open') is structurally guaranteed to fire before any close frame can
+    // be parsed (a close can't precede the handshake that establishes the
+    // connection), so a TEMPORARY connect-race listener torn down as soon as
+    // 'connect' resolves always misses this close. The fix installs a listener
+    // that is never removed instead — reproduced here.
+    const wss = new WebSocketServer({ port: 0 });
+    wss.on('connection', (ws) => {
+        ws.close(1011, 'no node node-gone-fast');
+    });
+    await new Promise((resolve) => wss.once('listening', resolve));
+    const addr = wss.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const transport = new RelayTransport('node-gone-fast', {
+        previewEndpoint: `http://127.0.0.1:${port}`,
+        relayToken: 'test-token',
+    });
+    // Reproduce viewer.ts's durable-listener fix: installed BEFORE
+    // connect() is dialed, and never removed — exactly the guard that survives
+    // the gap a temporary connect-race listener does not.
+    let terminalError;
+    transport.on('error', (err) => {
+        if (terminalError === undefined)
+            terminalError = err;
+    });
+    await new Promise((resolve) => {
+        transport.once('connect', resolve);
+        transport.connect();
+    });
+    // Proves the structural ordering the fix accounts for: 'connect' has ALREADY
+    // resolved here, before the close was ever observed — a naive connect-race
+    // would have already declared success and torn down its error listener.
+    // Compare a boolean rather than `terminalError` itself — `assert.equal`'s
+    // TS signature asserts the narrowed type on its first argument, which would
+    // otherwise wrongly pin `terminalError` to `undefined` for the rest of this
+    // test even though the listener above can still reassign it.
+    assert.equal(terminalError === undefined, true, "connect resolves before the close is observed — that's the bug");
+    // The close lands shortly after — caught by the durable listener, not a
+    // fresh temporary one (there is none left by now).
+    await new Promise((resolve) => transport.once('close', resolve));
+    assert.ok(terminalError !== undefined && terminalError instanceof BrokerUnavailableError, `expected the durable listener to have recorded a BrokerUnavailableError, got ${terminalError}`);
+    transport.destroy();
+    await new Promise((res) => wss.close(() => res()));
+});
+// --- Phase 3 review Major 3: RelayTransport must never write LOCAL fault
+// state keyed by a REMOTE node id (it is only ever constructed for --canvas
+// attach; there is no legitimate local use case). ---
+let faultTestHome;
+before(() => {
+    faultTestHome = mkdtempSync(join(tmpdir(), 'crtr-transport-relay-fault-'));
+    process.env['CRTR_HOME'] = faultTestHome;
+});
+after(() => {
+    rmSync(faultTestHome, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('RelayTransport never writes local fault state for the remote node id, even on a connect failure', async () => {
+    const nodeId = 'remote-fault-test-node';
+    const wss = new WebSocketServer({
+        port: 0,
+        verifyClient: (_info, cb) => cb(false, 401, 'unauthorized'),
+    });
+    await new Promise((resolve) => wss.once('listening', resolve));
+    const addr = wss.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const transport = new RelayTransport(nodeId, {
+        previewEndpoint: `http://127.0.0.1:${port}`,
+        relayToken: 'bad-token',
+    });
+    await new Promise((resolve) => {
+        transport.once('error', () => resolve());
+        transport.connect();
+    });
+    assert.equal(existsSync(join(jobDir(nodeId), 'fault')), false, 'a remote relay connect failure must never write a LOCAL fault file keyed by the remote node id');
+    transport.destroy();
+    await new Promise((res) => wss.close(() => res()));
+});
+test('a non-101 handshake response (401, bad token) rejects connect() with a clear error, not a hang', async () => {
+    const wss = new WebSocketServer({
+        port: 0,
+        verifyClient: (_info, cb) => cb(false, 401, 'unauthorized'),
+    });
+    await new Promise((resolve) => wss.once('listening', resolve));
+    const addr = wss.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const transport = new RelayTransport('node-401', {
+        previewEndpoint: `http://127.0.0.1:${port}`,
+        relayToken: 'bad-token',
+    });
+    const outcome = await Promise.race([
+        connectTransport(transport).then(() => 'connected', (err) => err),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timed out — connect() hung on a non-101 handshake response')), 3000)),
+    ]);
+    assert.notEqual(outcome, 'connected');
+    assert.ok(outcome instanceof Error);
+    assert.match(outcome.message, /relay transport error/);
+    await new Promise((res) => wss.close(() => res()));
+});

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

@@ -0,0 +1,97 @@
+import { EventEmitter } from 'node:events';
+import type { NodeRow } from '../canvas/types.js';
+import type { BrokerDataFrame, BrokerToClient, ClientToBroker, DequeueFrame, GetHumanForkCoordinatesFrame, GetSettingsFrame, GetTreeFrame, ListMemoryRefsFrame, ListModelsFrame, ListScopedModelsFrame, ListSessionsFrame } from '../runtime/broker-protocol.js';
+import { type Transport } from './transport.js';
+export { BrokerUnavailableError, type Transport } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport, type RelayTarget } from './transport-relay.js';
+/** A correlated read-op (or `dequeue`) request MINUS the client-chosen `id` —
+ *  {@link BrokerClient.request} mints the `id`, sends the frame, and resolves
+ *  with the matching `data` reply. The picker/operator code builds these; the
+ *  client owns the correlation token so callers never hand-roll one. */
+export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame, 'id'> | Omit<GetTreeFrame, 'id'> | Omit<GetSettingsFrame, 'id'> | Omit<ListScopedModelsFrame, 'id'> | Omit<DequeueFrame, 'id'> | Omit<GetHumanForkCoordinatesFrame, 'id'> | Omit<ListMemoryRefsFrame, 'id'>;
+export interface BrokerClientOptions {
+    /** Where the frames go. Defaults to a {@link SocketTransport} against this
+     *  node's local `view.sock` — the common case. Pass a {@link RelayTransport}
+     *  to attach a remote node instead; every method behaves identically either
+     *  way. */
+    transport?: Transport;
+    /** Re-emit a `data` frame that matches no in-flight request as a generic
+     *  `frame` event. OFF by default: the attach viewer's frame router would
+     *  mis-handle a stray `data` frame as a pi `AgentSessionEvent`. The operator
+     *  view (`core/view/stream-local.ts`) passes read-op replies through to its
+     *  own consumer and is the one caller that needs `true`. */
+    emitUnmatchedDataFrames?: boolean;
+}
+/** 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 declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
+/** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
+ *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */
+export interface BrokerClient {
+    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: 'frame', listener: (frame: BrokerToClient) => void): this;
+    once(event: 'close', 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;
+}
+export declare class BrokerClient extends EventEmitter {
+    private readonly nodeId;
+    private readonly transport;
+    private readonly emitUnmatchedDataFrames;
+    private closeEmitted;
+    /** 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. */
+    private connected;
+    /** 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. */
+    private 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. */
+    private pending;
+    constructor(nodeId: string, options?: BrokerClientOptions);
+    /** 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: ReadOpRequest): Promise<BrokerDataFrame>;
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
+    private rejectAllPending;
+    /** 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(): void;
+    /** 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(): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
+    send(frame: ClientToBroker): void;
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
+    close(): void;
+    private onFrame;
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    private emitError;
+}