@aeondave/pi-persona 1.15.2

package/src/bus/broker/host.ts

@@ -0,0 +1,407 @@
+/**
+ * Broker host — the supervisor-side relay (spec B2): listens on the session-scoped
+ * endpoint (`paths.ts`) and RELAYS every connected client's frames into (and out of) the
+ * local `InProcessBus`, so a remote (child-process) participant is indistinguishable from
+ * an in-process one to the rest of pi-persona (intercom, idle notifier, f9, peek, …) —
+ * the "same surface" promise `bus/inproc.ts`'s header makes, kept literally.
+ *
+ * Inbound (client → bus): `register` proxies `bus.register(handle)` (a client claiming
+ * the reserved `supervisorHandle` is rejected — the in-process supervisor never dials in,
+ * so a remote impersonating it would hijack the supervisor's own inbox); `send` becomes
+ * `bus.send`, or — when `expectsReply` — `bus.ask` run ON BEHALF of the remote sender (the
+ * bus mints its own ask id; the host correlates it back to the client's `msgId` via the
+ * settled promise, so an eventual `bus.reply`/local answer produces a `replied` frame);
+ * `cancel` aborts only the ask owned by that same socket; `reply` answers a pending ask via
+ * `bus.reply`; `list` answers a `peers` frame scoped to
+ * the caller's own registered group (B7); `bye`/socket close proxies `bus.unregister`.
+ *
+ * Outbound (bus → client): one `bus.onMessage` subscription drains (`bus.takeWhere`,
+ * mirroring the in-process delivery bridge in `engine/inproc.ts`) any envelope addressed
+ * to a connected remote handle — both kinds, since the host is that handle's ONLY
+ * consumer — and forwards it as a `deliver` frame (a blocking ask included: the remote
+ * side answers with a `reply` frame, resolved via the same `bus.reply` path above).
+ *
+ * Cross-process safety mirrors comtac's `broker/embedded.ts` MINUS its 12-attempt host
+ * election (the supervisor is always the sole host, spec B1): POSIX stale-socket reclaim
+ * before `listen` (unlink only a socket that is provably not connectable), a permanent
+ * `error` sink on every server/socket, `server.unref()` so the host never keeps Pi alive,
+ * idempotent teardown.
+ */
+
+import { existsSync, unlinkSync } from "node:fs";
+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";
+
+export interface BrokerHost {
+	endpoint: string;
+	close(): Promise<void>;
+	connectedHandles(): string[];
+	/** 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
+	 *  no-op, mirrors `InProcessBus.reply`'s unknown-id return) when the handle is not
+	 *  currently connected AND was never `expect()`ed — e.g. a typo, or already forgotten.
+	 *  A handle `expect()`ed during spawn-before-connect buffers the steer and still returns
+	 *  true; the buffer flushes when the child registers. */
+	steer(handle: string, text: string): boolean;
+	/** Mark `handle` as a child that is about to connect (adapter pre-register). A steer
+	 *  to an expected-but-not-yet-connected handle is buffered rather than reported as lost. */
+	expect(handle: string): void;
+	/** Drop expectation + any buffered steers (adapter unregister / spawn failure). */
+	forget(handle: string): void;
+}
+
+type PeerEntry = { handle: string; label: string };
+
+export interface StartBrokerHostDeps {
+	bus: InProcessBus;
+	/** Reserved — `register{handle: supervisorHandle}` from a client is rejected. */
+	supervisorHandle: string;
+	endpoint: string;
+	/** Injected transport (tests use a paired in-memory fake); defaults to real `node:net`. */
+	net?: typeof import("node:net");
+	/** Answers a `list` frame; default reads the host's own `peers:true` registrations. */
+	listPeersFor?: (group: string, self: string) => PeerEntry[];
+}
+
+const STALE_PROBE_TIMEOUT_MS = 1000;
+
+/** Probe a POSIX socket path: is something actually listening there? */
+function isConnectable(netImpl: typeof import("node:net"), endpoint: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = netImpl.connect(endpoint);
+		const finish = (ok: boolean): void => {
+			clearTimeout(timer);
+			socket.removeListener("connect", onConnect);
+			socket.removeListener("error", onError);
+			socket.destroy();
+			resolve(ok);
+		};
+		const onConnect = (): void => finish(true);
+		const onError = (): void => finish(false);
+		socket.once("connect", onConnect);
+		socket.once("error", onError);
+		const timer = setTimeout(() => finish(false), STALE_PROBE_TIMEOUT_MS);
+	});
+}
+
+type ListenAttempt = { server: net.Server } | { code: string };
+
+/** One bind attempt on a FRESH server (a server that failed to listen is not reused —
+ *  mirrors comtac's `listenOnce`). Wires the connection handler before `listen()` so no
+ *  connection can race the handler being attached. On success: permanent error sink + unref. */
+function attemptListen(netImpl: typeof import("node:net"), endpoint: string, onConnection: (socket: net.Socket) => void): Promise<ListenAttempt> {
+	return new Promise((resolve) => {
+		const server = netImpl.createServer();
+		server.on("connection", onConnection);
+		const onError = (err: NodeJS.ErrnoException): void => {
+			server.removeListener("listening", onListening);
+			try {
+				server.close();
+			} catch {
+				/* ignore */
+			}
+			resolve({ code: err.code ?? "EUNKNOWN" });
+		};
+		const onListening = (): void => {
+			server.removeListener("error", onError);
+			server.on("error", () => {
+				/* permanent sink: a late server error must never crash the host */
+			});
+			server.unref();
+			resolve({ server });
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		try {
+			server.listen(endpoint);
+		} catch (err) {
+			resolve({ code: (err as NodeJS.ErrnoException).code ?? "EUNKNOWN" });
+		}
+	});
+}
+
+/** Bind `endpoint`, reclaiming a stale POSIX socket file once (comtac `embedded.ts:103-114`,
+ *  minus the host-election loop — the supervisor is the sole host). */
+async function bindServer(netImpl: typeof import("node:net"), endpoint: string, onConnection: (socket: net.Socket) => void): Promise<net.Server> {
+	let attempt = await attemptListen(netImpl, endpoint, onConnection);
+	if (
+		!("server" in attempt) &&
+		attempt.code === "EADDRINUSE" &&
+		process.platform !== "win32" &&
+		existsSync(endpoint) &&
+		!(await isConnectable(netImpl, endpoint))
+	) {
+		try {
+			unlinkSync(endpoint);
+		} catch {
+			/* another session may have reaped it first */
+		}
+		attempt = await attemptListen(netImpl, endpoint, onConnection);
+	}
+	if (!("server" in attempt)) {
+		throw new Error(`broker host: failed to listen on ${endpoint} (${attempt.code})`);
+	}
+	return attempt.server;
+}
+
+export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<BrokerHost> {
+	const netImpl = deps.net ?? nodeNet;
+	const bus = deps.bus;
+
+	const connections = new Map<string, { write: (frame: Frame) => void }>();
+	const peerRegistry = new Map<string, { handle: string; label: string; group: string }>();
+	const sockets = new Set<net.Socket>();
+	const expected = new Set<string>();
+	const pendingSteer = new Map<string, string[]>();
+
+	function flushPendingSteer(handle: string): void {
+		const conn = connections.get(handle);
+		const queued = pendingSteer.get(handle);
+		if (!conn || !queued) return;
+		pendingSteer.delete(handle);
+		for (const text of queued) conn.write({ t: "steer", text });
+	}
+
+	function unregisterConnection(handle: string): void {
+		if (!connections.delete(handle)) return;
+		peerRegistry.delete(handle);
+		bus.unregister(handle);
+	}
+
+	function defaultPeersFor(group: string, self: string): PeerEntry[] {
+		return [...peerRegistry.values()]
+			.filter((p) => p.group === group && p.handle !== self)
+			.map((p) => ({ handle: p.handle, label: p.label }));
+	}
+
+	/** Forward every queued envelope addressed to `handle` as a `deliver` frame — both
+	 *  kinds, blocking ask included (the host is this handle's only consumer). */
+	function drain(handle: string): void {
+		const conn = connections.get(handle);
+		if (!conn) return;
+		for (const env of bus.takeWhere(handle, () => true)) {
+			const fromLabel = peerRegistry.get(env.from)?.label;
+			conn.write({
+				t: "deliver",
+				from: env.from,
+				kind: env.kind,
+				text: env.text,
+				msgId: env.id,
+				expectsReply: env.expectsReply,
+				...(fromLabel ? { fromLabel } : {}),
+			});
+		}
+	}
+
+	const unsubBus = bus.onMessage((env) => {
+		if (connections.has(env.to)) drain(env.to);
+	});
+
+	function handleConnection(socket: net.Socket): void {
+		sockets.add(socket);
+		let handle: string | undefined;
+		let group: string | undefined;
+		const pendingAsks = new Map<string, AbortController>();
+
+		const write = (frame: Frame): void => {
+			try {
+				socket.write(encodeFrame(frame));
+			} catch {
+				/* peer went away mid-write */
+			}
+		};
+		/** This connection's identity in `connections` — compared on cleanup so a socket only
+		 *  ever tears down a registration it still OWNS. */
+		const conn = { write };
+
+		const cleanup = (): void => {
+			for (const ac of pendingAsks.values()) ac.abort();
+			pendingAsks.clear();
+			// `bye` releases the handle while `handle` stays set (the socket's own `close`
+			// runs cleanup again, asynchronously); by then another connection may legitimately
+			// have claimed the freed handle, and unregistering blind would kill ITS live entry.
+			if (handle && connections.get(handle) === conn) unregisterConnection(handle);
+		};
+		const forgetAsk = (msgId: string, ac: AbortController): void => {
+			if (pendingAsks.get(msgId) === ac) pendingAsks.delete(msgId);
+		};
+		const errorReason = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+		const dispatch = (frame: Frame): void => {
+			switch (frame.t) {
+				case "register": {
+					if (frame.handle === deps.supervisorHandle) {
+						write({ t: "error", reason: "reserved handle" });
+						return;
+					}
+					// Registration is one-shot per socket and exclusive per handle: a
+					// second claim would overwrite the live entry, and this socket's close
+					// would then unregister a handle it no longer owns (or leak the one it
+					// silently abandoned).
+					if (handle) {
+						write({ t: "error", reason: "already registered" });
+						return;
+					}
+					if (connections.has(frame.handle)) {
+						write({ t: "error", reason: `handle already connected: ${frame.handle}` });
+						return;
+					}
+					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 });
+					drain(handle);
+					flushPendingSteer(handle);
+					return;
+				}
+				case "send": {
+					if (!handle) {
+						write({ t: "error", reason: "send before register" });
+						return;
+					}
+					const from = handle;
+					if (frame.expectsReply) {
+						const ac = new AbortController();
+						pendingAsks.set(frame.msgId, ac);
+						try {
+							bus.ask(from, frame.to, frame.text, { kind: frame.kind, signal: ac.signal }).then(
+								(text) => {
+									forgetAsk(frame.msgId, ac);
+									write({ t: "replied", askId: frame.msgId, text });
+								},
+								(err: unknown) => {
+									forgetAsk(frame.msgId, ac);
+									write({ t: "error", reason: errorReason(err), msgId: frame.msgId });
+								},
+							);
+						} catch (error) {
+							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}` });
+					}
+					return;
+				}
+				case "cancel": {
+					if (!handle) {
+						write({ t: "error", reason: "cancel before register", msgId: frame.msgId });
+						return;
+					}
+					// The map is per socket/registered participant. A child can only cancel an
+					// ask that this same connection originated; an id from another peer is ignored.
+					pendingAsks.get(frame.msgId)?.abort();
+					return;
+				}
+				case "reply": {
+					bus.reply(frame.askId, frame.text);
+					return;
+				}
+				case "list": {
+					const self = handle ?? "";
+					const g = group ?? "";
+					const peers = deps.listPeersFor ? deps.listPeersFor(g, self) : defaultPeersFor(g, self);
+					write({ t: "peers", reqId: frame.reqId, peers });
+					return;
+				}
+				case "bye": {
+					cleanup();
+					socket.end();
+					return;
+				}
+				default:
+					return; // host→client-only frame types received from a client are ignored
+			}
+		};
+
+		const handleFrame = (raw: unknown): void => {
+			if (!isFrame(raw)) {
+				write({ t: "error", reason: "invalid frame" });
+				return;
+			}
+			try {
+				dispatch(raw);
+			} catch (e) {
+				write({
+					t: "error",
+					reason: e instanceof Error ? e.message : String(e),
+					...(raw.t === "send" && raw.expectsReply ? { msgId: raw.msgId } : {}),
+				});
+			}
+		};
+
+		socket.on("data", createFrameReader(handleFrame, (e) => {
+			write({ t: "error", reason: e.message });
+			socket.destroy();
+		}));
+		socket.on("error", () => socket.destroy());
+		socket.once("close", () => {
+			sockets.delete(socket);
+			cleanup();
+		});
+	}
+
+	const server = await bindServer(netImpl, deps.endpoint, handleConnection);
+
+	let closed = false;
+	return {
+		endpoint: deps.endpoint,
+		connectedHandles: () => [...connections.keys()],
+		steer(handle: string, text: string): boolean {
+			const conn = connections.get(handle);
+			if (conn) {
+				conn.write({ t: "steer", text });
+				return true;
+			}
+			if (!expected.has(handle) || !text.trim()) return false;
+			const queued = pendingSteer.get(handle) ?? [];
+			queued.push(text);
+			pendingSteer.set(handle, queued);
+			return true;
+		},
+		expect(handle: string): void {
+			expected.add(handle);
+		},
+		forget(handle: string): void {
+			expected.delete(handle);
+			pendingSteer.delete(handle);
+		},
+		async close(): Promise<void> {
+			if (closed) return;
+			closed = true;
+			unsubBus();
+			expected.clear();
+			pendingSteer.clear();
+			for (const h of [...connections.keys()]) unregisterConnection(h);
+			for (const s of [...sockets]) {
+				try {
+					s.destroy();
+				} catch {
+					/* ignore */
+				}
+			}
+			sockets.clear();
+			await new Promise<void>((resolve) => {
+				try {
+					server.close(() => resolve());
+				} catch {
+					resolve();
+				}
+			});
+			if (process.platform !== "win32") {
+				try {
+					unlinkSync(deps.endpoint);
+				} catch {
+					/* already gone, or this was a fake/in-memory endpoint */
+				}
+			}
+		},
+	};
+}

package/src/bus/broker/messages.ts

@@ -0,0 +1,87 @@
+/**
+ * Slimmed wire-frame catalog + validators (spec B6) — comtac's protocol trimmed to the
+ * frames pi-persona actually needs: register/send/cancel/reply/list/bye (client→host) and
+ * registered/deliver/steer/peers/replied/error (host→client). Mirrors comtac's
+ * `messages.ts` validation STYLE (structural per-field checks, one explicit assert per
+ * case) but drops presence/sessions/attachments/broadcasts entirely (YAGNI here).
+ *
+ * Pure module: no Pi imports, unit-tested.
+ */
+
+import type { MsgKind } from "../inproc.ts";
+
+export type Frame =
+	| { t: "register"; handle: string; label?: string; group?: string; peers?: boolean }
+	| { t: "registered"; handle: string }
+	| { t: "send"; to: string; kind: MsgKind; text: string; msgId: string; expectsReply: boolean }
+	| { t: "cancel"; msgId: string }
+	| { t: "deliver"; from: string; fromLabel?: string; kind: MsgKind; text: string; msgId: string; expectsReply: boolean }
+	| { t: "reply"; askId: string; text: string }
+	| { t: "replied"; askId: string; text: string }
+	| { t: "steer"; text: string }
+	| { t: "list"; reqId: string }
+	| { t: "peers"; reqId: string; peers: Array<{ handle: string; label: string }> }
+	| { t: "bye" }
+	| { t: "error"; reason: string; msgId?: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isMsgKind(value: unknown): value is MsgKind {
+	return value === "progress" || value === "decision" || value === "interview";
+}
+
+function isPeerEntry(value: unknown): value is { handle: string; label: string } {
+	return isRecord(value) && typeof value.handle === "string" && typeof value.label === "string";
+}
+
+export function isFrame(value: unknown): value is Frame {
+	if (!isRecord(value)) return false;
+	switch (value.t) {
+		case "register": {
+			if (typeof value.handle !== "string") return false;
+			if (value.label !== undefined && typeof value.label !== "string") return false;
+			if (value.group !== undefined && typeof value.group !== "string") return false;
+			return value.peers === undefined || typeof value.peers === "boolean";
+		}
+		case "registered":
+			return typeof value.handle === "string";
+		case "send":
+			return (
+				typeof value.to === "string" &&
+				isMsgKind(value.kind) &&
+				typeof value.text === "string" &&
+				typeof value.msgId === "string" &&
+				typeof value.expectsReply === "boolean"
+			);
+		case "cancel":
+			return typeof value.msgId === "string";
+		case "deliver": {
+			if (typeof value.from !== "string") return false;
+			if (value.fromLabel !== undefined && typeof value.fromLabel !== "string") return false;
+			return (
+				isMsgKind(value.kind) &&
+				typeof value.text === "string" &&
+				typeof value.msgId === "string" &&
+				typeof value.expectsReply === "boolean"
+			);
+		}
+		case "reply":
+			return typeof value.askId === "string" && typeof value.text === "string";
+		case "replied":
+			return typeof value.askId === "string" && typeof value.text === "string";
+		case "steer":
+			return typeof value.text === "string";
+		case "list":
+			return typeof value.reqId === "string";
+		case "peers":
+			return typeof value.reqId === "string" && Array.isArray(value.peers) && value.peers.every(isPeerEntry);
+		case "bye":
+			return true;
+		case "error":
+			return typeof value.reason === "string" && (value.msgId === undefined || typeof value.msgId === "string");
+		default:
+			return false;
+	}
+}

package/src/bus/broker/paths.ts

@@ -0,0 +1,31 @@
+/**
+ * Session-scoped broker endpoint — the supervisor hosts one bus PER SESSION, so two
+ * concurrent supervisors never share it (spec B1). Windows uses a named pipe, every other
+ * platform a Unix domain socket under the user's Pi dir. Pure (home/platform injectable).
+ */
+
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** AF_UNIX `sun_path` is 104 bytes on macOS/BSD and 108 on Linux, NUL included — a socket
+ *  path over the smallest of those makes both `listen` and `connect` fail outright. */
+const MAX_SUN_PATH = 103;
+
+export function sanitizeSegment(s: string): string {
+	return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function brokerEndpoint(sessionId: string, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+	const sid = sanitizeSegment(sessionId) || "default";
+	if (platform === "win32") return `\\\\.\\pipe\\pi-persona-${sanitizeSegment(home)}-${sid}`;
+	const dir = join(home, ".pi", "agent", "persona");
+	const endpoint = join(dir, `broker-${sid}.sock`);
+	if (Buffer.byteLength(endpoint) <= MAX_SUN_PATH) return endpoint;
+	// Session ids are uuidv7 (36 chars), so an ordinary-but-longish $HOME already pushes the
+	// readable name past sun_path; a hashed one is short and still derived purely from the
+	// session id, so host and client compute the same endpoint independently. The hashed form
+	// costs `$HOME` + 41 bytes, so a $HOME past 62 bytes stays out of reach either way —
+	// nothing under the user's own dir would fit.
+	return join(dir, `b-${createHash("sha1").update(sid).digest("hex").slice(0, 12)}.sock`);
+}

package/src/bus/contact.ts

@@ -0,0 +1,145 @@
+/**
+ * `contact_supervisor` — the CHILD-side tool of the communication plane. A sub-agent
+ * calls it to reach its supervisor while it runs (guardrails §4.9, the comtac
+ * `contact_supervisor` semantic). Injected into an in-process child session as a
+ * `customTool` by the engine, bound to the shared {@link InProcessBus} + the child's
+ * handle.
+ *
+ * - `progress_update` (one-way): post and return immediately — the supervisor reads it
+ *   on its next peek (or it rides back on the run's result in sync mode).
+ * - `need_decision` / `interview_request` (blocking): `bus.ask` — the child waits for
+ *   the supervisor's reply. This only makes sense in **async** runs where the supervisor
+ *   is free to answer; the tool aborts cleanly on the run's signal so it never hangs a
+ *   sync run with no one listening.
+ *
+ * Pure factory (takes the bus + handles), so it is unit-tested without a live model.
+ */
+
+import { type Static, Type } from "typebox";
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import type { InProcessBus, MsgKind } from "./inproc.ts";
+
+const ContactParams = Type.Object({
+	kind: Type.Union([Type.Literal("progress"), Type.Literal("decision"), Type.Literal("interview")], {
+		description:
+			"progress = one-way status update (don't wait); decision = ask the supervisor to choose; interview = ask a clarifying question. For decision/interview, async runs wait for a reply; synchronous runs post one-way and continue.",
+	}),
+	message: Type.String({ description: "What to tell or ask the supervisor — specific and self-contained." }),
+});
+
+type ContactDetails = { kind: MsgKind; delivered: boolean };
+
+type AskFailure = "aborted" | "timeout" | "inbox-full" | "unavailable" | "generic";
+
+function classifyAskFailure(error: unknown, signal: AbortSignal | undefined): AskFailure {
+	if (signal?.aborted) return "aborted";
+	const message = error instanceof Error ? error.message : "";
+	if (/^ask timeout(?:\s|$)/i.test(message)) return "timeout";
+	if (/^inbox full(?:\s|:|$)/i.test(message)) return "inbox-full";
+	if (/^ask unregistered(?:\s|$)/i.test(message) || /^broker (?:connection|client) closed(?:\s|$)/i.test(message)) return "unavailable";
+	return "generic";
+}
+
+function result(t: string, details: ContactDetails): { content: [{ type: "text"; text: string }]; details: ContactDetails } {
+	return { content: [{ type: "text", text: t }], details };
+}
+
+/** Build the child's `contact_supervisor` tool, bound to a bus + the child's handle.
+ *  `defineTool` preserves param inference while widening the result so it slots into a
+ *  `customTools: ToolDefinition[]` array (the variance shim Pi provides for exactly this).
+ *
+ *  `allowBlocking` (async runs only): when false, a `decision`/`interview` does NOT block —
+ *  the supervisor is busy (a sync run holds the turn), so the question is posted one-way and
+ *  the child proceeds. This prevents a sync delegate/council from deadlocking on a child ask. */
+export function makeContactSupervisorTool(
+	bus: InProcessBus,
+	fromHandle: string,
+	supervisorHandle: string,
+	opts: { allowBlocking?: boolean } = {},
+) {
+	const allowBlocking = opts.allowBlocking ?? true;
+	return defineTool({
+		name: "contact_supervisor",
+		label: "Contact supervisor",
+		description: [
+			"Reach the supervisor that delegated this task WHILE you work.",
+			"Use `progress` to report a milestone (one-way, don't wait).",
+			"Use `decision` when you hit a choice only the supervisor should make, or `interview` to ask a clarifying question.",
+			allowBlocking
+				? "This async run waits for the supervisor's reply before continuing."
+				: "This synchronous run cannot block: decision/interview are posted one-way and return immediately; proceed using your best judgement.",
+			`Messages longer than ${MAX_CONTACT_MESSAGE_CHARS} characters are shortened before delivery; use smaller messages to preserve full detail.`,
+		].join(" "),
+		promptSnippet: "contact_supervisor — report progress or ask the supervisor a question",
+		parameters: ContactParams,
+		async execute(_toolCallId, params: Static<typeof ContactParams>, signal, _onUpdate, _ctx) {
+			const kind = params.kind as MsgKind;
+			const message = boundContactMessage(params.message);
+			if (kind === "progress") {
+				const delivered = bus.send(fromHandle, supervisorHandle, message, "progress");
+				return result(
+					delivered ? "Progress reported to the supervisor." : "(no supervisor listening; progress dropped)",
+					{ kind, delivered },
+				);
+			}
+
+			// In a sync run the supervisor is blocked holding the turn → it cannot answer. Post the
+			// question one-way and let the child proceed, rather than deadlock until timeout.
+			if (!allowBlocking) {
+				const delivered = bus.send(fromHandle, supervisorHandle, message, kind);
+				return result(
+					delivered
+						? "The supervisor is busy right now; your question was noted — proceed using your best judgement."
+						: "(no supervisor reachable — proceed using your best judgement)",
+					{ kind, delivered },
+				);
+			}
+
+			// decision | interview → block for the supervisor's reply. `bus.ask` honours the run
+			// signal (cleaning up its own timer/entry), and a rejection (abort or timeout) is
+			// turned into a RESULT — execute() must never throw or hang under the tool contract.
+			let answer: Promise<string>;
+			try {
+				answer = bus.ask(fromHandle, supervisorHandle, message, signal ? { kind, signal } : { kind });
+			} catch {
+				return result("(no supervisor reachable — proceed using your best judgement)", { kind, delivered: false });
+			}
+			try {
+				const reply = await answer;
+				return result(`Supervisor: ${reply}`, { kind, delivered: true });
+			} catch (error) {
+				const msg = (() => {
+					switch (classifyAskFailure(error, signal)) {
+						case "aborted":
+							return "(the request was cancelled before the supervisor replied)";
+						case "timeout":
+							return "(the supervisor did not reply in time — proceed using your best judgement)";
+						case "inbox-full":
+							return "(the supervisor inbox is full — this request was not delivered; retry later or consolidate the question)";
+						case "unavailable":
+							return "(the supervisor is no longer available — this request was not delivered; proceed using your best judgement)";
+						default:
+							return "(the supervisor request could not be completed — proceed using your best judgement)";
+					}
+				})();
+				return result(msg, { kind, delivered: false });
+			}
+		},
+	});
+}
+/** Maximum body accepted by contact_supervisor's message action. Full reports should use the
+ * delegated result channel rather than sending megabytes over the supervisor bus. */
+export const MAX_CONTACT_MESSAGE_CHARS = 8_000;
+
+/** Keep the sender-facing body bounded while preserving both ends and an omission count. */
+export function boundContactMessage(message: string, maxChars = MAX_CONTACT_MESSAGE_CHARS): string {
+	if (message.length <= maxChars) return message;
+	const marker = `\n\n[… ${message.length - maxChars} characters omitted; send the remaining detail in smaller contact_supervisor messages …]\n\n`;
+	if (marker.length >= maxChars) return marker.slice(0, Math.max(0, maxChars));
+	const content = Math.max(0, maxChars - marker.length);
+	const head = Math.ceil(content / 2);
+	const tail = Math.max(0, content - head);
+	return `${message.slice(0, head)}${marker}${tail > 0 ? message.slice(-tail) : ""}`;
+}