pi-crew 0.10.2 → 0.10.4

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

@@ -25,15 +25,8 @@ import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
 import * as net from "node:net";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
-import {
-	appendMailboxMessageAsync,
-	type MailboxMessage,
-	type MailboxMessageKind,
-	type MailboxMessagePriority,
-	readMailbox,
-	registerMailboxAppendObserver,
-} from "../../state/coordination/mailbox.ts";
-import { appendEventAsync, readEventsCursor } from "../../state/event-log/event-log.ts";
+import { appendMailboxMessageAsync, type MailboxMessage, registerMailboxAppendObserver } from "../../state/coordination/mailbox.ts";
+import { appendEventAsync } 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 { runEventBus } from "../../ui/run-event-bus.ts";
@@ -42,103 +35,55 @@ import { BrokerError, encodeBrokerFrame, MAX_BROKER_FRAME_BYTES, NdjsonDecoder }
 import { redactSecretString } from "../../utils/redaction.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import { getBrokerSocketPath, prepareBrokerSocketDir, removeStaleBrokerSocket } from "../../utils/socket-path.ts";
-import { type GrandchildSpawnInput, type GrandchildSpawnResult, spawnDelegateGrandchild } from "../delegate-spawn.ts";
+import { type GrandchildSpawnResult, spawnDelegateGrandchild } from "../delegate-spawn.ts";
 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 { recordDelegateEvent } from "./delegate/delegate-event.ts";
+import { fanoutMailboxMessage } from "./mailbox-observer/mailbox-fanout.ts";
+import type { CrewBrokerOptions, ServerConnection } from "./protocol/connection-state.ts";
+import { handleEventsSince } from "./protocol/events-replay.ts";
+import { loadRunForHello } from "./protocol/manifest-loader.ts";
+import { handleMsgInbox } from "./protocol/msg-inbox.ts";
+import {
+	BROKER_PROTOCOL,
+	isHelloParams,
+	isRequestObject,
+	parseMsgSendParams,
+	parseWaitRequestParams,
+	parseWaitResolveParams,
+	safeStringify,
+	WAIT_REQUEST_TIMEOUT_SEC_DEFAULT,
+	WAIT_REQUEST_TIMEOUT_SEC_MAX,
+} from "./protocol/request-parsers.ts";
+import { recordWaitPolicyRejection, waitAuthError } from "./protocol/wait-auth.ts";
 import { WaitStatusCache } from "./wait-status-cache.ts";
 
-/** Protocol version negotiated at `hello` time. Bump on breaking change. */
-const BROKER_PROTOCOL = 1;
+/** Protocol version negotiated at `hello` time. Bump on breaking change.
+ * (Re-export removed 2026-09-10 — zero consumers; defined + exported in
+ * request-parsers.ts.) */
 
 /** Hard hello deadline (per spec). After 1s, the connection is closed with a
- *  generic auth/protocol code. */
+ *  generic auth/protocol code. (Unexported 2026-09-10 — zero consumers.) */
 const HELLO_DEADLINE_MS = 1_000;
 
-/** Default per-connection outbound queue cap (events). */
-const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
+/** Per-connection server-side state.
+ *  Moved to ./protocol/connection-state.ts (M4 / WI-4.1):
+ *   - interface CrewBrokerOptions
+ *   - interface ServerConnection
+ *  Both re-exported from connection-state.ts; the class body is unchanged.
+ */
 
