@yefengr/remote-pi 0.7.0

package/dist/protocol/v2/session_state.js

@@ -0,0 +1,176 @@
+import { createHash } from "node:crypto";
+export class V2SessionState {
+    generationValue;
+    maxEntries;
+    ttlMs;
+    clock;
+    channels = new Map();
+    records = new Map();
+    constructor(options) {
+        if (!options.generation)
+            throw new Error("generation is required");
+        this.generationValue = options.generation;
+        this.maxEntries = Math.max(1, Math.floor(options.maxEntries ?? 512));
+        this.ttlMs = Math.max(1, options.ttlMs ?? 10 * 60 * 1000);
+        this.clock = options.clock ?? Date.now;
+    }
+    get generation() {
+        return this.generationValue;
+    }
+    setGeneration(generation) {
+        if (!generation)
+            throw new Error("generation is required");
+        if (generation === this.generationValue)
+            return;
+        this.generationValue = generation;
+        this.records.clear();
+    }
+    hello(senderRef, channelId) {
+        this.assertId(senderRef, "senderRef");
+        this.assertId(channelId, "channelId");
+        const state = {
+            senderRef,
+            channelId,
+            ready: true,
+            lastSeen: this.clock(),
+        };
+        this.channels.set(this.channelKey(senderRef, channelId), state);
+        return state;
+    }
+    touch(senderRef, channelId) {
+        const current = this.get(senderRef, channelId);
+        if (!current)
+            return undefined;
+        const state = { ...current, lastSeen: this.clock() };
+        this.channels.set(this.channelKey(senderRef, channelId), state);
+        return state;
+    }
+    get(senderRef, channelId) {
+        return this.channels.get(this.channelKey(senderRef, channelId));
+    }
+    removeChannel(senderRef, channelId) {
+        this.channels.delete(this.channelKey(senderRef, channelId));
+    }
+    removeOwner(senderRef) {
+        for (const [key, channel] of this.channels) {
+            if (channel.senderRef === senderRef)
+                this.channels.delete(key);
+        }
+        for (const [key, record] of this.records) {
+            if (record.senderRef === senderRef)
+                this.records.delete(key);
+        }
+    }
+    begin(request) {
+        this.prune();
+        this.assertId(request.senderRef, "senderRef");
+        this.assertId(request.clientRequestId, "clientRequestId");
+        const key = this.recordKey(request.senderRef, request.clientRequestId);
+        const fingerprint = fingerprintPayload(request.payload);
+        const existing = this.records.get(key);
+        if (existing) {
+            existing.touchedAt = this.clock();
+            this.records.delete(key);
+            this.records.set(key, existing);
+            return {
+                kind: existing.fingerprint === fingerprint ? "replay" : "conflict",
+                record: { ...existing },
+            };
+        }
+        const record = {
+            key,
+            generation: this.generationValue,
+            senderRef: request.senderRef,
+            clientRequestId: request.clientRequestId,
+            fingerprint,
+            status: "received",
+            touchedAt: this.clock(),
+        };
+        this.records.set(key, record);
+        this.pruneCapacity();
+        return { kind: "new", record: { ...record } };
+    }
+    update(key, status, details = {}) {
+        this.prune();
+        const record = this.records.get(key);
+        if (!record)
+            return undefined;
+        record.status = status;
+        if (details.messageId !== undefined)
+            record.messageId = details.messageId;
+        if (details.groupId !== undefined)
+            record.groupId = details.groupId;
+        record.touchedAt = this.clock();
+        this.records.delete(key);
+        this.records.set(key, record);
+        return { ...record };
+    }
+    rememberUnknownDelivery(key) {
+        return this.update(key, "unknown_delivery");
+    }
+    getRecord(key) {
+        this.prune();
+        const record = this.records.get(key);
+        return record ? { ...record } : undefined;
+    }
+    forget(key) {
+        return this.records.delete(key);
+    }
+    snapshot() {
+        this.prune();
+        return {
+            channels: [...this.channels.values()].map((channel) => ({ ...channel })),
+            records: [...this.records.values()].map((record) => ({ ...record })),
+        };
+    }
+    prune() {
+        const now = this.clock();
+        for (const [key, record] of this.records) {
+            if (now - record.touchedAt >= this.ttlMs)
+                this.records.delete(key);
+        }
+        this.pruneCapacity();
+    }
+    pruneCapacity() {
+        while (this.records.size > this.maxEntries) {
+            const oldest = this.records.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.records.delete(oldest);
+        }
+    }
+    recordKey(senderRef, clientRequestId) {
+        return `${this.generationValue}\u0000${senderRef}\u0000${clientRequestId}`;
+    }
+    channelKey(senderRef, channelId) {
+        return `${senderRef}\u0000${channelId}`;
+    }
+    assertId(value, name) {
+        if (!value || value.length > 256)
+            throw new Error(`${name} is invalid`);
+    }
+}
+function fingerprintPayload(value) {
+    const canonical = canonicalize(value);
+    return createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex");
+}
+function canonicalize(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object") {
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            result[key] = canonicalize(value[key]);
+        }
+        return result;
+    }
+    return String(value);
+}
+export function fingerprintV2Payload(value) {
+    return fingerprintPayload(value);
+}
+//# sourceMappingURL=session_state.js.map

