pi-crew 0.9.68 → 0.10.2

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

@@ -21,8 +21,10 @@
  *  full contract and acceptance criteria.
  */
 
+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,
@@ -31,15 +33,21 @@ import {
 	readMailbox,
 	registerMailboxAppendObserver,
 } from "../../state/coordination/mailbox.ts";
-import { readEventsCursor } from "../../state/event-log/event-log.ts";
-import { loadRunManifestById } from "../../state/stores/state-store.ts";
+import { appendEventAsync, readEventsCursor } from "../../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../../state/stores/state-store.ts";
+import type { TeamTaskState } from "../../state/types.ts";
 import { runEventBus } from "../../ui/run-event-bus.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { BrokerError, encodeBrokerFrame, MAX_BROKER_FRAME_BYTES, NdjsonDecoder } from "../../utils/ndjson.ts";
 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 { 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 { WaitStatusCache } from "./wait-status-cache.ts";
 
 /** Protocol version negotiated at `hello` time. Bump on breaking change. */
 const BROKER_PROTOCOL = 1;
@@ -69,6 +77,38 @@ export interface CrewBrokerOptions {
 	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;
 }
 
 /** Per-connection server-side state. */
@@ -83,6 +123,11 @@ interface ServerConnection {
 	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. */
@@ -96,8 +141,23 @@ interface ServerConnection {
 }
 
 export class CrewBroker {
-	private readonly options: Required<Pick<CrewBrokerOptions, "sessionId" | "enabled">> &
-		Pick<CrewBrokerOptions, "socketPath" | "maxFrameBytes" | "outboundQueueCap" | "cwd" | "netModule">;
+	private readonly options: Required<Pick<CrewBrokerOptions, "sessionId" | "enabled" | "waitMethodsEnabled" | "nestingEnabled">> &
+		Pick<
+			CrewBrokerOptions,
+			| "socketPath"
+			| "maxFrameBytes"
+			| "outboundQueueCap"
+			| "cwd"
+			| "netModule"
+			| "waitStatusCache"
+			| "nestingMaxSlots"
+			| "nestingMaxDepth"
+			| "nestingTrustedEscalation"
+			| "globalWorkerSemaphore"
+			| "grandchildSpawner"
+			| "modelCatalog"
+			| "serializeOnPathOverlap"
+		>;
 	private readonly tokens = new BrokerTokenRegistry();
 	private server: net.Server | null = null;
 	private resolvedSocketPath: string | null = null;
@@ -110,8 +170,14 @@ export class CrewBroker {
 	private readonly subscriptionUnsubs = new WeakMap<ServerConnection, Set<() => void>>();
 	/** Unsubscribe handle for the mailbox append observer (set on start, cleared on stop). */
 	private mailboxObserverUnsub: (() => void) | null = null;
+	/** T3/R5 (ADR-5 §2): nested-slot budget for delegate grandchildren — lazily
+	 *  sized from options (max(1, floor(globalWorkerSemaphore/2)) or override). */
+	private nestedSlots: NestedSlotBudget | undefined;
 	/** A single observable handshake counter (test/observability). */
 	private handshakeCount = 0;
+	/** R10-3: stat-gated manifest/tasks cache shared by all task.waitStatus
+	 *  waiters on this broker (keyed by runId — the broker serves one cwd). */
+	private readonly waitStatusCache: WaitStatusCache;
 
 	constructor(options: CrewBrokerOptions) {
 		if (!options || typeof options !== "object") {
@@ -128,7 +194,17 @@ export class CrewBroker {
 			outboundQueueCap: options.outboundQueueCap,
 			cwd: options.cwd,
 			netModule: options.netModule,
+			waitMethodsEnabled: options.waitMethodsEnabled === true,
+			nestingEnabled: options.nestingEnabled === true,
+			nestingMaxSlots: options.nestingMaxSlots,
+			nestingMaxDepth: options.nestingMaxDepth,
+			nestingTrustedEscalation: options.nestingTrustedEscalation === true,
+			globalWorkerSemaphore: options.globalWorkerSemaphore,
+			grandchildSpawner: options.grandchildSpawner,
+			modelCatalog: options.modelCatalog,
+			serializeOnPathOverlap: options.serializeOnPathOverlap === true,
 		};
+		this.waitStatusCache = options.waitStatusCache ?? new WaitStatusCache();
 	}
 
 	/** Read the resolved socket path. Available after start() resolves. */
@@ -362,6 +438,13 @@ export class CrewBroker {
 	// ------------------------------------------------------------------------
 
 	private async handleConnection(sock: net.Socket): Promise<void> {
+		// B1 (Round 14): a connection event queued after stop() must not be
+		// processed — the broker is shutting down and the token registry is
+		// already cleared. Destroy (not end) since the server is stopping.
+		if (this.stopped) {
+			sock.destroy();
+			return;
+		}
 		const conn: ServerConnection = {
 			socket: sock,
 			decoder: new NdjsonDecoder(),
@@ -369,6 +452,7 @@ export class CrewBroker {
 			runId: undefined,
 			taskId: undefined,
 			role: undefined,
+			authMatchKind: undefined,
 			outbound: [],
 			needsResync: false,
 			closed: false,
@@ -425,7 +509,12 @@ export class CrewBroker {
 			const set = this.connectionsByRun.get(conn.runId);
 			if (set) {
 				set.delete(conn);
-				if (set.size === 0) this.connectionsByRun.delete(conn.runId);
+				if (set.size === 0) {
+					this.connectionsByRun.delete(conn.runId);
+					// R10-3: no more waiters for this run — drop its stat-gated
+					// manifest cache entry so the Map stays bounded across runs.
+					this.waitStatusCache.delete(conn.runId);
+				}
 			}
 		}
 		// Phase 2: tear down any per-connection event subscriptions.
@@ -544,6 +633,21 @@ export class CrewBroker {
 			case "escalate":
 				await this.handleEscalate(conn, id, params);
 				return;
+			// WP-2/R2 (ADR-0 2026-08-17-waiting-producer-ask items 3,6,7):
+			// waiting-producer park/resolve. Task-scoped tokens only;
+			// capability-gated via options.waitMethodsEnabled (fail-closed).
+			case "wait.request":
+				await this.handleWaitRequest(conn, id, params);
+				return;
+			case "wait.resolve":
+				await this.handleWaitResolve(conn, id, params);
+				return;
+			// T3/R5 (ADR-5 §1): governed-nesting delegation. Task-scoped tokens
+			// only; capability-gated via options.nestingEnabled (fail-closed);
+			// admission runs the full spawn-policy gate matrix.
+			case "delegate.request":
+				await this.handleDelegateRequest(conn, id, params);
+				return;
 			default:
 				// Unhandled method → typed not-implemented.
 				this.sendError(conn, id, "not-implemented", `method '${method}' is not implemented`);
@@ -571,8 +675,11 @@ export class CrewBroker {
 		// vs worker), never from a self-declared hello field (F-06: otherwise a
 		// worker could forge role:'orchestrator' and call steer.push/msg.send).
 		// Constant-time compare; never include the token in the error path.
-		const role = this.tokens.tokenRole(runId, taskId, token);
-		if (role === null) {
+		// WP-2/R2 (ADR-0 item 6): the match KIND is recorded on the connection
+		// (compound vs legacy bare-runId fallback) so wait.* can enforce the
+		// task-scoped-token rule without retaining the secret candidate.
+		const resolved = this.tokens.tokenRoleWithMatchKind(runId, taskId, token);
+		if (resolved === null) {
 			this.sendErrorAndClose(conn, id, "auth", "hello rejected");
 			return;
 		}
@@ -591,7 +698,8 @@ export class CrewBroker {
 		conn.authed = true;
 		conn.runId = runId;
 		conn.taskId = taskId;
-		conn.role = role;
+		conn.role = resolved.role;
+		conn.authMatchKind = resolved.matchKind;
 		// Phase 1.3: index by runId for live mailbox fanout.
 		let connsForRun = this.connectionsByRun.get(runId);
 		if (!connsForRun) {
@@ -980,7 +1088,7 @@ export class CrewBroker {
 			this.sendError(conn, id, "bad-params", "task.waitStatus: taskId out of range");
 			return;
 		}
-		const validStatuses = new Set(["queued", "running", "completed", "failed", "blocked", "cancelled"]);
+		const validStatuses = new Set(["queued", "running", "waiting", "completed", "failed", "blocked", "cancelled"]);
 		if (!validStatuses.has(targetStatus)) {
 			this.sendError(conn, id, "bad-params", `task.waitStatus: invalid until '${targetStatus}'`);
 			return;
@@ -1012,7 +1120,9 @@ export class CrewBroker {
 						return;
 					}
 					try {
-						const loaded = loadRunManifestById(cwd, connRunId);
+						// R10-3: stat-gated cache — parse only when manifest/tasks
+						// mtime/size changed; identical observable behavior per poll.
+						const loaded = this.waitStatusCache.load(cwd, connRunId);
 						if (!loaded) {
 							this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
 							resolve();
@@ -1184,6 +1294,660 @@ export class CrewBroker {
 			this.sendError(conn, id, "escalate-failed", (err as Error).message);
 		}
 	}
+
+	// ------------------------------------------------------------------------
+	// 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. */
+	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;
+	}
+
+	/** 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. */
+	// 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;
+	}
+
+	private recordDelegateEvent(
+		manifest: { eventsPath: string; runId: string },
+		type:
+			| "delegate.requested"
+			| "delegate.admitted"
+			| "delegate.rejected"
+			| "delegate.completed"
+			| "delegate.timed_out"
+			| "delegate.rolled_up",
+		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}`),
+		);
+	}
+
+	private async handleDelegateRequest(conn: ServerConnection, id: string, params: unknown): Promise<void> {
+		// Auth: task-scoped token MANDATORY (ADR-5 pin iii) — same rule as wait.*.
+		if (!conn.runId || !conn.taskId) {
+			this.sendError(conn, id, "auth", "not authed");
+			return;
+		}
+		if (conn.role !== "worker" || conn.authMatchKind !== "compound") {
+			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");
+			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 cwd = this.options.cwd;
+		if (!cwd) {
+			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+			return;
+		}
+		let loaded: NonNullable<ReturnType<typeof loadRunManifestById>>;
+		try {
+			const l = loadRunManifestById(cwd, conn.runId);
+			if (!l) {
+				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+				return;
+			}
+			loaded = l;
+		} catch (err) {
+			this.sendError(conn, id, "no-manifest", (err as Error).message);
+			return;
+		}
+		// Capability gate (ADR-5 §10): fail-closed, NEVER silent.
+		if (this.options.nestingEnabled !== true) {
+			this.recordDelegateEvent(loaded.manifest, "delegate.rejected", conn.taskId, {
+				reason: "nesting-disabled",
+				policy: "nesting.enabled=false (fail-closed default)",
+			});
+			this.sendError(
+				conn,
+				id,
+				"policy-disabled",
+				"delegate is disabled: nesting.enabled=false (fail-closed default; delegate.rejected recorded in events.jsonl)",
+			);
+			return;
+		}
+		const runId = conn.runId;
+		const parentTaskId = conn.taskId;
+		// S1#1 fix (security round 1): the subId is minted BEFORE admission so the
+		// grandchild token scopes to the SUBID (never the parent task key) and the
+		// nested slot is acquired INSIDE the same lock as the admission snapshot.
+		const subId = `gc-${randomUUID()}`;
+		this.recordDelegateEvent(loaded.manifest, "delegate.requested", parentTaskId, { subId, role: requested.role ?? "explorer" });
+		// Admission: full spawn-policy matrix (ADR-5 §2-§7), parent state from
+		// the RECORD under the run lock — never the worker's env/self-report.
+		const admissionOutcome = withRunLockSync(loaded.manifest, () => {
+			const fresh = loadRunManifestById(loaded.manifest.cwd, runId);
+			if (!fresh) return { code: "no-manifest" as const, message: `run '${runId}' not found` };
+			const task = fresh.tasks.find((t) => t.id === parentTaskId);
+			if (!task) {
+				this.recordDelegateEvent(fresh.manifest, "delegate.rejected", parentTaskId, { subId, reason: "no-task" });
+				return { code: "no-task" as const, message: `task '${parentTaskId}' not found` };
+			}
+			if (task.status !== "running") {
+				this.recordDelegateEvent(fresh.manifest, "delegate.rejected", parentTaskId, {
+					subId,
+					reason: "parent-not-running",
+					message: `task is ${task.status}`,
+				});
+				return { code: "bad-params" as const, message: `delegate: parent task '${parentTaskId}' is ${task.status}, not running` };
+			}
+			const catalog = this.options.modelCatalog?.();
+			// S3 fail-closed: a DEFINED loader yielding undefined is a loader failure.
+			const effectiveCatalog = this.options.modelCatalog !== undefined ? (catalog ?? []) : undefined;
+			// ADR-5 §9: count OTHER in-flight executor-class tasks sharing the
+			// parent task's cwd (manifest record — single source of truth).
+			const overlapping = fresh.tasks.filter(
+				(t) =>
+					t.id !== parentTaskId &&
+					t.status === "running" &&
+					(t.role === "executor" || t.role === "test-engineer") &&
+					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)
+				parentTask: {
+					taskId: parentTaskId,
+					role: task.role,
+					...(task.depth !== undefined ? { depth: task.depth } : {}),
+					...(task.allocation !== undefined ? { allocation: task.allocation } : {}),
+				},
+				slots: this.getDelegateNestedSlots().snapshot(),
+				requested,
+				...(effectiveCatalog !== undefined ? { modelCatalog: effectiveCatalog } : {}),
+				// ADR-5 §12: the delegate surface is an escalation — trusted only by the
+				// explicit user opt-in threaded from config.nesting.enabled (sensitive).
+				untrusted: this.options.nestingTrustedEscalation !== true,
+				workspace: {
+					serializeEnabled: this.options.serializeOnPathOverlap === true,
+					overlappingInFlightExecutors: overlapping,
+				},
+			});
+			if (!decision.allowed) {
+				this.recordDelegateEvent(fresh.manifest, "delegate.rejected", parentTaskId, {
+					subId,
+					reason: decision.reason,
+					message: (decision.message ?? "").slice(0, 120),
+				});
+				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)) {
+				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}`,
+				};
+			}
+			// Reserve the requested budget pessimistically (ADR-5 §5): tokensSpent
+			// += budgetTokens now; the completion roll-up reconciles to actual usage
+			// (refund the difference). Single writer under the run lock.
+			let reserved = 0;
+			const parentAllocation = task.allocation;
+			let tasksAfterReserve = fresh.tasks;
+			if (requested.budgetTokens !== undefined && parentAllocation) {
+				reserved = requested.budgetTokens;
+				const updatedTasks = fresh.tasks.map((t) =>
+					t.id === parentTaskId
+						? {
+								...t,
+								allocation: {
+									tokensGranted: parentAllocation.tokensGranted,
+									tokensSpent: (parentAllocation.tokensSpent ?? 0) + reserved,
+								},
+							}
+						: t,
+				);
+				tasksAfterReserve = updatedTasks;
+				saveRunTasks(fresh.manifest, updatedTasks);
+			}
+			// S1#1: register the grandchild SHADOW TASK — the subId identity gets a
+			// real depth/role entry (unbounded-chain fix). Built on tasksAfterReserve
+			// so the budget reservation above is never clobbered.
+			saveRunTasks(fresh.manifest, [
+				...tasksAfterReserve,
+				{
+					id: subId,
+					runId,
+					role: requested.role ?? "explorer",
+					agent: "delegate",
+					title: `delegate: ${(requested as { description?: string }).description ?? subId}`,
+					status: "queued",
+					cwd: task.cwd,
+					dependsOn: [],
+					depth: decision.childDepth ?? 2,
+					startedAt: new Date().toISOString(),
+				} satisfies TeamTaskState,
+			]);
+			return { code: "ok" as const, decision, reserved };
+		});
+		if (admissionOutcome.code !== "ok") {
+			this.sendError(conn, id, admissionOutcome.code, admissionOutcome.message);
+			return;
+		}
+		const { decision, reserved } = admissionOutcome;
+		this.recordDelegateEvent(loaded.manifest, "delegate.admitted", parentTaskId, {
+			subId,
+			childDepth: decision.childDepth,
+			role: requested.role ?? "explorer",
+			...(reserved > 0 ? { reservedTokens: reserved } : {}),
+		});
+		// S1#1: pre-mint the grandchild-scoped token when (and only when) the
+		// child may itself delegate (childDepth < resolved maxDepth — the same
+		// gate as issueForChild). Depth-2 at default maxDepth gets NO creds.
+		const grandchildCreds =
+			(decision.childDepth ?? 2) < (this.options.nestingMaxDepth ?? resolveCrewMaxDepth(undefined))
+				? { socketPath: this.socketPath, token: this.issueRunToken(runId, subId) }
+				: undefined;
+		// Return IMMEDIATELY (principle 7): the tool self-polls the mailbox.
+		this.sendResult(conn, id, { ok: true, grandchildTaskRef: subId, childDepth: decision.childDepth, timeoutSec: decision.timeoutSec });
+		// Background grandchild lifecycle (ADR-5 §1/§6).
+		const spawner = this.options.grandchildSpawner ?? spawnDelegateGrandchild;
+		void (async () => {
+			let outcome: GrandchildSpawnResult;
+			try {
+				outcome = await spawner({
+					cwd,
+					runId,
+					parentTaskId,
+					subId,
+					prompt: requested.prompt,
+					eventsPath: loaded.manifest.eventsPath,
+					role: requested.role ?? "explorer",
+					...(grandchildCreds ? { brokerSpawn: grandchildCreds } : {}),
+					...(requested.model !== undefined ? { model: requested.model } : {}),
+					...(requested.maxTurns !== undefined ? { maxTurns: requested.maxTurns } : {}),
+					timeoutSec: decision.timeoutSec ?? 900,
+					depthOverride: decision.childDepth ?? 2,
+				});
+			} catch (err) {
+				outcome = { ok: false, resultText: `delegate spawn failed: ${(err as Error).message}` };
+			}
+			// S3 fence hardening: neutralize smuggled end-fence markers in the
+			// grandchild's raw text, then wrap (the client re-fences too — the
+			// mailbox is an unauthenticated same-uid channel by design).
+			const sanitizedText = outcome.resultText.replace(/^--- (end )?delegate /gm, "-- ~delegate ").slice(0, 65_536);
+			const fenced = `--- delegate ${subId} ${outcome.timedOut ? "(timed out)" : outcome.ok ? "(ok)" : "(failed)"} ---\n${sanitizedText}\n--- end delegate ${subId} ---`;
+			// Durable delivery (ADR-5 §1): fenced result into the PARENT task's
+			// mailbox + budget roll-up + slot release — run-locked RMW.
+			try {
+				const fresh = loadRunManifestById(cwd, runId);
+				if (fresh) {
+					withRunLockSync(fresh.manifest, () => {
+						const latest = loadRunManifestById(cwd, runId);
+						if (!latest) return;
+						void appendMailboxMessageAsync(latest.manifest, {
+							direction: "inbox",
+							from: `delegate:${subId}`,
+							to: parentTaskId,
+							taskId: parentTaskId,
+							body: fenced,
+							kind: "response",
+							data: { subId, ok: outcome.ok, timedOut: outcome.timedOut === true },
+						}).catch((err) =>
+							logInternalError(
+								"crew-broker.delegate.mailbox",
+								err instanceof Error ? err : new Error(String(err)),
+								`runId=${runId}`,
+							),
+						);
+						// Roll-up (ADR-5 §5): reconcile the pessimistic reservation to
+						// actual usage; refund the difference. Unattributed → keep reserve.
+						let tasksToWrite = latest.tasks;
+						if (reserved > 0) {
+							const parent = latest.tasks.find((t) => t.id === parentTaskId);
+							const parentAlloc = parent?.allocation;
+							if (parentAlloc) {
+								const actual = Math.max(0, Math.min(outcome.usageTokens ?? reserved, reserved));
+								const tokensSpent = (parentAlloc.tokensSpent ?? 0) - reserved + actual;
+								tasksToWrite = tasksToWrite.map((t) =>
+									t.id === parentTaskId
+										? { ...t, allocation: { tokensGranted: parentAlloc.tokensGranted, tokensSpent } }
+										: t,
+								);
+								this.recordDelegateEvent(latest.manifest, "delegate.rolled_up", parentTaskId, {
+									subId,
+									actualTokens: actual,
+								});
+							}
+						}
+						// S1#1: flip the shadow task to terminal — UNCONDITIONAL (verifier N1): the
+						// flip must not depend on a reservation; no allocation producer ships
+						// yet so reserved===0 is the common case and the guard left every
+						// shadow "queued" forever.
+						// S1#1: flip the shadow task to terminal so the subId record does not
+						// linger as "queued" in team status views.
+						saveRunTasks(
+							latest.manifest,
+							tasksToWrite.map((t) =>
+								t.id === subId
+									? {
+											...t,
+											status: outcome.ok ? ("completed" as const) : ("failed" as const),
+											completedAt: new Date().toISOString(),
+										}
+									: t,
+							),
+						);
+					});
+				}
+			} catch (err) {
+				logInternalError("crew-broker.delegate.finalize", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`);
+				// P2-8c: best-effort refund when finalize fails — the reservation
+				// must not linger inflated after a roll-up write failure.
+				if (reserved > 0) {
+					try {
+						const rf = loadRunManifestById(cwd, runId);
+						if (rf) {
+							withRunLockSync(rf.manifest, () => {
+								const rl = loadRunManifestById(cwd, runId);
+								if (!rl) return;
+								const par = rl.tasks.find((t) => t.id === parentTaskId);
+								const pa = par?.allocation;
+								if (pa) {
+									saveRunTasks(
+										rl.manifest,
+										rl.tasks.map((t) =>
+											t.id === parentTaskId
+												? {
+														...t,
+														allocation: {
+															tokensGranted: pa.tokensGranted,
+															tokensSpent: Math.max(0, (pa.tokensSpent ?? 0) - reserved),
+														},
+													}
+												: t,
+										),
+									);
+								}
+							});
+						}
+					} catch {
+						/* refund is best-effort; the startup reconcile is the follow-up */
+					}
+				}
+			} finally {
+				this.getDelegateNestedSlots().release(subId);
+			}
+			this.recordDelegateEvent(loaded.manifest, outcome.timedOut ? "delegate.timed_out" : "delegate.completed", parentTaskId, {
+				subId,
+				ok: outcome.ok,
+			});
+		})();
+	}
+
+	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}`),
+		);
+	}
+
+	/** WP-2/R2 step 4: park the calling task while its `ask` tool awaits a
+	 *  leader answer. Park = task.status "waiting" + task.waiting marker +
+	 *  manifest.waitState pointer; manifest.status NEVER flips (stays
+	 *  "running" — registry entry, sidebar visibility and
+	 *  live-executor.isCurrent() all preserved; ADR item 3). Writes happen
+	 *  under withRunLockSync with a fresh reload (respond.ts:42-43 discipline).
+	 *  deadline = now + min(timeoutSec, 3600): the SERVER clamps —
+	 *  worker-controlled timeoutSec may never exceed 1h (ADR P2-7). */
+	private async handleWaitRequest(conn: ServerConnection, id: string, params: unknown): Promise<void> {
+		if (!conn.runId || !conn.taskId) {
+			this.sendError(conn, id, "auth", "not authed");
+			return;
+		}
+		const authErr = this.waitAuthError(conn);
+		if (authErr) {
+			this.sendError(conn, id, authErr.code, authErr.message);
+			return;
+		}
+		const parsed = parseWaitRequestParams(params);
+		if (!parsed) {
+			this.sendError(conn, id, "bad-params", "wait.request: invalid params");
+			return;
+		}
+		// Server-side identity enforcement: `to` MUST equal the authenticated
+		// task — a worker may only park ITSELF. (The escalate handler's
+		// unvalidated `to` is the recorded anti-pattern; do NOT replicate.)
+		if (parsed.to !== conn.taskId) {
+			this.sendError(conn, id, "forbidden", "wait.request: 'to' must match the authenticated task");
+			return;
+		}
+		const cwd = this.options.cwd;
+		if (!cwd) {
+			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+			return;
+		}
+		let loaded: NonNullable<ReturnType<typeof loadRunManifestById>>;
+		try {
+			const l = loadRunManifestById(cwd, conn.runId);
+			if (!l) {
+				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+				return;
+			}
+			loaded = l;
+		} catch (err) {
+			this.sendError(conn, id, "no-manifest", (err as Error).message);
+			return;
+		}
+		// Capability gate (ADR item 7): fail-closed, NEVER silent — every
+		// rejection leaves a policy.action trace in the run's events.jsonl.
+		if (this.options.waitMethodsEnabled !== true) {
+			this.recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.request");
+			this.sendError(
+				conn,
+				id,
+				"policy-disabled",
+				"wait.request is disabled: broker.waitMethodsEnabled=false (fail-closed; policy.action recorded in events.jsonl)",
+			);
+			return;
+		}
+		// Server clamp BEFORE any state write (ADR P2-7).
+		const requestedSec = parsed.timeoutSec ?? WAIT_REQUEST_TIMEOUT_SEC_DEFAULT;
+		const clampSec = Math.min(Math.max(1, Math.floor(requestedSec)), WAIT_REQUEST_TIMEOUT_SEC_MAX);
+		const clamped = requestedSec > clampSec;
+		const questionId = randomUUID();
+		const askedAt = new Date().toISOString();
+		const deadline = Date.now() + clampSec * 1000;
+		const runId = conn.runId;
+		const taskId = conn.taskId;
+		const outcome = withRunLockSync(loaded.manifest, () => {
+			// Fresh reload INSIDE the lock (respond.ts:42-43 discipline).
+			const fresh = loadRunManifestById(loaded.manifest.cwd, runId);
+			if (!fresh) return { code: "no-manifest" as const, message: `run '${runId}' not found` };
+			const task = fresh.tasks.find((t) => t.id === taskId);
+			if (!task) return { code: "no-task" as const, message: `task '${taskId}' not found` };
+			if (task.status !== "running") {
+				return { code: "bad-params" as const, message: `wait.request: task '${taskId}' is ${task.status}, not running` };
+			}
+			const updatedTasks = fresh.tasks.map((t) =>
+				t.id === taskId
+					? {
+							...t,
+							status: "waiting" as const,
+							waiting: {
+								questionId,
+								askedAt,
+								deadline,
+								...(parsed.options ? { options: parsed.options } : {}),
+							},
+						}
+					: t,
+			);
+			const updatedManifest = {
+				...fresh.manifest,
+				// manifest.status stays "running" — park NEVER flips run status (ADR item 3).
+				waitState: { taskId, questionId, askedAt },
+				updatedAt: askedAt,
+			};
+			saveRunTasks(updatedManifest, updatedTasks);
+			saveRunManifest(updatedManifest);
+			return { code: "ok" as const, message: "" };
+		});
+		if (outcome.code !== "ok") {
+			this.sendError(conn, id, outcome.code, outcome.message);
+			return;
+		}
+		// Events AFTER the run lock is released (the event-log lock is a
+		// separate lock; no cross-lock ordering). task.waiting mirrors the
+		// persisted status flip for event-log reconstruction (tasks.json
+		// corruption recovery); ask.requested carries the question for the
+		// leader/UI. Fire-and-forget: an event failure must not fail the park.
+		const eventsPath = loaded.manifest.eventsPath;
+		void appendEventAsync(eventsPath, {
+			type: "task.waiting",
+			runId,
+			taskId,
+			message: `Task parked awaiting leader answer (question ${questionId}, deadline in ${clampSec}s).`,
+			data: { questionId, deadline },
+		}).catch((err) =>
+			logInternalError("crew-broker.wait.task-waiting-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+		);
+		void appendEventAsync(eventsPath, {
+			type: "ask.requested",
+			runId,
+			taskId,
+			message: parsed.question,
+			data: {
+				questionId,
+				deadline,
+				timeoutSec: clampSec,
+				clamped,
+				...(parsed.options ? { options: parsed.options } : {}),
+			},
+		}).catch((err) =>
+			logInternalError("crew-broker.wait.ask-requested-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+		);
+		this.sendResult(conn, id, {
+			ok: true,
+			questionId,
+			askedAt,
+			deadline,
+			timeoutSec: clampSec,
+			clamped,
+		});
+	}
+
+	/** WP-2/R2: terminal report of the parked `ask` tool — flips the task
+	 *  waiting→running and clears the park coordination state. Scoped to
+	 *  auth + state transition + ask.answered event ONLY (ADR item 6/8):
+	 *  answer DELIVERY is the mailbox respond path (step 6), not this
+	 *  method. A questionId mismatch (or a task that is not parked) is
+	 *  rejected WITHOUT clearing anything — fail-closed. */
+	private async handleWaitResolve(conn: ServerConnection, id: string, params: unknown): Promise<void> {
+		if (!conn.runId || !conn.taskId) {
+			this.sendError(conn, id, "auth", "not authed");
+			return;
+		}
+		const authErr = this.waitAuthError(conn);
+		if (authErr) {
+			this.sendError(conn, id, authErr.code, authErr.message);
+			return;
+		}
+		const parsed = parseWaitResolveParams(params);
+		if (!parsed) {
+			this.sendError(conn, id, "bad-params", "wait.resolve: invalid params");
+			return;
+		}
+		// Server-side identity enforcement (same rule as wait.request).
+		if (parsed.to !== conn.taskId) {
+			this.sendError(conn, id, "forbidden", "wait.resolve: 'to' must match the authenticated task");
+			return;
+		}
+		const cwd = this.options.cwd;
+		if (!cwd) {
+			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+			return;
+		}
+		let loaded: NonNullable<ReturnType<typeof loadRunManifestById>>;
+		try {
+			const l = loadRunManifestById(cwd, conn.runId);
+			if (!l) {
+				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+				return;
+			}
+			loaded = l;
+		} catch (err) {
+			this.sendError(conn, id, "no-manifest", (err as Error).message);
+			return;
+		}
+		if (this.options.waitMethodsEnabled !== true) {
+			this.recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.resolve");
+			this.sendError(
+				conn,
+				id,
+				"policy-disabled",
+				"wait.resolve is disabled: broker.waitMethodsEnabled=false (fail-closed; policy.action recorded in events.jsonl)",
+			);
+			return;
+		}
+		const runId = conn.runId;
+		const taskId = conn.taskId;
+		const outcome = withRunLockSync(loaded.manifest, () => {
+			const fresh = loadRunManifestById(loaded.manifest.cwd, runId);
+			if (!fresh) return { code: "no-manifest" as const, message: `run '${runId}' not found` };
+			const task = fresh.tasks.find((t) => t.id === taskId);
+			if (!task) return { code: "no-task" as const, message: `task '${taskId}' not found` };
+			if (task.status !== "waiting" || task.waiting?.questionId !== parsed.questionId) {
+				return {
+					code: "bad-params" as const,
+					message: `wait.resolve: no parked question '${parsed.questionId}' on task '${taskId}'`,
+				};
+			}
+			const updatedTasks = fresh.tasks.map((t) => (t.id === taskId ? { ...t, status: "running" as const, waiting: undefined } : t));
+			// waitState is a single run-level slot: clear it ONLY when it points
+			// at this exact question — never clobber another task's newer park.
+			const waitState = fresh.manifest.waitState;
+			const clearWaitState = waitState !== undefined && waitState.taskId === taskId && waitState.questionId === parsed.questionId;
+			const updatedManifest = {
+				...fresh.manifest,
+				...(clearWaitState ? { waitState: undefined } : {}),
+				updatedAt: new Date().toISOString(),
+			};
+			saveRunTasks(updatedManifest, updatedTasks);
+			saveRunManifest(updatedManifest);
+			return { code: "ok" as const, message: "" };
+		});
+		if (outcome.code !== "ok") {
+			this.sendError(conn, id, outcome.code, outcome.message);
+			return;
+		}
+		const eventsPath = loaded.manifest.eventsPath;
+		void appendEventAsync(eventsPath, {
+			type: "ask.answered",
+			runId,
+			taskId,
+			message: `Question ${parsed.questionId} answered; task resumed.`,
+			data: { questionId: parsed.questionId },
+		}).catch((err) =>
+			logInternalError("crew-broker.wait.ask-answered-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+		);
+		void appendEventAsync(eventsPath, {
+			type: "task.resumed",
+			runId,
+			taskId,
+			message: `Task resumed after ask answer (question ${parsed.questionId}).`,
+			data: { questionId: parsed.questionId },
+		}).catch((err) =>
+			logInternalError("crew-broker.wait.task-resumed-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+		);
+		this.sendResult(conn, id, { ok: true, taskId, questionId: parsed.questionId });
+	}
 }
 
 // ============================================================================
@@ -1278,3 +2042,67 @@ function safeStringify(value: unknown): string {
 		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 };
+}