pi-crew 0.11.23 → 0.11.24

package/src/prompt/prompt-runtime.ts

@@ -408,6 +408,65 @@ export function shouldRegisterAskTool(env: NodeJS.ProcessEnv = process.env): boo
 
 const PI_CREW_DELEGATE_ENABLED_ENV = "PI_CREW_DELEGATE_ENABLED";
 export const DELEGATE_TIMED_OUT_RESULT = "[delegate timed out]";
+
+// ── R9-F1 (2026-10-17): delegate-result recovery across parent turn-restarts ──
+// A parent session can restart mid-turn (pi-core seam): the delegate poll loop
+// dies with it, the grandchild later COMPLETES durably into the task inbox,
+// and nothing ever re-reads that message — the report is silently lost
+// (runtime-proven: run event seq 209/216/281/431, mailbox msg_b0297f83).
+// Conservative, seam-level mitigation (the pi-core trigger is external):
+//  - every in-flight subId is tracked in `inFlightDelegateSubIds`;
+//  - whenever a delegate poll loop (re)starts, the inbox is scanned ONCE for
+//    results of still-pending subIds that have no delivered result yet and
+//    they are re-injected into `recoveredDelegateResults` (logged as
+//    `delegate.result.recovered`) so the owning loop's next iteration — or a
+//    RESTARTED loop for the same subId — surfaces it without re-deriving it;
+//  - the timed-out notice points at the durable copy in the task inbox.
+// `no double-count`: a recovered message is consumed exactly once (deleted
+// from the map on delivery) and the inbox stays append-only ground truth.
+const inFlightDelegateSubIds = new Set<string>();
+const recoveredDelegateResults = new Map<string, MailboxMessage>();
+const RECOVERED_DELEGATE_RESULTS_MAX = 64;
+
+/** R9-F1: scan the task inbox for completed results of still-pending subIds.
+ *  Pure w.r.t. its inputs (injectable reader for tests); mutates the module
+ *  recovery map + logs one `delegate.result.recovered` internal event per
+ *  recovered subId. Returns the recovered messages keyed by subId. */
+export function recoverPendingDelegateResults(
+	manifest: TeamRunManifest,
+	pendingSubIds: ReadonlySet<string>,
+	readInbox: (m: TeamRunManifest) => MailboxMessage[] = (m) => readAllMailboxMessages(m, "inbox"),
+): Map<string, MailboxMessage> {
+	const recovered = new Map<string, MailboxMessage>();
+	if (pendingSubIds.size === 0) return recovered;
+	let messages: MailboxMessage[];
+	try {
+		messages = readInbox(manifest);
+	} catch (error) {
+		logInternalError("prompt-runtime.delegate-recovery-inbox-read", error instanceof Error ? error : new Error(String(error)), "warn");
+		return recovered;
+	}
+	for (const message of messages) {
+		const from = message.from ?? "";
+		if (!from.startsWith("delegate:")) continue;
+		const subId = from.slice("delegate:".length);
+		if (!pendingSubIds.has(subId)) continue;
+		if (recoveredDelegateResults.has(subId)) continue; // already recovered — no double-count
+		recoveredDelegateResults.set(subId, message);
+		while (recoveredDelegateResults.size > RECOVERED_DELEGATE_RESULTS_MAX) {
+			const oldest = recoveredDelegateResults.keys().next().value;
+			if (oldest === undefined) break;
+			recoveredDelegateResults.delete(oldest);
+		}
+		recovered.set(subId, message);
+		logInternalError(
+			"delegate.result.recovered",
+			new Error(`recovered completed delegate result from task inbox after a parent turn-restart (subId=${subId})`),
+			"warn",
+		);
+	}
+	return recovered;
+}
 /** P3-11: poll slack past the server deadline — the server timer fires first
  *  and writes the fenced (timed out) result; the client checks a bit longer
  *  so the outcome lands in-tool instead of lingering unread in the inbox. */
@@ -540,24 +599,40 @@ export function createDelegateTool(deps: DelegateToolDeps = {}): DelegateToolDef
 				const fromTag = `delegate:${subId}`;
 				let terminal: "completed" | "timed-out" | "aborted" = "timed-out";
 				let result: MailboxMessage | undefined;
