pi-crew 0.9.68 → 0.10.2

package/src/runtime/merge-loop.ts

@@ -0,0 +1,130 @@
+/**
+ * Merge of settled dispatch units into the run state for the team-run
+ * scheduler loop.
+ *
+ * Extracted from team-runner.ts (2026-08, Phase 2.6 maintainability split —
+ * CORE-4 extraction 5). Pure code motion: isRunTerminalPreserved +
+ * mergeUnitResult moved verbatim, including the RT-12 / NEW-D1 / R15-2 /
+ * CANCEL-1 comments.
+ *
+ * `isRunTerminalPreserved` lives here (not in finalize-run.ts) because it is
+ * shared by mergeUnitResult, finalizeRun (finalize-run.ts imports it from
+ * here) and the core loop in team-runner.ts (which imports it from here) —
+ * keeping it here avoids a merge-loop ↔ finalize-run import cycle.
+ */
+import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
+import { withRunLock } from "../state/coordination/locks.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { classifyFatalFsError } from "../utils/fs-errno.ts";
+import { cancelNonTerminalTasks } from "./dispatch-batch.ts";
+import { mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
+import type { SchedulerContext, SchedulerDecision } from "./scheduler-context.ts";
+import { mergeArtifacts } from "./team-runner-artifacts.ts";
+
+/**
+ * CORE-4 extraction 5: wait for one in-flight dispatch unit to settle and
+ * merge its result into the run state.
+ *
+ * Awaits Promise.race on ctx.pendingUnits; the first settled unit is merged
+ * into ctx.manifest/tasks under the run lock (flushPendingAtomicWrites +
+ * loadRunManifestById + mergeTaskUpdatesPreservingTerminal + save). The settled
+ * unit is then deleted from ctx.pendingUnits, and the merge outcome (taskIds
+ * + result object) is recorded on ctx.settledMerge for the post-merge inline
+ * logic (cancel-during-exec check + batch summary).
+ *
+ * Returns null to continue to the phase/budget check. A `{ kind: "return" }`
+ * decision is reserved for future run-complete/failure detection during merge.
+ *
+ * Reads ctx.pendingUnits/manifest/tasks. Mutates ctx.pendingUnits (delete),
+ * ctx.manifest/tasks, ctx.settledMerge.
+ *
+ * @param ctx  The scheduler context.
+ */
+/** R15-2/R15-1: run statuses that must never be overwritten by an in-memory
+ * derived status (mergeUnitResult force-"running", finalizeRun "completed").
+ * "blocked" is deliberately EXCLUDED — a blocked run can be unblocked and the
+ * finalize chain may legitimately derive blocked from in-memory state. */
+export function isRunTerminalPreserved(status: TeamRunManifest["status"]): boolean {
+	return status === "cancelled" || status === "failed" || status === "completed";
+}
+
+export async function mergeUnitResult(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
+	// RT-12: race on pre-created wrapper promises (created once at dispatch
+	// time) instead of rebuilding a wrapper-promise array with new async
+	// closures every iteration. This reduces allocation from O(C×T) wrapper
+	// promises to O(C) total (one per unit, created once at dispatch).
+	const settled = await Promise.race([...ctx.pendingUnits.values()].map((u) => u.wrapped));
+	const completedUnit = ctx.pendingUnits.get(settled.unitKey)!;
+	ctx.pendingUnits.delete(settled.unitKey);
+
+	// Build the single result to merge. On rejection, synthesize a failed
+	// result so the run continues (mirrors the old validResults guard).
+	// bug-026 sub-issue B: a rejected unit means runTeamTask itself threw —
+	// typically an atomicWriteFile/persistSingleTaskUpdate ENOSPC mid-run.
+	// Classify the errno and stamp failureCause on the synthesized failed
+	// tasks so the operator sees "failed (disk full)", not a generic write
+	// error string.
+	const thrownFailureCause = settled.result ? undefined : classifyFatalFsError(settled.error);
+	const resultToMerge: { manifest: TeamRunManifest; tasks: TeamTaskState[] } = settled.result ?? {
+		manifest: ctx.manifest,
+		tasks: cancelNonTerminalTasks(ctx.tasks, "failed", settled.error!.message, (t) => completedUnit.taskIds.includes(t.id)).map((t) =>
+			thrownFailureCause && t.status === "failed" ? { ...t, failureCause: thrownFailureCause } : t,
+		),
+	};
+	const validResults = [resultToMerge];
+	// Reconstruct manifest from the last worker's snapshot. The .artifacts field
+	// is re-merged from both the team-runner's in-memory state and all workers'
+	// snapshots, so artifact writes by task-runner (which individually save manifest
+	// after writing artifacts) are safely persisted. The in-memory manifest is only
+	// used for the next batch iteration's orchestration — actual persistence is safe.
+	// Use updateRunStatus to recompute manifest status from merged tasks rather than
+	// relying on the last result's manifest (which is arbitrary due to mapConcurrent
+	// returning results in arbitrary order).
+	// Use the in-memory manifest as base (not the last-completing worker's snapshot).
+	// Recompute status from merged tasks so the manifest reflects actual task state,
+	// not the arbitrary order in which mapConcurrent returned results.
+	// Read committed manifest from disk inside the lock so artifact merge is based
+	// on committed state, not in-memory state that may differ from disk.
+	const mergeResult = await withRunLock(ctx.manifest, async () => {
+		// NEW-D1: flush any pending coalesced atomic writes before reading from
+		// disk. Without this, a worker's async manifest save (coalesced by
+		// atomic-write) may not be committed yet, causing a lost-update on the
+		// merge read. flushPendingAtomicWrites forces all queued writes to disk.
+		flushPendingAtomicWrites();
+		const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+		const diskManifest = disk?.manifest ?? ctx.manifest;
+		const diskArtifacts = diskManifest.artifacts;
+		const reconciledArtifacts = mergeArtifacts([...diskArtifacts, ...validResults.map((item) => item.manifest.artifacts)].flat());
+		// R15-2: only force "running" when the disk manifest is NON-terminal
+		// (queued/planning/running/blocked). If the disk status is already terminal
+		// (cancelled/failed/completed — an external cancel or reconciler write
+		// landing during the batch), PRESERVE that terminal status: forcing
+		// "running" would legally erase it (contracts.ts allows cancelled/failed/
+		// completed → running) and the loop would never observe the disk-terminal
+		// (CANCEL-1/CANCEL-2 only catch worker-reported cancel or signal abort).
+		const mergedBase = { ...diskManifest, artifacts: reconciledArtifacts };
+		const resultManifest = isRunTerminalPreserved(diskManifest.status)
+			? mergedBase
+			: updateRunStatus(mergedBase, "running", "Merged task updates from parallel batch.");
+		// CANCEL-1: use the freshly-loaded disk tasks as the merge base instead
+		// of the in-memory `tasks` closure variable. The in-memory tasks reflect
+		// only team-runner's view; an external cancel (handleCancel, background
+		// race with SIGTERM arriving after cancel wrote but before merge ran)
+		// writes 'cancelled' to disk.tasks — using disk.tasks as base preserves
+		// that cancellation through the merge instead of overwriting it with the
+		// stale in-memory view. disk was loaded inside this lock, so it reflects
+		// the freshest committed state.
+		const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+		await saveRunManifestAsync(resultManifest);
+		await saveRunTasksAsync(resultManifest, resultTasks);
+		return { resultManifest, resultTasks };
+	});
+	ctx.manifest = mergeResult.resultManifest;
+	ctx.tasks = mergeResult.resultTasks;
+	ctx.settledMerge = { taskIds: completedUnit.taskIds, result: resultToMerge };
+	return null;
+}
+
+/** @internal 1.9(b) test export — exercise mergeUnitResult directly. */
+export const __test__mergeUnitResult = mergeUnitResult;

package/src/runtime/model/model-budget-summary.ts

@@ -0,0 +1,53 @@
+/**
+ * model-budget-summary.ts — R8 model-routing transparency (WP-8, T5).
+ *
+ * One pre-run summary line: the resolved fallback chain + the WORST-CASE
+ * spawn budget per task (`attemptModels × (maxAttempts + 1)` — the RT-6
+ * formula; always ≥ 1 full attempt above the theoretical max). Cost
+ * surprises in multi-model fallback runs were invisible until workers
+ * started burning through attempts; this makes the ceiling loud UP FRONT.
+ */
+
+import { loadConfig } from "../../config/config.ts";
+import { DEFAULT_RETRY_POLICY } from "../recovery/retry-executor.ts";
+import { computeSpawnBudgetMax } from "../task-runner/child-executor.ts";
+import { buildConfiguredModelRouting } from "./model-fallback.ts";
+
+export interface ModelBudgetSummary {
+	/** Deduped resolved chain (requested first, then fallbacks). */
+	chain: string[];
+	/** Worst-case child spawns per task: chain.length × (maxAttempts + 1). */
+	worstCaseSpawnsPerTask: number;
+	/** Configured maxAttempts (or the default when unset/unreadable). */
+	maxAttempts: number;
+	/** Rendered single-line summary for console output. */
+	line: string;
+}
+
+/** Compute the pre-run model budget summary. Never throws — degrades to an
+ *  empty chain + default attempts on any config/catalog read failure. */
+export function summarizeModelBudget(cwd: string): ModelBudgetSummary {
+	let maxAttempts = DEFAULT_RETRY_POLICY.maxAttempts;
+	let chain: string[] = [];
+	try {
+		const { config } = loadConfig(cwd);
+		// The same routing pipeline tasks use (config catalog + auto tail policy):
+		// the summary must describe what would ACTUALLY spawn, not a parallel
+		// reconstruction of it.
+		const routing = buildConfiguredModelRouting({ cwd, policy: config.runtime?.modelFallback });
+		chain = routing.candidates;
+		if (config.reliability?.retryPolicy?.maxAttempts !== undefined) {
+			maxAttempts = config.reliability.retryPolicy.maxAttempts;
+		}
+	} catch {
+		/* degrade: defaults below */
+	}
+	const worst = computeSpawnBudgetMax(Math.max(1, chain.length), maxAttempts);
+	const chainText = chain.length ? chain.join(" → ") : "(default pi model)";
+	return {
+		chain,
+		worstCaseSpawnsPerTask: worst,
+		maxAttempts,
+		line: `[team-tool.run] model routing: ${chainText} · worst-case ${worst} spawns/task (chain=${Math.max(1, chain.length)} × maxAttempts+1=${maxAttempts + 1})`,
+	};
+}

package/src/runtime/model/model-fallback.ts

@@ -273,14 +273,47 @@ export function splitThinkingSuffix(model: string): {
 	};
 }
 
