pi-crew 0.9.46 → 0.9.48

package/src/config/config.ts

@@ -8,6 +8,7 @@ import { atomicWriteFile } from "../state/atomic-write.ts";
 import { withFileLockSync } from "../state/locks.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
+import { DEFAULT_BROKER, resolveBrokerEnvOverride } from "./defaults.ts";
 import { suggestConfigKey } from "./suggestions.ts";
 
 // 2.9: interface types extracted to ./types.ts; re-export for back-compat.
@@ -44,6 +45,7 @@ import type {
 	AgentOverrideConfig,
 	ConfigValidationResult,
 	CrewAgentsConfig,
+	CrewBrokerConfig,
 	CrewControlConfig,
 	CrewLimitsConfig,
 	CrewNotificationsConfig,
@@ -744,6 +746,38 @@ function parseControlConfig(value: unknown): CrewControlConfig | undefined {
 	return Object.values(control).some((entry) => entry !== undefined) ? control : undefined;
 }
 
+/**
+ * Phase 0 broker parser. Returns `undefined` only when input is not an object;
+ * otherwise returns the broker config (with only defined fields populated)
+ * so the caller can layer defaults on top.
+ */
+function parseBrokerConfig(value: unknown): CrewBrokerConfig | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	// Use the exact schema bounds (4..32 / 1024..1048576 / 32..4096). The
+	// previous version used parsePositiveInteger(value, default) which clamps
+	// the UPPER bound to the default — effectively pathHashLen was capped
+	// at 8, much narrower than the schema advertises.
+	const broker: CrewBrokerConfig = {
+		enabled: parseWithSchema(Type.Boolean(), obj.enabled),
+		pathHashLen: parseIntegerInRange(obj.pathHashLen, 4, 32),
+		maxFrameBytes: parseIntegerInRange(obj.maxFrameBytes, 1024, 1_048_576),
+		outboundQueueCap: parseIntegerInRange(obj.outboundQueueCap, 32, 4096),
+	};
+	return Object.values(broker).some((entry) => entry !== undefined) ? broker : undefined;
+}
+
+/**
+ * Apply PI_CREW_BROKER env override to the parsed broker config, then
+ * layer in DEFAULT_BROKER for any field the user did not set. Keeps the
+ * kill switch (enabled:false) reachable in three independent ways: env,
+ * config block, or default.
+ */
+function applyBrokerEnvOverrideAndDefaults(parsed: CrewBrokerConfig | undefined): CrewBrokerConfig {
+	const envOverridden = resolveBrokerEnvOverride(parsed);
+	return { ...DEFAULT_BROKER, ...envOverridden };
+}
+
 function parseWorktreeConfig(value: unknown): CrewWorktreeConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
@@ -1019,6 +1053,7 @@ export function parseConfig(raw: unknown): PiTeamsConfig {
 		reliability: parseReliabilityConfig(obj.reliability),
 		otlp: parseOtlpConfig(obj.otlp),
 		ui: parseUiConfig(obj.ui),
+		broker: parseBrokerConfig(obj.broker),
 	};
 }
 
@@ -1164,7 +1199,13 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 	const result: LoadedPiTeamsConfig = {
 		path: filePath,
 		paths,
-		config,
+		config: {
+			...config,
+			// Phase 0 broker: layer in env override + defaults. Env wins over
+			// config; defaults fill any missing field. Env `"1"`/`"0"` forces
+			// the enabled flag even when no broker block is configured.
+			broker: applyBrokerEnvOverrideAndDefaults(config.broker),
+		},
 		warnings: warnings.length > 0 ? warnings : undefined,
 	};
 	// Only cache when at least one of the watched paths exists — this avoids

package/src/config/defaults.ts