-				while (true) {
-					if (signal?.aborted) {
-						terminal = "aborted";
-						break;
-					}
-					try {
-						result = readAllMailboxMessages(manifest, "inbox").find(
-							(m) => m.from === fromTag && (m.taskId === undefined || m.taskId === taskId),
-						);
-					} catch {
-						/* transient read error — keep polling */
-					}
-					if (result) {
-						terminal = "completed";
-						break;
+				// R9-F1: register the subId as in-flight and, at every loop (re)start,
+				// re-inject results of still-pending subIds that a previous (restarted)
+				// turn never delivered — they become visible to THIS loop's reads.
+				inFlightDelegateSubIds.add(subId);
+				try {
+					recoverPendingDelegateResults(manifest, inFlightDelegateSubIds);
+					while (true) {
+						if (signal?.aborted) {
+							terminal = "aborted";
+							break;
+						}
+						// Consume a recovered result FIRST (exactly once — map delete), then
+						// fall through to the durable inbox read (append-only ground truth).
+						result = recoveredDelegateResults.get(subId);
+						if (result) recoveredDelegateResults.delete(subId);
+						if (!result) {
+							try {
+								result = readAllMailboxMessages(manifest, "inbox").find(
+									(m) => m.from === fromTag && (m.taskId === undefined || m.taskId === taskId),
+								);
+							} catch {
+								/* transient read error — keep polling */
+							}
+						}
+						if (result) {
+							terminal = "completed";
+							break;
+						}
+						if (now() >= deadline) break;
+						await sleep(effectiveSteeringInterval(hasLiveControlRealtimeListeners()));
 					}
-					if (now() >= deadline) break;
-					await sleep(effectiveSteeringInterval(hasLiveControlRealtimeListeners()));
+				} finally {
+					inFlightDelegateSubIds.delete(subId);
+					recoveredDelegateResults.delete(subId);
 				}
 				const waitedMs = now() - startedAt;
 				if (terminal === "completed" && result) {
@@ -574,8 +649,17 @@ export function createDelegateTool(deps: DelegateToolDeps = {}): DelegateToolDef
 						details: { status: "aborted", grandchildTaskRef: subId, waitedMs },
 					};
 				}
+				// R9-F1: recovery hint — the grandchild can still complete AFTER this
+				// timeout (and after a parent turn-restart the tool result itself can be
+				// lost); the durable copy lands in the task inbox. Point the model at it
+				// instead of silently redoing the delegated work.
 				return {
-					content: [{ type: "text" as const, text: DELEGATE_TIMED_OUT_RESULT }],
+					content: [
+						{
+							type: "text" as const,
+							text: `${DELEGATE_TIMED_OUT_RESULT} — the grandchild may still complete; its result lands durably in the task inbox (from=delegate:${subId}) — check the task inbox / lastResult before redoing the work, or ask the leader to relay it.`,
+						},
+					],
 					details: { status: "timed-out", grandchildTaskRef: subId, waitedMs },
 				};
 			} finally {

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

@@ -223,6 +223,13 @@ export class CrewBrokerClient {
 			Math.max(1, Math.floor(timeoutMs)),
 		);
 		if (entry) entry.timer = requestTimer;
+		// R2-L-A3 (2026-10-17): unref the per-request timer (mirror the hello/
+		// backoff timers at :466-474) — a stranded in-flight request must not
+		// hold a finishing child's event loop open for up to timeoutMs. The
+		// typeof guard keeps injected test timer fakes (no unref) working.
+		if (requestTimer && typeof (requestTimer as { unref?: () => void }).unref === "function") {
+			(requestTimer as { unref?: () => void }).unref?.();
+		}
 		try {
 			const frame = encodeBrokerFrame({ id, method, params });
 			// Write may emit EPIPE etc. We don't await drain here — the response

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

@@ -64,6 +64,13 @@ import { type DelegateEventTarget, type DelegateEventType, recordDelegateEvent }
 import { promoteShadowToRunning } from "./delegate/shadow-lifecycle.ts";
 import { fanoutMailboxMessage } from "./mailbox-observer/mailbox-fanout.ts";
 import type { CrewBrokerOptions, ServerConnection } from "./protocol/connection-state.ts";
+// Outbound-queue management + caps (wc-gate move — bodies in protocol/connection-state.ts)
+import {
+	handleOutboundOverflowFrame,
+	type OutboundAdmission,
+	type OutboundQueueHooks,
+	writeOrQueueFrame,
+} from "./protocol/connection-state.ts";
 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";
@@ -107,29 +114,6 @@ const HELLO_DEADLINE_MS = 1_000;
  *  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;
-
-/** 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<
@@ -137,6 +121,7 @@ export class CrewBroker {
 			| "socketPath"
 			| "maxFrameBytes"
 			| "outboundQueueCap"
+			| "outboundQueueBytesCap"
 			| "cwd"
 			| "netModule"
 			| "waitStatusCache"
@@ -189,6 +174,7 @@ export class CrewBroker {
 			socketPath: options.socketPath,
 			maxFrameBytes: options.maxFrameBytes,
 			outboundQueueCap: options.outboundQueueCap,
+			outboundQueueBytesCap: options.outboundQueueBytesCap,
 			cwd: options.cwd,
 			netModule: options.netModule,
 			waitMethodsEnabled: options.waitMethodsEnabled === true,
@@ -473,6 +459,7 @@ export class CrewBroker {
 			role: undefined,
 			authMatchKind: undefined,
 			outbound: [],
+			queuedBytes: 0,
 			needsResync: false,
 			closed: false,
 			helloTimer: null,
@@ -822,6 +809,27 @@ export class CrewBroker {
 				err instanceof Error ? err : new Error(String(err)),
 				`sessionId=${this.options.sessionId}`,
 			);
+			// R9-N1 (2026-10-17): silently dropping a REQUEST-RESPONSE frame here
+			// (e.g. an events.since replay page larger than MAX_BROKER_FRAME_BYTES)
+			// left the client waiting on its id until its request timeout — a
+			// hang with no diagnostic. When the payload carries an id, answer it
+			// with a small typed error frame on the SAME id; if even that cannot
+			// encode, close (the client's reconnect+replay is the only durable
+			// answer left).
+			const id = (payload as { id?: unknown } | null)?.id;
+			if (typeof id === "number" || typeof id === "string") {
+				try {
+					const errBuf = encodeBrokerFrame({
+						id,
+						error: { code: "response-oversize", message: "response frame exceeds the broker frame limit" },
+					});
+					this.writeOrQueue(conn, errBuf, /*force*/ true);
+					return;
+				} catch {
+					/* fall through to close */
+				}
+			}
+			this.closeConnection(conn);
 			return;
 		}
 		// R6-5: request responses (the acks for ping/msg.send/wait.request/…)
