pi-crew 0.8.14 → 0.9.1

package/src/runtime/verification-worktree.ts

@@ -0,0 +1,136 @@
+/**
+ * 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/workspace-lock.ts

@@ -0,0 +1,448 @@
+/**
+ * workspace-lock.ts — Per-cwd workspace lock with startTime-safe liveness (P1g).
+ *
+ * RFC: research-findings/goal-workflow/13-VISION-RFC.md v0.5 §P1g + D10.
+ *
+ * Closes #8 (multi-goal clobber) and the B-2 PID-recycling gap. Each
+ * `workspaceMode:"single"` goal acquires this lock for its entire lifetime,
+ * serializing concurrent goals that share a cwd.
+ *
+ * Lockfile location: `<crewRoot>/state/workspace-locks/<sha256(absCwd)>.lock`
+ * Lockfile contents: { pid, startTime, heartbeat, goalId, acquiredAt }
+ *
+ * ─── LIVENESS = stale-reconciler startTime pattern (D10, B-2 fix) ───
+ * A lock is STALE iff EITHER:
+ *   (a) the recorded pid's CURRENT startTime ≠ the lockfile startTime
+ *       (the PID was recycled to a different process), OR
+ *   (b) the heartbeat is older than HEARTBEAT_STALE_MS (default 60s)
+ *       (the process crashed without exiting / heartbeat stopped).
+ *
+ * Why NOT child-pi.ts killProcessPid (B-2): killProcessPid uses
+ * process.kill(pid, 0) which is PID-only — vulnerable to PID recycling. The
+ * startTime + before/after re-verify pattern is TOCTOU-correct.
+ *
+ * getProcessStartTime is NOT exported from stale-reconciler.ts, so its logic
+ * is REPLICATED here (RFC §P1g explicitly permits importing OR replicating).
+ * The replication matches stale-reconciler.ts:112 field-for-field.
+ *
+ * Granularity: per-goal, held for the goal's lifetime (release() on goal end).
+ * Contention: default QUEUE (poll until released or stale);
+ *             opts.failOnWorkspaceBusy:true → THROW instead of queue.
+ */
+
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	unlinkSync,
+	openSync,
+	closeSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+
+/** Heartbeat staleness threshold (ms). Default 60s per RFC §P1g. */
+const DEFAULT_HEARTBEAT_STALE_MS = 60_000;
+
+/** Polling interval while queued waiting for a held lock (ms). */
+const DEFAULT_LOCK_POLL_MS = 500;
+
+/**
+ * Resolve a pid's process start time in ms, reusing the stale-reconciler
+ * pattern (src/runtime/stale-reconciler.ts:112). Returns undefined if the
+ * process is gone or /proc is unavailable (non-Linux). The absolute value
+ * matters less than its uniqueness per PID lifecycle. Used to detect PID
+ * recycling: a recycled PID has a different startTime than the recorded one.
+ *
+ * Callers (esp. tests) may inject a custom resolver to simulate PID recycling
+ * deterministically without spawning real processes.
+ */
+export type StartTimeResolver = (pid: number) => number | undefined;
+
+export const defaultStartTimeResolver: StartTimeResolver = (pid: number): number | undefined => {
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const lastParen = stat.lastIndexOf(")");
+		if (lastParen === -1) return undefined;
+		const fieldsAfterComm = stat.slice(lastParen + 1).trim().split(/\s+/);
+		// starttime is at index 19 (the 20th field after comm) of /proc/<pid>/stat.
+		const startTimeClockTicks = Number(fieldsAfterComm[19]);
+		if (!Number.isFinite(startTimeClockTicks)) return undefined;
+		// Convert clock ticks to ms (~CLK_TCK). Absolute uniqueness is what matters.
+		return Math.floor(startTimeClockTicks * 10);
+	} catch {
+		return undefined;
+	}
+};
+
+/** Lockfile contents (persisted as JSON). */
+export interface WorkspaceLockContents {
+	pid: number;
+	startTime: number | undefined;
+	heartbeat: number;
+	goalId: string;
+	acquiredAt: string;
+}
+
+/**
+ * Opaque handle returned by acquireWorkspaceLock. Call release() to free the
+ * lock when the goal ends. release() is a no-op if the lock was already
+ * reclaimed/re-acquired by another goal (guarded by goalId + pid + startTime).
+ */
+export interface WorkspaceLockHandle {
+	readonly cwd: string;
+	readonly goalId: string;
+	readonly lockPath: string;
+	/** The startTime value written to the lockfile at acquire (release guard). */
+	readonly startTime: number | undefined;
+	release(): void;
+}
+
+export interface AcquireWorkspaceLockOptions {
+	/** Throw instead of queue when the workspace is already held (default: queue). */
+	failOnWorkspaceBusy?: boolean;
+	/** Override the heartbeat-staleness threshold (ms). */
+	heartbeatStaleMs?: number;
+	/** Override the polling interval while queued (ms). */
+	pollMs?: number;
+	/** Test injection: override process start time resolution. */
+	startTimeResolver?: StartTimeResolver;
+	/** Test injection: override current time (ms). Default Date.now(). */
+	now?: () => number;
+	/** Test injection: override the current pid. Default process.pid. */
+	pid?: number;
+	/** Abort waiting when this signal aborts. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Resolve the lockfile path for a cwd. Lockfiles live under the project's
+ * `.crew/state/workspace-locks/` (or user crew-root fallback) and are named by
+ * the sha256 of the absolute cwd to avoid filesystem-unsafe characters and to
+ * normalize symlink-equivalent paths.
+ */
+export function workspaceLockPath(cwd: string): string {
+	const absCwd = path.resolve(cwd);
+	const crewRoot = projectCrewRoot(absCwd) ?? userCrewRoot();
+	const locksDir = path.join(crewRoot, "state", "workspace-locks");
+	const hash = createHash("sha256").update(absCwd).digest("hex");
+	return path.join(locksDir, `${hash}.lock`);
+}
+
+/** Read + parse a lockfile. Returns undefined if missing/corrupt. */
+function readLock(lockPath: string): WorkspaceLockContents | undefined {
+	if (!existsSync(lockPath)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(lockPath, "utf-8"));
+		if (!parsed || typeof parsed !== "object") return undefined;
+		return parsed as WorkspaceLockContents;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write the lockfile atomically (temp+rename+fsync via atomicWriteJson).
+ * Used for HEARTBEAT refresh only (a claim that already owns the lock is refreshing its
+ * timestamp — overwrite is correct because the owner verified ownership first).
+ */
+function writeLock(lockPath: string, contents: WorkspaceLockContents): void {
+	mkdirSync(path.dirname(lockPath), { recursive: true });
+	atomicWriteJson(lockPath, contents);
+}
+
+/**
+ * CLAIM the lockfile atomically via O_EXCL (cold-review #3 NIT #N1 fix).
+ * The previous claim used temp+rename (writeLock), which is NOT cross-process atomic —
+ * two goals that both observed a free lock in the same tick could both writeLock and
+ * both believe they own it (the same class of TOCTOU cold-review #2 caught for CAS).
+ * O_EXCL (openSync "wx") IS atomic at the OS level: only one process can create the
+ * file. Returns true on success, false if the file already exists (EEXIST). Stale
+ * lockfiles older than the threshold are force-deleted + retried once.
+ */
+/**
+ * CLAIM the lockfile atomically via O_EXCL (cold-review #3 NIT #N1 fix).
+ * The previous claim used temp+rename (writeLock), which is NOT cross-process atomic —
+ * two goals that both observed a free/stale lock in the same tick could both writeLock
+ * and both believe they own it (the same class of TOCTOU cold-review #2 caught for CAS).
+ * O_EXCL (openSync "wx") IS atomic at the OS level: only one process can create the file.
+ *
+ * `forceOverwrite`: when the caller has ALREADY verified (via isLockStale) that the existing
+ * lock is logically stale (e.g. PID recycled — a stronger signal than mtime age), the caller
+ * passes forceOverwrite:true and claimLock unlinks then claims, bypassing the mtime age check.
+ * (Without this, a stale-by-PID-recycling lock whose mtime is recent would never be claimed,
+ *  because tryCreate sees EEXIST and the mtime age check fails — infinite re-queue = hang.)
+ *
+ * Returns true on success, false if the file already exists and is not stale.
+ */
+function claimLock(lockPath: string, contents: WorkspaceLockContents, staleReclaimMs: number, forceOverwrite = false): boolean {
+	mkdirSync(path.dirname(lockPath), { recursive: true });
+	const json = JSON.stringify(contents);
+	const tryCreate = (): boolean => {
+		try {
+			const fd = openSync(lockPath, "wx"); // O_EXCL — throws EEXIST if it exists.
+			try {
+				writeFileSync(fd, json);
+			} finally {
+				closeSync(fd);
+			}
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") throw error;
+			return false;
+		}
+	};
+	if (forceOverwrite) {
+		// Caller verified the existing lock is logically stale; remove it and claim. A concurrent
+		// reclaimer might re-create between our unlink and our open — that's fine, we lose the race
+		// and return false, falling through to the queue path.
+		try { unlinkSync(lockPath); } catch { /* best-effort */ }
+		return tryCreate();
+	}
+	if (tryCreate()) return true;
+	// Stale recovery by mtime age: if the lockfile is older than staleReclaimMs, force-delete + retry.
+	try {
+		const stat = statSync(lockPath);
+		if (Date.now() - stat.mtimeMs > staleReclaimMs) {
+			try { unlinkSync(lockPath); } catch { /* fall through */ }
+			return tryCreate();
+		}
+	} catch { /* fall through to false */ }
+	return false;
+}
+
+/**
+ * Is the lock STALE? RFC §P1g + D10 dual-check:
+ *   (a) startTime mismatch → PID recycled to a different process, OR
+ *   (b) heartbeat older than heartbeatStaleMs → crash w/o exit / abandoned.
+ *
+ * On platforms where startTime is unavailable (non-Linux), only the heartbeat
+ * check applies (weaker PID-reuse detection — documented platform limitation,
+ * matching stale-reconciler.ts).
+ */
+function isLockStale(
+	lock: WorkspaceLockContents,
+	resolveStartTime: StartTimeResolver,
+	heartbeatStaleMs: number,
+	now: number,
+): { stale: boolean; reason?: string } {
+	// (a) startTime mismatch → PID recycled to a different process.
+	if (lock.startTime !== undefined) {
+		const currentStartTime = resolveStartTime(lock.pid);
+		if (currentStartTime !== undefined && currentStartTime !== lock.startTime) {
+			return { stale: true, reason: "pid_recycled" };
+		}
+		// currentStartTime === undefined: process gone OR /proc unavailable →
+		// fall through to the heartbeat check (corroborating evidence).
+	}
+	// (b) heartbeat older than threshold → crash without exit / abandoned.
+	const heartbeatAge = now - lock.heartbeat;
+	if (heartbeatAge > heartbeatStaleMs) {
+		return { stale: true, reason: "heartbeat_stale" };
+	}
+	return { stale: false };
+}
+
+/**
+ * Acquire the workspace lock for `goalId` at `cwd`. If the lock is held by a
+ * live goal, the default behavior is QUEUE (poll until released or the holder
+ * goes stale); with opts.failOnWorkspaceBusy:true, throws instead.
+ *
+ * Stale locks (PID recycled or heartbeat expired) are reclaimed transparently.
+ *
+ * The returned handle's release() deletes the lockfile ONLY if it still
+ * belongs to this goal+pid+startTime — so a stale handle cannot clobber a
+ * lock reclaimed and re-acquired by another goal after this goal went stale.
+ *
+ * In-process serialization: the read→stale-check→write sequence is
+ * synchronous within one event-loop tick, so concurrent in-process acquires
+ * cannot both observe a free lock and both write (no interleave between the
+ * sync read and sync write).
+ */
+export async function acquireWorkspaceLock(
+	cwd: string,
+	goalId: string,
+	opts: AcquireWorkspaceLockOptions = {},
+): Promise<WorkspaceLockHandle> {
+	const lockPath = workspaceLockPath(cwd);
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const pollMs = opts.pollMs ?? DEFAULT_LOCK_POLL_MS;
+	const now = opts.now ?? Date.now;
+	const pid = opts.pid ?? process.pid;
+	const writtenStartTime = resolveStartTime(pid);
+
+	while (true) {
+		// Poll-loop: re-check the lock each tick until free/stale or aborted.
+		if (opts.signal?.aborted) {
+			throw new Error(
+				`workspace lock acquisition aborted for goal ${goalId} (cwd=${cwd})`,
+			);
+		}
+		const existing = readLock(lockPath);
+		// Classify the existing lock: "absent" / "stale" (PID recycled or heartbeat dead) / "live".
+		// Cold-review #3 NIT #N1 fix: when stale, pass forceOverwrite:true to claimLock so it
+		// unlinks the stale file before claiming. Without this, a stale-by-PID lock whose mtime
+		// is recent would never pass claimLock's mtime age check (it would return false) and the
+		// acquireWorkspaceLock poll loop would re-queue forever = hang.
+		const existingKind: "absent" | "stale" | "live" = !existing
+			? "absent"
+			: (isLockStale(existing, resolveStartTime, heartbeatStaleMs, now()).stale ? "stale" : "live");
+		if (existingKind !== "live") {
+			// Claim the lock (covers both no-lock and stale-lock cases).
+			// Cold-review #3 NIT #N1 fix: claim via O_EXCL (claimLock), NOT temp+rename — two
+			// processes racing past the isLockStale check could both writeLock and both believe
+			// they own the lock. claimLock atomically creates the file; if it returns false we
+			// lost the race, so fall through to the queue/re-throw path below.
+			const contents: WorkspaceLockContents = {
+				pid,
+				startTime: writtenStartTime,
+				heartbeat: now(),
+				goalId,
+				acquiredAt: new Date(now()).toISOString(),
+			};
+			const claimed = claimLock(lockPath, contents, heartbeatStaleMs, existingKind === "stale");
+			if (claimed) {
+				return {
+					cwd,
+					goalId,
+					lockPath,
+					startTime: writtenStartTime,
+					release(): void {
+						safeRelease(lockPath, goalId, pid, writtenStartTime);
+					},
+				};
+			}
+			// claimLock lost the race (another process claimed between our stale-check and
+			// our claim). Fall through to the busy path (throw or queue) — re-check next tick.
+		}
+		// Lock is held and live.
+		if (opts.failOnWorkspaceBusy) {
+			throw new Error(
+				`workspace busy: cwd=${cwd} held by goalId=${existing!.goalId} (pid=${existing!.pid})`,
+			);
+		}
+		// Queue: wait for the next poll interval, then re-check.
+		await sleepOrAbort(pollMs, opts.signal);
+	}
+}
+
+/**
+ * Delete the lockfile at `lockPath` only if it still belongs to
+ * (goalId, pid, startTime). A stale handle (whose lock was reclaimed and
+ * re-acquired by another goal) must NOT delete the new owner's lock.
+ */
+function safeRelease(
+	lockPath: string,
+	goalId: string,
+	pid: number,
+	writtenStartTime: number | undefined,
+): void {
+	try {
+		const current = readLock(lockPath);
+		if (
+			current &&
+			current.goalId === goalId &&
+			current.pid === pid &&
+			current.startTime === writtenStartTime
+		) {
+			unlinkSync(lockPath);
+		}
+	} catch {
+		/* best-effort — release must never throw into a finally block */
+	}
+}
+
+/** Sleep that resolves after `ms`, or rejects early if `signal` aborts. */
+function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<void> {
+	if (!signal) return new Promise<void>((r) => setTimeout(r, ms));
+	return new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(resolve, ms);
+		signal.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(new Error("workspace lock acquisition aborted"));
+			},
+			{ once: true },
+		);
+	});
+}
+
+/**
+ * Reclaim all stale locks under `dir` (the workspace-locks directory). Returns
+ * the list of reclaimed lock paths. Stale = PID recycled OR heartbeat older
+ * than threshold. Corrupt/unreadable locks are also reclaimed.
+ *
+ * Useful as a startup or periodic sweep to clear locks left by crashed
+ * processes before any goal tries to acquire them.
+ */
+/**
+ * Peek whether the workspace is currently locked by a live owner (without acquiring).
+ * Used by `goal start` / `goal resume` to fail-fast with a clear error BEFORE spawning.
+ * Returns the goalId of the current owner if busy, undefined if free (or lock missing).
+ */
+export function isWorkspaceBusy(
+	cwd: string,
+	opts: { startTimeResolver?: StartTimeResolver; heartbeatStaleMs?: number; now?: () => number } = {},
+): string | undefined {
+	const lockPath = workspaceLockPath(cwd);
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const now = opts.now ?? Date.now;
+	const existing = readLock(lockPath);
+	if (!existing) return undefined;
+	const { stale } = isLockStale(existing, resolveStartTime, heartbeatStaleMs, now());
+	return stale ? undefined : existing.goalId;
+}
+
+export function reclaimStaleLocks(
+	dir: string,
+	opts: {
+		heartbeatStaleMs?: number;
+		startTimeResolver?: StartTimeResolver;
+		now?: () => number;
+	} = {},
+): string[] {
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const now = opts.now ?? Date.now;
+	const reclaimed: string[] = [];
+	if (!existsSync(dir)) return reclaimed;
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return reclaimed;
+	}
+	for (const entry of entries) {
+		if (!entry.endsWith(".lock")) continue;
+		const lockPath = path.join(dir, entry);
+		const lock = readLock(lockPath);
+		if (!lock) {
+			// Corrupt/empty — reclaim.
+			try {
+				unlinkSync(lockPath);
+				reclaimed.push(lockPath);
+			} catch {
+				/* best-effort */
+			}
+			continue;
+		}
+		if (isLockStale(lock, resolveStartTime, heartbeatStaleMs, now()).stale) {
+			try {
+				unlinkSync(lockPath);
+				reclaimed.push(lockPath);
+			} catch {
+				/* best-effort */
+			}
+		}
+	}
+	return reclaimed;
+}

