opencode-workflow-guard 1.12.0 → 1.13.1

package/src/policies/continuation.ts

@@ -14,6 +14,7 @@ type ContinuationState = {
 	generatedMessageIDs: Map<string, Set<string>>;
 	lastUserMessageIDs: Map<string, string>;
 	inFlight: Set<string>;
+	interrupted: Set<string>;
 };
 export type RalphOutcome = "running" | "completed" | "blocked" | "budget_exhausted" | "user_stopped";
 const states = new WeakMap<object, Map<string, ContinuationState>>();
@@ -43,7 +44,7 @@ function getState(): ContinuationState | undefined {
 	const root = projectRootKey(getWorkspaceRoot());
 	let state = clientStates.get(root);
 	if (!state) {
-		state = { counts: new Map(), ralphOutcomes: new Map(), generatedMessageIDs: new Map(), lastUserMessageIDs: new Map(), inFlight: new Set() };
+		state = { counts: new Map(), ralphOutcomes: new Map(), generatedMessageIDs: new Map(), lastUserMessageIDs: new Map(), inFlight: new Set(), interrupted: new Set() };
 		clientStates.set(root, state);
 	}
 	return state;
@@ -56,6 +57,9 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 	try {
 		const ralph = isRalphModeEnabled(getWorkspaceRoot());
 		if (ralph && state.ralphOutcomes.get(sessionID) === "user_stopped") return false;
+		// A user-initiated interrupt (Esc) suspends automatic continuation:
+		// only genuine user input re-enables it (see recordUserMessage).
+		if (state.interrupted.has(sessionID)) return false;
 		const effective = await effectiveTodosWithOwner(sessionID);
 		if (!effective || effective.ownerSessionID !== sessionID || !hasActiveTodo(effective.todos)) {
 			if (ralph && state.ralphOutcomes.has(sessionID)) state.ralphOutcomes.set(sessionID, "completed");
@@ -73,7 +77,7 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 		const session = getSdkClient()?.session;
 		if (typeof session?.promptAsync !== "function") return false;
 
-		const messageID = `workflow-guard-${randomUUID()}`;
+		const messageID = `msg_wg_${randomUUID().replace(/-/g, "")}`;
 		state.counts.set(sessionID, count + 1);
 		if (ralph) state.ralphOutcomes.set(sessionID, "running");
 		const generatedIDs = state.generatedMessageIDs.get(sessionID) ?? new Set<string>();
@@ -122,12 +126,26 @@ export function recordUserMessage(sessionID: string, messageID?: string): void {
 	if (messageID && state.lastUserMessageIDs.get(sessionID) === messageID) return;
 	if (messageID) state.lastUserMessageIDs.set(sessionID, messageID);
 	state.counts.delete(sessionID);
+	state.interrupted.delete(sessionID);
 	if (isRalphModeEnabled(getWorkspaceRoot()) && state.ralphOutcomes.has(sessionID)) {
 		if (state.ralphOutcomes.get(sessionID) === "user_stopped") state.ralphOutcomes.delete(sessionID);
 		else state.ralphOutcomes.set(sessionID, "user_stopped");
 	}
 }
 
+// Record a user-initiated interrupt (Esc): the session's run was aborted
+// from the user side, so automatic continuation must stop. Ralph runs are
+// marked user_stopped, mirroring genuine user input. A later genuine user
+// message re-enables continuation (recordUserMessage clears the flag).
+export function markInterrupted(sessionID: string): void {
+	const state = getState();
+	if (!state) return;
+	state.interrupted.add(sessionID);
+	if (isRalphModeEnabled(getWorkspaceRoot()) && state.ralphOutcomes.has(sessionID)) {
+		state.ralphOutcomes.set(sessionID, "user_stopped");
+	}
+}
+
 export function getRalphOutcome(sessionID: string): RalphOutcome | undefined {
 	return getState()?.ralphOutcomes.get(sessionID);
 }
@@ -145,4 +163,5 @@ export function clearContinuationState(sessionID: string): void {
 	state.generatedMessageIDs.delete(sessionID);
 	state.lastUserMessageIDs.delete(sessionID);
 	state.inFlight.delete(sessionID);
+	state.interrupted.delete(sessionID);
 }

package/src/policies/git.ts

@@ -123,7 +123,7 @@ export function normalizeGitCommands(command: string): string {
 }
 
 export const GIT_WRITE_RE =
-	/\bgit\s+(add|rm|mv|commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+tag\s+(?!--?list\b|-l\b)|\bgit\s+checkout\s+(?!-b\b)|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
+	/\bgit\s+(add|rm|mv|commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+tag\s+(?!--?list\b|-l\b)(?:[^|;&]*\s)?(?:-d\b|--delete\b)|\bgit\s+checkout\s+(?!-b\b)|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
 
 export function currentGitBranch(root: string): string | undefined {
 	const result = spawnSync("git", ["branch", "--show-current"], {
@@ -179,6 +179,47 @@ export function pushedProtectedBranchIn(pushCommand: string, root: string): stri
 	return undefined;
 }
 
+/**
+ * True when a `git push` command pushes a tag refspec: an explicit
+ * `refs/tags/<name>` destination, or a short name that resolves to an
+ * existing tag in the repository at `root`. Publishing a tag is a release
+ * operation, not a branch mutation, so callers exempt it from the
+ * protected-branch and merged-branch push rules (#134). Deletion refspecs
+ * (`:refs/tags/<name>`, `git push --delete`, `-d`) return false so tag
+ * deletions stay blocked.
+ */
+export function tagRefspecIn(pushCommand: string, root: string): boolean {
+	if (/\s--delete\b|\s-d(?:\b|$)/.test(pushCommand)) return false;
+	for (const segment of splitShellSegments(pushCommand)) {
+		const parsed = parseGitInvocation(segment);
+		if (!parsed || !/\bpush\b/.test(parsed.rest)) continue;
+		const tokens = parsed.rest.split(/\s+/).slice(1);
+		let remoteSeen = false;
+		for (const rawToken of tokens) {
+			if (rawToken.startsWith("-")) continue;
+			if (!remoteSeen) {
+				remoteSeen = true;
+				continue;
+			}
+			const token = rawToken.replace(/^\+/, "");
+			if (!token) continue;
+			if (token.startsWith(":")) continue; // deletion refspec: empty source
+			if (token.includes(":")) {
+				if (token.includes(":refs/tags/")) return true; // <src>:refs/tags/<name>
+				continue;
+			}
+			if (token.startsWith("refs/tags/")) return true; // explicit tag refspec
+			const probe = spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/tags/${token}`], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+			if (probe.status === 0) return true;
+		}
+	}
+	return false;
+}
+
 export function onProtectedBranch(root: string): boolean {
 	return isProtectedBranchName(currentGitBranch(root) ?? "", root);
 }

package/src/policies/tamper.ts

@@ -36,11 +36,23 @@ export function normalizeGlobPathEvasion(text: string): string {
 		.replace(/opencode\.[?*]/gi, ocJson);
 }
 
+// Collaboration invocations (hosted-git/PR/issue CLIs) never write local
+// configuration: their arguments may legitimately mention guarded paths.
+const COLLABORATION_INVOCATION_PATTERNS: RegExp[] = [
+	/^\s*(?:gh|glab)\s+(?:issue|pr)\b/,
+	/^\s*az\s+repos\s+pr\b/,
+];
+
+export function isCollaborationInvocation(segment: string): boolean {
+	return COLLABORATION_INVOCATION_PATTERNS.some((re) => re.test(segment));
+}
+
 export function isSettingsTamper(command: string): boolean {
 	const segments = command.split(/[\n|;&]+/).map((s) =>
 		normalizeGlobPathEvasion(normalizeShellEvasion(s)),
 	);
 	return segments.some((segment) =>
+		!isCollaborationInvocation(segment) &&
 		SETTINGS_TAMPER_PATTERNS.some((re) => re.test(segment)),
 	);
 }
@@ -53,6 +65,11 @@ export function isProtectedPath(targetPath: string): boolean {
 		const base = basename(path);
 		const lower = path.toLowerCase();
 		const dotOc = "." + "opencode/";
+		// opencode plan mode writes agent plan markdown under the project's
+		// .opencode/plans/ directory - plan files are documents, not
+		// configuration. The trailing slash keeps the plans directory
+		// itself protected.
+		if (lower.includes("/" + dotOc + "plans/")) return false;
 		const cfgOc = "/.config/" + "opencode/";
 		const cfgOcJson = "/.config/" + "opencode.json";
 		return (

package/src/workflow-guard-ui.ts

@@ -1,4 +1,14 @@
+/**
+ * Workflow Guard TUI companion plugin for OpenCode V2 (CLI plugin API).
+ *
+ * - Registers the `/guard-options` palette + slash command to toggle project options.
+ * - Renders the Workflow Guard badge in the home and prompt footer status slots.
+ *
+ * The V1 entrypoint (`WorkflowGuardTui`) remains for OpenCode 1.x TUI clients.
+ */
+
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
+import { Plugin } from "@opencode/plugin/tui";
 import type { JSX } from "@opentui/solid";
 import { createElement, insert, setProp } from "@opentui/solid";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -75,6 +85,79 @@ export function formatBadge(): { text: string; isBlocked: boolean } {
 	return { text: BADGE_ACTIVE, isBlocked: false };
 }
 
+// ── V2 CLI plugin ─────────────────────────────────────────────────────────────
+
+type TuiContext = Plugin.Context;
+
+const TOGGLE_OPTIONS: Array<{ key: ProjectToggle; label: string; description: string }> = [
+	{ key: "recoveryCheckpoints", label: "Recovery checkpoints", description: "Toggle durable pre-run Git checkpoints" },
+	{ key: "projectMemory", label: "Project memory", description: "Toggle durable local project memory" },
+	{ key: "learning", label: "Learner mode", description: "Toggle evidence-based learning tools" },
+	{ key: "titleSettleWorkaround", label: "Title settle workaround", description: "Delay automatic continuation while OpenCode generates a session title" },
+	{ key: "ralphMode", label: "Ralph mode", description: "Opt into bounded autonomous continuation of already-owned todos" },
+];
+
+export const WorkflowGuardTuiV2 = (ctx: TuiContext) => {
+	const badge = () => {
+		const formatted = formatBadge();
+		return text({ fg: ctx.theme.text.feedback.success.base }, [formatted.text]);
+	};
+
+	const optionsRoot = () => ctx.location?.directory || process.cwd();
+
+	ctx.keymap.layer(() => ({
+		commands: [{
+			id: "workflow-guard.project-options",
+			title: "Workflow Guard: Project Options",
+			description: "Toggle Workflow Guard project options (recovery checkpoints, project memory, learning, title settle, ralph mode)",
+			group: "Workflow Guard",
+			palette: true,
+			slash: { name: "guard-options" },
+			async run() {
+				const root = optionsRoot();
+				for (;;) {
+					const current = new Map(TOGGLE_OPTIONS.map((option) => [option.key, readProjectOption(root, option.key)]));
+					const choice = await ctx.ui.dialog.select<ProjectToggle>({
+						title: "Workflow Guard Project Options",
+						options: TOGGLE_OPTIONS.map((option) => ({
+							title: `${option.label}: ${current.get(option.key) ? "On" : "Off"}`,
+							value: option.key,
+							description: option.description,
+						})),
+					});
+					if (!choice) break;
+					try {
+						const enabled = !readProjectOption(root, choice);
+						const path = writeProjectOption(root, choice, enabled);
+						ctx.ui.toast.show({
+							variant: "success",
+							title: "Workflow Guard",
+							message: `Saved ${choice} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.`,
+						});
+					} catch (error) {
+						ctx.ui.toast.show({
+							variant: "error",
+							title: "Workflow Guard",
+							message: error instanceof Error ? error.message : String(error),
+						});
+						break;
+					}
+				}
+			},
+		}],
+		bindings: [],
+	}));
+
+	ctx.ui.slot({ append: "home.footer.status", render: () => badge() });
+	ctx.ui.slot({ append: "prompt.footer.status", render: () => badge() });
+
+	return () => {
+		// Slot claims and keymap layers are disposed automatically on unload.
+	};
+};
+
+// ── V1 TUI plugin ─────────────────────────────────────────────────────────────
+
 export const WorkflowGuardTui: TuiPlugin = async (api) => {
 	api.keymap.registerLayer({
 		commands: [{
@@ -85,11 +168,6 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 			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");
-				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
-				const ralphMode = readProjectOption(root, "ralphMode");
 				const toggle = (key: ProjectToggle) => {
 					const enabled = !readProjectOption(root, key);
 					const path = writeProjectOption(root, key, enabled);
@@ -99,13 +177,12 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				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", onSelect: () => toggle("recoveryCheckpoints") },
-						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory", onSelect: () => toggle("projectMemory") },
-						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools", onSelect: () => toggle("learning") },
-						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title", onSelect: () => toggle("titleSettleWorkaround") },
-						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos", onSelect: () => toggle("ralphMode") },
-					],
+					options: TOGGLE_OPTIONS.map((option) => ({
+						title: `${option.label}: ${readProjectOption(root, option.key) ? "On" : "Off"}`,
+						value: option.key,
+						description: option.description,
+						onSelect: () => toggle(option.key),
+					})),
 				}));
 			},
 		}],
@@ -129,7 +206,11 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 	});
 };
 
+// Default export supports BOTH generations: V1 TUI clients call tui(), V2 reads setup().
 export default {
-	id: "workflow-guard-ui",
+	...Plugin.define({
+		id: "workflow-guard-ui",
+		setup: WorkflowGuardTuiV2,
+	}),
 	tui: WorkflowGuardTui,
-} satisfies TuiPluginModule;
+} as const satisfies TuiPluginModule;

package/src/workflow-guard.ts

@@ -8,7 +8,9 @@
  * from ./lib/, and re-exports the public helper surface for tests.
  */
 
-import { type Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { type Plugin as V1Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { Plugin } from "@opencode/plugin";
+import { WorkflowGuardV2 } from "./lib/v2-plugin.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { join } from "node:path";
@@ -74,10 +76,14 @@ import {
 	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
+	getLastReviewResultForWorkspace,
 	resetReviewState,
 	sessionReviews,
+	setSessionWorkspace,
+	getSessionWorkspace,
+	resolveEffectiveWorkspace,
 } from "./lib/state.ts";
-import { loadProjectConfig, reloadProjectConfig, stripJsonComments } from "./lib/project-config.ts";
+import { findGitRoot, isSameGitRepo, loadProjectConfig, reloadProjectConfig, stripJsonComments } from "./lib/project-config.ts";
 
 export {
 	setWorkspaceRoot,
@@ -101,11 +107,18 @@ export {
 	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
+	getLastReviewResultForWorkspace,
 	resetReviewState,
+	setSessionWorkspace,
+	getSessionWorkspace,
+	resolveEffectiveWorkspace,
+	findGitRoot,
+	isSameGitRepo,
 };
 
 // ── Shared shell/env utilities ───────────────────────────────────────────────
 import {
+	asRecord,
 	extractRecordTargetPath,
 	getCleanEnv,
 	showBlockToast,
@@ -149,14 +162,17 @@ import { ensureProjectMemoryExcluded, getProjectMemoryIdentity, getRecentProject
 import {
 	getAuditFilePath,
 	getVerifyCacheFilePath,
+	getReviewCacheFilePath,
 	persistVerifyCache,
 	loadVerifyCache,
+	persistReviewCache,
+	loadReviewCache,
 	audit,
 	logDecision,
 	summarizeInput,
 } from "./lib/audit.ts";
 
-export { getAuditFilePath, getVerifyCacheFilePath, getVerifyHistoryFilePath, persistVerifyCache, loadVerifyCache, getRecentAuditEntries, getRecentVerifyHistory } from "./lib/audit.ts";
+export { getAuditFilePath, getVerifyCacheFilePath, getReviewCacheFilePath, getVerifyHistoryFilePath, persistVerifyCache, loadVerifyCache, persistReviewCache, loadReviewCache, getRecentAuditEntries, getRecentVerifyHistory } from "./lib/audit.ts";
 export { summarizeInput };
 
 export function managedConfigDiagnostic(platform = process.platform, env: NodeJS.ProcessEnv = process.env): string {
@@ -174,6 +190,7 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -183,6 +200,7 @@ import {
 
 export {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -225,6 +243,7 @@ import {
 	clearContinuationState,
 	continueUnfinishedSession,
 	isGeneratedContinuationMessage,
+	markInterrupted,
 	recordUserMessage,
 } from "./policies/continuation.ts";
 import {
@@ -363,15 +382,22 @@ export function buildCompactionContext(operationalState: string, priorityBlocks:
 	return context;
 }
 
-export const WorkflowGuard: Plugin = async (ctx) => {
+export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
 	// so worktree plugins cannot punch through boundary gates. When the host
 	// reports the filesystem root, use the SDK's actual project worktree instead.
 	const hostRoot = ctx.worktree || ctx.directory || process.cwd();
 	const hostIsFilesystemRoot = resolve(hostRoot) === resolve(hostRoot, "..");
-	const effectiveRoot = hostIsFilesystemRoot && ctx.project?.worktree
+	let effectiveRoot = hostIsFilesystemRoot && ctx.project?.worktree && resolve(ctx.project.worktree) !== resolve(ctx.project.worktree, "..")
 		? ctx.project.worktree
 		: hostRoot;
+	if (resolve(effectiveRoot) === resolve(effectiveRoot, "..")) {
+		const nonRootCandidate = [ctx.directory, process.cwd()].find((p) => typeof p === "string" && resolve(p) !== resolve(p, ".."));
+		if (nonRootCandidate) {
+			const gitRoot = findGitRoot(nonRootCandidate);
+			effectiveRoot = gitRoot ?? nonRootCandidate;
+		}
+	}
 	setWorkspaceRoot(effectiveRoot);
 	setSdkClient(ctx.client);
 	reloadProjectConfig(effectiveRoot);
@@ -439,6 +465,16 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
 				toolLifecycle.start(input.sessionID, input.callID);
+				if (input.sessionID) {
+					const record = asRecord(args);
+					const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
+					const filePath = typeof record?.filePath === "string" ? record.filePath : (typeof record?.path === "string" ? record.path : undefined);
+					const candidatePath = workdir ?? filePath ?? toolWorktree;
+					if (candidatePath) {
+						const gitRoot = findGitRoot(candidatePath);
+						if (gitRoot) setSessionWorkspace(input.sessionID, gitRoot);
+					}
+				}
 				if (input.tool === "read") {
 					const target = editTargets(args, toolWorktree)[0];
 					if (target) {
@@ -732,12 +768,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				}
 			}
 			if (event?.type === "message.updated") {
-				const info = (event.properties as { info?: { id?: unknown; role?: unknown; sessionID?: unknown } })?.info;
+				const info = (event.properties as { info?: { id?: unknown; role?: unknown; sessionID?: unknown; error?: { name?: unknown } } })?.info;
 				if (info?.role === "user" && typeof info.sessionID === "string") {
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => {
 						recordUserMessage(info.sessionID as string, typeof info.id === "string" ? info.id : undefined);
 					});
 				}
+				// A user-initiated interrupt (Esc) surfaces as an aborted
+				// assistant message: stop automatic continuation for the
+				// session until genuine user input arrives.
+				if (info?.role === "assistant" && typeof info.sessionID === "string" && info.error?.name === "MessageAbortedError") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => markInterrupted(info.sessionID as string));
+				}
+			}
+			if (event?.type === "session.error") {
+				const props = event.properties as { sessionID?: unknown; error?: { name?: unknown } };
+				if (typeof props?.sessionID === "string" && props?.error?.name === "MessageAbortedError") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => markInterrupted(props.sessionID as string));
+				}
 			}
 			if (event?.type === "session.deleted") {
 				const sessionID = (event.properties as { info?: { id?: unknown } })?.info?.id;
@@ -773,8 +821,12 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 	};
 };
 
-// Default export MUST be a V1 PluginModule record.
+// Default export supports BOTH generations: V1 calls server(), V2 reads id+setup().
+// Spread Plugin.define() so the V2 definition type-checks separately from server().
 export default {
-	id: "workflow-guard",
+	...Plugin.define({
+		id: "workflow-guard",
+		setup: WorkflowGuardV2,
+	}),
 	server: WorkflowGuard,
 } satisfies PluginModule;