@@ -832,91 +840,19 @@ export class CrewBroker {
 	}
 
 	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.
-				try {
-					conn.socket.write(buf);
-				} catch {
-					/* socket may have closed; the close handler will sweep. */
-				}
-				return;
-			}
-			// 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);
-		this.drainOutbound(conn);
+		writeOrQueueFrame(conn, buf, force, this.options, this.outboundHooks());
 	}
 
-	private drainOutbound(conn: ServerConnection): void {
-		while (conn.outbound.length > 0) {
-			const buf = conn.outbound[0];
-			if (buf === undefined) break;
-			// Try the write; if it returns false, wait for drain before pushing more.
-			try {
-				const ok = conn.socket.write(buf);
-				if (!ok) {
-					// Backpressure — re-arm on drain event.
-					conn.socket.once("drain", () => {
-						if (!conn.closed) this.drainOutbound(conn);
-					});
-					return;
-				}
-			} catch {
-				// Write failed — close the connection (we already had it open).
-				this.closeConnection(conn);
-				return;
-			}
-			conn.outbound.shift();
-			conn.outboundSeq += 1;
-		}
+	/** R6-5(b): fanout/event frame dropped at cap → typed resync close (moved body in connection-state.ts). */
+	private handleOutboundOverflow(conn: ServerConnection): void {
+		handleOutboundOverflowFrame(conn, this.options, this.outboundHooks());
 	}
 
-	/** 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);
+	private outboundHooks(): OutboundQueueHooks {
+		return {
+			onOverflow: (conn) => this.handleOutboundOverflow(conn),
+			onClose: (conn) => this.closeConnection(conn),
+		};
 	}
 
 	// Phase 1: msg.send + msg.inbox handlers
@@ -1298,6 +1234,11 @@ export class CrewBroker {
 		const v = params && typeof params === "object" && !Array.isArray(params) ? (params as Record<string, unknown>) : {};
 		const targetTaskId = typeof v.taskId === "string" ? v.taskId : undefined;
 		const body = typeof v.body === "string" ? v.body : undefined;
+		// R2-L-A4 (2026-10-17): optional client requestId — mirrors msg.send's U5
+		// dedup. An orchestrator retry after ack-loss used to DUPLICATE the steer
+		// (mailbox append + steering file); a stable requestId makes the resend a
+		// no-op.
+		const requestId = typeof v.requestId === "string" && v.requestId.length > 0 ? v.requestId.slice(0, 128) : undefined;
 		if (!targetTaskId || body === undefined) {
 			this.sendError(conn, id, "bad-params", "steer.push: taskId and body are required");
 			return;
@@ -1320,39 +1261,61 @@ export class CrewBroker {
 
 			const messageId = `steer_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 			// Write 1: mailbox — live broker fanout + persistent inbox read.
-			await appendMailboxMessageAsync(loaded.manifest, {
-				id: messageId,
-				direction: "inbox",
-				from: conn.taskId ?? conn.runId,
-				to: targetTaskId,
-				taskId: targetTaskId,
-				body,
-				kind: "steer",
-				priority: (v.priority as "urgent" | "normal" | "low" | undefined) ?? "urgent",
-				deliveryMode: "interrupt",
-			});
+			// R2-L-A4: idempotent append when the client supplied a requestId —
+			// resend-after-ack-loss dedupes instead of duplicating the steer.
+			let deduped = false;
+			if (requestId) {
+				const outcome = await appendMailboxMessageIdempotentAsync(loaded.manifest, {
+					id: messageId,
+					direction: "inbox",
+					from: conn.taskId ?? conn.runId,
+					to: targetTaskId,
+					taskId: targetTaskId,
+					body,
+					kind: "steer",
+					priority: (v.priority as "urgent" | "normal" | "low" | undefined) ?? "urgent",
+					deliveryMode: "interrupt",
+					requestId,
+				});
+				deduped = outcome.deduped;
+			} else {
+				await appendMailboxMessageAsync(loaded.manifest, {
+					id: messageId,
+					direction: "inbox",
+					from: conn.taskId ?? conn.runId,
+					to: targetTaskId,
+					taskId: targetTaskId,
+					body,
+					kind: "steer",
+					priority: (v.priority as "urgent" | "normal" | "low" | undefined) ?? "urgent",
+					deliveryMode: "interrupt",
+				});
+			}
 			// Write 2: steering file — durable fallback so pollSteering() picks
 			// up the steer even when the recipient child's broker connection is down. Matches the
 			// JSONL format of appendSteeringAsync in task-runner.ts.
 			// Best-effort: a failure here must NOT fail the push (mailbox write
 			// already succeeded).
-			try {
-				const steeringDir = `${loaded.manifest.artifactsRoot}/steering`;
-				const steeringPath = resolveRealContainedPath(loaded.manifest.artifactsRoot, `steering/${targetTaskId}.jsonl`);
-				const line =
-					JSON.stringify({
-						type: "steer",
-						message: body,
-						id: messageId,
-						ts: new Date().toISOString(),
-					}) + "\n";
-				await fsp.mkdir(steeringDir, { recursive: true });
-				await fsp.appendFile(steeringPath, line, "utf-8");
-			} catch (fileErr) {
-				const safeMessage = fileErr instanceof Error ? redactSecretString(fileErr.message) : "";
-				logInternalError("crew-broker.steer-file-write-failed", new Error(safeMessage), `taskId=${targetTaskId}`);
+			// R2-L-A4: a deduped resend must NOT re-append the steering file either.
+			if (!deduped) {
+				try {
+					const steeringDir = `${loaded.manifest.artifactsRoot}/steering`;
+					const steeringPath = resolveRealContainedPath(loaded.manifest.artifactsRoot, `steering/${targetTaskId}.jsonl`);
+					const line =
+						JSON.stringify({
+							type: "steer",
+							message: body,
+							id: messageId,
+							ts: new Date().toISOString(),
+						}) + "\n";
+					await fsp.mkdir(steeringDir, { recursive: true });
+					await fsp.appendFile(steeringPath, line, "utf-8");
+				} catch (fileErr) {
+					const safeMessage = fileErr instanceof Error ? redactSecretString(fileErr.message) : "";
+					logInternalError("crew-broker.steer-file-write-failed", new Error(safeMessage), `taskId=${targetTaskId}`);
+				}
 			}
-			this.sendResult(conn, id, { messageId, taskId: targetTaskId, durable: true });
+			this.sendResult(conn, id, { messageId, taskId: targetTaskId, durable: true, ...(requestId ? { requestId, deduped } : {}) });
 		} catch (err) {
 			this.sendError(conn, id, "steer-failed", (err as Error).message);
 		}
@@ -1389,6 +1352,15 @@ export class CrewBroker {
 		}
 		// Default recipient: the sender's taskId (the orchestrator that
 		// spawned this worker). If 'to' is provided, use it instead.
+		// R2-L-A6 (wave-2b): 'to' is SENDER-CHOSEN and lands in a mailbox
+		// record (taskId field) — an arbitrary value would let a worker
+		// address any task in the run (spoofed follow-up routing). Restrict
+		// to the two identities the sender legitimately owns: its run and
+		// its own (parent) task.
+		if (to !== undefined && to !== conn.runId && to !== conn.taskId) {
+			this.sendError(conn, id, "bad-params", `escalate: 'to' must be this connection's run or task`);
+			return;
+		}
 		const target = to ?? conn.taskId ?? conn.runId;
 		try {
 			const loaded = loadRunManifestById(cwd, conn.runId);
@@ -1884,7 +1856,7 @@ export class CrewBroker {
 			const updatedManifest = {
 				...fresh.manifest,
 				// manifest.status stays "running" — park NEVER flips run status (ADR item 3).
-				waitState: { taskId, questionId, askedAt },
+				waitState: { taskId, questionId, askedAt, deadline }, // R2-M-A2: mirror task.waiting.deadline for shield expiry
 				updatedAt: askedAt,
 			};
 			saveRunTasks(updatedManifest, updatedTasks);

package/src/runtime/broker/protocol/connection-state.ts

@@ -9,7 +9,8 @@
  */
 
 import type * as net from "node:net";
-import type { NdjsonDecoder } from "../../../utils/ndjson.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+import { encodeBrokerFrame, type NdjsonDecoder } from "../../../utils/ndjson.ts";
 import type { GrandchildSpawnInput, GrandchildSpawnResult } from "../../delegate-spawn.ts";
 import type { WaitStatusCache } from "../wait-status-cache.ts";
 
@@ -22,6 +23,10 @@ export interface CrewBrokerOptions {
 	maxFrameBytes?: number;
 	/** Per-connection outbound queue cap. Default 256. */
 	outboundQueueCap?: number;
+	/** R8-M1: per-connection queued-BYTES cap (frames can be up to
+	 *  MAX_BROKER_FRAME_BYTES each, so the frame cap alone bounds the queue
+	 *  at cap × 256 KiB ≈ 64 MiB in-app). Default 4 MiB. */
+	outboundQueueBytesCap?: 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. */
@@ -102,6 +107,9 @@ export interface ServerConnection {
 	authedSecretHash?: string;
 	/** Outbound queue of encoded frames awaiting drain. */
 	outbound: Buffer[];
+	/** R8-M1: sum of `outbound[i].length` — maintained by writeOrQueue/
+	 *  drainOutbound so the queued-BYTES cap does not rescan the queue. */
+	queuedBytes: number;
 	/** Set when the queue has hit the cap and a frame was dropped. */
 	needsResync: boolean;
 	/** Set when the connection is closing (idempotent). */
@@ -111,3 +119,153 @@ export interface ServerConnection {
 	/** Monotonic seq counter for outbound events (diagnostic). */
 	outboundSeq: number;
 }
+
+// ---------------------------------------------------------------------------
+// Outbound queue management (moved from crew-broker.ts — M4 wc-gate ≤2000;
+// pure move, no behavior change). The broker keeps thin delegating methods.
+// ---------------------------------------------------------------------------
+
+/** Default per-connection outbound queue cap (events). */
+export const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
+
+/** R8-M1 (2026-10-17): default per-connection queued-BYTES cap. The frame cap
+ *  alone lets a subscribed-but-never-reading client buffer 256 × 256 KiB ≈
+ *  64 MiB in-app before the R6-5 typed close engages (kernel backpressure
+ *  shifts frames off the queue, so the count rarely grows — the BYTES the
+ *  process holds do). ~4 MiB bounds a stuck connection's memory while a
+ *  healthy LAN client drains comfortably inside it. */
+export const DEFAULT_OUTBOUND_QUEUE_BYTES = 4 * 1024 * 1024;
+
+/** 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. */
+export type OutboundAdmission = boolean | "response";
+
+export interface OutboundQueueOpts {
+	outboundQueueCap?: number;
+	outboundQueueBytesCap?: number;
+	sessionId: string;
+}
+export interface OutboundQueueHooks {
+	onOverflow(conn: ServerConnection): void;
+	onClose(conn: ServerConnection): void;
+}
+
+export function writeOrQueueFrame(
+	conn: ServerConnection,
+	buf: Buffer,
+	force: OutboundAdmission,
+	opts: OutboundQueueOpts,
+	hooks: OutboundQueueHooks,
+): void {
+	if (conn.closed) return;
+	const cap = opts.outboundQueueCap ?? DEFAULT_OUTBOUND_QUEUE_CAP;
+	// R8-M1: queued-BYTES cap alongside the frame cap. Few-but-large frames
+	// (a slow reader behind a 256 KiB fanout) never trip a 256-frame cap;
+	// without this the process buffers up to ~64 MiB per stuck connection.
+	// Overflow takes the same typed-close path as the frame cap (resync +
+	// reconnect + replay) — applied to ALL admission classes because the
+	// connection is about to close anyway and the alternative is unbounded
+	// memory, not a delivered response.
+	const bytesCap = opts.outboundQueueBytesCap ?? DEFAULT_OUTBOUND_QUEUE_BYTES;
+	if (conn.queuedBytes + buf.length > bytesCap) {
+		hooks.onOverflow(conn);
+		return;
+	}
+	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);
+			conn.queuedBytes += buf.length;
+			drainOutboundFrames(conn, hooks);
+			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.
+			try {
+				conn.socket.write(buf);
+			} catch {
+				/* socket may have closed; the close handler will sweep. */
+			}
+			return;
+		}
+		// 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).
+		hooks.onOverflow(conn);
+		return;
+	}
+	conn.outbound.push(buf);
+	conn.queuedBytes += buf.length;
+	drainOutboundFrames(conn, hooks);
+}
+
+export function drainOutboundFrames(conn: ServerConnection, hooks: OutboundQueueHooks): void {
+	while (conn.outbound.length > 0) {
+		const buf = conn.outbound[0];
+		if (buf === undefined) break;
+		// Try the write; if it returns false, wait for drain before pushing more.
+		try {
+			const ok = conn.socket.write(buf);
+			if (!ok) {
+				// Backpressure — re-arm on drain event.
+				conn.socket.once("drain", () => {
+					if (!conn.closed) drainOutboundFrames(conn, hooks);
+				});
+				return;
+			}
+		} catch {
+			// Write failed — close the connection (we already had it open).
+			hooks.onClose(conn);
+			return;
+		}
+		conn.outbound.shift();
+		conn.queuedBytes -= buf.length;
+		conn.outboundSeq += 1;
+	}
+}
+
+export function handleOutboundOverflowFrame(conn: ServerConnection, opts: OutboundQueueOpts, hooks: OutboundQueueHooks): 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=${opts.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 */
+	}
+	hooks.onClose(conn);
+}