opencode-workflow-guard 1.5.1 → 1.7.0

package/src/policies/file-claims.ts

@@ -0,0 +1,56 @@
+import { readlinkSync, realpathSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+
+interface FileClaim {
+	sessionID: string;
+	callID: string;
+}
+
+const claims = new Map<string, FileClaim>();
+
+export function canonicalPath(path: string, seen = new Set<string>()): string {
+	const resolved = resolve(path);
+	if (seen.has(resolved)) return resolved;
+	seen.add(resolved);
+	try {
+		return realpathSync(resolved);
+	} catch {
+		try {
+			return canonicalPath(resolve(dirname(resolved), readlinkSync(resolved)), seen);
+		} catch {}
+		let ancestor = dirname(resolved);
+		while (true) {
+			try {
+				return resolve(realpathSync(ancestor), relative(ancestor, resolved));
+			} catch {
+				const parent = dirname(ancestor);
+				if (parent === ancestor) return resolved;
+				ancestor = parent;
+			}
+		}
+	}
+}
+
+export function claimFiles(paths: string[], sessionID: string, callID: string): string | undefined {
+	const canonical = [...new Set(paths.map((path) => canonicalPath(path)))];
+	for (const path of canonical) {
+		const existing = claims.get(path);
+		if (existing && existing.sessionID !== sessionID) {
+			return `Blocked: file '${path}' is claimed by another active session ('${existing.sessionID}'). Wait for that edit to finish or use an isolated worktree.`;
+		}
+	}
+	for (const path of canonical) {
+		if (!claims.has(path)) {
+			claims.set(path, { sessionID, callID });
+		}
+	}
+	return undefined;
+}
+
+export function releaseFileClaims(sessionID: string, callID?: string): void {
+	for (const [path, claim] of claims) {
+		if (claim.sessionID === sessionID && (callID === undefined || claim.callID === callID)) {
+			claims.delete(path);
+		}
+	}
+}

package/src/policies/git.ts

@@ -9,7 +9,7 @@ import {
 import {
 	unwrapShellWords,
 	splitShellSegments,
-} from "../lib/utils.ts";
+} from "../lib/shell.ts";
 
 export const PROTECTED_BRANCHES = new Set(["main", "master"]);
 

package/src/policies/post-edit-validation.ts

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { getProjectConfig } from "../lib/state.ts";
+import { runVerify, snipVerifyOutput } from "../lib/verify.ts";
+import { extractPatchPaths } from "./boundary.ts";
+
+export interface FileSnapshot {
+	path: string;
+	digest?: string;
+}
+
+function globRegex(pattern: string): RegExp {
+	let source = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const char = pattern[i];
+		if (char === "*") {
+			if (pattern[i + 1] === "*") {
+				i++;
+				if (pattern[i + 1] === "/") {
+					i++;
+					source += "(?:.*/)?";
+				} else {
+					source += ".*";
+				}
+			} else {
+				source += "[^/]*";
+			}
+		} else if (char === "?") {
+			source += "[^/]";
+		} else {
+			source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+		}
+	}
+	return new RegExp(`${source}$`);
+}
+
+export function snapshotFile(path: string): FileSnapshot {
+	try {
+		return { path, digest: createHash("sha256").update(readFileSync(path)).digest("hex") };
+	} catch {
+		return { path };
+	}
+}
+
+export function editTargets(args: unknown, root: string): string[] {
+	if (!args || typeof args !== "object") return [];
+	const record = args as Record<string, unknown>;
+	const raw = typeof record.filePath === "string" ? record.filePath : typeof record.path === "string" ? record.path : undefined;
+	if (raw) return [isAbsolute(raw) ? raw : resolve(root, raw)];
+	if (typeof record.patchText !== "string") return [];
+	return extractPatchPaths(record.patchText).map((path) => isAbsolute(path) ? path : resolve(root, path));
+}
+
+export async function runPostEditValidators(root: string, before: FileSnapshot): Promise<string | undefined> {
+	const after = snapshotFile(before.path);
+	if (after.digest === before.digest) return undefined;
+	const relativePath = relative(root, before.path).replaceAll("\\", "/");
+	const validators = getProjectConfig(root).postEditValidators;
+	if (!Array.isArray(validators)) return undefined;
+
+	const failures: string[] = [];
+	for (const [index, validator] of validators.entries()) {
+		if (!validator || typeof validator.pattern !== "string" || !validator.pattern || /[{}\[\]]/.test(validator.pattern) || typeof validator.command !== "string" || !validator.command.trim() || (validator.timeoutMs !== undefined && (!Number.isFinite(validator.timeoutMs) || validator.timeoutMs <= 0))) {
+			failures.push(`[workflow-guard] Invalid postEditValidators configuration at index ${index}: pattern must be a non-empty *, **, ? glob without brace/class syntax; command must be non-empty; timeoutMs must be a positive finite number when provided.`);
+			continue;
+		}
+		if (!globRegex(validator.pattern).test(relativePath)) continue;
+		const timeoutMs = validator.timeoutMs ?? 30_000;
+		const result = await runVerify(validator.command, root, timeoutMs);
+		if (!result.passed) {
+			failures.push(`[workflow-guard] Post-edit validator failed for ${relativePath}: ${validator.command}\n${snipVerifyOutput(result.output, false)}`);
+		}
+	}
+	return failures.length ? failures.join("\n\n") : undefined;
+}

