opencode-workflow-guard 1.13.6 → 1.14.1

package/src/lib/verify.ts

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, type Hash } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { dynamicShellSyntaxIn, normalize } from "./shell.ts";
@@ -141,6 +141,35 @@ function warnFingerprintSkip(root: string, file: string, detail: string): void {
 	} catch {}
 }
 
+/**
+ * Content hash over tracked repository content only: the index listing
+ * (staged/tracked blob hashes) plus the worktree-vs-index diff (unstaged
+ * edits). Review evidence binds to this fingerprint, not to the full one:
+ * untracked scratch files are not part of the reviewed diff, so creating,
+ * modifying, or deleting them must never invalidate a recorded approval.
+ */
+function trackedContentHash(root: string): Hash | undefined {
+	const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	if (staged.status !== 0 || unstaged.status !== 0) return undefined;
+	return createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+}
+
+export function getTrackedWorktreeFingerprint(root: string): string | undefined {
+	try {
+		return trackedContentHash(root)?.digest("hex");
+	} catch {}
+	return undefined;
+}
+
 export function getGitWorktreeFingerprint(root: string): string | undefined {
 	try {
 		// Index listing captures the exact staged/tracked content (blob hashes);
@@ -148,23 +177,14 @@ export function getGitWorktreeFingerprint(root: string): string | undefined {
 		// contents cover files git does not yet track. Together these bind the
 		// fingerprint to file contents regardless of whether HEAD exists, so
 		// freshly initialized (commitless) repositories are covered too.
-		const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
+		const hash = trackedContentHash(root);
+		if (!hash) return undefined;
 		const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
 		});
-		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
-		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+		if (untracked.status !== 0) return undefined;
 		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
 			// The path itself is always part of the fingerprint, so a skipped
 			// entry still binds its presence even when its contents do not.

package/src/lib/worktree.ts

@@ -1,5 +1,5 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, symlinkSync } from "node:fs";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve, sep } from "node:path";
 import { getWorkspaceRoot } from "./state.ts";
@@ -63,6 +63,89 @@ function localBranchExists(branch: string, root: string): boolean {
 	return res.status === 0;
 }
 