-export interface CrewBrokerOptions {
-	/** Root session ID used to derive the socket path. */
-	sessionId: string;
-	/** Pre-resolved socket path (skips re-derivation; useful for tests). */
-	socketPath?: string;
-	/** Frame cap in UTF-8 bytes. Default 256 KiB. */
-	maxFrameBytes?: number;
-	/** Per-connection outbound queue cap. Default 256. */
-	outboundQueueCap?: number;
-	/** Required: when false, start() is a no-op and the server never binds.
-	 *  Lets the lifecycle controller install the broker unconditionally and
-	 *  have a single kill switch. */
-	enabled: boolean;
-	/** CWD for `loadRunManifestById` (Phase 1 msg.send / msg.inbox resolution).
-	 *  When omitted, manifest-touching methods return no-manifest errors. */
-	cwd?: string;
-	/** Optional test seam: override the `net` module (allows fake-server tests). */
-	netModule?: typeof net;
-	/** Optional test seam: inject a pre-configured WaitStatusCache (e.g. one
-	 *  wrapping a loader spy). Production uses a plain cache — see
-	 *  wait-status-cache.ts (R10-3). */
-	waitStatusCache?: WaitStatusCache;
-	/** WP-2/R2 (ADR-0 2026-08-17-waiting-producer-ask item 7): capability
-	 *  gate for the `wait.*` methods. DEFAULT FALSE — fail-closed. When not
-	 *  explicitly true, wait.request/wait.resolve are rejected with a
-	 *  `policy-disabled` error AND a `policy.action` event is appended to the
-	 *  run's events.jsonl (never silent). The production wiring threads
-	 *  `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). */
-	nestingEnabled?: boolean;
-	/** Optional override for the nested-slot budget size (config nesting.maxSlots). */
-	nestingMaxSlots?: number;
-	nestingMaxDepth?: number;
-	nestingTrustedEscalation?: boolean;
-	/** Global worker semaphore size, used to size the nested-slot budget. */
-	globalWorkerSemaphore?: number;
-	/** Test seam / alternative spawner for delegate grandchildren. Production
-	 *  uses spawnDelegateGrandchild (direct runChildPi call-site, ADR-5 §2). */
-	grandchildSpawner?: (input: GrandchildSpawnInput) => Promise<GrandchildSpawnResult>;
-	/** Resolved model catalog (canonical provider/id strings) for admission-time
-	 *  model validation (ADR-5 §7). When omitted, model validation is skipped
-	 *  (documented gap — the production wiring must always supply it). */
-	modelCatalog?: () => string[] | undefined;
-	/** ADR-5 §9: mirrors config limits.serializeOnPathOverlap for the workspace
-	 *  admission gate. Default false. */
-	serializeOnPathOverlap?: boolean;
-}
+/** 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"]);
 
-/** Per-connection server-side state. */
-interface ServerConnection {
-	socket: net.Socket;
-	decoder: NdjsonDecoder;
-	/** Whether the connection has completed `hello` successfully. */
-	authed: boolean;
-	/** Run id bound by hello. */
-	runId?: string;
-	/** Task id bound by hello. */
-	taskId?: string;
-	/** Role bound by hello: orchestrator can steer/msg-send; workers default. */
-	role?: "orchestrator" | "worker";
-	/** How the hello token matched the registry (ADR-0 item 6). Derived,
-	 *  non-secret metadata recorded at hello time so `wait.*` can reject a
-	 *  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";
-	/** Outbound queue of encoded frames awaiting drain. */
-	outbound: Buffer[];
-	/** Set when the queue has hit the cap and a frame was dropped. */
-	needsResync: boolean;
-	/** Set when the connection is closing (idempotent). */
-	closed: boolean;
-	/** Timer for the hello deadline. */
-	helloTimer: NodeJS.Timeout | null;
-	/** Monotonic seq counter for outbound events (diagnostic). */
-	outboundSeq: number;
-}
+/** Default per-connection outbound queue cap (events). */
+const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
 
 export class CrewBroker {
 	private readonly options: Required<Pick<CrewBrokerOptions, "sessionId" | "enabled" | "waitMethodsEnabled" | "nestingEnabled">> &
@@ -159,6 +104,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 +187,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 +385,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.
@@ -433,9 +408,7 @@ export class CrewBroker {
 		this.resolvedSocketPath = null;
 	}
 
-	// ------------------------------------------------------------------------
 	// Connection lifecycle
-	// ------------------------------------------------------------------------
 
 	private async handleConnection(sock: net.Socket): Promise<void> {
 		// B1 (Round 14): a connection event queued after stop() must not be
@@ -538,30 +511,11 @@ export class CrewBroker {
 	}
 
 	/**
-	 * Phase 1.3: push a durable-appended mailbox message to any connected
-	 * recipient for the message's run. Best-effort — silently skips
-	 * recipients that are offline (they recover via msg.inbox). Never throws.
+	 * Phase 1.3: see ./mailbox-observer/mailbox-fanout.ts (M4 / WI-4.1 moved).
+	 * Class method delegates with 1-line binding of connectionsByRun + writers.
 	 */
 	private fanoutMailboxMessage(msg: MailboxMessage): void {
-		const set = this.connectionsByRun.get(msg.runId);
-		if (!set || set.size === 0) return;
-		// Recipient delivery dedup lives in src/prompt/prompt-runtime.ts and is
-		// keyed by the same message id in this mailbox event and the steering JSONL.
-		const eventFrame = encodeBrokerFrame({
-			event: "mailbox.message",
-			data: { id: msg.id, from: msg.from, to: msg.to, body: msg.body, kind: msg.kind, priority: msg.priority },
-			seq: 0, // mailbox messages don't carry a TeamEvent seq; dedup by msg.id
-		});
-		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;
-			try {
-				this.writeOrQueue(conn, eventFrame, false);
-			} catch {
-				/* a slow/dead recipient must not break fanout to others */
-			}
-		}
+		fanoutMailboxMessage(this.connectionsByRun, { writeOrQueue: (conn, buf, force) => this.writeOrQueue(conn, buf, force) }, msg);
 	}
 
 	private async handleData(conn: ServerConnection, chunk: Buffer): Promise<void> {
@@ -604,6 +558,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 +652,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 = loadRunForHello(this.options.cwd, 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 = loadRunForHello(this.options.cwd, 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 +711,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,9 +734,14 @@ 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). */
+	// loadRunForHello: inlined at the 2 call sites (was a 5-line method; M4/WI-4.1).
+
 	// Outbound queue + drop-newest + needsResync
-	// ------------------------------------------------------------------------
 
 	private sendResult(conn: ServerConnection, id: string, result: unknown): void {
 		this.enqueueFrame(conn, { id, result });
@@ -813,25 +832,35 @@ export class CrewBroker {
 		}
 	}
 
-	// ------------------------------------------------------------------------
 	// Phase 1: msg.send + msg.inbox handlers
-	// ------------------------------------------------------------------------
 
 	/** 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,136 +885,150 @@ 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",
 		});
 	}
 
-	/** Phase 1.2: paginated inbox pull for the authenticated run/task. */
+	/** Phase 1.2: paginated inbox pull — see ./protocol/msg-inbox.ts
+	 * (M4 / WI-4.1 moved; label corrected 2026-09-10: Phase 1.1 = msg.send). */
 	private async handleMsgInbox(conn: ServerConnection, id: string, params: unknown): Promise<void> {
-		if (!conn.runId) {
-			this.sendError(conn, id, "auth", "not authed");
-			return;
-		}
-		const parsed = parseMsgInboxParams(params);
-		if (!parsed) {
-			this.sendError(conn, id, "bad-params", "msg.inbox: invalid params");
-			return;
-		}
-		const cwd = this.options.cwd;
-		if (!cwd) {
-			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
-			return;
-		}
-		let manifest: Parameters<typeof readMailbox>[0];
-		try {
-			const loaded = loadRunManifestById(cwd, conn.runId);
-			if (!loaded) {
-				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
-				return;
-			}
-			manifest = loaded.manifest;
-		} catch (err) {
-			this.sendError(conn, id, "no-manifest", (err as Error).message);
-			return;
-		}
-		const limit = Math.min(Math.max(parsed.limit ?? 100, 1), 1000);
-		const taskId = conn.taskId ?? undefined;
-		const all = readMailbox(manifest, "inbox", taskId);
-		const filtered = all.filter((m) => m.status !== "acknowledged");
-		const offset = parsed.cursor ? parseInt(parsed.cursor, 10) || 0 : 0;
-		const page = filtered.slice(offset, offset + limit);
-		const nextOffset = offset + page.length;
-		const hasMore = nextOffset < filtered.length;
-		this.sendResult(conn, id, {
-			messages: page,
-			nextCursor: hasMore ? String(nextOffset) : undefined,
-			hasMore,
-			total: filtered.length,
-		});
+		await handleMsgInbox(
+			conn,
+			id,
+			params,
+			{
+				sendError: (c, i, code, msg) => this.sendError(c, i, code, msg),
+				sendResult: (c, i, r) => this.sendResult(c, i, r),
+			},
+			this.options.cwd,
+		);
 	}
 
-	/**
-	 * Phase 1.5: events.since — bounded replay of structured events with seq >
-	 * sinceSeq from the durable log. Used by clients to resync after a missed
-	 * live frame (e.g. after a queue overflow or reconnect). Reuses the same
-	 * readEventsCursor + seq semantics as runEventBus.onWithReplay.
-	 */
+	/** Phase 1.5: events.since — bounded replay; clients resync after a missed
+	 * live frame (queue overflow / reconnect). See ./protocol/events-replay.ts
+	 * (M4 / WI-4.1 moved; Phase 2 = events.subscribe, not this). */
 	private async handleEventsSince(conn: ServerConnection, id: string, params: unknown): Promise<void> {
-		if (!conn.runId) {
-			this.sendError(conn, id, "auth", "not authed");
-			return;
-		}
-		const cwd = this.options.cwd;
-		if (!cwd) {
-			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
-			return;
-		}
-		let eventsPath: string;
-		try {
-			const loaded = loadRunManifestById(cwd, conn.runId);
-			if (!loaded) {
-				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
-				return;
-			}
-			eventsPath = loaded.manifest.eventsPath;
-		} catch (err) {
-			this.sendError(conn, id, "no-manifest", (err as Error).message);
-			return;
-		}
-		const v = params && typeof params === "object" && !Array.isArray(params) ? (params as Record<string, unknown>) : {};
-		const sinceSeq = typeof v.sinceSeq === "number" && Number.isFinite(v.sinceSeq) ? Math.max(0, Math.floor(v.sinceSeq)) : 0;
-		const limit = typeof v.limit === "number" && Number.isFinite(v.limit) ? Math.min(Math.max(1, Math.floor(v.limit)), 1000) : 1000;
-		try {
-			const result = readEventsCursor(eventsPath, { sinceSeq, limit });
-			// hasMore is true iff the total filtered count exceeds the page we
-			// returned. When `total === events.length` we are at the exact end
-			// of the stream (caller will discover this on the next call when
-			// `nextSeq` is unchanged from `sinceSeq`).
-			const hasMore = result.total > result.events.length;
-			this.sendResult(conn, id, {
-				events: result.events,
-				nextSeq: result.nextSeq,
-				hasMore,
-			});
-		} catch (err) {
-			this.sendError(conn, id, "replay-failed", (err as Error).message);
-		}
+		await handleEventsSince(
+			conn,
+			id,
+			params,
+			{
+				sendError: (c, i, code, msg) => this.sendError(c, i, code, msg),
+				sendResult: (c, i, r) => this.sendResult(c, i, r),
+			},
+			this.options.cwd,
+		);
 	}
 
 	/**
@@ -1295,39 +1338,19 @@ export class CrewBroker {
 		}
 	}
 
-	// ------------------------------------------------------------------------
 	// WP-2/R2: wait.request / wait.resolve (ADR-0 2026-08-17-waiting-producer-ask)
-	// ------------------------------------------------------------------------
 
-	/** Shared auth for wait.*: worker role + task-scoped (compound-key) token
-	 *  ONLY (ADR item 6). A legacy bare-runId fallback match is REJECTED with
-	 *  a migrate hint; the orchestrator token is rejected by role. Returns the
-	 *  error to send, or null when auth passes. */
+	// waitAuthError: protocol/wait-auth.ts (M4/WI-4.1).
 	private waitAuthError(conn: ServerConnection): { code: string; message: string } | null {
-		if (conn.role !== "worker" || conn.authMatchKind === undefined) {
-			return { code: "forbidden", message: "wait.* requires a worker task-scoped token" };
-		}
-		if (conn.authMatchKind !== "compound") {
-			return {
-				code: "forbidden",
-				message: "wait.* requires a task-scoped token; re-dispatch with PI_CREW_BROKER_TASK_ID",
-			};
-		}
-		return null;
+		return waitAuthError(conn);
 	}
 
-	/** ADR item 7: a disabled-gate rejection MUST leave a durable trace in
-	 *  events.jsonl — the gate fails CLOSED but never SILENTLY. Fire-and-forget
-	 *  async append (broker handlers must not block the event loop on the sync
-	 *  event-log lock); an append failure is logged, never thrown. */
+	// (The "ADR item 7" doc that used to dangle here documents
+	// recordWaitPolicyRejection — see wait-auth.ts, where it belongs.
+	// Removed 2026-09-10, review F6.)
 	// T3/R5 (ADR-5): delegate.request — governed-nesting admission + background
 	// grandchild spawn with durable mailbox delivery (WP-5 step 5).
-	private getDelegateNestedSlots(): NestedSlotBudget {
-		if (!this.nestedSlots) {
-			this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
-		}
-		return this.nestedSlots;
-	}
+	// getDelegateNestedSlots: inlined at 4 call sites (5-line method; M4/WI-4.1).
 
 	private recordDelegateEvent(
 		manifest: { eventsPath: string; runId: string },
@@ -1341,15 +1364,7 @@ export class CrewBroker {
 		taskId: string,
 		data: Record<string, unknown>,
 	): void {
-		void appendEventAsync(manifest.eventsPath, {
-			type,
-			runId: manifest.runId,
-			taskId,
-			message: `${type}: ${JSON.stringify(data).slice(0, 200)}`,
-			data,
-		}).catch((err) =>
-			logInternalError("crew-broker.delegate.event", err instanceof Error ? err : new Error(String(err)), `runId=${manifest.runId}`),
-		);
+		recordDelegateEvent(manifest, type, taskId, data);
 	}
 
 	private async handleDelegateRequest(conn: ServerConnection, id: string, params: unknown): Promise<void> {
@@ -1401,17 +1416,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,15 +1470,18 @@ 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,
 					...(task.depth !== undefined ? { depth: task.depth } : {}),
 					...(task.allocation !== undefined ? { allocation: task.allocation } : {}),
 				},
-				slots: this.getDelegateNestedSlots().snapshot(),
+				slots: (() => {
+					if (!this.nestedSlots)
+						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
+					return this.nestedSlots;
+				})().snapshot(),
 				requested,
 				...(effectiveCatalog !== undefined ? { modelCatalog: effectiveCatalog } : {}),
 				// ADR-5 §12: the delegate surface is an escalation — trusted only by the
@@ -1481,11 +1501,28 @@ export class CrewBroker {
 				return { code: "policy-denied" as const, message: decision.message ?? decision.reason ?? "delegate denied" };
 			}
 			// Slot acquisition INSIDE the lock (no reserve-then-race refund window).
-			if (!this.getDelegateNestedSlots().tryAcquire(subId)) {
+			if (
+				!(() => {
+					if (!this.nestedSlots)
+						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
+					return this.nestedSlots;
+				})().tryAcquire(subId)
+			) {
 				this.recordDelegateEvent(fresh.manifest, "delegate.rejected", parentTaskId, { subId, reason: "slots-exhausted" });
 				return {
 					code: "policy-denied" as const,
-					message: `delegate rejected: nested spawn budget exhausted; ${this.getDelegateNestedSlots().statusLine}`,
+					message: `delegate rejected: nested spawn budget exhausted; ${
+						(
+							() => {
+								if (!this.nestedSlots)
+									this.nestedSlots = new NestedSlotBudget(
+										this.options.globalWorkerSemaphore ?? 4,
+										this.options.nestingMaxSlots,
+									);
+								return this.nestedSlots;
+							}
+						)().statusLine
+					}`,
 				};
 			}
 			// Reserve the requested budget pessimistically (ADR-5 §5): tokensSpent
@@ -1676,7 +1713,11 @@ export class CrewBroker {
 					}
 				}
 			} finally {
-				this.getDelegateNestedSlots().release(subId);
+				(() => {
+					if (!this.nestedSlots)
+						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
+					return this.nestedSlots;
+				})().release(subId);
 			}
 			this.recordDelegateEvent(loaded.manifest, outcome.timedOut ? "delegate.timed_out" : "delegate.completed", parentTaskId, {
 				subId,
@@ -1686,16 +1727,7 @@ export class CrewBroker {
 	}
 
 	private recordWaitPolicyRejection(manifest: { eventsPath: string; runId: string }, taskId: string, method: string): void {
-		const runId = manifest.runId;
-		void appendEventAsync(manifest.eventsPath, {
-			type: "policy.action",
-			runId,
-			taskId,
-			message: `${method} rejected: waitMethodsEnabled=false (fail-closed)`,
-			data: { action: method, reason: "wait-methods-disabled", policy: "broker.waitMethodsEnabled=false" },
-		}).catch((err) =>
-			logInternalError("crew-broker.wait.policy-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
-		);
+		recordWaitPolicyRejection(manifest, taskId, method);
 	}
 
 	/** WP-2/R2 step 4: park the calling task while its `ask` tool awaits a
@@ -1954,155 +1986,14 @@ export class CrewBroker {
 // Type guards (no `any`)
 // ============================================================================
 
-function isRequestObject(value: unknown): value is { id: string; method: string; params: unknown } {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const v = value as Record<string, unknown>;
-	if (typeof v.id !== "string" || v.id.length === 0 || v.id.length > 256) return false;
-	if (typeof v.method !== "string" || v.method.length === 0 || v.method.length > 64) return false;
-	// Method names are restricted to a small safe charset. This guards against
-	// odd inputs (control chars, very long names) reaching the dispatcher.
-	if (!/^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/.test(v.method)) return false;
-	// params may be anything (validated per-method), but not undefined-shaped.
-	return "params" in v;
-}
-
-function isHelloParams(value: unknown): value is {
-	protocol: number;
-	runId: string;
-	taskId: string;
-	token: string;
-	role?: string;
-} {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const v = value as Record<string, unknown>;
-	if (v.protocol !== BROKER_PROTOCOL) {
-		// Force exact-type comparison (must be the number 1, not "1").
-		if (typeof v.protocol !== "number" || !Number.isInteger(v.protocol)) return false;
-	}
-	if (typeof v.runId !== "string" || v.runId.length === 0 || v.runId.length > 256) return false;
-	if (typeof v.taskId !== "string" || v.taskId.length === 0 || v.taskId.length > 256) return false;
-	if (typeof v.token !== "string" || v.token.length === 0 || v.token.length > 256) return false;
-	return true;
-}
-
-// ============================================================================
-// Phase 1 parameter parsers (module-level; no `any`)
-// ============================================================================
-
-interface MsgSendParams {
-	to: string | string[] | "all";
-	body: unknown;
-	kind?: MailboxMessageKind;
-	priority?: MailboxMessagePriority;
-	replyTo?: string;
-}
-
-function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const v = value as Record<string, unknown>;
-	const to = v.to;
-	if (typeof to !== "string" && !Array.isArray(to)) return undefined;
-	if (Array.isArray(to) && !to.every((s) => typeof s === "string" && s.length > 0)) return 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)) {
-		return undefined;
-	}
-	const priority = v.priority as MailboxMessagePriority | undefined;
-	if (priority !== undefined && !["urgent", "normal", "low"].includes(priority)) {
-		return undefined;
-	}
-	const replyTo = typeof v.replyTo === "string" ? v.replyTo : undefined;
-	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo };
-}
-
-interface MsgInboxParams {
-	limit?: number;
-	cursor?: string;
-}
-
-function parseMsgInboxParams(value: unknown): MsgInboxParams | undefined {
-	if (value === undefined || value === null) return { limit: 100, cursor: undefined };
-	if (typeof value !== "object" || Array.isArray(value)) return undefined;
-	const v = value as Record<string, unknown>;
-	const limit = v.limit;
-	if (limit !== undefined && (typeof limit !== "number" || !Number.isFinite(limit) || limit < 1)) {
-		return undefined;
-	}
-	const cursor = v.cursor;
-	if (cursor !== undefined && typeof cursor !== "string") return undefined;
-	return { limit: limit as number | undefined, cursor: cursor as string | undefined };
-}
-
-function safeStringify(value: unknown): string {
-	try {
-		return JSON.stringify(value) ?? "{}";
-	} catch {
-		return "{}";
-	}
-}
-
-// ============================================================================
-// WP-2/R2 wait.* parameter parsers (ADR-0 2026-08-17-waiting-producer-ask)
-// ============================================================================
-
-/** Server-side ceiling for the ask deadline (ADR P2-7): worker-controlled
- *  timeoutSec may NEVER exceed 1h — an unbounded timeout would pin slots and
- *  amplify I/O. Applied as deadline = now + min(timeoutSec, 3600). */
-const WAIT_REQUEST_TIMEOUT_SEC_MAX = 3600;
-/** Default ask timeout when the caller omits timeoutSec (ADR item 1). */
-const WAIT_REQUEST_TIMEOUT_SEC_DEFAULT = 600;
-/** Bounded question payload (defense-in-depth under the 256 KiB frame cap). */
-const WAIT_QUESTION_MAX_CHARS = 8192;
-/** Bounded answer-choice list: at most 16 options, 256 chars each. */
-const WAIT_OPTIONS_MAX = 16;
-const WAIT_OPTION_MAX_CHARS = 256;
-
-interface WaitRequestParams {
-	to: string;
-	question: string;
-	options?: string[];
-	timeoutSec?: number;
-}
-
-function parseWaitRequestParams(value: unknown): WaitRequestParams | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const v = value as Record<string, unknown>;
-	if (typeof v.to !== "string" || v.to.length === 0 || v.to.length > 256) return undefined;
-	if (typeof v.question !== "string" || v.question.length === 0 || v.question.length > WAIT_QUESTION_MAX_CHARS) {
-		return undefined;
-	}
-	let options: string[] | undefined;
-	if (v.options !== undefined) {
-		if (!Array.isArray(v.options) || v.options.length === 0 || v.options.length > WAIT_OPTIONS_MAX) return undefined;
-		for (const o of v.options) {
-			if (typeof o !== "string" || o.length === 0 || o.length > WAIT_OPTION_MAX_CHARS) return undefined;
-		}
-		options = v.options as string[];
-	}
-	// timeoutSec is clamped server-side in the handler (max 3600); the parser
-	// only rejects non-finite values. Non-positive values clamp to 1s.
-	if (v.timeoutSec !== undefined && (typeof v.timeoutSec !== "number" || !Number.isFinite(v.timeoutSec))) {
-		return undefined;
-	}
-	return {
-		to: v.to,
-		question: v.question,
-		options,
-		timeoutSec: v.timeoutSec as number | undefined,
-	};
-}
-
-interface WaitResolveParams {
-	to: string;
-	questionId: string;
-}
-
-function parseWaitResolveParams(value: unknown): WaitResolveParams | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const v = value as Record<string, unknown>;
-	if (typeof v.to !== "string" || v.to.length === 0 || v.to.length > 256) return undefined;
-	if (typeof v.questionId !== "string" || v.questionId.length === 0 || v.questionId.length > 128) return undefined;
-	return { to: v.to, questionId: v.questionId };
-}
+/** Moved to ./protocol/request-parsers.ts (M4 / WI-4.1):
+ *   - isRequestObject
+ *   - isHelloParams + BROKER_PROTOCOL
+ *   - parseMsgSendParams + MsgSendParams
+ *   - parseMsgInboxParams + MsgInboxParams
+ *   - parseWaitRequestParams + WaitRequestParams
+ *   - parseWaitResolveParams + WaitResolveParams
+ *   - safeStringify
+ *   - WAIT_* constants
+ *  Removed from this file; re-exported via "./protocol/request-parsers.ts".
+ */