package/dist/protocol/v2/session_state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_state.js","sourceRoot":"","sources":["../../../src/protocol/v2/session_state.ts"],"names":[],"mappings":"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"}

package/dist/rooms.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic room id derived from a cwd. Two Pi processes in the same
+ * directory produce the same id; different cwds produce different ids
+ * (with cryptographic-strength collision resistance). Symlinks are resolved
+ * via `realpath` so `/a` and `/symlink-to-a` map to the same room.
+ *
+ * Format: first 12 chars of base64url(sha256(realpath)).
+ */
+export declare function roomIdForCwd(cwd: string): string;
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export declare function roomIdFor(cwd: string, name?: string): string;

package/dist/rooms.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { defaultAgentName } from "./session/local_config.js";
+/**
+ * Deterministic room id derived from a cwd. Two Pi processes in the same
+ * directory produce the same id; different cwds produce different ids
+ * (with cryptographic-strength collision resistance). Symlinks are resolved
+ * via `realpath` so `/a` and `/symlink-to-a` map to the same room.
+ *
+ * Format: first 12 chars of base64url(sha256(realpath)).
+ */
+export function roomIdForCwd(cwd) {
+    let target;
+    try {
+        target = realpathSync(cwd);
+    }
+    catch {
+        // cwd doesn't exist (unlikely in production) — fallback to raw path.
+        target = cwd;
+    }
+    return createHash("sha256").update(target).digest("base64url").slice(0, 12);
+}
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export function roomIdFor(cwd, name) {
+    if (!name || name === defaultAgentName(cwd))
+        return roomIdForCwd(cwd);
+    let target;
+    try {
+        target = realpathSync(cwd);
+    }
+    catch {
+        target = cwd;
+    }
+    // NUL separator (U+0000): impossible in a POSIX path and stripped from any
+    // sanitized name, so the cwd/name boundary is unambiguous.
+    const sep = String.fromCharCode(0);
+    return createHash("sha256").update(target + sep + name).digest("base64url").slice(0, 12);
+}
+//# sourceMappingURL=rooms.js.map

package/dist/rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../src/rooms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAa;IAClD,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,gBAAgB,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IACtE,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,2EAA2E;IAC3E,2DAA2D;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/dist/session/bridge.d.ts

