pi-crew 0.11.21 → 0.11.22

package/src/extension/team-tool.ts

@@ -954,11 +954,33 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 	);
 }
 
+// R5-6 (DR-02 round-5): send-side clamp for `team steer` bodies. The
+// worker-side receiver (prompt-runtime sanitizeSteerMessage) clamps too (its
+// rejection of >4096-char steers was terminal — the poll cursor advanced
+// past the line, so an oversized leader steer was silently dropped), but the
+// send-side clamp means pendingSteers, the steering JSONL, and the
+// task.steer_queued event all already carry a receiver-safe body with the
+// truncation marker visible to the leader's audit trail. Deliberately
+// duplicated from prompt-runtime's clampSteerMessage (same rationale as the
+// estimateHandoffTokens duplication in task-output-context.ts): importing
+// prompt-runtime here would pull the broker-client/scratchpad/surface-worker
+// graph into the extension registration path (cold-start). Keep the two
+// clamps in sync.
+const TEAM_STEER_MAX_MESSAGE_LENGTH = 4096;
+const TEAM_STEER_TRUNCATION_MARKER = `\n[message truncated at ${TEAM_STEER_MAX_MESSAGE_LENGTH} chars]`;
+function clampSteerBody(message: string): string {
+	if (message.length <= TEAM_STEER_MAX_MESSAGE_LENGTH) return message;
+	return `${message.slice(0, TEAM_STEER_MAX_MESSAGE_LENGTH - TEAM_STEER_TRUNCATION_MARKER.length)}${TEAM_STEER_TRUNCATION_MARKER}`;
+}
+
 export function handleSteer(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	const { runId, taskId, message } = params;
-	if (!runId || !taskId || !message) {
+	const { runId, taskId } = params;
+	const rawMessage = params.message;
+	if (!runId || !taskId || !rawMessage) {
 		return result("steer requires runId, taskId, and message", { action: "steer", status: "error" }, true);
 	}
+	// R5-6: clamp BEFORE any sink (pending queue, JSONL, event) sees the body.
+	const message = clampSteerBody(String(rawMessage));
 	const runCwd = locateRunCwd(runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${runId}' not found`, { action: "steer", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency

package/src/prompt/inbox-poll.ts

@@ -23,12 +23,19 @@
  *     must be dropped at consume time);
  *   - dedup by message id across polls via a caller-owned seen-set and/or a
  *     `sinceTs` watermark — one message delivers once;
- *   - U5 (2026-10-10): dedup is ALSO durable across restarts — every picked
- *     row is recorded in delivery.json (`messages[id]="acknowledged"` +
+ *   - U5 (2026-10-10): dedup is ALSO durable across restarts — delivered
+ *     rows are recorded in delivery.json (`messages[id]="acknowledged"` +
  *     `${direction}:${requestId}` index) and re-read on the next poll, so a
  *     worker that restarts mid-run (fresh process, EMPTY seen-set) never
  *     re-delivers. A resend carrying the same requestId is dropped by the
  *     same index; duplicate rows under one requestId deliver exactly once.
+ *   - R5-1 (DR-02, 2026-10-15): the durable record is written in TWO PHASES.
+ *     `pollWorkerInbox` only picks rows and marks the IN-MEMORY seen-set;
+ *     the durable "acknowledged" write lives in
+ *     `acknowledgeWorkerInboxDelivery`, which the delivery loop calls ONLY
+ *     after `pi.sendMessage` succeeded. A send that throws must instead call
+ *     `unmarkSeenInboxIds` so the next tick re-picks the batch — at-least-once
+ *     beats the pre-fix at-most-once-with-a-false-"delivered"-audit-record.
  */
 import * as path from "node:path";
 import {
@@ -125,13 +132,22 @@ function emitPickupEvent(stateRoot: string, runId: string, taskId: string, picke
 
 /**
  * Read the worker's inbox mailbox and return the messages that should be
- * surfaced as fenced context on the next turn.
+ * surfaced as fenced context on the next turn. PICKUP PHASE ONLY (R5-1):
+ * picked rows are marked in the caller-owned in-memory seen-set, but the
+ * durable delivery record is NOT written here — the caller must run
+ * {@link acknowledgeWorkerInboxDelivery} after its send succeeded, and
+ * {@link unmarkSeenInboxIds} when the send threw.
+ *
+ * `limit` (R5-2, DR-02): pick at most this many rows per call (callers pass
+ * their per-tick batch cap). Leftover rows are simply not picked — not
+ * marked, in memory or durably — and flow on a later tick.
  *
  * Stateless apart from the optional caller-owned `seenIds`/`sinceTs` — safe
- * to call on every 500ms poll tick. U5: picked rows are ALSO recorded in the
- * durable delivery state (delivery.json), so dedup survives a restart.
+ * to call on every 500ms poll tick. U5: the durable dedup-read checks
+ * (acknowledged rows / delivered requestIds) still run here so dedup
+ * survives a restart.
  */
-export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
+export function pollWorkerInbox(pickup: WorkerInboxPickup, limit?: number): MailboxMessage[] {
 	const { stateRoot, runId, taskId } = pickup;
 	if (!stateRoot || !runId || !taskId) return [];
 	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
@@ -157,6 +173,11 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 	const byId = new Set<string>();
 	const byRequestId = new Set<string>();
 	for (const m of messages) {
+		// R5-2 (DR-02): enforce the batch cap AT PICKUP, not at the send site —
+		// every picked row must also be a row the caller can actually send (and
+		// later acknowledge). The pre-fix shape picked N rows, durably acked all
+		// N, then sliced 8 for the send — the surplus was never re-delivered.
+		if (limit !== undefined && picked.length >= limit) break;
 		// Kind gate: only durable `message`s (per §15.2). Notify is
 		// fire-and-forget (its own channel), steer/response/follow-up are
 		// other delivery paths.
@@ -204,25 +225,56 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 		seen?.add(m.id);
 		picked.push(m);
 	}
-	if (picked.length > 0) {
-		// U5: persist the pickup — the durable record that powers the two
-		// layers above after a restart. Best-effort on failure: the in-memory
-		// seen-set still dedups within THIS process, and logInternalError
-		// makes the lost-durability window visible.
-		try {
-			recordMailboxRequestIdDelivery(
-				manifest,
-				picked.map((m) => ({
-					direction: m.direction,
-					messageId: m.id,
-					requestId: messageIdempotencyKey(m),
-				})),
-			);
-			emitPickupEvent(stateRoot, runId, taskId, picked);
-		} catch (error) {
-			logInternalError("inbox-poll.record-delivery", error, `runId=${runId} taskId=${taskId}`);
-		}
-	}
 	// Deterministic delivery order (same sort readAllMailboxMessages applies).
 	return picked;
 }
+
+/**
+ * R5-1 (DR-02, 2026-10-15): durable-ack phase of the pickup, split OUT of
+ * `pollWorkerInbox`. The caller invokes this ONLY after the picked rows were
+ * successfully delivered (`pi.sendMessage` returned) — the durable
+ * "acknowledged" record and the pickup audit event must never precede a send
+ * that can fail (the pre-fix bug wrote them BEFORE the send, so a send
+ * failure produced a permanent false "delivered" record plus silent message
+ * loss). Mid-batch all-or-nothing: recordMailboxRequestIdDelivery is a single
+ * locked RMW, so acks are atomic per call.
+ *
+ * Best-effort on failure (never throws into the poll tick): the in-memory
+ * seen-set still dedups within THIS process, and logInternalError makes the
+ * lost-durability window visible.
+ */
+export function acknowledgeWorkerInboxDelivery(
+	pickup: Pick<WorkerInboxPickup, "stateRoot" | "runId" | "taskId">,
+	picked: MailboxMessage[],
+): void {
+	const { stateRoot, runId, taskId } = pickup;
+	if (!stateRoot || !runId || !taskId || picked.length === 0) return;
+	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
+	try {
+		// U5: persist the delivery — the durable record that powers the two
+		// dedup layers above after a restart.
+		recordMailboxRequestIdDelivery(
+			manifest,
+			picked.map((m) => ({
+				direction: m.direction,
+				messageId: m.id,
+				requestId: messageIdempotencyKey(m),
+			})),
+		);
+		emitPickupEvent(stateRoot, runId, taskId, picked);
+	} catch (error) {
+		logInternalError("inbox-poll.record-delivery", error, `runId=${runId} taskId=${taskId}`);
+	}
+}
+
+/**
+ * R5-1 (DR-02): release the in-memory seen marks for a batch whose
+ * `pi.sendMessage` THREW, so the next poll tick re-picks and re-delivers it
+ * (at-least-once beats at-most-once with a false "delivered" audit record).
+ * Mirrors the steer channel's `seenSteers.unmark` + offset-rewind
+ * compensation in prompt-runtime.ts pollSteering.
+ */
+export function unmarkSeenInboxIds(seen: Set<string> | undefined, picked: MailboxMessage[]): void {
+	if (!seen) return;
+	for (const m of picked) seen.delete(m.id);
+}

package/src/prompt/message-tool.ts

@@ -24,6 +24,7 @@
  * sending, so two workers cannot loop message each other to death.
  */
 
+import { createHash } from "node:crypto";
 import { type Static, Type } from "@sinclair/typebox";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { CrewBrokerClient } from "../runtime/broker/crew-broker-client.ts";
@@ -38,6 +39,14 @@ const MSG_TO_MAX_CHARS = 256;
 /** §15.2 rate-limit: 10 messages/min/task, sliding window. */
 const MSG_RATE_LIMIT_MAX = 10;
 const MSG_RATE_LIMIT_WINDOW_MS = 60_000;
+/** R6-6 (DR-03 round-6 2026-10-16): explicit per-request timeout for
+ *  msg.send. The client's 15s default (REQUEST_TIMEOUT_DEFAULT_MS) turns a
+ *  merely-slow durable send (multi-recipient chunked appends + fsync + audit
+ *  event) into a reported "NOT sent" — and the model's natural retry into a
+ *  duplicate delivery. 60s matches the worst bounded fanout (64 recipients,
+ *  8-wide chunks) with headroom while staying below the tool's own "never a
+ *  hang" budget (the request still resolves via this timeout, never hangs). */
+export const MSG_SEND_TIMEOUT_MS = 60_000;
 
 export const MessageToolParamsSchema = Type.Object({
 	to: Type.Union([Type.Literal("parent"), Type.Literal("group"), Type.String({ minLength: 1, maxLength: MSG_TO_MAX_CHARS })]),
@@ -49,12 +58,46 @@ export const MessageToolParamsSchema = Type.Object({
 export type MessageToolParams = Static<typeof MessageToolParamsSchema>;
 
 /** Minimal broker-client surface the message tool needs (structural subset of
- *  CrewBrokerClient — tests substitute a recorder). */
+ *  CrewBrokerClient — tests substitute a recorder). R6-6: the optional third
+ *  argument carries the per-request timeout; existing 2-arg recorders remain
+ *  structurally assignable. */
 export interface MessageBrokerClientSurface {
-	request(method: string, params: unknown): Promise<{ ok: true; value: unknown } | { ok: false; fallback?: boolean; errorCode?: string }>;
+	request(
+		method: string,
+		params: unknown,
+		opts?: { timeoutMs?: number },
+	): Promise<{ ok: true; value: unknown } | { ok: false; fallback?: boolean; errorCode?: string }>;
 	close?(): Promise<void>;
 }
 
+/** R6-6: stable idempotency key derived from message identity. A retry of
+ *  the same logical message (same sender, target, kind, content — e.g. the
+ *  model re-invoking `message` after a lost/slow ack) computes the SAME
+ *  requestId, and the broker's U5 durable (direction, requestId) index in
+ *  delivery.json + appendMailboxMessageIdempotentAsync turn the resend into
+ *  a no-op instead of a duplicate row. Pure content hash: matches the
+ *  request-parsers `^[\\w:.-]{1,256}$` requestId charset (hex + `-`). */
+export function computeMessageRequestId(identity: {
+	runId: string;
+	taskId: string;
+	to: string;
+	kind: string;
+	body: string;
+	subject?: string;
+	priority?: string;
+}): string {
+	const material = JSON.stringify([
+		identity.runId,
+		identity.taskId,
+		identity.to,
+		identity.kind,
+		identity.body,
+		identity.subject ?? null,
+		identity.priority ?? null,
+	]);
+	return `msgtool-${createHash("sha256").update(material).digest("hex").slice(0, 32)}`;
+}
+
 export interface MessageToolDeps {
 	/** Env source override (tests). Production reads via getCrewEnv. */
 	env?: NodeJS.ProcessEnv;
@@ -137,11 +180,26 @@ export function createMessageTool(deps: MessageToolDeps = {}): MessageTool {
 						return new CrewBrokerClient({ runId, taskId, socketPath, token });
 					})();
 			if (!client) return brokerUnavailable();
-			const requestParams: Record<string, unknown> = { to: params.to, kind: params.kind, body: params.body };
+			// R6-6: stable requestId (idempotency across retries) + explicit
+			// timeoutMs (a slow durable ack is NOT a failure).
+			const requestParams: Record<string, unknown> = {
+				to: params.to,
+				kind: params.kind,
+				body: params.body,
+				requestId: computeMessageRequestId({
+					runId,
+					taskId,
+					to: params.to,
+					kind: params.kind,
+					body: params.body,
+					subject: params.subject,
+					priority: params.priority,
+				}),
+			};
 			if (params.subject) requestParams.subject = params.subject;
 			if (params.priority) requestParams.priority = params.priority;
 			try {
-				const sent = await client.request("msg.send", requestParams);
+				const sent = await client.request("msg.send", requestParams, { timeoutMs: MSG_SEND_TIMEOUT_MS });
 				if (!sent.ok) {
 					// Broker rejection (role gate / policy / auth / fallback) — all
 					// fast-fail, non-blocking.

package/src/prompt/prompt-runtime.ts

@@ -12,7 +12,7 @@ import { appendEventFireAndForget } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { pollWorkerInbox } from "./inbox-poll.ts";
+import { acknowledgeWorkerInboxDelivery, pollWorkerInbox, unmarkSeenInboxIds } from "./inbox-poll.ts";
 import { createMessageTool, type MessageToolParams as MessageToolInputs, shouldRegisterMessageTool } from "./message-tool.ts";
 import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 import { createWorkerActivityTracker, registerSurfaceWorkerLifecycle, trackToolActivity } from "./surface-worker.ts";
@@ -32,13 +32,31 @@ const DATE_HEADER = "\nCurrent date:";
 // ── FIX-02: Steering content sanitization limits ──────────────────────────
 // Bounded to keep a malformed/malicious steer entry from blowing up the
 // worker's prompt budget or smuggling control sequences into the agent.
-const MAX_STEER_MESSAGE_LENGTH = 4096;
+export const MAX_STEER_MESSAGE_LENGTH = 4096;
 const MAX_STEER_MESSAGE_NEWLINES = 50;
 // C0 control characters minus the printable whitespace (\t \n \r). These
 // are the bytes most useful for ANSI escapes, terminal-control tricks, and
 // NUL-injection attacks when steer content reaches the worker's UI.
 const STEER_CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
 
+/** R5-6 (DR-02 round-5): truncation marker for oversized steer bodies —
+ *  mirrors renderInboxMessage's 8192-char marker pattern below. The clamp
+ *  slices so the FINAL message (slice + marker) stays ≤
+ *  {@link MAX_STEER_MESSAGE_LENGTH}, keeping the receiver's length invariant
+ *  honest. */
+const STEER_TRUNCATION_MARKER = `\n[message truncated at ${MAX_STEER_MESSAGE_LENGTH} chars]`;
+
+/** R5-6 (DR-02 round-5): clamp a steer body to
+ *  {@link MAX_STEER_MESSAGE_LENGTH} with a truncation marker. The send side
+ *  (team-tool handleSteer) clamps at dispatch; this helper is the receiver's
+ *  clean seam — every delivery path (file poll AND broker push) funnels
+ *  through `sanitizeSteerMessage`, so an oversized steer from ANY writer is
+ *  delivered truncated-with-marker instead of rejected-and-dropped. */
+export function clampSteerMessage(message: string): string {
+	if (message.length <= MAX_STEER_MESSAGE_LENGTH) return message;
+	return `${message.slice(0, MAX_STEER_MESSAGE_LENGTH - STEER_TRUNCATION_MARKER.length)}${STEER_TRUNCATION_MARKER}`;
+}
+
 export interface SteerSanitizeResult {
 	valid: boolean;
 	reason?: string;
@@ -118,25 +136,28 @@ export function createSeenSteerIdSet(): {
 
 /**
  * Validate a single steering-file entry before forwarding it to
- * `pi.sendMessage`. FIX-02: reject oversized payloads, excessive newlines,
- * or control characters that could be used to confuse the worker UI.
- */
+ * `pi.sendMessage`. FIX-02: reject excessive newlines or control characters
+ * that could be used to confuse the worker UI. R5-6 (DR-02 round-5): an
+ * OVERSIZED payload (>4096 chars) is no longer rejected-and-dropped — the
+ * rejection was terminal (the poll cursor advanced past the line, warn-only)
+ * and the send side had no clamp, so a leader steer over the limit silently
+ * vanished. It is now truncated-with-marker ({@link clampSteerMessage}) and
+ * delivered; the newline/control-char rejections remain terminal (different
+ * failure modes — UI confusion / escape smuggling, not length). */
 export function sanitizeSteerMessage(entry: SteerEntry): SteerSanitizeResult {
 	const message = entry.message;
 	if (typeof message !== "string" || message.length === 0) {
 		return { valid: false, reason: "missing-or-empty-message" };
 	}
-	if (message.length > MAX_STEER_MESSAGE_LENGTH) {
-		return { valid: false, reason: `message-too-long:${message.length}` };
-	}
-	const newlineCount = (message.match(/\n/g) ?? []).length;
+	const clamped = clampSteerMessage(message);
+	const newlineCount = (clamped.match(/\n/g) ?? []).length;
 	if (newlineCount > MAX_STEER_MESSAGE_NEWLINES) {
 		return { valid: false, reason: `too-many-newlines:${newlineCount}` };
 	}
-	if (STEER_CONTROL_CHAR_PATTERN.test(message)) {
+	if (STEER_CONTROL_CHAR_PATTERN.test(clamped)) {
 		return { valid: false, reason: "contains-control-characters" };
 	}
-	return { valid: true, message };
+	return { valid: true, message: clamped };
 }
 
 // ── FIX-03: Steering file path containment validation ─────────────────────
@@ -1067,45 +1088,74 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	// (`deliverAs:"steer"`, customType "crew-inbox") so the model sees
 	// conversations between agents. Dormant-until-env: only when this worker
 	// carries broker credentials (child-pi-spawn sets them for every worker)
-	// + a state root. A message is delivered EXACTLY ONCE via a seen-id set
-	// owned by this loop (the same keying that guards cross-channel steer
-	// dedup; here the durable mailbox is the only channel).
+	// + a state root. R5-1/R5-2 (DR-02, 2026-10-15): delivery is ack-AFTER-send
+	// — the poll picks (in-memory seen-set) up to INBOX_BATCH_MAX rows, the
+	// DURABLE "acknowledged" record is written (acknowledgeWorkerInboxDelivery)
+	// only after pi.sendMessage succeeded; a send throw unmarks the batch
+	// (unmarkSeenInboxIds) so the next tick re-delivers it. Pickup is thus
+	// at-least-once across send failures and exactly-once once the durable
+	// ack lands (it also survives a restart — U5 semantics).
 	const inboxBrokerRunId = getCrewEnv(PI_CREW_BROKER_RUN_ID_ASK_ENV);
 	const inboxStateRoot = getCrewEnv(PI_CREW_STATE_ROOT_ENV);
 	const inboxTaskId = getCrewEnv(PI_CREW_TASK_ID_ASK_ENV) ?? getCrewEnv(PI_CREW_BROKER_TASK_ID_ASK_ENV);
 	if (inboxBrokerRunId && inboxStateRoot && inboxTaskId) {
 		const seenInboxIds = new Set<string>();
 		// Batch cap per tick: bounds a single steer frame that could otherwise
-		// pile up many fenced messages in one delivery.
+		// pile up many fenced messages in one delivery. R5-2 (DR-02): the cap
+		// is enforced AT PICKUP (pollWorkerInbox `limit`) so every picked row is
+		// also a row actually sent + acked — the pre-fix shape acked N rows
+		// durably but sliced 8 for the send, orphaning the surplus forever.
 		const INBOX_BATCH_MAX = 8;
 		const pollInbox = (): void => {
 			try {
-				const picked = pollWorkerInbox({
-					stateRoot: inboxStateRoot,
-					runId: inboxBrokerRunId,
-					taskId: inboxTaskId,
-					seenIds: seenInboxIds,
-				});
+				const picked = pollWorkerInbox(
+					{
+						stateRoot: inboxStateRoot,
+						runId: inboxBrokerRunId,
+						taskId: inboxTaskId,
+						seenIds: seenInboxIds,
+					},
+					INBOX_BATCH_MAX,
+				);
 				if (picked.length === 0) return;
-				const batch = picked.slice(0, INBOX_BATCH_MAX);
 				// §15.2 trust boundary: the sender's body is DATA, never
 				// instructions. pollWorkerInbox hands back raw mailbox entries —
 				// fence each body (control chars stripped, closing fence
 				// neutralized, length capped) before it reaches the agent.
-				const fenced = batch.map((m) => ({
+				const fenced = picked.map((m) => ({
 					from: m.from,
 					to: m.to,
 					body: renderInboxMessage(m),
 				}));
-				pi.sendMessage(
-					{
-						customType: "crew-inbox",
-						content: fenced.map((e) => e.body).join("\n"),
-						display: false,
-						details: { messages: fenced, count: batch.length },
-					},
-					{ deliverAs: "steer" },
-				);
+				try {
+					pi.sendMessage(
+						{
+							customType: "crew-inbox",
+							content: fenced.map((e) => e.body).join("\n"),
+							display: false,
+							details: { messages: fenced, count: picked.length },
+						},
+						{ deliverAs: "steer" },
+					);
+				} catch (sendErr) {
+					// R5-1: the send FAILED (e.g. pre-bind notInitialized — exactly
+					// what the registration-time synchronous pollInbox() below can
+					// hit). No durable ack was written yet, so there is no false
+					// "delivered" record; release the seen marks so the next tick
+					// re-picks and re-delivers the batch — mirrors seenSteers.unmark
+					// + offset rewind in pollSteering above (at-least-once).
+					unmarkSeenInboxIds(seenInboxIds, picked);
+					logInternalError(
+						"prompt-runtime.inbox-delivery-failed",
+						sendErr instanceof Error ? sendErr : new Error(String(sendErr)),
+						`runId=${inboxBrokerRunId} taskId=${inboxTaskId} count=${picked.length}`,
+						"warn",
+					);
+					return;
+				}
+				// R5-1: the durable "acknowledged" record + pickup audit event
+				// happen ONLY after a successful send — never before it.
+				acknowledgeWorkerInboxDelivery({ stateRoot: inboxStateRoot, runId: inboxBrokerRunId, taskId: inboxTaskId }, picked);
 			} catch {
 				// A transient mailbox read error must never break the tick — the
 				// next 500ms (or 50ms under live-session realtime) poll retries.

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;