@@ -1,3 +1,5 @@
+import type { CrewBrokerConfig } from "./types.ts";
+
 export const DEFAULT_CHILD_PI: Readonly<{
 	postExitStdioGuardMs: number;
 	finalDrainMs: number;
@@ -20,7 +22,7 @@ export const DEFAULT_CHILD_PI: Readonly<{
 	hardKillMs: 3000,
 	// Child workers can spend more than a few seconds in provider calls or long-running tools without emitting stdout.
 	// Keep this as a coarse stuck-worker guard rather than a short per-message latency budget.
-	responseTimeoutMs: 5 * 60_000,
+	responseTimeoutMs: 10 * 60_000,
 	// #3 unresponsive worker hardening: increased from 256KB to 512KB so critical
 	// diagnostic stderr is less likely to be silently truncated during hang analysis.
 	maxCaptureBytes: 512 * 1024,
@@ -147,3 +149,45 @@ export const DEFAULT_MAILBOX = {
 export const DEFAULT_SUBAGENT = {
 	stuckBlockedNotifyMs: 5 * 60_000,
 };
+
+/**
+ * Phase 0 inter-pi broker defaults.
+ * Phase 4 (v0.9.47): default is ON (enabled:true). The broker runs
+ * automatically for users on supported platforms (Linux + macOS).
+ * Three independent ways to disable:
+ *   1. `broker.enabled: false` in user config
+ *   2. env `PI_CREW_BROKER=0` (beats config=true)
+ *   3. (Windows) auto-disabled — broker requires unix socket which Windows
+ *      supports only via WSL1/2; native Windows perm model lacks the
+ *      abstract-socket guarantees the broker relies on. See
+ *      docs/decisions/2026-07-21-broker-windows-perms.md.
+ * Limits are bounded by `src/schema/config-schema.ts` CrewBrokerConfigSchema:
+ *   pathHashLen       4..32     (default 8)
+ *   maxFrameBytes     1024..1048576 (default 262144 = 256 KiB)
+ *   outboundQueueCap  32..4096  (default 256)
+ */
+export const DEFAULT_BROKER = {
+	enabled: true,
+	pathHashLen: 8,
+	maxFrameBytes: 262144,
+	outboundQueueCap: 256,
+} as const;
+
+/**
+ * Apply `PI_CREW_BROKER` env override to a parsed broker config.
+ * - `"1"` forces `enabled: true` (beats a config of `false` AND the
+ *   default of `false` when no broker block is configured).
+ * - `"0"` forces `enabled: false` (beats a config of `true`).
+ * - unset / any other value falls through to the parsed value (which
+ *   may itself be `undefined`; the loadConfig merge layer fills defaults).
+ * Phase 0 scope: only the `enabled` flag is overridable via env; numeric
+ * bounds must go through the schema + parser path, not env.
+ */
+export function resolveBrokerEnvOverride(parsed: CrewBrokerConfig | undefined): CrewBrokerConfig | undefined {
+	const override = process.env.PI_CREW_BROKER;
+	if (override === "1" || override === "0") {
+		const base: CrewBrokerConfig = parsed ?? {};
+		return { ...base, enabled: override === "1" };
+	}
+	return parsed;
+}

package/src/config/types.ts

@@ -224,6 +224,25 @@ export interface PiTeamsConfig {
 	reliability?: CrewReliabilityConfig;
 	otlp?: CrewOtlpConfig;
 	ui?: CrewUiConfig;
+	/**
+	 * Inter-pi broker (Phase 0). Local-only socket transport between parent
+	 * and child pi workers. Default is OFF (`enabled:false`) — keep it that
+	 * way until Phase 4 soak completes. Numeric limits are bounded by the
+	 * schema (`src/schema/config-schema.ts`).
+	 */
+	broker?: CrewBrokerConfig;
+}
+
+/** CrewBroker config (Phase 0 inter-pi broker). */
+export interface CrewBrokerConfig {
+	/** Master switch. `false` keeps the broker fully dormant. */
+	enabled?: boolean;
+	/** Length of the SHA-256 hex prefix used in the socket filename. 4..32. */
+	pathHashLen?: number;
+	/** Maximum NDJSON frame size in UTF-8 bytes (default 262144 = 256 KiB). 1024..1048576. */
+	maxFrameBytes?: number;
+	/** Per-connection outbound queue cap. 32..4096 (default 256). */
+	outboundQueueCap?: number;
 }
 
 export interface LoadedPiTeamsConfig {

package/src/extension/register.ts

@@ -36,7 +36,7 @@ import { importCrashRecovery, purgeStaleActiveRunIndexSyncIfLoaded } from "./reg
 import { installForegroundRunController } from "./registration/foreground-run-controller.ts";
 import { installPiHooks } from "./registration/hook-registration.ts";
 import { installLazyConfigurers } from "./registration/lazy-configurers.ts";
-import { installSessionLifecycleHandlers } from "./registration/lifecycle-handlers.ts";
+import { installCrewBrokerLifecycleController, installSessionLifecycleHandlers } from "./registration/lifecycle-handlers.ts";
 import { installRuntimeCleanup } from "./registration/runtime-cleanup.ts";
 import { __test__subagentSpawnParams } from "./registration/subagent-helpers.ts";
 import { installSubagentManager } from "./registration/subagent-manager-setup.ts";
@@ -73,6 +73,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	registerPiCommands(pi, ctx);
 	installPiHooks(pi, ctx);
 	installSessionLifecycleHandlers(pi, ctx);
+	// Phase 0 inter-pi broker: install the lifecycle controller immediately
+	// after the session handlers. The controller's gate (broker.enabled AND
+	// root-session only) decides whether anything is actually done; for
+	// subagents or when the flag is off, it returns a no-op controller.
+	ctx.brokerController = installCrewBrokerLifecycleController(pi, ctx);
 
 	registerCleanupHandler(pi);
 	registerCompactionGuard(pi, {

package/src/extension/registration/context-builder.ts

@@ -102,6 +102,10 @@ export function buildRegistrationContext(pi: ExtensionAPI): RegistrationContext
 		startForegroundRun: undefined as never,
 		abortForegroundRun: () => false,
 		openLiveSidebar: () => {},
+		// Phase 0 inter-pi broker controller. Initially undefined; register.ts
+		// replaces this with a real controller (or no-op) after lifecycle
+		// handlers are installed.
+		brokerController: undefined,
 	};
 
 	ctx.notifyOperator = (notification: NotificationDescriptor): void => {

package/src/extension/registration/lifecycle-handlers.ts

@@ -20,11 +20,13 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_UI } from "../../config/defaults.ts";
 import { pruneFinishedRuns, pruneUserLevelRuns } from "../../extension/run-maintenance.ts";
+import { type BrokerSpawnCredentials, setActiveBrokerIssuer } from "../../runtime/broker-issuer.ts";
 import { reconcileAllStaleRuns } from "../../runtime/crash-recovery.ts";
+import { CrewBroker } from "../../runtime/crew-broker.ts";
 import { listLiveAgents } from "../../runtime/live-agent-manager.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
 import { cleanupOrphanWorkers } from "../../runtime/orphan-worker-registry.ts";
-import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs } from "../../runtime/pi-args.ts";
+import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth } from "../../runtime/pi-args.ts";
 import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduler.ts";
 import { tryRegisterSessionCleanup } from "../../runtime/session-resources.ts";
 import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
@@ -47,7 +49,8 @@ import { updateCrewWidget } from "../../ui/widget/index.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
 import { RunWatcherRegistry } from "../../utils/run-watcher-registry.ts";
-import { extractSessionId } from "../../utils/session-utils.ts";
+import { extractBrokerSessionId } from "../../utils/session-utils.ts";
+import { getBrokerSocketPath } from "../../utils/socket-path.ts";
 import { startAsyncRunNotifier, stopAsyncRunNotifier } from "../async-notifier.ts";
 import { registerCrewAutocomplete } from "../crew-autocomplete.ts";
 import { notifyActiveRuns } from "../session-summary.ts";
@@ -169,7 +172,11 @@ function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext):
 		ctx.widgetState.interval = undefined;
 		notifyActiveRuns(extensionCtx);
 
-		const currentSessionId = extractSessionId(extensionCtx);
+		const currentSessionId = extractBrokerSessionId(extensionCtx);
+		// Phase 0 broker: feed the captured session_id to the controller so
+		// it can issue tokens for child runs in this session. The controller
+		// already gates by flag + root-session; this is a no-op when disabled.
+		ctx.brokerController?.setSessionId(currentSessionId);
 
 		// Defer ALL heavy cleanup to after the session_start handler returns.
 		// These operations involve synchronous directory scanning (readdirSync, readFileSync)
@@ -760,3 +767,159 @@ function setupRenderLoop(
 	// watchers for any runs that are already active on session start.
 	backgroundPreload();
 }
+
+// =============================================================================
+// Phase 0 inter-pi broker lifecycle controller (sub-task 0.5)
+// =============================================================================
+//
+// `installCrewBrokerLifecycleController` wires the per-session broker into
+// the existing extension lifecycle. The controller:
+//
+//  - is a no-op unless broker.enabled is true AND the current process is the
+//    root pi session (PI_CREW_KIND !== "subagent" AND currentCrewDepth === 0).
+//    Children NEVER install a broker.
+//  - lazily constructs a single CrewBroker instance per session_id. listen()
+//    is deferred until the first child run actually requests broker credentials.
+//  - issues a heap-only token per child run via `issueForChild`. The token
+//    NEVER leaves the parent's heap and the child's env (PI_CREW_BROKER_TOKEN).
+//    It is never written to disk.
+//  - retains the broker across session switches when the session_id is
+//    unchanged; on a session_id change, stops the old broker and binds a new
+//    one on the next acquire.
+//  - stops the broker during session_shutdown BEFORE the runtime cleanup path.
+//
+// The gate is re-evaluated on every `issueForChild` call (cheap env+depth
+// check) so the kill switch (PI_CREW_BROKER=0) takes effect immediately.
+
+export interface CrewBrokerLifecycleController {
+	/** Issue credentials for a child run. Returns undefined when the broker
+	 *  is disabled, this process is a subagent, or no session_id is known. */
+	issueForChild(runId: string): Promise<BrokerSpawnCredentials | undefined>;
+	/** Stop the broker (idempotent). Called on session_shutdown. */
+	stop(): Promise<void>;
+	/** Test/lifecycle seam: remember the most recent session_id for token issuance. */
+	setSessionId(sessionId: string | undefined): void;
+}
+
+function isRootSession(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.PI_CREW_KIND === "subagent") return false;
+	try {
+		return currentCrewDepth(env) === 0;
+	} catch {
+		return false;
+	}
+}
+
+export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: RegistrationContext): CrewBrokerLifecycleController {
+	let broker: CrewBroker | null = null;
+	let brokerSessionId: string | undefined;
+	let starting: Promise<CrewBroker> | null = null;
+	let cachedSessionId: string | undefined;
+
+	function effectiveEnabled(): boolean {
+		// Env wins over config. PI_CREW_BROKER=1 forces on, =0 forces off.
+		const envOverride = process.env.PI_CREW_BROKER;
+		if (envOverride === "0") return false;
+		// Config block: read fresh so a runtime config update takes effect.
+		try {
+			const cfg = loadConfig().config.broker;
+			if (envOverride === "1") return cfg !== undefined ? cfg.enabled !== false : true;
+			// Phase 4 (v0.9.47) default-on: enabled unless explicitly disabled.
+			return cfg?.enabled !== false;
+		} catch {
+			// Fail-safe: config load failed → keep broker disabled.
+			return false;
+		}
+	}
+
+	async function getOrStartBroker(sessionId: string): Promise<CrewBroker> {
+		if (broker && brokerSessionId === sessionId) return broker;
+		if (broker && brokerSessionId !== sessionId) {
+			try {
+				await broker.stop();
+			} catch {
+				/* ignore */
+			}
+			broker = null;
+			brokerSessionId = undefined;
+		}
+		if (!broker && !starting) {
+			starting = (async () => {
+				const cfg = (() => {
+					try {
+						return loadConfig().config.broker;
+					} catch {
+						return undefined;
+					}
+				})();
+				const b = new CrewBroker({
+					sessionId,
+					socketPath: getBrokerSocketPath(sessionId),
+					maxFrameBytes: cfg?.maxFrameBytes ?? 262144,
+					outboundQueueCap: cfg?.outboundQueueCap ?? 256,
+					enabled: true,
+					cwd: process.cwd(),
+				});
+				try {
+					await b.start();
+					broker = b;
+					brokerSessionId = sessionId;
+					return b;
+				} finally {
+					starting = null;
+				}
+			})();
+		}
+		return starting!;
+	}
+
+	const issueForChild = async (runId: string): Promise<BrokerSpawnCredentials | undefined> => {
+		if (!runId || typeof runId !== "string") return undefined;
+		if (!isRootSession(process.env)) return undefined;
+		if (!effectiveEnabled()) return undefined;
+		const sessionId = cachedSessionId;
+		if (!sessionId) return undefined;
+		try {
+			const b = await getOrStartBroker(sessionId);
+			const token = b.issueRunToken(runId);
+			return { socketPath: b.socketPath, token };
+		} catch {
+			return undefined;
+		}
+	};
+
+	// Publish this issuer as the process-local active issuer so runChildPi can
+	// default `brokerIssuer` without the registration context being threaded
+	// through every runner call site. The issuer self-gates (root + flag), so
+	// publishing it unconditionally is safe even when the broker is disabled.
+	setActiveBrokerIssuer(issueForChild);
+
+	return {
+		issueForChild,
+		stop: async () => {
+			setActiveBrokerIssuer(undefined);
+			if (broker) {
+				try {
+					await broker.stop();
+				} catch {
+					/* ignore */
+				}
+				broker = null;
+				brokerSessionId = undefined;
+			}
+		},
+		/** Test seam: remember the most recent session_id for token issuance. */
+		setSessionId: (sessionId: string | undefined) => {
+			// Runtime validation: cap the length and charset to defend against
+			// a hostile extension supplying a huge or pathological id. The
+			// socket path is already hash-derived (4..32 hex), so a longer
+			// sessionId is harmless on disk but wastes heap.
+			if (typeof sessionId !== "string") return;
+			if (sessionId.length === 0 || sessionId.length > 256) return;
+			cachedSessionId = sessionId;
+		},
+	};
+}
+
+/** Marker used by tests to confirm the controller object identity. */
+export const __test__brokerControllerMarker = true;

