pi-crew 0.8.14 → 0.9.1

package/src/runtime/goal-state-store.ts

@@ -0,0 +1,209 @@
+/**
+ * goal-state-store.ts — Persistent outer state for the autonomous goal loop (P0/P1).
+ *
+ * Spec: research-findings/goal-workflow/00-SPEC.md §2.3
+ * Plan: research-findings/goal-workflow/07-PLAN.md v3 §0b G2 (one manifest per turn,
+ * goal loop owns OUTER state) + §0c C10 (hardening: assertSafePathId + UUID goalId).
+ *
+ * Stores GoalLoopState as atomic JSON at <crewRoot>/state/goals/<goalId>.json.
+ * Modeled on ScheduleStore (state/schedule.ts:86) but with atomicWriteJson +
+ * path-traversal defense (assertSafePathId on every public method).
+ *
+ * Per §0c C2: budget lives here (budgetUsed accumulates collectRunMetrics across turns);
+ * per-turn usage stays on each turn's TeamRunManifest/tasks.json.
+ */
+
+import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, unlinkSync, openSync, closeSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { assertSafePathId } from "../utils/safe-paths.ts";
+import { createRunId } from "../utils/ids.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import type { GoalLoopState, GoalLoopStatus } from "../state/types.ts";
+
+/** Default state-root resolver: project scope if a project crew-root exists, else user scope. */
+function resolveGoalsRoot(cwd: string): string {
+	const crewRoot = projectCrewRoot(cwd) ?? userCrewRoot();
+	return `${crewRoot}/state/goals`;
+}
+
+/** Goal file path for a goalId. Asserts the id is path-safe (§0c C10). */
+function goalFilePath(cwd: string, goalId: string): string {
+	assertSafePathId("goalId", goalId);
+	return `${resolveGoalsRoot(cwd)}/${goalId}.json`;
+}
+
+/**
+ * GoalStore — CRUD for GoalLoopState files.
+ *
+ * Concurrency: writes are atomic (temp+rename+fsync via atomicWriteJson). For
+ * read-modify-write sequences under contention, callers should coordinate via
+ * GoalLoopState.state transitions (cooperative, the goal loop is single-writer
+ * between turns). There is no file-lock here because the loop is the sole writer
+ * during its lifetime; `goal stop`/`pause`/`resume` from another session flip
+ * state fields that the loop checks between turns (cooperative, §0c C11).
+ */
+export class GoalStore {
+	private readonly cwd: string;
+
+	constructor(cwd: string) {
+		this.cwd = cwd;
+	}
+
+	/** Generate a fresh, path-safe goalId (never user-derived — §0c C10). */
+	createGoalId(): string {
+		return createRunId("goal");
+	}
+
+	/** Load a goal by id. Returns undefined if missing/corrupt. Throws on unsafe goalId (§0c C10). */
+	load(goalId: string): GoalLoopState | undefined {
+		// Path-safety check runs BEFORE the try/catch so traversal attempts throw (not silently return undefined).
+		const path = goalFilePath(this.cwd, goalId);
+		try {
+			if (!existsSync(path)) return undefined;
+			const raw = readFileSync(path, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || typeof parsed.goalId !== "string") return undefined;
+			return parsed as GoalLoopState;
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Atomically persist a goal state. Emits a goal.state_changed event if eventsPath given. */
+	save(state: GoalLoopState, eventsPath?: string): void {
+		assertSafePathId("goalId", state.goalId);
+		const path = goalFilePath(this.cwd, state.goalId);
+		const next = { ...state, updatedAt: new Date().toISOString() };
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			atomicWriteJson(path, next);
+			if (eventsPath) {
+				appendEvent(eventsPath, { type: "goal.state_changed", runId: state.goalId, data: { goalId: state.goalId, state: state.state } });
+			}
+		} catch (error) {
+			logInternalError("goal-state-store.save", error, `goalId=${state.goalId}`);
+			throw error;
+		}
+	}
+
+	/** Patch a goal's top-level fields (e.g. state, turnsUsed, budgetUsed, currentRunId). */
+	patch(goalId: string, patch: Partial<GoalLoopState>, eventsPath?: string): GoalLoopState | undefined {
+		const current = this.load(goalId);
+		if (!current) return undefined;
+		const next: GoalLoopState = { ...current, ...patch, goalId: current.goalId, createdAt: current.createdAt };
+		this.save(next, eventsPath);
+		return next;
+	}
+
+	/** Convenience: transition state with optional event emission. */
+	setStatus(goalId: string, state: GoalLoopStatus, eventsPath?: string): GoalLoopState | undefined {
+		return this.patch(goalId, { state }, eventsPath);
+	}
+
+	/**
+	 * Compare-And-Set status for atomic stuck↔resume transitions (P1b, RFC v0.5 §P1b).
+	 *
+	 * Loads current state; if `current.state === expected`, sets it to `next`,
+	 * persists, and emits a `goal.state_changed` event (reusing the save()
+	 * emission pattern). Otherwise returns undefined (CAS failed — no mutation,
+	 * no event). This prevents lost updates when the background loop and a
+	 * `goal resume`/idle-sweeper session race to flip `state`.
+	 *
+	 * Legal P1b transitions enforced by callers (not by this method):
+	 *   running → stuck,  stuck → running,  stuck → cancelled.
+	 */
+	/**
+	 * Cross-process-safe compare-and-set (cold-review #2 HIGH #2 fix).
+	 *
+	 * The synchronous read-check-write is only atomic within one event loop. `goal resume` runs
+	 * in a DIFFERENT process than the (exited) loop, so two concurrent resumes both see
+	 * `stuck`, both pass the CAS, both spawn → double background loops, double budget burn.
+	 *
+	 * Fix: wrap the read-modify-write in an O_EXCL lockfile per goalId. O_EXCL is atomic at the
+	 * OS level — only one process can create the lockfile. The operation is fast (ms), so stale
+	 * lockfiles are rare; a 5s age guard force-clears them (crash recovery).
+	 */
+	compareAndSetStatus(
+		goalId: string,
+		expected: GoalLoopStatus,
+		next: GoalLoopStatus,
+		eventsPath?: string,
+	): GoalLoopState | undefined {
+		const lockPath = `${goalFilePath(this.cwd, goalId)}.cas.lock`;
+		if (!this.acquireCasLock(lockPath)) {
+			return undefined; // Another process holds the CAS lock — caller treats as CAS-failed.
+		}
+		try {
+			const current = this.load(goalId);
+			if (!current) return undefined;
+			if (current.state !== expected) return undefined; // CAS failed — state moved underneath us.
+			const updated: GoalLoopState = { ...current, state: next };
+			this.save(updated, eventsPath);
+			return updated;
+		} finally {
+			try { unlinkSync(lockPath); } catch { /* best-effort; may already be gone */ }
+		}
+	}
+
+	/** Acquire an O_EXCL lockfile for CAS, with stale-lock recovery (5s age guard). */
+	private acquireCasLock(lockPath: string): boolean {
+		try {
+			const fd = openSync(lockPath, "wx"); // O_EXCL — throws EEXIST if already exists.
+			closeSync(fd);
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") return false;
+			// Stale recovery: if the lockfile is older than 5s, force-delete and retry once.
+			try {
+				const stat = statSync(lockPath);
+				if (Date.now() - stat.mtimeMs > 5000) {
+					unlinkSync(lockPath);
+				const fd = openSync(lockPath, "wx");
+				closeSync(fd);
+				return true;
+			}
+			} catch { /* fall through */ }
+			return false;
+		}
+	}
+
+	/** Remove a goal file (used by `goal clear`). Returns true if deleted. */
+	remove(goalId: string): boolean {
+		try {
+			const path = goalFilePath(this.cwd, goalId);
+			if (!existsSync(path)) return false;
+			unlinkSync(path);
+			return true;
+		} catch (error) {
+			logInternalError("goal-state-store.remove", error, `goalId=${goalId}`);
+			return false;
+		}
+	}
+
+	/** List all known goals (newest first by updatedAt). */
+	list(): GoalLoopState[] {
+		try {
+			const root = resolveGoalsRoot(this.cwd);
+			if (!existsSync(root)) return [];
+			const entries = readdirSync(root) as string[];
+			const goals: GoalLoopState[] = [];
+			for (const entry of entries) {
+				if (!entry.endsWith(".json")) continue;
+				const goalId = entry.slice(0, -".json".length);
+				// Skip entries that fail the safe-id check (defensive; createGoalId always produces safe ids).
+				if (!/^[A-Za-z0-9_-]+$/.test(goalId)) continue;
+				const g = this.load(goalId);
+				if (g) goals.push(g);
+			}
+			goals.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+			return goals;
+		} catch (error) {
+			logInternalError("goal-state-store.list", error, `cwd=${this.cwd}`);
+			return [];
+		}
+	}
+}

package/src/runtime/iteration-hooks.ts

@@ -7,6 +7,7 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { resolveShellForScript } from "../utils/resolve-shell.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { DENIED_METRIC_NAMES } from "./metric-parser.ts";
@@ -171,7 +172,7 @@ export async function runIterationHook(
 		const { command, args } = resolveShellForScript(resolvedScript);
 		const child = spawn(command, args, {
 			cwd: payload.cwd,
-			env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_CREW_*"] }), PI_CREW_HOOK: "1" },
+			env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", ...WINDOWS_ESSENTIAL_ENV_VARS, "TMPDIR", "LANG", "LC_ALL", "PI_CREW_*"] }), PI_CREW_HOOK: "1" },
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 

package/src/runtime/pi-args.ts

@@ -269,8 +269,16 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	const explicitTools = policy.tools;
 	const excludeTools = policy.excludeTools;
 
-	if (explicitTools?.length) args.push("--tools", explicitTools.join(","));
-	if (excludeTools?.length) args.push("--exclude-tools", excludeTools.join(","));
+	// §0c C6: agent.disableTools (Pi `--no-tools`) fully disables all tools. Used by
+	// capability-locked agents (e.g. the goal-judge) that must have NO agency.
+	// MUST come before any --tools/--exclude-tools so it wins (Pi applies last-wins).
+	// An empty `tools:[]` is INSUFFICIENT because the length-check below skips it.
+	if (input.agent.disableTools === true) {
+		args.push("--no-tools");
+	} else {
+		if (explicitTools?.length) args.push("--tools", explicitTools.join(","));
+		if (excludeTools?.length) args.push("--exclude-tools", excludeTools.join(","));
+	}
 	// Always add --no-extensions before --extension to prevent user extensions from being auto-loaded.
 	// User extensions in ~/.pi/agent/extensions/ may fail due to missing dependencies.
 	args.push("--no-extensions");

package/src/runtime/post-checks.ts

@@ -6,6 +6,7 @@
  */
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { resolveShellForScript } from "../utils/resolve-shell.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 
@@ -94,7 +95,7 @@ export async function runPostCheck(config: PostCheckConfig, cwd: string): Promis
 				timeout: timeoutMs,
 				encoding: "utf-8",
 				maxBuffer: 10 * 1024 * 1024, // 10 MB
-				env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_CREW_*"] }), PI_CREW_POST_CHECK: "1" },
+				env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", ...WINDOWS_ESSENTIAL_ENV_VARS, "TMPDIR", "LANG", "LC_ALL", "PI_CREW_*"] }), PI_CREW_POST_CHECK: "1" },
 			});
 
 			const durationMs = Date.now() - startTime;

package/src/runtime/result-extractor.ts

@@ -41,6 +41,14 @@ export function extractStructuredResult(raw: string, _schema?: Record<string, un
 		return { structured: true, data: markerResult, rawText: raw };
 	}
 
+	// Strategy 4: Scan for the first JSON object/array anywhere in text.
+	// Models often add prose preamble/epilogue ("Here's my review:", "Let me analyze...")
+	// around the JSON. This catches JSON embedded in sentences, lists, or prose.
+	const scannedResult = tryScanJson(trimmed);
+	if (scannedResult !== undefined) {
+		return { structured: true, data: scannedResult, rawText: raw };
+	}
+
 	return { structured: false, data: null, rawText: raw };
 }
 
@@ -63,6 +71,30 @@ function tryFencedJson(text: string): unknown | undefined {
 	}
 }
 