package/src/policies/secrets.ts

@@ -1,7 +1,7 @@
 import { realpathSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { getWorkspaceRoot } from "../lib/state.ts";
-import { shellWords, unwrapShellCommand } from "../lib/utils.ts";
+import { shellWords, unwrapShellCommand } from "../lib/shell.ts";
 
 export const SAFE_ENV_FIXTURE_RE =
 	/\.env\.(example|sample|template|dist|schema)(\.[\w-]+)*$/i;

package/src/policies/stale-write.ts

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { canonicalPath } from "./file-claims.ts";
+
+interface ReadFingerprint {
+	dev: bigint;
+	ino: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	digest: string;
+}
+
+export interface ReadObservation {
+	path: string;
+	fingerprint: ReadFingerprint;
+}
+
+const reads = new Map<string, Map<string, ReadFingerprint>>();
+
+function fingerprint(path: string): ReadFingerprint | undefined {
+	try {
+		const stat = statSync(path, { bigint: true });
+		if (!stat.isFile()) return undefined;
+		return {
+			dev: stat.dev,
+			ino: stat.ino,
+			size: stat.size,
+			mtimeNs: stat.mtimeNs,
+			digest: createHash("sha256").update(readFileSync(path)).digest("hex"),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function equal(a: ReadFingerprint, b: ReadFingerprint): boolean {
+	return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.digest === b.digest;
+}
+
+export function beginReadObservation(path: string): ReadObservation | undefined {
+	const observed = fingerprint(path);
+	if (!observed) return undefined;
+	return { path: canonicalPath(path), fingerprint: observed };
+}
+
+export function recordSuccessfulRead(observation: ReadObservation, sessionID: string): void {
+	const current = fingerprint(observation.path);
+	if (!current || !equal(observation.fingerprint, current)) return;
+	const sessionReads = reads.get(sessionID) ?? new Map<string, ReadFingerprint>();
+	sessionReads.set(observation.path, observation.fingerprint);
+	reads.set(sessionID, sessionReads);
+}
+
+export function staleWriteReason(path: string, sessionID: string): string | undefined {
+	const current = fingerprint(path);
+	const canonical = canonicalPath(path);
+	const observed = reads.get(sessionID)?.get(canonical);
+	if (!observed) {
+		if (!current) return undefined;
+		return `Blocked: existing file '${canonical}' has not been read by this session. Re-read it before editing or overwriting it.`;
+	}
+	if (!current || !equal(observed, current)) {
+		return `Blocked: file '${canonical}' changed since this session read it. Re-read it before editing or overwriting it.`;
+	}
+	return undefined;
+}
+
+export function clearReadFingerprints(sessionID: string): void {
+	reads.delete(sessionID);
+}

package/src/policies/tamper.ts

@@ -1,7 +1,7 @@
 import { realpathSync } from "node:fs";
 import { basename, relative, resolve } from "node:path";
 import { getWorkspaceRoot } from "../lib/state.ts";
-import { decodeShellEscapes } from "../lib/utils.ts";
+import { decodeShellEscapes } from "../lib/shell.ts";
 
 export const PROTECTED_PATH_REASON =
 	"Blocked: modifying Open" +

package/src/policies/todo.ts

@@ -1,5 +1,5 @@
 import type { TodoItem } from "../lib/types.ts";
-import { getSdkClient } from "../lib/state.ts";
+import { getSessionMutationCount, getSdkClient, getSubagentMutationBudget } from "../lib/state.ts";
 
 export const EDIT_TOOL_NAMES = new Set(["edit", "write", "patch", "apply_patch"]);
 export const ACTIVE_TODO_STATUSES = new Set(["pending", "in_progress"]);
@@ -19,16 +19,34 @@ export async function fetchSessionTodos(sessionID: string): Promise<TodoItem[] |
 }
 
 export async function fetchParentSessionID(sessionID: string): Promise<string | undefined> {
+	const result = await fetchParentSession(sessionID);
+	return result.ok ? result.parentID : undefined;
+}
+
+export async function subagentMutationBudgetReason(
+	sessionID: string,
+	root: string,
+): Promise<string | undefined> {
+	if (!await fetchParentSessionID(sessionID)) return undefined;
+	const count = getSessionMutationCount(sessionID);
+	const budget = getSubagentMutationBudget(root);
+	if (count < budget) return undefined;
+	return `Blocked: subagent session '${sessionID}' has reached its mutation budget (${count}/${budget}). Hand work back to parent orchestrator.`;
+}
+
+export async function fetchParentSession(sessionID: string): Promise<{ ok: true; parentID?: string } | { ok: false }> {
 	const client = getSdkClient();
 	const session = client?.session;
 	const get = session?.get;
-	if (typeof get !== "function") return undefined;
+	if (typeof get !== "function") return { ok: false };
 	try {
 		const result = await get.call(session, { path: { id: sessionID } });
-		const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
-		return typeof parent === "string" && parent ? parent : undefined;
+		const data = (result as { data?: { parentID?: unknown } } | undefined)?.data;
+		if (!data) return { ok: false };
+		const parent = data.parentID;
+		return { ok: true, parentID: typeof parent === "string" && parent ? parent : undefined };
 	} catch {
-		return undefined;
+		return { ok: false };
 	}
 }
 
@@ -58,16 +76,8 @@ export async function effectiveTodoOwnerSessionID(
 	sessionID: string | undefined,
 ): Promise<string | undefined> {
 	if (!sessionID) return undefined;
-	const seen = new Set<string>();
-	let current: string | undefined = sessionID;
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		const todos = await fetchSessionTodos(current);
-		if (todos === undefined) return sessionID;
-		if (todos.length > 0) return current;
-		current = await fetchParentSessionID(current);
-	}
-	return sessionID;
+	const effective = await effectiveTodosWithOwner(sessionID);
+	return effective?.ownerSessionID ?? sessionID;
 }
 
 export function hasActiveTodo(todos: TodoItem[]): boolean {

package/src/workflow-guard-ui.ts

@@ -1,6 +1,11 @@
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
 import type { JSX } from "@opentui/solid";
 import { createElement, insert, setProp } from "@opentui/solid";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { applyEdits, modify, parse, type ParseError } from "jsonc-parser";
+import { projectConfigPath } from "./lib/project-config.ts";
+import { canonicalPath } from "./policies/file-claims.ts";
 
 type Child = JSX.Element | string | number | null | undefined | false;
 
@@ -29,6 +34,43 @@ let lastBlockedReason: string | undefined;
 const sessionBlockedReasons = new Map<string, string>();
 const badgeNodes = new Map<string, unknown>();
 
+export function readProjectOption(root: string, option: "recoveryCheckpoints" | "projectMemory" | "learning"): boolean {
+	const path = projectConfigPath(root);
+	if (!existsSync(path)) return option === "projectMemory";
+	const errors: ParseError[] = [];
+	const config = parse(readFileSync(path, "utf8"), errors, { allowTrailingComma: true });
+	if (errors.length > 0) throw new Error(`Invalid Workflow Guard project config: ${path}`);
+	return option === "projectMemory" ? config?.projectMemory !== false : config?.[option] === true;
+}
+
+function writeProjectOption(root: string, option: "recoveryCheckpoints" | "projectMemory" | "learning", enabled: boolean): string {
+	const path = projectConfigPath(root);
+	const raw = existsSync(path) ? readFileSync(path, "utf8") : "{}\n";
+	const errors: ParseError[] = [];
+	parse(raw, errors, { allowTrailingComma: true });
+	if (errors.length > 0) throw new Error(`Invalid Workflow Guard project config: ${path}`);
+	const realRoot = canonicalPath(root);
+	const realPath = canonicalPath(path);
+	const rel = relative(realRoot, realPath);
+	if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
+		throw new Error(`Refusing to write Workflow Guard config outside project: ${path}`);
+	}
+	const next = applyEdits(raw, modify(raw, [option], enabled, {
+		formattingOptions: { insertSpaces: true, tabSize: 2 },
+	}));
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, next.endsWith("\n") ? next : next + "\n");
+	return path;
+}
+
+export function readRecoveryCheckpointsOption(root: string): boolean {
+	return readProjectOption(root, "recoveryCheckpoints");
+}
+
+export function writeRecoveryCheckpointsOption(root: string, enabled: boolean): string {
+	return writeProjectOption(root, "recoveryCheckpoints", enabled);
+}
+
 export function setLastBlockedReasonForTesting(reason: string | undefined): void {
 	lastBlockedReason = reason;
 	if (reason === undefined) sessionBlockedReasons.clear();
@@ -49,6 +91,39 @@ export function formatBadge(sessionID?: string): { text: string; isBlocked: bool
 }
 
 export const WorkflowGuardTui: TuiPlugin = async (api) => {
+	api.keymap.registerLayer({
+		commands: [{
+			name: "workflow-guard.project-options",
+			title: "Workflow Guard: Project Options",
+			category: "Workflow Guard",
+			namespace: "palette",
+			slashName: "guard-options",
+			run() {
+				const root = api.state.path.worktree || api.state.path.directory;
+				const recovery = readProjectOption(root, "recoveryCheckpoints");
+				const memory = readProjectOption(root, "projectMemory");
+				const learning = readProjectOption(root, "learning");
+				api.ui.dialog.replace(() => api.ui.DialogSelect({
+					title: "Workflow Guard Project Options",
+					current: undefined,
+					options: [
+						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints" },
+						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory" },
+						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools" },
+					],
+					onSelect: (option) => {
+						const key = option.value as "recoveryCheckpoints" | "projectMemory" | "learning";
+						const enabled = !readProjectOption(root, key);
+						const path = writeProjectOption(root, key, enabled);
+						api.ui.dialog.clear();
+						api.ui.toast({ variant: "success", title: "Workflow Guard", message: `Saved ${key} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.` });
+					},
+				}));
+			},
+		}],
+		bindings: [],
+	});
+
 	try {
 		api.event?.on?.("tui.toast.show" as any, (e: any) => {
 			const title = e?.properties?.title ?? e?.title;