+// WP-8 (R8): loud passthrough warnings — deduped per model so a chain of
+// tasks resolving the same unvalidated model warns once per process. The
+// delegate surface (spawn-policy admission) validates models against the
+// catalog itself (WP-5) and never routes through resolveModelCandidate.
+const passthroughWarned = new Set<string>();
+function warnUnvalidatedPassthrough(model: string, reason: string): void {
+	const key = `${model}|${reason}`;
+	if (passthroughWarned.has(key)) return;
+	passthroughWarned.add(key);
+	// Muted: per-model passthrough noise became too loud when many pi-crew
+	// child workers resolve their parent model + fallback chain against the
+	// full catalog (each worker printed one line). Dedup Set is preserved
+	// so re-enabling is a one-line revert.
+	// console.warn(
+	// 	`[model-routing] unvalidated passthrough: '${model}' (${reason}) — not confirmed against the configured model catalog; spawn may fail at the provider.`,
+	// );
+}
+
+/** Test seam: the dedup set is module-global (one warn per model+reason per
+ *  process); tests reset it for deterministic counting. */
+export function resetPassthroughWarnings(): void {
+	passthroughWarned.clear();
+}
+
 export function resolveModelCandidate(
 	model: string | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
 ): string | undefined {
 	if (!model) return undefined;
-	if (model.includes("/")) return model;
-	if (!availableModels || availableModels.length === 0) return model;
+	// Provider-qualified refs ("provider/model") pass through UNVALIDATED —
+	// the caller asserted a full id; there is nothing to resolve. Loud (R8):
+	// this is the documented trust path, not a silent one.
+	if (model.includes("/")) {
+		warnUnvalidatedPassthrough(model, "provider-qualified ref, no catalog check");
+		return model;
+	}
+	if (!availableModels || availableModels.length === 0) {
+		warnUnvalidatedPassthrough(model, "no model catalog available");
+		return model;
+	}
 
 	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
 	const matches = availableModels.filter((entry) => entry.id === baseModel);
@@ -294,6 +327,7 @@ export function resolveModelCandidate(
 		// Fuzzy fallback: try to resolve via partial name matching
 		const fuzzy = fuzzyResolveModelId(baseModel, availableModels);
 		if (fuzzy) return `${fuzzy}${thinkingSuffix}`;
+		warnUnvalidatedPassthrough(model, "no exact or fuzzy catalog match");
 		return model;
 	}
 	return `${matches[0]!.fullId}${thinkingSuffix}`;

package/src/runtime/model/pi-args.ts

@@ -328,6 +328,16 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		) {
 			allowed = allowed.filter((ext) => path.resolve(ext) === path.resolve(PROMPT_RUNTIME_EXTENSION_PATH));
 		}
