pi-crew 0.10.3 → 0.10.5

package/src/extension/team-tool.ts

@@ -23,14 +23,10 @@ import { listRecentRuns } from "./run-index.ts";
 import type { PiTeamsToolResult } from "./tool-result.ts";
 
 type ExecuteTeamRunFn = typeof _executeTeamRunFn;
-let _cachedExecuteTeamRun: ExecuteTeamRunFn | undefined;
 async function executeTeamRun(...args: Parameters<ExecuteTeamRunFn>): Promise<Awaited<ReturnType<ExecuteTeamRunFn>>> {
-	if (_cachedExecuteTeamRun === undefined) {
-		// LAZY: heavy runtime — defer 1.4s import cost until team run actually executes.
-		const mod = await import("../runtime/team-runner.ts");
-		_cachedExecuteTeamRun = mod.executeTeamRun;
-	}
-	return _cachedExecuteTeamRun(...args);
+	// LAZY: heavy runtime — defer 1.4s import cost until team run actually executes.
+	const mod = await import("../runtime/team-runner.ts");
+	return mod.executeTeamRun(...args);
 }
 
 import { directTeamAndWorkflowFromRun } from "../runtime/direct-run.ts";
@@ -44,14 +40,10 @@ import { buildParentContext, formatScoped, result, type TeamContext } from "./te
 import type { handleRun as _handleRunFn } from "./team-tool/run.ts";
 
 type HandleRunFn = typeof _handleRunFn;
-let _cachedHandleRun: HandleRunFn | undefined;
 async function handleRun(...args: Parameters<HandleRunFn>): Promise<Awaited<ReturnType<HandleRunFn>>> {
-	if (_cachedHandleRun === undefined) {
-		// LAZY: run.ts pulls in spawnBackgroundTeamRun + resolveCrewRuntime; also avoids jiti import race in child-process contexts.
-		const mod = await import("./team-tool/run.ts");
-		_cachedHandleRun = mod.handleRun;
-	}
-	return _cachedHandleRun(...args);
+	// LAZY: run.ts pulls in spawnBackgroundTeamRun + resolveCrewRuntime; also avoids jiti import race in child-process contexts.
+	const mod = await import("./team-tool/run.ts");
+	return mod.handleRun(...args);
 }
 
 import { t } from "../i18n.ts";

package/src/hooks/registry.ts

