pi-crew 0.11.21 → 0.11.23

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

@@ -2,16 +2,25 @@
  * crew-broker-client.ts — Child-side connector for the local broker.
  *                       PHASE 0 skeleton (sub-task 0.3).
  *
- *  - Connects only on the first request/subscribe.
+ *  - Connects only on the first request/subscribe. The connect is
+ *    SINGLE-FLIGHT (H7, DR-03 round-6 2026-10-16): concurrent request()s
+ *    on a fresh client share one in-flight connectAndHello() instead of
+ *    racing N sockets into existence.
  *  - Sends `hello` first; any other method before ack is a protocol error.
  *  - Bounded backoff (50/100/200/400/800 ms + jitter, max 4 attempts).
  *    After exhaustion, no hot reconnect loop is scheduled. The only way back
  *    to the live path is an explicit `reconnect()` (or a new worker lifecycle).
  *  - On ANY connect/auth/timeout/close error, transitions to `fallback` mode
- *    and never lets an exception escape `request()` / `subscribe()`. The
- *    caller can read `client.mode` or the `{ok:false, fallback:true}` result
- *    and continue using today's file-based paths.
- *  - `close()` removes all listeners and pending requests.
+ *    and never lets an exception escape `request()`. The caller can read
+ *    `client.mode` or the `{ok:false, fallback:true}` result and continue
+ *    using today's file-based paths. (`subscribe()` is the ONE deliberate
+ *    exception — it throws "not supported" (H8) because a silent no-op
+ *    unsubscribe let callers believe they were subscribed; it has zero
+ *    production callers.)
+ *  - `close()` removes all listeners and pending requests. Any teardown of
+ *    the current socket (close/reconnect) rejects stranded pending entries
+ *    IMMEDIATELY with a typed `connection-closed` error (H8) instead of
+ *    leaving them to their request timers.
  *  - All diagnostic strings pass through `redactSecretString` from
  *    `src/utils/redaction.ts`. Token and payload bytes are never logged.
  *
@@ -112,6 +121,13 @@ export class CrewBrokerClient {
 	}> = [];
 	/** Set in close(); gates reconnect attempts and backoff loops. */
 	private closed = false;
