pi-crew 0.11.45 → 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,
@@ -1456,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/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). */

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

@@ -20,10 +20,12 @@ import type { SpawnOptions } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { childPiBaseAllowlist } from "../../config/env-allowlist-registry.ts";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { isScratchpadEnabledForRole } from "../../config/role-tools.ts";
 import { buildScopedAllowList, providerEnvKeys, sanitizeEnvSecrets } from "../../utils/env-filter.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { buildBrokerStdinLine } from "../broker/stdin-handshake.ts";
 import { buildPiWorkerArgs, createSafeTempDir, getPiTempBase } from "../model/pi-args.ts";
 import { getPiSpawnCommand } from "../pi-spawn.ts";
 import { findLatestScratchpadSnapshot } from "../scratchpad/snapshot-lookup.ts";
@@ -44,6 +46,19 @@ import {
 // NOT set this (their sessions persist and benefit from long-lived cache).
 export const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
 
+/** LOW-1 residual closure (2026-10-27): when the inter-pi broker credentials
+ * are present, the per-task compound TOKEN travels over the spawn stdin pipe
+ * (one `buildBrokerStdinLine` payload, heap → pipe → heap — same shape as the
+ * F4 background-runner handshake) instead of the child env. Set
+ * PI_CREW_BROKER_STDIN=0 to roll back to the legacy env route (token in
+ * built.env, stdin stays "ignore"). Default ON. Only the headless JSON spawn
+ * branch consumes the payload: the RPC branch (stdin is the JSONL protocol
+ * channel) and the surface TUI panes keep the env route, so their env is
+ * untouched. */
+export function resolveBrokerStdinHandshakeEnabled(): boolean {
+	return getCrewEnv("PI_CREW_BROKER_STDIN") !== "0";
+}
+
 // ── Env allowlist (base set always passed to children) ──────────────────
 // Provider API keys are injected dynamically via buildScopedAllowList() only
 // when a model is assigned to the task (per-task key scoping).
@@ -258,6 +273,7 @@ export function buildFinalChildPiSpawnOptions(
 	model?: string,
 	modelChain?: (string | undefined)[],
 	workerCacheSplit?: boolean,
+	stdinBrokerPayload?: string,
 ): SpawnOptions {
 	// (a) Canary: builtEnv must contain ONLY PI_CREW_*/PI_TEAMS_* keys.
 	assertOnlyControlEnvKeys(builtEnv);
@@ -287,7 +303,18 @@ export function buildFinalChildPiSpawnOptions(
 	if (workerCacheSplit) {
 		spawnOptions.env[PI_CACHE_RETENTION_ENV] = "short";
 	}
-	// (d) Return the composed SpawnOptions for spawn(...).
+	// (d) LOW-1 closure: when the caller will hand the broker token to the child
+	// over the stdin pipe (headless JSON branch — it passes the payload it got
+	// from prepareSpawnContext), switch stdin from "ignore" to "pipe" and strip
+	// the secret from the env as defense-in-depth (prepareSpawnContext already
+	// omits it; the delete guards direct builtEnv constructions in tests/callers
+	// that still carry it). RPC branch / surface workerEnv snapshots call
+	// WITHOUT this param → env keeps the token and nothing else changes.
+	if (stdinBrokerPayload !== undefined) {
+		spawnOptions.stdio = ["pipe", "pipe", "pipe"];
+		delete spawnOptions.env.PI_CREW_BROKER_TOKEN;
+	}
+	// (e) Return the composed SpawnOptions for spawn(...).
 	return spawnOptions;
 }
 
@@ -310,6 +337,12 @@ export interface SpawnContext {
 	builtEnv: Record<string, string | undefined>;
 	/** v0.11.31: inference-broker worker key that owns this spawn's token (cleanup/revoke bookkeeping). */
 	inferenceWorkerKey?: string;
+	/** LOW-1 closure: one-line broker credential payload to write to the
+	 * child's stdin right after spawn (headless JSON branch ONLY — the RPC
+	 * branch owns stdin for its JSONL protocol and surface panes are TTY).
+	 * Present ⇒ PI_CREW_BROKER_TOKEN is NOT in builtEnv (token travels
+	 * heap → pipe → heap instead). Undefined ⇒ legacy env route. */
+	brokerStdinPayload?: string;
 }
 
 /**
@@ -364,6 +397,9 @@ export function prepareSpawnContext(
 	// a per-spawn unique.
 	const inferenceSnapshot = requireInferenceBrokerIfEnabled();
 	let inferenceWorkerKey: string | undefined;
+	// LOW-1 closure: stdin handshake payload for the headless JSON branch (see
+	// the brokerSpawn block below). Undefined = env route (legacy/rollback).
+	let brokerStdinPayload: string | undefined;
 	if (inferenceSnapshot.active) {
 		// v0.11.36: the agentId derivation is SHARED with the exit-revoke wrapper
 		// (runChildPi finally) via inferenceWorkerKeyForAgent — both sides must
@@ -415,11 +451,23 @@ export function prepareSpawnContext(
 	// Phase 0 inter-pi broker: inject socket path + token (control-namespace keys,
 	// safe under assertOnlyControlEnvKeys). Only when the parent broker issued
 	// credentials for this run — i.e. the broker is enabled AND this run is
-	// eligible. The token is heap-only on the parent; the child receives it
-	// solely through env. NEVER persisted to disk.
+	// eligible. NEVER persisted to disk.
+	// LOW-1 closure: by default the TOKEN leaves the env entirely — it rides the
+	// spawn stdin pipe as a single buildBrokerStdinLine payload (ctx
+	// .brokerStdinPayload; the headless JSON branch pipes stdin and writes it
+	// right after spawn). SOCKET/RUN_ID/TASK_ID stay in env (non-secret, needed
+	// by the worker bootstrap to bind + validate the stdin payload). Rollback
+	// gate PI_CREW_BROKER_STDIN=0 (or a legacy shape without runId/taskId to
+	// bind the payload to) keeps the env route bit-for-bit.
 	if (input.brokerSpawn?.socketPath && input.brokerSpawn.token) {
 		built.env.PI_CREW_BROKER_SOCKET = input.brokerSpawn.socketPath;
-		built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
+		if (resolveBrokerStdinHandshakeEnabled() && input.runId && input.agentId) {
+			brokerStdinPayload = buildBrokerStdinLine(input.runId, input.brokerSpawn.socketPath, {
+				[input.agentId]: input.brokerSpawn.token,
+			});
+		} else {
+			built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
+		}
 		// runId/taskId are threaded unconditionally above (I5); nothing to add here.
 	}
 	// WP-9 (R9): the worker self-reporting channel env is UNCONDITIONAL —
@@ -499,6 +547,7 @@ export function prepareSpawnContext(
 			tempDir: built.tempDir,
 			builtEnv: built.env,
 			inferenceWorkerKey,
+			...(brokerStdinPayload !== undefined ? { brokerStdinPayload } : {}),
 		},
 	};
 }

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

@@ -852,7 +852,18 @@ async function runChildPiInner(input: ChildPiRunInput): Promise<ChildPiRunResult
 			// R6-8: modelChain threads the candidate chain for provider-key scoping.
 			// v0.11.38 W10-1: workerCacheSplit — headless single-run workers opt into
 			// short prompt-cache retention (see PI_CACHE_RETENTION_ENV).
-			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain, true);
+			// LOW-1 closure: ctx.brokerStdinPayload (when present) switches stdin to
+			// "pipe" + strips PI_CREW_BROKER_TOKEN from the child env — the token
+			// travels over the stdin pipe right after spawn instead (heap → pipe → heap).
+			const spawnOptions = buildFinalChildPiSpawnOptions(
+				input.cwd,
+				mergedEnv,
+				builtEnv,
+				input.model,
+				input.modelChain,
+				true,
+				spawnPrep.ctx.brokerStdinPayload,
+			);
 			// v0.11.36 OS boundary: when the sandbox is on, the headless spawn is
 			// wrapped in bwrap. Mounts: cwd RW (the worker edits the project), the
 			// scoped inference agent dir RW (pi writes session state under it), and
@@ -909,6 +920,26 @@ async function runChildPiInner(input: ChildPiRunInput): Promise<ChildPiRunResult
 					ts: new Date().toISOString(),
 				});
 			}
+			// LOW-1 closure: hand the worker its broker credential over stdin — one
+			// buildBrokerStdinLine JSON line (v2, per-task compound token), then close
+			// the pipe. Mirror of the F4 async-runner handshake; the worker-side
+			// reader (crew-broker-child.ts via stdin-handshake.readStdinFirstLine)
+			// binds it by runId + taskId. Best-effort in BOTH directions: any write
+			// failure (EPIPE on a fast-exiting child, destroyed stream) leaves the
+			// worker creds-less exactly like a broker-less spawn — never throws out
+			// of the spawn path.
+			if (spawnPrep.ctx.brokerStdinPayload) {
+				try {
+					child.stdin?.write(spawnPrep.ctx.brokerStdinPayload);
+				} catch {
+					/* best-effort: worker proceeds creds-less */
+				}
+				try {
+					child.stdin?.end();
+				} catch {
+					/* EPIPE: child already died — spawn error handling owns that */
+				}
+			}
 			// P0-1: O(1)-amortized bounded accumulators (segment ring) — replaces the O(n²)
 			// appendBoundedTail rebuild-per-line pattern that re-scanned 512 KiB every line.
 			const stdoutTail = new BoundedTail();