@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/bus/broker/client.ts

@@ -2,7 +2,7 @@
  * Broker client — the child-side half of the relay (spec B3/B6): connects to the
  * session-scoped endpoint (`paths.ts`), performs the `register`/`registered` handshake,
  * and exposes the same shape a local `contact_supervisor`/`contact_peer` binding needs —
- * `send` (fire-and-forget), `ask` (a blocking `send{expectsReply}` correlated to a
+ * `send` (one-way with a bounded host-admission receipt), `ask` (a blocking `send{expectsReply}` correlated to a
  * `replied{askId}`, 10-minute cap, mirrors `bus.ask`, and sends `cancel{msgId}` when
  * aborted), `reply` (answers a host-issued
  * blocking `deliver`), `list` (the engine-scoped peer roster, B7), and `onDeliver`/`onSteer`
@@ -14,19 +14,22 @@
  * exponential backoff (250ms–5s) on the INITIAL connect only (comtac's presence tracking,
  * roster cache, and endless reconnect-after-disconnect "storm" are dropped — YAGNI here,
  * see spec B6/Task 4 brief). An unexpected disconnect (host died
- * mid-run) is NOT auto-reconnected: sends silently go nowhere, while in-flight asks/lists
- * reject promptly and clean up their timers — the child keeps executing, mute, never crashing.
+ * mid-run) is NOT auto-reconnected: sends resolve false, while in-flight asks/lists
+ * reject promptly and clean up their timers. Authenticated result readers are stricter:
+ * one connect attempt, bounded handshake/reads, closed failure replies, never mute success.
  *
  * Pure over an injected socket factory (`net`), mirroring `host.ts`'s `net` param — same
  * transport-injection seam, opposite side of the same fake in tests.
  */
 
-import { randomUUID } from "node:crypto";
+import { randomUUID, timingSafeEqual } from "node:crypto";
 import nodeNet from "node:net";
 import type net from "node:net";
 
 import { createFrameReader, encodeFrame } from "./framing.ts";
