opencode-workflow-guard 1.6.0 → 1.7.1

package/README.md

@@ -12,7 +12,13 @@ OpenCode plugin enforcing workflow discipline, agent focus, and deterministic sa
 
 ### 1. Installation
 
-Add to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:
+Run the setup command to register both the server guard and TUI companion globally:
+
+```bash
+npx opencode-workflow-guard setup
+```
+
+For server-only setup, add the package to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -23,9 +29,9 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
 }
 ```
 
-*Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for full setup options and TUI companion badge configuration.
+*Requires OpenCode >= 1.18.* Restart OpenCode after setup. See [docs/installation.md](docs/installation.md) for full setup options.
 
-For the optional TUI badge, configure `"opencode-workflow-guard/tui"` in `tui.json`. The package root is the server plugin; TUI plugin specs are resolved as written and must use the exported `./tui` entrypoint. Do not place the TUI module under the server `plugins/` directory.
+For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. Do not place the TUI module under the server `plugins/` directory.
 
 ### 2. Verification
 

package/bin/opencode-workflow-guard.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse, modify, applyEdits } from "jsonc-parser";
+
+const SERVER_SPEC = "opencode-workflow-guard";
+const TUI_SPEC = "opencode-workflow-guard";
+const LEGACY_TUI_SPEC = "opencode-workflow-guard/tui";
+
+function configHome() {
+	return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+function existingConfig(base, name) {
+	const json = join(base, name + ".json");
+	const jsonc = join(base, name + ".jsonc");
+	return existsSync(json) ? json : existsSync(jsonc) ? jsonc : json;
+}
+
+function preparePluginUpdate(path, schema, spec, legacySpec) {
+	const source = existsSync(path) ? readFileSync(path, "utf8") : `{
+  "$schema": "${schema}"
+}\n`;
+	const errors = [];
+	const config = parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+	if (errors.length > 0 || !config || typeof config !== "object" || Array.isArray(config)) {
+		throw new Error(`Cannot update invalid config: ${path}`);
+	}
+	if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+		throw new Error(`Cannot update ${path}: "plugin" must be an array`);
+	}
+	const plugins = config.plugin ?? [];
+	const matches = (entry, target) => entry === target || (Array.isArray(entry) && entry[0] === target);
+	if (!legacySpec) {
+		if (plugins.some((entry) => matches(entry, spec))) return undefined;
+		return applyEdits(source, modify(source, ["plugin", plugins.length], spec, {
+			formattingOptions: { insertSpaces: true, tabSize: 2 },
+		}));
+	}
+	const updatedPlugins = plugins.filter((entry) => !matches(entry, legacySpec));
+	if (!updatedPlugins.some((entry) => matches(entry, spec))) updatedPlugins.push(spec);
+	if (updatedPlugins.length === plugins.length && updatedPlugins.every((entry, index) => entry === plugins[index])) return undefined;
+	return applyEdits(source, modify(source, ["plugin"], updatedPlugins, {
+		formattingOptions: { insertSpaces: true, tabSize: 2 },
+	}));
+}
+
+if (process.argv[2] !== "setup" || process.argv.length > 3) {
+	console.error("Usage: opencode-workflow-guard setup");
+	process.exitCode = 1;
+} else {
+	try {
+		const base = join(configHome(), "opencode");
+		const serverPath = existingConfig(base, "opencode");
+		const tuiPath = existingConfig(base, "tui");
+		const serverUpdate = preparePluginUpdate(serverPath, "https://opencode.ai/config.json", SERVER_SPEC);
+		const tuiUpdate = preparePluginUpdate(tuiPath, "https://opencode.ai/tui.json", TUI_SPEC, LEGACY_TUI_SPEC);
+		mkdirSync(base, { recursive: true });
+		if (serverUpdate !== undefined) writeFileSync(serverPath, serverUpdate);
+		if (tuiUpdate !== undefined) writeFileSync(tuiPath, tuiUpdate);
+		console.log(`Workflow Guard configured in ${serverPath} and ${tuiPath}.`);
+		console.log("Restart OpenCode to load both plugins.");
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",
   "main": "src/workflow-guard.ts",
+  "bin": {
+    "opencode-workflow-guard": "./bin/opencode-workflow-guard.mjs"
+  },
   "exports": {
     ".": "./src/workflow-guard.ts",
     "./server": "./src/workflow-guard.ts",
@@ -18,6 +21,7 @@
     "url": "git+https://github.com/ultus-net/opencode-workflow-guard.git"
   },
   "files": [
+    "bin/",
     "src/",
     "README.md",
     "LICENSE",

package/src/lib/custom-tools.ts

@@ -183,7 +183,7 @@ export function createCustomTools(options: {
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree creation with no active todo item. Break the request down with todowrite first, then create worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot); if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}`;
-				recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID); return `[workflow-guard] Worktree created successfully at: ${res.worktreePath}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
+				recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID); return `[workflow-guard] Worktree created successfully at: ${res.worktreePath}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
 			},
 		}),
 		guard_worktree_cleanup: tool({
@@ -191,7 +191,7 @@ export function createCustomTools(options: {
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree cleanup with no active todo item. Break the request down with todowrite first, then clean up worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = cleanupGitWorktree(args.worktreePath, toolRoot); if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
-				recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID); return `[workflow-guard] Worktree at '${args.worktreePath}' cleaned up successfully.`;
+				recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID); return `[workflow-guard] Worktree at '${args.worktreePath}' cleaned up successfully.`;
 			},
 		}),
 	};

