pi-crew 0.11.1 → 0.11.4

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

@@ -28,7 +28,7 @@ import { withRunLockSync } from "../../state/coordination/locks.ts";
 import { appendMailboxMessageAsync, type MailboxMessage, registerMailboxAppendObserver } from "../../state/coordination/mailbox.ts";
 import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../../state/stores/state-store.ts";
-import type { TeamTaskState } from "../../state/types.ts";
+import type { TeamRunManifest, 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";
@@ -40,10 +40,12 @@ import { resolveCrewMaxDepth } from "../model/pi-args.ts";
 import { NestedSlotBudget } from "../scheduling/nested-slots.ts";
 import { evaluateDelegateAdmission } from "../spawn-policy.ts";
 import { type BrokerToken, BrokerTokenRegistry } from "./crew-broker-tokens.ts";
-import { recordDelegateEvent } from "./delegate/delegate-event.ts";
+import { type DelegateEventTarget, type DelegateEventType, recordDelegateEvent } from "./delegate/delegate-event.ts";
+import { promoteShadowToRunning } from "./delegate/shadow-lifecycle.ts";
 import { fanoutMailboxMessage } from "./mailbox-observer/mailbox-fanout.ts";
 import type { CrewBrokerOptions, ServerConnection } from "./protocol/connection-state.ts";
 import { handleEventsSince } from "./protocol/events-replay.ts";
+import { DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS, type LockBusyOutcome, withRunLockBusyRetry } from "./protocol/lock-busy.ts";
 import { loadRunForHello } from "./protocol/manifest-loader.ts";
 import { handleMsgInbox } from "./protocol/msg-inbox.ts";
 import {
@@ -103,6 +105,7 @@ export class CrewBroker {
 			| "grandchildSpawner"
 			| "modelCatalog"
 			| "serializeOnPathOverlap"
+			| "lockBusyRetryDelaysMs"
 		>;
 	private readonly tokens = new BrokerTokenRegistry();
 	/** Task 10 (mux-surface A1 §5.2): taskId → the compound token most
@@ -1331,28 +1334,31 @@ export class CrewBroker {
 	}
 
 	// WP-2/R2: wait.request / wait.resolve (ADR-0 2026-08-17-waiting-producer-ask)
+	// waitAuthError: imported directly from protocol/wait-auth.ts (M4/WI-4.1).
 
-	// waitAuthError: protocol/wait-auth.ts (M4/WI-4.1).
-	private waitAuthError(conn: ServerConnection): { code: string; message: string } | null {
-		return waitAuthError(conn);
-	}
-
-	// (The "ADR item 7" doc that used to dangle here documents
-	// recordWaitPolicyRejection — see wait-auth.ts, where it belongs.
-	// Removed 2026-09-10, review F6.)
 	// T3/R5 (ADR-5): delegate.request — governed-nesting admission + background
 	// grandchild spawn with durable mailbox delivery (WP-5 step 5).
-	// getDelegateNestedSlots: inlined at 4 call sites (5-line method; M4/WI-4.1).
+
+	/** ADR-5 §5: lazy singleton for the nested-slot budget — first use
+	 *  constructs it from the broker options (4 call sites previously
+	 *  inlined this IIFE). */
+	private nestedSlotBudget(): NestedSlotBudget {
+		if (!this.nestedSlots)
+			this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
+		return this.nestedSlots;
+	}
+
+	/** RR-023 F4: bounded busy-retry around a run-locked RMW (see
+	 *  protocol/lock-busy.ts) — options override or the default schedule.
+	 *  A busy-exhausted result is the handler's cue to answer a typed `busy`
+	 *  frame (connection survives) instead of letting the throw kill it. */
+	private runLockBusyRetry<T>(manifest: TeamRunManifest, fn: () => T): Promise<LockBusyOutcome<T>> {
+		return withRunLockBusyRetry(manifest, this.options.lockBusyRetryDelaysMs ?? DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS, fn);
+	}
 
 	private recordDelegateEvent(
-		manifest: { eventsPath: string; runId: string },
-		type:
-			| "delegate.requested"
-			| "delegate.admitted"
-			| "delegate.rejected"
-			| "delegate.completed"
-			| "delegate.timed_out"
-			| "delegate.rolled_up",
+		manifest: DelegateEventTarget,
+		type: DelegateEventType,
 		taskId: string,
 		data: Record<string, unknown>,
 	): void {
@@ -1433,7 +1439,8 @@ export class CrewBroker {
 		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, () => {
+		// RR-023 F4: run-locked via bounded busy-retry (protocol/lock-busy.ts).
+		const admissionAttempt = await this.runLockBusyRetry(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);
@@ -1449,6 +1456,10 @@ export class CrewBroker {
 				});
 				return { code: "bad-params" as const, message: `delegate: parent task '${parentTaskId}' is ${task.status}, not running` };
 			}
+			// RR-012 F03: authoritative execution cwd = the parent task's cwd from
+			// this locked fresh read — ONE source for overlap check, shadow record
+			// and spawner input; broker cwd stays for manifest lookup only.
+			const executionCwd = task.cwd;
 			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;
@@ -1459,7 +1470,7 @@ export class CrewBroker {
 					t.id !== parentTaskId &&
 					t.status === "running" &&
 					(t.role === "executor" || t.role === "test-engineer") &&
-					t.cwd === task.cwd,
+					t.cwd === executionCwd,
 			).length;
 			const decision = evaluateDelegateAdmission({
 				maxDepth: this.options.nestingMaxDepth ?? resolveCrewMaxDepth(undefined), // config knob > env-clamped 1..10, default 4 (D8; ADR-5 §3)
@@ -1469,11 +1480,7 @@ export class CrewBroker {
 					...(task.depth !== undefined ? { depth: task.depth } : {}),
 					...(task.allocation !== undefined ? { allocation: task.allocation } : {}),
 				},
-				slots: (() => {
-					if (!this.nestedSlots)
-						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
-					return this.nestedSlots;
-				})().snapshot(),
+				slots: this.nestedSlotBudget().snapshot(),
 				requested,
 				...(effectiveCatalog !== undefined ? { modelCatalog: effectiveCatalog } : {}),
 				// ADR-5 §12: the delegate surface is an escalation — trusted only by the
@@ -1493,28 +1500,11 @@ export class CrewBroker {
 				return { code: "policy-denied" as const, message: decision.message ?? decision.reason ?? "delegate denied" };
 			}
 			// Slot acquisition INSIDE the lock (no reserve-then-race refund window).
-			if (
-				!(() => {
-					if (!this.nestedSlots)
-						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
-					return this.nestedSlots;
-				})().tryAcquire(subId)
-			) {
+			if (!this.nestedSlotBudget().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; ${
-						(
-							() => {
-								if (!this.nestedSlots)
-									this.nestedSlots = new NestedSlotBudget(
-										this.options.globalWorkerSemaphore ?? 4,
-										this.options.nestingMaxSlots,
-									);
-								return this.nestedSlots;
-							}
-						)().statusLine
-					}`,
+					message: `delegate rejected: nested spawn budget exhausted; ${this.nestedSlotBudget().statusLine}`,
 				};
 			}
 			// Reserve the requested budget pessimistically (ADR-5 §5): tokensSpent
@@ -1551,19 +1541,29 @@ export class CrewBroker {
 					agent: "delegate",
 					title: `delegate: ${(requested as { description?: string }).description ?? subId}`,
 					status: "queued",
-					cwd: task.cwd,
+					cwd: executionCwd,
 					dependsOn: [],
 					depth: decision.childDepth ?? 2,
 					startedAt: new Date().toISOString(),
 				} satisfies TeamTaskState,
 			]);
-			return { code: "ok" as const, decision, reserved };
+			// RR-023 F3: thread the parent's model out of the locked read (gc fallback).
+			return { code: "ok" as const, decision, reserved, executionCwd, parentModel: task.model };
 		});
+		// RR-023 F4 (finding #4): run.lock held by a live cross-process holder —
+		// degrade to a typed busy frame AND a delegate.rejected event (never
+		// silent); the connection survives (ping still answers).
+		if (!admissionAttempt.ok) {
+			this.recordDelegateEvent(loaded.manifest, "delegate.rejected", parentTaskId, { subId, reason: "run-lock-busy" });
+			this.sendError(conn, id, "busy", admissionAttempt.message);
+			return;
+		}
+		const admissionOutcome = admissionAttempt.value;
 		if (admissionOutcome.code !== "ok") {
 			this.sendError(conn, id, admissionOutcome.code, admissionOutcome.message);
 			return;
 		}
-		const { decision, reserved } = admissionOutcome;
+		const { decision, reserved, executionCwd, parentModel } = admissionOutcome;
 		this.recordDelegateEvent(loaded.manifest, "delegate.admitted", parentTaskId, {
 			subId,
 			childDepth: decision.childDepth,
@@ -1579,13 +1579,16 @@ export class CrewBroker {
 				: 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 });
+		// RR-023 F3 (finding #3, run team_20260929041427): model-less gc spawn fell
+		// through to the pi GLOBAL default — inherit the parent task's model.
+		const gcModel = requested.model ?? parentModel;
 		// Background grandchild lifecycle (ADR-5 §1/§6).
 		const spawner = this.options.grandchildSpawner ?? spawnDelegateGrandchild;
 		void (async () => {
 			let outcome: GrandchildSpawnResult;
 			try {
 				outcome = await spawner({
-					cwd,
+					cwd: executionCwd,
 					runId,
 					parentTaskId,
 					subId,
@@ -1593,10 +1596,14 @@ export class CrewBroker {
 					eventsPath: loaded.manifest.eventsPath,
 					role: requested.role ?? "explorer",
 					...(grandchildCreds ? { brokerSpawn: grandchildCreds } : {}),
-					...(requested.model !== undefined ? { model: requested.model } : {}),
+					...(gcModel !== undefined ? { model: gcModel } : {}),
 					...(requested.maxTurns !== undefined ? { maxTurns: requested.maxTurns } : {}),
 					timeoutSec: decision.timeoutSec ?? 900,
 					depthOverride: decision.childDepth ?? 2,
+					// RR-012 F16: promote shadow queued→running once the process exists.
+					onSpawn: (pid) => {
+						if (pid !== null) promoteShadowToRunning(cwd, runId, subId);
+					},
 				});
 			} catch (err) {
 				outcome = { ok: false, resultText: `delegate spawn failed: ${(err as Error).message}` };
@@ -1649,12 +1656,9 @@ export class CrewBroker {
 								});
 							}
 						}
-						// 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.
+						// S1#1 (verifier N1): the terminal flip is UNCONDITIONAL — never depends
+						// on a reservation. RR-012 F16: onSpawn promotes the record to "running"
+						// during execution; this flip terminalizes every settle path.
 						saveRunTasks(
 							latest.manifest,
 							tasksToWrite.map((t) =>
@@ -1705,11 +1709,7 @@ export class CrewBroker {
 					}
 				}
 			} finally {
-				(() => {
-					if (!this.nestedSlots)
-						this.nestedSlots = new NestedSlotBudget(this.options.globalWorkerSemaphore ?? 4, this.options.nestingMaxSlots);
-					return this.nestedSlots;
-				})().release(subId);
+				this.nestedSlotBudget().release(subId);
 			}
 			this.recordDelegateEvent(loaded.manifest, outcome.timedOut ? "delegate.timed_out" : "delegate.completed", parentTaskId, {
 				subId,
@@ -1718,9 +1718,7 @@ export class CrewBroker {
 		})();
 	}
 
-	private recordWaitPolicyRejection(manifest: { eventsPath: string; runId: string }, taskId: string, method: string): void {
-		recordWaitPolicyRejection(manifest, taskId, method);
-	}
+	// recordWaitPolicyRejection: imported directly from protocol/wait-auth.ts.
 
 	/** WP-2/R2 step 4: park the calling task while its `ask` tool awaits a
 	 *  leader answer. Park = task.status "waiting" + task.waiting marker +
@@ -1735,7 +1733,7 @@ export class CrewBroker {
 			this.sendError(conn, id, "auth", "not authed");
 			return;
 		}
-		const authErr = this.waitAuthError(conn);
+		const authErr = waitAuthError(conn);
 		if (authErr) {
 			this.sendError(conn, id, authErr.code, authErr.message);
 			return;
@@ -1772,7 +1770,7 @@ export class CrewBroker {
 		// 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");
+			recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.request");
 			this.sendError(
 				conn,
 				id,
@@ -1790,7 +1788,8 @@ export class CrewBroker {
 		const deadline = Date.now() + clampSec * 1000;
 		const runId = conn.runId;
 		const taskId = conn.taskId;
-		const outcome = withRunLockSync(loaded.manifest, () => {
+		// RR-023 F4: run-locked via bounded busy-retry (protocol/lock-busy.ts).
+		const outcome = await this.runLockBusyRetry(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` };
@@ -1823,8 +1822,14 @@ export class CrewBroker {
 			saveRunManifest(updatedManifest);
 			return { code: "ok" as const, message: "" };
 		});
-		if (outcome.code !== "ok") {
-			this.sendError(conn, id, outcome.code, outcome.message);
+		// RR-023 F4 (finding #4): run.lock held by a live cross-process holder
+		// (e.g. the detached runner) — typed busy frame, connection survives.
+		if (!outcome.ok) {
+			this.sendError(conn, id, "busy", outcome.message);
+			return;
+		}
+		if (outcome.value.code !== "ok") {
+			this.sendError(conn, id, outcome.value.code, outcome.value.message);
 			return;
 		}
 		// Events AFTER the run lock is released (the event-log lock is a
@@ -1889,7 +1894,7 @@ export class CrewBroker {
 			this.sendError(conn, id, "auth", "not authed");
 			return;
 		}
-		const authErr = this.waitAuthError(conn);
+		const authErr = waitAuthError(conn);
 		if (authErr) {
 			this.sendError(conn, id, authErr.code, authErr.message);
 			return;
@@ -1922,7 +1927,7 @@ export class CrewBroker {
 			return;
 		}
 		if (this.options.waitMethodsEnabled !== true) {
-			this.recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.resolve");
+			recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.resolve");
 			this.sendError(
 				conn,
 				id,

package/src/runtime/broker/delegate/delegate-event.ts

@@ -13,15 +13,19 @@ import { logInternalError } from "../../../utils/internal-error.ts";
 /** Fire-and-forget async append; an append failure is logged, never thrown
  *  (broker handlers must not block the event loop on the sync event-log lock).
  *  See `crew-broker.delegate.event` event scope conventions in ADR-5 §10. */
+export type DelegateEventType =
+	| "delegate.requested"
+	| "delegate.admitted"
+	| "delegate.rejected"
+	| "delegate.completed"
+	| "delegate.timed_out"
+	| "delegate.rolled_up";
+
+export type DelegateEventTarget = { eventsPath: string; runId: string };
+
 export function recordDelegateEvent(
-	manifest: { eventsPath: string; runId: string },
-	type:
-		| "delegate.requested"
-		| "delegate.admitted"
-		| "delegate.rejected"
-		| "delegate.completed"
-		| "delegate.timed_out"
-		| "delegate.rolled_up",
+	manifest: DelegateEventTarget,
+	type: DelegateEventType,
 	taskId: string,
 	data: Record<string, unknown>,
 ): void {

package/src/runtime/broker/delegate/shadow-lifecycle.ts

@@ -0,0 +1,92 @@
+/**
+ * shadow-lifecycle.ts — broker-owned lifecycle for delegate grandchild SHADOW
+ * task records (RR-012, findings F03/F16; ADR-5 §1/§3 S1#1).
+ *
+ * The `delegate.request` handler (crew-broker.ts) mints a `gc-*` shadow task
+ * (agent "delegate", NO stepId) so the subId identity gets a real depth/role
+ * entry. The record is NOT a workflow task: it is managed by the EXTERNAL
+ * grandchild spawner (the broker), never by the workflow scheduler.
+ * isDelegateShadowTask() is the single discriminator the scheduler uses to
+ * keep shadow records out of DAG/batch selection — they carry no stepId, and
+ * dispatching one would throw ResourceNotFound in findStep()/findAgent()
+ * (dispatch-batch.ts; RR-012 §3 reachability proof in
+ * test/unit/runtime/broker/shadow-task-dag-readiness.test.ts).
+ *
+ * BR-09 (discriminator correctness): the marker is STRUCTURAL — the absence of
+ * `stepId` — NOT the agent name. Every scheduler-managed task sets
+ * `stepId: step.id` (state-store.ts materializeTasks), so "no stepId" means
+ * "not a workflow task". The previous test (`agent === "delegate"`) filtered
+ * out any LEGITIMATE workflow task whose resolved agent happens to be named
+ * `delegate` — such a task never entered a batch, was never dispatched, and
+ * finalize-run then marked the whole run `blocked`. (`delegate` is deliberately
+ * NOT in PROTECTED_AGENT_NAMES, so the name itself carries no reserved
+ * meaning.) Backward compatible both ways: legacy persisted shadows also lack
+ * `stepId` (still excluded) and legacy workflow tasks carry one (still
+ * dispatched); no schema change.
+ *
+ * KNOWN overlap (cold-verify): `reconstructTasksFromEventLog`
+ * (manifest-io.ts, ST-4 corruption recovery) also emits tasks WITHOUT `stepId`
+ * — those are classified as shadows and excluded from dispatch selection.
+ * That is fail-closed, and strictly better than the pre-guard behavior
+ * (findStep would throw ResourceNotFound and kill the batch): reconstructed
+ * tasks carry agent "unknown" and no step, so they cannot be dispatched
+ * anyway. Do NOT reuse this predicate to mean "broker shadow" outside
+ * scheduler selection.
+ *
+ * F16 lifecycle contract (broker-owned; every write under the run lock):
+ *   queued    → saved by the admission write (crew-broker.ts handleDelegateRequest)
+ *   running   → promoteShadowToRunning() from the spawner's onSpawn hook the
+ *               moment the grandchild process exists (pid !== null). Idempotent:
+ *               only a record still "queued" is promoted — a terminal flip or a
+ *               stale-reconciler cancel always wins over a late promote.
+ *   completed | failed → the unconditional terminal flip when the spawner
+ *               settles (success, failure, error, timeout — every path).
+ */
+
+import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import { loadRunManifestById, saveRunTasks } from "../../../state/stores/state-store.ts";
+import type { TeamTaskState } from "../../../state/types.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+
+/** Shadow-task discriminator (RR-012 + BR-09): a task record managed by the
+ *  external delegate-broker spawner rather than the workflow scheduler.
+ *
+ *  The marker is STRUCTURAL: shadow records are persisted with NO `stepId`
+ *  (the broker's shadow literal in crew-broker.ts sets none), while every
+ *  scheduler-materialized task sets `stepId: step.id`. A record without a
+ *  stepId cannot be dispatched anyway — `findStep()` matches on `stepId` and
+ *  throws ResourceNotFound — so "no stepId" is exactly the set the scheduler
+ *  must skip. The agent name is NOT part of the predicate (BR-09: a real
+ *  workflow task may legitimately resolve to an agent named `delegate`). */
+export function isDelegateShadowTask(task: Pick<TeamTaskState, "id" | "agent" | "stepId">): boolean {
+	return task.stepId === undefined;
+}
+
+/** F16: queued→running promote, called from the spawner's onSpawn hook when
+ *  the grandchild process exists. Best-effort by design: a failure logs and
+ *  leaves the record as-is — the unconditional terminal flip on settle still
+ *  runs, so a promote failure can never strand a record in "queued" past the
+ *  settle (and depth-3 admission merely stays blocked until then, which is
+ *  the fail-closed direction). */
+export function promoteShadowToRunning(brokerCwd: string, runId: string, subId: string): void {
+	try {
+		const fresh = loadRunManifestById(brokerCwd, runId);
+		if (!fresh) return;
+		withRunLockSync(fresh.manifest, () => {
+			const latest = loadRunManifestById(brokerCwd, runId);
+			if (!latest) return;
+			const shadow = latest.tasks.find((t) => t.id === subId);
+			if (shadow?.status !== "queued") return;
+			saveRunTasks(
+				latest.manifest,
+				latest.tasks.map((t) => (t.id === subId ? { ...t, status: "running" as const } : t)),
+			);
+		});
+	} catch (err) {
+		logInternalError(
+			"crew-broker.delegate.promote-shadow",
+			err instanceof Error ? err : new Error(String(err)),
+			`runId=${runId} subId=${subId}`,
+		);
+	}
+}

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

@@ -55,6 +55,16 @@ export interface CrewBrokerOptions {
 	nestingTrustedEscalation?: boolean;
 	/** Global worker semaphore size, used to size the nested-slot budget. */
 	globalWorkerSemaphore?: number;
+	/** RR-023 F4 (2026-09-29 battery, finding #4): bounded retry schedule
+	 *  (ms) for run.lock contention in the wait.request / delegate.request
+	 *  handlers. A live cross-process holder (e.g. the detached runner
+	 *  persisting task state) makes acquireLockWithRetry throw; instead of
+	 *  letting that escape handleData → closeConnection, the handler retries
+	 *  on this schedule and then answers a typed `busy` error frame with the
+	 *  connection SURVIVING (plus a delegate.rejected event on the delegate
+	 *  path — never silent). Default DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS
+	 *  (50/100/200/400/800). See protocol/lock-busy.ts. */
+	lockBusyRetryDelaysMs?: readonly number[];
 	/** Test seam / alternative spawner for delegate grandchildren. Production
 	 *  uses spawnDelegateGrandchild (direct runChildPi call-site, ADR-5 §2). */
 	grandchildSpawner?: (input: GrandchildSpawnInput) => Promise<GrandchildSpawnResult>;

package/src/runtime/broker/protocol/lock-busy.ts

@@ -0,0 +1,76 @@
+/**
+ * lock-busy.ts — RR-023 F4 (2026-09-29 full battery, finding #4).
+ *
+ * Broker-handler degradation for run.lock contention. Root cause: the
+ * wait.request / delegate.request handlers run their state RMW inside
+ * withRunLockSync; acquireLockWithRetry (locks.ts, canSteal=false) throws
+ * IMMEDIATELY when a live cross-process holder (e.g. the detached runner
+ * persisting task state) owns run.lock, and that throw escaped handleData →
+ * closeConnection — workers saw an untyped `code=close` socket death
+ * (evidence: team_20260929041005 ask-probe / team_20260929041020
+ * delegate-probe, both dead within ~5ms; the SYNC foreground run was the
+ * zero-contention control).
+ *
+ * Fix layer is the broker ONLY — locks.ts steal semantics are the v0.9.26
+ * lock-family invariant and stay untouched (a live holder is never stolen).
+ * Precedent: protocol/request-parsers.ts (M4/WI-4.1 extraction discipline).
+ */
+
+import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import type { TeamRunManifest } from "../../../state/types.ts";
+
+/** Default bounded retry schedule for run.lock contention (ms). Five
+ *  back-off attempts (~1.55s total) absorb a transient holder — e.g. the
+ *  detached runner's state flush — without parking the request. */
+export const DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS: readonly number[] = [50, 100, 200, 400, 800];
+
+/** Match the exact identity locks.ts throws for a LIVE holder on the
+ *  never-steal path (sync acquireLockWithRetry, its async twin, and the
+ *  lockCtx fallthrough): `Run '<basename>' is locked by another operation.`
+ *  Classification is by message identity — locks.ts exports no error class
+ *  (plain Error), and src/state must not be edited from the broker layer. */
+const RUN_LOCK_BUSY_MESSAGE = /^Run '[^']+' is locked by another operation\.$/;
+
+export function isRunLockBusyError(error: unknown): boolean {
+	return error instanceof Error && RUN_LOCK_BUSY_MESSAGE.test(error.message);
+}
+
+/** Result of a run-locked RMW under the busy-retry policy: either the body's
+ *  value, or the typed busy degradation (message derived from the underlying
+ *  lock error — it names run.lock, so it matches /run\.lock|busy/i). */
+export type LockBusyOutcome<T> = { ok: true; value: T } | { ok: false; message: string };
+
+/** Run `fn` under withRunLockSync with a bounded busy-retry.
+ *
+ *  Retry safety: the busy throw is raised by the lock ACQUIRE before `fn`
+ *  runs (locks.ts), and in the broker's wait/delegate bodies every nested
+ *  state write is lockCtx-reentrant (same-context nesting never re-acquires),
+ *  so a retry never re-executes a partially-run body. Any NON-busy error
+ *  propagates unchanged (previous handler behavior for real faults).
+ *  Waits use async sleep — the broker event loop keeps serving other
+ *  connections (and pings) between attempts. */
+export async function withRunLockBusyRetry<T>(
+	manifest: TeamRunManifest,
+	delaysMs: readonly number[],
+	fn: () => T,
+): Promise<LockBusyOutcome<T>> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			return { ok: true, value: withRunLockSync(manifest, fn) };
+		} catch (error) {
+			if (!isRunLockBusyError(error)) throw error;
+			const delay = delaysMs[attempt];
+			if (delay === undefined) {
+				return {
+					ok: false,
+					message: `run.lock busy (bounded retry budget exhausted): ${(error as Error).message}`,
+				};
+			}
+			await sleep(delay);
+		}
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -1,7 +1,7 @@
 /**
  * wait-status-cache.ts — R10-3: mtime+size-gated load cache for task.waitStatus.
  *
- * Problem (docs/refactor-plan.review.md §Round 10, R10-3): the broker's
+ * Problem (docs/archive/refactor-plan.review.md §Round 10, R10-3): the broker's
  * task.waitStatus poll loop ticks every 200ms per waiter and each tick calls
  * loadRunManifestById() — stat manifest + stat tasks + (on the state-store
  * manifest-cache miss, which every write invalidates via generation bump) a

package/src/runtime/child-pi/child-pi-timers.ts

@@ -20,7 +20,7 @@
  * `deps` (values) + `state` (getters/setters over the runChildPi-local flags)
  * so behavior is preserved byte-for-byte.
  *
- * R6-F1 (refactor-plan.review.md §ROUND 6): clearAll() MUST cover all six
+ * R6-F1 (docs/archive/refactor-plan.review.md §ROUND 6): clearAll() MUST cover all six
  * constructs — previously cancelHardKill was a local const inside abort() and
  * was NOT cleared by clearChildPiTimeouts(), leaking a 200 ms unref'd timer per
  * cancel on short-lived children.

package/src/runtime/child-pi/mock-fixtures.ts

@@ -131,6 +131,54 @@ export async function runMockChildPi(
 			stderr: "[MOCK] rate limit: mock failure",
 		};
 
+	// RR-013 (F04) test seam: reproduce the MuxSurface A1 degrade result WITHOUT a
+	// real multiplexer. child-executor's `childResult.surface?.degraded` branch is
+	// the ONLY producer of TaskExecutionResult.surfaceLost, and runTeamTask offers
+	// no seam to inject `surface.providers` (child-executor's runWorker() call
+	// passes no `surface` field), so no other mock mode can reach that branch.
+	//
+	// SCOPE NOTE: this mode does NOT simulate `classifyOnExit` (the 2s window) — it
+	// starts from the exact point where classifyOnExit already returned
+	// `degraded`. That is the correct scope: the F04 defect lives at the
+	// child-executor → task-runner → finalizer boundary, not in classify (which is
+	// covered by degrade.test.ts + child-pi-surface.test.ts).
+	//
+	// Guarded by the existing PI_CREW_ALLOW_MOCK parent-only check above, so it
+	// cannot be activated from a child worker.
+	if (mock === "surface-degraded") {
+		return {
+			exitCode: 0,
+			stdout: "",
+			stderr: "",
+			rawFinalText: "",
+			surface: {
+				kind: "tmux",
+				paneId: "%9",
+				scriptPath: "/tmp/pi-crew-mock-launch.sh",
+				degraded: {
+					cause: "pane-closed",
+					exitReason: "pane-closed",
+					classifiedAt: new Date().toISOString(),
+				},
+			},
+		};
+	}
+
+	// RR-013 (AC-2) test seam: the ONLY result channel carrying text is
+	// `rawFinalText` (stdout/transcript are empty). This reproduces the compaction
+	// scenario the TaskExecutionResult.rawFinalText docstring describes —
+	// parsedOutput.finalText and finalStdout are both empty, so the spec-evidence
+	// footer union can only see the text if rawFinalText survives the
+	// child-executor → task-runner → finalizer boundary.
+	if (mock === "raw-final-text-only") {
+		return {
+			exitCode: 0,
+			stdout: "",
+			stderr: "",
+			rawFinalText: "RR-013 boundary probe result.\n\nSPEC-EVIDENCE:\nacc-1: ran the boundary check\n",
+		};
+	}
+
 	// E2E fallback-chain fixture: invocation #1 returns a SILENT retryable
 	// failure (exit code 0, no real assistant text, message_end carries a
 	// retryable-pattern errorMessage). Invocation #2+ delegates to the