pi-crew 0.9.53 → 0.9.55

package/src/runtime/verification-worktree.ts

@@ -0,0 +1,186 @@
+/**
+ * Phase 1.5 #2 — Git-worktree verification sandbox.
+ *
+ * RFC: research-findings/goal-workflow/16-PHASE1.5-WORKTREE-SANDBOX-RFC.md
+ *
+ * Closes the two remaining Med-High tampering residuals from RFC 13 §6:
+ *   (1) Round-trip manifest tamper (MAJ#2): worker edits package.json, runs
+ *       test, reverts before T_verify_done → snapshot matches → undetected.
+ *   (2) Invoked-script tampering: worker rewrites a script the verification
+ *       command invokes; only MANIFEST_FILES are hashed → invisible.
+ *
+ * Mitigation: run verification commands in a pristine `git worktree` at the
+ * T_snap commit SHA. Worker edits in the main workspace are invisible to
+ * the verification subprocess. Content-addressed execution: the test passes
+ * (or fails) against the original code, regardless of worker edits.
+ *
+ * Opt-in via PI_CREW_VERIFICATION_WORKTREE=1 (mirrors Phase 1.5 #1 pattern).
+ * Auto-fallback to existing behavior when: not a git repo, dirty index,
+ * git unavailable, or opt-out explicitly set. NEVER blocks the goal loop.
+ *
+ * Pure leaf module: depends only on node: built-ins + git CLI. No imports
+ * from goal-loop-runner or verification-gates (keeps unit-testable).
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface VerificationWorktree {
+	/** Absolute path to the pristine worktree directory. */
+	worktreePath: string;
+	/** Commit SHA the worktree is checked out at (matches T_snap). */
+	commitSha: string;
+	/** Cleanup handle — call to remove the worktree + temp dir. Idempotent. */
+	cleanup: () => void;
+}
+
+/** Whether the worktree sandbox is enabled (env var opt-in). */
+export function isWorktreeSandboxEnabled(): boolean {
+	const v = process.env.PI_CREW_VERIFICATION_WORKTREE ?? process.env.PI_TEAMS_VERIFICATION_WORKTREE;
+	return v === "1" || v === "true";
+}
+
+/**
+ * Detect whether the worktree sandbox is AVAILABLE at `cwd`:
+ *  - opt-in env var set
+ *  - git executable on PATH
+ *  - cwd is inside a git repo
+ *  - git index is clean (no uncommitted changes that would be lost)
+ *
+ * Returns false (with reason) when any precondition fails. Callers MUST
+ * gracefully fall back to non-sandboxed execution — never block the goal.
+ */
+export function checkWorktreeSandboxAvailable(cwd: string): { available: true; commitSha: string } | { available: false; reason: string } {
+	if (!isWorktreeSandboxEnabled()) {
+		return {
+			available: false,
+			reason: "PI_CREW_VERIFICATION_WORKTREE not set (opt-in)",
+		};
+	}
+	try {
+		// Is cwd inside a git repo? `git rev-parse --show-toplevel` errors out
+		// (non-zero exit) when not in a repo. execFileSync throws on non-zero.
+		const toplevel = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			encoding: "utf-8",
+		}).trim();
+		if (!toplevel)
+			return {
+				available: false,
+				reason: "git rev-parse returned empty toplevel",
+			};
+		// Current commit SHA (this is what T_snap will pin to).
+		const commitSha = execFileSync("git", ["rev-parse", "HEAD"], {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			encoding: "utf-8",
+		}).trim();
+		if (!commitSha)
+			return {
+				available: false,
+				reason: "git rev-parse HEAD returned empty SHA",
+			};
+		// Dirty index? `git status --porcelain` outputs non-empty if there are
+		// uncommitted changes. We refuse to sandbox a dirty workspace because
+		// the worktree would NOT contain the in-progress edits (T_snap would
+		// pin to a stale commit). Better to fall back + warn than silently
+		// verify against the wrong code.
+		const status = execFileSync("git", ["status", "--porcelain"], {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			encoding: "utf-8",
+		}).trim();
+		if (status.length > 0)
+			return {
+				available: false,
+				reason: `dirty git index (${status.split("\n").length} changed files); refusing to sandbox — worktree would pin to stale commit`,
+			};
+		return { available: true, commitSha };
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		return {
+			available: false,
+			reason: `git precondition check failed: ${msg.slice(0, 200)}`,
+		};
+	}
+}
+
+/**
+ * Prepare a pristine git worktree at `commitSha`. The worktree is a fresh
+ * checkout of the project at that commit — it does NOT contain worker edits
+ * from the main workspace.
+ *
+ * `git worktree add --detach <tmp>/wt-<sha8> <sha>` creates a detached-HEAD
+ * worktree (no branch pollution). Returns the worktree path + cleanup handle.
+ *
+ * Cleanup is idempotent (safe to call multiple times) and best-effort (swallows
+ * errors so a stuck worktree doesn't propagate into the goal loop).
+ */
+export function prepareVerificationWorktree(cwd: string, commitSha: string): VerificationWorktree {
+	// Temp parent dir under os.tmpdir() so worktrees are auto-cleaned on reboot.
+	const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-wt-"));
+	const shortSha = commitSha.slice(0, 8);
+	const worktreePath = path.join(tmpRoot, `wt-${shortSha}`);
+	let cleaned = false;
+	const cleanup = (): void => {
+		if (cleaned) return;
+		cleaned = true;
+		// Remove the worktree (force = proceed even if it has untracked files).
+		try {
+			execFileSync("git", ["worktree", "remove", "--force", worktreePath], { cwd, stdio: ["ignore", "pipe", "pipe"], timeout: 5000 });
+		} catch {
+			// Fall back to `git worktree prune` if remove fails (already gone).
+			try {
+				execFileSync("git", ["worktree", "prune"], {
+					cwd,
+					stdio: ["ignore", "pipe", "pipe"],
+					timeout: 5000,
+				});
+			} catch {
+				/* best-effort */
+			}
+		}
+		// Remove the temp parent dir.
+		try {
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		} catch {
+			/* best-effort */
+		}
+	};
+	try {
+		execFileSync("git", ["worktree", "add", "--detach", worktreePath, commitSha], {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			timeout: 30_000,
+		});
+		return { worktreePath, commitSha, cleanup };
+	} catch (error) {
+		cleanup();
+		const msg = error instanceof Error ? error.message : String(error);
+		throw new Error(`git worktree add failed (cwd=${cwd}, sha=${shortSha}): ${msg.slice(0, 300)}`);
+	}
+}
+
+/**
+ * RAII wrapper: prepare worktree, run `fn(worktree)`, ALWAYS cleanup in finally.
+ *
+ * `fn` may throw — the worktree is removed regardless. The original error
+ * propagates (cleanup errors are swallowed and best-effort).
+ *
+ * If preparation fails, the function rethrows WITHOUT calling fn — caller
+ * must handle the prep failure (typically by falling back to non-sandboxed).
+ */
+export async function withVerificationWorktree<T>(
+	cwd: string,
+	commitSha: string,
+	fn: (worktree: VerificationWorktree) => Promise<T> | T,
+): Promise<T> {
+	const worktree = prepareVerificationWorktree(cwd, commitSha);
+	try {
+		return await fn(worktree);
+	} finally {
+		worktree.cleanup();
+	}
+}

