opencode-workflow-guard 1.13.5 → 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.
@@ -90,6 +91,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list; subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
 - Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider/model parameters.
 - **Git State & Snapshot Binding:** Verification evidence records the current git commit hash (`git rev-parse HEAD`) and working tree status. If unverified edits or index modifications occur after verification, fresh verification is enforced.
+- **Untracked Special Entries:** The worktree fingerprint binds untracked symlinks by their target string (git semantics - re-pointing a link moves the fingerprint, changing the link target's contents does not), FIFOs/sockets by path and mode, and skips unopenable entries with a `worktree-fingerprint` warning in the audit trail instead of voiding the whole fingerprint. One unreadable scratch symlink or `chmod 000` file can no longer make review/verification evidence permanently unfresh, and the PR preflight names the actual cause when an approval cannot be matched (no fingerprint binding, fingerprint mismatch, or uncomputable fingerprint) instead of the generic "review approval required". Documented tradeoff: the contents of a skipped entry are excluded from the fingerprint, so a file that stays unreadable to the guard's user across the entire window can change contents without moving the fingerprint; any readability transition is fingerprint-visible (fail-closed), and each skip is named in the durable audit trail.
 - **Durable Disk Cache:** Passing verification results (`~/.local/state/opencode/workflow-guard/last-verify.json`) and passing secondary review approvals (`~/.local/state/opencode/workflow-guard/last-review.json`) are cached to disk, allowing session restarts and multi-agent handoffs to retain valid verification and review evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
 - If verification fails, finalization is blocked with a structured summary of error markers, stack traces, and failure output.
 - OpenCode's current `lsp.client.diagnostics` event identifies the server and path but does not expose the diagnostics themselves, so the guard deliberately does not claim an LSP-clean finalization gate until the SDK provides a supported diagnostics source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.13.5",
+  "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);
 		}
@@ -446,8 +447,27 @@ export async function guardToolCallImpl(
 						review = diskCached;
 					}
 				}
-				const reviewMatchesContext = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: getCurrentGitCommitHash(prRoot), worktreeFingerprint: getGitWorktreeFingerprint(prRoot), sessionID: review.targetSessionID }, 0) && (!review.targetSessionID || review.targetSessionID === context?.sessionID);
-				if (!reviewMatchesContext) preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
+				const prFingerprint = getGitWorktreeFingerprint(prRoot);
+				const reviewMatchesContext = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: getCurrentGitCommitHash(prRoot), worktreeFingerprint: prFingerprint, sessionID: review.targetSessionID }, 0) && (!review.targetSessionID || review.targetSessionID === context?.sessionID);
+				if (!reviewMatchesContext) {
+					// When an approval exists but cannot be matched to this
+					// worktree, the message must name the actual cause instead
+					// of the generic "review required" (which sends the agent
+					// into an endless re-review loop on an unreadable entry).
+					// Cause attribution only makes sense for approvals of THIS
+					// repository; a review of another repo is not evidence here.
+					const reviewIsForThisRepo = typeof review?.workspace === "string" && (projectRootKey(review.workspace) === projectRootKey(prRoot) || isSameGitRepo(review.workspace, prRoot));
+					const sameRepoApproval = review && review.passed === true && reviewIsForThisRepo ? review : undefined;
+					if (sameRepoApproval && prFingerprint === undefined) {
+						preflightFailures.push("Worktree fingerprint could not be computed (git unavailable or worktree unreadable), so review evidence cannot be bound to this worktree; resolve worktree readability and re-run the secondary review.");
+					} else if (sameRepoApproval && !sameRepoApproval.worktreeFingerprint) {
+						preflightFailures.push(`The recorded review approval from '${sameRepoApproval.reviewer}' has no worktree fingerprint binding (recorded against an unreadable worktree or an older guard version); re-run the secondary review and record it with record_review.`);
+					} else if (sameRepoApproval && sameRepoApproval.worktreeFingerprint !== prFingerprint) {
+						preflightFailures.push(`The recorded review approval from '${sameRepoApproval.reviewer}' does not match the current worktree contents (worktree fingerprint changed after review); re-run the secondary review and record it with record_review.`);
+					} else {
+						preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
+					}
+				}
 			}
 			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);

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/lib/verify.ts