package/src/lib/guard-dispatcher.ts

@@ -24,6 +24,7 @@ import {
 	unwrapShellCommand,
 } from "./shell.ts";
 import { asRecord, extractTargetPath } from "./utils.ts";
+import { getProjectMemoryIdentity } from "./project-memory.ts";
 import {
 	detectVerifyCommand,
 	getCurrentGitCommitHash,
@@ -272,7 +273,7 @@ export async function guardToolCallImpl(
 				return claimReason;
 			}
 		}
-		recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+		recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
 		return undefined;
 	}
 
@@ -285,6 +286,11 @@ export async function guardToolCallImpl(
 		}
 	}
 	if (!SHELL_TOOL_NAMES.has(toolName)) return undefined;
+	const shellWorkdir = asRecord(input)?.workdir;
+	const requestedShellRoot = typeof shellWorkdir === "string" ? resolve(currentRoot, shellWorkdir) : currentRoot;
+	const shellRoot = !isPathOutsideWorkspace(requestedShellRoot, currentRoot) || getProjectMemoryIdentity(requestedShellRoot) === getProjectMemoryIdentity(currentRoot)
+		? requestedShellRoot
+		: currentRoot;
 
 	for (const raw of extractCommands(input)) {
 		const dynamicSyntax = dynamicShellSyntaxIn(raw);
@@ -348,7 +354,7 @@ export async function guardToolCallImpl(
 				if (onProtectedBranch(currentRoot)) return branchGuardReason();
 				const todos = await effectiveTodos(context?.sessionID);
 				if (todos !== undefined && !hasActiveTodo(todos)) return "Blocked: inline interpreter file mutation with no active todo item.";
-				recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+				recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
 			}
 			if (!allowLive) {
 				const liveCheck = liveMutationIn(normalizeGitCommands(normalize(payload)));
@@ -402,24 +408,25 @@ export async function guardToolCallImpl(
 			}
 		}
 		if (hasPrCreateInvocation(raw)) {
+			const prRoot = shellRoot;
 			const isAz = /\baz\s+repos\s+pr\s+create\b/.test(normalizedCommand);
 			const prTool = isAz ? "az repos pr create" : "gh pr create";
 			const descFlag = isAz ? "--description" : "--body";
 			const preflightFailures: string[] = [];
-			const conflictCheck = checkMergeConflicts(currentRoot);
+			const conflictCheck = checkMergeConflicts(prRoot);
 			if (conflictCheck.hasConflicts) preflightFailures.push(conflictCheck.reason ?? "Branch has merge conflicts with its base branch.");
-			const branch = currentGitBranch(currentRoot);
+			const branch = currentGitBranch(prRoot);
 			if (branch) {
-				const mergedStatus = isBranchAlreadyMergedOrClosed(currentRoot, branch);
+				const mergedStatus = isBranchAlreadyMergedOrClosed(prRoot, branch);
 				if (mergedStatus.merged) preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
 			}
-			if (isReviewRequired(currentRoot)) {
+			if (isReviewRequired(prRoot)) {
 				const review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
-				const reviewMatchesContext = review?.passed === true && review.workspace === resolve(currentRoot) && (!review.targetSessionID || review.targetSessionID === context?.sessionID) && review.commitHash === getCurrentGitCommitHash(currentRoot) && review.gitStatus === getGitStatusSummary(currentRoot) && review.worktreeFingerprint === getGitWorktreeFingerprint(currentRoot);
+				const reviewMatchesContext = review?.passed === true && review.workspace === resolve(prRoot) && (!review.targetSessionID || review.targetSessionID === context?.sessionID) && review.commitHash === getCurrentGitCommitHash(prRoot) && review.gitStatus === getGitStatusSummary(prRoot) && review.worktreeFingerprint === getGitWorktreeFingerprint(prRoot);
 				if (!reviewMatchesContext) preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
 			}
-			if (isDocumentationRequired(currentRoot) && !branchHasDocumentationChange(currentRoot)) preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
-			const branchChangelog = branchHasChangelogChange(currentRoot);
+			if (isDocumentationRequired(prRoot) && !branchHasDocumentationChange(prRoot)) preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
+			const branchChangelog = branchHasChangelogChange(prRoot);
 			let shellCwdKnown = true;
 			const prSegments: Array<{ segment: string; invocationRoot: string | null }> = [];
 			for (const segment of splitShellSegments(raw)) {
@@ -427,12 +434,12 @@ export async function guardToolCallImpl(
 				if (/(?:^|\s)(?:(?:builtin|command)\s+)?(?:cd|pushd|popd)(?:\s|$)/.test(unwrapped)) shellCwdKnown = false;
 				if (hasPrCreateInvocation(segment)) {
 					const wrapperChangesCwd = shellWrappersChangeCwd(segment);
-					prSegments.push({ segment, invocationRoot: shellCwdKnown && !wrapperChangesCwd ? currentRoot : null });
+					prSegments.push({ segment, invocationRoot: shellCwdKnown && !wrapperChangesCwd ? prRoot : null });
 				}
 			}
 			const hasChangelog = branchChangelog || prSegments.every(({ segment, invocationRoot }) => prBodyIncludesChangelog(segment, invocationRoot));
 			if (!hasChangelog) preflightFailures.push(`Release information is required; update a CHANGELOG/changeset file or include a Summary, Changes, Release notes, or Changelog section in the PR description (${descFlag}).`);
-			const lockCheck = checkLockfileSync(currentRoot);
+			const lockCheck = checkLockfileSync(prRoot);
 			if (lockCheck.isOutOfSync) preflightFailures.push(lockCheck.reason ?? "Dependency lockfile is out of sync with its manifest.");
 			if (preflightFailures.length > 0) {
 				const reason = `Blocked: PR preflight failed:\n${preflightFailures.map((failure) => `- ${failure}`).join("\n")}`;
@@ -465,7 +472,7 @@ export async function guardToolCallImpl(
 				}
 			}
 		}
-		if (hasGitMutation) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+		if (hasGitMutation) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
 	}
 	return undefined;
 }

package/src/lib/project-memory.ts

@@ -39,9 +39,9 @@ export function ensureProjectMemoryExcluded(root: string): boolean {
 export function isProjectMemoryFresh(memory: ProjectMemoryRecord, root: string): boolean {
 	if (!memory.commit || memory.paths.length === 0) return true;
 	if (!/^[0-9a-f]{7,64}$/i.test(memory.commit)) return false;
-	const result = spawnSync("git", ["-C", root, "diff", "--quiet", memory.commit, "--", ...memory.paths], { encoding: "utf8" });
+	const result = spawnSync("git", ["-C", root, "diff", "--quiet", memory.commit, "--", ...memory.paths], { encoding: "utf8", timeout: 2_000 });
 	if (result.status !== 0) return false;
-	const untracked = spawnSync("git", ["-C", root, "ls-files", "--others", "--exclude-standard", "--", ...memory.paths], { encoding: "utf8" });
+	const untracked = spawnSync("git", ["-C", root, "ls-files", "--others", "--exclude-standard", "--", ...memory.paths], { encoding: "utf8", timeout: 2_000 });
 	return untracked.status === 0 && !untracked.stdout.trim();
 }
 

package/src/lib/state.ts

@@ -79,16 +79,16 @@ export const sessionVerifyResults = new Map<string, NonNullable<VerifyResult>>()
 export let lastReview: ReviewResult | undefined;
 export const sessionReviews = new Map<string, ReviewResult>();
 
-export function recordMutation(sessionID?: string): void {
+export function recordMutation(sessionID?: string, actorSessionID?: string): void {
 	lastMutationTimestamp = Date.now();
 	mutationCount++;
-	if (sessionID) {
-		sessionMutationTimestamps.set(sessionID, lastMutationTimestamp);
-		sessionMutationCounts.set(sessionID, (sessionMutationCounts.get(sessionID) ?? 0) + 1);
-		sessionVerifyResults.delete(sessionID);
+	for (const id of new Set([sessionID, actorSessionID].filter((value): value is string => Boolean(value)))) {
+		sessionMutationTimestamps.set(id, lastMutationTimestamp);
+		sessionMutationCounts.set(id, (sessionMutationCounts.get(id) ?? 0) + 1);
+		sessionVerifyResults.delete(id);
+		sessionReviews.delete(id);
 	}
-	if (sessionID) sessionReviews.delete(sessionID);
-	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID) {
+	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID || lastReview.targetSessionID === actorSessionID) {
 		lastReview = undefined;
 	}
 }
@@ -100,6 +100,10 @@ export function getMutationCount(sessionID?: string): number {
 	return mutationCount;
 }
 
+export function getSessionMutationCount(sessionID: string): number {
+	return sessionMutationCounts.get(sessionID) ?? 0;
+}
+
 export function getLastMutationTimestamp(): number {
 	return lastMutationTimestamp;
 }

package/src/policies/boundary.ts

@@ -384,7 +384,7 @@ export async function guardShellMutation(
 		}
 	}
 	if (hasMutation) {
-		recordMutation(await effectiveTodoOwnerSessionID(sessionID));
+		recordMutation(await effectiveTodoOwnerSessionID(sessionID), sessionID);
 	}
 	return undefined;
 }

package/src/policies/todo.ts

@@ -1,5 +1,5 @@
 import type { TodoItem } from "../lib/types.ts";
-import { getMutationCount, getSdkClient, getSubagentMutationBudget } 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"]);
@@ -28,7 +28,7 @@ export async function subagentMutationBudgetReason(
 	root: string,
 ): Promise<string | undefined> {
 	if (!await fetchParentSessionID(sessionID)) return undefined;
-	const count = getMutationCount(sessionID);
+	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.`;

package/src/workflow-guard-ui.ts

@@ -29,7 +29,7 @@ function text(props: Record<string, unknown>, children: Child[]) {
 	return element("text", props, children);
 }
 
-const BADGE_ACTIVE = "[Workflow Guard: Active]";
+const BADGE_ACTIVE = "Workflow Guard 🛡️";
 let lastBlockedReason: string | undefined;
 const sessionBlockedReasons = new Map<string, string>();
 const badgeNodes = new Map<string, unknown>();

package/src/workflow-guard.ts

@@ -47,6 +47,7 @@ import {
 	lastMutationTimestamp,
 	getLastMutationTimestamp,
 	getMutationCount,
+	getSessionMutationCount,
 	lastVerify,
 	getLastVerifyResult,
 	recordMutation,
@@ -447,20 +448,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					return s === "pending" || s === "in_progress";
 				});
 				const branch = currentGitBranch(effectiveRoot) ?? "unknown";
-				const isProtected = onProtectedBranch(effectiveRoot);
+				const isProtected = branch !== "unknown" && isProtectedBranchName(branch, effectiveRoot);
+				const sessionMutationCount = sessionID ? getSessionMutationCount(sessionID) : 0;
 				const lastV = sessionID
-					? (sessionVerifyResults.get(sessionID) ?? lastVerify)
+					? (sessionVerifyResults.get(sessionID) ?? (sessionMutationCount === 0 && parentID ? sessionVerifyResults.get(parentID) : undefined))
 					: lastVerify;
-				const lastR = getLastReviewResult();
-				const mutationCountVal = getMutationCount(sessionID);
+				const lastR = sessionID
+					? (sessionReviews.get(sessionID) ?? (sessionMutationCount === 0 && parentID ? sessionReviews.get(parentID) : undefined))
+					: getLastReviewResult();
+				const mutationCountVal = sessionID ? sessionMutationCount : getMutationCount();
 
 				const contextBlocks: string[] = [];
 
 				if (active && active.length > 0) {
-					const lines = active.map(
+					const lines = active.slice(0, 20).map(
 						(t) =>
-							`- [${String(t.status) === "in_progress" ? "IN PROGRESS" : "PENDING"}] ${String(t.content ?? "")}`,
+							`- [${String(t.status) === "in_progress" ? "IN PROGRESS" : "PENDING"}] ${String(t.content ?? "").slice(0, 300)}`,
 					);
+					if (active.length > 20) lines.push(`- ... ${active.length - 20} more active task(s) omitted`);
 					const attribution = parentID
 						? ` (Subagent session: ${sessionID}, Parent: ${parentID})`
 						: sessionID
@@ -488,15 +493,18 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						`- Secondary Review: ${lastR.passed ? "APPROVED" : "CHANGES REQUESTED"} by ${lastR.reviewer}`,
 					);
 				}
-				const openFollowups = followupStore ? listReviewFollowups(followupStore, "open", 8) : [];
+				let openFollowups: ReturnType<typeof listReviewFollowups> = [];
+				try { openFollowups = followupStore ? listReviewFollowups(followupStore, "open", 8) : []; } catch {}
 				if (openFollowups.length > 0) {
 					stateLines.push(`- Open Review Follow-ups: ${openFollowups.length} local P2/P3 item(s)`);
 					contextBlocks.push(`## Review Follow-ups\n${openFollowups.map((item) => `- [${item.severity}:${item.id.slice(0, 8)}] ${item.summary.slice(0, 300)}`).join("\n")}\nTreat these as durable technical debt: address relevant items when practical and resolve them explicitly after verification.`);
 				}
 				contextBlocks.push(stateLines.join("\n"));
-				const projectKnowledge = (projectMemory ? getRecentProjectMemory(projectMemory, 20) : [])
-					.filter((memory) => memory.source !== "portable" && isProjectMemoryFresh(memory, effectiveRoot))
-					.slice(0, 8);
+				let projectKnowledge: ReturnType<typeof getRecentProjectMemory> = [];
+				try {
+					projectKnowledge = (projectMemory ? getRecentProjectMemory(projectMemory, 8) : [])
+						.filter((memory) => memory.source !== "portable" && isProjectMemoryFresh(memory, effectiveRoot));
+				} catch {}
 				if (projectKnowledge.length > 0) {
 					const lines = projectKnowledge.map((memory) => `- [${memory.kind}:${memory.id.slice(0, 8)}] ${memory.content.slice(0, 300)}`);
 					contextBlocks.push(`## Project Memory\n${lines.join("\n")}\nTreat these as historical project knowledge; verify against current repository state when relevant files have changed.`);