+		// ADR-5 §8 (governed nesting, T3/WP-5 step 8): every spawn this builder
+		// produces runs at depth > 0 (workers are depth 1, delegate grandchildren
+		// are 2+; currentCrewDepth(base)+1 is ALWAYS >= 1) — the extension list
+		// is an unconditional ALLOWLIST: only the trusted
+		// PROMPT_RUNTIME_EXTENSION_PATH passes, REGARDLESS OF SOURCE. User-sourced
+		// agent declarations can no longer inject extensions into sub-agents
+		// (SEC-1's project-only strip left user/builtin declarations unfiltered —
+		// the audit's untested hole). The denylist + SEC-1 strip above remain as
+		// defense-in-depth; the allowlist is authoritative.
+		allowed = [];
 		for (const extension of [PROMPT_RUNTIME_EXTENSION_PATH, ...allowed]) args.push("--extension", extension);
 	} else {
 		args.push("--extension", PROMPT_RUNTIME_EXTENSION_PATH);

package/src/runtime/model/provider-extensions.ts

@@ -44,6 +44,12 @@ export interface DiscoveredProviderExtension {
  */
 const cache = new Map<string, { mtimeMs: number; result: DiscoveredProviderExtension[] }>();
 
+// R5-L3 (Round 5 LOW-3): FIFO cap at insertion (mirrors knowledgeCache in
+// knowledge-injection.ts). Entries are only removed when a re-access sees a
+// changed mtime, so distinct settings paths (e.g. per-test temp roots) would
+// otherwise accumulate for the process lifetime.
+const MAX_PROVIDER_EXTENSION_CACHE = 64;
+
 function cachedResult(settingsPath: string): { mtimeMs: number; result: DiscoveredProviderExtension[] } | undefined {
 	const entry = cache.get(settingsPath);
 	if (!entry) return undefined;
@@ -157,6 +163,10 @@ export function discoverProviderExtensions(settingsPath?: string): DiscoveredPro
 	// Cache the resolved result keyed on the settings.json path + mtime.
 	try {
 		cache.set(settingsFile, { mtimeMs: fs.statSync(settingsFile).mtimeMs, result: out });
+		if (cache.size > MAX_PROVIDER_EXTENSION_CACHE) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== undefined) cache.delete(oldest);
+		}
 	} catch {
 		cache.delete(settingsFile);
 	}

package/src/runtime/orphan-worker-registry.ts

@@ -201,7 +201,7 @@ function readRegistry(): OrphanWorkerEntry[] {
 		}
 		// Silent failure is deliberate for robustness (registry read failures
 		// shouldn't crash the process), but log at warning level to aid troubleshooting.
-		console.warn(`[orphan-worker-registry] readRegistry failed: ${error}`);
+		logInternalError("orphan-worker-registry", new Error(`readRegistry failed: ${error}`), undefined, "warn");
 		return [];
 	}
 }

