pi-crew 0.7.6 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.7.7] — Windows spawn fix + plan-approval crash-recovery fix + CI flake fixes (2026-06-16)
+
+A focused patch release driven by two community reports (Issue #33 and PR #32) plus the CI flake surfaced while validating them. CI green on Windows / Ubuntu / macOS (run 27599121797). 4965 tests pass / 0 fail.
+
+### Bug Fixes
+
+- **`#33` — Windows `spawn pi ENOENT`** (commit `afc23b4`): when pi is installed outside `%APPDATA%\npm` (nvm-windows / Volta / fnm put the global `node_modules` elsewhere), the static `%APPDATA%\npm` paths in `resolvePiCliScript()` all miss, and the fallback `spawn("pi")` fails with `ENOENT` because `child_process.spawn` does NOT do PATHEXT resolution on Windows (only `exec`/`execSync` via `cmd.exe` do). **Fix**: pi-crew now discovers the real npm global `node_modules` dir at runtime via `npm root -g` (run through `execSync`, which DOES resolve `npm.cmd` via PATHEXT), then derives the `@earendil-works` / `@mariozechner` package dirs from it and checks them BEFORE the static `%APPDATA%\npm` paths and the cwd fallback. Covers standard installs **and** nvm-windows / Volta / fnm uniformly. Memoized once per process (one-time ~200ms cost). Injection-safe — no `shell: true` on the real worker spawn. +6 tests.
+- **Plan-approval-blocked runs crash-recovery fix** (commit `421b76d`, adapts PR #32 change #1 by @gustavo-pelissaro): crash recovery and stale reconciliation both treated `status === "blocked"` runs as repair candidates, so a run legitimately blocked on **human** plan approval (`requirePlanApproval`, `status="pending"`) was marked failed and/or orphan-cancelled when its owning session died or its async PID was no longer live — destroying an in-flight HITL checkpoint. **Fix**: new `isPlanApprovalPending(manifest)` guard (status=blocked AND `planApproval.required=true` AND `planApproval.status=pending`). Guarded in `reconcileStaleRun` (new `blocked_awaiting_approval` verdict, `repaired=false` — which automatically covers `reconcileAllStaleRuns`), `detectInterruptedRuns` (skip), `cancelOrphanedRuns` (push to `skipped`), and a belt-and-suspenders re-check under the lock in `reconcileAllStaleRuns`. The guard is intentionally narrow: a plain `blocked` run (no planApproval, or already approved/cancelled) is still a recovery candidate, so existing orphaned-blocked-run handling is unchanged. +6 tests.
+
+### Tests (CI reliability)
+
+- **`run-watcher-registry` macOS cancellation** (commit `dccb5e7`): the two fs.watch-dependent tests used unbounded `done()` callbacks that hung the whole test file on macOS CI runners (fs.watch events are slow/dropped under `/var/folders` + VM-runner FS load). Fixed with bounded async waits (1.5s deadline) consistent with production semantics, where fs.watch is best-effort and the preload poll loop is the source of truth.
+- **`operator-experience` ubuntu redaction flake** (commit `2da1a1b`): the redaction test seeded a secret literally named `abc` and asserted `/abc/` does not leak, but the runId hash (`randomBytes(8).toString("hex")`) occasionally spells `...abc...` (e.g. `team_..._9791deabc2f52485`) → false failure, even though redaction worked perfectly. Fixed by switching to a `ZZ_LEAK_CANARY` marker — uppercase letters never appear in a lowercase-hex hash, so the marker is collision-proof.
+
+### Community
+
+- Thanks to **@YrFnS** for the textbook-quality Issue #33 report and diagnosis (PATHEXT, spawn vs execSync matrix) that pinpointed the fix.
+- Thanks to **@gustavo-pelissaro** for PR #32 — change #1 (plan-approval preservation) landed here; changes #2/#3 (child exit-143 normalization, symlinked temp base) were closed for heavy conflicts but will be revisited.
+- PR #34 (closed) overlapped the existing `%APPDATA%\npm` resolution; superseded by the runtime `npm root -g` probe.
+
 ## [0.7.6] — DX, observability, and a critical interactive-session hang fix (2026-06-16)
 
 This release bundles Rounds 16–28: a developer-experience pass, an observability pass, and eight correctness/security audits — culminating in the **fix for the pts/2 interactive-session busy-loop hang** (two separate Pi sessions had hung at 71.5% CPU with 339 inotify watches). All 24 commits passed CI on Windows, Ubuntu, and macOS.

package/package.json

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

package/src/runtime/crash-recovery.ts

@@ -9,7 +9,7 @@ import type { TeamTaskState } from "../state/types.ts";
 import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
 import type { ManifestCache } from "./manifest-cache.ts";
 import { checkProcessLiveness } from "./process-status.ts";
-import { reconcileStaleRun, type ReconcileResult } from "./stale-reconciler.ts";
+import { isPlanApprovalPending, reconcileStaleRun, type ReconcileResult } from "./stale-reconciler.ts";
 import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { unregisterActiveRun, readActiveRunRegistry } from "../state/active-run-registry.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
@@ -38,6 +38,8 @@ export function detectInterruptedRuns(cwd: string, manifestCache: ManifestCache,
 	const plans: RecoveryPlan[] = [];
 	for (const manifest of manifestCache.list(50)) {
 		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
+		// Preserve runs intentionally blocked on plan approval — not crashes.
+		if (isPlanApprovalPending(manifest)) continue;
 		if (manifest.async?.pid !== undefined && checkProcessLiveness(manifest.async.pid).alive) continue;
 		// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
 		const loaded = loadRunManifestById(cwd, manifest.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
@@ -107,6 +109,12 @@ export function cancelOrphanedRuns(
 	// Phase 1: Scan project-level manifests via manifestCache
 	for (const manifest of manifestCache.list(50)) {
 		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
+		// Preserve plan-approval-blocked runs — they belong to their owner and are
+		// waiting on a human decision, not orphaned by a dead owner process.
+		if (isPlanApprovalPending(manifest)) {
+			skipped.push(manifest.runId);
+			continue;
+		}
 
 		// Only consider runs owned by a different session
 		const ownerId = manifest.ownerSessionId;
@@ -340,6 +348,18 @@ export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache,
 			// Re-read inside lock to get freshest data
 			const fresh = loadRunManifestById(cwd, runId); // NOTE: inside withRunLockSync - consistent read
 			if (!fresh || (fresh.manifest.status !== "running" && fresh.manifest.status !== "blocked")) return;
+			// Belt-and-suspenders: reconcileStaleRun itself guards this, but the run
+			// may have flipped to blocked+plan-approval between cache-list and lock
+			// acquisition — re-check the freshest manifest under the lock.
+			if (isPlanApprovalPending(fresh.manifest)) {
+				results.push({
+					runId,
+					verdict: "blocked_awaiting_approval",
+					repaired: false,
+					detail: "Plan approval is pending; stale reconciliation skipped",
+				});
+				return;
+			}
 			const result = reconcileStaleRun(fresh.manifest, fresh.tasks, now);
 			if (result.repaired || result.verdict === "result_exists") {
 				if (result.repairedTasks) {

package/src/runtime/pi-spawn.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
+import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 
@@ -118,6 +119,63 @@ function findPiPackageJsonFrom(startDir: string): string | undefined {
 	return undefined;
 }
 
+/**
+ * Discover the real npm global node_modules directory at runtime.
+ *
+ * Why this exists (Issue #33): on Windows, pi may be installed somewhere
+ * other than %APPDATA%\npm — e.g. nvm-windows puts the global node_modules
+ * under %NVM_HOME%/<version>/node_modules, Volta under
+ * %LOCALAPPDATA%\Volta, fnm under %LOCALAPPDATA%\fnm_multishells. The static
+ * %APPDATA%\npm paths in resolvePiCliScript() miss all of those, and the
+ * fallback spawn("pi") then fails with ENOENT because child_process.spawn does
+ * NOT do PATHEXT resolution on Windows (only exec/execSync via cmd.exe do).
+ *
+ * `npm root -g` is the canonical way to find the global node_modules dir and
+ * works across every npm-based install layout. We run it via execSync, which
+ * DOES resolve `npm.cmd` through PATHEXT. Capped at 5s; any failure (npm not
+ * on PATH, slow start, etc.) just falls through to the other resolution roots.
+ *
+ * Memoized: the npm global root does not change during a process lifetime, so
+ * this is a one-time ~200ms cost rather than per-worker.
+ *
+ * @internal — exported for unit-test injection via __setNpmGlobalRootForTest.
+ */
+let cachedNpmGlobalRoot: string | undefined | null = null;
+export function resolveNpmGlobalRoot(): string | undefined {
+	if (cachedNpmGlobalRoot !== null) {
+		return cachedNpmGlobalRoot ?? undefined;
+	}
+	let resolved: string | undefined;
+	try {
+		const out = execSync("npm root -g", {
+			encoding: "utf-8",
+			timeout: 5000,
+			stdio: ["pipe", "pipe", "pipe"], // suppress npm's stderr chatter
+			windowsHide: true,
+		}).trim();
+		resolved = out.length > 0 ? out : undefined;
+	} catch {
+		resolved = undefined;
+	}
+	cachedNpmGlobalRoot = resolved ?? null;
+	return resolved;
+}
+
+/**
+ * Given an npm global node_modules root, derive the candidate package dirs for
+ * each supported pi scope. Pure + exported so the mapping is unit-testable
+ * without spawning npm.
+ * @internal
+ */
+export function buildNpmGlobalPackageDirs(npmGlobalRoot: string): string[] {
+	return PI_PACKAGE_NAMES.map((pkgName) => path.join(npmGlobalRoot, ...pkgName.split("/")));
+}
+
+/** @internal — test hook: inject a fake global root (or undefined) and reset the memo. */
+export function __setNpmGlobalRootForTest(root: string | undefined): void {
+	cachedNpmGlobalRoot = root ?? null;
+}
+
 function resolvePiCliScript(): string | undefined {
 	const argv1 = process.argv[1];
 	if (argv1) {
@@ -125,8 +183,16 @@ function resolvePiCliScript(): string | undefined {
 		if (isRunnableNodeScript(argvPath)) return argvPath;
 	}
 
+	// npm-global package dirs derived from `npm root -g` — placed BEFORE the
+	// %APPDATA%\npm static paths and the cwd/import.meta fallbacks so that a pi
+	// install under nvm-windows / Volta / fnm is found even when %APPDATA%\npm
+	// doesn't contain it. Covers Issue #33.
+	const npmGlobalRoot = resolveNpmGlobalRoot();
+	const npmGlobalDirs = npmGlobalRoot ? buildNpmGlobalPackageDirs(npmGlobalRoot) : [];
+
 	const roots = [
 		resolvePiPackageRoot(),
+		...npmGlobalDirs,
 		process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules", "@earendil-works", "pi-coding-agent") : undefined,
 		process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules", "@mariozechner", "pi-coding-agent") : undefined,
 		path.dirname(fileURLToPath(import.meta.url)),

package/src/runtime/stale-reconciler.ts

@@ -24,6 +24,7 @@ export interface ReconcileResult {
 	/** What was found and what action was taken */
 	verdict:
 		| "healthy"
+		| "blocked_awaiting_approval"
 		| "result_exists"
 		| "pid_dead"
 		| "pid_alive_stale"
@@ -36,6 +37,23 @@ export interface ReconcileResult {
 	repairedTasks?: TeamTaskState[];
 }
 
+/**
+ * Is this run intentionally waiting for human plan approval?
+ *
+ * Such runs are NOT stale even if their owning session died or their async PID
+ * is no longer live — they are blocked on a human decision, not a crash. Crash
+ * recovery and stale reconciliation must preserve them rather than mark them
+ * failed or orphan-cancel them. See PR #32 (gustavo-pelissaro) for the
+ * original analysis of this failure mode.
+ */
+export function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
+	return (
+		manifest.status === "blocked" &&
+		manifest.planApproval?.required === true &&
+		manifest.planApproval.status === "pending"
+	);
+}
+
 const STALE_ALIVE_PID_MS = 24 * 60 * 60 * 1000; // 24 hours
 const ACTIVE_EVIDENCE_TTL_MS = 5 * 60 * 1000;
 /** For no-PID runs, repair when ALL running tasks have heartbeat stale beyond this threshold. */
@@ -347,6 +365,18 @@ export function reconcileStaleRun(
 ): ReconcileResult {
 	const runId = manifest.runId;
 
+	// Preserve runs intentionally blocked on human plan approval. These are not
+	// crashes even if the owning PID is gone — they are waiting for a decision.
+	// Must short-circuit before Phase 1 (result check) and Phase 2 (PID liveness).
+	if (isPlanApprovalPending(manifest)) {
+		return {
+			runId,
+			verdict: "blocked_awaiting_approval",
+			repaired: false,
+			detail: "Plan approval is pending; blocked run is intentionally waiting and must not be stale-repaired",
+		};
+	}
+
 	// Phase 1: Check if results already exist
 	const phase1 = checkResultFile(manifest, tasks);
 	if (phase1.found) {