package/src/extension/registration/registration-types.ts

@@ -146,4 +146,13 @@ export interface RegistrationContext {
 	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
 	abortForegroundRun: (runId: string) => boolean;
 	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
+	/**
+	 * Phase 0 inter-pi broker lifecycle controller. Set by `register.ts`
+	 * after `installSessionLifecycleHandlers`. The controller is a no-op
+	 * when the broker is disabled or the current process is a subagent;
+	 * callers (e.g. child-pi-spawn consumers) MUST handle the case where
+	 * `issueForChild` returns undefined. The controller is stopped
+	 * during session_shutdown via `stop()`.
+	 */
+	brokerController: import("./lifecycle-handlers.ts").CrewBrokerLifecycleController | undefined;
 }

package/src/prompt/prompt-runtime.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { startChildBrokerClient } from "../runtime/crew-broker-child.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 
@@ -34,6 +35,59 @@ export interface SteerSanitizeResult {
 export interface SteerEntry {
 	type?: string;
 	message?: string;
+	/** Message id. Present in entries the broker writes; absent in legacy
+	 *  entries pre-dating the broker id-forwarding change. */
+	id?: string;
+}
+
+// ── FIX-S1: Cross-channel steer dedup state ──────────────────────────────
+// Both the live broker push (mailbox.message → onSteer) and the durable
+// file poll (pollSteering JSONL) can deliver the SAME steer to the worker
+// for two reasons:
+//   1. The broker writes to BOTH the mailbox AND the steering JSONL for
+//      durability. A connected child receives the broker push FIRST, then
+//      file-poll sees the JSONL shortly after (the broker's own write is
+//      what populates that file).
+//   2. A reconnect / catch-up from a previously-disconnected child can
+//      re-deliver the same mailbox.message id a second time.
+//
+// We dedup at the recipient (worker) by tracking steer ids across BOTH
+// channels in a single bounded FIFO set. Entries without an id (legacy
+// JSONL rows written before S1) are NOT deduped, because they lack a
+// stable identity — the file-poll path is their only delivery route.
+const SEEN_STEER_ID_CAP = 1024;
+
+/**
+ * Bounded FIFO seen-set for steer message ids.
+ *
+ * - `markOrSkip(undefined)` returns true (the file-poll path may emit
+ *   legacy id-less entries; forward them).
+ * - `markOrSkip('a')` first call returns true; the same call again returns
+ *   false (id already seen → drop the duplicate deliver).
+ * - When the cap is exceeded, the oldest id is evicted so the set stays
+ *   bounded under long-running workers with high steer churn.
+ *
+ * Factory-shaped so multiple prompt-runtime instances (tests, parallel
+ * workers) get independent sets.
+ */
+export function createSeenSteerIdSet(): { markOrSkip: (id?: string) => boolean; size: () => number } {
+	const seen: string[] = [];
+	const set = new Set<string>();
+	return {
+		markOrSkip(id?: string): boolean {
+			if (id === undefined) return true; // legacy steers have no id; only file-poll path can produce these
+			if (set.has(id)) return false;
+			set.add(id);
+			seen.push(id);
+			// FIFO eviction: when the cap is exceeded, drop the oldest entry.
+			while (seen.length > SEEN_STEER_ID_CAP) {
+				const oldest = seen.shift();
+				if (oldest !== undefined) set.delete(oldest);
+			}
+			return true;
+		},
+		size: () => set.size,
+	};
 }
 
 /**
@@ -157,6 +211,16 @@ export function rewriteTeamWorkerPrompt(prompt: string, options: { inheritProjec
 }
 
 export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
+	// ── FIX-S1: cross-channel steer dedup state ────────────────────────────
+	// Both the broker push (mailbox.message → onSteer callback below) and the
+	// file poll (pollSteering below) are wired to sendMessage. The broker
+	// writes to BOTH the mailbox observer (live fanout) AND the steering
+	// JSONL (durable fallback) so a connected worker will see the same steer
+	// twice: once via the broker, once via the next poll tick. We dedup at the
+	// consumer by tracking steer ids in a bounded FIFO set shared by both
+	// delivery paths. Without id-bearing entries (legacy producer), pollSteering
+	// is the only delivery channel and dedup is a no-op for id-less entries.
+	const seenSteers = createSeenSteerIdSet();
 	// ── Feature 1: maxTokens cap ──────────────────────────────────────────
 	// Cap output tokens per API call for background workers. Reads
 	// PI_CREW_MAX_OUTPUT_TOKENS env (set by pi-args.ts from agent.maxTokens).
@@ -220,6 +284,15 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 							try {
 								const entry = JSON.parse(line) as SteerEntry;
 								if (entry.type !== "steer") continue;
+								// FIX-S1: cross-channel dedup. The broker writes the
+								// same steer to both the mailbox (live fanout via the
+								// onSteer callback below) and this JSONL file. A
+								// connected worker receives it via the broker first
+								// and via this poll second; the seen-id set ensures
+								// only the first arrival reaches pi.sendMessage.
+								const entryId =
+									typeof (entry as { id?: unknown }).id === "string" ? (entry as { id: string }).id : undefined;
+								if (!seenSteers.markOrSkip(entryId)) continue;
 								// FIX-02: sanitize each steer entry before forwarding
 								// to pi.sendMessage. Reject oversized payloads,
 								// excessive newlines, and control characters.
@@ -257,6 +330,41 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 		}
 	}
 
+	// ── Feature 2b: broker push steering (opt-in, layered on the file poll) ──
+	// When the parent injected broker credentials, connect a broker client and
+	// deliver pushed steers with the SAME sanitize + pi.sendMessage path as the
+	// file poll above. The file poll remains the durable fallback; a broker
+	// connect failure is invisible to the worker.
+	const brokerHandle = startChildBrokerClient({
+		onSteer: (rawMessage, id) => {
+			// FIX-S1: cross-channel dedup. The broker persists every steer to
+			// the steering JSONL (durable) AND pushes it via the mailbox
+			// observer (live). This callback sees the live push; the
+			// pollSteering path above will see the same steer on its next
+			// tick. Keying on `id` (a stable identifier emitted by the broker)
+			// guarantees a single pi.sendMessage per steer.
+			if (!seenSteers.markOrSkip(id)) return;
+			const sanitized = sanitizeSteerMessage({ type: "steer", message: rawMessage });
+			if (!sanitized.valid || sanitized.message === undefined) {
+				logInternalError(
+					"prompt-runtime.broker-steer-rejected",
+					new Error(sanitized.reason ?? "steer-sanitization-failed"),
+					undefined,
+					"warn",
+				);
+				return;
+			}
+			pi.sendMessage({ customType: "crew-steer", content: sanitized.message, display: false }, { deliverAs: "steer" });
+		},
+	});
+	// Close the broker connection on session shutdown to avoid leaking the
+	// persistent socket / reconnect timer. Fire-and-forget: the socket is
+	// already .unref()'d so it never blocks event-loop exit; errors are
+	// swallowed because teardown failures during shutdown are harmless.
+	pi.on("session_shutdown", () => {
+		void brokerHandle.close().catch(() => {});
+	});
+
 	// ── Prompt rewriting (existing) ────────────────────────────────────────
 	pi.on("before_agent_start", (event) => {
 		const inheritProjectContext = readBooleanEnvAny(PI_CREW_INHERIT_PROJECT_CONTEXT_ENV, PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);

package/src/runtime/broker-issuer.ts

@@ -0,0 +1,37 @@
+/**
+ * broker-issuer.ts — Process-local registry for the active broker credential
+ * issuer.
+ *
+ * The broker lifecycle controller (parent/root session) registers its
+ * `issueForChild` function here on start and clears it on stop. `runChildPi`
+ * reads it as the default `brokerIssuer` so the spawn path does not need the
+ * registration context threaded through every runner call site.
+ *
+ * This mirrors the existing module-level singletons in the codebase
+ * (`runEventBus`, the mailbox append observers). It lives ONLY in the parent
+ * process — children never register an issuer (they receive credentials via
+ * env). The value is a function reference, never a token; nothing here is
+ * persisted or logged.
+ */
+
+/** Credentials handed to a child worker so it can authenticate to the broker. */
+export interface BrokerSpawnCredentials {
+	socketPath: string;
+	token: string;
+}
+
+/** Issuer signature: given a runId, return credentials or undefined when the
+ *  broker is disabled / this process is not the root session. */
+export type BrokerIssuer = (runId: string) => Promise<BrokerSpawnCredentials | undefined>;
+
+let activeIssuer: BrokerIssuer | undefined;
+
+/** Register the active issuer (called by the lifecycle controller on start). */
+export function setActiveBrokerIssuer(issuer: BrokerIssuer | undefined): void {
+	activeIssuer = issuer;
+}
+
+/** Read the active issuer, if any. Returns undefined when no broker is wired. */
+export function getActiveBrokerIssuer(): BrokerIssuer | undefined {
+	return activeIssuer;
+}

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

@@ -166,6 +166,44 @@ export function assertOnlyControlEnvKeys(builtEnv: Record<string, string | undef
 	}
 }
 
