pi-crew 0.10.2 → 0.10.3

package/src/runtime/broker/crew-broker.ts

@@ -35,7 +35,7 @@ import {
 } from "../../state/coordination/mailbox.ts";
 import { appendEventAsync, readEventsCursor } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../../state/stores/state-store.ts";
-import type { TeamTaskState } from "../../state/types.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import { runEventBus } from "../../ui/run-event-bus.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { BrokerError, encodeBrokerFrame, MAX_BROKER_FRAME_BYTES, NdjsonDecoder } from "../../utils/ndjson.ts";
@@ -46,7 +46,7 @@ import { type GrandchildSpawnInput, type GrandchildSpawnResult, spawnDelegateGra
 import { resolveCrewMaxDepth } from "../model/pi-args.ts";
 import { NestedSlotBudget } from "../scheduling/nested-slots.ts";
 import { evaluateDelegateAdmission } from "../spawn-policy.ts";
-import { BrokerTokenRegistry } from "./crew-broker-tokens.ts";
+import { type BrokerToken, BrokerTokenRegistry } from "./crew-broker-tokens.ts";
 import { WaitStatusCache } from "./wait-status-cache.ts";
 
 /** Protocol version negotiated at `hello` time. Bump on breaking change. */
@@ -56,6 +56,13 @@ const BROKER_PROTOCOL = 1;
  *  generic auth/protocol code. */
 const HELLO_DEADLINE_MS = 1_000;
 
+/** Task 10 (mux-surface A1 §5.2): run statuses after which every hello token
+ *  is by definition stale — the run will never issue work again, so the error
+ *  is "stale-token" instead of generic auth. NARROWER than
+ *  TEAM_TERMINAL_RUN_STATUSES on purpose: "blocked" is recoverable, so a
+ *  blocked run still authenticates normally. */
+const STALE_RUN_STATUSES: ReadonlySet<string> = new Set(["completed", "failed", "cancelled"]);
+
 /** Default per-connection outbound queue cap (events). */
 const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
 
@@ -89,9 +96,11 @@ export interface CrewBrokerOptions {
 	 *  `config.broker.waitMethodsEnabled` here; tests pass it explicitly. */
 	waitMethodsEnabled?: boolean;
 	/** T3/R5 (ADR-5 §10): capability gate for the `delegate` surface. DEFAULT
-	 *  FALSE — fail-closed until the WP-5 completion gate flips it. The
-	 *  production wiring threads `config.nesting.enabled` here; tests pass it
-	 *  explicitly. Rejections are NEVER silent (delegate.rejected event). */
+	 *  TRUE since D8 (spec v0.7) — nested spawning is open out of the box; the
+	 *  broker still fail-closes when the flag is anything but true. The
+	 *  production wiring threads `config.nesting.enabled` (loadConfig layers
+	 *  DEFAULT_NESTING.enabled=true; a user `false` closes the surface); tests
+	 *  pass it explicitly. Rejections are NEVER silent (delegate.rejected). */
 	nestingEnabled?: boolean;
 	/** Optional override for the nested-slot budget size (config nesting.maxSlots). */
 	nestingMaxSlots?: number;
@@ -128,6 +137,12 @@ interface ServerConnection {
 	 *  legacy bare-runId fallback match WITHOUT keeping the raw token on the
 	 *  connection (tokens stay confined to the heap-only registry). */
 	authMatchKind?: "compound" | "runId-fallback";
+	/** Task 10 fix round 2 (BUG #3): sha256 of the secret this connection
+	 *  authenticated with. Derived, one-way — never the plaintext token. The
+	 *  post-hello revocation check evaluates THIS digest so a revoke →
+	 *  re-issue window cannot let an old connection ride the freshly issued
+	 *  token for the same key. */
+	authedSecretHash?: string;
 	/** Outbound queue of encoded frames awaiting drain. */
 	outbound: Buffer[];
 	/** Set when the queue has hit the cap and a frame was dropped. */
@@ -159,6 +174,12 @@ export class CrewBroker {
 			| "serializeOnPathOverlap"
 		>;
 	private readonly tokens = new BrokerTokenRegistry();
+	/** Task 10 (mux-surface A1 §5.2): taskId → the compound token most
+	 *  recently issued for it. revokeTaskToken(taskId) resolves the exact
+	 *  secret through this map — no runId needed (the broker serves many
+	 *  runs; a colliding taskId in another run revokes both, which is the
+	 *  conservative direction). Heap-only like the registry. */
+	private readonly taskTokens = new Map<string, BrokerToken>();
 	private server: net.Server | null = null;
 	private resolvedSocketPath: string | null = null;
 	private stopped = false;
@@ -236,7 +257,29 @@ export class CrewBroker {
 		if (typeof runId !== "string" || runId.length === 0) {
 			throw new Error("CrewBroker.issueRunToken: runId must be a non-empty string");
 		}
-		return this.tokens.issue(runId, taskId);
+		const token = this.tokens.issue(runId, taskId);
+		// Task 10: track the live secret per taskId so revokeTaskToken can
+		// resolve it later. A re-issue overwrites the entry; the OLD token
+		// keeps whatever revocation it already had (per-secret, not per-key).
+		if (taskId !== undefined) this.taskTokens.set(taskId, token);
+		return token;
+	}
+
+	/** Task 10 (mux-surface A1 §5.2): revoke the token issued for `taskId`.
+	 *  The next hello presenting that token — and every subsequent frame on a
+	 *  connection already authenticated with it — is rejected with code
+	 *  "revoked". Open connections are NOT force-closed (A1 enforces at the
+	 *  next frame boundary; re-issue is the A2 remedy). No-op when no token
+	 *  was ever issued for the task. */
+	revokeTaskToken(taskId: string): void {
+		if (typeof taskId !== "string" || taskId.length === 0) {
+			throw new Error("CrewBroker.revokeTaskToken: taskId must be a non-empty string");
+		}
+		const token = this.taskTokens.get(taskId);
+		if (token !== undefined) {
+			this.tokens.revokeToken(token);
+			this.taskTokens.delete(taskId);
+		}
 	}
 
 	/** Issue the orchestrator token for `runId` (F-06). Cryptographically
@@ -412,6 +455,8 @@ export class CrewBroker {
 		// 3. Clear the token map. This is the single point where the heap
 		//    state for runIds is wiped. No persistence to clean up.
 		this.tokens.clear();
+		// Task 10: drop the taskId → token index with it.
+		this.taskTokens.clear();
 
 		// 4. Unlink the recorded socket file IF we created it. We never
 		//    touch any other path. We also never `process.kill` anything.
@@ -555,7 +600,15 @@ export class CrewBroker {
 		for (const conn of set) {
 			if (conn.closed || !conn.authed) continue;
 			// Recipient filter: deliver to the addressed task, or to all if 'all'.
-			if (msg.to && msg.to !== "all" && conn.taskId !== msg.to) continue;
+			// Task 5b (§15.2 wake): "parent"-addressed messages land in the
+			// run-level inbox, whose live consumer is the run's orchestrator
+			// connection (role from the orchestrator token — its taskId never
+			// equals "parent"), so without this branch the wake frame would be
+			// filtered out and the orchestrator would only see the message on
+			// its next inbox poll.
+			const isRecipient =
+				!msg.to || msg.to === "all" || conn.taskId === msg.to || (msg.to === "parent" && conn.role === "orchestrator");
+			if (!isRecipient) continue;
 			try {
 				this.writeOrQueue(conn, eventFrame, false);
 			} catch {
@@ -604,6 +657,24 @@ export class CrewBroker {
 		}
 
 		// Post-hello: dispatch the known set.
+		// Task 10 (mux-surface A1 §5.2): a revoked task token is dead on
+		// arrival for EVERY frame, not just hellos — an already-authed
+		// connection is rejected here, at the next request boundary, with the
+		// connection closed (A1: no mid-stream force-close, so the revoke
+		// itself never tears a socket out from under a handler).
+		// Fix round 1 (BUG #2): WORKER role only — an orchestrator hello may
+		// legitimately name a revoked task as its taskId (T11 degrade: revoke
+		// → respawn → steer).
+		// Fix round 2 (BUG #3): SECRET-based, not key-based — the check
+		// evaluates the digest of the secret this connection authenticated
+		// with. Looking up the token currently registered for the key let a
+		// revoked-secret connection silently regain full capability once the
+		// key was re-issued for the respawn (the connection outlived the
+		// revoke → re-issue window while staying quiet).
+		if (conn.role === "worker" && conn.authedSecretHash !== undefined && this.tokens.isSecretRevoked(conn.authedSecretHash)) {
+			this.sendErrorAndClose(conn, id, "revoked", "token revoked");
+			return;
+		}
 		switch (method) {
 			case "ping":
 				this.sendResult(conn, id, { pong: true, protocol: BROKER_PROTOCOL });
@@ -680,9 +751,48 @@ export class CrewBroker {
 		// task-scoped-token rule without retaining the secret candidate.
 		const resolved = this.tokens.tokenRoleWithMatchKind(runId, taskId, token);
 		if (resolved === null) {
+			// Task 10 (mux-surface A1 §5.2): distinguish a STALE token from a
+			// wrong one. A worker re-attaching from a durable surface (broker
+			// restarted → heap registry lost, run still on disk) presents a
+			// token this broker never issued: when the run exists and the task
+			// is real, that is a stale token — reject, but say so, because the
+			// A2 remedy is a re-issue, not a retry. An unknown run/task keeps
+			// the generic auth error (no disclosure of which id was valid).
+			const loaded = this.loadRunForHello(runId);
+			if (loaded && (loaded.tasks ?? []).some((t) => t.id === taskId)) {
+				this.sendErrorAndClose(
+					conn,
+					id,
+					"stale-token",
+					"hello rejected: stale token (run/task exist but this broker did not issue the token; re-issue required)",
+				);
+				return;
+			}
 			this.sendErrorAndClose(conn, id, "auth", "hello rejected");
 			return;
 		}
+		// Task 10: the token matches — but an explicitly revoked secret is
+		// reported as "revoked" (more specific than stale), and a WORKER token
+		// for a TERMINAL run is stale by definition: the run will never issue
+		// work again, so a surface worker must not re-attach with it.
+		// Orchestrator connections are exempt from BOTH checks: the
+		// orchestrator is in-process (same root session) and legitimately
+		// talks to the broker after the run completed (late steer, closeout
+		// reads) and after a task token was revoked (T11 degrade flow).
+		// Fix round 1 (BUG #2): the revoked check keys on (runId, taskId), so
+		// without the role guard an orchestrator hello naming a revoked task
+		// as its taskId was rejected 'revoked'.
+		if (resolved.role === "worker" && this.tokens.isTaskTokenRevoked(runId, taskId)) {
+			this.sendErrorAndClose(conn, id, "revoked", "hello rejected: token revoked");
+			return;
+		}
+		if (resolved.role === "worker") {
+			const loaded = this.loadRunForHello(runId);
+			if (loaded && STALE_RUN_STATUSES.has(loaded.manifest.status)) {
+				this.sendErrorAndClose(conn, id, "stale-token", "hello rejected: run is already terminal (stale token)");
+				return;
+			}
+		}
 
 		// Bounded identity checks. taskId must be a non-empty string.
 		if (typeof taskId !== "string" || taskId.length === 0 || taskId.length > 256) {
@@ -700,6 +810,9 @@ export class CrewBroker {
 		conn.taskId = taskId;
 		conn.role = resolved.role;
 		conn.authMatchKind = resolved.matchKind;
+		// Fix round 2 (BUG #3): digest of the authenticated secret for the
+		// secret-based frame revocation check below (never the plaintext).
+		conn.authedSecretHash = BrokerTokenRegistry.hashToken(token);
 		// Phase 1.3: index by runId for live mailbox fanout.
 		let connsForRun = this.connectionsByRun.get(runId);
 		if (!connsForRun) {
@@ -720,6 +833,21 @@ export class CrewBroker {
 		});
 	}
 
+	/** Task 10 (mux-surface A1 §5.2): best-effort manifest load for the hello
+	 *  decision path. Returns undefined when no cwd is configured or the run
+	 *  is not on disk — callers treat that as "cannot classify" and keep the
+	 *  legacy generic-auth behavior (the heap registry stays the source of
+	 *  truth for authentication). */
+	private loadRunForHello(runId: string): { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined {
+		const cwd = this.options.cwd;
+		if (!cwd) return undefined;
+		try {
+			return loadRunManifestById(cwd, runId) ?? undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
 	// ------------------------------------------------------------------------
 	// Outbound queue + drop-newest + needsResync
 	// ------------------------------------------------------------------------
@@ -819,19 +947,31 @@ export class CrewBroker {
 
 	/** Phase 1.1: direct or broadcast mailbox write via the durable append path. */
 	private async handleMsgSend(conn: ServerConnection, id: string, params: unknown): Promise<void> {
-		if (conn.role !== "orchestrator") {
-			this.sendError(conn, id, "forbidden", "msg.send requires orchestrator role");
-			return;
-		}
 		if (!conn.runId) {
 			this.sendError(conn, id, "auth", "not authed");
 			return;
 		}
+		// D9/§15.2 role gate: workers may send messages (for notifying the
+		// orchestrator, DMing a sibling, or broadcasting the group) with strictly
+		// bounded privileges. Orchestrator role keeps its full prior surface
+		// (arrays / "all" / steer kinds / arbitrary recipient sets).
+		const isWorker = conn.role === "worker";
+		if (conn.role !== "orchestrator" && !isWorker) {
+			this.sendError(conn, id, "forbidden", "msg.send requires orchestrator or worker role");
+			return;
+		}
 		const parsed = parseMsgSendParams(params);
 		if (!parsed) {
 			this.sendError(conn, id, "bad-params", "msg.send: invalid params");
 			return;
 		}
+		// Worker constraint (3): kind limited to notify|message. Fire-and-forget
+		// `notify` vs inbox-facing `message` — both return immediately to the
+		// caller; the distinction is receiver-side handling.
+		if (isWorker && parsed.kind !== undefined && parsed.kind !== "notify" && parsed.kind !== "message") {
+			this.sendError(conn, id, "bad-params", "msg.send: worker kind must be 'notify' or 'message'");
+			return;
+		}
 		const bodyJson = safeStringify(parsed.body);
 		if (bodyJson.length > MAX_BROKER_FRAME_BYTES) {
 			this.sendError(conn, id, "oversize-frame", "msg.send: body too large");
@@ -856,41 +996,116 @@ export class CrewBroker {
 			this.sendError(conn, id, "no-manifest", (err as Error).message);
 			return;
 		}
-		const recipients: string[] = Array.isArray(parsed.to)
-			? (parsed.to as string[])
-			: parsed.to === "all"
-				? taskIds
-				: [parsed.to as string];
-		if (recipients.length === 0 || recipients.length > 64) {
-			this.sendError(conn, id, "bad-params", "msg.send: recipient count out of range");
-			return;
+		// ── Recipient resolution ──────────────────────────────────────────────
+		// Each target is {label, mailboxTaskId}: `label` is echoed in the ack
+		// and message id, `mailboxTaskId` is the mailbox file the append lands
+		// in (undefined = run-level inbox, which the orchestrator consumes).
+		let targets: Array<{ label: string; mailboxTaskId: string | undefined }>;
+		// Task 5b (spec §15.2 wake): set when a worker addresses the parent —
+		// the durable write alone would sit unread in the run-level inbox.
+		let sentToParent = false;
+		if (isWorker) {
+			// Worker constraint (1): from is ALWAYS the authenticated taskId.
+			// Worker constraint (2): to is limited to parent | valid sibling
+			// taskId | group.
+			if (!conn.taskId) {
+				this.sendError(conn, id, "forbidden", "msg.send worker requires a task-scoped identity");
+				return;
+			}
+			const to = typeof parsed.to === "string" ? parsed.to : undefined;
+			if (to === "parent") {
+				// Run-level inbox (taskId undefined) → the orchestrator session.
+				targets = [{ label: "parent", mailboxTaskId: undefined }];
+				sentToParent = true;
+			} else if (to === "group") {
+				targets = taskIds.map((t) => ({ label: t, mailboxTaskId: t }));
+			} else if (to !== undefined && taskIds.includes(to)) {
+				targets = [{ label: to, mailboxTaskId: to }];
+			} else {
+				this.sendError(conn, id, "forbidden", `msg.send: worker cannot target '${to}'`);
+				return;
+			}
+			if (targets.length === 0 || targets.length > 64) {
+				this.sendError(conn, id, "bad-params", "msg.send: recipient count out of range");
+				return;
+			}
+		} else {
+			const recipients: string[] = Array.isArray(parsed.to)
+				? (parsed.to as string[])
+				: parsed.to === "all"
+					? taskIds
+					: [parsed.to as string];
+			if (recipients.length === 0 || recipients.length > 64) {
+				this.sendError(conn, id, "bad-params", "msg.send: recipient count out of range");
+				return;
+			}
+			targets = recipients.map((recipient) => ({ label: recipient, mailboxTaskId: recipient }));
 		}
 		const messageId = `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-		const fromField = conn.taskId ?? conn.runId;
+		const fromField = isWorker ? conn.taskId! : (conn.taskId ?? conn.runId);
 		let durable = false;
 		try {
-			for (const recipient of recipients) {
-				await appendMailboxMessageAsync(manifest, {
-					id: `${messageId}_${recipient}`,
-					direction: "inbox",
-					from: fromField,
-					to: recipient,
-					taskId: recipient,
-					body: bodyJson,
-					kind: parsed.kind ?? "message",
-					priority: parsed.priority ?? "normal",
-					deliveryMode: "next_turn",
-					replyTo: parsed.replyTo,
-				});
+			// PERF (2026-08-24): to:"all" with 50 tasks used to run 50 sequential
+			// awaited locked appends (~70 syscalls + 2 fsync each) while the
+			// connection's frames queued behind it. Chunked fan-out — independent
+			// mailbox files append concurrently; delivery.json stays serialized by
+			// its own lock.
+			const CHUNK = 8;
+			for (let i = 0; i < targets.length; i += CHUNK) {
+				const results = await Promise.allSettled(
+					targets.slice(i, i + CHUNK).map((target) =>
+						appendMailboxMessageAsync(manifest, {
+							id: `${messageId}_${target.label}`,
+							direction: "inbox",
+							from: fromField,
+							to: target.label,
+							taskId: target.mailboxTaskId,
+							body: bodyJson,
+							kind: parsed.kind ?? "message",
+							priority: parsed.priority ?? "normal",
+							deliveryMode: "next_turn",
+							replyTo: parsed.replyTo,
+						}),
+					),
+				);
+				const failure = results.find((r) => r.status === "rejected") as PromiseRejectedResult | undefined;
+				if (failure) throw failure.reason;
 			}
 			durable = true;
 		} catch (err) {
 			this.sendError(conn, id, "durable-failed", (err as Error).message);
 			return;
 		}
+		// Task 5b (spec §15.2 wake): a worker message addressed to the parent
+		// appends a bounded `worker.message` run event so the host-side event
+		// bus (sidebar/widget refresh) and any live orchestrator connection
+		// wake up. Only kind/subject are recorded — NEVER the body, to keep the
+		// append-only event log lean. Awaited before the ack so the wake signal
+		// is durable by the time the caller proceeds; failure is non-fatal (the
+		// mailbox write above is the source of truth).
+		if (sentToParent) {
+			try {
+				await appendEventAsync(manifest.eventsPath, {
+					type: "worker.message",
+					runId: manifest.runId,
+					taskId: fromField,
+					data: {
+						to: "parent",
+						kind: parsed.kind ?? "message",
+						...(parsed.subject !== undefined ? { subject: parsed.subject } : {}),
+					},
+				});
+			} catch (err) {
+				logInternalError(
+					"crew-broker.msg.worker-message-event",
+					err instanceof Error ? err : new Error(String(err)),
+					`runId=${conn.runId}`,
+				);
+			}
+		}
 		this.sendResult(conn, id, {
 			messageId,
-			recipientCount: recipients.length,
+			recipientCount: targets.length,
 			durableStatus: durable ? "ok" : "failed",
 			liveDeliveryStatus: "ok",
 		});
@@ -1401,17 +1616,19 @@ export class CrewBroker {
 			this.sendError(conn, id, "no-manifest", (err as Error).message);
 			return;
 		}
-		// Capability gate (ADR-5 §10): fail-closed, NEVER silent.
+		// Capability gate (ADR-5 §10): fail-closed, NEVER silent. Since the D8
+		// flip the DEFAULT is true, so reaching this branch means the user
+		// closed the surface via config — the message points back at the knob.
 		if (this.options.nestingEnabled !== true) {
 			this.recordDelegateEvent(loaded.manifest, "delegate.rejected", conn.taskId, {
 				reason: "nesting-disabled",
-				policy: "nesting.enabled=false (fail-closed default)",
+				policy: "nesting.enabled=false (user config; default is true since D8)",
 			});
 			this.sendError(
 				conn,
 				id,
 				"policy-disabled",
-				"delegate is disabled: nesting.enabled=false (fail-closed default; delegate.rejected recorded in events.jsonl)",
+				"delegate is disabled: nesting.enabled=false (set nesting.enabled=true in user config; delegate.rejected recorded in events.jsonl)",
 			);
 			return;
 		}
@@ -1453,8 +1670,7 @@ export class CrewBroker {
 					t.cwd === task.cwd,
 			).length;
 			const decision = evaluateDelegateAdmission({
-				nestingEnabled: true, // flag already checked above
-				maxDepth: this.options.nestingMaxDepth ?? resolveCrewMaxDepth(undefined), // config knob > env-clamped 1..10, default 2 (ADR-5 §3)
+				maxDepth: this.options.nestingMaxDepth ?? resolveCrewMaxDepth(undefined), // config knob > env-clamped 1..10, default 4 (D8; ADR-5 §3)
 				parentTask: {
 					taskId: parentTaskId,
 					role: task.role,
@@ -1995,6 +2211,9 @@ interface MsgSendParams {
 	kind?: MailboxMessageKind;
 	priority?: MailboxMessagePriority;
 	replyTo?: string;
+	/** Task 5b (§15.2): short subject echoed into the worker.message wake
+	 * event (bounded like the tool-side MSG_SUBJECT_MAX_CHARS). */
+	subject?: string;
 }
 
 function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
@@ -2006,7 +2225,7 @@ function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
 	if (typeof to === "string" && to.length === 0) return undefined;
 	if (v.body === undefined) return undefined;
 	const kind = v.kind as MailboxMessageKind | undefined;
-	if (kind !== undefined && !["message", "steer", "follow-up", "response", "group_join"].includes(kind)) {
+	if (kind !== undefined && !["message", "notify", "steer", "follow-up", "response", "group_join"].includes(kind)) {
 		return undefined;
 	}
 	const priority = v.priority as MailboxMessagePriority | undefined;
@@ -2014,7 +2233,8 @@ function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
 		return undefined;
 	}
 	const replyTo = typeof v.replyTo === "string" ? v.replyTo : undefined;
-	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo };
+	const subject = typeof v.subject === "string" && v.subject.length > 0 && v.subject.length <= 256 ? v.subject : undefined;
+	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo, subject };
 }
 
 interface MsgInboxParams {

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -237,6 +237,13 @@ export function buildFinalChildPiSpawnOptions(
 export interface SpawnContext {
 	/** The command + args returned by getPiSpawnCommand. */
 	spawnSpec: ReturnType<typeof getPiSpawnCommand>;
+	/**
+	 * RAW worker argv as produced by buildPiWorkerArgs (BEFORE any binary/script
+	 * wrapping) — the surface spawn branch re-resolves the command line after
+	 * stripping `--mode json -p` (spec §5.2: surface variant differs ONLY in run
+	 * mode), so it needs the untouched argument list.
+	 */
+	builtArgs: string[];
 	/** The merged env (process.env + built.env) to pass to spawn(). */
 	mergedEnv: NodeJS.ProcessEnv;
 	/** Temp dir created by buildPiWorkerArgs (caller must clean up after spawn). */
@@ -288,15 +295,21 @@ export function prepareSpawnContext(
 	// design (S-6), which would leave the ask tool dead-on-arrival there.
 	// Control-namespace keys → pass assertOnlyControlEnvKeys.
 	built.env.PI_CREW_ASK_ENABLED = "1"; // dormant gate (worker conditional registerTool)
-	// T3/R5 (ADR-5 §1): the worker-side `delegate` tool is registered ONLY for
-	// executor-class roles at depth 1 (read-only roles are spawn-denied
-	// server-side anyway — the env gate is UX/dead-weight hygiene, not the
-	// security boundary; broker admission re-checks role+depth from the task
-	// RECORD). Control-namespace key → assertOnlyControlEnvKeys.
-	const childDepth = Number(built.env.PI_CREW_DEPTH ?? "1");
-	if (childDepth <= 1 && (input.role === "executor" || input.role === "test-engineer")) {
-		built.env.PI_CREW_DELEGATE_ENABLED = "1";
-	}
+	// D9/§15.2: the worker-side `message` tool env is UNCONDITIONAL for EVERY
+	// role and depth, like ask/delegate. The env gate is UX/hygiene, NOT the
+	// security boundary: the broker re-checks `from` (always the authenticated
+	// taskId) + `to` (parent/sibling/group) + kind (notify|message) from the
+	// connection identity, so an env flag alone cannot forge a sender.
+	// Control-namespace key → assertOnlyControlEnvKeys.
+	built.env.PI_CREW_MSG_ENABLED = "1"; // dormant gate (worker conditional registerTool)
+	// T3/R5 (ADR-5 §1, D8): the worker-side `delegate` tool env is now
+	// UNCONDITIONAL for EVERY role and depth — read-only/analyst roles get the
+	// tool too. The env gate is UX/hygiene, NOT the security boundary:
+	// broker admission re-checks depth + nested-slot budget from the task
+	// RECORD (spawn-policy.ts), and the spawn-side checkCrewDepth cap stops
+	// depth ≥ maxDepth children from even starting. Control-namespace key →
+	// assertOnlyControlEnvKeys.
+	built.env.PI_CREW_DELEGATE_ENABLED = "1"; // dormant gate (worker conditional registerTool)
 	// stateRoot from the spawn manifest: ChildPiRunInput threads
 	// manifest.eventsPath unconditionally (child-executor / background-runner)
 	// and the state store pins eventsPath === <stateRoot>/events.jsonl
@@ -386,6 +399,7 @@ export function prepareSpawnContext(
 		kind: "ready",
 		ctx: {
 			spawnSpec,
+			builtArgs: built.args,
 			mergedEnv: { ...process.env, ...built.env },
 			tempDir: built.tempDir,
 			builtEnv: built.env,

package/src/runtime/child-pi/child-pi-streams.ts

@@ -69,7 +69,15 @@ function compactContentPart(part: unknown): unknown | undefined {
 	return undefined;
 }
 
-function compactChildPiEvent(event: unknown): unknown | undefined {
+/**
+ * Compact one child-pi JSON event into the bounded record shape stored in
+ * agent transcripts / per-agent event logs. Shared by TWO producers that must
+ * stay byte-compatible (the consumer, agent-transcript.ts, parses both):
+ *   1. the host-side stdout funnel (headless workers), and
+ *   2. the worker-side surface recorder (S2-T8 — surface panes have no
+ *      stdout JSON stream, so the worker records its own events).
+ */
+export function compactChildPiEvent(event: unknown): unknown | undefined {
 	const record = asRecord(event);
 	if (!record) return undefined;
 	if (record.type === "message_update") return undefined;