+/**
+ * Strategy 4: Scan for the first balanced JSON object/array anywhere in text.
+ * Robust against prose preamble/epilogue that models add around JSON output.
+ * Returns the first valid JSON value found, or undefined.
+ */
+function tryScanJson(text: string): unknown | undefined {
+	// Find the first '{' or '[' in the text.
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (ch !== "{" && ch !== "[") continue;
+		const rest = text.slice(i);
+		const end = findMatchingBracket(rest);
+		if (end <= 0) continue;
+		const candidate = rest.slice(0, end);
+		try {
+			return JSON.parse(candidate);
+		} catch {
+			// Not valid JSON at this position; keep scanning for the next '{'/'['.
+			continue;
+		}
+	}
+	return undefined;
+}
+
 function tryMarkerExtraction(text: string): unknown | undefined {
 	// Try to find JSON after common markers
 	const markers = ["RESULT:", "OUTPUT:", "ANSWER:", "### Result\n", "## Output\n"];

package/src/runtime/team-runner.ts

@@ -408,9 +408,19 @@ export function hasPendingMutatingTaskAtBoundary(tasks: TeamTaskState[]): boolea
 function dagReadyTaskIds(tasks: TeamTaskState[], completedIds: Set<string>): string[] | null {
 	const hasExplicitDeps = tasks.some((t) => t.dependsOn.length > 0);
 	if (!hasExplicitDeps) return null;
+	// FIX (goal-wrap runtime test): task.dependsOn stores STEP IDs (e.g. "execute"), not
+	// task IDs (e.g. "02_execute"). The DAG scheduler compares deps against completedIds
+	// (which are task IDs), so step-ID deps would never match → dependent tasks stuck blocked
+	// forever. Map step IDs -> task IDs first (mirror dependencySatisfied in
+	// task-graph-scheduler.ts which handles this via stepToTaskId). buildDagExecutionPlan +
+	// getDagReadyTasks then work on consistent task IDs.
+	const stepToTaskId = new Map<string, string>();
+	for (const t of tasks) {
+		if (t.stepId) stepToTaskId.set(t.stepId, t.id);
+	}
 	const nodes: TaskNode[] = tasks.map((t) => ({
 		id: t.id,
-		dependsOn: t.dependsOn,
+		dependsOn: t.dependsOn.map((dep) => stepToTaskId.get(dep) ?? dep),
 		phase: t.adaptive?.phase ?? t.stepId,
 	}));
 	const plan = buildDagExecutionPlan(nodes);

package/src/runtime/verification-gates.ts

@@ -12,9 +12,77 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
+import { redactSecretString } from "../utils/redaction.ts";
+import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import type { VerificationContract, VerificationCommandResult, GreenLevel, ArtifactDescriptor } from "../state/types.ts";
 
+/**
+ * Phase 1.5 #1 (RFC 13 §6 info-disclosure mitigation): sanitize the env passed
+ * to verification commands so worker-induced output cannot leak model-provider
+ * secrets. P1f redaction at artifact-write + judge-bound is regex-best-effort
+ * against adversarial workers; this kills the leak at the source by never
+ * giving the verification process the secret in the first place.
+ *
+ * Opt-in via `PI_CREW_VERIFICATION_SANITIZE_ENV=1` to avoid breaking existing
+ * flows whose tests legitimately need API access. Escape hatch:
+ * `PI_CREW_VERIFICATION_PRESERVE_ENV=KEY1,KEY2,...` lets users explicitly opt
+ * specific secrets back in (audited via the allowlist validator).
+ */
+const VERIFICATION_ENV_ALLOWLIST: readonly string[] = [
+	// Essential non-secret vars only — NO model-provider keys by default.
+	"PATH",
+	"HOME",
+	"USER",
+	"SHELL",
+	"TERM",
+	"LANG",
+	"LC_ALL",
+	"LC_COLLATE",
+	"LC_CTYPE",
+	"LC_MESSAGES",
+	"LC_MONETARY",
+	"LC_NUMERIC",
+	"LC_TIME",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_CACHE_HOME",
+	"XDG_RUNTIME_DIR",
+	// Windows essentials — see WINDOWS_ESSENTIAL_ENV_VARS (src/utils/env-allowlist.ts).
+	...WINDOWS_ESSENTIAL_ENV_VARS,
+	"NVM_BIN",
+	"NVM_DIR",
+	"NVM_INC",
+	"NODE_PATH",
+	"NODE_DISABLE_COLORS",
+	"NODE_EXTRA_CA_CERTS",
+	"NPM_CONFIG_REGISTRY",
+	"NPM_CONFIG_USERCONFIG",
+	"NPM_CONFIG_GLOBALCONFIG",
+];
+
+/** Whether env sanitization for verification is enabled (env var opt-in). */
+export function isVerificationEnvSanitizeEnabled(): boolean {
+	return process.env.PI_CREW_VERIFICATION_SANITIZE_ENV === "1" || process.env.PI_TEAMS_VERIFICATION_SANITIZE_ENV === "1";
+}
+
+/**
+ * Build the env dict for a verification command. When sanitization is enabled,
+ * strips everything except VERIFICATION_ENV_ALLOWLIST + any explicitly-preserved
+ * keys (PI_CREW_VERIFICATION_PRESERVE_ENV=KEY1,KEY2). Always adds FORCE_COLOR=0
+ * to keep output plain-text (matches pre-existing behavior).
+ */
+function buildVerificationEnv(): Record<string, string> {
+	if (!isVerificationEnvSanitizeEnabled()) {
+		return { ...process.env, FORCE_COLOR: "0" };
+	}
+	const preserveRaw = process.env.PI_CREW_VERIFICATION_PRESERVE_ENV ?? process.env.PI_TEAMS_VERIFICATION_PRESERVE_ENV ?? "";
+	const preserve = preserveRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	const allowList = [...VERIFICATION_ENV_ALLOWLIST, ...preserve];
+	return { ...sanitizeEnvSecrets(process.env, { allowList }), FORCE_COLOR: "0" };
+}
+
 export interface PhaseGateResult {
 	phase: number;
 	name: string;
@@ -116,7 +184,7 @@ async function executeCommand(
 		const shell = spawn("sh", ["-c", command], {
 			cwd,
 			timeout: timeoutMs,
-			env: { ...process.env, FORCE_COLOR: "0" },
+			env: buildVerificationEnv(),
 		});
 
 		shell.stdout?.on("data", (data) => {
@@ -249,6 +317,11 @@ export async function executeVerificationCommands(
 	taskId: string,
 	artifactsRoot: string,
 	signal?: AbortSignal,
+	/** Phase 1.5 #2 (RFC 16): when provided, run verification commands in this
+	 *  pristine git-worktree path instead of `cwd`. The caller is responsible
+	 *  for preparing + cleaning up the worktree (see verification-worktree.ts).
+	 *  When undefined, behavior is unchanged (run in `cwd`). */
+	worktreeCwd?: string,
 ): Promise<VerificationCommandResult[]> {
 	if (!contract.commands || contract.commands.length === 0) {
 		return [];
@@ -269,8 +342,17 @@ export async function executeVerificationCommands(
 		fs.mkdirSync(gatesDir, { recursive: true });
 	}
 
+	// Phase 1.5 #2: run phase gates inside the worktree when provided.
+	const execCwd = worktreeCwd ?? cwd;
+
 	// Run phase gates
-	const bundle = await runPhaseGates(gates, cwd, signal, (phaseResult) => {
+	const bundle = await runPhaseGates(gates, execCwd, signal, (phaseResult) => {
+		// P1f: redact secrets from verification output BEFORE persisting to the
+		// world-readable artifact file. redactSecretString is best-effort vs
+		// adversarial workers (RFC §6 — Med-High residual). writeArtifact ALSO
+		// redacts (defense-in-depth); this explicit pass sanitizes the raw output
+		// at the source so the in-memory bundle and the summary below are clean.
+		const safeOutput = redactSecretString(phaseResult.output || "");
 		// Write phase artifact immediately for observability
 		const phaseArtifact = writeArtifact(artifactsRoot, {
 			kind: "log",
@@ -284,7 +366,7 @@ export async function executeVerificationCommands(
 				phaseResult.error ? `Error: ${phaseResult.error}` : "",
 				"",
 				"## Output",
-				phaseResult.output || "(no output)",
+				safeOutput || "(no output)",
 			].join("\n"),
 			producer: taskId,
 		});
@@ -297,11 +379,12 @@ export async function executeVerificationCommands(
 		});
 	});
 
-	// Write summary artifact
+	// Write summary artifact. Redact the whole bundle JSON (it embeds the raw
+	// per-phase output strings) BEFORE writeArtifact persists it.
 	const summaryArtifact = writeArtifact(artifactsRoot, {
 		kind: "metadata",
 		relativePath: `verification-gates/${taskId}-summary.json`,
-		content: JSON.stringify(bundle, null, 2),
+		content: redactSecretString(JSON.stringify(bundle, null, 2)),
 		producer: taskId,
 	});
 

package/src/runtime/verification-integrity.ts

@@ -0,0 +1,110 @@
+/**
+ * Verification Integrity — manifest bookend snapshot helper (RFC §P1a).
+ *
+ * Hashes a FIXED set of project-manifest files so the goal loop can detect
+ * drift between T_snap (before verification runs) and T_verify_done (after the
+ * command exits). This closes the PERSISTENT-edit subcase of workspace
+ * tampering (a worker that rewrites package.json / lockfile and leaves it
+ * changed). See RFC §P1a / §6 STRIDE for the full threat model.
+ *
+ * RESIDUALS (documented; closed by Phase 1.5 git-worktree sandbox, NOT here):
+ *  - Round-trip tamper: a worker can edit a manifest, run the test, then REVERT
+ *    before T_verify_done so the hash matches T_snap. Content-addressed
+ *    execution (git-worktree) is required to close this. Not fixable by hashing.
+ *  - Invoked-script tampering: only the manifest files in MANIFEST_FILES are
+ *    hashed. A worker that overwrites a script the verification command invokes
+ *    is NOT caught. Phase 1.5 git-worktree closes this.
+ *  - node_modules/ and transitive deps are deliberately NOT hashed (size +
+ *    churn); package-lock.json IS hashed, which transitively pins resolved
+ *    dependency versions.
+ *
+ * Pure leaf module: depends only on node: built-ins. Does NOT import
+ * goal-loop-runner or goal-evaluator (keeps the P1a helper unit-testable in
+ * isolation and avoids pulling the conflict-zone modules into this file).
+ *
+ * @module verification-integrity
+ */
+
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Fixed set of project-manifest files considered by {@link snapshotManifests}.
+ * Only files from this set that EXIST in the target directory are hashed.
+ * (RFC §P1a: package.json, package-lock.json, pyproject.toml, setup.py,
+ * Cargo.toml, Cargo.lock, go.mod, tsconfig.json.)
+ */
+export const MANIFEST_FILES = [
+	"package.json",
+	"package-lock.json",
+	"pyproject.toml",
+	"setup.py",
+	"Cargo.toml",
+	"Cargo.lock",
+	"go.mod",
+	"tsconfig.json",
+] as const;
+
+/**
+ * sha256-hash the manifest files from the fixed set that EXIST in `cwd`.
+ *
+ * - Missing files are SKIPPED silently (not errors): a Python project has no
+ *   package.json, a JS project has no Cargo.toml, etc.
+ * - Non-regular files (directories, etc.) are skipped.
+ * - node_modules is NEVER hashed.
+ *
+ * @returns A map of relative manifest path -> sha256 hex digest for each
+ * present file. Stable key order = MANIFEST_FILES order (insertion order).
+ */
+export function snapshotManifests(cwd: string): Record<string, string> {
+	const snapshot: Record<string, string> = {};
+	for (const rel of MANIFEST_FILES) {
+		const abs = path.join(cwd, rel);
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(abs);
+		} catch {
+			continue; // missing file — skip gracefully
+		}
+		if (!stat.isFile()) continue; // directory / special — skip
+		try {
+			const content = fs.readFileSync(abs);
+			snapshot[rel] = createHash("sha256").update(content).digest("hex");
+		} catch {
+			continue; // unreadable (permissions/race) — skip gracefully
+		}
+	}
+	return snapshot;
+}
+
+/**
+ * Compare two snapshots and return the list of DRIFTED file paths.
+ *
+ * A file is considered drifted if:
+ *  - its hash differs between `a` and `b`, OR
+ *  - it is present in only one of the two snapshots (added or removed).
+ *
+ * @returns Sorted array of relative manifest paths that drifted. Identical
+ * snapshots yield `[]`.
+ */
+export function compareSnapshot(
+	a: Record<string, string>,
+	b: Record<string, string>,
+): string[] {
+	const drifted = new Set<string>();
+	for (const [key, hash] of Object.entries(a)) {
+		const other = b[key];
+		if (other === undefined) {
+			drifted.add(key); // removed between a -> b
+		} else if (other !== hash) {
+			drifted.add(key); // content changed
+		}
+	}
+	for (const key of Object.keys(b)) {
+		if (a[key] === undefined) {
+			drifted.add(key); // added between a -> b
+		}
+	}
+	return [...drifted].sort();
+}