+	/** H7: in-flight connect (single-flight). Concurrent request()s on an
+	 *  unstarted client await the SAME connectAndHello() promise instead of
+	 *  each opening its own socket (previously two concurrent first-requests
+	 *  raced two sockets; the loser's socket leaked until its hello deadline).
+	 *  Cleared on settle — success moves `mode` to "connected" and failure to
+	 *  "fallback", so a null value never masks a needed reconnect. */
+	private connecting: Promise<BrokerClientResult<true>> | null = null;
 	/** Handle to the in-flight backoff timer so close() can cancel it. */
 	private backoffTimer: NodeJS.Timeout | null = null;
 	/** Resolver for the in-flight backoff await so close() can unblock it.
@@ -171,9 +187,10 @@ export class CrewBrokerClient {
 			return { ok: false, fallback: true, errorCode: "bad-method" };
 		}
 
-		// Lazy connect + hello on first use.
+		// Lazy connect + hello on first use. H7: single-flight — concurrent
+		// requests share one connectAndHello() (one socket), not N.
 		if (this._mode === "unstarted" || !this.socket) {
-			const connectResult = await this.connectAndHello();
+			const connectResult = await this.ensureConnected();
 			if (!connectResult.ok) {
 				return connectResult;
 			}
@@ -246,18 +263,17 @@ export class CrewBrokerClient {
 	}
 
 	/**
-	 * Subscribe to a per-run event stream. Phase 0 does not implement
-	 * events.since — the subscription returns a no-op unsubscribe and
-	 * transitions to fallback if the connection is lost. The caller can
-	 * continue using the file poll path.
+	 * Subscribe to a per-run event stream. NOT SUPPORTED (H8, DR-03
+	 * round-6 2026-10-16): Phase 0 never implemented the event stream, and
+	 * the old silent no-op unsubscribe let a caller believe it was
+	 * subscribed while frames went nowhere. Zero production callers exist,
+	 * so this now throws instead of silently misbehaving. Live frames are
+	 * available via the `onEvent` constructor option; durable resync via
+	 * `msg.inbox` / `events.since` polling.
 	 */
 	subscribe(options: { runId: string; sinceSeq: number; onEvent: (event: unknown) => void }): () => void {
-		// Phase 0: subscription is a typed not-implemented. We register a
-		// no-op unsubscribe so the caller can call it without errors.
 		void options;
-		return () => {
-			/* no-op */
-		};
+		throw new BrokerError("not-implemented", "subscribe is not supported; use onEvent / events.since polling");
 	}
 
 	/**
@@ -331,6 +347,19 @@ export class CrewBrokerClient {
 	// Connect + hello with bounded backoff
 	// ------------------------------------------------------------------------
 
+	/** H7: single-flight wrapper around connectAndHello. The first caller
+	 *  creates the in-flight promise; concurrent callers await the same one.
+	 *  Settled promises are dropped so a later reconnect() (explicit
+	 *  `unstarted` reset) starts a genuinely fresh connect. */
+	private ensureConnected(): Promise<BrokerClientResult<true>> {
+		if (!this.connecting) {
+			this.connecting = this.connectAndHello().finally(() => {
+				this.connecting = null;
+			});
+		}
+		return this.connecting;
+	}
+
 	private async connectAndHello(): Promise<BrokerClientResult<true>> {
 		if (!this.options.socketPath || !this.options.token) {
 			this.enterFallbackOnce("missing-credentials", new Error("socket or token not provided"));
@@ -642,6 +671,35 @@ export class CrewBrokerClient {
 	}
 
 	private teardownSocket(): void {
+		// H8: reject stranded pending entries IMMEDIATELY. A teardown means
+		// the socket they were written to is going away (close() semantics, a
+		// reconnect() replacing it, or the closed-race in connectAndHello) —
+		// their responses can never arrive on it. Leaving them to their
+		// request timers kept callers (e.g. an await inside reconnect())
+		// hanging for up to the full request timeout on a dead connection.
+		// The typed `connection-closed` error funnels into request()'s catch →
+		// {ok:false, fallback:true, errorCode:"connection-closed"}.
+		if (this.pending.size > 0) {
+			const clearTimeoutFn = this.options.clearTimeoutFn ?? ((t: NodeJS.Timeout) => clearTimeout(t));
+			for (const [, p] of this.pending) {
+				if (p.timer) {
+					try {
+						clearTimeoutFn(p.timer);
+					} catch {
+						/* best-effort */
+					}
+				}
+				p.reject(
+					// Code outside the closed BrokerErrorCode union (which lives in
+					// ndjson.ts and gates protocol responses); same cast precedent as
+					// the wire-error path in attemptHello. Surfaces to callers as
+					// errorCode "connection-closed" (BrokerClientResult.errorCode is a
+					// plain string).
+					new BrokerError("connection-closed" as never, "connection torn down before response"),
+				);
+			}
+			this.pending.clear();
+		}
 		if (!this.socket) {
 			this.socket = null;
 			this.decoder = null;

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

@@ -1,24 +1,39 @@
 /**
  * crew-broker.ts — Root-only local socket server for cross-process pi-worker
- *                  message transport. PHASE 0 skeleton (sub-task 0.4).
+ *                  message transport (grew out of the Phase 0 skeleton,
+ *                  sub-task 0.4 — see history note below).
  *
  *  - Bound to a `node:net` Unix domain socket or Windows named pipe.
  *  - One broker per root session; per-run token auth on first `hello`.
  *  - NDJSON framing, 256 KiB UTF-8 cap, 1s hello deadline.
- *  - Per-connection outbound queue cap (default 256) with drop-newest +
- *    `needsResync` marker.
- *  - Phase 0 dispatches ONLY `hello` and `ping`. All other methods return
- *    a typed `not-implemented` response (preserves forward-compat without
- *    pretending Phase 1 methods are live).
+ *  - Per-connection outbound queue cap (default 256). Fanout/event frames
+ *    are drop-newest at cap, and the drop now CLOSES the connection with a
+ *    typed `protocol.close` reason ("outbound-overflow-resync") so the
+ *    client reconnects and replays (R6-5). Request RESPONSE frames
+ *    (sendResult/sendError acks) bypass the cap — bounded by in-flight
+ *    request count, never the fanout storm.
+ *  - Dispatches 12 methods post-hello: `ping`, `hello`, `msg.send`,
+ *    `msg.inbox`, `events.since`, `events.subscribe`, `task.waitStatus`,
+ *    `steer.push`, `escalate`, `wait.request`/`wait.resolve`
+ *    (capability-gated via `options.waitMethodsEnabled`, fail-closed), and
+ *    `delegate.request` (governed-nesting grandchild spawn through
+ *    `delegate-spawn.ts`, capability-gated via `options.nestingEnabled`,
+ *    fail-closed). Unknown methods return a typed `not-implemented`.
+ *  - Mailbox/event persistence flows through the `src/state/` stores
+ *    (`appendMailboxMessage*`, event-log) — the broker itself keeps no
+ *    durable state of its own.
  *  - Token map is HEAP ONLY; cleared on `stop()`. Never serialized.
  *  - `stop()` is idempotent. Never calls `process.kill`.
  *  - All log/error scopes use `crew-broker.*` prefix; every diagnostic
  *    passes through `redactSecretString` from `src/utils/redaction.ts`.
  *
- *  NO outbound TCP. NO persistence. NO children. NO process killing.
+ *  NO outbound TCP. NO process killing.
  *
- *  See `reports/inter-pi-broker-impl-plan-2026-07-21.md` §"0.4" for the
- *  full contract and acceptance criteria.
+ *  History: the Phase 0 contract (hello/ping only, no persistence, no
+ *  children) lives in `reports/inter-pi-broker-impl-plan-2026-07-21.md` §0.4;
+ *  the 12-method surface above supersedes it. DR-01 (2026-10-14) rewrote
+ *  this header after it had drifted ~1900 LOC past the skeleton it
+ *  described.
  */
 
 import { randomUUID } from "node:crypto";
@@ -53,10 +68,12 @@ import { handleEventsSince } from "./protocol/events-replay.ts";
 import { DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS, type LockBusyOutcome, withRunLockBusyRetry } from "./protocol/lock-busy.ts";
 import { loadRunForHello } from "./protocol/manifest-loader.ts";
 import { handleMsgInbox } from "./protocol/msg-inbox.ts";
+import { resolveMsgSendTargets } from "./protocol/msg-send-targets.ts";
 import {
 	BROKER_PROTOCOL,
 	isHelloParams,
 	isRequestObject,
+	parseDelegateRequestParams,
 	parseMsgSendParams,
 	parseWaitRequestParams,
 	safeStringify,
@@ -93,6 +110,26 @@ const STALE_RUN_STATUSES: ReadonlySet<string> = new Set(["completed", "failed",
 /** Default per-connection outbound queue cap (events). */
 const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
 
+/** R6-5 (2026-10-16): typed protocol close-reason sent as a best-effort
+ *  `protocol.close` event frame (direct write, jumps the saturated queue)
+ *  before the connection is closed after a fanout/event frame was dropped
+ *  at the queue cap. Clients observe the reason, reconnect, and replay via
+ *  `events.since` (Phase 1.5). */
+export const OUTBOUND_OVERFLOW_RESYNC_CLOSE_REASON = "outbound-overflow-resync";
+
+/** R6-5: admission class for an outbound frame.
+ *  - `false`  — fanout/event class: drop-newest at cap → resync close.
+ *  - `true`   — close-reason class: bypass the cap, attempt an immediate
+ *    direct write (existing `sendErrorAndClose` behavior).
+ *  - `"response"` — request-response class (sendResult/sendError acks):
+ *    bypass the drop-newest cap but stay IN the queue (ordering preserved,
+ *    backpressure honored). Bounded by the client's in-flight request count
+ *    — one response frame per request — so it can never storm the way a
+ *    fanout burst can. Kept a `boolean | "response"` union (not a fresh
+ *  enum) so the external FanoutWriters interface (mailbox-fanout.ts) keeps
+ *  its `(conn, buf, force: boolean)` shape. */
+type OutboundAdmission = boolean | "response";
+
 export class CrewBroker {
 	private readonly options: Required<Pick<CrewBrokerOptions, "sessionId" | "enabled" | "waitMethodsEnabled" | "nestingEnabled">> &
 		Pick<
@@ -750,7 +787,7 @@ export class CrewBroker {
 	 *  truth for authentication). */
 	// loadRunForHello: inlined at the 2 call sites (was a 5-line method; M4/WI-4.1).
 
-	// Outbound queue + drop-newest + needsResync
+	// Outbound queue + drop-newest + resync-close (R6-5)
 
 	private sendResult(conn: ServerConnection, id: string, result: unknown): void {
 		this.enqueueFrame(conn, { id, result });
@@ -787,13 +824,27 @@ export class CrewBroker {
 			);
 			return;
 		}
-		this.writeOrQueue(conn, buf, /*force*/ false);
+		// R6-5: request responses (the acks for ping/msg.send/wait.request/…)
+		// are response-class — they bypass the drop-newest cap so a saturated
+		// fanout queue can no longer swallow an ack and leave the caller to its
+		// request-timeout (a delivered send reported "NOT sent").
+		this.writeOrQueue(conn, buf, "response");
 	}
 
-	private writeOrQueue(conn: ServerConnection, buf: Buffer, force: boolean): void {
+	private writeOrQueue(conn: ServerConnection, buf: Buffer, force: OutboundAdmission): void {
 		if (conn.closed) return;
 		const cap = this.options.outboundQueueCap ?? DEFAULT_OUTBOUND_QUEUE_CAP;
 		if (conn.outbound.length >= cap) {
+			if (force === "response") {
+				// R6-5(a): response frames queue PAST the cap instead of being
+				// drop-newest'd. Bounded: at most one response per in-flight
+				// request, and the client's request pipeline is serial — this can
+				// never grow unbounded the way a fanout burst can. Ordering is
+				// preserved (pushed at the tail; drainOutbound honors backpressure).
+				conn.outbound.push(buf);
+				this.drainOutbound(conn);
+				return;
+			}
 			if (force) {
 				// Forced sends (e.g. close-reason) bypass the cap and attempt
 				// to flush directly; if the socket is busy they may still drop.
@@ -804,13 +855,13 @@ export class CrewBroker {
 				}
 				return;
 			}
-			// Drop-newest: do NOT add the new frame, mark needsResync, and stop
-			// further live fanout for this connection. The client must reconnect
-			// and replay (Phase 1: via events.since; Phase 0: protocol error).
-			conn.needsResync = true;
-			// We do NOT revoke auth — the connection is still authenticated; we
-			// simply pause live frame production. The client is expected to
-			// notice the queue-depth and resync.
+			// R6-5(b): fanout/event frame dropped at cap (drop-newest). The old
+			// `needsResync` marker was write-only (set, never read) — the claimed
+			// "pause + client notices" recovery did not exist, so live frames
+			// were silently dropped for the connection's remaining lifetime.
+			// Now the drop CLOSES the connection with a typed close-reason so
+			// the client reconnects and replays (events.since / msg.inbox).
+			this.handleOutboundOverflow(conn);
 			return;
 		}
 		conn.outbound.push(buf);
@@ -841,6 +892,33 @@ export class CrewBroker {
 		}
 	}
 
+	/** R6-5(b): a fanout/event frame was dropped at the outbound queue cap.
+	 *  Close the connection with a typed protocol close-reason so the client
+	 *  can reconnect + replay instead of silently missing live frames
+	 *  forever. The reason frame is written DIRECTLY (jumps the saturated
+	 *  queue — those frames are already doomed once we close) and delivery
+	 *  is best-effort, exactly like `sendErrorAndClose`. */
+	private handleOutboundOverflow(conn: ServerConnection): void {
+		// Single-flight: fanoutMailboxMessage iterates a snapshot of the run's
+		// connections, so one burst can re-enter here for an already-overflowing
+		// conn before `closeConnection`'s `closed` guard becomes visible. The
+		// flag is the "close already initiated" bit (its only read).
+		if (conn.needsResync) return;
+		conn.needsResync = true;
+		logInternalError(
+			"crew-broker.outbound.overflow",
+			new Error("outbound queue overflow — closing connection for resync"),
+			`sessionId=${this.options.sessionId} runId=${conn.runId ?? "?"} queued=${conn.outbound.length} seq=${conn.outboundSeq}`,
+		);
+		try {
+			const buf = encodeBrokerFrame({ event: "protocol.close", data: { reason: OUTBOUND_OVERFLOW_RESYNC_CLOSE_REASON } });
+			conn.socket.write(buf);
+		} catch {
+			/* socket may be dead; closeConnection below sweeps regardless */
+		}
+		this.closeConnection(conn);
+	}
+
 	// Phase 1: msg.send + msg.inbox handlers
 
 	/** Phase 1.1: direct or broadcast mailbox write via the durable append path. */
@@ -894,67 +972,25 @@ export class CrewBroker {
 			this.sendError(conn, id, "no-manifest", (err as Error).message);
 			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 }));
+		// ── Recipient resolution: pure D9/§15.2 matrix in protocol/msg-send-targets.ts (wc-gate).
+		const resolved = resolveMsgSendTargets({ isWorker, connTaskId: conn.taskId, to: parsed.to, taskIds });
+		if (!resolved.ok) {
+			this.sendError(conn, id, resolved.code, resolved.message);
+			return;
 		}
+		const { targets, sentToParent } = resolved;
 		const messageId = `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 		const fromField = isWorker ? conn.taskId! : (conn.taskId ?? conn.runId);
-		// U5 (2026-10-10): every send carries a unique requestId — client-supplied
-		// (idempotent retries reuse the SAME one) or broker-generated
-		// `{runId}:{sender}:{uuid}`. The durable (direction, requestId) index in
-		// delivery.json + the idempotent append below make resend-after-resume a
-		// no-op instead of a duplicate delivery.
+		// U5: every send carries a unique requestId — client-supplied (idempotent
+		// retries reuse the SAME one) or broker-generated. The durable
+		// (direction, requestId) index makes resend-after-resume a no-op.
 		const requestId = parsed.requestId ?? `${manifest.runId}:${fromField}:${randomUUID()}`;
 		let dedupedRecipients = 0;
 		let durable = false;
 		try {
-			// 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.
+			// PERF: to:"all" with 50 tasks used to run 50 sequential awaited locked
+			// appends while the connection's frames queued behind it. Chunked
+			// fan-out — independent mailbox files append concurrently.
 			const CHUNK = 8;
 			for (let i = 0; i < targets.length; i += CHUNK) {
 				const results = await Promise.allSettled(
@@ -985,10 +1021,9 @@ export class CrewBroker {
 			this.sendError(conn, id, "durable-failed", (err as Error).message);
 			return;
 		}
-		// U5: one bounded audit event per send — requestId + dedup count make the
-		// exactly-once chain auditable end-to-end (mailbox.send → worker
-		// mailbox.pickup → mailbox.pickup_deduped). Never the body. Failure is
-		// non-fatal: the mailbox rows are the source of truth.
+		// U5: one bounded audit event per send — requestId + dedup count make
+		// the exactly-once chain auditable. Never the body; mailbox rows are
+		// the source of truth.
 		try {
 			await appendEventAsync(manifest.eventsPath, {
 				type: "mailbox.send",
@@ -1421,28 +1456,16 @@ export class CrewBroker {
 			this.sendError(conn, id, "forbidden", "delegate requires a task-scoped token; re-dispatch with PI_CREW_BROKER_TASK_ID");
 			return;
 		}
-		const p = (params ?? {}) as {
-			description?: unknown;
-			prompt?: unknown;
-			role?: unknown;
-			model?: unknown;
-			maxTurns?: unknown;
-			budgetTokens?: unknown;
-			timeoutSec?: unknown;
-		};
-		if (typeof p.prompt !== "string" || p.prompt.trim().length === 0) {
-			this.sendError(conn, id, "bad-params", "delegate.request: 'prompt' (non-empty string) is required");
+		// R7-H1 fix: parse params through the protocol-level parser (mirrors
+		// parseWaitRequestParams discipline) — non-integer/non-finite/negative/
+		// over-ceiling maxTurns/budgetTokens never reach admission or the
+		// budget reservation (durable-negative tokensSpent escape).
+		const parsed = parseDelegateRequestParams(params);
+		if (!parsed) {
+			this.sendError(conn, id, "bad-params", "delegate.request: invalid params");
 			return;
 		}
-		const requested = {
-			prompt: p.prompt,
-			...(typeof p.description === "string" ? { description: p.description } : {}),
-			...(typeof p.role === "string" ? { role: p.role } : {}),
-			...(typeof p.model === "string" ? { model: p.model } : {}),
-			...(typeof p.maxTurns === "number" ? { maxTurns: p.maxTurns } : {}),
-			...(typeof p.budgetTokens === "number" ? { budgetTokens: p.budgetTokens } : {}),
-			...(typeof p.timeoutSec === "number" ? { timeoutSec: p.timeoutSec } : {}),
-		};
+		const requested = parsed;
 		const cwd = this.options.cwd;
 		if (!cwd) {
 			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");

package/src/runtime/broker/protocol/msg-send-targets.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure recipient resolution for the broker's `msg.send` handler.
+ *
+ * Extracted from crew-broker.ts (DR-03 wave, wc-gate: no module over 2000
+ * lines — same precedent as live-session/usage-bridge.ts): the worker/
+ * orchestrator recipient matrices are pure functions of
+ * {role, taskId, parsed.to, taskIds} — no broker state involved.
+ *
+ * Worker constraints (D9/§15.2): from is always the authenticated taskId;
+ * to is limited to `parent` | valid sibling taskId | `group`; kind limited
+ * to notify|message (checked by the caller BEFORE resolution).
+ * Orchestrator keeps the full prior surface (arrays / "all" / arbitrary
+ * recipient sets).
+ */
+
+export type MsgSendTarget = { label: string; mailboxTaskId: string | undefined };
+
+export type MsgSendTargetResolution =
+	| { ok: true; targets: MsgSendTarget[]; sentToParent: boolean }
+	| { ok: false; code: "forbidden" | "bad-params"; message: string };
+
+/** Max recipients per send (both roles) — matches the historical inline check. */
+export const MSG_SEND_MAX_RECIPIENTS = 64;
+
+/**
+ * Resolve `parsed.to` into mailbox targets.
+ *
+ * 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).
+ * `sentToParent` is set when a worker addresses the parent — the durable
+ * write alone would sit unread in the run-level inbox (spec §15.2 wake).
+ */
+export function resolveMsgSendTargets(input: {
+	isWorker: boolean;
+	connTaskId: string | undefined;
+	to: unknown;
+	taskIds: string[];
+}): MsgSendTargetResolution {
+	const { isWorker, connTaskId, taskIds } = input;
+
+	if (isWorker) {
+		// Worker constraint (1): from is ALWAYS the authenticated taskId.
+		if (!connTaskId) {
+			return { ok: false, code: "forbidden", message: "msg.send worker requires a task-scoped identity" };
+		}
+		// Worker constraint (2): to is limited to parent | valid sibling
+		// taskId | group.
+		const to = typeof input.to === "string" ? input.to : undefined;
+		let targets: MsgSendTarget[];
+		let sentToParent = false;
+		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 {
+			return { ok: false, code: "forbidden", message: `msg.send: worker cannot target '${to}'` };
+		}
+		if (targets.length === 0 || targets.length > MSG_SEND_MAX_RECIPIENTS) {
+			return { ok: false, code: "bad-params", message: "msg.send: recipient count out of range" };
+		}
+		return { ok: true, targets, sentToParent };
+	}
+
+	const recipients: string[] = Array.isArray(input.to) ? (input.to as string[]) : input.to === "all" ? taskIds : [input.to as string];
+	if (recipients.length === 0 || recipients.length > MSG_SEND_MAX_RECIPIENTS) {
+		return { ok: false, code: "bad-params", message: "msg.send: recipient count out of range" };
+	}
+	return { ok: true, targets: recipients.map((recipient) => ({ label: recipient, mailboxTaskId: recipient })), sentToParent: false };
+}

package/src/runtime/broker/protocol/request-parsers.ts

@@ -176,6 +176,74 @@ export function parseWaitRequestParams(value: unknown): WaitRequestParams | unde
 	};
 }
 
+// ============================================================================
+// R7-H1 fix (deep-review round 8): delegate.request parameter parser.
+// Mirrors parseWaitRequestParams discipline — the handler previously spread
+// `typeof x === "number"` values straight into `requested`, so non-integer,
+// non-finite, negative and over-ceiling maxTurns/budgetTokens reached
+// admission (e.g. raw-wire -1e9 budget → durable negative tokensSpent;
+// 1e999 → Infinity maxTurns → dead child-pi turn caps).
+// ============================================================================
+
+/** Server-side ceiling for grandchild turn caps (client tool schema: 1..200). */
+export const DELEGATE_MAX_TURNS_CEILING = 200;
+/** Server-side ceiling for grandchild token budgets (client schema: <=100M). */
+export const DELEGATE_BUDGET_TOKENS_CEILING = 100_000_000;
+/** Bounded delegate prompt (defense-in-depth under the frame cap). */
+export const DELEGATE_PROMPT_MAX_CHARS = 100_000;
+
+export interface DelegateRequestParams {
+	prompt: string;
+	description?: string;
+	role?: string;
+	model?: string;
+	maxTurns?: number;
+	budgetTokens?: number;
+	timeoutSec?: number;
+}
+
+export function parseDelegateRequestParams(value: unknown): DelegateRequestParams | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const v = value as Record<string, unknown>;
+	if (typeof v.prompt !== "string" || v.prompt.trim().length === 0 || v.prompt.length > DELEGATE_PROMPT_MAX_CHARS) {
+		return undefined;
+	}
+	if (v.description !== undefined && typeof v.description !== "string") return undefined;
+	if (v.role !== undefined && !(typeof v.role === "string" && ["explorer", "analyst", "executor"].includes(v.role))) {
+		return undefined;
+	}
+	if (v.model !== undefined && typeof v.model !== "string") return undefined;
+	if (v.maxTurns !== undefined) {
+		if (typeof v.maxTurns !== "number" || !Number.isInteger(v.maxTurns) || v.maxTurns < 1 || v.maxTurns > DELEGATE_MAX_TURNS_CEILING) {
+			return undefined;
+		}
+	}
+	if (v.budgetTokens !== undefined) {
+		if (
+			typeof v.budgetTokens !== "number" ||
+			!Number.isInteger(v.budgetTokens) || // R8 lane-B correction: client Type.Integer parity (0.5/3.5 pass isFinite)
+			v.budgetTokens < 0 ||
+			v.budgetTokens > DELEGATE_BUDGET_TOKENS_CEILING
+		) {
+			return undefined;
+		}
+	}
+	// timeoutSec stays finite-only here; the 1..MAX range enforcement remains
+	// in spawn-policy §7 (evaluateDelegateAdmission).
+	if (v.timeoutSec !== undefined && (typeof v.timeoutSec !== "number" || !Number.isFinite(v.timeoutSec))) {
+		return undefined;
+	}
+	return {
+		prompt: v.prompt,
+		...(typeof v.description === "string" ? { description: v.description } : {}),
+		...(typeof v.role === "string" ? { role: v.role } : {}),
+		...(typeof v.model === "string" ? { model: v.model } : {}),
+		...(v.maxTurns !== undefined ? { maxTurns: v.maxTurns as number } : {}),
+		...(v.budgetTokens !== undefined ? { budgetTokens: v.budgetTokens as number } : {}),
+		...(v.timeoutSec !== undefined ? { timeoutSec: v.timeoutSec as number } : {}),
+	};
+}
+
 export interface WaitResolveParams {
 	to: string;
 	questionId: string;

package/src/runtime/broker/wait-status-cache.ts

@@ -119,9 +119,18 @@ export class WaitStatusCache {
 	/**
 	 * Stat-gated load. Fast path (stamp unchanged): 2 statSync calls, zero
 	 * parses. Slow path (first sight or changed mtime/size): delegate to the
-	 * loader, then record the POST-load stamp so a concurrent writer that
-	 * landed between our pre-load stat and the parse forces the next tick to
-	 * reload instead of serving a stale entry.
+	 * loader, then record the PRE-load stamp (H5, DR-03 round-6 2026-10-16).
+	 *
+	 * Why PRE-load: keying the entry on the POST-load stamp had a
+	 * parse→stat TOCTOU bug — a writer landing between the parse and the
+	 * after-stat produced an entry whose stamp was FRESH while its cached
+	 * value was STALE, and every later tick with an unchanged disk served
+	 * the stale value forever (stale-under-fresh pinning). With the PRE-load
+	 * stamp, a writer that lands anywhere between the pre-stat and the parse
+	 * leaves the entry keyed on the OLDER stamp, so the very next tick sees
+	 * the stamp change and reloads. Worst case is one spurious reload
+	 * (writer landed before the parse — the loaded value was already fresh),
+	 * never a missed one.
 	 */
 	load(cwd: string, runId: string): LoadedRun {
 		// Same path derivation as resolveRunStateRoot inside
@@ -135,13 +144,13 @@ export class WaitStatusCache {
 		}
 		const loaded = this.loader(cwd, runId);
 		this.reloadsValue += 1;
-		const after = statStamp(paths.manifestPath, paths.tasksPath);
 		if (this.entries.size >= WAIT_STATUS_CACHE_MAX && !this.entries.has(runId)) {
 			// Map preserves insertion order — evict the oldest entry.
 			const oldest = this.entries.keys().next().value;
 			if (oldest !== undefined) this.entries.delete(oldest);
 		}
-		this.entries.set(runId, { ...after, loaded });
+		// H5: key on the PRE-load stamp (`before`), NOT a post-load re-stat.
+		this.entries.set(runId, { ...before, loaded });
 		return loaded;
 	}