+/**
+ * Compose the final SpawnOptions for a child Pi worker: runs the runtime canary
+ * (assertOnlyControlEnvKeys) on builtEnv, builds the allowlist-filtered base
+ * SpawnOptions via buildChildPiSpawnOptions, then re-applies builtEnv on top
+ * so the PI_CREW_-prefixed / PI_TEAMS_-prefixed execution-control vars actually
+ * reach the child.
+ *
+ * Extracted from child-pi.ts (BLOCKER 2 / S5) so the spread step is testable
+ * in isolation and the canary lives in one place. Guarantees:
+ *   1. The canary runs FIRST — a non-control key in builtEnv throws before
+ *      buildChildPiSpawnOptions (and before spawn()) is ever called.
+ *   2. The spread always runs LAST on the SpawnOptions returned by
+ *      buildChildPiSpawnOptions — the filtered base env cannot accidentally
+ *      drop execution-control vars that the child needs (steering file, kind,
+ *      role, broker credentials, etc.).
+ *   3. The returned SpawnOptions.env contains BOTH the allowlist-filtered
+ *      system vars (PATH, HOME, …) AND the per-call control vars.
+ */
+export function buildFinalChildPiSpawnOptions(
+	cwd: string,
+	mergedEnv: NodeJS.ProcessEnv,
+	builtEnv: Record<string, string | undefined>,
+	model?: string,
+): SpawnOptions {
+	// (a) Canary: builtEnv must contain ONLY PI_CREW_*/PI_TEAMS_* keys.
+	assertOnlyControlEnvKeys(builtEnv);
+	// (b) Build the allowlist-filtered base SpawnOptions (cwd validation, env
+	//     filtering, provider-key scoping when model is set, NODE_PATH guard).
+	const spawnOptions = buildChildPiSpawnOptions(cwd, mergedEnv, model);
+	// (c) Spread builtEnv back on top — the allowlist in step (b) intentionally
+	//     strips PI_CREW_*/PI_TEAMS_* keys, so without this spread the child
+	//     process would never see steering file, kind, role, or broker creds.
+	//     Safe because step (a) just proved builtEnv holds no secret keys.
+	spawnOptions.env = { ...spawnOptions.env, ...builtEnv };
+	// (d) Return the composed SpawnOptions for spawn(...).
+	return spawnOptions;
+}
+
 /** What the spawn site needs to start the child process. */
 export interface SpawnContext {
 	/** The command + args returned by getPiSpawnCommand. */
@@ -201,6 +239,21 @@ export function prepareSpawnContext(
 	});
 	// Pass steering file path to child for real-time steer injection
 	if (input.steeringFile) built.env.PI_CREW_STEERING_FILE = input.steeringFile;
+	// 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.
+	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;
+		// The child needs its own runId + taskId to complete the broker `hello`
+		// (the token is validated against the runId; the taskId binds the
+		// connection for message routing). Both are control-namespace keys so
+		// they pass assertOnlyControlEnvKeys. agentId is the per-task id.
+		if (input.runId) built.env.PI_CREW_BROKER_RUN_ID = input.runId;
+		if (input.agentId) built.env.PI_CREW_BROKER_TASK_ID = input.agentId;
+	}
 	// B5: if the parent already aborted before we spawn, do not start the child
 	// at all. Spawning a doomed process wastes resources, and the abort listener
 	// registered below will not re-fire for an already-aborted signal (so the