pi-crew 0.11.44 → 0.11.46

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

@@ -47,22 +47,18 @@ import {
 } 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 { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { TeamRunManifest } 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 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 { handleDelegateRequest } from "./crew-broker-delegate-request.ts";
 import { type BrokerToken, BrokerTokenRegistry } from "./crew-broker-tokens.ts";
 import { DelegateAbortRegistry } from "./delegate/delegate-abort.ts";
 import { type DelegateEventTarget, type DelegateEventType, recordDelegateEvent } from "./delegate/delegate-event.ts";
-import { delegateTerminalEvent, finalizeDelegateResult } from "./delegate/delegate-finalize.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";
 // Outbound-queue management + caps (wc-gate move — bodies in protocol/connection-state.ts)
@@ -81,7 +77,6 @@ import {
 	BROKER_PROTOCOL,
 	isHelloParams,
 	isRequestObject,
-	parseDelegateRequestParams,
 	parseMsgSendParams,
 	parseWaitRequestParams,
 	safeStringify,
@@ -90,6 +85,7 @@ import {
 } from "./protocol/request-parsers.ts";
 import { recordWaitPolicyRejection, waitAuthError } from "./protocol/wait-auth.ts";
 import { handleWaitResolve } from "./protocol/wait-resolve.ts";
+import { captureSocketIdentity, type SocketIdentity, stopServerAndRemoveSocket } from "./socket-stop.ts";
 import { pushWaitingToForegroundWaiter } from "./wait-push.ts";
 import { WaitStatusCache } from "./wait-status-cache.ts";
 
@@ -144,6 +140,10 @@ export class CrewBroker {
 	private readonly taskTokens = new Map<string, BrokerToken>();
 	private server: net.Server | null = null;
 	private resolvedSocketPath: string | null = null;
+	/** [3] stop-unlink race: dev+ino of the leaf we created, captured right
+	 *  after listen() succeeded. stop() removes the path only while this
+	 *  still matches (a rebound leaf is a new inode); see socket-stop.ts. */
+	private socketIdentity: SocketIdentity | null = null;
 	private stopped = false;
 	private startingPromise: Promise<void> | null = null;
 	private readonly connections = new Set<ServerConnection>();
@@ -350,6 +350,13 @@ export class CrewBroker {
 			}
 		});
 
+		// 4.5 [3] stop-unlink race: pin the fresh leaf's identity so stop()
+		//     can prove it still owns the path before removing it (win32
+		//     named pipes have no fs leaf — nothing to pin).
+		if (process.platform !== "win32") {
+			this.socketIdentity = await captureSocketIdentity(sockPath);
+		}
+
 		// 5. Tighten socket permissions on POSIX. Node's net module has no
 		//    `mode` option (unlike `fs`), so we chmod after listen() succeeds.
 		if (process.platform !== "win32") {
@@ -432,43 +439,46 @@ export class CrewBroker {
 		}
 		this.connections.clear();
 
-		// 2. Close the server itself.
-		if (this.server) {
-			await new Promise<void>((resolve) => {
-				const srv = this.server;
+		// 2+4. Close the server AND remove the socket path in one
+		//      ownership-gated step. [3] stop-unlink race: libuv unlinks the
+		//      bind path BY NAME when the listening handle closes, so the
+		//      unlink/shield decision must wrap the close itself — see
+		//      broker/socket-stop.ts. We never touch any other path and
+		//      never `process.kill` anything.
+		const srv = this.server;
+		this.server = null;
+		const sockPath = this.resolvedSocketPath ?? this.options.socketPath;
+		const closeServer = () =>
+			new Promise<void>((resolve) => {
 				if (!srv) return resolve();
 				srv.close(() => resolve());
 				// If the server is not currently listening, close() resolves
 				// synchronously — guard with a hard timeout for safety.
 				setTimeout(() => resolve(), 250).unref();
 			});
-			this.server = null;
+		if (sockPath && process.platform !== "win32") {
+			const outcome = await stopServerAndRemoveSocket(sockPath, this.socketIdentity, closeServer);
+			if (outcome === "shielded-foreign" || outcome === "unshielded-foreign") {
+				// Path exists but is not provably ours (rebound or never bound):
+				// we did not remove it — any corpse is left for
+				// removeStaleBrokerSocket at the next start (fail-safe design).
+				logInternalError(
+					"crew-broker.stop.unlink-skipped",
+					new Error(`socket path not provably owned (${outcome}); left for removeStaleBrokerSocket`),
+					`path=${redactSecretString(sockPath)}`,
+				);
+			}
+		} else {
+			await closeServer();
 		}
+		this.resolvedSocketPath = null;
+		this.socketIdentity = null;
 
 		// 3. Clear the token map. This is the single point where the heap
 		//    state for runIds is wiped. No persistence to clean up.
 		this.tokens.clear();
 		// Task 10: drop the taskId → token index with it.
 		this.taskTokens.clear();
-
-		// 4. Unlink the recorded socket file IF we created it. We never
-		//    touch any other path. We also never `process.kill` anything.
-		const sockPath = this.resolvedSocketPath ?? this.options.socketPath;
-		if (sockPath && process.platform !== "win32") {
-			try {
-				await fsp.unlink(sockPath);
-			} catch (err) {
-				const code = (err as NodeJS.ErrnoException).code;
-				if (code !== "ENOENT") {
-					logInternalError(
-						"crew-broker.stop.unlink-failed",
-						err instanceof Error ? err : new Error(String(err)),
-						`path=${redactSecretString(sockPath)}`,
-					);
-				}
-			}
-		}
-		this.resolvedSocketPath = null;
 	}
 
 	// Connection lifecycle
@@ -759,15 +769,7 @@ export class CrewBroker {
 			}
 		}
 
-		// Bounded identity checks. taskId must be a non-empty string.
-		if (typeof taskId !== "string" || taskId.length === 0 || taskId.length > 256) {
-			this.sendErrorAndClose(conn, id, "auth", "hello rejected");
-			return;
-		}
-		if (typeof runId !== "string" || runId.length === 0 || runId.length > 256) {
-			this.sendErrorAndClose(conn, id, "auth", "hello rejected");
-			return;
-		}
+		// taskId/runId/token bounds (non-empty, ≤256) are enforced upstream by isHelloParams — protocol/request-parsers.ts.
 
 		// Bind connection identity and ack. Ack never includes the token.
 		conn.authed = true;
@@ -1449,295 +1451,23 @@ export class CrewBroker {
 		recordDelegateEvent(manifest, type, taskId, data);
 	}
 
+	/** T3/R5 (ADR-5): delegate.request — governed-nesting admission + background
+	 *  grandchild spawn with durable mailbox delivery (WP-5 step 5). Handler
+	 *  body moved to ./crew-broker-delegate-request.ts (wc-gate ITEM C,
+	 *  2026-10-27 — pure move, no behavior change; deps threaded via
+	 *  DelegateRequestDeps). */
 	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;
-		}
-		// R7-H1 fix: parse params through the protocol-level parser (mirrors
-		// parseWaitRequestParams discipline) — non-integer/non-finite/negative/
-		// over-ceiling maxTurns/budgetTokens never reach admission or the
-		// budget reservation (durable-negative tokensSpent escape).
-		const parsed = parseDelegateRequestParams(params);
-		if (!parsed) {
-			this.sendError(conn, id, "bad-params", "delegate.request: invalid params");
-			return;
-		}
-		const requested = parsed;
-		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. Since the D8
-		// flip the DEFAULT is true, so reaching this branch means the user
-		// closed the surface via config — the message points back at the knob.
-		if (this.options.nestingEnabled !== true) {
-			this.recordDelegateEvent(loaded.manifest, "delegate.rejected", conn.taskId, {
-				reason: "nesting-disabled",
-				policy: "nesting.enabled=false (user config; default is true since D8)",
-			});
-			this.sendError(
-				conn,
-				id,
-				"policy-disabled",
-				"delegate is disabled: nesting.enabled=false (set nesting.enabled=true in user config; 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.
-		// 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);
-			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` };
-			}
-			// 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;
-			// 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 === executionCwd,
-			).length;
-			const decision = evaluateDelegateAdmission({
-				maxDepth: this.options.nestingMaxDepth ?? resolveCrewMaxDepth(undefined), // config knob > env-clamped 1..10, default 4 (D8; ADR-5 §3)
-				parentTask: {
-					taskId: parentTaskId,
-					role: task.role,
-					...(task.depth !== undefined ? { depth: task.depth } : {}),
-					...(task.allocation !== undefined ? { allocation: task.allocation } : {}),
-				},
-				slots: this.nestedSlotBudget().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,
-				// M3-3 / R43-N1 SEED: the run-level token budget is the grant every
-				// task inherits when its own record carries no allocation (pre-fix
-				// state of EVERY task — nothing produced `tokensGranted`, so every
-				// budgeted delegate was denied and every unmetered one slipped by).
-				// `budgetUnlimited` opts out of enforcement entirely ⇒ no seed.
-				...(fresh.manifest.budgetTotal !== undefined && fresh.manifest.budgetUnlimited !== true
-					? { parentBudgetGrantTokens: fresh.manifest.budgetTotal }
-					: {}),
-				// M3-3 / R43-N1: unmetered delegation stays available (documented
-				// pre-fix behavior for nesting runs without a budgetTotal) but is now
-				// an EXPLICIT, audited allow (`unmetered: true` on delegate.admitted).
-				unmeteredDelegates: "allow",
-				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.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; ${this.nestedSlotBudget().statusLine}`,
-				};
-			}
-			// Reserve the requested budget pessimistically (ADR-5 §5): tokensSpent
-			// += budgetTokens now. M3-3/R43-N1: the reservation ALSO seeds the parent
-			// allocation when the record has none — the `decision.budget.grantedTokens`
-			// the gate admitted against is the write-once `tokensGranted`
-			// (state-helpers.ts merge keeps disk's value verbatim). Pre-fix the
-			// `parentAllocation` guard silently skipped the reserve for every task
-			// that had no allocation, i.e. for every task.
-			// M3-4/R44-N4: this reservation IS the spend — no settle-time refund.
-			let reserved = 0;
-			const budgetDecision = decision.budget;
-			let tasksAfterReserve = fresh.tasks;
-			if (budgetDecision?.metered === true) {
-				reserved = budgetDecision.requestedTokens ?? 0;
-				const updatedTasks = fresh.tasks.map((t) =>
-					t.id === parentTaskId
-						? {
-								...t,
-								allocation: {
-									tokensGranted: budgetDecision.grantedTokens,
-									tokensSpent: budgetDecision.spentTokens + 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: executionCwd,
-					dependsOn: [],
-					depth: decision.childDepth ?? 2,
-					startedAt: new Date().toISOString(),
-				} satisfies TeamTaskState,
-			]);
-			// 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, parentRole: task.role };
-		});
-		// 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, executionCwd, parentModel, parentRole } = admissionOutcome;
-		this.recordDelegateEvent(loaded.manifest, "delegate.admitted", parentTaskId, {
-			subId,
-			childDepth: decision.childDepth,
-			role: requested.role ?? "explorer",
-			// M3-3/R43-N1: an unmetered allow is EXPLICIT in the audit trail.
-			...(decision.budget?.metered === false ? { unmetered: true } : {}),
-			...(reserved > 0 ? { reservedTokens: reserved } : {}),
+		await handleDelegateRequest(conn, id, params, {
+			sendError: (c, i, code, msg) => this.sendError(c, i, code, msg),
+			sendResult: (c, i, r) => this.sendResult(c, i, r),
+			options: this.options,
+			nestedSlotBudget: () => this.nestedSlotBudget(),
+			recordDelegateEvent: (m, type, taskId, data) => this.recordDelegateEvent(m, type, taskId, data),
+			runLockBusyRetry: (manifest, fn) => this.runLockBusyRetry(manifest, fn),
+			delegateAborts: this.delegateAborts,
+			socketPath: this.socketPath,
+			issueRunToken: (runId, taskId) => this.issueRunToken(runId, taskId),
 		});
-		// 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 });
-		// 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;
-		// M3-5/R43-N3: register the grandchild's abort controller BEFORE the
-		// spawn starts, so a run terminalise / budget abort / broker stop that
-		// lands mid-spawn still cancels it (no orphan outliving the run).
-		const delegateAbort = this.delegateAborts.register(subId, runId);
-		// Background grandchild lifecycle (ADR-5 §1/§6).
-		const spawner = this.options.grandchildSpawner ?? spawnDelegateGrandchild;
-		void (async () => {
-			let outcome: GrandchildSpawnResult;
-			try {
-				outcome = await spawner({
-					cwd: executionCwd,
-					runId,
-					parentTaskId,
-					// R43-S1: transitive tier containment — the spawner applies
-					// min(parentRole, requestedRole) as the grandchild tool policy.
-					parentRole,
-					subId,
-					prompt: requested.prompt,
-					eventsPath: loaded.manifest.eventsPath,
-					role: requested.role ?? "explorer",
-					...(grandchildCreds ? { brokerSpawn: grandchildCreds } : {}),
-					...(gcModel !== undefined ? { model: gcModel } : {}),
-					...(requested.maxTurns !== undefined ? { maxTurns: requested.maxTurns } : {}),
-					timeoutSec: decision.timeoutSec ?? 900,
-					depthOverride: decision.childDepth ?? 2,
-					// M3-5/R43-N3: owner cancellation (registry-driven).
-					signal: delegateAbort.signal,
-					// 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}` };
-			}
-			try {
-				// 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 statusTag = outcome.cancelled ? "(cancelled)" : outcome.timedOut ? "(timed out)" : outcome.ok ? "(ok)" : "(failed)";
-				const fenced = `--- delegate ${subId} ${statusTag} ---\n${sanitizedText}\n--- end delegate ${subId} ---`;
-				// Durable delivery + budget charge + shadow terminal flip — all
-				// inside one run lock, off a fresh disk read (delegate-finalize.ts
-				// owns the R43-N4 reroute and the R44-N4 broker-side charge).
-				finalizeDelegateResult({
-					brokerCwd: cwd,
-					runId,
-					parentTaskId,
-					subId,
-					fenced,
-					ok: outcome.ok,
-					...(outcome.timedOut !== undefined ? { timedOut: outcome.timedOut } : {}),
-					reservedTokens: reserved,
-					...(outcome.usageTokens !== undefined ? { selfReportedTokens: outcome.usageTokens } : {}),
-				});
-			} finally {
-				this.delegateAborts.release(subId);
-				this.nestedSlotBudget().release(subId);
-			}
-			this.recordDelegateEvent(loaded.manifest, delegateTerminalEvent(outcome), parentTaskId, {
-				subId,
-				ok: outcome.ok,
-			});
-		})();
 	}
 
 	// recordWaitPolicyRejection: imported directly from protocol/wait-auth.ts.

package/src/runtime/broker/socket-stop.ts

@@ -0,0 +1,147 @@
+/**
+ * socket-stop.ts — Ownership-gated teardown of the broker's listening socket.
+ *
+ * An AF_UNIX listener has TWO unlink vectors, and both must be owned-gated:
+ *  1. The explicit `fs.unlink` of the recorded path (CrewBroker.stop step 4).
+ *  2. libuv itself: `uv__pipe_close` unlinks the server pipe's bind path BY
+ *     NAME (no inode check) when the listening handle closes — Node's
+ *     `server.close()` deletes whatever currently sits at the path, even a
+ *     socket another listener re-bound there after ours was unlinked
+ *     (empirically verified on Node 22, 2026-10-26).
+ *
+ * The broker socket path is deterministic per sessionId, so a rebound leaf
+ * must survive our stop(). stopServerAndRemoveSocket therefore:
+ *  - Unlinks the leaf itself FIRST when its dev+ino match the identity
+ *    captured at listen() time — libuv's close-unlink then finds nothing.
+ *  - Otherwise, if ANY entry lives at the path (rebound foreign socket, or
+ *    ownership unprovable because the capture lstat failed), renames it
+ *    aside (shield) across closeServer() and renames it back afterwards:
+ *    a brief ENOENT window for new connects instead of permanent deletion
+ *    of a live foreign socket. B-LOW2: the rename-back happens ONLY while
+ *    sockPath is still absent — if a new listener re-bound the leaf during
+ *    the close, its leaf wins and the shield is kept (renaming back would
+ *    clobber the fresh bind).
+ *    A stranded shield (crash between renames, or one kept after a rebind)
+ *    keeps its `.stopping.` suffix and is swept by the corpse sweep inside
+ *    removeStaleBrokerSocket at the next start — it unlinks a shield ONLY
+ *    when the pid embedded in its name is provably dead (B-LOW1).
+ *  - Windows named pipes have no filesystem leaf: plain close only.
+ *
+ * Never throws; diagnostics flow through logInternalError with redaction.
+ */
+
+import { randomBytes } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactSecretString } from "../../utils/redaction.ts";
+
+/** dev+ino of the socket leaf created by listen() — captured immediately
+ *  after a successful bind so stop() can prove continued ownership of the
+ *  path before removing it. Null when the lstat failed (stop() then treats
+ *  the leaf as NOT provably ours — the safe direction). */
+export interface SocketIdentity {
+	dev: number;
+	ino: number;
+}
+
+/** Capture the identity of the freshly-bound socket leaf (POSIX only). */
+export async function captureSocketIdentity(sockPath: string): Promise<SocketIdentity | null> {
+	try {
+		const st = await fsp.lstat(sockPath);
+		return { dev: st.dev, ino: st.ino };
+	} catch {
+		return null;
+	}
+}
+
+export type SocketStopOutcome =
+	/** Our leaf (identity matched) was unlinked by us before the close. */
+	| "unlinked"
+	/** A foreign/unpinned entry existed and was shielded across the close. */
+	| "shielded-foreign"
+	/** A foreign entry existed but the shield rename failed (close then
+	 *  unlinks it by name — the pre-fix behavior; logged loudly). */
+	| "unshielded-foreign"
+	/** Nothing lived at the path (or win32: no fs leaf at all). */
+	| "absent";
+
+/** Close the listening server and remove the socket path ONLY while we
+ *  provably own it. `closeServer` must perform the net.Server close (the
+ *  libuv by-name unlink vector) — it is called exactly once, sandwiched
+ *  inside the ownership decision. Never throws. */
+export async function stopServerAndRemoveSocket(
+	sockPath: string,
+	identity: SocketIdentity | null,
+	closeServer: () => Promise<void>,
+): Promise<SocketStopOutcome> {
+	if (process.platform === "win32") {
+		await closeServer();
+		return "absent";
+	}
+	const current = await fsp.lstat(sockPath).catch(() => null);
+	if (current === null) {
+		await closeServer();
+		return "absent";
+	}
+	const owned = identity !== null && current.dev === identity.dev && current.ino === identity.ino;
+	if (owned) {
+		// Remove our own leaf first so libuv's close-unlink finds nothing.
+		// (Microsecond TOCTOU between this unlink and the close-unlink is
+		// inherent to path-based APIs — accepted, same class as before.)
+		await fsp.unlink(sockPath).catch(() => {
+			/* best-effort: the leaf may already be gone */
+		});
+		await closeServer();
+		return "unlinked";
+	}
+	// Foreign or unprovably-owned entry: shield it across the close.
+	const shield = `${sockPath}.stopping.${process.pid}.${randomBytes(3).toString("hex")}`;
+	let shielded = false;
+	try {
+		await fsp.rename(sockPath, shield);
+		shielded = true;
+	} catch (err) {
+		logInternalError(
+			"crew-broker.stop.shield-rename-failed",
+			err instanceof Error ? err : new Error(String(err)),
+			`path=${redactSecretString(sockPath)}`,
+		);
+	}
+	try {
+		await closeServer();
+	} finally {
+		if (shielded) {
+			// B-LOW2: restore ONLY while the leaf is still absent. While our
+			// handle was closing, a new listener may have bound sockPath — a
+			// rename back would REPLACE its fresh leaf (rename clobbers the
+			// target), recreating the exact deletion bug the shield exists to
+			// prevent. When rebound: keep the shield (the corpse sweep at the
+			// next start removes it once this pid is dead) and log loudly.
+			let rebound = false;
+			try {
+				await fsp.lstat(sockPath);
+				rebound = true;
+			} catch {
+				/* still absent — safe to restore */
+			}
+			if (rebound) {
+				logInternalError(
+					"crew-broker.stop.shield-kept-rebound",
+					new Error(`socket path re-bound during close — keeping shield at ${shield} instead of clobbering the new listener`),
+					`path=${redactSecretString(sockPath)}`,
+				);
+			} else {
+				try {
+					await fsp.rename(shield, sockPath);
+				} catch (err) {
+					logInternalError(
+						"crew-broker.stop.shield-restore-failed",
+						err instanceof Error ? err : new Error(String(err)),
+						`path=${redactSecretString(shield)}`,
+					);
+				}
+			}
+		}
+	}
+	return shielded ? "shielded-foreign" : "unshielded-foreign";
+}

package/src/runtime/broker/stdin-handshake.ts

@@ -50,6 +50,17 @@ export function parseStdinBrokerPayload(raw: string, expectedRunId: string): Std
 	}
 }
 
+/** LOW-1 residual closure (2026-10-27): the ONE line a spawner writes to a
+ * worker's stdin carrying PER-TASK compound broker tokens. Moved here from
+ * async-runner.ts (which re-exports for API stability) so BOTH writer sides —
+ * the detached background runner AND the main child-pi spawn path — share the
+ * pure protocol piece and cannot drift from the reader parser below (a
+ * writer/reader drift silently breaks coordination). Compound (runId+taskId)
+ * tokens only: wait.* rejects bare-runId tokens (ADR-0 item 6). */
+export function buildBrokerStdinLine(runId: string, socketPath: string, tasks: Record<string, string>): string {
+	return `${JSON.stringify({ v: 2, runId, socketPath, tasks })}\n`;
+}
+
 /** Read the FIRST stdin line with a hard cap. Resolves undefined for: no
  * stdin / TTY / silence past the timeout / oversize / error. Never throws,
  * never destroys stdin (leaves it paused for the rest of boot). */