package/src/runtime/worker-heartbeat.ts

@@ -0,0 +1,25 @@
+export interface WorkerHeartbeatState {
+	workerId: string;
+	pid?: number;
+	lastSeenAt: string;
+	lastStdoutAt?: string;
+	lastEventAt?: string;
+	turnCount?: number;
+	alive?: boolean;
+}
+
+export function createWorkerHeartbeat(workerId: string, pid?: number, now = new Date()): WorkerHeartbeatState {
+	return { workerId, pid, lastSeenAt: now.toISOString(), alive: true };
+}
+
+export function touchWorkerHeartbeat(
+	heartbeat: WorkerHeartbeatState,
+	updates: Partial<Omit<WorkerHeartbeatState, "workerId">> = {},
+	now = new Date(),
+): WorkerHeartbeatState {
+	return { ...heartbeat, ...updates, lastSeenAt: now.toISOString() };
+}
+
+export function isWorkerHeartbeatStale(heartbeat: WorkerHeartbeatState, staleMs: number, now = new Date()): boolean {
+	return now.getTime() - Date.parse(heartbeat.lastSeenAt) > staleMs;
+}

package/src/runtime/worker-startup.ts

@@ -0,0 +1,83 @@
+export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
+export type StartupFailureClassification =
+	| "trust_required"
+	| "prompt_misdelivery"
+	| "prompt_acceptance_timeout"
+	| "transport_dead"
+	| "worker_crashed"
+	| "rate_limited"
+	| "provider_error"
+	| "unknown";
+
+export interface WorkerStartupEvidence {
+	lastLifecycleState: WorkerLifecycleState;
+	command: string;
+	promptSentAt?: string;
+	promptAccepted: boolean;
+	trustPromptDetected: boolean;
+	transportHealthy: boolean;
+	childProcessAlive: boolean;
+	elapsedMs: number;
+	classification: StartupFailureClassification;
+	stderrPreview?: string;
+}
+
+export function detectTrustPrompt(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return (
+		lowered.includes("do you trust") ||
+		lowered.includes("trust this") ||
+		lowered.includes("untrusted") ||
+		lowered.includes("workspace trust") ||
+		lowered.includes("allow this folder")
+	);
+}
+
+export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
+	if (evidence.stderrPreview && /429|rate.?limit/i.test(evidence.stderrPreview)) return "rate_limited";
+	if (evidence.stderrPreview && /5\d{2}|server.?error|internal.?error|provider.?error/i.test(evidence.stderrPreview))
+		return "provider_error";
+	if (!evidence.transportHealthy) return "transport_dead";
+	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
+	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
+	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
+	if (
+		evidence.stderrPreview?.toLowerCase().includes("command not found") ||
+		evidence.stderrPreview?.toLowerCase().includes("not recognized")
+	)
+		return "prompt_misdelivery";
+	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
+	return "unknown";
+}
+
+export function createStartupEvidence(input: {
+	command: string;
+	startedAt: Date;
+	finishedAt?: Date;
+	promptSentAt?: Date;
+	promptAccepted?: boolean;
+	stderr?: string;
+	error?: string;
+	exitCode?: number | null;
+}): WorkerStartupEvidence {
+	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
+	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
+	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
+	const base: Omit<WorkerStartupEvidence, "classification"> = {
+		lastLifecycleState:
+			input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0)
+				? "failed"
+				: input.finishedAt
+					? "finished"
+					: "running",
+		command: input.command,
+		promptSentAt: input.promptSentAt?.toISOString(),
+		promptAccepted: input.promptAccepted ?? !input.error,
+		trustPromptDetected,
+		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
+		childProcessAlive,
+		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
+		stderrPreview,
+	};
+	return { ...base, classification: classifyStartupFailure(base) };
+}

