pi-crew 0.9.26 → 0.9.27

package/scripts/test-issue-29-real-tasks.ts

@@ -0,0 +1,387 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * REAL-TASK E2E test for issue #29.
+ *
+ * This test runs ACTUAL pi-crew operations in a .pi/-only project (no
+ * .crew/ directory) to verify the fix works end-to-end through the
+ * public API — not just isolated unit tests.
+ *
+ * Operations exercised:
+ *   1. spawnBackgroundTeamRun() — exercises the background-runner path
+ *      (which writes to background.log and exit-code.txt using paths
+ *      that previously hardcoded .crew/state/runs/).
+ *   2. waitForRun() — the CRASH site. With fix, the slow-path early-exit
+ *      uses projectCrewRoot() so the error message references .pi/teams/.
+ *   3. loadRunManifestById() — the loader used by waitForRun's fast path,
+ *      which was always correct but is exercised here for completeness.
+ *   4. saveCheckpoint() / loadCheckpoint() — round-trip through .pi/teams/.
+ *   5. recordSkillActivation() / getSkillActivations() — paths land in
+ *      .pi/teams/state/runs/, not .crew/.
+ *   6. Full executeTeamRun() with executeWorkers=false — runs the entire
+ *      team-runner pipeline (with placeholder results) which internally
+ *      creates manifests, tasks, events.jsonl, and exercises the full
+ *      projectCrewRoot() path.
+ *   7. initLedger() / appendEntry() — decision-ledger uses projectCrewRoot()
+ *      when stateRoot is omitted.
+ *
+ * Crash detection: registers uncaughtException + unhandledRejection
+ * listeners. Any crash during the operations causes exit 1.
+ *
+ * Run with: npx tsx scripts/test-issue-29-real-tasks.ts
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-issue-29-real-"));
+fs.mkdirSync(path.join(tmpDir, ".pi"), { recursive: true });
+// CRITICALLY: no .crew/
+
+console.log("=".repeat(72));
+console.log("Issue #29 REAL-TASK E2E test (exercises public API)");
+console.log("=".repeat(72));
+console.log(`Project: ${tmpDir}`);
+console.log(`  Has .pi/  : ${fs.existsSync(path.join(tmpDir, ".pi"))}`);
+console.log(`  Has .crew/: ${fs.existsSync(path.join(tmpDir, ".crew"))} (should be false)`);
+console.log();
+
+// ── Crash detection ──────────────────────────────────────────────────────
+let crashed = false;
+let crashError: Error | undefined;
+process.on("uncaughtException", (error) => {
+	crashed = true;
+	crashError = error;
+	console.error(`[CRASH] uncaughtException: ${error.message}`);
+});
+process.on("unhandledRejection", (reason) => {
+	crashed = true;
+	const err = reason instanceof Error ? reason : new Error(String(reason));
+	crashError = err;
+	console.error(`[CRASH] unhandledRejection: ${err.message}`);
+});
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+const piCrewRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+let pass = 0;
+let fail = 0;
+const failures: string[] = [];
+
+function check(label: string, condition: boolean, detail = ""): void {
+	if (condition) {
+		pass++;
+		console.log(`  ✓ ${label}`);
+	} else {
+		fail++;
+		failures.push(label);
+		console.error(`  ✗ ${label}${detail ? ` — ${detail}` : ""}`);
+	}
+}
+
+async function main(): Promise<void> {
+	// Force placeholder-result mode (no child process spawns needed for the
+	// full executeTeamRun pipeline).
+	process.env.PI_CREW_EXECUTE_WORKERS = "false";
+
+	// ── Test 1: projectCrewRoot returns the right path ─────────────────
+	console.log();
+	console.log("Test 1: projectCrewRoot resolver");
+	console.log("-".repeat(72));
+	const { projectCrewRoot, clearProjectRootCache } = await import(path.join(piCrewRoot, "src/utils/paths.ts"));
+	clearProjectRootCache();
+	const root = projectCrewRoot(tmpDir);
+	check(`projectCrewRoot returns .pi/teams/ for .pi-only project (got: ${root})`, root === path.join(tmpDir, ".pi", "teams"));
+
+	// ── Test 2: Full executeTeamRun() pipeline ──────────────────────────
+	// This runs the actual team-runner (with executeWorkers=false so it
+	// doesn't spawn child Pi processes). It internally creates the manifest,
+	// tasks.json, events.jsonl, and exercises every projectCrewRoot() site.
+	console.log();
+	console.log("Test 2: Full executeTeamRun() pipeline (with placeholder workers)");
+	console.log("-".repeat(72));
+
+	const { createRunManifest, createTasksFromWorkflow, loadRunManifestById } = await import(
+		path.join(piCrewRoot, "src/state/state-store.ts")
+	);
+	const { discoverTeams, allTeams } = await import(path.join(piCrewRoot, "src/teams/discover-teams.ts"));
+	const { discoverAgents, allAgents } = await import(path.join(piCrewRoot, "src/agents/discover-agents.ts"));
+	const { discoverWorkflows, allWorkflows } = await import(path.join(piCrewRoot, "src/workflows/discover-workflows.ts"));
+	const { executeTeamRun } = await import(path.join(piCrewRoot, "src/runtime/team-runner.ts"));
+
+	const teams = allTeams(discoverTeams(tmpDir));
+	const agents = allAgents(discoverAgents(tmpDir));
+	const workflows = allWorkflows(discoverWorkflows(tmpDir));
+	console.log(`  Discovered ${teams.length} teams, ${agents.length} agents, ${workflows.length} workflows`);
+
+	const team = teams.find((t) => t.name === "fast-fix");
+	const workflow = workflows.find((w) => w.name === "fast-fix");
+	check("fast-fix team found", Boolean(team));
+	check("fast-fix workflow found", Boolean(workflow));
+
+	if (team && workflow) {
+		const {
+			manifest,
+			tasks: initialTasks,
+			paths,
+		} = createRunManifest({
+			cwd: tmpDir,
+			team,
+			workflow,
+			goal: "E2E test for issue #29: run real team-runner pipeline in .pi-only project",
+			workspaceMode: "single",
+		});
+		const tasks = initialTasks;
+
+		console.log(`  Created run: ${manifest.runId}`);
+		console.log(`  Tasks: ${tasks.length}`);
+
+		const start = Date.now();
+		try {
+			const result = await executeTeamRun({
+				manifest,
+				tasks,
+				team,
+				workflow,
+				agents,
+				executeWorkers: false,
+				workspaceId: "e2e-test-29",
+			});
+			const elapsed = Date.now() - start;
+			console.log(`  executeTeamRun completed in ${elapsed}ms`);
+			console.log(`  Final status: ${result.manifest.status}`);
+
+			// Verify the manifest is at the right path
+			const expectedStateRoot = path.join(tmpDir, ".pi", "teams", "state", "runs", manifest.runId);
+			check(
+				`manifest.stateRoot is under .pi/teams/state/runs/`,
+				result.manifest.stateRoot === expectedStateRoot,
+				`got: ${result.manifest.stateRoot}`,
+			);
+
+			// Verify the manifest can be reloaded
+			const reloaded = loadRunManifestById(tmpDir, manifest.runId);
+			check("manifest can be reloaded by loadRunManifestById()", Boolean(reloaded));
+			if (reloaded) {
+				check("reloaded manifest has same runId", reloaded.manifest.runId === manifest.runId);
+			}
+
+			// Verify .pi/teams/state/runs/<runId>/ directory exists
+			check(`.pi/teams/state/runs/${manifest.runId}/ exists`, fs.existsSync(expectedStateRoot));
+
+			// Verify NO .crew/ directory was created
+			check(`no .crew/ directory was created (would indicate fallback)`, !fs.existsSync(path.join(tmpDir, ".crew")));
+
+			// Verify all expected files are under .pi/teams/
+			const runDir = expectedStateRoot;
+			const expectedFiles = ["manifest.json", "tasks.json", "events.jsonl"];
+			for (const f of expectedFiles) {
+				check(`${f} exists at .pi/teams/state/runs/<runId>/${f}`, fs.existsSync(path.join(runDir, f)));
+			}
+		} catch (error) {
+			fail++;
+			failures.push("executeTeamRun");
+			console.error(`  ✗ executeTeamRun FAILED: ${(error as Error).message}`);
+		}
+	}
+
+	// ── Test 3: waitForRun() with real runId ────────────────────────────
+	console.log();
+	console.log("Test 3: waitForRun() against the just-created run");
+	console.log("-".repeat(72));
+	const { waitForRun } = await import(path.join(piCrewRoot, "src/runtime/run-tracker.ts"));
+	if (team && workflow) {
+		const { manifest, tasks } = createRunManifest({
+			cwd: tmpDir,
+			team,
+			workflow,
+			goal: "waitForRun test",
+			workspaceMode: "single",
+		});
+		// Manually write a completed manifest (avoid running the full pipeline again)
+		const completedManifest = {
+			...manifest,
+			status: "completed" as const,
+			summary: "Test completed",
+			updatedAt: new Date().toISOString(),
+			completedAt: new Date().toISOString(),
+		};
+		fs.mkdirSync(completedManifest.stateRoot, { recursive: true });
+		fs.writeFileSync(path.join(completedManifest.stateRoot, "manifest.json"), JSON.stringify(completedManifest, null, 2));
+		fs.writeFileSync(path.join(completedManifest.stateRoot, "tasks.json"), JSON.stringify(tasks, null, 2));
+		fs.writeFileSync(path.join(completedManifest.stateRoot, "events.jsonl"), "");
+
+		const start = Date.now();
+		try {
+			const result = await waitForRun(manifest.runId, tmpDir, {
+				timeoutMs: 2000,
+				pollIntervalMs: 50,
+			});
+			const elapsed = Date.now() - start;
+			check(
+				`waitForRun() succeeded in ${elapsed}ms (manifest.status=${result.manifest.status})`,
+				result.manifest.status === "completed",
+			);
+		} catch (error) {
+			fail++;
+			failures.push("waitForRun");
+			console.error(`  ✗ waitForRun FAILED: ${(error as Error).message}`);
+		}
+	}
+
+	// ── Test 4: waitForRun() with non-existent runId (slow path) ────────
+	console.log();
+	console.log("Test 4: waitForRun() with non-existent runId (slow path early-exit)");
+	console.log("-".repeat(72));
+	try {
+		await waitForRun("team_definitely_does_not_exist_xyz_29", tmpDir, {
+			timeoutMs: 200,
+			pollIntervalMs: 50,
+		});
+		fail++;
+		failures.push("waitForRun(non-existent)");
+		console.error("  ✗ waitForRun should have thrown");
+	} catch (error) {
+		const msg = (error as Error).message;
+		check(
+			"error message references .pi/teams/ (not .crew/state/runs/)",
+			msg.includes(".pi/teams") && !msg.includes(".crew/state/runs"),
+			`got: ${msg}`,
+		);
+	}
+
+	// ── Test 5: saveCheckpoint / loadCheckpoint round-trip ──────────────
+	console.log();
+	console.log("Test 5: saveCheckpoint / loadCheckpoint round-trip");
+	console.log("-".repeat(72));
+	const { saveCheckpoint, loadCheckpoint, listCheckpoints, clearCheckpointStores } = await import(
+		path.join(piCrewRoot, "src/runtime/checkpoint.ts")
+	);
+	const ckRunId = `ck_real_${Date.now().toString(36)}`;
+	const ckTaskId = "task-real-1";
+	saveCheckpoint(ckRunId, ckTaskId, 1, "context", "progress", "agent-real", "model-real", tmpDir);
+	const loaded = loadCheckpoint(ckRunId, ckTaskId, tmpDir);
+	check("saveCheckpoint → loadCheckpoint round-trip", Boolean(loaded));
+	if (loaded) {
+		check("loaded checkpoint has correct taskId", loaded.taskId === ckTaskId);
+		check("loaded checkpoint has correct progress", loaded.progress === "progress");
+	}
+	const ckPath = path.join(tmpDir, ".pi", "teams", "state", "runs", ckRunId, "checkpoints", `${ckTaskId}.json`);
+	check(`checkpoint file at .pi/teams/state/runs/${ckRunId}/checkpoints/${ckTaskId}.json`, fs.existsSync(ckPath));
+	const ckList = listCheckpoints(ckRunId, tmpDir);
+	check(`listCheckpoints returns 1 entry`, ckList.length === 1);
+	clearCheckpointStores();
+
+	// ── Test 6: recordSkillActivation / getSkillActivations ─────────────
+	console.log();
+	console.log("Test 6: recordSkillActivation / getSkillActivations");
+	console.log("-".repeat(72));
+	const { recordSkillActivation, getSkillActivations } = await import(path.join(piCrewRoot, "src/runtime/skill-effectiveness.ts"));
+	const seRunId = `se_real_${Date.now().toString(36)}`;
+	recordSkillActivation(tmpDir, {
+		id: "act-real-1",
+		skillId: "verification-before-done",
+		role: "executor",
+		runId: seRunId,
+		taskId: "task-real-1",
+		timestamp: new Date().toISOString(),
+		passed: true,
+		confidence: 0.7,
+	});
+	const seList = getSkillActivations(tmpDir, seRunId);
+	check("recordSkillActivation → getSkillActivations round-trip", seList.length === 1);
+	if (seList.length === 1) {
+		check("recorded skill has correct skillId", seList[0].skillId === "verification-before-done");
+	}
+	const sePath = path.join(tmpDir, ".pi", "teams", "state", "runs", seRunId, "skill-activations.jsonl");
+	check(`skill-activations file at .pi/teams/state/runs/${seRunId}/skill-activations.jsonl`, fs.existsSync(sePath));
+
+	// ── Test 7: initLedger / appendEntry / getLedger ────────────────────
+	console.log();
+	console.log("Test 7: initLedger / appendEntry / getLedger");
+	console.log("-".repeat(72));
+	const { initLedger, appendEntry, getLedger } = await import(path.join(piCrewRoot, "src/state/decision-ledger.ts"));
+	const ledgerRunId = `ledger_real_${Date.now().toString(36)}`;
+	initLedger(ledgerRunId);
+	appendEntry(ledgerRunId, {
+		rolloutId: "rollout-1",
+		timestamp: new Date().toISOString(),
+		decision: "chose option A",
+		confidence: 0.8,
+		reasoning: "lowest cost",
+	});
+	const ledger = getLedger(ledgerRunId);
+	check(`initLedger + appendEntry round-trip (${ledger.length} entries)`, ledger.length === 1);
+
+	// ── Test 8: background-runner.ts path computation (offline) ──────────
+	// We can't actually spawn the background worker (it requires a real
+	// child Pi process), but we can import the path functions and verify
+	// they would resolve to the right location.
+	console.log();
+	console.log("Test 8: background-runner path resolution (offline check)");
+	console.log("-".repeat(72));
+	// The background-runner.ts uses projectCrewRoot(_cwd) for the log path.
+	// We verify the resolver gives the right path:
+	const logExpectedDir = path.join(projectCrewRoot(tmpDir), "state", "runs");
+	check(`background log dir resolves to .pi/teams/state/runs/`, logExpectedDir === path.join(tmpDir, ".pi", "teams", "state", "runs"));
+
+	// ── Test 9: subagent-manager crash safety ───────────────────────────
+	console.log();
+	console.log("Test 9: subagent-manager crash safety (defense in depth)");
+	console.log("-".repeat(72));
+	const { SubagentManager } = await import(path.join(piCrewRoot, "src/runtime/subagent-manager.ts"));
+	const mgr = new SubagentManager();
+	const throwingRunner = async (): Promise<never> => {
+		throw new Error("simulated failure");
+	};
+	const record = mgr.spawn(
+		{
+			cwd: tmpDir,
+			type: "test",
+			description: "issue-29 real test",
+			prompt: "throw",
+			background: false,
+		},
+		throwingRunner as Parameters<typeof mgr.spawn>[1],
+	);
+	// Do NOT await record.promise — this is the scenario that crashes pi.
+	await new Promise((resolve) => setTimeout(resolve, 300));
+	check(`record.status is 'error' after runner throws`, record.status === "error");
+	check(`no uncaughtException/unhandledRejection fired`, !crashed, crashError?.message);
+
+	// ── Final verdict ───────────────────────────────────────────────────
+	console.log();
+	console.log("=".repeat(72));
+	console.log(`Results: ${pass} passed, ${fail} failed, ${crashed ? "1" : "0"} crashed`);
+	if (failures.length > 0) {
+		console.error("Failures:");
+		for (const f of failures) console.error(`  - ${f}`);
+	}
+	if (crashed) {
+		console.error(`Crashed: ${crashError?.message}`);
+	}
+	console.log("=".repeat(72));
+
+	// Cleanup
+	try {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+
+	if (crashed || fail > 0) {
+		process.exit(1);
+	}
+	process.exit(0);
+}
+
+main().catch((error) => {
+	console.error("Test script itself crashed:");
+	console.error(error);
+	try {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+	process.exit(1);
+});

package/scripts/test-issue-29-team-tool.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Real-world reproduction of issue #29.
+ *
+ * Scenario (from the issue report):
+ *   1. User has a .pi/-only project (no .crew/ directory).
+ *   2. A background team run is in progress; the run directory does NOT
+ *      exist on disk yet (the worker is still starting up).
+ *   3. waitForRun() is called to wait for the run to complete.
+ *   4. waitForRun() takes the slow path and on attempt 0 hits the
+ *      early-exit "Run not found" check.
+ *
+ * On the BUGGY version (pre-fix a80fe6c):
+ *   - The early-exit check uses `path.join(cwd, ".crew", "state", "runs", runId)`
+ *   - That directory does not exist in a .pi/-only project
+ *   - Throws "Run not found. No run directory at <cwd>/.crew/state/runs/..."
+ *   - The throw escapes as an unhandled rejection → pi crashes
+ *
+ * On the FIXED version (a80fe6c):
+ *   - The early-exit check uses `path.join(projectCrewRoot(cwd), "state", "runs", runId)`
+ *   - In a .pi/-only project, projectCrewRoot returns .pi/teams/
+ *   - The check still throws (the directory doesn't exist anywhere), but the
+ *     error message correctly points at .pi/teams/state/runs/...
+ *
+ * The test is "passes on fixed, fails on buggy" — verified by toggling the
+ * fix in src/runtime/run-tracker.ts.
+ *
+ * Run with: npx tsx scripts/test-issue-29-team-tool.ts
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-issue-29-real-"));
+fs.mkdirSync(path.join(tmpDir, ".pi"), { recursive: true });
+// CRITICALLY: no .crew/
+
+console.log("Issue #29 REAL-WORLD reproduction test");
+console.log(`Project: ${tmpDir}`);
+console.log(`  Has .pi/:  ${fs.existsSync(path.join(tmpDir, ".pi"))}`);
+console.log(`  Has .crew/: ${fs.existsSync(path.join(tmpDir, ".crew"))} (should be false)`);
+console.log();
+
+async function main(): Promise<void> {
+	const piCrewRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+	// Realistic scenario: the run manifest does NOT exist yet (the background
+	// worker is still starting up). waitForRun() takes the slow path and
+	// hits the early-exit check on attempt 0 — that's where the bug fires.
+	const runId = `team_real_${Date.now().toString(36)}`;
+	console.log(`Looking for run ${runId}`);
+	console.log(`  Expected (correct) path: ${path.join(tmpDir, ".pi", "teams", "state", "runs", runId)}`);
+	console.log(`  Buggy path:              ${path.join(tmpDir, ".crew", "state", "runs", runId)}`);
+	console.log();
+
+	const { waitForRun } = await import(path.join(piCrewRoot, "src/runtime/run-tracker.ts"));
+
+	console.log("Calling waitForRun()...");
+	const start = Date.now();
+	try {
+		const result = await waitForRun(runId, tmpDir, {
+			timeoutMs: 500,
+			pollIntervalMs: 100,
+		});
+		const elapsed = Date.now() - start;
+		console.error(`✗ waitForRun unexpectedly SUCCEEDED in ${elapsed}ms (should have thrown)`);
+		console.error(`  manifest.status = ${result.manifest.status}`);
+		process.exit(1);
+	} catch (error) {
+		const elapsed = Date.now() - start;
+		const msg = (error as Error).message;
+		console.log(`waitForRun threw after ${elapsed}ms:`);
+		console.log(`  Message: ${msg}`);
+		console.log();
+
+		// The error message must reference the CORRECT path (.pi/teams/...),
+		// not the old hardcoded .crew/state/runs/...
+		if (msg.includes(".pi/teams")) {
+			console.log("✓ Error message references .pi/teams/ (resolver applied)");
+			console.log("✓ TEST PASSED: waitForRun correctly resolves .pi/teams/state/runs/");
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+			process.exit(0);
+		}
+		if (msg.includes(".crew/state/runs")) {
+			console.error("✗ TEST FAILED: Error message references .crew/state/runs/");
+			console.error("  This is the bug described in issue #29:");
+			console.error("  waitForRun() looked in .crew/state/runs/ instead of .pi/teams/state/runs/");
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+			process.exit(1);
+		}
+		console.error(`✗ TEST FAILED: Error message doesn't reference expected path`);
+		console.error(`  Got: ${msg}`);
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+		process.exit(1);
+	}
+}
+
+main().catch((error) => {
+	console.error("Test script itself crashed:");
+	console.error(error);
+	fs.rmSync(tmpDir, { recursive: true, force: true });
+	process.exit(1);
+});

package/scripts/test-runner.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Test runner wrapper that enforces non-zero exit code on failures.
+ *
+ * Problem: `tsx --test` always exits 0 even when tests fail.
+ * Fix: Use stdio: 'inherit' so output streams directly (avoids pipe buffer
+ * deadlocks on large test suites), and rely on the child's exit code.
+ *
+ * Always passes --test-force-exit so the child process cannot hang the
+ * parent (pi) on shutdown. Defensive: prevents the "pi froze" failure
+ * mode where a long-running test keeps file handles/timers open and
+ * blocks the agent's wait-for-exit.
+ *
+ * Usage: node scripts/test-runner.mjs [tsx test args...]
+ */
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+	// When run by Node's test runner (no args), exit 0 gracefully.
+	// This script needs test file arguments to do anything useful.
+	console.log("skip: no test files specified");
+	process.exit(0);
+}
+
+// Always inject --test-force-exit to guarantee child exits (prevents pi hang).
+const hasForceExit = args.includes("--test-force-exit");
+let finalArgs = hasForceExit ? args : ["--test-force-exit", ...args];
+
+// CI reliability: node:test runs test FILES concurrently in one process
+// (--test-concurrency=N). On shared CI runners (GitHub Actions), high
+// concurrency causes cross-file filesystem contention that makes write-then-
+// stat tests (notably state-store's createRunManifest assertions) flake:
+//   - windows-latest: Windows Defender real-time scanning locks freshly-
+//     created temp files → transient EPERM/EBUSY on rename inside
+//     atomicWriteFile (exhausts the ~1.6s rename retries).
+//   - macos-latest: /var/folders tmp contention under load → occasional
+//     4ms instant write failures.
+// The flake only surfaced after the Round 13/14 test additions pushed the
+// runners past their timing threshold. Capping cross-file concurrency at 2
+// across ALL platforms gives the FS room to flush and eliminates the storm.
+// Local dev is unaffected (developers pass --test-concurrency=4 explicitly
+// and run on idle machines). This only clamps the CI-requested value.
+finalArgs = finalArgs.map((arg) => {
+	const m = /^(--test-concurrency)=(\d+)$/.exec(arg);
+	return m && Number(m[2]) > 2 ? `${m[1]}=2` : arg;
+});
+
+const result = spawnSync(
+	process.execPath,
+	["--import", "tsx/esm", "--test", ...finalArgs],
+	{
+		stdio: "inherit",
+		env: { ...process.env, NODE_ENV: "test", PI_CREW_SKIP_HOME_CHECK: "1" },
+		// 2026-07-01: bumped from 600s → 900s after atomic-write.ts added
+		// fs.fsyncSync for the mailbox-replay flake fix. fsync adds ~5-10ms
+		// per atomic-write, which compounded across 5800 tests pushed
+		// Windows CI just over the 10-minute budget. 15 minutes gives
+		// comfortable headroom on Windows (slowest) without masking real
+		// test bugs.
+		timeout: 900_000,
+	},
+);
+
+if (result.error) {
+	console.error("Test runner error:", result.error.message);
+	process.exit(1);
+}
+
+// The Node.js test runner exits with non-zero when tests fail.
+// With --test-force-exit, it may exit with code 1 if force-exited
+// while tests were still running (which shouldn't happen normally).
+process.exit(result.status ?? 0);

package/scripts/verify-flicker-fix.ts

@@ -0,0 +1,109 @@
+// E2E verification for the UI flicker fix.
+// Loads the fixed snapshot-cache, builds a real snapshot against a temp
+// run directory, fires a burst of run:state + worker:lifecycle events
+// (the exact trigger the fix handles), and verifies the cache entry
+// survives the burst synchronously. Pre-fix: every event deleted the
+// cache entry → widget alternated between snapshot path and disk-read
+// fallback every render tick. Post-fix: the entry is preserved (or
+// replaced via coalesced refresh) so the widget sees a stable snapshot.
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { saveCrewAgents } from "../src/runtime/crew-agent-records.ts";
+import { createRunManifest, saveRunManifest } from "../src/state/state-store.ts";
+import { runEventBus } from "../src/ui/run-event-bus.ts";
+import { createRunSnapshotCache } from "../src/ui/run-snapshot-cache.ts";
+
+const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "verify-flicker-"));
+fs.mkdirSync(path.join(cwd, ".crew"), { recursive: true });
+
+const team = {
+	name: "verify",
+	description: "",
+	roles: [{ name: "explorer", agent: "explorer" }],
+	source: "test",
+	filePath: "builtin",
+};
+const workflow = {
+	name: "verify",
+	description: "",
+	steps: [{ id: "explore", role: "explorer" }],
+	source: "test",
+	filePath: "builtin",
+};
+const created = createRunManifest({
+	cwd,
+	team,
+	workflow,
+	goal: "verify-flicker-fix",
+});
+saveRunManifest({ ...created.manifest, status: "running" });
+saveCrewAgents(created.manifest, [
+	{
+		id: `${created.manifest.runId}:01`,
+		runId: created.manifest.runId,
+		taskId: created.tasks[0]?.id ?? "explore",
+		agent: "explorer",
+		role: "explorer",
+		runtime: "child-process",
+		status: "running",
+		startedAt: created.manifest.createdAt,
+		progress: {
+			recentTools: [],
+			recentOutput: ["first"],
+			toolCount: 1,
+			currentTool: "read",
+			tokens: 10,
+		},
+	},
+]);
+
+const cache = createRunSnapshotCache(cwd, { ttlMs: 60_000 });
+const initial = cache.refresh(created.manifest.runId);
+console.log(`INITIAL: signature=${initial.signature} tasks=${initial.tasks.length}`);
+
+const runId = created.manifest.runId;
+// Burst simulating the exact event sequence that fired the OLD flicker:
+// every run:state and worker:lifecycle event in this list would have
+// deleted the cache entry pre-fix.
+const burst: {
+	type: string;
+	channel: "run:state" | "worker:lifecycle";
+	taskId?: string;
+}[] = [
+	{ type: "run.started", channel: "worker:lifecycle" },
+	{ type: "task.started", channel: "worker:lifecycle" },
+	{ type: "manifest.saved", channel: "run:state" },
+	{ type: "task.claimed", channel: "run:state" },
+	{ type: "manifest.saved", channel: "run:state" },
+	{ type: "task.unclaimed", channel: "run:state" },
+	{ type: "manifest.saved", channel: "run:state" },
+	{ type: "task.claimed", channel: "run:state" },
+	{ type: "worker.status", channel: "worker:lifecycle", taskId: "t1" },
+	{ type: "worker.status", channel: "worker:lifecycle", taskId: "t1" },
+	{ type: "task.completed", channel: "worker:lifecycle" },
+	{ type: "manifest.saved", channel: "run:state" },
+];
+let survivalCount = 0;
+for (const e of burst) {
+	runEventBus.emit({ ...e, runId });
+	const after = cache.get(runId);
+	if (after) survivalCount++;
+	else console.log(`FAILED at ${e.type} — cache entry deleted`);
+}
+console.log(`SURVIVED: ${survivalCount}/${burst.length} burst events`);
+
+await new Promise((r) => setTimeout(r, 200));
+const after = cache.get(runId);
+console.log(`AFTER COALESCE: ${after ? `present (signature=${after.signature})` : "MISSING"}`);
+
+fs.rmSync(cwd, { recursive: true, force: true });
+console.log("\n=== RESULT ===");
+if (survivalCount === burst.length && after) {
+	console.log("PASS — cache survives all burst events (no flicker window)");
+	process.exit(0);
+} else {
+	console.log("FAIL — cache was deleted by burst events");
+	process.exit(1);
+}