pi-crew 0.9.44 → 0.9.47

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)
@@ -521,7 +528,15 @@ function setupRenderLoop(
 		{
 			const onRunChange = (runId: string): void => {
 				if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return;
-				ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).invalidate(runId);
+				// FLICKER FIX: rebuild-in-place instead of deleting the entry. The
+				// file just changed on disk, so force a fresh snapshot while keeping
+				// the entry populated — deleting it left a window where the widget's
+				// `get()` returned undefined and dropped the run to "(loading…)".
+				try {
+					ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
+				} catch (error) {
+					logInternalError("register.runWatcher.refresh", error, runId);
+				}
 				ctx.renderScheduler?.schedule({ runId });
 			};
 			const onWatchErr = (error: unknown): void => {
@@ -678,7 +693,23 @@ function setupRenderLoop(
 				typeof (payload as { runId: unknown }).runId === "string"
 					? (payload as { runId: string }).runId
 					: undefined;
-			ctx.getRunSnapshotCache(extensionCtx.cwd).invalidate(runId);
+			// FLICKER FIX: never hard-delete snapshot entries from a render-scheduler
+			// invalidate. A no-runId payload — emitted by EVERY fallback tick
+			// (~every 160ms while a run is active) — previously ran
+			// `invalidate(undefined)` → `entries.clear()`, wiping ALL snapshots.
+			// The next `renderTick` then saw `get() === undefined` for every run,
+			// so `activeWidgetRuns` dropped them to "(loading…)" until the async
+			// preload rebuilt the cache — an endless visible flicker. For a
+			// specific runId we now refresh-if-stale (stale-while-revalidate) so
+			// the widget always sees a populated snapshot; a no-runId tick does
+			// nothing (renderTick itself repaints; the cache's own
+			// run:state/worker:lifecycle subscription refreshes affected runs).
+			if (!runId) return;
+			try {
+				ctx.getRunSnapshotCache(extensionCtx.cwd).refreshIfStale(runId);
+			} catch (error) {
+				logInternalError("register.renderScheduler.refresh", error, runId);
+			}
 		},
 	});
 	// Fix D: bridge internal runEventBus events to renderScheduler so the UI
@@ -697,7 +728,14 @@ function setupRenderLoop(
 	// Bounded run watcher setup (pts/2 hang fix 2026-06-16).
 	const crewRunWatcherOnChange = (runId: string): void => {
 		if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return;
-		ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).invalidate(runId);
+		// FLICKER FIX: rebuild-in-place instead of deleting the entry (see
+		// onRunChange above). A hard delete left `get()` returning undefined for
+		// a frame, dropping the run to "(loading…)" and causing visible flicker.
+		try {
+			ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
+		} catch (error) {
+			logInternalError("register.crewRunWatcher.refresh", error, runId);
+		}
 		ctx.renderScheduler?.schedule({ runId });
 	};
 	const crewRunWatcherOnError = (error: unknown): void => {
@@ -729,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;
 }