package/src/runtime/output/output-validator.ts

@@ -115,6 +115,51 @@ export function validateWorkerOutput(role: string, output: string): OutputValida
 	};
 }
 
+/**
+ * bug-026 sub-issue A: strict log-noise line shapes observed in the corrupted
+ * `02_explore-core.txt` result artifact (run team_20260815144514) — extension/
+ * MCP session-log stderr that the child-executor result fallback chain leaked
+ * into the result artifact when the worker payload was corrupted/empty.
+ *
+ * A trimmed non-empty line counts as log noise ONLY if it matches one of:
+ *  1. a bracket-tag extension log line: `[oc-go] ...`, `[pi-qwen-mm] ...`,
+ *     `[pi-qwen-mm] [core] [stderr] ...` — the leading tag is a lowercase
+ *     identifier (deliberately excludes capitalized bracketed prose like
+ *     `[Note] ...`), optionally followed by known sub-tags
+ *     (core/mcp/stderr/stdout/warn/info/error/debug);
+ *  2. a Python `warnings.warn(` line (deprecation-warning continuation);
+ *  3. a timestamped logging line: `2026-08-15 21:49:02,986 WARNING ...`.
+ *
+ * Anything else — prose, markdown, file:line results, `OK done.` — is NOT
+ * noise, so a single such line marks the artifact as usable content.
+ *
+ * NOTE: a `true` return is NOT by itself failure evidence; the caller
+ * (post-execution.ts) applies the two-gate rule (authoritative output
+ * sources empty AND artifact log-noise-only) before failing a task.
+ */
+const BRACKET_TAG_LOG_LINE = /^\[[a-z0-9][a-z0-9_.-]*\](?:\s*\[(?:core|mcp|stderr|stdout|warn|info|error|debug)\])*(?:\s.*)?$/;
+const PYTHON_WARNING_LINE = /(?:^|\s)warnings\.warn\(/;
+const TIMESTAMPED_LOG_LINE = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:[.,]\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})?\s+[A-Za-z]+\b/;
+
+/**
+ * Detect a "stderr-only" result artifact: every non-empty trimmed line is
+ * strict log noise (see the pattern docs above). Empty/whitespace-only input
+ * returns false — emptiness is the caller's separate, explicit check.
+ * Conservative by design: any prose/markdown line makes it return false.
+ */
+export function isStderrOnlyResult(text: string): boolean {
+	if (!text?.trim()) return false;
+	let noiseLines = 0;
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const isNoise = BRACKET_TAG_LOG_LINE.test(trimmed) || PYTHON_WARNING_LINE.test(trimmed) || TIMESTAMPED_LOG_LINE.test(trimmed);
+		if (!isNoise) return false;
+		noiseLines++;
+	}
+	return noiseLines > 0;
+}
+
 /**
  * Extract structured findings from reviewer output.
  * Returns array of { file, line, severity, message } objects.

package/src/runtime/parent-guard.ts

@@ -1,3 +1,5 @@
+import { getCrewEnv } from "../config/env-vars.ts";
+
 /**
  * Parent liveness guard for pi-crew background-runner process.
  *
@@ -70,7 +72,7 @@
  * polling approach for near-instantaneous parent-death detection on Unix
  * systems, avoiding the polling overhead entirely.
  */