@@ -0,0 +1,37 @@
+import type { Broker } from "./broker.js";
+import { BrokerRemote } from "./broker_remote.js";
+import { PiForwardClient } from "../transport/pi_forward_client.js";
+import type { RelayClient } from "../transport/relay_client.js";
+import { type MeshTopologySnapshot } from "../mesh/siblings.js";
+import type { Ed25519Keypair } from "../pairing/crypto.js";
+/**
+ * Cross-PC mesh bridge composition. Discovery finishes before either transport
+ * half is constructed, and the returned bridge stays dormant until its caller
+ * has re-checked lifecycle ownership and calls `activate()`.
+ */
+export interface AttachBridgeOptions {
+    /** The leader's local Broker (from SessionPeer.localBroker()). */
+    broker: Broker;
+    /** Live relay connection. Caller owns its lifecycle. */
+    relay: RelayClient;
+    /** Relay URL in http(s):// form — for standalone topology discovery. */
+    relayUrl: string;
+    /** This host's Ed25519 identity (machine Pi-key). */
+    keypair: Ed25519Keypair;
+    /** Retained Pi-produced topology. Supplying it bypasses discovery. */
+    topology?: MeshTopologySnapshot;
+    /** Standalone discovery deadline per mesh request. Defaults to 5 seconds. */
+    meshRequestTimeoutMs?: number;
+    /** Diagnostic logger. Defaults to a no-op (avoids TUI leaks). */
+    log?: (msg: string) => void;
+}
+export interface CrossPcBridge {
+    brokerRemote: BrokerRemote;
+    piForward: PiForwardClient;
+    topology: MeshTopologySnapshot;
+    /** Publish the already-built router exactly once. */
+    activate(): void;
+    /** Safe before or after activation; tears down both halves exactly once. */
+    detach(): void;
+}
+export declare function attachCrossPcBridge(opts: AttachBridgeOptions): Promise<CrossPcBridge>;

package/dist/session/bridge.js

