opencode-workflow-guard 1.13.6 → 1.14.0

package/docs/policies.md

@@ -64,6 +64,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - Quoted data spans are not shell syntax: pattern matching runs on the quote-stripped residue, where redirect targets are honored quoted or not and quote-concatenated paths keep normalizing. A quoted span containing a guarded path is never treated as a redirect or command verb; unquoted redirects into guarded paths stay blocked.
 - Plan files under `.opencode/plans/` are exempt: opencode's plan mode writes agent-authored plan markdown there, and plans are content, not configuration. Everything else under `.opencode/` (including the directory itself) stays protected.
 - **Read-only access is allowed** (`cat`, `less`, `grep`, `head`, `tail` on config files) - only modification attempts trigger the guard.
+- **Live control-plane facts (`liveControlPlanePaths`, opt-in):** declare the absolute paths of the live control plane (for example `~/.config/opencode`, or the guard's own install) in `.opencode/workflow-guard.json` or via `WORKFLOW_GUARD_LIVE_CONTROL_PLANE_PATHS` (comma-separated). When set, config-path protection classifies by runtime consumption instead of filename segments: only targets that resolve under a live root are protected (symlink-aware), so copying **from** a config path into a sanctioned workspace draft is no longer blocked (the copy destination is what matters) and versioned drafts such as a project `.opencode/` or a dotfiles `.config/opencode` are editable. Roots must be absolute (`~`/`$HOME` are expanded); an unusable root rejects the whole set and falls back to the legacy fail-closed segment matching. Unset keeps the legacy behavior.
 
 ### 7. Feature-Branch Workflow
 - When the workspace git repository is on `main` or `master`, all file mutations and history-changing git commands (`commit`, `merge`, `rebase`, `cherry-pick`, `revert`, `apply`, `am`, `reset`, `restore`, `stash pop`, `update-ref`, `filter-branch`, `branch -D/-M`) are blocked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.13.6",
+  "version": "1.14.0",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/guard-dispatcher.ts

@@ -5,6 +5,7 @@ import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidenc
 import { findGitRoot, isSameGitRepo, projectRootKey } from "./project-config.ts";
 import {
 	getLastReviewResult,
+	getLiveControlPlaneRoots,
 	getSdkClient,
 	getWorkspaceRoot,
 	isDocumentationRequired,
@@ -343,7 +344,7 @@ export async function guardToolCallImpl(
 				return block("git", "branch_base_behind", `Blocked: ${behindCheck.reason}`);
 			}
 		}
-		if (isSettingsTamper(command)) {
+		if (isSettingsTamper(command, getLiveControlPlaneRoots(currentRoot))) {
 			logPolicyBlock(`[workflow-guard] blocked settings tamper: ${command.slice(0, 120)}`);
 			return block("tamper", "settings_tamper", PROTECTED_PATH_REASON);
 		}

package/src/lib/live-control-plane.ts

@@ -0,0 +1,74 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+/**
+ * Expands a leading `~`/`~user`/`$HOME`/`${HOME}` in a declared path and
+ * rejects any remaining unresolved `$VARIABLE` (returns undefined so callers
+ * fail closed rather than treating an unresolvable root as absent).
+ */
+export function expandLivePath(value: string): string | undefined {
+	const trimmed = value.trim().replace(/^["']|["']$/g, "");
+	if (!trimmed) return undefined;
+	const home = process.env.HOME || homedir();
+	let out = trimmed;
+	if (out === "~") {
+		out = home;
+	} else if (out.startsWith("~/") || out.startsWith("~\\")) {
+		out = join(home, out.slice(2));
+	} else if (/^~[A-Za-z0-9_.-]+(?:\/|\\|$)/.test(out)) {
+		const parts = out.slice(1).split(/[/\\]/);
+		out = join(dirname(home), parts[0]!, ...parts.slice(1));
+	} else if (/^\$(?:HOME|\{HOME\})(?=$|[/\\])/.test(out)) {
+		out = out.replace(/^\$(?:HOME|\{HOME\})/, home);
+	}
+	if (out.includes("$")) return undefined;
+	return out;
+}
+
+/**
+ * Normalizes the host-declared live control-plane roots. A root is usable only
+ * when it expands (no unresolved `$VAR`) and is absolute; on ANY unusable root
+ * the whole set is rejected (undefined) so classification falls back to the
+ * fail-closed legacy segment matching rather than trusting partial facts.
+ */
+export function normalizeLiveControlPlaneRoots(
+	values: readonly string[] | undefined,
+): readonly string[] | undefined {
+	if (!values || values.length === 0) return undefined;
+	const roots: string[] = [];
+	for (const value of values) {
+		const expanded = expandLivePath(value);
+		if (expanded === undefined || !isAbsolute(expanded)) return undefined;
+		roots.push(resolve(expanded));
+	}
+	return roots;
+}
+
+function realpathWithMissingTail(path: string): string | undefined {
+	let ancestor = path;
+	while (true) {
+		try {
+			return resolve(realpathSync(ancestor), relative(ancestor, path));
+		} catch {
+			const parent = dirname(ancestor);
+			if (parent === ancestor) return undefined;
+			ancestor = parent;
+		}
+	}
+}
+
+/** True when `candidate` is, or is nested under, any root (root realpath-aware). */
+export function pathWithinAnyRoot(candidate: string, roots: readonly string[]): boolean {
+	return roots.some((root) => {
+		const realRoot = realpathWithMissingTail(resolve(root)) ?? resolve(root);
+		const rel = relative(realRoot, candidate);
+		return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+	});
+}
+
+/** Symlink-aware variant: resolves `candidate`'s existing ancestor before matching. */
+export function realpathWithinAnyRoot(candidate: string, roots: readonly string[]): boolean {
+	const real = realpathWithMissingTail(candidate);
+	return real !== undefined && real !== candidate && pathWithinAnyRoot(real, roots);
+}

package/src/lib/state.ts

@@ -4,6 +4,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
 import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
+import { normalizeLiveControlPlaneRoots } from "./live-control-plane.ts";
 import type {
 	TodoSdkClient,
 	ProjectConfig,
@@ -305,6 +306,20 @@ export function getProjectConfig(root: string): ProjectConfig {
 	return getCachedProjectConfig(root) ?? loadProjectConfig(root);
 }
 
+/**
+ * The host-declared live control-plane roots: `WORKFLOW_GUARD_LIVE_CONTROL_PLANE_PATHS`
+ * (comma-separated) overrides, else project config `liveControlPlanePaths`.
+ * Returns undefined when unset or when any declared root is unusable, so
+ * callers fall back to the legacy fail-closed segment matching.
+ */
+export function getLiveControlPlaneRoots(root: string = getWorkspaceRoot()): readonly string[] | undefined {
+	const env = process.env.WORKFLOW_GUARD_LIVE_CONTROL_PLANE_PATHS;
+	if (env && env.trim()) {
+		return normalizeLiveControlPlaneRoots(env.split(",").map((value) => value.trim()).filter(Boolean));
+	}
+	return normalizeLiveControlPlaneRoots(getProjectConfig(root).liveControlPlanePaths);
+}
+
 export function isReviewRequired(root: string): boolean {
 	const env = process.env.WORKFLOW_GUARD_REQUIRE_REVIEW?.toLowerCase();
 	if (env === "0" || env === "false" || env === "off") return false;

package/src/lib/types.ts

@@ -35,6 +35,15 @@ export interface ProjectConfig {
 	}>;
 	requireReview?: boolean;
 	requireDocumentation?: boolean;
+	/**
+	 * Absolute paths of the LIVE control plane (runtime `~/.config/opencode`,
+	 * the guard's own install). When set, config-path protection classifies by
+	 * runtime consumption instead of filename segments: only targets under a
+	 * live root are protected, while versioned drafts (project `.opencode/`,
+	 * dotfiles `.config/opencode`, worktrees) are not. Unset keeps the legacy
+	 * fail-closed segment matching.
+	 */
+	liveControlPlanePaths?: string[];
 	recoveryCheckpoints?: boolean;
 	projectMemory?: boolean;
 	learning?: boolean;

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

@@ -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,

package/test/test.mts

@@ -3915,6 +3915,43 @@ check("project-memory initialization failure leaves core guard hooks active", ty
 if (prevDataHome === undefined) delete process.env.XDG_DATA_HOME;
 else process.env.XDG_DATA_HOME = prevDataHome;
 
+console.log("- live control-plane paths (tier port: config-path facts) -");
+const liveBase = mkdtempSync(join(tmpdir(), "wg-lcp-base-"));
+const livePlane = join(liveBase, ".config", "open" + "code");
+mkdirSync(livePlane, { recursive: true });
+const lcpRoot = mkdtempSync(join(tmpdir(), "wg-lcp-root-"));
+mkdirSync(join(lcpRoot, ".opencode"), { recursive: true });
+const ocJson = "open" + "code.json";
+const ocJsonc = "open" + "code.jsonc";
+setWorkspaceRoot(root);
+
+// Legacy (no live roots configured): the copy SOURCE under a config path alone
+// blocks the command — the F3 false positive, pinned as current behavior.
+check("legacy: cp FROM a .config/opencode source is blocked without live roots", blocked(await call("bash", { command: `cp ${livePlane}/agent/x.md ./draft.md` }, { sessionID: "s-active" })));
+
+// Declare the live control plane via project config, then reload.
+writeFileSync(join(lcpRoot, ".opencode", "workflow-guard.json"), JSON.stringify({ liveControlPlanePaths: [livePlane] }));
+reloadProjectConfig(lcpRoot);
+setWorkspaceRoot(lcpRoot);
+
+// With facts: the same copy is allowed — the SOURCE is no longer matched and
+// the destination is a sanctioned workspace draft (F3 fixed).
+check("facts: cp FROM live config into a workspace draft is allowed", !(await call("bash", { command: `cp ${livePlane}/agent/x.md ./draft.md` }, { sessionID: "s-active" })));
+// The live destination stays protected.
+check("facts: cp INTO the live config is blocked", blocked(await call("bash", { command: `cp ./draft.md ${livePlane}/agent/x.md` }, { sessionID: "s-active" })));
+check("facts: redirect into the live config is blocked", blocked(await call("bash", { command: `echo x > ${livePlane}/${ocJsonc}` }, { sessionID: "s-active" })));
+// A config-shaped draft inside the workspace is allowed.
+check("facts: write to a project .opencode draft is allowed", !(await call("write", { filePath: join(lcpRoot, ".opencode", ocJson), content: "{}" }, { sessionID: "s-active" })));
+
+// An unusable declared root rejects the whole fact set -> fail-closed legacy.
+writeFileSync(join(lcpRoot, ".opencode", "workflow-guard.json"), JSON.stringify({ liveControlPlanePaths: ["relative/dir"] }));
+reloadProjectConfig(lcpRoot);
+check("facts: an unusable declared root falls back to legacy segment matching", blocked(await call("write", { filePath: join(lcpRoot, ".opencode", ocJson), content: "{}" }, { sessionID: "s-active" })));
+
+setWorkspaceRoot(root);
+rmSync(lcpRoot, { recursive: true, force: true });
+rmSync(liveBase, { recursive: true, force: true });
+
 rmSync(root, { recursive: true, force: true });
 if (prevLive !== undefined) process.env.WORKFLOW_GUARD_ALLOW_LIVE = prevLive;
 console.log(`\n${pass} passed, ${fail} failed`);