package/src/schema/config-schema.ts

@@ -59,6 +59,31 @@ export const PiTeamsWorktreeConfigSchema = Type.Object({
 	seedPaths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 }, { additionalProperties: false });
 
+/**
+ * Goal-wrap config (RFC v0.5 vision: apply `goal` completion-guarantee to builtin workflows).
+ * Per-workflow toggle. When enabled, a builtin workflow runs as the WORKER TURN inside a
+ * goal loop (worker → judge → feedback → redo until achieved / maxTurns / budget / stuck).
+ * Default OFF — opt-in per workflow. Only applies to builtin workflows that have a clear
+ * 'done' condition (implementation, fast-fix). Read-only workflows (review, research) are
+ * not goal-wrappable.
+ */
+export const GoalWrapWorkflowConfigSchema = Type.Object({
+	enabled: Type.Optional(Type.Boolean()),
+	maxTurns: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+	evaluatorModel: Type.Optional(Type.String({ minLength: 1 })),
+	verification: Type.Optional(Type.Object({
+		commands: Type.Array(Type.String({ minLength: 1 })),
+		mode: Type.Optional(Type.Literal("text-only")),
+	}, { additionalProperties: false })),
+	budgetTotal: Type.Optional(Type.Integer({ minimum: 1000 })),
+	budgetUnlimited: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+export const PiTeamsGoalWrapConfigSchema = Type.Record(
+	Type.String({ minLength: 1 }),
+	GoalWrapWorkflowConfigSchema,
+);
+
 export const AgentOverrideSchema = Type.Object({
 	disabled: Type.Optional(Type.Boolean()),
 	model: Type.Optional(Type.Union([Type.String({ minLength: 1 }), Type.Literal(false)])),
@@ -152,6 +177,7 @@ export const PiTeamsConfigSchema = Type.Object({
 	runtime: Type.Optional(PiTeamsRuntimeConfigSchema),
 	control: Type.Optional(PiTeamsControlConfigSchema),
 	worktree: Type.Optional(PiTeamsWorktreeConfigSchema),
+	goalWrap: Type.Optional(PiTeamsGoalWrapConfigSchema),
 	agents: Type.Optional(PiTeamsAgentsConfigSchema),
 	tools: Type.Optional(PiTeamsToolsConfigSchema),
 	telemetry: Type.Optional(PiTeamsTelemetryConfigSchema),