pi-crew 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.8.6] — General cold-start race fix (runtime module-graph warmup) (2026-06-17)
+
+Fixes the `validateWorkflowForTeam` cold-start crash that v0.8.1 did NOT
+actually fix (honest correction — v0.8.1's per-import latch covered only the
+peer-dep namespace `existsSync` variant, not this pi-crew-internal variant).
+
+### Corrected root cause
+
+Under the **tsx loader**, a named import `import { X } from "mod"` compiles to
+`mod_1.X` — a namespace-property access at runtime. If `mod_1` is observed
+mid-instantiation as `undefined` during concurrent cold-start, the access
+throws `Cannot read properties of undefined (reading 'X')`. **ANY module in
+the graph is vulnerable**, not just the peer dep. v0.8.1's per-import latch
+can't scale to every named import in `src/`.
+
+### Fix — general, not per-import
+
+1. **Pre-warm at registration.** `startRuntimeWarmup()` fires eager `import()`
+   of the hot module graph ROOTS during single-threaded `registerPiTeams()` —
+   before any subagent can spawn. ESM transitively instantiates their entire
+   import graph, so one import per path warms the full subgraph.
+2. **Await at spawn boundaries.** `awaitRuntimeWarmup()` is awaited at the top
+   of `runLiveSessionTask` and `runTeamTask` — the two spawn entry points — so
+   the graph is guaranteed warm before any module is touched, regardless of
+   which binding would otherwise race.
+
+The warmup runs in milliseconds (module loading only). The await is
+belt-and-suspenders for the pathological case where a spawn races the warmup
+promise. Errors are swallowed — a failed warmup (e.g. peer dep absent) never
+blocks the extension; worst case the old race returns (no worse than before).
+
+### Files
+- NEW `src/runtime/runtime-warmup.ts` — `startRuntimeWarmup()` (idempotent
+  fire-and-forget) + `awaitRuntimeWarmup()` (gate) + test seams.
+- `src/extension/register.ts` — `startRuntimeWarmup()` early in
+  `registerPiTeams`.
+- `src/runtime/live-session-runtime.ts` — `await awaitRuntimeWarmup()` at top
+  of `runLiveSessionTask`.
+- `src/runtime/task-runner.ts` — `await awaitRuntimeWarmup()` at top of
+  `runTeamTask`.
+- NEW `test/unit/runtime-warmup.test.ts` (6 tests): idempotency, no-hang,
+  back-compat (no-op when not started), hot-module specifiers resolve,
+  integration (graph actually warms).
+- Updated `.github/issues/2026-06-16-validateworkflowf-team-cold-start-race.md`
+  — marked RESOLVED with the fix applied.
+
+typecheck clean; full suite 0 real failures (2 timer flakes under local load
+pass 3/3 in isolation — clean on CI).
+
 ## [0.8.5] — Per-write validator (T5) + validateWorkflowForTeam race note (2026-06-16)
 
 Third APPLIED technique from the pi-ecosystem distillation (pi-lens /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/register.ts

@@ -83,6 +83,7 @@ import { RenderScheduler } from "../ui/render-scheduler.ts";
 import { runEventBus } from "../ui/run-event-bus.ts";
 import { createTerminalStatusController, type TerminalStatusController } from "../ui/terminal-status.ts";
 import { extractPathFromInput, validateWrittenFile, buildValidationBlocker } from "../runtime/per-write-validator.ts";
+import { startRuntimeWarmup } from "../runtime/runtime-warmup.ts";
 import { createRunSnapshotCache } from "../ui/run-snapshot-cache.ts";
 import { closeWatcher } from "../utils/fs-watch.ts";
 import { RunWatcherRegistry } from "../utils/run-watcher-registry.ts";
@@ -198,6 +199,14 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	const disposeI18n = initI18n(pi);
 	resetTimings();
 	time("register:start");
+	// Cold-start race fix (general): pre-warm the hot module graph NOW, during
+	// single-threaded registration, before any concurrent subagent can spawn.
+	// Under the tsx loader, concurrent first-imports race module-record
+	// instantiation → `Cannot read properties of undefined (reading '<X>')` for
+	// ANY named import (observed: existsSync, validateWorkflowForTeam).
+	// Warming the graph here + awaiting it at spawn boundaries eliminates the
+	// race window. See src/runtime/runtime-warmup.ts.
+	startRuntimeWarmup();
 	// Deploy bundled themes (crew-dark, crew-dracula, etc.) to ~/.pi/agent/themes/
 	// so Pi's theme loader discovers them. Best-effort, idempotent.
 	deployBundledThemes();

package/src/extension/team-tool/doctor.ts

@@ -9,6 +9,7 @@ import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
 import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
+import { getRuntimeWarmupStatus } from "../../runtime/runtime-warmup.ts";
 import { validateResources } from "../validate-resources.ts";
 import { detectDrift, formatDriftReport, type DriftReport } from "../../config/drift-detector.ts";
 import { TeamToolParams } from "../../schema/team-tool-schema.ts";
@@ -188,6 +189,37 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 			{ label: "leader repository", ok: true, detail: input.cwd },
 			{ label: "cleanup policy", ok: true, detail: "dirty worktrees preserved unless force is set" },
 		]),