-const POLL_INTERVAL_MS = Number(process.env.PI_CREW_PARENT_GUARD_INTERVAL_MS) || 500;
+const POLL_INTERVAL_MS = Number(getCrewEnv("PI_CREW_PARENT_GUARD_INTERVAL_MS")) || 500;
 
 const guardIntervals = new Map<number, ReturnType<typeof setInterval>>();
 

package/src/runtime/peer-dep.ts

@@ -38,6 +38,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { resolveNpmGlobalRoot } from "./pi-spawn.ts";
 
 /**
@@ -78,7 +79,7 @@ export function peerDepResolutionBases(): string[] {
 	const bases: string[] = [];
 
 	// 0. Parent-provided hint (fastest — no probe). Set by async-runner.
-	const envHint = process.env[PEER_DEP_DIR_ENV]?.trim();
+	const envHint = getCrewEnv(PEER_DEP_DIR_ENV)?.trim();
 	if (envHint) bases.push(path.resolve(envHint));
 
 	// 1. This file's location — works when pi-crew and pi-coding-agent share a

package/src/runtime/per-write-validator.ts

@@ -87,11 +87,6 @@ function rememberSeen(path: string, content: string): void {
 	}
 }
 
-/** Test seam: reset the dedup cache between tests. */
-export function resetPerWriteValidatorCache(): void {
-	seenContent.clear();
-}
-
 /**
  * Replace the validator registry (test seam). Production uses
  * DEFAULT_VALIDATORS; tests inject a custom map to exercise specific extensions.

package/src/runtime/pi-spawn.ts

@@ -3,6 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getCrewEnv } from "../config/env-vars.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 
 export interface PiSpawnCommand {
 	command: string;
@@ -30,8 +32,11 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
 		allowedPrefixes.push(execDir.toLowerCase());
 		allowedPrefixes.push(path.join(path.dirname(execDir), "lib", "node_modules").toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3 (LOW): execPath realpath failure is genuinely unexpected (the
+		// running binary vanished / permission issue) — surface it so the
+		// "cannot find pi" fallback is diagnosable.
+		logInternalError("pi-spawn.allowlist-prefixes", error, "execPath realpath failed", "warn");
 	}
 
 	// npm global bin via APPDATA
@@ -49,24 +54,46 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 	try {
 		const projectBin = path.resolve("node_modules", ".bin");
 		allowedPrefixes.push(projectBin.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.project-bin", error, undefined, "debug");
 	}
 
 	// User home npm-global
 	try {
 		const homeNpm = path.join(os.homedir(), ".npm-global", "bin");
 		allowedPrefixes.push(homeNpm.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.npm-global", error, undefined, "debug");
 	}
 
 	// User home .local/bin
 	try {
 		const homeLocal = path.join(os.homedir(), ".local", "bin");
 		allowedPrefixes.push(homeLocal.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.local-bin", error, undefined, "debug");
+	}
+
+	// Canonicalize prefixes (macOS: /var/folders/... realpath → /private/var/folders/...).
+	// validateExplicitBin() compares fs.realpathSync(resolved) against this list —
+	// without the canonical forms, any prefix reached through a symlink (macOS
+	// tmpdir, ~/.npm-global as symlink) rejects its own realpath'd target
+	// (CI incident: run-worker-cap.test.ts on macos-latest). Additive: original
+	// forms stay, so Windows \\?\-prefixed realpaths simply never match.
+	for (let i = 0; i < allowedPrefixes.length; i++) {
+		try {
+			const real = fs.realpathSync.native(allowedPrefixes[i]!).toLowerCase();
+			if (real !== allowedPrefixes[i] && !allowedPrefixes.includes(real)) allowedPrefixes.push(real);
+		} catch {
+			// Prefix path doesn't exist (env var points nowhere) — the original form
+			// stays; nothing to canonicalize.
+		}
 	}
 
 	return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
@@ -81,12 +108,20 @@ function resolvePiPackageRoot(): string | undefined {
 			try {
 				const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8")) as { name?: string };
 				if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return dir;
-			} catch {
+			} catch (error) {
+				// R17-B3: the upward walk EXPECTS ENOENT probes (most dirs have no
+				// readable package.json) — debug-gated so the walk stays silent
+				// unless PI_TEAMS_DEBUG is set, but EACCES-style causes are visible.
+				logInternalError("pi-spawn.resolve-pi-package-root.probe", error, `dir=${dir}`, "debug");
 				// Continue walking upward.
 			}
 			dir = path.dirname(dir);
 		}
-	} catch {
+	} catch (error) {
+		// R17-B3: realpath failure on argv[1] is unexpected (not the normal
+		// missing-entry case, which is handled by the !entry guard above) —
+		// debug-gated visibility for the "cannot find pi" diagnosis.
+		logInternalError("pi-spawn.resolve-pi-package-root", error, `argv1=${process.argv[1] ?? ""}`, "debug");
 		return undefined;
 	}
 	return undefined;
@@ -101,7 +136,10 @@ function packageBinScript(packageJsonPath: string): string | undefined {
 		if (!binPath) return undefined;
 		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
 		return isRunnableNodeScript(candidate) ? candidate : undefined;
-	} catch {
+	} catch (error) {
+		// R17-B3 (LOW): a package.json that EXISTS but fails to parse is corrupt —
+		// not the expected ENOENT of the upward-walk probes.
+		logInternalError("pi-spawn.package-bin-script", error, `packageJsonPath=${packageJsonPath}`, "warn");
 		return undefined;
 	}
 }
@@ -115,7 +153,10 @@ function findPiPackageJsonFrom(startDir: string): string | undefined {
 				name?: string;
 			};
 			if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return direct;
-		} catch {
+		} catch (error) {
+			// R17-B3: same EXPECTED-ENOENT upward-walk probe as
+			// resolvePiPackageRoot — debug-gated, keeps walking either way.
+			logInternalError("pi-spawn.find-pi-package-json.probe", error, `dir=${dir}`, "debug");
 			// Continue searching upward and in node_modules.
 		}
 		for (const pkgName of PI_PACKAGE_NAMES) {
@@ -163,7 +204,12 @@ export function resolveNpmGlobalRoot(): string | undefined {
 			windowsHide: true,
 		}).trim();
 		resolved = out.length > 0 ? out : undefined;
-	} catch {
+	} catch (error) {
+		// R17-B3 (LOW): `npm root -g` failing (npm not on PATH / timeout) means
+		// Windows non-APPDATA installs fall back to the static roots and often
+		// fail with ENOENT downstream — surface the root cause here. Memoized,
+		// so at most one warn per process.
+		logInternalError("pi-spawn.npm-root-g", error, "npm root -g probe failed", "warn");
 		resolved = undefined;
 	}
 	cachedNpmGlobalRoot = resolved ?? null;
@@ -240,14 +286,14 @@ function validateExplicitBin(explicit: string): string | undefined {
 		}
 	} catch (e) {
 		if (e instanceof Error && e.message.includes("allowed prefixes")) throw e;
-		console.error("[pi-spawn] validateExplicitBin: unexpected realpathSync error:", e);
+		logInternalError("pi-spawn", e, "validateExplicitBin: unexpected realpathSync error", "error");
 		return undefined;
 	}
 	return resolved;
 }
 
 export function getPiSpawnCommand(args: string[]): PiSpawnCommand {
-	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
+	const explicit = getCrewEnv("PI_TEAMS_PI_BIN")?.trim();
 	if (explicit) {
 		const validated = validateExplicitBin(explicit);
 		if (validated) {