@@ -179,6 +179,9 @@ export async function executeHook(name: HookName, ctx: HookContext): Promise<Hoo
 }
 
 export function appendHookEvent(manifest: TeamRunManifest, report: HookExecutionReport): void {
+	// REVIEW FIX (2026-09-10): reverted M2b buffered conversion — hook.executed
+	// events are read back synchronously (recovery-hooks tests, hooks audit
+	// display) and are low-frequency (per hook execution).
 	appendEvent(manifest.eventsPath, {
 		type: "hook.executed",
 		runId: manifest.runId,

package/src/prompt/scratchpad-lifecycle.ts

@@ -32,7 +32,7 @@ import * as path from "node:path";
 import { type Static, Type } from "@sinclair/typebox";
 import { defineTool, type ExtensionAPI, type ToolDefinition } from "../extension/pi-api.ts";
 import { EngineManager, type ExecuteResult } from "../runtime/scratchpad/engine.ts";
-import { appendEventFireAndForget } from "../state/event-log/event-log.ts";
+import { appendEventBuffered, appendEventFireAndForget } from "../state/event-log/event-log.ts";
 // D5/MAJOR-S1: PI_CREW_PARENT_PID + PI_CREW_GUEST build the guest's zombie-
 // backstop env (PI_CREW_KIND_ENV is already exported above).
 import { type ArtifactWriteOptions, writeArtifact } from "../state/stores/artifact-store.ts";
@@ -84,12 +84,12 @@ function emitScratchpadMetric(
 	// never break the cell. The real appendEventFireAndForget already catches
 	// async; this guard also absorbs a sync throw from a bad writer.
 	try {
-		appendEvent(eventsPath, {
+		appendEventBuffered(eventsPath, {
 			type,
 			runId,
 			taskId: env[PI_CREW_TASK_ID_ENV],
 			data,
-		});
+		}).catch((e) => logInternalError("scratchpad_lifecycle.buffered", e, `type=${type}`));
 	} catch {
 		// Metric is best-effort — drop the event, never the cell.
 	}

package/src/runtime/background-runner.ts

@@ -5,12 +5,11 @@ import { loadConfig } from "../config/config.ts";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
 import { withRunLockSync } from "../state/coordination/locks.ts";
-import { appendEvent, appendEventFireAndForget } from "../state/event-log/event-log.ts";
+import { appendEvent, appendEventBuffered, appendEventFireAndForget } from "../state/event-log/event-log.ts";
 import { createRunPaths, loadRunManifestById, saveRunManifestAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { errorMessage } from "../utils/guards.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
 import { assertSafePathId } from "../utils/safe-paths.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 // Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
@@ -18,8 +17,6 @@ import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows
 import { primePeerDep } from "./peer-dep.ts";
 import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
 
-let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
-
 /** Maximum runtime for a single background run before the watchdog force-aborts
  *  it. Prevents zombie background-runner processes when a team run hangs forever
  *  (e.g. a hung child Pi process, a stuck lock, or a test that spawns a run
@@ -33,16 +30,13 @@ const MAX_BACKGROUND_RUN_MS = (() => {
 	return Number.isFinite(env) && env > 0 ? env : 2 * 60 * 60 * 1000;
 })();
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
-	if (!_cachedExecuteTeamRun) {
-		// FIX (split-scope install): prime the ESM peer dep BEFORE team-runner is
-		// imported, so its transitive skill-instructions.ts can read getAgentDir()
-		// from the primed cache instead of crashing on `Cannot find module`.
-		await primePeerDep().catch(() => undefined);
-		// LAZY: avoid pulling team-runner into background-runner at module load time.
-		const mod = await import("./team-runner.ts");
-		_cachedExecuteTeamRun = mod.executeTeamRun;
-	}
-	return _cachedExecuteTeamRun(...args);
+	// FIX (split-scope install): prime the ESM peer dep BEFORE team-runner is
+	// imported, so its transitive skill-instructions.ts can read getAgentDir()
+	// from the primed cache instead of crashing on `Cannot find module`.
+	await primePeerDep().catch(() => undefined);
+	// LAZY: avoid pulling team-runner into background-runner at module load time.
+	const mod = await import("./team-runner.ts");
+	return mod.executeTeamRun(...args);
 }
 
 import { logInternalError } from "../utils/internal-error.ts";
@@ -165,6 +159,27 @@ export function signalEventType(sig: string): "async.signal" | "async.failed" {
 	return BENIGN_SIGNALS.has(sig) ? "async.signal" : "async.failed";
 }
 
+/**
+ * Scope-aware diagnostic paths for the background runner (issue #55, follows
+ * the #54 fix in run-tracker.ts). Runs created in a markerless (non-git) cwd
+ * live under userCrewRoot() — resolved via the same createRunPaths/
+ * scopeBaseRoot chain used at run CREATION — while project cwds keep .crew/ or
+ * the .pi/teams/ fallback (issue #29). Pure path math: createRunPaths asserts
+ * the runId (R11-2 boundary hardening preserved) and never touches the fs.
+ *
+ * These must stay (cwd, runId)-derived: both sites run BEFORE the manifest is
+ * loaded (the console redirect is the FIRST thing main() does; exitCodePath is
+ * computed at module load), so manifest.stateRoot is not available yet.
+ */
+export function backgroundLogPath(cwd: string, runId: string): string {
+	return path.join(createRunPaths(cwd, runId).stateRoot, "background.log");
+}
+
+/** exit-code.txt sibling of background.log — same scope resolution (#55). */
+export function backgroundExitCodePath(cwd: string, runId: string): string {
+	return path.join(createRunPaths(cwd, runId).stateRoot, "exit-code.txt");
+}
+
 /**
  * Fire-and-forget event log for signal handlers. Extracted to module level
  * (from inside main()) so the exported SIGINT handler installer (test seam)
@@ -256,11 +271,11 @@ export function startInterruptGuard(
 					/* best-effort ack — interruptHandled gate prevents re-fire */
 				}
 
-				appendEvent(manifest.eventsPath, {
+				appendEventBuffered(manifest.eventsPath, {
 					type: "async.interrupt_detected",
 					runId: manifest.runId,
 					message: "Background runner detected foreground interrupt — killing child processes and exiting.",
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.interrupt_detected"));
 				// FIX: Terminate ALL child-pi processes IMMEDIATELY before exiting.
 				// Previously this was missing, causing orphaned child processes to run forever
 				// after the background-runner exited. terminateActiveChildPiProcesses sends
@@ -311,7 +326,7 @@ function setupUnhandledRejectionGuard(
 		console.error("[background-runner] Stack:", reason instanceof Error ? reason.stack : "N/A");
 		try {
 			if (state.eventsPath && state.runId) {
-				appendEvent(state.eventsPath, {
+				appendEventBuffered(state.eventsPath, {
 					type: "async.failed",
 					runId: state.runId,
 					message: `Unhandled rejection: ${message}`,
@@ -320,7 +335,7 @@ function setupUnhandledRejectionGuard(
 						stack: reason instanceof Error ? reason.stack : undefined,
 						handled: false,
 					},
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=unhandledRejection"));
 			}
 		} catch (appendErr) {
 			console.error("[background-runner] Failed to write async.failed event:", appendErr);
@@ -377,12 +392,12 @@ function runCleanup(
 		console.log(`[background-runner] runCleanup: unregisterWorker error: ${errorMessage(error)}`);
 		if (eventsPath) {
 			try {
-				appendEvent(eventsPath, {
+				appendEventBuffered(eventsPath, {
 					type: "background.unregister_worker_failed",
 					runId: argValue("--run-id") ?? "unknown",
 					message: `unregisterWorker failed: ${errorMessage(error)}`,
 					data: { pid: process.pid },
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=background.unregister_worker_failed"));
 			} catch {
 				/* best-effort */
 			}
@@ -426,10 +441,12 @@ async function main(): Promise<void> {
 		// best-effort try/catch so the hardening is never silently swallowed).
 		assertSafePathId("runId", _runId);
 		try {
-			// Use projectCrewRoot() so the background log lives next to the
-			// manifest in either .crew/state/runs/ or .pi/teams/state/runs/
-			// depending on the project's chosen layout (issue #29).
-			const logPath = path.join(projectCrewRoot(_cwd), "state", "runs", _runId, "background.log");
+			// Scope-aware (issue #55): resolve via createRunPaths so the log lands
+			// next to the manifest for BOTH project cwds (.crew/ or the .pi/teams/
+			// fallback, issue #29) and markerless cwds (user scope, issue #54). The
+			// previous projectCrewRoot join silently dropped the console redirect
+			// for user-scope runs — exactly the log needed to diagnose them.
+			const logPath = backgroundLogPath(_cwd, _runId);
 			logFd = fs.openSync(logPath, "a");
 			const origWrite =
 				(_prefix: string) =>
@@ -483,8 +500,11 @@ async function main(): Promise<void> {
 		// IIFE runs at MODULE LOAD, so an unsafe runId throws before the runner
 		// starts (intended fail-fast, matching run-import.ts:105 pattern).
 		assertSafePathId("runId", runId);
-		// Use projectCrewRoot() to honour the .pi/teams/ fallback (issue #29).
-		return path.join(projectCrewRoot(cwd), "state", "runs", runId, "exit-code.txt");
+		// Scope-aware (issue #55): same resolution as backgroundLogPath — project
+		// scope (.crew/ or .pi/teams/, issue #29) or user scope (#54). The
+		// previous projectCrewRoot join never landed exit-code.txt for user-scope
+		// runs, hiding non-zero exit diagnostics.
+		return backgroundExitCodePath(cwd, runId);
 	})();
 	if (exitCodePath) {
 		process.on("exit", (code) => {
@@ -538,12 +558,12 @@ async function main(): Promise<void> {
 		const runId = argValue("--run-id");
 		if (runId && manifest.eventsPath) {
 			try {
-				appendEvent(manifest.eventsPath, {
+				appendEventBuffered(manifest.eventsPath, {
 					type: "async.sigterm_received_graceful_shutdown",
 					runId,
 					message: `SIGTERM received, graceful shutdown via abort pid=${process.pid}`,
 					data: { pid: process.pid, ppid: process.ppid },
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.sigterm_received_graceful_shutdown"));
 			} catch {
 				/* best-effort */
 			}
@@ -596,12 +616,12 @@ async function main(): Promise<void> {
 			const codeStr = code === undefined ? "<none>" : String(code);
 			if (runId2 && manifest.eventsPath) {
 				try {
-					appendEvent(manifest.eventsPath, {
+					appendEventBuffered(manifest.eventsPath, {
 						type: "async.exit",
 						runId: runId2,
 						message: `Background runner exit(${codeStr}) pid=${process.pid}`,
 						data: { code, pid: process.pid },
-					});
+					}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.exit"));
 				} catch {
 					/* best-effort */
 				}
@@ -635,11 +655,11 @@ async function main(): Promise<void> {
 	// NOTE: intentionally no unref() — the guard keeps the event loop alive
 	// to prevent premature worker exit. See parent-guard.ts:86 for rationale.
 
-	appendEvent(manifest.eventsPath, {
+	appendEventBuffered(manifest.eventsPath, {
 		type: "async.started",
 		runId: manifest.runId,
 		data: { pid: process.pid },
-	});
+	}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.started"));
 	debugLog(`[background-runner] async.started written, pid=${process.pid}`);
 	writeAsyncStartMarker(manifest, {
 		pid: process.pid,
@@ -663,12 +683,12 @@ async function main(): Promise<void> {
 	const watchdogTimer = setTimeout(() => {
 		console.error(`[background-runner] WATCHDOG: run ${runId} exceeded ${MAX_BACKGROUND_RUN_MS}ms — aborting (zombie prevention)`);
 		try {
-			appendEvent(manifest.eventsPath, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "async.watchdog_fired",
 				runId,
 				message: `Run exceeded ${MAX_BACKGROUND_RUN_MS}ms and was force-aborted to prevent a zombie background-runner process.`,
 				data: { maxRunMs: MAX_BACKGROUND_RUN_MS },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.watchdog_fired"));
 		} catch {
 			/* best-effort event log */
 		}
@@ -825,12 +845,12 @@ async function main(): Promise<void> {
 				updatedAt: new Date().toISOString(),
 			};
 			await saveRunManifestAsync(manifest);
-			appendEvent(manifest.eventsPath, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "runtime.resolved",
 				runId: manifest.runId,
 				message: `Runtime resolved: ${runtime.kind} safety=${runtime.safety}`,
 				data: { runtimeResolution, async: true },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=runtime.resolved"));
 			if (runtime.safety === "blocked")
 				throw new Error(runtime.reason ?? "Child worker execution is disabled; refusing to create no-op scaffold subagents.");
 			const executeWorkers = runtime.kind !== "scaffold";
@@ -890,11 +910,11 @@ async function main(): Promise<void> {
 		} // close if (!earlyResult) — team-run setup+execute done; earlyResult path skips to here
 		manifest = result!.manifest;
 		tasks = result!.tasks;
-		appendEvent(manifest.eventsPath, {
+		appendEventBuffered(manifest.eventsPath, {
 			type: "async.completed",
 			runId: manifest.runId,
 			data: { status: manifest.status, tasks: tasks.length },
-		});
+		}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.completed"));
 		console.log(`[background-runner] async.completed written, status=${manifest.status}`);
 		if (manifest.status === "failed" || manifest.status === "cancelled" || manifest.status === "blocked") process.exitCode = 1;
 	} catch (error) {
@@ -915,11 +935,11 @@ async function main(): Promise<void> {
 					const fresh = loaded?.manifest ?? manifest;
 					if (fresh) {
 						manifest = updateRunStatus(fresh, "failed", message);
-						appendEvent(manifest.eventsPath, {
+						appendEventBuffered(manifest.eventsPath, {
 							type: "async.failed",
 							runId: manifest.runId,
 							message,
-						});
+						}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=updateFailed"));
 					}
 					return fresh;
 				},
@@ -988,12 +1008,12 @@ try {
 		const mRunId = argValue("--run-id");
 		if (mCwd && mRunId) {
 			const mEventsPath = createRunPaths(mCwd, mRunId).eventsPath;
-			appendEvent(mEventsPath, {
+			appendEventBuffered(mEventsPath, {
 				type: "async.failed",
 				runId: mRunId,
 				message: errorMessage(err),
 				data: { stack: err instanceof Error ? err.stack : undefined },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=catch"));
 		}
 	} catch {
 		/* best-effort — don't let event-write failure mask the original error */