package/src/runtime/workflow-state.ts

@@ -0,0 +1,195 @@
+/**
+ * Workflow Phase State Machine
+ *
+ * Tracks phase-level progression through a workflow, validating that each
+ * phase's declared inputs (required artifacts) are satisfied before it can
+ * start. All transition functions are immutable — they return new machine
+ * state rather than mutating in place.
+ */
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+export type PhaseStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+
+export interface PhaseGuardContext {
+	/** Artifact paths that currently exist on disk. */
+	completedArtifacts: string[];
+	/** Status of the phase immediately preceding the target phase. */
+	previousPhaseStatus: PhaseStatus;
+	/** Results from tasks that have already completed. */
+	taskResults: Array<{ taskId: string; status: string; outputPath?: string }>;
+}
+
+export interface GuardResult {
+	allowed: boolean;
+	reason?: string;
+}
+
+export interface PhaseTransition {
+	from: PhaseStatus;
+	to: PhaseStatus;
+	guard?: (context: PhaseGuardContext) => GuardResult;
+}
+
+export interface PhaseState {
+	name: string;
+	status: PhaseStatus;
+	/** Artifact names required before this phase can start. */
+	inputs: string[];
+	/** Artifact names this phase produces. */
+	outputs: string[];
+	startedAt?: string;
+	finishedAt?: string;
+}
+
+export interface WorkflowStateMachine {
+	phases: PhaseState[];
+	currentPhaseIndex: number;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create a new workflow state machine from an initial set of phases.
+ * All phases start as "pending" and the current index is set to 0.
+ */
+export function createWorkflowStateMachine(phases: PhaseState[]): WorkflowStateMachine {
+	return {
+		phases: phases.map((phase) => ({
+			...phase,
+			status: phase.status ?? "pending",
+		})),
+		currentPhaseIndex: 0,
+	};
+}
+
+// ── Queries ───────────────────────────────────────────────────────────────────
+
+/**
+ * Return the declared inputs for a given phase index.
+ * Returns an empty array for out-of-bounds indices.
+ */
+export function getPhaseInputs(machine: WorkflowStateMachine, phaseIndex: number): string[] {
+	const phase = machine.phases[phaseIndex];
+	if (!phase) return [];
+	return phase.inputs;
+}
+
+/**
+ * Check whether a transition to a specific phase is allowed.
+ *
+ * Rules (evaluated in order):
+ * 1. `phaseIndex` must be in bounds.
+ * 2. If this is not the first phase, the previous phase must be "completed" or "skipped".
+ * 3. All declared `inputs` for the target phase must appear in `completedArtifacts`.
+ * 4. If a custom `guard` is supplied on a transition, it must also approve.
+ */
+export function canTransitionToPhase(machine: WorkflowStateMachine, phaseIndex: number, context: PhaseGuardContext): GuardResult {
+	if (phaseIndex < 0 || phaseIndex >= machine.phases.length) {
+		return {
+			allowed: false,
+			reason: `Phase index ${phaseIndex} is out of bounds (0..${machine.phases.length - 1}).`,
+		};
+	}
+
+	// Previous phase must have completed (or been skipped).
+	if (phaseIndex > 0) {
+		const prevStatus = context.previousPhaseStatus;
+		if (prevStatus !== "completed" && prevStatus !== "skipped") {
+			return {
+				allowed: false,
+				reason: `Previous phase status is '${prevStatus}'; expected 'completed' or 'skipped'.`,
+			};
+		}
+	}
+
+	// All declared inputs must be satisfied.
+	const phase = machine.phases[phaseIndex]!;
+	if (phase.inputs.length > 0) {
+		const artifactSet = new Set(context.completedArtifacts);
+		const missing = phase.inputs.filter((input) => !artifactSet.has(input));
+		if (missing.length > 0) {
+			return {
+				allowed: false,
+				reason: `Missing required artifacts: ${missing.join(", ")}.`,
+			};
+		}
+	}
+
+	return { allowed: true };
+}
+
+/**
+ * Validate that all preconditions for the *current* phase are met.
+ * Returns the subset of declared inputs that are not yet present in `completedArtifacts`.
+ */
+export function validatePhasePreconditions(
+	machine: WorkflowStateMachine,
+	context: PhaseGuardContext,
+): { ready: boolean; blocking: string[] } {
+	const phase = machine.phases[machine.currentPhaseIndex];
+	if (!phase) {
+		return {
+			ready: false,
+			blocking: [`No phase at index ${machine.currentPhaseIndex}.`],
+		};
+	}
+
+	const artifactSet = new Set(context.completedArtifacts);
+	const missing = phase.inputs.filter((input) => !artifactSet.has(input));
+	return { ready: missing.length === 0, blocking: missing };
+}
+
+// ── Transitions ───────────────────────────────────────────────────────────────
+
+/** Result of a phase transition: the (potentially unchanged) machine and an optional guard result. */
+export interface TransitionResult {
+	machine: WorkflowStateMachine;
+	guardResult?: GuardResult;
+}
+
+/**
+ * Transition a phase to a new status. Returns a `TransitionResult` containing
+ * the new `WorkflowStateMachine` and an optional `guardResult` when the guard
+ * was checked.
+ *
+ * If `context` is provided and the guard fails, the machine is returned
+ * **UNCHANGED** (the phase is NOT auto-failed) along with the `guardResult`
+ * so the caller can decide what to do.
+ *
+ * For the "pending → running" transition the `startedAt` timestamp is set.
+ * For terminal transitions ("completed", "failed", "skipped") the `finishedAt` timestamp is set.
+ * On success the `currentPhaseIndex` advances to `phaseIndex` (or stays if already there).
+ */
+export function transitionPhase(
+	machine: WorkflowStateMachine,
+	phaseIndex: number,
+	status: PhaseStatus,
+	context?: PhaseGuardContext,
+): TransitionResult {
+	if (context) {
+		const check = canTransitionToPhase(machine, phaseIndex, context);
+		if (!check.allowed) {
+			// Return machine UNCHANGED with guard result — caller decides what to do
+			return { machine, guardResult: check };
+		}
+	}
+
+	const now = new Date().toISOString();
+	const phases = machine.phases.map((phase, index) => {
+		if (index !== phaseIndex) return phase;
+		return {
+			...phase,
+			status,
+			...(status === "running" && !phase.startedAt ? { startedAt: now } : {}),
+			...((status === "completed" || status === "failed" || status === "skipped") && !phase.finishedAt ? { finishedAt: now } : {}),
+		};
+	});
+
+	return {
+		machine: {
+			phases,
+			currentPhaseIndex: Math.max(machine.currentPhaseIndex, phaseIndex),
+		},
+	};
+}