-import { type Frame, isFrame } from "./messages.ts";
+import { type Frame, isFrame, isReaderToken } from "./messages.ts";
+import { isReadRequest, isReadReplyFor, readFailure, RESULT_READ_MAX_PENDING, RESULT_READ_TIMEOUT_MS,
+	type ReadReply, type ResultReadRequest } from "../result-reader.ts";
 import type { MsgKind } from "../inproc.ts";
 
 export interface DeliverEvent {
@@ -39,10 +42,13 @@ export interface DeliverEvent {
 }
 
 export interface BrokerClient {
-	/** Connect (capped backoff) and complete the register handshake. */
+	/** Register once. Ordinary comms back off on initial connect; reader grants never retry. */
 	register(): Promise<void>;
-	/** Fire-and-forget; a dead connection silently drops it (spec: "sends report undelivered"). */
-	send(to: string, kind: MsgKind, text: string): void;
+	/** Authenticated bounded read. Failures are fixed closed replies; never a mute success. */
+	read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply>;
+	/** One-way message; true only after host bus admission, never a recipient answer.
+	 * Missing receipt, cancellation, saturation or disconnect resolve false without replay. */
+	send(to: string, kind: MsgKind, text: string, signal?: AbortSignal): Promise<boolean>;
 	/** Blocking request; resolves on a matching `replied`, rejects on `signal` abort or the
 	 *  10-minute cap (mirrors `bus.ask`'s default). */
 	ask(to: string, kind: MsgKind, text: string, signal?: AbortSignal): Promise<string>;
@@ -63,6 +69,8 @@ export interface MakeBrokerClientDeps {
 	label?: string;
 	group?: string;
 	peers?: boolean;
+	/** Private, one-shot parent grant. Never log this or pass it to a model. */
+	readerToken?: string;
 	/** Injected transport (tests use a paired in-memory fake); defaults to real `node:net`. */
 	net?: typeof import("node:net");
 }
@@ -74,13 +82,8 @@ const ASK_TIMEOUT_MS = 600_000;
 // A roster lookup is one local socket/pipe round-trip, unlike a blocking supervisor ask. Do not
 // let a half-open broker pin `contact_peer list/send` until the child idle watchdog fires.
 const LIST_TIMEOUT_MS = 10_000;
-
-function delay(ms: number): Promise<void> {
-	return new Promise((resolve) => {
-		const t = setTimeout(resolve, ms);
-		t.unref?.();
-	});
-}
+export const SEND_TIMEOUT_MS = 10_000;
+export const MAX_PENDING_SENDS = 64;
 
 export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	const netImpl = deps.net ?? nodeNet;
@@ -88,6 +91,12 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	let socket: net.Socket | undefined;
 	let closed = false;
 	let disconnected = false;
+	let registerStarted = false;
+	let registered = false;
+	let cancelConnect: (() => void) | undefined;
+	let cancelBackoff: (() => void) | undefined;
+	const pendingReads = new Map<string, { request: ResultReadRequest; resolve: (result: ReadReply) => void }>();
+	const pendingSends = new Map<string, (delivered: boolean) => void>();
 	let registerSettle: { resolve: () => void; reject: (err: Error) => void } | undefined;
 
 	const deliverListeners = new Set<(evt: DeliverEvent) => void>();
@@ -96,9 +105,7 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	const pendingAsks = new Map<string, { resolve: (text: string) => void; reject: (err: Error) => void }>();
 	const pendingLists = new Map<string, { resolve: (peers: Array<{ handle: string; label: string }>) => void; reject: (err: Error) => void }>();
 
-	/** Best-effort write: a frame sent while disconnected is silently dropped — matches
-	 *  the design's "sends report undelivered" (no throw the caller could even act on,
-	 *  `send`/`reply` are `void`). */
+	/** Best-effort control frame write. Confirmed sends use their own guarded write and receipt. */
 	function write(frame: Frame): void {
 		if (!socket) return;
 		try {
@@ -121,20 +128,35 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 
 	function handleFrame(frame: Frame): void {
 		switch (frame.t) {
+			case "sent":
+				pendingSends.get(frame.msgId)?.(frame.delivered);
+				return;
 			case "registered":
-				registerSettle?.resolve();
+				if (!registerSettle) return;
+				if (frame.handle !== deps.handle || (deps.readerToken !== undefined && (!frame.readerToken
+					|| !timingSafeEqual(Buffer.from(deps.readerToken, "hex"), Buffer.from(frame.readerToken, "hex"))))) {
+					failReaderProtocol();
+					return;
+				}
+				registered = true;
+				registerSettle.resolve();
 				registerSettle = undefined;
 				return;
+			case "result_read_reply": {
+				const pending = pendingReads.get(frame.reqId);
+				if (pending) pending.resolve(isReadReplyFor(frame.result, pending.request) ? frame.result : readFailure("protocol"));
+				return;
+			}
 			case "error":
 				// A correlated error belongs to one request on this connection. Do not let an
 				// unknown/stale correlation id affect the register handshake or another ask.
 				if (frame.msgId !== undefined) {
+					pendingSends.get(frame.msgId)?.(false);
 					pendingAsks.get(frame.msgId)?.reject(new Error(frame.reason));
 					return;
 				}
-				// A bare error is reserved for the register handshake. Older hosts emit this
-				// shape, so keep accepting it for protocol compatibility.
-				registerSettle?.reject(new Error(frame.reason));
+				// A bare error belongs to the register handshake, not an outstanding read.
+				registerSettle?.reject(new Error(deps.readerToken !== undefined ? "Result reader authentication failed." : frame.reason));
 				registerSettle = undefined;
 				return;
 			case "deliver": {
@@ -167,25 +189,43 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		}
 	}
 
+	function failReaderProtocol(): void {
+		registerSettle?.reject(new Error("Result reader protocol failure."));
+		registerSettle = undefined;
+		for (const pending of pendingReads.values()) pending.resolve(readFailure("protocol"));
+		socket?.destroy();
+	}
+
 	function connectOnce(): Promise<net.Socket> {
 		return new Promise((resolve, reject) => {
 			const s = netImpl.connect(deps.endpoint);
 			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const finish = (): void => { clearTimeout(timer); cancelConnect = undefined; };
 			const onConnect = (): void => {
 				if (settled) return;
 				settled = true;
+				finish();
 				s.removeListener("error", onError);
 				resolve(s);
 			};
 			const onError = (err: Error): void => {
 				if (settled) return;
 				settled = true;
+				finish();
 				s.removeListener("connect", onConnect);
 				s.destroy();
 				reject(err);
 			};
 			s.once("connect", onConnect);
 			s.once("error", onError);
+			// Permanent sink also covers cancellation before the eventual connect event.
+			s.on("error", () => {});
+			cancelConnect = () => onError(new Error("broker client closed"));
+			if (deps.readerToken !== undefined) {
+				timer = setTimeout(() => onError(new Error("Result reader connection deadline exceeded.")), RESULT_READ_TIMEOUT_MS);
+				timer.unref?.();
+			}
 		});
 	}
 
@@ -198,9 +238,21 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 			try {
 				return await connectOnce();
 			} catch (err) {
+				// Local cancellation is terminal. Waiting on an unref'ed retry timer here
+				// can leave register() pending after the process has no live handles.
+				if (closed) throw new Error("broker client closed");
 				lastErr = err;
 				if (attempt < CONNECT_MAX_ATTEMPTS - 1) {
-					await delay(Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS));
+					await new Promise<void>((resolve) => {
+						const finish = (): void => {
+							clearTimeout(timer);
+							cancelBackoff = undefined;
+							resolve();
+						};
+						const timer = setTimeout(finish, Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS));
+						timer.unref?.();
+						cancelBackoff = finish;
+					});
 				}
 			}
 		}
@@ -208,6 +260,8 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	}
 
 	function rejectAllPending(reason: string): void {
+		for (const settle of pendingSends.values()) settle(false);
+		for (const p of pendingReads.values()) p.resolve(readFailure("unavailable"));
 		for (const p of pendingAsks.values()) p.reject(new Error(reason));
 		pendingAsks.clear();
 		for (const p of pendingLists.values()) p.reject(new Error(reason));
@@ -215,7 +269,11 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	}
 
 	async function register(): Promise<void> {
-		const s = await connectWithBackoff();
+		if (registerStarted || closed) throw new Error("broker register is one-shot or closed");
+		registerStarted = true;
+		if (deps.readerToken !== undefined && !isReaderToken(deps.readerToken)) throw new Error("Result reader protocol failure.");
+		// Ordinary comms retain initial-connect backoff. A result grant never reconnects/replays.
+		const s = await (deps.readerToken !== undefined ? connectOnce() : connectWithBackoff());
 		if (closed) {
 			s.destroy();
 			throw new Error("broker client closed");
@@ -226,16 +284,19 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 			createFrameReader(
 				(raw) => {
 					if (isFrame(raw)) handleFrame(raw);
+					else if (deps.readerToken !== undefined) failReaderProtocol();
 				},
-				() => s.destroy(),
+				() => { if (deps.readerToken !== undefined) failReaderProtocol(); else s.destroy(); },
 			),
 		);
 		s.on("error", () => {
+			if (deps.readerToken !== undefined) s.destroy();
 			/* The close event rejects in-flight requests; this listener only prevents an
 			 * unhandled socket error from taking down the child. */
 		});
 		s.once("close", () => {
-			socket = undefined;
+			if (socket === s) socket = undefined;
+			registered = false;
 			// A peer-initiated drop (host teardown/crash) between connect and the handshake
 			// reply would otherwise leave register() pending for the child's whole life.
 			registerSettle?.reject(new Error("connection closed during register"));
@@ -248,10 +309,20 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		});
 
 		return new Promise<void>((resolve, reject) => {
-			registerSettle = { resolve, reject };
+			const timer = deps.readerToken !== undefined ? setTimeout(() => {
+				registerSettle?.reject(new Error("Result reader handshake deadline exceeded."));
+				registerSettle = undefined;
+				s.destroy();
+			}, RESULT_READ_TIMEOUT_MS) : undefined;
+			timer?.unref?.();
+			registerSettle = {
+				resolve: () => { clearTimeout(timer); resolve(); },
+				reject: (error) => { clearTimeout(timer); reject(error); },
+			};
 			write({
 				t: "register",
 				handle: deps.handle,
+				...(deps.readerToken !== undefined ? { readerToken: deps.readerToken } : {}),
 				...(deps.label !== undefined ? { label: deps.label } : {}),
 				...(deps.group !== undefined ? { group: deps.group } : {}),
 				...(deps.peers !== undefined ? { peers: deps.peers } : {}),
@@ -259,8 +330,55 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		});
 	}
 
-	function send(to: string, kind: MsgKind, text: string): void {
-		write({ t: "send", to, kind, text, msgId: randomUUID(), expectsReply: false });
+	function read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply> {
+		if (signal?.aborted) return Promise.resolve(readFailure("cancelled"));
+		if (!isReadRequest(request)) return Promise.resolve(readFailure("invalid"));
+		if (deps.readerToken === undefined) return Promise.resolve(readFailure("denied"));
+		if (closed || disconnected || !registered || !socket) return Promise.resolve(readFailure("unavailable"));
+		if (pendingReads.size >= RESULT_READ_MAX_PENDING) return Promise.resolve(readFailure("busy"));
+		const reqId = randomUUID();
+		// Snapshot caller data so mutation after dispatch cannot alter correlation checks.
+		const snapshot = { ...request };
+		return new Promise((resolve) => {
+			const finish = (result: ReadReply): void => {
+				if (!pendingReads.delete(reqId)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				resolve(result);
+			};
+			const cancel = (result: ReadReply): void => {
+				finish(result);
+				write({ t: "result_read_cancel", reqId });
+			};
+			const onAbort = (): void => cancel(readFailure("cancelled"));
+			const timer = setTimeout(() => cancel(readFailure("timeout")), RESULT_READ_TIMEOUT_MS);
+			timer.unref?.();
+			pendingReads.set(reqId, { request: snapshot, resolve: finish });
+			signal?.addEventListener("abort", onAbort, { once: true });
+			try {
+				socket!.write(encodeFrame({ t: "result_read", reqId, ...snapshot }));
+			} catch { finish(readFailure("unavailable")); socket?.destroy(); }
+		});
+	}
+
+	function send(to: string, kind: MsgKind, text: string, signal?: AbortSignal): Promise<boolean> {
+		if (signal?.aborted || closed || disconnected || !registered || !socket || pendingSends.size >= MAX_PENDING_SENDS) return Promise.resolve(false);
+		const msgId = randomUUID();
+		return new Promise((resolve) => {
+			const finish = (delivered: boolean): void => {
+				if (!pendingSends.delete(msgId)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				resolve(delivered);
+			};
+			const onAbort = (): void => finish(false);
+			const timer = setTimeout(() => finish(false), SEND_TIMEOUT_MS);
+			timer.unref?.();
+			pendingSends.set(msgId, finish);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			try { socket!.write(encodeFrame({ t: "send", to, kind, text, msgId, expectsReply: false })); }
+			catch { finish(false); }
+		});
 	}
 
 	/** Why `ask`/`list` refuse to send right now — distinguishes a disposed client from one that
@@ -357,6 +475,9 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	function close(): void {
 		if (closed) return;
 		closed = true;
+		registered = false;
+		cancelConnect?.();
+		cancelBackoff?.();
 		const s = socket;
 		if (s) {
 			write({ t: "bye" });
@@ -375,5 +496,5 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		rejectAllPending("broker client closed");
 	}
 
-	return { register, send, ask, reply, list, onDeliver, onSteer, onClose, close };
+	return { register, read, send, ask, reply, list, onDeliver, onSteer, onClose, close };
 }

package/src/bus/broker/host.ts

@@ -29,17 +29,23 @@
  */
 
 import { existsSync, unlinkSync } from "node:fs";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import nodeNet from "node:net";
 import type net from "node:net";
 
 import { createFrameReader, encodeFrame } from "./framing.ts";
 import { type Frame, isFrame } from "./messages.ts";
 import type { InProcessBus } from "../inproc.ts";
+import { isReadReplyFor, readFailure, RESULT_READ_MAX_FRAME_BYTES, RESULT_READ_MAX_PENDING,
+	RESULT_READ_MAX_REQUESTS, RESULT_READ_TIMEOUT_MS, type PreparedResultReader, type ReadReply,
+	type ScopedReader } from "../result-reader.ts";
 
 export interface BrokerHost {
 	endpoint: string;
 	close(): Promise<void>;
 	connectedHandles(): string[];
+	/** Parent-only preflight. Reserve before bus/adapter registration or spawning. */
+	prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader>;
 	/** Pushes a `steer` frame directly to a connected handle (spec B4) — the supervisor's own
 	 *  live voice, NOT a bus envelope (it bypasses `bus.send`/the outbound drain entirely, so
 	 *  it can't be mistaken for a peer/child message on the wire). Returns false (a harmless
@@ -158,6 +164,39 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 	const sockets = new Set<net.Socket>();
 	const expected = new Set<string>();
 	const pendingSteer = new Map<string, string[]>();
+	type Grant = { token: Buffer; reader: ScopedReader; active: boolean; bound: boolean; stop?: () => void; revoke: () => void };
+	const grants = new Map<string, Grant>();
+	let closed = false;
+
+	function revokeReader(reader: ScopedReader): void {
+		try { reader.revoke(); } catch { /* cleanup cannot leak callback errors or strand siblings */ }
+	}
+
+	async function prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader> {
+		if (closed || signal?.aborted || !handle || handle.length > 256 || handle === deps.supervisorHandle
+			|| connections.has(handle) || grants.has(handle) || expected.has(handle) || bus.participants().includes(handle)) {
+			revokeReader(reader);
+			throw new Error("Result reader preparation refused.");
+		}
+		const token = randomBytes(32);
+		const grant: Grant = { token, reader, active: true, bound: false, revoke: () => {
+			if (!grant.active) return;
+			grant.active = false;
+			signal?.removeEventListener("abort", grant.revoke);
+			if (grants.get(handle) === grant) {
+				grants.delete(handle);
+				expected.delete(handle);
+				pendingSteer.delete(handle);
+			}
+			token.fill(0);
+			grant.stop?.();
+			revokeReader(reader);
+		} };
+		grants.set(handle, grant);
+		expected.add(handle);
+		signal?.addEventListener("abort", grant.revoke, { once: true });
+		return { token: token.toString("hex"), revoke: grant.revoke, wasBound: () => grant.bound };
+	}
 
 	function flushPendingSteer(handle: string): void {
 		const conn = connections.get(handle);
@@ -207,10 +246,19 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		let handle: string | undefined;
 		let group: string | undefined;
 		const pendingAsks = new Map<string, AbortController>();
+		let ended = false;
+		let boundGrant: Grant | undefined;
+		const seenReads = new Set<string>();
+		const pendingReads = new Map<string, { ac: AbortController; finish: (result?: ReadReply) => void }>();
 
 		const write = (frame: Frame): void => {
 			try {
-				socket.write(encodeFrame(frame));
+				const encoded = encodeFrame(frame);
+				if (frame.t === "result_read_reply" && encoded.length > RESULT_READ_MAX_FRAME_BYTES) {
+					socket.write(encodeFrame({ t: "result_read_reply", reqId: frame.reqId, result: readFailure("protocol") }));
+					return;
+				}
+				socket.write(encoded);
 			} catch {
 				/* peer went away mid-write */
 			}
@@ -220,6 +268,11 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const conn = { write };
 
 		const cleanup = (): void => {
+			if (ended) return;
+			ended = true;
+			for (const pending of pendingReads.values()) { pending.finish(); pending.ac.abort(); }
+			seenReads.clear();
+			boundGrant?.revoke();
 			for (const ac of pendingAsks.values()) ac.abort();
 			pendingAsks.clear();
 			// `bye` releases the handle while `handle` stays set (the socket's own `close`
@@ -233,10 +286,55 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const errorReason = (error: unknown): string => error instanceof Error ? error.message : String(error);
 
 		const dispatch = (frame: Frame): void => {
+			if (ended) return;
 			switch (frame.t) {
+				case "result_read": {
+					const grant = boundGrant;
+					const respond = (result: ReadReply): void => write({ t: "result_read_reply", reqId: frame.reqId, result });
+					if (!handle || connections.get(handle) !== conn || !grant?.active) { respond(readFailure("denied")); return; }
+					if (seenReads.has(frame.reqId)) {
+						const pending = pendingReads.get(frame.reqId);
+						pending?.finish();
+						pending?.ac.abort();
+						respond(readFailure("protocol"));
+						return;
+					}
+					if (seenReads.size >= RESULT_READ_MAX_REQUESTS) { grant.revoke(); return; }
+					seenReads.add(frame.reqId);
+					if (pendingReads.size >= RESULT_READ_MAX_PENDING) { respond(readFailure("busy")); return; }
+					const { t: _t, reqId, ...request } = frame;
+					const ac = new AbortController();
+					const finish = (result?: ReadReply): void => {
+						if (pendingReads.get(reqId)?.ac !== ac) return;
+						pendingReads.delete(reqId);
+						clearTimeout(timer);
+						if (result && !ended && grant.active && handle && connections.get(handle) === conn) respond(result);
+					};
+					const timer = setTimeout(() => { finish(readFailure("timeout")); ac.abort(); }, RESULT_READ_TIMEOUT_MS);
+					timer.unref?.();
+					pendingReads.set(reqId, { ac, finish });
+					void Promise.resolve().then(() => {
+						if (ac.signal.aborted || !grant.active) return readFailure("revoked");
+						return grant.reader.read(request, ac.signal);
+					}).then((result) => {
+						try { finish(isReadReplyFor(result, request) ? result : readFailure("protocol")); }
+						catch { finish(readFailure("protocol")); }
+					}, () => finish(readFailure("unavailable")));
+					return;
+				}
+				case "result_read_cancel": {
+					const pending = pendingReads.get(frame.reqId);
+					pending?.finish(readFailure("cancelled"));
+					pending?.ac.abort();
+					return;
+				}
 				case "register": {
+					const reject = (reason: string): void => {
+						write({ t: "error", reason });
+						if (frame.readerToken !== undefined || grants.has(frame.handle)) socket.destroy();
+					};
 					if (frame.handle === deps.supervisorHandle) {
-						write({ t: "error", reason: "reserved handle" });
+						reject("reserved handle");
 						return;
 					}
 					// Registration is one-shot per socket and exclusive per handle: a
@@ -244,26 +342,38 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 					// would then unregister a handle it no longer owns (or leak the one it
 					// silently abandoned).
 					if (handle) {
-						write({ t: "error", reason: "already registered" });
+						reject("already registered");
 						return;
 					}
 					if (connections.has(frame.handle)) {
-						write({ t: "error", reason: `handle already connected: ${frame.handle}` });
+						reject("handle already connected");
 						return;
 					}
+					const grant = grants.get(frame.handle);
+					// A supplied unknown/expired token never falls through to ordinary registration.
+					if (grant || frame.readerToken !== undefined) {
+						if (!grant?.active || grant.bound || !frame.readerToken
+							|| !timingSafeEqual(grant.token, Buffer.from(frame.readerToken, "hex"))) {
+							reject("result reader authentication failed");
+							return;
+						}
+						grant.bound = true;
+						boundGrant = grant;
+						grant.stop = () => { if (!ended) { cleanup(); socket.destroy(); } };
+					}
 					handle = frame.handle;
 					group = frame.group;
 					bus.register(handle);
 					connections.set(handle, conn);
 					if (frame.peers) peerRegistry.set(handle, { handle, label: frame.label ?? handle, group: frame.group ?? "" });
-					write({ t: "registered", handle });
+					write({ t: "registered", handle, ...(frame.readerToken ? { readerToken: frame.readerToken } : {}) });
 					drain(handle);
 					flushPendingSteer(handle);
 					return;
 				}
 				case "send": {
 					if (!handle) {
-						write({ t: "error", reason: "send before register" });
+						write({ t: "error", reason: "send before register", msgId: frame.msgId });
 						return;
 					}
 					const from = handle;
@@ -285,8 +395,12 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 							forgetAsk(frame.msgId, ac);
 							write({ t: "error", reason: errorReason(error), msgId: frame.msgId });
 						}
-					} else if (!bus.send(from, frame.to, frame.text, frame.kind)) {
-						write({ t: "error", reason: `unknown peer: ${frame.to}` });
+					} else {
+						// Admission is not an answer. Unknown/full inboxes both return false;
+						// never label a full inbox "unknown peer" or a socket write "delivered".
+						let delivered = false;
+						try { delivered = bus.send(from, frame.to, frame.text, frame.kind); } catch { /* no confirmation */ }
+						write({ t: "sent", msgId: frame.msgId, delivered });
 					}
 					return;
 				}
@@ -324,6 +438,8 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const handleFrame = (raw: unknown): void => {
 			if (!isFrame(raw)) {
 				write({ t: "error", reason: "invalid frame" });
+				if (boundGrant || (typeof raw === "object" && raw !== null
+					&& ("readerToken" in raw || ("t" in raw && String(raw.t).startsWith("result_read"))))) socket.destroy();
 				return;
 			}
 			try {
@@ -337,8 +453,9 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 			}
 		};
 
-		socket.on("data", createFrameReader(handleFrame, (e) => {
-			write({ t: "error", reason: e.message });
+		socket.on("data", createFrameReader(handleFrame, () => {
+			// JSON parser diagnostics can contain the private registration token.
+			write({ t: "error", reason: "invalid frame" });
 			socket.destroy();
 		}));
 		socket.on("error", () => socket.destroy());
@@ -350,9 +467,9 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 
 	const server = await bindServer(netImpl, deps.endpoint, handleConnection);
 
-	let closed = false;
 	return {
 		endpoint: deps.endpoint,
+		prepareResultReader,
 		connectedHandles: () => [...connections.keys()],
 		steer(handle: string, text: string): boolean {
 			const conn = connections.get(handle);
@@ -370,12 +487,14 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 			expected.add(handle);
 		},
 		forget(handle: string): void {
+			grants.get(handle)?.revoke();
 			expected.delete(handle);
 			pendingSteer.delete(handle);
 		},
 		async close(): Promise<void> {
 			if (closed) return;
 			closed = true;
+			for (const grant of grants.values()) grant.revoke();
 			unsubBus();
 			expected.clear();
 			pendingSteer.clear();