+		section("Runtime warmup (cold-start fix v0.8.6)", () => {
+			// Surface whether the general cold-start-race fix is active + how long
+			// the graph warmup took, so a session can confirm the fix loaded
+			// (post-restart) and isn't pathologically slow. An UNWARMED graph is
+			// the documented cause of `Cannot read properties of undefined
+			// (reading '<binding>')` under concurrent subagent spawn.
+			//
+			// "Not started" is NOT a doctor error: it is the normal state in unit
+			// tests and in any caller that invokes buildTeamDoctorReport directly
+			// without going through registerPiTeams. Only a STARTED-but-FAILED
+			// warmup is an error (something genuinely went wrong during pre-warm).
+			const status = getRuntimeWarmupStatus();
+			const checks: DoctorCheck[] = [
+				{
+					label: "warmup started",
+					ok: true, // informational — "not started" is not a failure
+					detail: status.started ? "module graph pre-warmed at registration" : "not started in this process (normal for direct unit-test calls; in a live Pi session, started at extension load)",
+				},
+			];
+			if (status.started) {
+				checks.push({
+					label: "warmup completed",
+					ok: status.completed,
+					detail: status.completed ? (status.durationMs !== undefined ? `graph warm in ${status.durationMs}ms` : "completed") : "in progress",
+				});
+				if (status.error) {
+					checks.push({ label: "warmup error", ok: false, detail: status.error });
+				}
+			}
+			return checks;
+		}),
 	];
 	if (input.smokeChildPi) {
 		sections.push([`Child check`, `- ${input.smokeChildPi.ok ? "OK" : "FAIL"} child Pi smoke: ${input.smokeChildPi.detail}`]);

package/src/runtime/live-session-runtime.ts

@@ -18,6 +18,7 @@ import { buildConfiguredModelRouting } from "./model-fallback.ts";
 import { readEnabledModelsPatterns } from "./model-scope.ts";
 import { resolveToolPolicy } from "../agents/agent-config.ts";
 import { loadConfig } from "../config/config.ts";
+import { awaitRuntimeWarmup } from "./runtime-warmup.ts";
 import { DEFAULT_LIVE_SESSION } from "../config/defaults.ts";
 import { buildYieldReminder, hasYieldInOutput, isYieldEvent, extractYieldResult, validateYieldData, DEFAULT_YIELD_CONFIG, type YieldResult } from "./yield-handler.ts";
 import { buildMcpProxyFromSession } from "./mcp-proxy.ts";
@@ -396,6 +397,10 @@ export async function probeLiveSessionRuntime(): Promise<LiveSessionUnavailableR
 }
 
 export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<LiveSessionRunResult> {
+	// Cold-start race fix: ensure the hot module graph is warm before touching
+	// any module. Under tsx, concurrent first-imports race module-record
+	// instantiation; awaiting the registration-time warmup eliminates the window.
+	await awaitRuntimeWarmup();
 	const isCurrent = input.isCurrent ?? (() => true);
 	let streamOut: StreamingOutputHandle | undefined;
 

package/src/runtime/runtime-warmup.ts

@@ -0,0 +1,156 @@
+/**
+ * Runtime module-graph warmup — general fix for the cold-start race.
+ *
+ * Problem: when N in-process live-session subagents spawn CONCURRENTLY, the
+ * tsx loader can race module-record instantiation, yielding
+ * `Cannot read properties of undefined (reading '<binding>')` for ANY named
+ * import in the hot graph (observed: `existsSync`, `validateWorkflowForTeam`).
+ * v0.8.1's per-import latch covered only the peer-dep namespace; this is the
+ * GENERAL fix.
+ *
+ * Root cause: under tsx, a named import `import { X } from "mod"` compiles to
+ * `mod_1.X` — a namespace-property access at runtime. If `mod_1` (the module
+ * namespace object) is observed mid-instantiation as `undefined`, the access
+ * throws. ANY module in the graph is vulnerable, not just the peer dep. So
+ * per-import latching doesn't scale.
+ *
+ * Fix: pre-warm the hot module graph during SINGLE-THREADED extension
+ * registration (before any subagent can spawn), then `await` the warmup at
+ * every spawn entry point. By the time concurrent subagents touch the graph,
+ * every module record is fully instantiated → no race window.
+ *
+ * Why this is general (not per-import):
+ *   - `startRuntimeWarmup()` fires `import()` for the ROOT modules of each
+ *     hot execution path. ESM transitively instantiates their entire import
+ *     graph, so one import per path warms the whole reachable subgraph.
+ *   - `awaitRuntimeWarmup()` is the gate: spawn paths await it before
+ *     touching any module, guaranteeing the graph is warm regardless of
+ *     which specific binding races.
+ *
+ * The warmup runs during `registerPiTeams()` (single-threaded, before pi
+ * accepts user input). It resolves in milliseconds (module loading only, no
+ * I/O for local modules). The `await` at spawn boundaries is belt-and-
+ * suspenders for pathological cases where a spawn races the warmup promise.
+ *
+ * @module runtime-warmup
+ */
+
+/**
+ * The modules whose transitive import graphs cover every hot execution path
+ * a concurrent subagent can reach. Importing the ROOT of each path warms the
+ * full subgraph (ESM instantiates imports eagerly during `import()`).
+ *
+ * - `./live-session-runtime.ts` — the in-process subagent spawn path
+ *   (pulls in the peer dep + the entire runtime layer).
+ * - `./task-runner.ts` — the child-process task dispatch path.
+ * - `../extension/team-tool.ts` — the team tool (pulls in
+ *   validate-resources → validate-workflow, the `validateWorkflowForTeam` site).
+ * - `../extension/validate-resources.ts` — direct warm of the aggregator.
+ * - `@earendil-works/pi-coding-agent` — the peer dep (the `existsSync` site;
+ *   also latched in v0.8.1 — defense in depth).
+ */
+const HOT_MODULE_SPECIFIERS = [
+	"./live-session-runtime.ts",
+	"./task-runner.ts",
+	"../extension/team-tool.ts",
+	"../extension/validate-resources.ts",
+] as const;
+
+/** Additional bare-specifier peer deps to warm. */
+const HOT_PEER_DEPS = ["@earendil-works/pi-coding-agent"] as const;
+
+let warmupPromise: Promise<void> | undefined;
+let warmupStarted = false;
+let warmupCompleted = false;
+let warmupDurationMs: number | undefined;
+let warmupError: string | undefined;
+
+/**
+ * Start the runtime warmup (idempotent). Fires eager `import()` of the hot
+ * module graph. Safe to call during single-threaded registration — the
+ * promises resolve on the event loop before any subagent can spawn.
+ *
+ * Errors are swallowed: a failed warmup (e.g. peer dep absent) must never
+ * block the extension from loading. The worst case is the old race returns
+ * (which is no worse than before this fix).
+ */
+export function startRuntimeWarmup(): void {
+	if (warmupStarted) return;
+	warmupStarted = true;
+	const startedAt = Date.now();
+	warmupPromise = (async (): Promise<void> => {
+		const imports: Array<Promise<unknown>> = [];
+		for (const spec of HOT_MODULE_SPECIFIERS) {
+			imports.push(
+				import(new URL(spec, import.meta.url).href).catch(() => {
+					// swallow — never block registration on a warmup failure
+				}),
+			);
+		}
+		for (const dep of HOT_PEER_DEPS) {
+			imports.push(
+				import(dep).catch(() => {
+					// peer dep may be absent (optional dep) — swallow
+				}),
+			);
+		}
+		await Promise.all(imports);
+	})()
+		.then(() => {
+			warmupCompleted = true;
+			warmupDurationMs = Date.now() - startedAt;
+		})
+		.catch((err: unknown) => {
+			// final safety net — warmup must never reject. Record for diagnostics.
+			warmupError = err instanceof Error ? err.message : String(err ?? "unknown");
+		});
+}
+
+/**
+ * Await the runtime warmup at a spawn entry point. No-op if warmup hasn't
+ * started (back-compat for callers that don't call startRuntimeWarmup) or has
+ * already resolved. Guarantees the hot module graph is instantiated before
+ * the caller touches any module — eliminating the concurrent cold-start race.
+ */
+export async function awaitRuntimeWarmup(): Promise<void> {
+	if (warmupPromise) await warmupPromise;
+}
+
+/**
+ * Test seam: reset the warmup state so tests can re-trigger it. Also lets
+ * tests verify idempotency by calling startRuntimeWarmup() multiple times.
+ */
+export function resetRuntimeWarmupForTest(): void {
+	warmupPromise = undefined;
+	warmupStarted = false;
+	warmupCompleted = false;
+	warmupDurationMs = undefined;
+	warmupError = undefined;
+}
+
+/** Test seam: has startRuntimeWarmup() been called? */
+export function isRuntimeWarmupStarted(): boolean {
+	return warmupStarted;
+}
+
+/**
+ * Diagnostic snapshot of warmup state for `team doctor`. Surfaces whether the
+ * v0.8.6 cold-start fix is active and how long the graph warmup took, so a
+ * session can confirm the fix loaded (post-restart) and isn't pathologically
+ * slow.
+ */
+export interface RuntimeWarmupStatus {
+	started: boolean;
+	completed: boolean;
+	durationMs: number | undefined;
+	error: string | undefined;
+}
+
+export function getRuntimeWarmupStatus(): RuntimeWarmupStatus {
+	return {
+		started: warmupStarted,
+		completed: warmupCompleted,
+		durationMs: warmupDurationMs,
+		error: warmupError,
+	};
+}

package/src/runtime/task-runner.ts

@@ -40,6 +40,7 @@ import {
 	type ParsedPiJsonOutput,
 } from "./pi-json-output.ts";
 import { runChildPi, type ChildPiLifecycleEvent } from "./child-pi.ts";
+import { awaitRuntimeWarmup } from "./runtime-warmup.ts";
 import { buildTaskPacket } from "./task-packet.ts";
 import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { createVerificationEvidence } from "./green-contract.ts";
@@ -155,6 +156,10 @@ export interface TaskRunnerInput {
 export async function runTeamTask(
 	input: TaskRunnerInput,
 ): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	// Cold-start race fix: ensure the hot module graph is warm before touching
+	// any module. Under tsx, concurrent first-imports race module-record
+	// instantiation; awaiting the registration-time warmup eliminates the window.
+	await awaitRuntimeWarmup();
 	let manifest = input.manifest;
 	// H4: registerStreamBridge inside try so dispose() in finally is safe
 	let streamBridge: ReturnType<typeof registerStreamBridge> | undefined;