+/**
+ * Worktree timeout: WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS env wins, then the
+ * 15s default. Large checkouts can exceed 15s; without this the killed
+ * `git worktree add` left the branch behind with only its stderr progress
+ * text as the reported reason.
+ */
+export function resolveWorktreeTimeoutMs(): number {
+	const envValue = Number(process.env.WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS);
+	return Number.isFinite(envValue) && envValue > 0 ? envValue : 15_000;
+}
+
+/** git exit status is the failure signal; stderr is only context (progress lines land there too). */
+function describeGitFailure(operation: string, res: SpawnSyncReturns<string>): string {
+	const status = res.status === null
+		? `null (killed${res.signal ? ` via ${res.signal}` : ""}${res.error ? `: ${res.error.message}` : ""})`
+		: String(res.status);
+	const stderrTail = (res.stderr ?? "").trim().split("\n").filter(Boolean).slice(-3).join("; ");
+	return `git ${operation} failed (exit status ${status})${stderrTail ? `: ${stderrTail}` : ""}`;
+}
+
+/**
+ * Rolls back the partial state of a failed `git worktree add`. git creates
+ * the branch ref before the worktree checkout, so a failure after that point
+ * (target path collision, killed checkout, hook error) leaves a dangling
+ * branch and possibly stale worktree admin entries behind. Deletion of the
+ * branch only happens when this call created it.
+ */
+function rollbackFailedWorktreeAdd(options: { branch: string; branchCreatedByUs: boolean; targetPath: string; existedBefore: boolean; root: string }): string {
+	const { branch, branchCreatedByUs, targetPath, existedBefore, root } = options;
+	const notes: string[] = [];
+	try {
+		const registered = (registeredWorktreePaths(root) ?? []).map((path) => resolve(path));
+		const targetRegistered = registered.includes(resolve(targetPath));
+		if (targetRegistered && !existedBefore && existsSync(targetPath)) {
+			// Only a worktree this call registered may be force-removed. A
+			// pre-existing registered worktree at the same sanitized path
+			// (duplicate name, concurrent subagents, feat/x vs feat:x) is the
+			// reason the add failed - it must never be destroyed by rollback.
+			spawnSync("git", ["worktree", "remove", "--force", targetPath], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+		}
+		if (!existedBefore) {
+			// Clear stale worktree admin entries left by an interrupted add for
+			// this new path. Scoped to the new-path case so unrelated
+			// worktrees on temporarily unavailable paths are never pruned.
+			spawnSync("git", ["worktree", "prune"], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+		}
+		if (!existedBefore && existsSync(targetPath)) {
+			// git may have partially populated the directory before failing.
+			// It did not exist before this call, so removing it is safe; a
+			// pre-existing path (e.g. the reason the add failed) is left alone.
+			try { rmSync(targetPath, { recursive: true, force: true }); } catch {}
+		}
+		if (branchCreatedByUs) {
+			// After the deregistration above: a branch cannot be deleted while
+			// still checked out in a worktree.
+			const deleteRes = spawnSync("git", ["branch", "-D", branch], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (deleteRes.status !== 0) {
+				notes.push(`the created branch '${branch}' could not be rolled back and was left in place; delete it manually if it is not needed`);
+			}
+		}
+	} catch {
+		if (branchCreatedByUs) {
+			notes.push(`the created branch '${branch}' may remain; delete it manually if it is not needed`);
+		}
+	}
+	return notes.join("; ");
+}
+
 export function createGitWorktree(
 	branch: string,
 	baseBranch = "HEAD",
@@ -77,12 +160,13 @@ export function createGitWorktree(
 
 	const storageBase = getWorktreeStorageDir(root);
 	const targetPath = join(storageBase, branch.replace(/[/\\:]/g, "-"));
+	const existedBefore = existsSync(targetPath);
 
 	try {
 		mkdirSync(storageBase, { recursive: true });
 
-		const exists = localBranchExists(branch, root);
-		const gitArgs = exists
+		const branchAlreadyExisted = localBranchExists(branch, root);
+		const gitArgs = branchAlreadyExisted
 			? ["worktree", "add", targetPath, branch]
 			: ["worktree", "add", "-b", branch, targetPath, baseBranch];
 
@@ -90,10 +174,12 @@ export function createGitWorktree(
 			cwd: root,
 			env: getCleanGitEnv(),
 			encoding: "utf8",
-			timeout: 15_000,
+			timeout: resolveWorktreeTimeoutMs(),
 		});
 		if (addRes.status !== 0) {
-			return { success: false, error: addRes.stderr.trim() || `git worktree add failed` };
+			const rollbackNote = rollbackFailedWorktreeAdd({ branch, branchCreatedByUs: !branchAlreadyExisted, targetPath, existedBefore, root });
+			const error = describeGitFailure("worktree add", addRes) + (rollbackNote ? `; ${rollbackNote}` : "");
+			return { success: false, error };
 		}
 
 		// Symlink the parent's node_modules so tooling works without a fresh install.
@@ -131,16 +217,44 @@ export function cleanupGitWorktree(
 	root = getWorkspaceRoot(),
 ): { success: boolean; error?: string } {
 	try {
+		const resolved = resolve(worktreePath);
+		const storageBase = resolve(getWorktreeStorageDir(root));
 		if (!existsSync(worktreePath)) {
-			return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
+			// A registered worktree whose directory is gone (manual removal, a
+			// crashed add, external cleanup) still holds a stale admin entry that
+			// keeps it in `git worktree list` as prunable, and must still be
+			// cleanable. Anything outside storage or unregistered is refused.
+			// The primary working tree is never at risk: prune only removes
+			// admin dirs under .git/worktrees/<id>, which the main tree lacks.
+			if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
+				return {
+					success: false,
+					error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
+				};
+			}
+			const registeredMissing = registeredWorktreePaths(root);
+			if (!registeredMissing) {
+				return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
+			}
+			if (!registeredMissing.map((path) => resolve(path)).includes(resolved)) {
+				return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
+			}
+			const prune = spawnSync("git", ["worktree", "prune"], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+			if (prune.status !== 0) {
+				return { success: false, error: describeGitFailure("worktree prune", prune) };
+			}
+			return { success: true };
 		}
 
 		// Ownership validation: the path must live under the configured worktree
 		// storage directory AND be a registered worktree of this repository. This
 		// refuses arbitrary directories, other repos' worktrees, and the primary
 		// working tree - cleanup must never be an unrestricted delete primitive.
-		const resolved = resolve(worktreePath);
-		const storageBase = resolve(getWorktreeStorageDir(root));
 		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
 			return {
 				success: false,

package/src/policies/shell-safety.ts

@@ -84,23 +84,43 @@ const INTERACTIVE_COMMAND_PATTERNS: Array<{ regex: RegExp; name: string; advice:
 
 const MONITOR_ADVICE = "Use ps aux, uptime, or batch flags (e.g. top -b -n 1) instead of interactive monitors.";
 const PAGER_ADVICE = "Use cat, head, or grep with non-interactive pipes instead of interactive pagers.";
-// Process monitoring tokens are matched on whitespace/segment boundaries so that
-// an unrelated word such as `desktop`, a hyphenated filename like `top-level-dir`,
-// or a quoted argument like `echo "top"` is not mistaken for the `top` command.
-const ALWAYS_INTERACTIVE_MONITOR_RE = /(?:^|[;&|\s])(?:htop|btop|atop|glances)(?:$|[;&|\s])/i;
-const TOP_COMMAND_RE = /(?:^|[;&|\s])top(?:$|[;&|\s])/i;
+// Monitor tokens are only interactive when they are the command of a
+// segment: a `top` in an argument (a secret name, a grep pattern, `echo
+// top`) is data, not the monitor. Wrappers are stripped first, so `sudo top`
+// and `timeout 5 top` are still caught, and `eval top` / `sh -c top` recurse
+// like the pager check. `top` in batch mode stays allowed. Indirection that
+// this does not model (`watch top`, `xargs top`, `man top`, shell loop bodies
+// such as `while true; do top; done`) is a known, documented limitation.
+const INTERACTIVE_MONITORS = new Set(["top", "htop", "btop", "atop", "glances"]);
 const TOP_BATCH_FLAG_RE = /(?:^|\s)(?:--batch|-[A-Za-z]*b[A-Za-z]*)(?:\s|$)/i;
 
-function checkProcessMonitorCommand(command: string): { isInteractive: boolean; name?: string; advice?: string } {
-	for (const segment of command.split(/[;&|\n]+/)) {
-		if (ALWAYS_INTERACTIVE_MONITOR_RE.test(segment)) {
-			return { isInteractive: true, name: "interactive process monitor", advice: MONITOR_ADVICE };
+function containsMonitorCommand(command: string, depth = 0): boolean {
+	if (depth >= 16) return false;
+	for (const segment of splitShellSegments(command)) {
+		const words = unwrapShellWords(segment);
+		while (words[0] === "--") words.shift();
+		const executable = basename(words[0] ?? "").toLowerCase();
+		const candidate = executable === "busybox" ? basename(words[1] ?? "").toLowerCase() : executable;
+		if (INTERACTIVE_MONITORS.has(candidate)) {
+			// Batch mode is the monitor's own flag, not a wrapper's (e.g. `sudo -b
+			// top` backgrounds sudo; it does not put `top` in batch mode).
+			const monitorIndex = executable === candidate ? 0 : 1;
+			if (candidate === "top" && TOP_BATCH_FLAG_RE.test(words.slice(monitorIndex + 1).join(" "))) continue;
+			return true;
 		}
-		if (TOP_COMMAND_RE.test(segment) && !TOP_BATCH_FLAG_RE.test(segment)) {
-			return { isInteractive: true, name: "interactive process monitor", advice: MONITOR_ADVICE };
+		if (executable === "eval" && words.length > 1 && containsMonitorCommand(words.slice(1).join(" "), depth + 1)) return true;
+		if (/^(?:ba|z|da|k)?sh$/i.test(executable)) {
+			const commandFlag = words.findIndex((word, index) => index > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(word));
+			if (commandFlag >= 0 && words[commandFlag + 1] && containsMonitorCommand(words[commandFlag + 1]!, depth + 1)) return true;
 		}
 	}
-	return { isInteractive: false };
+	return false;
+}
+
+function checkProcessMonitorCommand(command: string): { isInteractive: boolean; name?: string; advice?: string } {
+	return containsMonitorCommand(command)
+		? { isInteractive: true, name: "interactive process monitor", advice: MONITOR_ADVICE }
+		: { isInteractive: false };
 }
 
 function containsPagerCommand(command: string, depth = 0): boolean {

package/src/policies/stale-write.ts

@@ -51,6 +51,23 @@ export function recordSuccessfulRead(observation: ReadObservation, sessionID: st
 	reads.set(sessionID, sessionReads);
 }
 
+/**
+ * Records the session's observation of a file it just mutated. A successful
+ * edit/write means the session authored the resulting bytes, so a follow-up
+ * edit to that file must not demand a redundant re-read. The pre-mutation
+ * digest is compared so a no-op or failed call (content unchanged) does not
+ * seed an observation, and an external change after the mutation still fails
+ * the next comparison.
+ */
+export function recordMutationObservation(path: string, sessionID: string, beforeDigest?: string): void {
+	const current = fingerprint(path);
+	if (!current) return;
+	if (beforeDigest !== undefined && current.digest === beforeDigest) return;
+	const sessionReads = reads.get(sessionID) ?? new Map<string, ReadFingerprint>();
+	sessionReads.set(canonicalPath(path), current);
+	reads.set(sessionID, sessionReads);
+}
+
 export function staleWriteReason(path: string, sessionID: string): string | undefined {
 	const current = fingerprint(path);
 	const canonical = canonicalPath(path);

package/src/policies/tamper.ts

@@ -1,7 +1,8 @@
 import { realpathSync } from "node:fs";
 import { basename, relative, resolve } from "node:path";
-import { getWorkspaceRoot } from "../lib/state.ts";
+import { getLiveControlPlaneRoots, getWorkspaceRoot } from "../lib/state.ts";
 import { decodeShellEscapes, prepareRedirectResidue } from "../lib/shell.ts";
+import { pathWithinAnyRoot, realpathWithinAnyRoot } from "../lib/live-control-plane.ts";
 
 export const PROTECTED_PATH_REASON =
 	"Blocked: modifying Open" +
@@ -56,19 +57,37 @@ export function isCollaborationInvocation(segment: string): boolean {
 	return COLLABORATION_INVOCATION_PATTERNS.some((re) => re.test(segment));
 }
 
-export function isSettingsTamper(command: string): boolean {
+export function isSettingsTamper(command: string, liveControlPlaneRoots?: readonly string[]): boolean {
+	// When the host declares its live control-plane roots, path-shaped tamper is
+	// decided by the mutation TARGET's runtime location (`isProtectedPath`), not
+	// by matching any operand's raw text. That stops a copy/move SOURCE under a
+	// config path from being flagged while the destination is a sanctioned draft
+	// (finding F3). The opencode CLI verb patterns still apply. Callers that scan
+	// written content (edit payloads) pass no roots and keep the legacy
+	// fail-closed path matching.
+	const factMode = liveControlPlaneRoots !== undefined && liveControlPlaneRoots.length > 0;
 	return command.split(/[\n|;&]+/).some((s) => {
 		if (isCollaborationInvocation(s)) return false;
-		const residue = normalizeGlobPathEvasion(normalizeShellEvasion(prepareRedirectResidue(s)));
 		const flattened = normalizeGlobPathEvasion(normalizeShellEvasion(s));
-		return PATH_PATTERNS.some((re) => re.test(residue)) || VERB_PATTERNS.some((re) => re.test(flattened));
+		if (VERB_PATTERNS.some((re) => re.test(flattened))) return true;
+		if (factMode) return false;
+		const residue = normalizeGlobPathEvasion(normalizeShellEvasion(prepareRedirectResidue(s)));
+		return PATH_PATTERNS.some((re) => re.test(residue));
 	});
 }
 
-export function isProtectedPath(targetPath: string): boolean {
+export function isProtectedPath(
+	targetPath: string,
+	liveControlPlaneRoots: readonly string[] | undefined = getLiveControlPlaneRoots(),
+): boolean {
 	if (!targetPath) return false;
 	const root = getWorkspaceRoot();
 	const resolved = resolve(root, targetPath);
+	if (liveControlPlaneRoots && liveControlPlaneRoots.length > 0) {
+		// Fact mode: only the LIVE control plane is protected; versioned drafts
+		// (project .opencode/, dotfiles .config/opencode, worktrees) are not.
+		return pathWithinAnyRoot(resolved, liveControlPlaneRoots) || realpathWithinAnyRoot(resolved, liveControlPlaneRoots);
+	}
 	const matches = (path: string): boolean => {
 		const base = basename(path);
 		const lower = path.toLowerCase();

package/src/workflow-guard.ts

@@ -16,7 +16,7 @@ import { resolve } from "node:path";
 import { join } from "node:path";
 import { editTargets, runPostEditValidators, snapshotFile } from "./policies/post-edit-validation.ts";
 import { claimFiles, releaseFileClaims } from "./policies/file-claims.ts";
-import { beginReadObservation, clearReadFingerprints, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
+import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
 import { guardToolCallImpl, isReadOnlyRole } from "./lib/guard-dispatcher.ts";
@@ -66,6 +66,7 @@ import {
 	sessionMutationTimestamps,
 	sessionVerifyResults,
 	getProjectConfig,
+	getLiveControlPlaneRoots,
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
@@ -88,6 +89,7 @@ import { findGitRoot, isSameGitRepo, loadProjectConfig, reloadProjectConfig, str
 export {
 	setWorkspaceRoot,
 	getWorkspaceRoot,
+	getLiveControlPlaneRoots,
 	setSdkClient,
 	getLastMutationTimestamp,
 	getMutationCount,
@@ -196,6 +198,7 @@ import {
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
 	getGitWorktreeFingerprint,
+	getTrackedWorktreeFingerprint,
 } from "./lib/verify.ts";
 
 export {
@@ -206,6 +209,7 @@ export {
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
 	getGitWorktreeFingerprint,
+	getTrackedWorktreeFingerprint,
 };
 
 // ── Secondary review rubric ──────────────────────────────────────────────────
@@ -219,6 +223,7 @@ import {
 	isValidBranchName,
 	createGitWorktree,
 	cleanupGitWorktree,
+	resolveWorktreeTimeoutMs,
 } from "./lib/worktree.ts";
 
 export {
@@ -227,6 +232,7 @@ export {
 	isValidBranchName,
 	createGitWorktree,
 	cleanupGitWorktree,
+	resolveWorktreeTimeoutMs,
 };
 
 // ── Policy modules ───────────────────────────────────────────────────────────
@@ -512,6 +518,12 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			const pending = toolLifecycle.takePostEditSnapshots(input.sessionID, input.callID);
 			if (!pending) return;
 			await runWithRuntimeState(pending.root, ctx.client, async () => {
+				// A successful mutation means this session authored the resulting
+				// bytes, so seed its observation: a follow-up edit to a just
+				// created/modified file must not demand a redundant re-read. A
+				// no-op/failed call (content unchanged) seeds nothing, and an
+				// external change after the mutation still fails the comparison.
+				for (const before of pending.snapshots) recordMutationObservation(before.path, input.sessionID, before.digest);
 				const reports = await Promise.all(pending.snapshots.map((before) => runPostEditValidators(pending.root, before)));
 				const report = reports.filter((value): value is string => Boolean(value)).join("\n\n");
 				if (report) output.output = `${output.output}\n\n${report}`;