opencode-workflow-guard 1.12.1 → 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");
@@ -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";
@@ -188,6 +190,7 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -197,6 +200,7 @@ import {
 
 export {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -239,6 +243,7 @@ import {
 	clearContinuationState,
 	continueUnfinishedSession,
 	isGeneratedContinuationMessage,
+	markInterrupted,
 	recordUserMessage,
 } from "./policies/continuation.ts";
 import {
@@ -377,7 +382,7 @@ 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.
@@ -763,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;
@@ -804,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;

package/test/test-e2e.mts

@@ -7,8 +7,9 @@ import { parse as parseJsonc } from "jsonc-parser";
 let pass = 0;
 let fail = 0;
 let unavailable = 0;
-const check = (name: string, cond: unknown): void => {
+const check = (name: string, cond: unknown): boolean => {
 	cond ? (pass++, console.log("  ok  " + name)) : (fail++, console.log("FAIL  " + name));
+	return Boolean(cond);
 };
 const providerUnavailable = (output: string): boolean =>
 	/available credits|insufficient credits|rate limit|too many requests|capacity|overloaded/i.test(output);
@@ -137,7 +138,7 @@ check("server and TUI package specs resolve to different modules", installedPack
 const opencodeCheck = spawnSync("opencode", ["--version"], { encoding: "utf8" });
 if (opencodeCheck.status !== 0) {
 	console.log("SKIP: opencode CLI is not available in PATH. Package checks passed; skipping live runtime load tests.");
-	rmSync(testDir, { recursive: true, force: true });
+	if (!process.env.WG_E2E_KEEP) rmSync(testDir, { recursive: true, force: true });
 	console.log(`\n${pass} passed, ${fail} failed`);
 	process.exit(fail > 0 ? 1 : 0);
 }
@@ -149,20 +150,41 @@ mkdirSync(pluginsDir, { recursive: true });
 
 // Pre-seed .opencode with dependencies already installed into testDir
 // so opencode does not execute a cold network install at runtime startup.
-const opencodeVersion = opencodeCheck.stdout.trim();
+const opencodeVersionRaw = opencodeCheck.stdout.trim();
+const opencodeSemver = opencodeVersionRaw.match(/(\d+\.\d+\.\d+)/)?.[1] ?? opencodeVersionRaw;
+const opencodeMajor = Number(opencodeSemver.split(".")[0] ?? 1);
+const isOpenCodeV2 = opencodeMajor >= 2;
 const lockPath = join(testDir, "package-lock.json");
 if (existsSync(lockPath) && existsSync(join(testDir, "node_modules"))) {
 	try {
 		const lock = JSON.parse(readFileSync(lockPath, "utf8"));
 		lock.name = ".opencode";
-		if (lock.packages?.["node_modules/@opencode-ai/plugin"]) {
-			lock.packages["node_modules/@opencode-ai/plugin"].version = opencodeVersion;
+		const installedVersions: Record<string, string> = {};
+		for (const key of ["node_modules/@opencode-ai/plugin", "node_modules/@opencode/plugin"]) {
+			const version = lock.packages?.[key]?.version;
+			if (typeof version === "string" && version) installedVersions[key.replace("node_modules/", "")] = version;
 		}
-		if (lock.packages?.[""]) {
-			lock.packages[""].dependencies = { "@opencode-ai/plugin": opencodeVersion };
+		if (isOpenCodeV2) {
+			// V2 loads .opencode deps with the real installed versions; rewriting
+			// them to the CLI version string would produce invalid semver.
+			const dependencies: Record<string, string> = {};
+			for (const [name, version] of Object.entries(installedVersions)) dependencies[name] = version;
+			if (!Object.keys(dependencies).length) dependencies["@opencode/plugin"] = "latest";
+			if (lock.packages?.[""]) {
+				lock.packages[""].dependencies = dependencies;
+			}
+			writeFileSync(join(opencodeDir, "package-lock.json"), JSON.stringify(lock, null, 2) + "\n");
+			writeFileSync(join(opencodeDir, "package.json"), JSON.stringify({ name: ".opencode", dependencies }, null, 2) + "\n");
+		} else {
+			if (lock.packages?.["node_modules/@opencode-ai/plugin"]) {
+				lock.packages["node_modules/@opencode-ai/plugin"].version = opencodeSemver;
+			}
+			if (lock.packages?.[""]) {
+				lock.packages[""].dependencies = { "@opencode-ai/plugin": opencodeSemver };
+			}
+			writeFileSync(join(opencodeDir, "package-lock.json"), JSON.stringify(lock, null, 2) + "\n");
+			writeFileSync(join(opencodeDir, "package.json"), JSON.stringify({ name: ".opencode", dependencies: { "@opencode-ai/plugin": opencodeSemver } }, null, 2) + "\n");
 		}
-		writeFileSync(join(opencodeDir, "package-lock.json"), JSON.stringify(lock, null, 2) + "\n");
-		writeFileSync(join(opencodeDir, "package.json"), JSON.stringify({ name: ".opencode", dependencies: { "@opencode-ai/plugin": opencodeVersion } }, null, 2) + "\n");
 		cpSync(join(testDir, "node_modules"), join(opencodeDir, "node_modules"), { recursive: true });
 	} catch {}
 }
@@ -179,20 +201,63 @@ const importedMarker = join(testDir, ".workflow-guard-imported");
 const initializedMarker = join(testDir, ".workflow-guard-initialized");
 const accountabilityMarker = join(testDir, ".workflow-guard-accountability");
 writeFileSync(localAdapter, `import { writeFileSync } from "node:fs";
+import { Plugin } from "@opencode/plugin";
 
 writeFileSync(${JSON.stringify(importedMarker)}, "imported\\n");
 
-export const WorkflowGuardE2E = async (ctx: any) => {
-\tconst { WorkflowGuard } = await import("../workflow-guard-source/workflow-guard.ts");
-\tconst hooks = await WorkflowGuard(ctx);
-\tconst status = await hooks.tool?.guard_status?.execute({}, { sessionID: "headless-e2e", directory: ctx.directory, worktree: ctx.worktree });
-\tconst why = await hooks.tool?.guard_why?.execute({ tool: "bash", input: { command: "git push origin main" } }, { sessionID: "headless-e2e", directory: ctx.directory, worktree: ctx.worktree });
+// Load the shipped dual plugin: V1 probes call server(), V2 runs the real
+// setup(ctx) against the real plugin context and probes the REGISTERED tools.
+const loaded = await import("../workflow-guard-source/workflow-guard.ts");
+
+const headlessToolContext = { sessionID: "headless-e2e", agent: "build", messageID: "msg_headless", id: "call_headless", progress: async () => {} };
+
+const runV2Probes = async (ctx: any) => {
+\tawait loaded.default.setup(ctx);
+\tconst tools = await ctx.tool.list();
+\tconst byId = (id: string) => tools.find((t: any) => t.id === id);
+\tconst todowrite = byId("todowrite");
+\tconst guardStatus = byId("guard_status");
+\tconst guardWhy = byId("guard_why");
+\tconst pick = (r: any) => (typeof r?.content === "string" ? r.content : JSON.stringify(r));
+\tconst statusRes = guardStatus ? await guardStatus.execute({}, headlessToolContext) : undefined;
+\tconst whyRes = guardWhy ? await guardWhy.execute({ tool: "bash", input: { command: "git push origin main" } }, headlessToolContext) : undefined;
+\twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({
+\t\ttools: tools.map((t: any) => t.id),
+\t\ttodowriteEnriched: Boolean(todowrite?.description?.includes("Workflow Guard lifecycle")),
+\t\tstatus: JSON.parse(pick(statusRes)),
+\t\twhy: JSON.parse(pick(whyRes)),
+\t}) + "\\n");
+\twriteFileSync(${JSON.stringify(initializedMarker)}, "initialized\\n");
+};
+
+const runV1Probes = async (ctx: any) => {
+\tconst hooks = await loaded.default.server(ctx);
+\tconst directory = ctx?.location?.directory ?? ctx?.directory ?? process.cwd();
+\tconst toolCtx = { sessionID: "headless-e2e", directory, worktree: directory };
+\tconst status = await hooks.tool?.guard_status?.execute({}, toolCtx);
+\tconst why = await hooks.tool?.guard_why?.execute({ tool: "bash", input: { command: "git push origin main" } }, toolCtx);
 \twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({ status: JSON.parse(String(status)), why: JSON.parse(String(why)) }) + "\\n");
 \twriteFileSync(${JSON.stringify(initializedMarker)}, "initialized\\n");
 \treturn hooks;
 };
 
-export default { id: "workflow-guard-e2e", server: WorkflowGuardE2E };
+export default {
+\t...Plugin.define({
+\t\tid: "workflow-guard-e2e",
+\t\tasync setup(ctx: any) {
+\t\t\twriteFileSync(${JSON.stringify(importedMarker)}, "imported\\n");
+\t\t\ttry {
+\t\t\t\tawait runV2Probes(ctx);
+\t\t\t} catch (error) {
+\t\t\t\twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({ error: String((error as Error)?.message ?? error), stack: String((error as Error)?.stack ?? "") }) + "\\n");
+\t\t\t\tthrow error;
+\t\t\t}
+\t\t},
+\t}),
+\tserver: async (ctx: any) => {
+\t\treturn await runV1Probes(ctx);
+\t},
+};
 `);
 writeFileSync(join(testDir, ".opencode", "opencode.json"), `${JSON.stringify({ plugin: ["./plugins/workflow-guard.ts"] }, null, 2)}\n`);
 check("local plugin adapter and source copied successfully", existsSync(localAdapter) && existsSync(targetPlugin));
@@ -211,6 +276,13 @@ const runtimeEnv: NodeJS.ProcessEnv = {
 delete runtimeEnv.OPENCODE_PID;
 delete runtimeEnv.OPENCODE_PURE;
 delete runtimeEnv.OPENCODE;
+if (isOpenCodeV2) {
+	// V2 runs a shared managed service on a fixed default port. Each run uses
+	// its own isolated XDG dirs, so pick a run-unique port to keep concurrent
+	// and sequential runs from colliding on service startup.
+	const servicePort = 49400 + (process.pid % 1000);
+	spawnSync("opencode", ["service", "set", "port", String(servicePort)], { cwd: testDir, encoding: "utf8", env: runtimeEnv, timeout: 30_000 });
+}
 const runOpenCode = (args: string[], timeout: number) =>
 	spawnSync("opencode", ["run", "--dir", testDir, ...args], { cwd: testDir, encoding: "utf8", timeout, env: runtimeEnv });
 const configProbe = await new Promise<{ status: number | null; stdout: string; stderr: string }>((resolve) => {
@@ -229,7 +301,11 @@ const configProbe = await new Promise<{ status: number | null; stdout: string; s
 
 	const checkReady = () => {
 		try {
-			if (JSON.parse(stdout)?.plugin_origins && existsSync(initializedMarker)) {
+			const parsed = JSON.parse(stdout);
+			// V1 prints an object with plugin_origins; V2 prints a config document
+			// array. Either way, the adapter's setup/server must have run.
+			const hasConfig = Boolean(parsed?.plugin_origins) || Array.isArray(parsed);
+			if (hasConfig && existsSync(initializedMarker)) {
 				done(0);
 			}
 		} catch {}
@@ -247,26 +323,52 @@ const configProbe = await new Promise<{ status: number | null; stdout: string; s
 
 	timer = setTimeout(() => done(null), 30_000);
 });
+if (isOpenCodeV2) {
+	// V2's debug config can exit before plugin setup completes; wait briefly
+	// for the adapter's initialized marker before evaluating plugin checks.
+	for (let i = 0; i < 200 && !existsSync(initializedMarker); i++) {
+		await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+}
 let configLoadsLocalPlugin = false;
 try {
-	const config = JSON.parse(configProbe.stdout);
-	configLoadsLocalPlugin = config.plugin_origins?.some(
-		(origin: { spec?: unknown; source?: unknown; scope?: unknown }) =>
-			typeof origin.spec === "string" &&
-			origin.spec.endsWith("/.opencode/plugins/workflow-guard.ts") &&
-			origin.scope === "local",
-	);
+	if (isOpenCodeV2) {
+		// V2 has no plugin_origins in debug config output; the adapter's setup
+		// writing the imported marker is the plugin-load proof.
+		configLoadsLocalPlugin = existsSync(importedMarker) && existsSync(initializedMarker);
+	} else {
+		const config = JSON.parse(configProbe.stdout);
+		configLoadsLocalPlugin = config.plugin_origins?.some(
+			(origin: { spec?: unknown; source?: unknown; scope?: unknown }) =>
+				typeof origin.spec === "string" &&
+				origin.spec.endsWith("/.opencode/plugins/workflow-guard.ts") &&
+				origin.scope === "local",
+		);
+	}
 } catch {}
-check("OpenCode resolves isolated local plugin config without a model provider", configProbe.status === 0 && configLoadsLocalPlugin);
+const configCheckPassed = Boolean(check("OpenCode resolves isolated local plugin config without a model provider", configProbe.status === 0 && configLoadsLocalPlugin));
+if (!configCheckPassed) {
+	console.log(`  configProbe stderr: ${configProbe.stderr.slice(0, 2000)}`);
+	console.log(`  configProbe stdout: ${configProbe.stdout.slice(0, 2000)}`);
+	console.log(`  importedMarker: ${existsSync(importedMarker)} initializedMarker: ${existsSync(initializedMarker)}`);
+}
 let headlessAccountability: any;
 try {
 	headlessAccountability = JSON.parse(readFileSync(accountabilityMarker, "utf8"));
 } catch {}
 check("headless OpenCode runtime exposes structured guard status and why without TUI", headlessAccountability?.status?.workspaceRoot === testDir && headlessAccountability?.why?.policy === "git" && headlessAccountability?.why?.code === "protected_branch_push");
+if (isOpenCodeV2) {
+	// The V2 adapter runs the shipped setup(ctx) for real; verify the
+	// registered tool surface. Builtin description enrichment is best-effort:
+	// builtins are not visible to ctx.tool.list() during plugin setup, so
+	// todowriteEnriched is reported but not asserted.
+	check("V2 setup registers custom guard tools", (headlessAccountability?.tools ?? []).includes("guard_status") && (headlessAccountability?.tools ?? []).includes("guard_why"));
+	console.log(`  note: builtin todowrite description enriched under V2: ${headlessAccountability?.todowriteEnriched === true ? "yes" : "unknown at setup time"}`);
+}
 
 if (process.env.WORKFLOW_GUARD_LIVE_E2E !== "1") {
 	console.log("SKIP: model-driven policy probes require WORKFLOW_GUARD_LIVE_E2E=1.");
-	rmSync(testDir, { recursive: true, force: true });
+	if (!process.env.WG_E2E_KEEP) rmSync(testDir, { recursive: true, force: true });
 	console.log(`\n${pass} passed, ${fail} failed`);
 	process.exit(fail > 0 ? 1 : 0);
 }
@@ -286,7 +388,7 @@ try {
 const liveModel = process.env.WORKFLOW_GUARD_LIVE_MODEL?.trim() || recentModel;
 if (!liveModel) {
 	console.error(`FAIL: no recent OpenCode model found in ${recentModelPath}; select a model in OpenCode or set WORKFLOW_GUARD_LIVE_MODEL=provider/model.`);
-	rmSync(testDir, { recursive: true, force: true });
+	if (!process.env.WG_E2E_KEEP) rmSync(testDir, { recursive: true, force: true });
 	process.exit(1);
 }
 console.log(`  Using live model: ${liveModel}`);
@@ -337,7 +439,7 @@ if (!run3AccountedFor) {
 }
 
 // Clean up
-rmSync(testDir, { recursive: true, force: true });
+if (!process.env.WG_E2E_KEEP) rmSync(testDir, { recursive: true, force: true });
 
 console.log(`\n${pass} passed, ${fail} failed, ${unavailable} live unavailable`);
 process.exit(fail ? 1 : 0);