@@ -0,0 +1,130 @@
+import { BrokerRemote } from "./broker_remote.js";
+import { PiForwardClient } from "../transport/pi_forward_client.js";
+import { MeshClient } from "../mesh/client.js";
+import { buildTopologySnapshot, discoverTopology, } from "../mesh/siblings.js";
+import { canonicalizeEd25519PublicKey, encodeEd25519PublicKey, } from "../mesh/encoding.js";
+import { listOwnerPubkeys } from "../pairing/storage.js";
+function compareAscii(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function validateAlias(alias, field) {
+    if (typeof alias !== "string" || alias.length === 0 || alias.includes(":")) {
+        throw new Error(`mesh: ${field} is not a valid routing alias`);
+    }
+    return alias;
+}
+function validateLegacyPcLabel(label, field) {
+    if (typeof label !== "string" || label.length === 0) {
+        throw new Error(`mesh: ${field} is not a valid legacy PC label`);
+    }
+    return label;
+}
+function ownTopology(snapshot, expectedSelfPubkey) {
+    const selfPubkey = canonicalizeEd25519PublicKey(snapshot.self?.pcPubkey, "self public key");
+    if (selfPubkey !== expectedSelfPubkey) {
+        throw new Error("mesh: topology self public key does not match relay identity");
+    }
+    const selfLabel = validateAlias(snapshot.self.pcLabel, "self.pcLabel");
+    const selfLegacyPcLabel = validateLegacyPcLabel(snapshot.self.legacyPcLabel, "self.legacyPcLabel");
+    const self = Object.freeze({
+        pcLabel: selfLabel,
+        pcPubkey: selfPubkey,
+        legacyPcLabel: selfLegacyPcLabel,
+    });
+    const siblingKeys = new Set();
+    const siblingAliases = new Set();
+    const normalizedSiblings = [];
+    for (const [index, sibling] of snapshot.siblings.entries()) {
+        const pcPubkey = canonicalizeEd25519PublicKey(sibling.pcPubkey, `siblings[${index}].pcPubkey`);
+        if (pcPubkey === selfPubkey)
+            continue;
+        const pcLabel = validateAlias(sibling.pcLabel, `siblings[${index}].pcLabel`);
+        const legacyPcLabel = validateLegacyPcLabel(sibling.legacyPcLabel, `siblings[${index}].legacyPcLabel`);
+        if (pcLabel === selfLabel || siblingAliases.has(pcLabel)) {
+            throw new Error("mesh: duplicate sibling routing alias");
+        }
+        if (siblingKeys.has(pcPubkey)) {
+            throw new Error("mesh: duplicate sibling public key");
+        }
+        siblingAliases.add(pcLabel);
+        siblingKeys.add(pcPubkey);
+        normalizedSiblings.push(Object.freeze({ pcLabel, pcPubkey, legacyPcLabel }));
+    }
+    normalizedSiblings.sort((left, right) => compareAscii(left.pcPubkey, right.pcPubkey));
+    return Object.freeze({ self, siblings: Object.freeze(normalizedSiblings) });
+}
+async function discoverStandaloneTopology(opts) {
+    const silent = { warn: (_message) => { } };
+    try {
+        const owners = await listOwnerPubkeys();
+        return await discoverTopology({
+            client: new MeshClient(opts.relayUrl, {
+                ...(opts.meshRequestTimeoutMs !== undefined
+                    ? { requestTimeoutMs: opts.meshRequestTimeoutMs }
+                    : {}),
+            }),
+            ownerEpks: owners,
+            myPubkey: opts.keypair.publicKey,
+            log: silent,
+        });
+    }
+    catch {
+        return buildTopologySnapshot(opts.keypair.publicKey, []);
+    }
+}
+export async function attachCrossPcBridge(opts) {
+    const expectedSelfPubkey = encodeEd25519PublicKey(opts.keypair.publicKey, "relay public key");
+    const topology = ownTopology(opts.topology ?? await discoverStandaloneTopology(opts), expectedSelfPubkey);
+    // No Relay listeners exist until all standalone discovery has completed.
+    const piForward = new PiForwardClient(opts.relay);
+    let brokerRemote;
+    try {
+        brokerRemote = new BrokerRemote({
+            broker: opts.broker,
+            pi: piForward,
+            topology,
+            activateOnConstruct: false,
+            log: opts.log ?? (() => { }),
+        });
+    }
+    catch (error) {
+        piForward.detach();
+        throw error;
+    }
+    let state = "dormant";
+    return {
+        brokerRemote,
+        piForward,
+        topology,
+        activate() {
+            if (state !== "dormant")
+                return;
+            try {
+                brokerRemote.activate();
+                state = "active";
+            }
+            catch (error) {
+                state = "detached";
+                try {
+                    brokerRemote.detach();
+                }
+                finally {
+                    piForward.detach();
+                }
+                throw error;
+            }
+        },
+        detach() {
+            if (state === "detached")
+                return;
+            state = "detached";
+            try {
+                brokerRemote.detach();
+            }
+            finally {
+                piForward.detach();
+            }
+        },
+    };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/session/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../src/session/bridge.ts"],"names":[],"mappings":"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"}

package/dist/session/broker.d.ts

@@ -0,0 +1,189 @@
+import type { Server } from "node:net";
+import { type Envelope } from "./envelope.js";
+/**
+ * Structured view of one mesh peer (plan/38). The `address` is the canonical
+ * routing key; the other fields let a client group/label peers WITHOUT parsing
+ * the address string. `pc` is undefined for local peers (filled cross-PC in
+ * Fase 2). Returned by `list_peers` as `peers_detailed`.
+ */
+export interface PeerInfo {
+    /** Cross-PC label; undefined for a local peer. */
+    pc?: string;
+    /** Working directory (realpath). Empty string for a legacy peer (no cwd). */
+    cwd: string;
+    /** Clean leaf name (carries a `#N` only on a same-(cwd,name) collision). */
+    name: string;
+    /** Canonical address — the broker's Map key and the `to`/`from` on the wire. */
+    address: string;
+}
+/**
+ * THE sole encoder of a peer address (plan/38): `[<pc>:]<cwd>@<nome>`.
+ *
+ * - `cwd` present → `<cwd>@<nome>` (the `@` separates name from path so a `/`
+ *   in the path never confuses lookup, which is exact-match anyway).
+ * - `cwd` empty (legacy peer that sent no cwd) → `address == name`, preserving
+ *   pre-plan/38 behavior so a mixed mesh keeps routing.
+ * - `pc` present (cross-PC, Fase 2) → prefixed `<pc>:`.
+ *
+ * Does NOT sanitize — callers sanitize the `name` once (see `sanitizeMeshName`)
+ * before composing, so an already-appended `#N` collision suffix survives.
+ * Everyone else ECHOES `peer.address` verbatim; only the broker composes.
+ */
+export declare function composeAddress(parts: {
+    pc?: string;
+    cwd: string;
+    name: string;
+}): string;
+/**
+ * Sanitize a requested mesh name to a safe leaf while PRESERVING a trailing
+ * `#N` collision suffix (which the cwd-lock or a prior assignment may have
+ * added — `sanitizeSegment` alone would mangle `#`→`-`). The base is run through
+ * `sanitizeSegment` (af66d04); an unusable base (empty / reserved keyword) falls
+ * back to `"agent"`.
+ */
+export declare function sanitizeMeshName(raw: string): string;
+/**
+ * Broker hosted by the session leader. Accepts UDS connections, maintains a
+ * `name → connection` map, routes envelopes per the `to` field, and appends
+ * each routed message to an `audit.jsonl` log.
+ *
+ * Auto-suffix on name collision: when a peer registers a name already taken,
+ * the broker assigns `<name>#N` and returns it in the register ack.
+ *
+ * ## ACK protocol (plan/25 Wave 0; reliable delivery per plan/34)
+ *
+ * For **unicast non-broker** envelopes the broker synchronously emits an ACK
+ * envelope back to the sender once it has delivered:
+ *
+ *   - target online → deliver envelope, ACK `received`
+ *   - no such peer  → silent drop (sender times out)
+ *
+ * plan/34 removed the busy-drop: a message that arrives while the target is
+ * mid-turn is **always delivered**, never dropped. The Pi harness
+ * (`sendMessage(triggerTurn:true)`) enqueues mid-turn messages and processes
+ * them in the upcoming turn, so the broker needs no busy gate or mailbox.
+ * Consequently `busy` is no longer a possible ACK status for unicast new
+ * work — the sender always gets `received`. (Turn-lifecycle / working
+ * indicators live in `index.ts` via room_meta over the relay, not here.)
+ *
+ * Broadcast/multicast/broker-addressed envelopes are not ACKed (no single
+ * authoritative recipient or no semantic match). The audit log carries the
+ * ACK status (`received | denied | none`) per envelope.
+ */
+export interface BrokerOptions {
+    server: Server;
+    auditPath?: string;
+    /** Optional callback invoked after each successful route (testing/observability). */
+    onRouted?: (env: Envelope, deliveredTo: string[]) => void;
+}
+/**
+ * Hook the broker calls before doing local routing, so cross-PC prefixes
+ * (`<pc_label>:<peer_name>`) can be handed off to a remote forwarder
+ * without baking transport knowledge into the broker. Wave C (plan/25)
+ * wires `broker_remote.ts` here.
+ */
+export interface RemoteRouter {
+    /**
+     * Try to claim responsibility for routing this envelope cross-PC.
+     * Returns true if claimed (broker MUST NOT also deliver locally). Returns
+     * false if the envelope should fall through to local routing — e.g., the
+     * prefix matches the local `pc_label`, the prefix is not a known remote
+     * label (backward-compat for local names containing `:`), or there's no
+     * prefix at all.
+     */
+    tryRouteOutbound(env: Envelope): boolean;
+    /** Aggregated remote peer addresses (`<pc_label>:<cwd>@<nome>`) for the
+     *  `list_peers` reply's `peers` (string) field. Empty when nothing known. */
+    listRemotePeers(): string[];
+    /** Structured remote roster (plan/38 Fase 2): one `PeerInfo` per cross-PC
+     *  peer with `pc` filled (the sibling label), `cwd`/`name` from the sibling's
+     *  inventory, and `address` prefixed `<pc>:<cwd>@<nome>`. Powers the
+     *  `peers_detailed` half of `list_peers` so clients group by `pc`/`cwd`
+     *  without parsing. Empty when nothing known. */
+    listRemotePeerInfos(): PeerInfo[];
+}
+export interface ConditionalRemoteRouterHost {
+    clearRemoteRouter(expected: RemoteRouter): void;
+}
+/** Local outcome of a cross-PC envelope injection. broker_remote uses this
+ *  to construct the ACK envelope it sends back via the relay. plan/34: `busy`
+ *  is gone — injection always delivers when the peer exists. */
+export type RemoteInjectStatus = "received" | "denied";
+export declare class Broker {
+    private readonly peers;
+    private readonly auditPath?;
+    private readonly onRouted?;
+    private readonly server;
+    /** Plan/25 Wave C: optional handoff for cross-PC routing. Null = local only. */
+    private remoteRouter;
+    constructor(opts: BrokerOptions);
+    /** Attach (or detach with null) a cross-PC router. Idempotent. */
+    setRemoteRouter(router: RemoteRouter | null): void;
+    /** Clear only when the caller still owns the active router slot. */
+    clearRemoteRouter(expected: RemoteRouter): void;
+    /**
+     * Plan/25 Wave C entry point: deliver an envelope that arrived from a
+     * remote PC (via relay forward) into the local UDS mesh. Skips the
+     * `force from = conn.name` rule (that defense is anti-spoof for local
+     * peers; cross-PC has its own defense via the relay's verified `from_pc`).
+     *
+     * Returns the ACK status so the caller (broker_remote) can pack and
+     * forward an ACK envelope back across the relay:
+     *   - `received` — target exists, envelope delivered (plan/34: always
+     *     delivered when the peer is online — the Pi harness enqueues mid-turn
+     *     messages, so there is no busy-drop)
+     *   - `denied` — no such local peer (or write failed) — caller maps to
+     *     transport_error or denied ACK as it sees fit
+     */
+    injectFromRemote(env: Envelope): RemoteInjectStatus;
+    /** Peers currently registered. Snapshot, safe to read. */
+    peerNames(): string[];
+    close(): Promise<void>;
+    private _handleConnection;
+    private _onData;
+    private _handleLine;
+    private _handleRegister;
+    /**
+     * Answer a read-only `list_peers` request from an UNREGISTERED connection
+     * (the `remote-pi peers` CLI probe). Returns true when the line was such a
+     * probe — the reply is written and the connection stays unregistered: no
+     * name assigned, no `peer_joined`/`peer_left` broadcast, no sibling push, so
+     * querying the roster from the shell never perturbs the mesh. Returns false
+     * (not a probe) so the caller falls through to the register handshake.
+     */
+    private _tryObserverProbe;
+    /** Local UDS peer names plus cross-PC `<pc>:<peer>` entries from the remote
+     *  router (empty when no bridge). Shared by the registered `list_peers`
+     *  handler and the unregistered observer probe. */
+    private _allPeerNames;
+    /** Structured roster of LOCAL UDS peers (plan/38): one `PeerInfo` each, no
+     *  `pc` (they're on this machine). Public so the cross-PC router
+     *  (`broker_remote`) can read the authoritative local inventory directly to
+     *  push to siblings — no `list_peers` round-trip, no stale cache. */
+    localPeerInfos(): PeerInfo[];
+    /** Structured roster (plan/38): local peers (no `pc`) + cross-PC peers with
+     *  `pc`/`cwd`/`name` filled by the remote router (Fase 2). */
+    private _allPeerInfos;
+    /**
+     * Resolve a free `(name, address)` for a register, keyed by **(cwd, name)**
+     * (plan/38): the collision check is on the composed ADDRESS, so a name only
+     * collides with another peer in the SAME cwd. `#N` is appended to the name
+     * (matching the cwd-lock's suffix scheme) until the address is free; for a
+     * legacy peer (cwd "") the address is the name, preserving global-name `#N`.
+     */
+    private _identityForRegister;
+    private _dropPeerAt;
+    private _onClose;
+    private _route;
+    private _resolveTargets;
+    /**
+     * Writes an ACK envelope to the original sender's socket. Synchronous —
+     * the caller is inside `_route` and must keep busy-check/busy-set atomic.
+     * Broker → sender: `from="broker"`, `to=env.from`, `re=env.id`,
+     * `body={type:"ack", status, target}`.
+     */
+    private _sendAckToSender;
+    private _handleBrokerMessage;
+    private _broadcastSystem;
+    private _appendAudit;
+}