pi-crew 0.9.55 → 0.9.57

package/src/runtime/{sidechain-output.ts → output/sidechain-output.ts}

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { redactSecrets } from "../utils/redaction.ts";
-import { isSafePathId } from "../utils/safe-paths.ts";
+import { redactSecrets } from "../../utils/redaction.ts";
+import { isSafePathId } from "../../utils/safe-paths.ts";
 
 export interface SidechainEntry {
 	isSidechain: true;

package/src/runtime/{stream-preview.ts → output/stream-preview.ts}

@@ -2,7 +2,7 @@
 // Captures incremental worker output during task execution for live preview.
 // Used by the UI layer to show partial results before task completion.
 
-import { TAIL_CAPTURE_STREAM_STAGE } from "./compact-stages/index.ts";
+import { TAIL_CAPTURE_STREAM_STAGE } from "../compaction/compact-stages/index.ts";
 import type { ParsedPiUsage } from "./pi-json-output.ts";
 
 export interface ToolCallPreview {

package/src/runtime/{streaming-output.ts → output/streaming-output.ts}

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { TeamRunManifest } from "../state/types.ts";
-import { isSafePathId } from "../utils/safe-paths.ts";
+import type { TeamRunManifest } from "../../state/types.ts";
+import { isSafePathId } from "../../utils/safe-paths.ts";
 
 export interface StreamingOutputHandle {
 	write(text: string): void;

package/src/runtime/{tool-progress.ts → output/tool-progress.ts}

@@ -10,7 +10,7 @@
  * 4. This module provides structured types and utilities for the event system
  */
 
-import type { CrewAgentProgress } from "../state/types.ts";
+import type { CrewAgentProgress } from "../../state/types.ts";
 
 // ── Event Types ─────────────────────────────────────────────────────────
 

package/src/runtime/parent-guard.ts

@@ -1,16 +1,32 @@
 /**
- * Parent liveness guard for pi-crew worker processes.
+ * Parent liveness guard for pi-crew background-runner process.
  *
- * Workers call `startParentGuard(parentPid)` at startup. A lightweight
- * interval checks if the parent PID is still alive. When the parent dies
- * (SIGKILL, crash, power loss, terminal close), the worker self-terminates
- * immediately — no sentinel process needed.
+ * REALITY (verified by grep, RT-19/RT-2): `startParentGuard` is called in
+ * exactly ONE production location — `background-runner.ts:508`. The
+ * background-runner watches the main pi session that spawned it. If that
+ * parent dies, the runner self-terminates so it does not leak.
+ *
+ * Child pi workers do NOT call `startParentGuard`. They are the external
+ * `pi` binary (`@earendil-works/pi-coding-agent`) — pi-crew does not control
+ * its entry point. Although `PI_CREW_PARENT_PID` is set in the child's env
+ * (`child-pi-spawn.ts:134`), it has ZERO consumers: grep of the Pi binary
+ * dist for `PI_CREW_PARENT_PID` / `startParentGuard` / `parent-guard` = 0
+ * matches. This means child workers are NOT protected by this guard.
+ *
+ * The deeper fix (wiring `startParentGuard` into the pi worker entry point) is
+ * DEFERRED because workers are an external binary pi-crew doesn't control.
+ *
+ * Orphan-mitigation for this gap relies on:
+ *   1. The RT-2 SIGINT fix in `background-runner.ts` (abort + exitCode pattern
+ *      lets the finally/runCleanup block terminate child-pi processes).
+ *   2. The reactive `zombie-scanner.ts` sweep (finds workers whose
+ *      `PI_CREW_PARENT_PID` points at a dead PID and reports them).
  *
  * Note: `process.kill(pid, 0)` works on both Unix and Windows in Node.js
  * for checking process existence. On Windows, it may throw for processes
  * owned by other users (permission error), but correctly detects dead PIDs.
  *
- * Usage in worker entry points:
+ * Usage in background-runner.ts (the ONLY consumer):
  * ```ts
  * const parentPid = Number(process.env.PI_CREW_PARENT_PID);
  * if (parentPid > 0) startParentGuard(parentPid);
@@ -81,12 +97,16 @@ function selfTerminate(parentPid: number): never {
 
 /**
  * Start a lightweight poll that checks if the parent process is still alive.
- * If the parent dies, this worker exits immediately with code 124.
+ * If the parent dies, the calling process exits immediately with code 124.
+ *
+ * CURRENT REALITY: the only production caller is `background-runner.ts`, which
+ * uses this to self-terminate when the main pi session dies. Child pi workers
+ * do NOT call this (see module header for the DEFERRED deeper fix).
  *
  * FIX: Removed unref() — the guard interval MUST keep the event loop alive
- * to prevent premature worker exit when the parent is still alive but the
- * worker has no other pending work (LLM calls, timers, I/O). Without this,
- * a worker in pure CPU wait could exit even though its parent is alive.
+ * to prevent premature runner exit when the parent is still alive but the
+ * runner has no other pending work (LLM calls, timers, I/O). Without this,
+ * a runner in pure CPU wait could exit even though its parent is alive.
  */
 export function startParentGuard(parentPid: number): void {
 	if (!parentPid || !Number.isFinite(parentPid) || parentPid <= 0) return;

package/src/runtime/pipeline-runner.ts

@@ -1,8 +1,8 @@
 import { errors } from "../errors.ts";
-import { appendEventAsync, flushEventLogBuffer } from "../state/event-log.ts";
+import { appendEventAsync, flushEventLogBuffer } from "../state/event-log/event-log.ts";
 import { errorMessage } from "../utils/guards.ts";
 import type { WorkflowConfig } from "../workflows/workflow-config.ts";
-import { mapConcurrent } from "./parallel-utils.ts";
+import { mapConcurrent } from "./scheduling/parallel-utils.ts";
 
 /**
  * Pipeline stage configuration.

package/src/runtime/policy-engine.ts

@@ -1,7 +1,7 @@
 import type { CrewLimitsConfig } from "../config/config.ts";
 import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { evaluateGreenContract } from "./green-contract.ts";
-import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
+import { isWorkerHeartbeatStale } from "./heartbeat/worker-heartbeat.ts";
+import { evaluateGreenContract } from "./verification/green-contract.ts";
 
 export interface PolicyEngineInput {
 	manifest: TeamRunManifest;

package/src/runtime/{cancellation.ts → process/cancellation.ts}

@@ -1,4 +1,4 @@
-import type { OperationTerminalEvidence } from "../state/types.ts";
+import type { OperationTerminalEvidence } from "../../state/types.ts";
 
 export type CancellationReasonCode =
 	| "caller_cancelled"

package/src/runtime/{post-exit-stdio-guard.ts → process/post-exit-stdio-guard.ts}

@@ -1,5 +1,5 @@
 import type { ChildProcess } from "node:child_process";
-import { logInternalError } from "../utils/internal-error.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 
 interface PostExitStdioGuardOptions {
 	idleMs: number;

package/src/runtime/{process-lifecycle.ts → process/process-lifecycle.ts}

@@ -1,7 +1,7 @@
 /**
  * Owned-process lifecycle abstraction (P0 item #3).
  *
- * Distilled and adapted from gajae-code's `runtime/process-lifecycle.ts`.
+ * Distilled and adapted from gajae-code's `runtime/process/process-lifecycle.ts`.
  *
  * Two complementary primitives:
  *
@@ -30,7 +30,7 @@
  * See `.crew/knowledge.md` gotchas: BSD/Windows signal handling differs.
  */
 import { type ChildProcess, type SpawnOptions, spawn } from "node:child_process";
-import { logInternalError } from "../utils/internal-error.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 
 // ── tunables ──────────────────────────────────────────────────────────────────
 
@@ -197,7 +197,7 @@ export class OwnedProcess {
 		}
 	}
 
-	private deregisterFn: () => void = () => {};
+	private deregisterFn: () => void = () => undefined;
 
 	/** `true` once `dispose()` has started. */
 	get isDisposed(): boolean {

package/src/runtime/{checkpoint.ts → recovery/checkpoint.ts}

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { atomicWriteFile } from "../state/atomic-write.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId } from "../utils/safe-paths.ts";
+import { atomicWriteFile } from "../../state/atomic-write.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
 
 export interface Checkpoint {
 	runId: string;

package/src/runtime/{crash-recovery.ts → recovery/crash-recovery.ts}

@@ -1,22 +1,23 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { appendHookEvent, executeHook } from "../hooks/registry.ts";
-import type { MetricRegistry } from "../observability/metric-registry.ts";
-import { readActiveRunRegistry, unregisterActiveRun } from "../state/active-run-registry.ts";
-import { appendEvent, scanSequence } from "../state/event-log.ts";
-import { withRunLockSync } from "../state/locks.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
-import type { TeamTaskState } from "../state/types.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
-import { terminateLiveAgentsForRun } from "./live-agent-manager.ts";
-import type { ManifestCache } from "./manifest-cache.ts";
-import { checkProcessLiveness } from "./process-status.ts";
-import { isPlanApprovalPending, type ReconcileResult, reconcileStaleRun } from "./stale-reconciler.ts";
-import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
+import { appendHookEvent, executeHook } from "../../hooks/registry.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import { withRunLockSync } from "../../state/coordination/locks.ts";
+import { appendEvent, scanSequence } from "../../state/event-log/event-log.ts";
+import { readActiveRunRegistry, unregisterActiveRun } from "../../state/stores/active-run-registry.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
+import type { TeamTaskState } from "../../state/types.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { sleepSync } from "../../utils/sleep.ts";
+import { recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
+import { isWorkerHeartbeatStale } from "../heartbeat/worker-heartbeat.ts";
+import { terminateLiveAgentsForRun } from "../live-session/live-agent-manager.ts";
+import type { ManifestCache } from "../manifest-cache.ts";
+import { checkProcessLiveness } from "../process-status.ts";
+import { isPlanApprovalPending, type ReconcileResult, reconcileStaleRun } from "../stale-reconciler.ts";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -35,6 +36,68 @@ function isTerminalTask(task: TeamTaskState): boolean {
 	);
 }
 
+/**
+ * Errno codes that represent transient filesystem conditions (e.g. Windows AV
+ * scan temporarily locking the file, or a brief permission window). On these
+ * errors the manifest is NOT corrupt — retrying the read after a short backoff
+ * will succeed.
+ */
+const TRANSIENT_READ_ERRNO_CODES = new Set(["EBUSY", "EACCES", "EAGAIN", "EPERM", "ENFILE", "EMFILE"]);
+
+/**
+ * Raw file-read function used by readManifestWithTransientRetry. Separated as
+ * a module-level binding so tests can inject transient-error mocks without
+ * needing to mutate the frozen ESM `fs` namespace.
+ */
+let _readManifestFileSync: (filePath: string) => string = (p) => fs.readFileSync(p, "utf-8");
+
+/**
+ * @internal — test seam for readManifestWithTransientRetry. Pass `null` to reset.
+ */
+export function _setReadManifestFileSyncForTest(fn: ((filePath: string) => string) | null): void {
+	_readManifestFileSync = fn ?? ((p) => fs.readFileSync(p, "utf-8"));
+}
+
+/**
+ * Read and JSON-parse a manifest file, retrying transient read errors
+ * (EBUSY/EACCES/EAGAIN — common on Windows when AV software briefly locks the
+ * file) with exponential backoff.
+ *
+ * ST-6: Previously, a single `catch` quarantined the manifest on ALL errors,
+ * including transient I/O failures that left a perfectly healthy manifest
+ * unparseable for a few milliseconds. This renamed the valid file to
+ * `.corrupt-*`, making the run permanently unloadable.
+ *
+ * Behavior:
+ * - Success → returns parsed object
+ * - SyntaxError (genuinely corrupt JSON) → rethrown immediately (caller quarantines)
+ * - Transient ErrnoException → retried up to `maxRetries` times; if still
+ *   failing, rethrown so the caller can skip WITHOUT quarantining
+ * - Other ErrnoException (ENOENT, etc.) → rethrown immediately
+ */
+export function readManifestWithTransientRetry(manifestPath: string, maxRetries = 3, baseDelayMs = 100): Record<string, unknown> {
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			return JSON.parse(_readManifestFileSync(manifestPath)) as Record<string, unknown>;
+		} catch (err) {
+			// SyntaxError = genuinely corrupt JSON → rethrow immediately
+			if (err instanceof SyntaxError) throw err;
+			const code = (err as NodeJS.ErrnoException).code;
+			// Transient read error → retry with exponential backoff
+			if (code !== undefined && TRANSIENT_READ_ERRNO_CODES.has(code)) {
+				if (attempt < maxRetries) {
+					sleepSync(baseDelayMs * 2 ** attempt);
+					continue;
+				}
+			}
+			// Non-transient error, or retries exhausted → rethrow
+			throw err;
+		}
+	}
+	// Unreachable: the loop either returns or throws on every iteration.
+	throw new Error(`unreachable: readManifestWithTransientRetry exhausted for ${manifestPath}`);
+}
+
 function shouldRecoverTask(task: TeamTaskState, deadMs: number): boolean {
 	if (task.status !== "running") return false;
 	if (!task.heartbeat) return true;
@@ -375,11 +438,20 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 			  }
 			| undefined;
 		try {
-			manifest = JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8"));
-		} catch {
-			// R-01: Quarantine the corrupt manifest instead of deleting all run state.
-			// A single corrupted byte must NOT cause total data loss — events.jsonl,
-			// task data, and artifacts are preserved for manual recovery.
+			manifest = readManifestWithTransientRetry(entry.manifestPath) as typeof manifest;
+		} catch (err) {
+			// ST-6: Transient read errors (EBUSY/EACCES/EAGAIN from Windows AV
+			// scans) must NOT quarantine a healthy manifest — the file is fine,
+			// just temporarily locked. Skip this entry and try again next cycle.
+			const code = (err as NodeJS.ErrnoException).code;
+			const isTransient = code !== undefined && TRANSIENT_READ_ERRNO_CODES.has(code);
+			if (isTransient) continue;
+
+			// R-01: Quarantine the corrupt manifest instead of deleting all run
+			// state. A single corrupted byte must NOT cause total data loss —
+			// events.jsonl, task data, and artifacts are preserved for manual
+			// recovery. SyntaxError (genuinely corrupt JSON) and unexpected
+			// non-transient errors fall through to here.
 			try {
 				// Include pid for uniqueness across concurrent quarantines in the same ms.
 				fs.renameSync(entry.manifestPath, entry.manifestPath + ".corrupt-" + Date.now() + "-" + process.pid);

package/src/runtime/{overflow-recovery.ts → recovery/overflow-recovery.ts}

@@ -1,4 +1,4 @@
-import { logInternalError } from "../utils/internal-error.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 
 export type OverflowPhase = "none" | "compaction" | "retrying" | "recovered" | "failed";
 

package/src/runtime/{recovery-recipes.ts → recovery/recovery-recipes.ts}

@@ -1,4 +1,4 @@
-import type { PolicyDecision, PolicyDecisionReason } from "../state/types.ts";
+import type { PolicyDecision, PolicyDecisionReason } from "../../state/types.ts";
 
 export type FailureScenario =
 	| "trust_prompt_unresolved"

package/src/runtime/{retry-executor.ts → recovery/retry-executor.ts}

@@ -1,5 +1,5 @@
-import { sleep } from "../utils/sleep.ts";
-import { throwIfCancelled } from "./cancellation.ts";
+import { sleep } from "../../utils/sleep.ts";
+import { throwIfCancelled } from "../process/cancellation.ts";
 
 export interface RetryPolicy {
 	maxAttempts: number;

package/src/runtime/{retry-runner.ts → recovery/retry-runner.ts}

@@ -7,11 +7,9 @@
  * - Accumulates context from previous attempts
  * - Supports exponential backoff
  * - Limits handoff accumulation to prevent memory leaks
- *
- * @see docs/pi-boomerang-integration-plan.md
  */
 
-import type { HandoffManager, HandoffSummary, TaskPacket, TaskResult } from "./handoff-manager.ts";
+import type { HandoffManager, HandoffSummary, TaskPacket, TaskResult } from "../handoff-manager.ts";
 
 /**
  * Retry configuration.
@@ -73,7 +71,6 @@ export class RetryRunner {
 
 	private taskRunner: TaskRunnerLike;
 	private handoffManager: HandoffManager;
-	private _handoffs: HandoffSummary[] = [];
 
 	constructor(taskRunner: TaskRunnerLike, handoffManager: HandoffManager) {
 		this.taskRunner = taskRunner;
@@ -100,7 +97,7 @@ export class RetryRunner {
 	 * Useful when you want to reset state without disposing.
 	 */
 	clearHandoffs(): void {
-		this._handoffs = [];
+		/* no-op: _handoffs field removed (was never read) */
 	}
 
 	/**
@@ -139,9 +136,6 @@ export class RetryRunner {
 		const startTime = Date.now();
 		const maxHandoffs = this.getMaxHandoffs(config);
 
-		// Clear previous handoffs at start of each retry run
-		this._handoffs = [];
-
 		for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
 			if (this._disposed) {
 				throw new Error("RetryRunner was disposed during retry");

package/src/runtime/run-tracker.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { loadRunManifestById } from "../state/state-store.ts";
+import { loadRunManifestById } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { isFinishedRunStatus } from "./process-status.ts";

package/src/runtime/run-worker.ts

@@ -26,9 +26,9 @@
  * caller-owned (they need task/manifest state that runWorker does not see).
  */
 
-import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi.ts";
-import { runChildPi } from "./child-pi.ts";
-import { withWorkerSlot } from "./global-worker-cap.ts";
+import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi/child-pi.ts";
+import { runChildPi } from "./child-pi/child-pi.ts";
+import { withWorkerSlot } from "./scheduling/global-worker-cap.ts";
 
 /**
  * Input for {@link runWorker}. Extends {@link ChildPiRunInput} with the `cap`

package/src/runtime/{coalesce-tasks.ts → scheduling/coalesce-tasks.ts}

@@ -27,9 +27,9 @@
  *     grouping many micro-tasks into one worker prompt.
  */
 
-import type { TeamTaskState } from "../state/types.ts";
-import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
-import { permissionForRole } from "./role-permission.ts";
+import type { TeamTaskState } from "../../state/types.ts";
+import type { WorkflowConfig, WorkflowStep } from "../../workflows/workflow-config.ts";
+import { permissionForRole } from "../role-permission.ts";
 
 /** Default cap on group size to prevent context-budget overflow. */
 export const DEFAULT_MAX_GROUP_SIZE = 5;

package/src/runtime/{concurrency.ts → scheduling/concurrency.ts}

@@ -1,4 +1,5 @@
-import { DEFAULT_CONCURRENCY } from "../config/defaults.ts";
+import { DEFAULT_CONCURRENCY } from "../../config/defaults.ts";
+import { getWorkerCapCapacity } from "./global-worker-cap.ts";
 
 export interface ResolveBatchConcurrencyInput {
 	workflowName: string;
@@ -7,6 +8,8 @@ export interface ResolveBatchConcurrencyInput {
 	limitMaxConcurrentWorkers?: number;
 	allowUnboundedConcurrency?: boolean;
 	hardCap?: number;
+	/** Optional override for the global worker cap (test determinism). Defaults to getWorkerCapCapacity(). */
+	workerCap?: number;
 	readyCount: number;
 	workspaceMode?: "single" | "worktree";
 	readyRoles?: string[];
@@ -45,9 +48,12 @@ export function resolveBatchConcurrency(input: ResolveBatchConcurrencyInput): Ba
 	else if (teamMax !== undefined) source = "team";
 	else source = "workflow";
 	const hardCap = positiveInteger(input.hardCap) ?? DEFAULT_CONCURRENCY.hardCap;
-	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap);
+	// P1-7: consult the global worker cap so the scheduler doesn't over-dispatch
+	// (e.g. dispatch 4 while the global semaphore holds 2 on a 4-core machine).
+	const workerCap = positiveInteger(input.workerCap) ?? getWorkerCapCapacity();
+	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap, workerCap);
 	const readyCount = Math.max(0, Math.trunc(Number.isFinite(input.readyCount) ? input.readyCount : 0));
-	const cappedReason = maxConcurrent < requested ? `;capped:${hardCap}` : "";
+	const cappedReason = maxConcurrent < requested ? `;capped:hard=${hardCap},worker=${workerCap}` : "";
 	const unboundedReason = input.allowUnboundedConcurrency && requested > hardCap ? `;unbounded:${hardCap}` : "";
 	return {
 		maxConcurrent,

package/src/runtime/{parallel-research.ts → scheduling/parallel-research.ts}

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+import type { WorkflowConfig, WorkflowStep } from "../../workflows/workflow-config.ts";
 
 export function sourcePiProjects(cwd: string): string[] {
 	const sourceDir = path.join(cwd, "Source");
@@ -17,7 +17,9 @@ export function sourcePiProjects(cwd: string): string[] {
 
 export function chunkProjects(projects: string[], target = 6): string[][] {
 	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
-	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
+	projects.forEach((project, index) => {
+		chunks[index % chunks.length]!.push(project);
+	});
 	return chunks.filter((chunk) => chunk.length > 0);
 }