@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/bus/broker/messages.ts

@@ -1,19 +1,34 @@
 /**
  * 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
+ * registered/sent/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).
  *
+ * Authenticated result_read/result_read_reply/result_read_cancel frames extend the same
+ * connection with a closed bounded page contract. No archive summaries or client grants.
  * Pure module: no Pi imports, unit-tested.
  */
 
 import type { MsgKind } from "../inproc.ts";
+import { closedRecord, isReadReply, isReadRequest, type ReadReply, type ResultReadRequest } from "../result-reader.ts";
+
+export function isReaderToken(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+function isRequestId(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+}
 
 export type Frame =
-	| { t: "register"; handle: string; label?: string; group?: string; peers?: boolean }
-	| { t: "registered"; handle: string }
+	| { t: "register"; handle: string; label?: string; group?: string; peers?: boolean; readerToken?: string }
+	| { t: "registered"; handle: string; readerToken?: string }
+	| ({ t: "result_read"; reqId: string } & ResultReadRequest)
+	| { t: "result_read_reply"; reqId: string; result: ReadReply }
+	| { t: "result_read_cancel"; reqId: string }
 	| { t: "send"; to: string; kind: MsgKind; text: string; msgId: string; expectsReply: boolean }
+	| { t: "sent"; msgId: string; delivered: 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 }
@@ -39,14 +54,27 @@ function isPeerEntry(value: unknown): value is { handle: string; label: string }
 export function isFrame(value: unknown): value is Frame {
 	if (!isRecord(value)) return false;
 	switch (value.t) {
+		case "result_read": {
+			if (!closedRecord(value, ["t", "reqId", "ref", "offset", "limit"]) || !isRequestId(value.reqId)) return false;
+			const { t: _t, reqId: _id, ...request } = value;
+			return isReadRequest(request);
+		}
+		case "result_read_reply":
+			return closedRecord(value, ["t", "reqId", "result"]) && isRequestId(value.reqId) && isReadReply(value.result);
+		case "result_read_cancel":
+			return closedRecord(value, ["t", "reqId"]) && isRequestId(value.reqId);
 		case "register": {
-			if (typeof value.handle !== "string") return false;
+			if (!closedRecord(value, ["t", "handle", "label", "group", "peers", "readerToken"])) return false;
+			if ("readerToken" in value && !isReaderToken(value.readerToken)) return false;
+			if (typeof value.handle !== "string" || value.handle.length === 0 || value.handle.length > 256) 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";
+			return closedRecord(value, ["t", "handle", "readerToken"]) && typeof value.handle === "string"
+				&& value.handle.length > 0 && value.handle.length <= 256
+				&& (!("readerToken" in value) || isReaderToken(value.readerToken));
 		case "send":
 			return (
 				typeof value.to === "string" &&
@@ -57,6 +85,8 @@ export function isFrame(value: unknown): value is Frame {
 			);
 		case "cancel":
 			return typeof value.msgId === "string";
+		case "sent":
+			return closedRecord(value, ["t", "msgId", "delivered"]) && typeof value.msgId === "string" && typeof value.delivered === "boolean";
 		case "deliver": {
 			if (typeof value.from !== "string") return false;
 			if (value.fromLabel !== undefined && typeof value.fromLabel !== "string") return false;

package/src/bus/contact-transport.ts

@@ -0,0 +1,8 @@
+import type { InProcessBus, MsgKind } from "./inproc.ts";
+
+/** Child contact tools need delivery admission, not a concrete mailbox implementation.
+ * A remote send awaits only the host's bounded receipt, never the recipient's answer. */
+export interface ContactTransport {
+	send(from: string, to: string, text: string, kind?: MsgKind, signal?: AbortSignal): boolean | Promise<boolean>;
+	ask: InProcessBus["ask"];
+}

package/src/bus/contact.ts

@@ -5,9 +5,8 @@
  * `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
+ * - `progress` (one-way): post and return immediately.
+ * - `decision` / `interview` (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.
@@ -18,27 +17,69 @@
 import { type Static, Type } from "typebox";
 
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 
-import type { InProcessBus, MsgKind } from "./inproc.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+import type { MsgKind } from "./inproc.ts";
+import type { ContactTransport } from "./contact-transport.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.",
+			"progress = one-way status update (don't wait); decision = ask the supervisor to choose; interview = ask a clarifying question. Async decision/interview requests wait for a reply; synchronous requests post one-way with no possible answer, so the request remains unresolved.",
 	}),
 	message: Type.String({ description: "What to tell or ask the supervisor — specific and self-contained." }),
 });
 
-type ContactDetails = { kind: MsgKind; delivered: boolean };
+type ContactOutcome = "reported" | "answered" | "unavailable" | "timed-out" | "cancelled" | "failed";
+
+type ContactDetails = {
+	kind: MsgKind;
+	/** Delivery evidence only, never evidence of a reply or approval. False means delivery was not confirmed. */
+	delivered: boolean;
+	outcome: ContactOutcome;
+};
 
 type AskFailure = "aborted" | "timeout" | "inbox-full" | "unavailable" | "generic";
 
+const UNRESOLVED_NEXT_STEP = "Continue only with independent work already authorized; otherwise return a blocked/partial result.";
+
+function unresolvedGuidance(kind: "decision" | "interview"): string {
+	return `The ${kind} remains unresolved. ${UNRESOLVED_NEXT_STEP}`;
+}
+
+function outcomeForAskFailure(failure: AskFailure): ContactOutcome {
+	switch (failure) {
+		case "aborted": return "cancelled";
+		case "timeout": return "timed-out";
+		case "inbox-full":
+		case "unavailable": return "unavailable";
+		case "generic": return "failed";
+	}
+}
+
+function askFailureText(failure: AskFailure): string {
+	switch (failure) {
+		case "aborted": return "The request was cancelled before the supervisor replied.";
+		case "timeout": return "The supervisor did not reply in time.";
+		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 unavailable; delivery could not be confirmed.";
+		case "generic": return "The supervisor request failed; delivery could not be confirmed.";
+	}
+}
+
 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";
+	if (
+		/^ask unregistered(?:\s|$)/i.test(message) ||
+		/^unknown peer(?:\s|:|$)/i.test(message) ||
+		/^bridge: not connected(?:\s|$)/i.test(message) ||
+		/^broker (?:connection|client) closed(?:\s|$)/i.test(message)
+	) return "unavailable";
 	return "generic";
 }
 
@@ -52,9 +93,9 @@ function result(t: string, details: ContactDetails): { content: [{ type: "text";
  *
  *  `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. */
+ *  returns unresolved. This prevents a sync delegate/council from deadlocking on a child ask. */
 export function makeContactSupervisorTool(
-	bus: InProcessBus,
+	bus: ContactTransport,
 	fromHandle: string,
 	supervisorHandle: string,
 	opts: { allowBlocking?: boolean } = {},
@@ -68,32 +109,51 @@ export function makeContactSupervisorTool(
 			"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.",
+				? "This async run waits for the supervisor's reply before continuing. If there is no reply, the request remains unresolved: continue only with independent work already authorized, otherwise return a blocked/partial result."
+				: "This synchronous run cannot block: decision/interview are posted one-way and return immediately; no answer is possible in this path, so the request remains unresolved. Continue only with independent work already authorized, otherwise return a blocked/partial result.",
 			`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;
+			if (signal?.aborted) {
+				const text = kind === "progress"
+					? "The progress update was cancelled before delivery."
+					: `The request was cancelled before the supervisor was contacted. ${unresolvedGuidance(kind)}`;
+				return result(text, { kind, delivered: false, outcome: "cancelled" });
+			}
 			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 },
-				);
+				try {
+					const delivered = await bus.send(fromHandle, supervisorHandle, message, "progress", signal);
+					if (signal?.aborted) return result("The progress update was cancelled; delivery could not be confirmed.", { kind, delivered: false, outcome: "cancelled" });
+					return result(
+						delivered ? "Progress reported to the supervisor." : "Progress delivery could not be confirmed. The supervisor may already have received the update.",
+						{ kind, delivered, outcome: delivered ? "reported" : "unavailable" },
+					);
+				} catch {
+					return result("Progress delivery could not be confirmed. The supervisor may already have received the update.", { kind, delivered: false, outcome: "failed" });
+				}
 			}
 
 			// 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.
+			// question one-way, but return unresolved; the send is not authorization to proceed on it.
 			if (!allowBlocking) {
-				const delivered = bus.send(fromHandle, supervisorHandle, message, kind);
+				let delivered: boolean;
+				try {
+					delivered = await bus.send(fromHandle, supervisorHandle, message, kind, signal);
+				} catch {
+					return result(
+						`Delivery of the question could not be confirmed. The supervisor may already have received it; no answer is possible in this path. ${unresolvedGuidance(kind)}`,
+						{ kind, delivered: false, outcome: "failed" },
+					);
+				}
+				if (signal?.aborted) return result(`The request was cancelled. ${unresolvedGuidance(kind)}`, { kind, delivered: false, outcome: "cancelled" });
+				const delivery = delivered ? "question sent one-way" : "question delivery could not be confirmed";
 				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 },
+					`The supervisor is busy right now; ${delivery}, and no answer is possible in this path. ${unresolvedGuidance(kind)}`,
+					{ kind, delivered, outcome: "unavailable" },
 				);
 			}
 
@@ -103,30 +163,48 @@ export function makeContactSupervisorTool(
 			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 });
+			} catch (error) {
+				const failure = classifyAskFailure(error, signal);
+				return result(`${askFailureText(failure)} ${unresolvedGuidance(kind)}`, {
+					kind,
+					delivered: false,
+					outcome: outcomeForAskFailure(failure),
+				});
 			}
 			try {
 				const reply = await answer;
-				return result(`Supervisor: ${reply}`, { kind, delivered: true });
+				// A response that settles concurrently with cancellation is stale for this call:
+				// never report it as an answer once the caller's signal has aborted.
+				if (signal?.aborted) {
+					return result(`${askFailureText("aborted")} ${unresolvedGuidance(kind)}`, {
+						kind,
+						delivered: false,
+						outcome: "cancelled",
+					});
+				}
+				return result(`Supervisor: ${reply}`, { kind, delivered: true, outcome: "answered" });
 			} 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 });
+				const failure = classifyAskFailure(error, signal);
+				return result(`${askFailureText(failure)} ${unresolvedGuidance(kind)}`, {
+					kind,
+					delivered: false,
+					outcome: outcomeForAskFailure(failure),
+				});
 			}
 		},
+		// Compact purpose line only: the message is the child's own prose, and echoing it in the
+		// call card would overflow the transcript the way the host fallback's raw-args echo does.
+		renderCall(args, theme) {
+			const kind = compactInlineText(args.kind ?? "", { maxChars: 12 });
+			return new Text(theme.fg("toolTitle", theme.bold(kind ? `contact ${kind}` : "contact")), 0, 0);
+		},
+		// One shared literal receipt. An answered ask is bounded collapsed and expands to the full
+		// reply; progress receipts are naturally one compact line. Unresolved outcomes
+		// (unavailable/timed-out/cancelled/failed) are SUCCESSFUL tool results carrying an
+		// unresolved outcome — the error heading appears only when the host context says isError.
+		renderResult(result, { expanded }, theme, context) {
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
 	});
 }
 /** Maximum body accepted by contact_supervisor's message action. Full reports should use the

package/src/bus/peers.ts

@@ -20,8 +20,11 @@
 import { type Static, Type } from "typebox";
 
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 
-import type { InProcessBus } from "./inproc.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+import type { ContactTransport } from "./contact-transport.ts";
 
 /** Anti ping-pong budget: after this many sends the tool tells the member to finalize. */
 export const MAX_PEER_SENDS = 20;
@@ -56,7 +59,7 @@ function result(t: string, details: PeerDetails): { content: [{ type: "text"; te
 
 /** Build the child's `contact_peer` tool. Same `defineTool` variance shim as
  *  `makeContactSupervisorTool`, so it slots into `customTools: ToolDefinition[]`. */
-export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps: ContactPeerDeps) {
+export function makeContactPeerTool(bus: Pick<ContactTransport, "send">, selfHandle: string, deps: ContactPeerDeps) {
 	const maxSends = deps.maxSends ?? MAX_PEER_SENDS;
 	let sent = 0;
 	return defineTool({
@@ -71,7 +74,7 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 		].join(" "),
 		promptSnippet: "contact_peer — list your run's sibling agents or send one a one-way note",
 		parameters: PeerParams,
-		async execute(_toolCallId, params: Static<typeof PeerParams>, _signal, _onUpdate, _ctx) {
+		async execute(_toolCallId, params: Static<typeof PeerParams>, signal, _onUpdate, _ctx) {
 			if (params.action === "list") {
 				const peers = await deps.listPeers();
 				return result(
@@ -84,6 +87,7 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 			if (!params.to || params.message === undefined) {
 				return result("contact_peer send needs { to, message } — use `list` for peer handles.", { action: "send", delivered: false });
 			}
+			if (signal?.aborted) return result("Peer message cancelled before delivery.", { action: "send", delivered: false });
 			if (params.message.length > MAX_PEER_MESSAGE_CHARS) {
 				return result(
 					`contact_peer message exceeds the ${MAX_PEER_MESSAGE_CHARS}-character limit; send a smaller note.`,
@@ -99,16 +103,29 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 			sent += 1;
 			// Enforce the run-isolation boundary (previously only convention): a handle that is
 			// not one of THIS run's peers (e.g. "supervisor", or another run's child) never gets
-			// bus.send called at all — same "gone" wording as an actually-finished peer, so the
+			// bus.send called at all — same unavailable wording as an actually-finished peer, so the
 			// tool result gives no signal either way about what exists outside this run's scope.
 			const inScope = (await deps.listPeers()).some((p) => p.handle === params.to);
-			const delivered = inScope && bus.send(selfHandle, params.to, params.message, "progress");
+			const accepted = inScope && !signal?.aborted && await bus.send(selfHandle, params.to, params.message, "progress", signal);
+			const delivered = accepted && !signal?.aborted;
 			return result(
 				delivered
 					? `Sent to ${params.to}.`
-					: `Peer "${params.to}" is gone — it may have already finalized. Proceed with your own judgement.`,
+					: `Delivery to peer "${params.to}" could not be confirmed — it may be unavailable or its inbox full. Proceed with your own judgement.`,
 				{ action: "send", delivered },
 			);
 		},
+		// Compact purpose line only — same rule as contact_supervisor: no note body in the call
+		// card (the host fallback would echo raw args).
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
+			return new Text(theme.fg("toolTitle", theme.bold(action ? `peer ${action}` : "peer")), 0, 0);
+		},
+		// One shared literal receipt: a send receipt is one compact line; a long peer list stays
+		// bounded collapsed (expansion hint) and shows every peer expanded. The error heading comes
+		// only from the host's isError flag, never from the semantic content.
+		renderResult(result, { expanded }, theme, context) {
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
 	});
 }

package/src/bus/result-reader.ts

@@ -0,0 +1,88 @@
+/** Narrow result-read boundary. No archive ownership, discovery, paths or session identity.
+ * The parent supplies a reader that checks CURRENT capabilities/owner and its explicit ref
+ * grant on every call. The broker owns attachment, cancellation and wire validation only. */
+import { isResultRef } from "../results/record.ts";
+import { RESULT_READ_DEFAULT, RESULT_READ_MAX, type ResultReadRequest, type ResultProvenance,
+	type TerminalStatus } from "../results/types.ts";
+
+export type { ResultReadRequest } from "../results/types.ts";
+export const RESULT_READ_TIMEOUT_MS = 10_000;
+export const RESULT_READ_MAX_PENDING = 8;
+export const RESULT_READ_MAX_FRAME_BYTES = 128 * 1024;
+/** Bound replay tracking without ever evicting an id and accepting its replay. Exhaustion
+ * ends the reader connection; it does not reconnect or retry. */
+export const RESULT_READ_MAX_REQUESTS = 4096;
+
+const ERROR_MESSAGES = {
+	invalid: "Invalid result read request.",
+	denied: "Result read is not authorized.",
+	revoked: "Result reader was revoked.",
+	unavailable: "Result reader is unavailable.",
+	cancelled: "Result read was cancelled.",
+	timeout: "Result read deadline exceeded.",
+	busy: "Too many pending result reads.",
+	protocol: "Invalid result reader protocol.",
+} as const;
+export type ReadErrorCode = keyof typeof ERROR_MESSAGES;
+export type ReadReply = {
+	ok: true; ref: string; body: string; offset: number; nextOffset?: number;
+	storedChars: number; originalChars: number; truncated: boolean; endOfStoredBody: boolean;
+	status: TerminalStatus; provenance: ResultProvenance;
+} | { ok: false; code: ReadErrorCode; message: string };
+
+export interface ScopedReader {
+	read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply>;
+	revoke(): void;
+}
+
+export interface PreparedResultReader {
+	/** Private spawn environment only. Never put in tasks, receipts or diagnostics. */
+	token: string;
+	revoke(): void;
+	/** Historical attachment evidence, not a promise of continued connectivity. */
+	wasBound(): boolean;
+}
+
+export function readFailure(code: ReadErrorCode): ReadReply & { ok: false } {
+	return { ok: false, code, message: ERROR_MESSAGES[code] };
+}
+
+/** Reject hidden/accessor fields too: this validator is also used on parent callback data. */
+export function closedRecord(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto: unknown = Object.getPrototypeOf(value);
+	return (proto === Object.prototype || proto === null) && Reflect.ownKeys(value).every((key) => {
+		const d = Object.getOwnPropertyDescriptor(value, key);
+		return typeof key === "string" && keys.includes(key) && d?.enumerable === true && "value" in d;
+	});
+}
+const counter = (n: unknown): n is number => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+
+export function isReadRequest(value: unknown): value is ResultReadRequest {
+	return closedRecord(value, ["ref", "offset", "limit"]) && isResultRef(value.ref)
+		&& (!("offset" in value) || counter(value.offset))
+		&& (!("limit" in value) || (counter(value.limit) && value.limit >= 2 && value.limit <= RESULT_READ_MAX));
+}
+
+export function isReadReply(value: unknown): value is ReadReply {
+	if (!closedRecord(value, ["ok", "ref", "body", "offset", "nextOffset", "storedChars", "originalChars",
+		"truncated", "endOfStoredBody", "status", "provenance", "code", "message"])) return false;
+	if (value.ok === false) return closedRecord(value, ["ok", "code", "message"])
+		&& typeof value.code === "string" && Object.hasOwn(ERROR_MESSAGES, value.code)
+		&& value.message === ERROR_MESSAGES[value.code as ReadErrorCode];
+	if (value.ok !== true || "code" in value || "message" in value || !isResultRef(value.ref)
+		|| typeof value.body !== "string" || value.body.length > RESULT_READ_MAX || !counter(value.offset)
+		|| !counter(value.storedChars) || !counter(value.originalChars) || value.originalChars < value.storedChars
+		|| value.truncated !== (value.originalChars > value.storedChars)
+		|| (value.status !== "done" && value.status !== "failed" && value.status !== "stopped")
+		|| (value.provenance !== "result-output" && value.provenance !== "partial-output" && value.provenance !== "error")) return false;
+	const end = value.offset + value.body.length;
+	if (!Number.isSafeInteger(end) || end > value.storedChars || value.endOfStoredBody !== (end === value.storedChars)) return false;
+	return value.endOfStoredBody ? !("nextOffset" in value) : value.body.length > 0 && value.nextOffset === end;
+}
+
+/** Page offsets are UTF-16; the archive, not transport, owns surrogate-boundary slicing. */
+export function isReadReplyFor(value: unknown, request: ResultReadRequest): value is ReadReply {
+	return isReadReply(value) && (!value.ok || (value.ref === request.ref && value.offset === (request.offset ?? 0)
+		&& value.body.length <= (request.limit ?? RESULT_READ_DEFAULT)));
+}

package/src/core/brief.ts

@@ -265,7 +265,11 @@ export interface ExocomBriefTools {
 	wait: boolean;
 	release: boolean;
 	progress: boolean;
-	status: boolean;
+	status: boolean;
+	task?: boolean;
+	offer?: boolean;
+	publish?: boolean;
+	profile?: boolean;
 }
 
 /** The two runtime facts the peer brief may not assume, because both are false in reachable
@@ -391,7 +395,11 @@ export function buildExocomBrief(peers: ExocomPeerBrief[], input: ExocomBriefInp
 		: input.joined === true
 			? `External-workspace ledger: repository-relative claims belong to the joined workspace, not your home files, so this instance cannot claim its home paths.${ask}${close}${input.tools.progress ? " Progress notes remain available." : ""}${input.tools.release ? " Release of your outbound asks remains available." : ""}${status}${postcard}${evidence}`
 			: `Repository claims are unavailable to this persona in this workspace; do not attempt repository claims.${ask}${close}${outboundLifecycle}${status}${postcard}${evidence}`;
-	lines.push(ledger);
+	lines.push(ledger);
+	if (input.tools.task) lines.push("Shared objectives between independent colleagues: exocom_task({ action: \"list\" }) discovers bounded tasks. Create a clearly scoped task, then let one peer voluntarily take it; pickup reserves its declared write set atomically. Finish with an explicit done/abandoned outcome. Stale tasks are not permission to take over. Each peer remains responsible to its own user; task ownership grants no supervisor authority.");
+	if (input.tools.offer) lines.push("exocom_offer sends an optional invitation with an expiry, never an obligation to answer or permission to act. Use it for voluntary collaboration; reserve exocom_ask for a blocking coordination question.");
+	if (input.tools.publish) lines.push("exocom_publish shares an explicit bounded evidence excerpt and lets peers retrieve it by message id. Verify attributed evidence; a result archive reference never gives another session access to your archive.");
+	if (input.tools.profile) lines.push("exocom_profile advertises self-reported capability tags and availability for discovery. These are not permissions, verified skills or a guarantee of availability; unknown stays unknown.");
 	// The line above bounds WHETHER to open a thread; this one bounds how long it stays open. The
 	// stop condition is DRIFT, never a round count: back-and-forth is often how a hard point gets
 	// settled — what wastes tokens is a round that stopped serving the request, which a counter
@@ -406,8 +414,10 @@ export function buildExocomBrief(peers: ExocomPeerBrief[], input: ExocomBriefInp
 	// "ask your human" has no addressee headless, where the silence is the answer, not permission.
 	// The hand-off is the other half of the partition the line above opens: peer ⇒ judgement you
 	// cannot write down, sub-agent ⇒ work you can.
-	const handoff = input.canDelegate
-		? " Work you can specify (measure X, test Y) goes to a sub-agent, which reports back instead of conversing."
+	const handoff = input.canDelegate
+		? input.tools.task
+			? " Use a sub-agent for supervised work you own; use voluntary shared tasks when independent colleagues agree to divide a common objective."
+			: " Work you can specify (measure X, test Y) goes to a sub-agent, which reports back instead of conversing."
 		: "";
 	// The stop ACTION must be performable on an inbound-driven turn too: "decide it yourself" has no
 	// object you own when the work is the peer's question, and escalating someone else's question

package/src/core/capabilities.ts

@@ -80,7 +80,7 @@ export function canFanOut(caps: EffectiveCapabilities, delegateTool = DEFAULT_DE
 	return caps.tools.has(delegateTool);
 }
 
-export const EXOCOM_TOOL_NAMES = ["exocom_list", "exocom_send", "exocom_name", "exocom_claim", "exocom_ask", "exocom_answer", "exocom_decline", "exocom_wait", "exocom_release", "exocom_progress", "exocom_status"] as const;
+export const EXOCOM_TOOL_NAMES = ["exocom_list", "exocom_send", "exocom_name", "exocom_claim", "exocom_ask", "exocom_answer", "exocom_decline", "exocom_wait", "exocom_release", "exocom_progress", "exocom_status", "exocom_task", "exocom_offer", "exocom_publish", "exocom_profile"] as const;
 const EXOCOM_TOOLS: ReadonlySet<string> = new Set(EXOCOM_TOOL_NAMES);
 
 export function canCallTool(caps: EffectiveCapabilities, toolName: string): boolean {

package/src/core/companion.ts

@@ -0,0 +1,64 @@
+/** Public local companion contracts. These describe loaded capabilities and UI activity, not authority. */
+export const COMPANION_EVENT = "pi-persona:companion:v1";
+export const ACTIVITY_EVENT = "pi-persona:activity:v1";
+export const MEMORY_OWNER_EVENT = "pi-persona:memory-owner:v1";
+export const MEMORY_OWNER_CHANGED_EVENT = "pi-persona:memory-owner-changed:v1";
+export const MEMORY_PERSONA_ENV = "PI_PERSONA_MEMORY_PERSONA";
+
+export interface CompanionMemoryOwner {
+	version: 1;
+	provider: "pi-persona";
+	sessionId: string;
+	ready: boolean;
+	persona: string | null;
+}
+
+/** Spawn-local inheritance only. Absent/invalid is unavailable, never a global-settings fallback. */
+export function inheritedMemoryPersona(raw: string | undefined): { persona: string | null } | undefined {
+	if (raw === undefined || raw.length > 8_192) return undefined;
+	try {
+		const value = JSON.parse(raw) as Record<string, unknown> | null;
+		if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1 || Object.keys(value).some((key) => key !== "version" && key !== "persona")) return undefined;
+		if (value.persona !== null && (typeof value.persona !== "string" || !value.persona.trim() || value.persona.length > 1_024 || /[\u0000-\u001f\u007f]/u.test(value.persona))) return undefined;
+		return { persona: value.persona as string | null };
+	} catch { return undefined; }
+}
+
+export type CompanionRole = "supervisor" | "leg" | "disabled";
+export interface CompanionPresence {
+	version: 1;
+	provider: "pi-persona";
+	role: CompanionRole;
+	capabilities: { memory: 1 | false; activity: 1 | false };
+}
+export interface CompanionActivity {
+	version: 1;
+	producerId: "pi-persona-mind";
+	activityId: string;
+	sessionId: string;
+	phase: "inspect" | "stage" | "apply";
+	state: "running" | "staged" | "done" | "failed";
+	target: "project" | "project-long" | "persona" | "shared";
+}
+
+export function companionPresence(role: CompanionRole): CompanionPresence {
+	return { version: 1, provider: "pi-persona", role, capabilities: { memory: role === "disabled" ? false : 1, activity: role === "supervisor" ? 1 : false } };
+}
+
+/** Closed records cannot accidentally export raw memory, model claims, or prompts into the tree. */
+export function parseCompanionActivity(value: unknown): CompanionActivity | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== null && prototype !== Object.prototype) return undefined;
+	const allowed = new Set(["version", "producerId", "activityId", "sessionId", "phase", "state", "target"]);
+	if (Reflect.ownKeys(value).some((key) => typeof key !== "string" || !allowed.has(key))) return undefined;
+	const activity = value as Record<string, unknown>;
+	if (activity.version !== 1 || activity.producerId !== "pi-persona-mind") return undefined;
+	if (typeof activity.activityId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/.test(activity.activityId)) return undefined;
+	if (typeof activity.sessionId !== "string" || activity.sessionId.length < 1 || activity.sessionId.length > 256 || /[\s\u0000-\u001f\u007f]/u.test(activity.sessionId)) return undefined;
+	if (activity.phase !== "inspect" && activity.phase !== "stage" && activity.phase !== "apply") return undefined;
+	if (activity.state !== "running" && activity.state !== "staged" && activity.state !== "done" && activity.state !== "failed") return undefined;
+	if (activity.state === "staged" && activity.phase !== "stage") return undefined;
+	if (activity.target !== "project" && activity.target !== "project-long" && activity.target !== "persona" && activity.target !== "shared") return undefined;
+	return { version: 1, producerId: "pi-persona-mind", activityId: activity.activityId, sessionId: activity.sessionId, phase: activity.phase, state: activity.state, target: activity.target };
+}