@@ -1,6 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { readFileSync, existsSync } from "node:fs";
+import { lstatSync, readFileSync, readlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { dynamicShellSyntaxIn, normalize } from "./shell.ts";
 import { getCleanEnv } from "./utils.ts";
@@ -8,6 +8,7 @@ import { getProjectConfig } from "./state.ts";
 import { normalizeGitCommands } from "../policies/git.ts";
 import { liveMutationIn } from "../policies/destructive.ts";
 import { isSettingsTamper } from "../policies/tamper.ts";
+import { audit } from "./audit.ts";
 
 export function detectVerifyCommand(root: string): string | undefined {
 	if (process.env.WORKFLOW_GUARD_VERIFY !== undefined) {
@@ -118,6 +119,28 @@ export function getGitStatusSummary(root: string): string | undefined {
 	return undefined;
 }
 
+// One warning per unreadable/unopenable untracked entry per process: the
+// fingerprint skips the entry (fail-open per entry, path still hashed) but
+// the durable audit trail must name it, since evidence binding silently
+// excludes its contents from the worktree identity.
+const fingerprintSkipWarnings = new Set<string>();
+
+function warnFingerprintSkip(root: string, file: string, detail: string): void {
+	const key = `${root}\0${file}`;
+	if (fingerprintSkipWarnings.has(key)) return;
+	fingerprintSkipWarnings.add(key);
+	try {
+		audit({
+			ts: new Date().toISOString(),
+			tool: "worktree-fingerprint",
+			decision: "allow",
+			phase: "event",
+			reason: `fingerprint_entry_skipped: untracked entry '${file}' could not be read (${detail}); its contents are excluded from the worktree fingerprint`,
+			input: { root, file },
+		});
+	} catch {}
+}
+
 export function getGitWorktreeFingerprint(root: string): string | undefined {
 	try {
 		// Index listing captures the exact staged/tracked content (blob hashes);
@@ -143,11 +166,33 @@ export function getGitWorktreeFingerprint(root: string): string | undefined {
 		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
 		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
 		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
+			// The path itself is always part of the fingerprint, so a skipped
+			// entry still binds its presence even when its contents do not.
 			hash.update("\0" + file + "\0");
 			try {
-				hash.update(readFileSync(join(root, file)));
-			} catch {
-				return undefined;
+				// Classify with lstat (never follows the final component):
+				// git's untracked listing treats a symlink as a file whose
+				// content is the target string, so hash link bytes for
+				// symlinks - a symlink to a directory (readFileSync throws
+				// EISDIR), a broken link, or a link whose target changes
+				// contents are all bound by the link itself, matching git.
+				const stats = lstatSync(join(root, file));
+				if (stats.isSymbolicLink()) {
+					hash.update(readlinkSync(join(root, file)));
+				} else if (stats.isFile()) {
+					hash.update(readFileSync(join(root, file)));
+				} else {
+					// FIFOs, sockets, devices: opening them can block or fail
+					// and they have no stable hashable content - bind their
+					// identity by path (above) and file mode.
+					hash.update(`special:${stats.mode}`);
+				}
+			} catch (error) {
+				// A single unreadable entry must never void the whole
+				// fingerprint: that made review/verification evidence
+				// permanently unfresh for the worktree. Skip its contents
+				// and name the entry in the audit trail instead.
+				warnFingerprintSkip(root, file, error instanceof Error ? error.message : String(error));
 			}
 		}
 		return hash.digest("hex");

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

@@ -1745,6 +1745,53 @@ check("commitless repo content change updates review fingerprint", getGitWorktre
 rmSync(commitlessRepo, { recursive: true, force: true });
 rmSync(fingerprintRepo, { recursive: true, force: true });
 
+// Untracked special entries must never void the worktree fingerprint: a
+// symlink to a directory (readFileSync throws EISDIR), a broken symlink,
+// an unreadable file, and a FIFO all keep the fingerprint computable and
+// stable. One unopenable entry previously returned undefined, making
+// review/verification evidence permanently unfresh for that worktree and
+// surfacing as a misleading "review approval required" preflight failure.
+const specialRepo = mkdtempSync(join(tmpdir(), "wg-fingerprint-specials-"));
+spawnSync("git", ["init", "-b", "main"], { cwd: specialRepo });
+spawnSync("git", ["config", "user.email", "test" + "@example.com"], { cwd: specialRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: specialRepo });
+writeFileSync(join(specialRepo, "tracked.txt"), "base\n");
+spawnSync("git", ["add", "tracked.txt"], { cwd: specialRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: specialRepo });
+mkdirSync(join(specialRepo, "target-dir"));
+symlinkSync(join(specialRepo, "target-dir"), join(specialRepo, "dir-link"));
+symlinkSync(join(specialRepo, "missing-target"), join(specialRepo, "broken-link"));
+writeFileSync(join(specialRepo, "locked.txt"), "unreadable\n");
+chmodSync(join(specialRepo, "locked.txt"), 0o000);
+const fifoPath = join(specialRepo, "pipe.fifo");
+if (process.platform !== "win32") spawnSync("mkfifo", [fifoPath], { cwd: specialRepo });
+const fpWithSpecials = getGitWorktreeFingerprint(specialRepo);
+check("fingerprint stays computable with untracked dir-symlink/broken-symlink/unreadable-file/fifo", typeof fpWithSpecials === "string" && fpWithSpecials.length === 64);
+check("fingerprint is stable across repeated computation with special entries", fpWithSpecials !== undefined && getGitWorktreeFingerprint(specialRepo) === fpWithSpecials);
+if ((process.getuid?.() ?? 1) !== 0) {
+	check("audit trail names the skipped unreadable entry", getRecentAuditEntries(50).some((entry) => entry.tool === "worktree-fingerprint" && (entry.input as { file?: string } | undefined)?.file === "locked.txt"));
+}
+// git's untracked listing binds a symlink to its target STRING (the link
+// bytes), never the target's contents. The link target lives outside the
+// repo so target contents cannot leak into the untracked listing.
+const linkTargetBase = mkdtempSync(join(tmpdir(), "wg-link-target-"));
+mkdirSync(join(linkTargetBase, "one"));
+mkdirSync(join(linkTargetBase, "two"));
+rmSync(join(specialRepo, "dir-link"));
+symlinkSync(join(linkTargetBase, "one"), join(specialRepo, "dir-link"));
+check("re-pointing an untracked directory symlink updates the fingerprint", getGitWorktreeFingerprint(specialRepo) !== fpWithSpecials);
+rmSync(join(specialRepo, "dir-link"));
+symlinkSync(join(linkTargetBase, "two"), join(specialRepo, "dir-link"));
+const fpAfterTargetChange = getGitWorktreeFingerprint(specialRepo);
+writeFileSync(join(linkTargetBase, "two", "inner.txt"), "changed inside the link target\n");
+check("changing symlink target contents does not change the fingerprint", getGitWorktreeFingerprint(specialRepo) === fpAfterTargetChange);
+rmSync(join(specialRepo, "dir-link"));
+check("removing an untracked symlink updates the fingerprint", getGitWorktreeFingerprint(specialRepo) !== fpAfterTargetChange);
+symlinkSync(join(specialRepo, "missing-target-2"), join(specialRepo, "broken-link-2"));
+check("adding an untracked symlink updates the fingerprint", getGitWorktreeFingerprint(specialRepo) !== fpWithSpecials);
+rmSync(specialRepo, { recursive: true, force: true });
+rmSync(linkTargetBase, { recursive: true, force: true });
+
 // 9. Secret-File READ Blocks (Policy 17)
 console.log("- Policy 17: Secret-File READ Blocks -");
 check("isSecretPath detects .env", isSecretPath(".env"));
@@ -3868,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`);