opencode-workflow-guard 1.14.0 → 1.15.0

package/test/test.mts

@@ -2,6 +2,7 @@ import { mkdtempSync, writeFileSync, rmSync, symlinkSync, readFileSync, existsSy
 import { spawn, spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import type { PluginModule } from "@opencode-ai/plugin";
 import { getRalphMaxIterations, runWithRuntimeState } from "../src/lib/state.ts";
@@ -27,6 +28,8 @@ import {
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
 	getGitWorktreeFingerprint,
+	getTrackedWorktreeFingerprint,
+	resolveWorktreeTimeoutMs,
 	getVerifyCacheFilePath,
 	persistVerifyCache,
 	loadVerifyCache,
@@ -72,6 +75,7 @@ import {
 	checkLockfileSync,
 	branchHasDocumentationChange,
 	isDocumentationRequired,
+	loadedPluginVersion,
 	isReviewRequired,
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
@@ -676,6 +680,35 @@ check("block write to /etc/passwd", blocked(await call("write", { filePath: "/et
 check("block write to ~ path", blocked(await call("write", { filePath: "~/.bashrc", content: "x" }, { sessionID: "s-active" })));
 check("block write to $HOME path", blocked(await call("write", { filePath: "$HOME/.profile", content: "x" }, { sessionID: "s-active" })));
 check("block write to unresolvable $VAR path", blocked(await call("write", { filePath: "$UNKNOWN_DIR/file.txt", content: "x" }, { sessionID: "s-active" })));
+// Cause attribution: indeterminate $VARIABLE destinations get a message that
+// names the unresolvable reference (the on-device over-block class), while
+// deterministically-outside paths keep the generic escape message.
+const unresolvableWrite = await call("write", { filePath: "$UNKNOWN_DIR/file.txt", content: "x" }, { sessionID: "s-active" });
+check("unresolvable $VAR write names the variable cause", blocked(unresolvableWrite) && String(unresolvableWrite).includes("unresolvable variable reference") && String(unresolvableWrite).includes("$UNKNOWN_DIR"));
+const literalEscapeWrite = await call("write", { filePath: "/etc/passwd", content: "x" }, { sessionID: "s-active" });
+check("literal outside path keeps the generic escape message", blocked(literalEscapeWrite) && String(literalEscapeWrite).includes("escapes workspace root") && !String(literalEscapeWrite).includes("unresolvable variable reference"));
+const homeWrite = await call("write", { filePath: "$HOME/.profile", content: "x" }, { sessionID: "s-active" });
+check("deterministically-expanded $HOME path keeps the generic escape message", blocked(homeWrite) && String(homeWrite).includes("escapes workspace root") && !String(homeWrite).includes("unresolvable variable reference"));
+const unresolvableShell = await call("bash", { command: "mkdir -p $D/sub" }, { sessionID: "s-active" });
+check("shell mutation with unresolvable $VAR names the variable cause", blocked(unresolvableShell) && String(unresolvableShell).includes("unresolvable variable reference") && String(unresolvableShell).includes("$D"));
+const unresolvablePatch = await call("apply_patch", { patchText: "*** Update File: $UNKNOWN_DIR/file.ts\n" }, { sessionID: "s-active" });
+check("apply_patch with unresolvable $VAR names the variable cause", blocked(unresolvablePatch) && String(unresolvablePatch).includes("unresolvable variable reference"));
+const unresolvableMv = await call("bash", { command: "mv $D/foo.txt ./bar.txt" }, { sessionID: "s-active" });
+check("mv source with unresolvable $VAR names the variable cause", blocked(unresolvableMv) && String(unresolvableMv).includes("unresolvable variable reference"));
+const unresolvableGit = await call("bash", { command: "git -C $OTHER_REPO commit -m x" }, { sessionID: "s-active" });
+check("git repoDir with unresolvable $VAR names the variable cause", blocked(unresolvableGit) && String(unresolvableGit).includes("unresolvable variable reference"));
+// Scratch-directory cause attribution: /tmp/opencode is the environment's
+// designated scratch space, but the workspace boundary is workspace-absolute
+// and does not cover it; the message explains that instead of reading as a
+// guard bug (6 of the device audit's boundary blocks were this class).
+const scratchWrite = await call("write", { filePath: "/tmp/opencode/scratch.txt", content: "x" }, { sessionID: "s-active" });
+check("scratch-dir write attributes the environment scratch cause", blocked(scratchWrite) && String(scratchWrite).includes("environment scratch directory") && String(scratchWrite).includes("/tmp/opencode") && !String(scratchWrite).includes("unresolvable variable reference"));
+const scratchRedirect = await call("bash", { command: "echo x > /tmp/opencode/out.md" }, { sessionID: "s-active" });
+check("scratch-dir redirect attributes the environment scratch cause", blocked(scratchRedirect) && String(scratchRedirect).includes("environment scratch directory"));
+const scratchPatch = await call("apply_patch", { patchText: "*** Add File: /tmp/opencode/scratch.ts\n+scratch\n" }, { sessionID: "s-active" });
+check("scratch-dir apply_patch attributes the environment scratch cause", blocked(scratchPatch) && String(scratchPatch).includes("environment scratch directory"));
+const otherOutsideWrite = await call("write", { filePath: "/var/tmp/elsewhere.txt", content: "x" }, { sessionID: "s-active" });
+check("non-scratch outside path keeps the generic escape message", blocked(otherOutsideWrite) && String(otherOutsideWrite).includes("escapes workspace root") && !String(otherOutsideWrite).includes("scratch directory"));
 check("allow apply_patch within workspace", !(await call("apply_patch", { patchText: "*** Update File: src/app.ts\n" }, { sessionID: "s-active" })));
 check("block apply_patch escaping workspace", blocked(await call("apply_patch", { patchText: "*** Update File: ../../secret.env\n" }, { sessionID: "s-active" })));
 
@@ -895,6 +928,169 @@ try {
 }
 check("blocked multi-target patch leaves no partial claims", !partialPatchClaim);
 
+// Stale claim takeover (missed idle release): a claim created BEFORE its
+// owner's last recorded idle timestamp cannot belong to an in-flight tool
+// call, so a leaked claim must not block another session forever. Owners that
+// are still mid-session (no idle timestamp), a client without a session
+// lookup, and a failing lookup all keep the block (fail-closed).
+console.log("- Stale file-claim takeover -");
+const takeoverDir = mkdtempSync(join(tmpdir(), "wg-claim-takeover-"));
+writeFileSync(join(takeoverDir, "stale.ts"), "before");
+writeFileSync(join(takeoverDir, "live.ts"), "before");
+writeFileSync(join(takeoverDir, "refresh.ts"), "before");
+const takeoverIdle = new Map<string, number>();
+const takeoverClient = {
+	session: {
+		todo: fakeClient.session.todo,
+		get: async ({ path }: { path: { id: string } }) => {
+			const idle = takeoverIdle.get(path.id);
+			return { data: { id: path.id, parentID: fakeParents.get(path.id), ...(typeof idle === "number" ? { time: { idle } } : {}) } };
+		},
+	},
+};
+const takeoverHooks = await pluginFn({
+	directory: takeoverDir,
+	client: takeoverClient as any,
+	project: {} as any,
+	worktree: takeoverDir,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+todo("s-stale-owner", item("edit stale file", "in_progress"));
+todo("s-live-owner", item("edit live file", "in_progress"));
+todo("s-claimant", item("take over stale claim", "in_progress"));
+const takeoverBefore = takeoverHooks["tool.execute.before"];
+const takeoverAfter = takeoverHooks["tool.execute.after"];
+
+// The owner claims the file, its after-hook is skipped, and it idles LATER.
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "stale.ts"), "takeover-read-stale");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "stale-claim" }, { args: { filePath: join(takeoverDir, "stale.ts"), content: "a" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+// A live owner, still mid-session, claims the other file.
+await recordRead(takeoverBefore, takeoverAfter, "s-live-owner", join(takeoverDir, "live.ts"), "takeover-read-live");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-live-owner", callID: "live-claim" }, { args: { filePath: join(takeoverDir, "live.ts"), content: "b" } });
+
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "stale.ts"), "takeover-read-claimant");
+let staleTakeoverAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "takeover-claim" }, { args: { filePath: join(takeoverDir, "stale.ts"), content: "c" } });
+} catch {
+	staleTakeoverAllowed = false;
+}
+check("a claim older than its owner's recorded idle is released for the next claimant", staleTakeoverAllowed);
+const takeoverAudit = getRecentAuditEntries(30).find((entry) => entry.tool === "file-claims" && entry.reason === "stale_claim_takeover");
+check("stale claim takeover is audited with the released path and owner", takeoverAudit?.decision === "allow" && typeof takeoverAudit?.evidence?.targetPath === "string" && takeoverAudit.evidence.targetPath.endsWith("stale.ts") && takeoverAudit.evidence.claimOwnerSessionID === "s-stale-owner");
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "takeover-claim", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// A live owner, still mid-turn (no idle timestamp recorded), keeps its claim.
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "live.ts"), "takeover-read-live-claimant");
+let liveClaimBlocked = false;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "live-blocked" }, { args: { filePath: join(takeoverDir, "live.ts"), content: "c" } });
+} catch (error) {
+	liveClaimBlocked = String(error).includes("claimed by another active session");
+}
+check("a live owner without an idle timestamp keeps its claim", liveClaimBlocked);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-live-owner", callID: "live-claim", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// A same-session re-claim refreshes the stored claim (new callID/timestamp):
+// an owner that idled with a leaked claim and comes back to the same file
+// mid-turn must not have its fresh claim taken over, and the refreshed
+// callID must be the one the after-hook releases.
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "refresh.ts"), "takeover-read-refresh");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-1" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "d" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-2" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "e" } });
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "refresh.ts"), "takeover-read-refresh-claimant");
+let refreshClaimBlocked = false;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-conflict" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "f" } });
+} catch (error) {
+	refreshClaimBlocked = String(error).includes("claimed by another active session");
+}
+check("a same-session re-claim refreshes past the owner's idle so it is not taken over mid-turn", refreshClaimBlocked);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-2", args: {} }, { title: "edit", output: "edited", metadata: {} });
+let refreshReleasedAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-after-release" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "g" } });
+} catch {
+	refreshReleasedAllowed = false;
+}
+check("the refreshed claim releases through its updated callID", refreshReleasedAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-after-release", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// The takeover releases every provably stale claim of the owner, each with
+// its own audit entry: an owner holding two stale paths loses both in one
+// pass, and no fresh claim of that owner is touched.
+writeFileSync(join(takeoverDir, "multi-a.ts"), "before");
+writeFileSync(join(takeoverDir, "multi-b.ts"), "before");
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "multi-a.ts"), "takeover-read-multi-a");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "multi-claim-a" }, { args: { filePath: join(takeoverDir, "multi-a.ts"), content: "h" } });
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "multi-b.ts"), "takeover-read-multi-b");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "multi-claim-b" }, { args: { filePath: join(takeoverDir, "multi-b.ts"), content: "h" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "multi-a.ts"), "takeover-read-multi-a-claimant");
+let multiTakeoverAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-a" }, { args: { filePath: join(takeoverDir, "multi-a.ts"), content: "i" } });
+} catch {
+	multiTakeoverAllowed = false;
+}
+check("one conflict releases every provably stale claim of the owner", multiTakeoverAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-a", args: {} }, { title: "edit", output: "edited", metadata: {} });
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "multi-b.ts"), "takeover-read-multi-b-claimant");
+let multiSecondAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-b" }, { args: { filePath: join(takeoverDir, "multi-b.ts"), content: "j" } });
+} catch {
+	multiSecondAllowed = false;
+}
+check("the owner's other stale path is released in the same pass", multiSecondAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-b", args: {} }, { title: "edit", output: "edited", metadata: {} });
+const takeoverAudits = getRecentAuditEntries(30).filter((entry) => entry.reason === "stale_claim_takeover" && typeof entry.evidence?.targetPath === "string" && entry.evidence.targetPath.includes("multi-"));
+check("each released stale path has its own audited takeover entry", takeoverAudits.length === 2 && takeoverAudits.every((entry) => entry.evidence?.claimOwnerSessionID === "s-stale-owner"));
+
+// Fail-closed: no session lookup on the client, and a lookup that throws.
+const noLookupDir = mkdtempSync(join(tmpdir(), "wg-claim-nolookup-"));
+writeFileSync(join(noLookupDir, "file.ts"), "before");
+const noLookupHooks = await pluginFn({ directory: noLookupDir, client: {} as any, project: {} as any, worktree: noLookupDir, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const noLookupBefore = noLookupHooks["tool.execute.before"];
+const noLookupAfter = noLookupHooks["tool.execute.after"];
+todo("s-nolookup-owner", item("edit file", "in_progress"));
+await recordRead(noLookupBefore, noLookupAfter, "s-nolookup-owner", join(noLookupDir, "file.ts"), "nolookup-read-owner");
+await noLookupBefore?.({ tool: "edit", sessionID: "s-nolookup-owner", callID: "nolookup-claim" }, { args: { filePath: join(noLookupDir, "file.ts"), content: "a" } });
+todo("s-nolookup-claimant", item("edit file", "in_progress"));
+await recordRead(noLookupBefore, noLookupAfter, "s-nolookup-claimant", join(noLookupDir, "file.ts"), "nolookup-read-claimant");
+let noLookupBlocked = false;
+try {
+	await noLookupBefore?.({ tool: "edit", sessionID: "s-nolookup-claimant", callID: "nolookup-claimant" }, { args: { filePath: join(noLookupDir, "file.ts"), content: "b" } });
+} catch (error) {
+	noLookupBlocked = String(error).includes("claimed by another active session");
+}
+check("stale takeover fails closed when the client has no session lookup", noLookupBlocked);
+
+const throwLookupDir = mkdtempSync(join(tmpdir(), "wg-claim-throwlookup-"));
+writeFileSync(join(throwLookupDir, "file.ts"), "before");
+const throwLookupHooks = await pluginFn({ directory: throwLookupDir, client: { session: { get: async () => { throw new Error("lookup failed"); } } } as any, project: {} as any, worktree: throwLookupDir, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const throwLookupBefore = throwLookupHooks["tool.execute.before"];
+const throwLookupAfter = throwLookupHooks["tool.execute.after"];
+todo("s-throwlookup-owner", item("edit file", "in_progress"));
+await recordRead(throwLookupBefore, throwLookupAfter, "s-throwlookup-owner", join(throwLookupDir, "file.ts"), "throwlookup-read-owner");
+await throwLookupBefore?.({ tool: "edit", sessionID: "s-throwlookup-owner", callID: "throwlookup-claim" }, { args: { filePath: join(throwLookupDir, "file.ts"), content: "a" } });
+todo("s-throwlookup-claimant", item("edit file", "in_progress"));
+await recordRead(throwLookupBefore, throwLookupAfter, "s-throwlookup-claimant", join(throwLookupDir, "file.ts"), "throwlookup-read-claimant");
+let throwLookupBlocked = false;
+try {
+	await throwLookupBefore?.({ tool: "edit", sessionID: "s-throwlookup-claimant", callID: "throwlookup-claimant" }, { args: { filePath: join(throwLookupDir, "file.ts"), content: "b" } });
+} catch (error) {
+	throwLookupBlocked = String(error).includes("claimed by another active session");
+}
+check("stale takeover fails closed when the session lookup throws", throwLookupBlocked);
+
 // Existing files must be read by the same session before edit/write, and the
 // bytes plus filesystem identity must still match when the mutation starts.
 const staleDir = mkdtempSync(join(tmpdir(), "wg-stale-write-"));
@@ -980,6 +1176,56 @@ try {
 }
 check("stale-write protection allows creating a new file without a prior read", newFileAllowed);
 await staleAfter?.({ tool: "write", sessionID: "s-stale", callID: "new-file", args: {} }, { title: "write", output: "written", metadata: {} });
+// A successful mutation seeds the session's observation of the bytes it
+// authored, so iterating on a just-created/modified file needs no re-read;
+// a no-op mutation seeds nothing and external changes stay blocked.
+const mutationSession = "s-stale-mutation";
+todo(mutationSession, item("iterate on authored file", "in_progress"));
+const authoredPath = join(staleDir, "authored.ts");
+await staleBefore?.({ tool: "write", sessionID: mutationSession, callID: "write-authored" }, { args: { filePath: authoredPath, content: "v1" } });
+writeFileSync(authoredPath, "v1");
+await staleAfter?.({ tool: "write", sessionID: mutationSession, callID: "write-authored", args: {} }, { title: "write", output: "written", metadata: {} });
+let authoredEditAllowed = true;
+try {
+	await staleBefore?.({ tool: "edit", sessionID: mutationSession, callID: "edit-authored-1" }, { args: { filePath: authoredPath, oldString: "v1", newString: "v2" } });
+} catch {
+	authoredEditAllowed = false;
+}
+check("a successful write seeds the session observation so the authored file can be edited without a re-read", authoredEditAllowed);
+writeFileSync(authoredPath, "v2");
+await staleAfter?.({ tool: "edit", sessionID: mutationSession, callID: "edit-authored-1", args: {} }, { title: "edit", output: "edited", metadata: {} });
+let chainedEditAllowed = true;
+try {
+	await staleBefore?.({ tool: "edit", sessionID: mutationSession, callID: "edit-authored-2" }, { args: { filePath: authoredPath, oldString: "v2", newString: "v3" } });
+} catch {
+	chainedEditAllowed = false;
+}
+check("a successful edit seeds the observation so chained edits need no re-read", chainedEditAllowed);
+writeFileSync(authoredPath, "changed externally");
+let externalAfterMutationBlocked = false;
+try {
+	await staleBefore?.({ tool: "edit", sessionID: mutationSession, callID: "edit-authored-3" }, { args: { filePath: authoredPath, oldString: "v3", newString: "v4" } });
+} catch (error) {
+	externalAfterMutationBlocked = String(error).includes("changed since this session read it");
+}
+check("an external change after a successful mutation is still blocked", externalAfterMutationBlocked);
+// Negative branch: a mutation that leaves content unchanged must not seed.
+// apply_patch is not stale-write checked, so this unobserved session can run
+// it; because the file is left unchanged, the seed gate must skip and a
+// later edit must still demand a read.
+const noopSession = "s-stale-noop";
+todo(noopSession, item("no-op patch", "in_progress"));
+const noopPath = join(staleDir, "noop.ts");
+writeFileSync(noopPath, "stable");
+await staleBefore?.({ tool: "apply_patch", sessionID: noopSession, callID: "noop-patch" }, { args: { patchText: `*** Begin Patch\n*** Update File: ${noopPath}\n@@\n stable\n*** End Patch` } });
+await staleAfter?.({ tool: "apply_patch", sessionID: noopSession, callID: "noop-patch", args: {} }, { title: "patch", output: "done", metadata: {} });
+let noopEditBlocked = false;
+try {
+	await staleBefore?.({ tool: "edit", sessionID: noopSession, callID: "noop-edit" }, { args: { filePath: noopPath, oldString: "stable", newString: "changed" } });
+} catch (error) {
+	noopEditBlocked = String(error).includes("has not been read");
+}
+check("a no-op mutation does not seed an observation for a later edit", noopEditBlocked);
 const staleAlternateRoot = mkdtempSync(join(tmpdir(), "wg-stale-root-"));
 writeFileSync(join(staleAlternateRoot, "relative.ts"), "observed");
 todo("s-stale-root", item("edit relative file", "in_progress"));
@@ -1718,10 +1964,10 @@ check("evidence freshness requires exact subject and post-mutation observation",
 const missingProvenanceEvidence = verificationEvidence({ passed: true, command: "npm test", output: "ok", timestamp: 123, workspaceRoot: "/tmp/ws" }, "s-evidence");
 check("evidence freshness fails closed when Git provenance is unavailable", !isEvidenceFresh(missingProvenanceEvidence, { workspace: "/tmp/ws", sessionID: "s-evidence" }, 0) && !isEvidenceFresh(verificationEvidenceResult, { workspace: "/tmp/ws", sessionID: "s-evidence" }, 0));
 await call("edit", { filePath: join(root, "after-review.ts"), content: "changed" }, { sessionID: "s-active" });
-check("new mutation invalidates prior review approval", getLastReviewResult() === undefined);
+check("mutations no longer erase review approval state (freshness is re-evaluated against content)", getLastReviewResult() !== undefined);
 recordReviewResult("reviewer-subagent", "Child review passed all axes.", true, "s-reviewed-child");
 recordMutation("s-reviewed-parent", "s-reviewed-child");
-check("actor mutation invalidates child-targeted global review", getLastReviewResult() === undefined);
+check("actor mutation no longer erases child-targeted review evidence", getLastReviewResult()?.targetSessionID === "s-reviewed-child");
 
 const fingerprintRepo = mkdtempSync(join(tmpdir(), "wg-review-fingerprint-"));
 spawnSync("git", ["init", "-b", "feature/review"], { cwd: fingerprintRepo });
@@ -1791,6 +2037,29 @@ symlinkSync(join(specialRepo, "missing-target-2"), join(specialRepo, "broken-lin
 check("adding an untracked symlink updates the fingerprint", getGitWorktreeFingerprint(specialRepo) !== fpWithSpecials);
 rmSync(specialRepo, { recursive: true, force: true });
 rmSync(linkTargetBase, { recursive: true, force: true });
+// Review evidence binds to tracked content only: untracked scratch files are
+// not part of the reviewed diff, so creating or deleting them must keep the
+// approval fresh, while the full fingerprint still covers untracked contents
+// for verification evidence.
+const trackedFpRepo = mkdtempSync(join(tmpdir(), "wg-review-tracked-fp-"));
+spawnSync("git", ["init", "-b", "main"], { cwd: trackedFpRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: trackedFpRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: trackedFpRepo });
+writeFileSync(join(trackedFpRepo, "tracked.txt"), "tracked\n");
+spawnSync("git", ["add", "tracked.txt"], { cwd: trackedFpRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: trackedFpRepo });
+const trackedFpBase = getTrackedWorktreeFingerprint(trackedFpRepo);
+check("tracked-content fingerprint is available for a git worktree", typeof trackedFpBase === "string" && trackedFpBase.length === 64);
+writeFileSync(join(trackedFpRepo, ".tmp-review-final.diff"), "scratch\n");
+check("untracked scratch creation does not change the tracked-content fingerprint", getTrackedWorktreeFingerprint(trackedFpRepo) === trackedFpBase);
+const fullFpWithScratch = getGitWorktreeFingerprint(trackedFpRepo);
+writeFileSync(join(trackedFpRepo, ".tmp-review-final.diff"), "scratch v2\n");
+check("full fingerprint still binds untracked contents for verification evidence", getGitWorktreeFingerprint(trackedFpRepo) !== fullFpWithScratch);
+rmSync(join(trackedFpRepo, ".tmp-review-final.diff"));
+check("untracked scratch deletion does not change the tracked-content fingerprint", getTrackedWorktreeFingerprint(trackedFpRepo) === trackedFpBase);
+writeFileSync(join(trackedFpRepo, "tracked.txt"), "tracked edit\n");
+check("tracked-content fingerprint changes on a tracked edit", getTrackedWorktreeFingerprint(trackedFpRepo) !== trackedFpBase);
+rmSync(trackedFpRepo, { recursive: true, force: true });
 
 // 9. Secret-File READ Blocks (Policy 17)
 console.log("- Policy 17: Secret-File READ Blocks -");
@@ -2237,6 +2506,17 @@ try {
 	rmSync(whyRemoteRoot, { recursive: true, force: true });
 }
 
+// record_review binds verdicts to tracked repository content, so its tool
+// tests need a real git worktree rather than the non-git test root.
+const reviewToolRepo = join(root, "wg-review-tool-repo");
+mkdirSync(reviewToolRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: reviewToolRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: reviewToolRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: reviewToolRepo });
+writeFileSync(join(reviewToolRepo, "code.txt"), "reviewed\n");
+spawnSync("git", ["add", "code.txt"], { cwd: reviewToolRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: reviewToolRepo });
+
 fakeParents.set("s-reviewer-tool", "s-active");
 const unrelatedClient = {
 	session: {
@@ -2255,15 +2535,15 @@ await (defaultExport?.server ?? WorkflowGuard)({
 });
 const reviewToolResult = await customPlugin.tool?.record_review?.execute(
 	{ reviewer: "subagent-1", summary: "Test integrity: real assertions. Task completeness: done. Cleanliness: no stubs. Security: clean. Platform fit: ok.", passed: true },
-	{ sessionID: "s-reviewer-tool", agent: "reviewer", worktree: root, directory: root } as any,
+	{ sessionID: "s-reviewer-tool", agent: "reviewer", worktree: reviewToolRepo, directory: reviewToolRepo } as any,
 );
-check("record_review resolves subagent lineage through its own plugin client", typeof reviewToolResult === "string" && reviewToolResult.includes("APPROVED"));
+check("record_review resolves subagent lineage through its own plugin client", typeof reviewToolResult === "string" && reviewToolResult.includes("APPROVED") && reviewToolResult.includes(reviewToolRepo));
 setSdkClient(fakeClient);
 
 fakeParents.set("s-reviewer-changes", "s-active");
 const changesReviewResult = await customPlugin.tool?.record_review?.execute(
 	{ reviewer: "subagent-changes", summary: "Test integrity: gap found. Task completeness: needs work. Cleanliness: ok. Security: ok. Platform: ok.", passed: false },
-	{ sessionID: "s-reviewer-changes", agent: "reviewer", worktree: root, directory: root } as any,
+	{ sessionID: "s-reviewer-changes", agent: "reviewer", worktree: reviewToolRepo, directory: reviewToolRepo } as any,
 );
 const changesReviewAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-reviewer-changes");
 check("record_review audit distinguishes changes-requested verdict without persisting summary", typeof changesReviewResult === "string" && changesReviewResult.includes("CHANGES REQUESTED") && changesReviewAudit?.reason === "changes_requested" && !JSON.stringify(changesReviewAudit).includes("gap found"));
@@ -2275,7 +2555,7 @@ await customPlugin.tool?.record_review?.execute(
 		summary: "Test integrity: covered. Task completeness: done. Cleanliness: clean. Security: safe. Platform: compatible.\nP2: first durable issue\nP3: second durable issue",
 		passed: true,
 	},
-	{ sessionID: "s-reviewer-followups", agent: "reviewer", worktree: root, directory: root } as any,
+	{ sessionID: "s-reviewer-followups", agent: "reviewer", worktree: reviewToolRepo, directory: reviewToolRepo } as any,
 );
 const durableReviewFollowups = JSON.parse(String(await customPlugin.tool?.guard_review_followups?.execute({}, {} as any))) as Array<{ severity?: string; summary?: string }>;
 check("record_review persists multiple P2/P3 findings independently", durableReviewFollowups.some((item) => item.severity === "P2" && item.summary?.includes("first durable issue")) && durableReviewFollowups.some((item) => item.severity === "P3" && item.summary?.includes("second durable issue")));
@@ -2316,11 +2596,80 @@ check(
 const rubricOptionFlag = await customPlugin.tool?.guard_review_rubric?.execute({ base: "--output=injected" }, {} as any);
 check("guard_review_rubric sanitizes option flags in base ref", typeof rubricOptionFlag === "string" && !existsSync(join(root, "injected")));
 
+// Regression: the rubric must embed the real branch diff. The git argv
+// previously placed `--` before the revision, so the revision parsed as a
+// pathspec and every rubric carried an empty diff block.
+const rubricDiffRepo = join(root, "wg-review-rubric-diff");
+mkdirSync(rubricDiffRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: rubricDiffRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: rubricDiffRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: rubricDiffRepo });
+writeFileSync(join(rubricDiffRepo, "seed.txt"), "base\n");
+spawnSync("git", ["add", "seed.txt"], { cwd: rubricDiffRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: rubricDiffRepo });
+spawnSync("git", ["switch", "-c", "feature/rubric-diff"], { cwd: rubricDiffRepo });
+writeFileSync(join(rubricDiffRepo, "added.txt"), "export const rubricDiffMarker = 42;\n");
+spawnSync("git", ["add", "added.txt"], { cwd: rubricDiffRepo });
+spawnSync("git", ["commit", "-m", "add rubric marker"], { cwd: rubricDiffRepo });
+const rubricWithDiff = await customPlugin.tool?.guard_review_rubric?.execute(
+	{ base: "main", directory: rubricDiffRepo },
+	{ sessionID: "s-rubric-diff", worktree: rubricDiffRepo, directory: rubricDiffRepo } as any,
+);
+check(
+	"guard_review_rubric embeds the real branch diff content",
+	typeof rubricWithDiff === "string" && rubricWithDiff.includes("rubricDiffMarker") && rubricWithDiff.includes("added.txt"),
+);
+rmSync(rubricDiffRepo, { recursive: true, force: true });
+
+// The default-bases loop is directly asserted: with no origin remote, the
+// loop falls through origin/main and origin/master to the local main branch
+// and embeds the real branch diff. The spawn also keeps a trailing `--` after
+// the revision so the base ref can never parse as a pathspec (LL-001).
+const rubricNoOrigin = join(root, "wg-rubric-no-origin");
+mkdirSync(rubricNoOrigin, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: rubricNoOrigin });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: rubricNoOrigin });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: rubricNoOrigin });
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "base\n");
+spawnSync("git", ["add", "fallthrough.txt"], { cwd: rubricNoOrigin });
+spawnSync("git", ["commit", "-m", "base"], { cwd: rubricNoOrigin });
+spawnSync("git", ["switch", "-c", "feature/rubric-fallthrough"], { cwd: rubricNoOrigin });
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "branch marker\n");
+spawnSync("git", ["add", "fallthrough.txt"], { cwd: rubricNoOrigin });
+spawnSync("git", ["commit", "-qm", "branch change"], { cwd: rubricNoOrigin });
+// An uncommitted tracked edit discriminates the fallbacks: main...HEAD is
+// committed-only and must NOT include it, while the HEAD~1 fallback (commit
+// vs worktree) would — so the assertion proves the base loop won.
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "branch marker\nuncommitted worktree edit\n");
+const rubricFallthrough = await customPlugin.tool?.guard_review_rubric?.execute(
+	{ directory: rubricNoOrigin },
+	{ sessionID: "s-rubric-fallthrough", worktree: rubricNoOrigin, directory: rubricNoOrigin } as any,
+);
+check(
+	"rubric default bases fall through to the local main when no origin exists",
+	typeof rubricFallthrough === "string" && rubricFallthrough.includes("diff --git") && rubricFallthrough.includes("fallthrough.txt") && rubricFallthrough.includes("branch marker") && !rubricFallthrough.includes("uncommitted worktree edit"),
+);
+rmSync(rubricNoOrigin, { recursive: true, force: true });
+
+// Reviewer-type agents often lack record_review in their toolset entirely, so
+// the tool accepts recorders of any session type: the verdict binds to the
+// recording session's directory and the audit trail captures the recorder
+// lineage (recorderRole). The decision is documented in the changelog.
 const mainReviewToolResult = await customPlugin.tool?.record_review?.execute(
-	{ reviewer: "self", summary: "self approval", passed: true },
-	{ sessionID: "s-active", agent: "main", worktree: root, directory: root } as any,
+	{ reviewer: "root-relay", summary: "Test integrity: verified. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ sessionID: "s-active", agent: "main", worktree: reviewToolRepo, directory: reviewToolRepo } as any,
+);
+check(
+	"record_review accepts a root-session recorder and binds the verdict to its directory",
+	typeof mainReviewToolResult === "string" && mainReviewToolResult.includes("APPROVED") && mainReviewToolResult.includes(reviewToolRepo),
 );
-check("record_review rejects self-approval from main session", typeof mainReviewToolResult === "string" && mainReviewToolResult.includes("rejected"));
+const rootRecorderAudit = getRecentAuditEntries(30).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-active");
+check(
+	"record_review audit includes the binding key and recorder lineage",
+	(rootRecorderAudit?.evidence as { binding?: { workspace?: string; recorderRole?: string } })?.binding?.workspace === reviewToolRepo &&
+		(rootRecorderAudit?.evidence as { binding?: { recorderRole?: string } })?.binding?.recorderRole === "root",
+);
+resetReviewState();
 
 // Secondary Review Approval Handoff & Durable Cache Tests
 console.log("- Secondary Review Approval Handoff & Durability -");
@@ -2412,6 +2761,259 @@ check("worktree and main repo recognized as same git repository", isSameGitRepo(
 rmSync(handoffRepo, { recursive: true, force: true });
 resetReviewState();
 
+// 5. Review binding across sessions and linked worktrees (regression): a
+// review recorded by a subagent rooted in a LINKED WORKTREE must satisfy the
+// PR preflight even when the PR is created from a DIFFERENT session, and must
+// stay valid across innocuous untracked-file cleanup.
+console.log("- Review Binding Across Sessions & Linked Worktrees -");
+const flowRepo = join(root, "wg-flow-repo");
+mkdirSync(flowRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: flowRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: flowRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: flowRepo });
+writeFileSync(join(flowRepo, "seed.txt"), "base\n");
+spawnSync("git", ["add", "seed.txt"], { cwd: flowRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: flowRepo });
+mkdirSync(join(flowRepo, ".opencode"), { recursive: true });
+writeFileSync(join(flowRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true }));
+const prevWorktreeDirFlow = process.env.WORKFLOW_GUARD_WORKTREE_DIR;
+process.env.WORKFLOW_GUARD_WORKTREE_DIR = join(root, "wg-flow-worktrees");
+const flowWorktreeRes = createGitWorktree("fix/flow-branch", "HEAD", flowRepo);
+check("flow: linked worktree created", flowWorktreeRes.success && typeof flowWorktreeRes.worktreePath === "string");
+const flowWt = flowWorktreeRes.worktreePath!;
+writeFileSync(join(flowWt, "seed.txt"), "worktree change\n");
+spawnSync("git", ["add", "seed.txt"], { cwd: flowWt });
+spawnSync("git", ["commit", "-qm", "worktree change"], { cwd: flowWt });
+writeFileSync(join(flowWt, ".tmp-review-final.diff"), "scratch\n");
+
+const flowPlugin = await WorkflowGuard({
+	directory: root,
+	worktree: root,
+	client: fakeClient as any,
+	project: {} as any,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+// The orchestrator session moved itself into the linked worktree
+// (tools.opencode.session_move): its file tools are rooted at the worktree.
+setSessionWorkspace("s-flow-orch", flowWt);
+fakeParents.set("s-flow-reviewer", "s-flow-orch");
+fakeParents.set("s-flow-pr", "s-flow-orch");
+todo("s-flow-orch", item("drive the flow", "in_progress"));
+const flowCtx = (sessionID: string) => ({ sessionID, worktree: flowWt, directory: flowWt }) as any;
+
+const flowReview = await flowPlugin.tool?.record_review?.execute(
+	{ reviewer: "secondary-reviewer", summary: "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ ...flowCtx("s-flow-reviewer"), agent: "general" },
+);
+check("flow: review recorded from a subagent rooted in the linked worktree binds to it", typeof flowReview === "string" && flowReview.includes("APPROVED") && flowReview.includes(flowWt));
+
+const flowStatus = JSON.parse(String(await flowPlugin.tool?.guard_status?.execute({ directory: flowWt }, flowCtx("s-flow-orch"))));
+check("flow: guard_status reports fresh lastReview for the linked worktree", flowStatus.lastReview?.fresh === true && !flowStatus.outstandingRequirements.includes("review"));
+
+const flowPrevPath = process.env.PATH;
+const flowBin = join(root, "wg-flow-bin");
+mkdirSync(flowBin, { recursive: true });
+writeFileSync(join(flowBin, "gh"), "#!/bin/sh\nexit 1\n");
+writeFileSync(join(flowBin, "az"), "#!/bin/sh\nexit 1\n");
+chmodSync(join(flowBin, "gh"), 0o755);
+chmodSync(join(flowBin, "az"), 0o755);
+process.env.PATH = `${flowBin}:${flowPrevPath ?? ""}`;
+const flowPrBody = "gh pr create --title 'fix: flow' --body 'Changelog: flow'";
+try {
+	const flowPrParent = await call("bash", { command: flowPrBody, workdir: flowWt }, flowCtx("s-flow-orch"));
+	check("flow: PR from the reviewer's parent session is allowed", !blocked(flowPrParent));
+	const flowPrOther = await call("bash", { command: flowPrBody, workdir: flowWt }, flowCtx("s-flow-pr"));
+	check("flow: PR from a DIFFERENT session in the same worktree is allowed (content binding, not session identity)", !blocked(flowPrOther));
+	if (blocked(flowPrOther)) console.log("   blocked:", flowPrOther);
+
+	// Untracked scratch cleanup must not invalidate the approval
+	const flowRm = await call("bash", { command: "rm -f .tmp-review-final.diff", workdir: flowWt }, flowCtx("s-flow-orch"));
+	check("flow: untracked scratch deletion is a permitted cleanup", !blocked(flowRm));
+	const flowStatusAfterRm = JSON.parse(String(await flowPlugin.tool?.guard_status?.execute({ directory: flowWt }, flowCtx("s-flow-orch"))));
+	check("flow: review stays fresh after untracked scratch deletion", flowStatusAfterRm.lastReview?.fresh === true && !flowStatusAfterRm.outstandingRequirements.includes("review"));
+	const flowPrAfterRm = await call("bash", { command: flowPrBody, workdir: flowWt }, flowCtx("s-flow-pr"));
+	check("flow: PR still allowed after innocuous untracked-file mutations", !blocked(flowPrAfterRm));
+
+	// Tracked content changes still invalidate (the gate is not weakened)
+	writeFileSync(join(flowWt, "seed.txt"), "post-review tracked edit\n");
+	const flowStatusAfterEdit = JSON.parse(String(await flowPlugin.tool?.guard_status?.execute({ directory: flowWt }, flowCtx("s-flow-orch"))));
+	check("flow: tracked edit after review makes the approval stale", flowStatusAfterEdit.outstandingRequirements.includes("review"));
+	const flowPrAfterEdit = await call("bash", { command: flowPrBody, workdir: flowWt }, flowCtx("s-flow-orch"));
+	check("flow: PR blocked after tracked content changed post-review", blocked(flowPrAfterEdit) && String(flowPrAfterEdit).includes("tracked content changed after review"));
+	spawnSync("git", ["checkout", "--", "seed.txt"], { cwd: flowWt });
+} finally {
+	process.env.PATH = flowPrevPath;
+}
+
+// Reviewer-type agents cannot call record_review themselves (their toolset has
+// no record_review), so the orchestrator relays the verdict from its own
+// session; the verdict must still bind to the reviewed worktree.
+const relayedReview = await flowPlugin.tool?.record_review?.execute(
+	{ reviewer: "relayed-reviewer", summary: "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ ...flowCtx("s-flow-orch"), agent: "reviewer" },
+);
+check("flow: relayed verdict from a root session binds to the reviewed worktree", typeof relayedReview === "string" && relayedReview.includes("APPROVED") && relayedReview.includes(flowWt));
+
+// A verdict recorded against a non-git directory can never bind to a PR
+// preflight; it must fail loudly instead of silently not binding.
+const flowNonGit = join(root, "wg-flow-nongit");
+mkdirSync(flowNonGit, { recursive: true });
+const flowBadReview = await flowPlugin.tool?.record_review?.execute(
+	{ reviewer: "unbindingable", summary: "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ ...flowCtx("s-flow-reviewer"), worktree: flowNonGit, directory: flowNonGit },
+);
+check(
+	"flow: verdict against a non-git directory returns an explicit bind error",
+	typeof flowBadReview === "string" && flowBadReview.includes("rejected") && flowBadReview.includes("cannot be bound") && !flowBadReview.includes("APPROVED"),
+);
+
+rmSync(flowNonGit, { recursive: true, force: true });
+rmSync(flowBin, { recursive: true, force: true });
+rmSync(flowRepo, { recursive: true, force: true });
+if (prevWorktreeDirFlow === undefined) delete process.env.WORKFLOW_GUARD_WORKTREE_DIR;
+else process.env.WORKFLOW_GUARD_WORKTREE_DIR = prevWorktreeDirFlow;
+rmSync(join(root, "wg-flow-worktrees"), { recursive: true, force: true });
+resetReviewState();
+
+// Commit drift: a review recorded with its change already staged stays
+// fingerprint-identical once that change is committed, so the commit-hash
+// binding is the invalidation signal and the preflight must name it.
+const driftRepo = join(root, "wg-review-commit-drift");
+mkdirSync(driftRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/commit-drift"], { cwd: driftRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: driftRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: driftRepo });
+writeFileSync(join(driftRepo, "code.txt"), "base\n");
+spawnSync("git", ["add", "code.txt"], { cwd: driftRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: driftRepo });
+mkdirSync(join(driftRepo, ".opencode"), { recursive: true });
+writeFileSync(join(driftRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true }));
+writeFileSync(join(driftRepo, "code.txt"), "reviewed staged edit\n");
+spawnSync("git", ["add", "code.txt"], { cwd: driftRepo });
+const driftFingerprintBefore = getTrackedWorktreeFingerprint(driftRepo);
+recordReviewResult("commit-drift-reviewer", "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", true, "s-drift", driftRepo);
+spawnSync("git", ["commit", "-qm", "commit reviewed change"], { cwd: driftRepo });
+check("committing staged reviewed content keeps the tracked fingerprint", getTrackedWorktreeFingerprint(driftRepo) === driftFingerprintBefore);
+const driftPr = await call("bash", { command: "gh pr create --title t --body 'Changelog: drift'", workdir: driftRepo }, { sessionID: "s-drift", worktree: driftRepo, directory: driftRepo });
+check("PR blocked when only the reviewed commit drifted, with a commit-specific cause", blocked(driftPr) && String(driftPr).includes("bound to commit"));
+rmSync(driftRepo, { recursive: true, force: true });
+resetReviewState();
+
+// Strict recorder mode (requireSubagentReview): an opt-in policy that closes
+// the root-session self-approval path which default content binding keeps
+// open for read-only reviewer relays. Approvals must be recorded from a
+// subagent session (lineage, not agent role); changes-requested verdicts
+// stay relayable.
+console.log("- Strict Recorder Mode (requireSubagentReview) -");
+const strictSummary = "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.";
+const strictRepo = join(root, "wg-review-strict");
+mkdirSync(strictRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/strict-recorder"], { cwd: strictRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: strictRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: strictRepo });
+writeFileSync(join(strictRepo, "code.txt"), "base\n");
+spawnSync("git", ["add", "code.txt"], { cwd: strictRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: strictRepo });
+mkdirSync(join(strictRepo, ".opencode"), { recursive: true });
+writeFileSync(join(strictRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true, requireSubagentReview: true }));
+const strictPlugin = await WorkflowGuard({
+	directory: root,
+	worktree: root,
+	client: fakeClient as any,
+	project: {} as any,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+const strictPrProbe = { tool: "bash", input: { command: "gh pr create --title t --body 'Changelog: strict'", workdir: strictRepo } };
+
+// Root-session self-approval is rejected before any verdict is recorded
+const strictRootAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-approved", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+const strictRootAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-strict-root");
+check("strict mode: root-session approval is rejected with an actionable cause", typeof strictRootAttempt === "string" && strictRootAttempt.includes("rejected") && strictRootAttempt.includes("requireSubagentReview") && !strictRootAttempt.includes("APPROVED"));
+check("strict mode: rejected root approval is audited as subagent_recorder_required", strictRootAudit?.reason === "subagent_recorder_required");
+const strictStatusAfterRoot = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: strictRepo }, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: review gate stays unsatisfied after rejected self-approval", strictStatusAfterRoot.outstandingRequirements.includes("review") && strictStatusAfterRoot.lastReview === null && strictStatusAfterRoot.projectConfig?.requireSubagentReview === true);
+const strictPrAfterRoot = JSON.parse(String(await strictPlugin.tool?.guard_why?.execute(strictPrProbe, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: PR preflight still blocked after rejected self-approval", strictPrAfterRoot.status === "blocked" && strictPrAfterRoot.message.includes("Passing secondary review approval is required"));
+
+// Changes-requested findings remain relayable from the root session
+const strictRootNegative = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-flagged", summary: strictSummary, passed: false },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode: root session may still relay changes-requested verdicts", typeof strictRootNegative === "string" && strictRootNegative.includes("CHANGES REQUESTED"));
+
+// A subagent session (has a parent) records the approval
+fakeParents.set("s-strict-reviewer", "s-strict-root");
+const strictSubagentResult = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "strict-reviewer", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-reviewer", agent: "general", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode: subagent recorder records the approval", typeof strictSubagentResult === "string" && strictSubagentResult.includes("APPROVED"));
+const strictStatusAfterSubagent = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: strictRepo }, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: subagent approval satisfies the review gate", !strictStatusAfterSubagent.outstandingRequirements.includes("review") && strictStatusAfterSubagent.lastReview?.fresh === true);
+const strictPrAfterSubagent = JSON.parse(String(await strictPlugin.tool?.guard_why?.execute(strictPrProbe, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: PR preflight passes after subagent-recorded approval", strictPrAfterSubagent.status !== "blocked" && (strictPrAfterSubagent.status === "allowed" || strictPrAfterSubagent.code === "remote_state_unchecked"));
+if (strictPrAfterSubagent.status === "blocked") console.log("   blocked:", strictPrAfterSubagent.message);
+
+// The knob follows the REVIEWED workspace's config, not the caller's: a root
+// session based in a non-strict context cannot approve strictRepo's work by
+// naming it as the reviewed directory from outside strict mode. Note the
+// reviewed workspace comes from the tool ARG (`directory`), not the caller's
+// context; the context worktree below is deliberately the non-strict temp root.
+const strictCrossAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "cross-root", summary: strictSummary, passed: true, directory: strictRepo },
+	{ sessionID: "s-strict-cross", worktree: root, directory: root } as any,
+);
+const strictCrossAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-strict-cross");
+check("strict mode: the knob follows the reviewed workspace, not the caller's repo", typeof strictCrossAttempt === "string" && strictCrossAttempt.includes("rejected") && strictCrossAttempt.includes("requireSubagentReview") && !strictCrossAttempt.includes("APPROVED"));
+check("strict mode: cross-repo root approval audited as subagent_recorder_required", strictCrossAudit?.reason === "subagent_recorder_required");
+
+// Env override: =0 disables the knob even when project config enables it
+process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW = "0";
+const strictEnvOff = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "env-off-root", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode env off: WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0 overrides the enabled project config", typeof strictEnvOff === "string" && strictEnvOff.includes("APPROVED"));
+delete process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW;
+
+rmSync(strictRepo, { recursive: true, force: true });
+resetReviewState();
+
+// Environment overrides follow the requireReview pattern; the default keeps
+// root-session relay recording allowed without the knob.
+const relaxedRepo = join(root, "wg-review-relaxed");
+mkdirSync(relaxedRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/relaxed-recorder"], { cwd: relaxedRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: relaxedRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: relaxedRepo });
+writeFileSync(join(relaxedRepo, "code.txt"), "base\n");
+spawnSync("git", ["add", "code.txt"], { cwd: relaxedRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: relaxedRepo });
+process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW = "1";
+const relaxedEnvAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-approved", summary: strictSummary, passed: true },
+	{ sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any,
+);
+check("strict recorder env override: WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1 applies without project config", typeof relaxedEnvAttempt === "string" && relaxedEnvAttempt.includes("rejected") && relaxedEnvAttempt.includes("subagent"));
+const relaxedEnvStatus = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: relaxedRepo }, { sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any)));
+check("strict recorder env override: status echoes the forced requirement", relaxedEnvStatus.projectConfig?.requireSubagentReview === true);
+delete process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW;
+const relaxedDefault = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "relayed-reviewer", summary: strictSummary, passed: true },
+	{ sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any,
+);
+check("strict recorder default: root-session relay recording stays allowed without the knob", typeof relaxedDefault === "string" && relaxedDefault.includes("APPROVED"));
+rmSync(relaxedRepo, { recursive: true, force: true });
+resetReviewState();
+
 // Event hook handles permission events
 if (typeof customPlugin.event === "function") {
 	await customPlugin.event({
@@ -2743,6 +3345,17 @@ check("checkInteractiveTtyCommand permits top long-form batch flag", !checkInter
 check("checkInteractiveTtyCommand permits hyphenated top-like filename", !checkInteractiveTtyCommand("ls top-level-dir").isInteractive);
 check("top batch mode does not hide another interactive monitor", checkInteractiveTtyCommand("top -b -n 1; htop").isInteractive);
 check("top batch mode does not hide a later interactive top", checkInteractiveTtyCommand("top -b -n 1; top").isInteractive);
+check("checkInteractiveTtyCommand permits top as an argument value", !checkInteractiveTtyCommand("az keyvault secret show --vault-name jcs-pim-vault-nz --name top").isInteractive);
+check("checkInteractiveTtyCommand permits an unquoted top argument", !checkInteractiveTtyCommand("echo top").isInteractive);
+check("checkInteractiveTtyCommand still detects a monitor after a pipe", checkInteractiveTtyCommand("cat file | top").isInteractive);
+check("checkInteractiveTtyCommand still detects a wrapped monitor", checkInteractiveTtyCommand("sudo top").isInteractive);
+check("checkInteractiveTtyCommand still detects busybox top", checkInteractiveTtyCommand("busybox top").isInteractive);
+check("checkInteractiveTtyCommand detects eval-wrapped monitor", checkInteractiveTtyCommand("eval top").isInteractive);
+check("checkInteractiveTtyCommand detects shell -c monitor", checkInteractiveTtyCommand("bash -c top").isInteractive);
+check("checkInteractiveTtyCommand detects shell -lc quoted monitor", checkInteractiveTtyCommand("sh -lc 'htop'").isInteractive);
+check("checkInteractiveTtyCommand permits a quoted separator before a monitor name", !checkInteractiveTtyCommand('echo "run; top"').isInteractive);
+check("checkInteractiveTtyCommand detects timeout-wrapped monitor", checkInteractiveTtyCommand("timeout 5 top").isInteractive);
+check("checkInteractiveTtyCommand detects a backgrounded-wrapper monitor", checkInteractiveTtyCommand("sudo -b top").isInteractive);
 check("checkInteractiveTtyCommand detects sudo", checkInteractiveTtyCommand("sudo apt-get update").isInteractive);
 check("checkInteractiveTtyCommand detects git rebase -i", checkInteractiveTtyCommand("git rebase -i HEAD~2").isInteractive);
 check("checkInteractiveTtyCommand detects npm init without -y", checkInteractiveTtyCommand("npm init").isInteractive);
@@ -2757,6 +3370,7 @@ check("shell tool blocks less", blocked(await shell("less package.json")));
 check("shell tool blocks top", blocked(await shell("top")));
 check("shell tool allows top batch mode", !(await shell("top -b -n 1")));
 check("shell tool allows top long-form batch flag", !(await shell("top --batch -n 1")));
+check("shell tool allows top as an argument value", !(await shell("az keyvault secret show --vault-name jcs-pim-vault-nz --name top")));
 check("shell tool blocks npm init without flag", blocked(await shell("npm init")));
 check("shell tool allows npm init -y", !(await shell("npm init -y")));
 
@@ -2974,6 +3588,21 @@ check(
 	!rogueCleanup.success && existsSync(join(roguePath, "keep.txt")),
 );
 
+// Idempotent cleanup: a registered worktree whose directory vanished (the
+// prunable admin entry `git worktree list` shows) must be deregistered rather
+// than refused, while unregistered missing paths stay refused.
+const prunableCreate = createGitWorktree("feat/prunable-cleanup", "HEAD", worktreeBaseRepo);
+check("prunable-cleanup setup creates a worktree", prunableCreate.success && typeof prunableCreate.worktreePath === "string");
+const prunablePath = prunableCreate.worktreePath!;
+rmSync(prunablePath, { recursive: true, force: true });
+const prunableListedBefore = (spawnSync("git", ["worktree", "list", "--porcelain"], { cwd: worktreeBaseRepo, encoding: "utf8" }).stdout ?? "").includes(prunablePath);
+check("a removed-directory worktree is still listed as prunable before cleanup", prunableListedBefore);
+const prunableCleanup = cleanupGitWorktree(prunablePath, worktreeBaseRepo);
+const prunableStillListed = (spawnSync("git", ["worktree", "list", "--porcelain"], { cwd: worktreeBaseRepo, encoding: "utf8" }).stdout ?? "").includes(prunablePath);
+check("cleanupGitWorktree deregisters a registered worktree whose directory is missing", prunableCleanup.success && !prunableStillListed);
+const missingRogue = cleanupGitWorktree(join(storageBase, "missing-rogue"), worktreeBaseRepo);
+check("cleanupGitWorktree still refuses an unregistered missing path", !missingRogue.success);
+
 // Snapshot integrity: when the snapshot commit cannot be established (e.g. a
 // failing pre-commit hook), cleanup must abort and preserve the worktree.
 const failingHooks = mkdtempSync(join(tmpdir(), "wg-wt-hooks-"));
@@ -3067,6 +3696,53 @@ delete process.env.GIT_INDEX_FILE;
 delete process.env.GIT_DIR;
 check("getCleanGitEnv strips git context variables", typeof getCleanGitEnv().GIT_INDEX_FILE === "undefined");
 
+// Partial-failure rollback: git creates the branch ref before the worktree
+// checkout, so a failure after that point must not leave the branch behind,
+// must not delete a branch that already existed, must leave a pre-existing
+// target path intact, and must report the git exit status rather than only
+// stderr progress text.
+const storageBaseForRollback = getWorktreeStorageDir(worktreeBaseRepo);
+mkdirSync(storageBaseForRollback, { recursive: true });
+const rollbackBranch = "feat/rollback-partial";
+const rollbackCollision = join(storageBaseForRollback, "feat-rollback-partial");
+writeFileSync(rollbackCollision, "path collision\n");
+const rollbackRes = createGitWorktree(rollbackBranch, "HEAD", worktreeBaseRepo);
+check(
+	"partial worktree add failure reports git exit status, not only stderr progress",
+	rollbackRes.success === false && /exit status/.test(String(rollbackRes.error)),
+);
+check(
+	"partial worktree add failure rolls back the created branch",
+	spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${rollbackBranch}`], { cwd: worktreeBaseRepo }).status !== 0,
+);
+check("partial worktree add failure leaves a pre-existing target path intact", existsSync(rollbackCollision) && readFileSync(rollbackCollision, "utf8") === "path collision\n");
+const preservedBranch = "feat/preserve-on-fail";
+spawnSync("git", ["branch", preservedBranch], { cwd: worktreeBaseRepo });
+writeFileSync(join(storageBaseForRollback, "feat-preserve-on-fail"), "blocker\n");
+createGitWorktree(preservedBranch, "HEAD", worktreeBaseRepo);
+check(
+	"a pre-existing branch is not deleted when worktree add fails",
+	spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${preservedBranch}`], { cwd: worktreeBaseRepo }).status === 0,
+);
+// A colliding sanitized path must never let rollback destroy a live
+// registered worktree (duplicate names, concurrent subagents, feat/x vs
+// feat:x). The failed add must leave it and its uncommitted work intact.
+const liveCollision = createGitWorktree("feat/live-collision", "HEAD", worktreeBaseRepo);
+check("live-collision setup creates a registered worktree", liveCollision.success && typeof liveCollision.worktreePath === "string");
+const liveCollisionPath = liveCollision.worktreePath!;
+writeFileSync(join(liveCollisionPath, "uncommitted-work.txt"), "do not lose me\n");
+const duplicateCreate = createGitWorktree("feat/live-collision", "HEAD", worktreeBaseRepo);
+const liveSurvived = existsSync(liveCollisionPath) && existsSync(join(liveCollisionPath, "uncommitted-work.txt"));
+const liveCleanup = cleanupGitWorktree(liveCollisionPath, worktreeBaseRepo);
+check(
+	"failed duplicate create leaves a live registered worktree and its uncommitted work intact",
+	duplicateCreate.success === false && liveSurvived && liveCleanup.success,
+);
+process.env.WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS = "2500";
+check("resolveWorktreeTimeoutMs honors WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS", resolveWorktreeTimeoutMs() === 2500);
+delete process.env.WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS;
+check("resolveWorktreeTimeoutMs falls back to the 15s default", resolveWorktreeTimeoutMs() === 15_000);
+
 rmSync(worktreeBaseRepo, { recursive: true, force: true });
 delete process.env.WORKFLOW_GUARD_WORKTREE_DIR;
 rmSync(worktreeStorage, { recursive: true, force: true });
@@ -3915,6 +4591,80 @@ 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;
 
+// Loaded plugin version visibility: OpenCode resolves configured bare plugin
+// names through Node's parent-directory lookup from its configuration
+// location, so the loaded copy can silently differ from a globally
+// npm-installed one (observed on-device: npm i -g updates ignored while a
+// home-level pnpm node_modules copy kept loading). The version is therefore
+// surfaced in guard_status and in the startup app log.
+console.log("- Git hygiene snapshot -");
+const hygieneRepo = join(root, "wg-hygiene");
+mkdirSync(hygieneRepo, { recursive: true });
+const hgit = (args: string[]): string => {
+	const res = spawnSync("git", args, { cwd: hygieneRepo, encoding: "utf8" });
+	if (res.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${res.stderr}`);
+	return res.stdout;
+};
+hgit(["init", "-b", "main"]);
+hgit(["config", "user.email", "test@test.local"]);
+hgit(["config", "user.name", "Test Runner"]);
+writeFileSync(join(hygieneRepo, "base.txt"), "base\n");
+hgit(["add", "base.txt"]);
+hgit(["commit", "-m", "base"]);
+hgit(["switch", "-c", "feature/done"]);
+writeFileSync(join(hygieneRepo, "done.txt"), "done\n");
+hgit(["add", "done.txt"]);
+hgit(["commit", "-m", "done work"]);
+hgit(["switch", "main"]);
+hgit(["merge", "--ff-only", "feature/done"]);
+hgit(["switch", "-c", "feature/open"]);
+writeFileSync(join(hygieneRepo, "open.txt"), "open\n");
+hgit(["add", "open.txt"]);
+hgit(["commit", "-m", "open work"]);
+// Prunable worktree: register one, then delete its directory (crashed-add
+// simulation) so the admin entry stays behind.
+hgit(["worktree", "add", join(root, "wg-hygiene-wt"), "feature/done"]);
+rmSync(join(root, "wg-hygiene-wt"), { recursive: true, force: true });
+const hygieneStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneRepo }, { sessionID: "s-hygiene", worktree: hygieneRepo, directory: hygieneRepo } as any)));
+check("guard_status exposes the git hygiene snapshot", typeof hygieneStatus.gitHygiene === "object" && hygieneStatus.gitHygiene !== null);
+check("hygiene lists merged local branches excluding the current and unmerged", Array.isArray(hygieneStatus.gitHygiene.mergedLocalBranches) && hygieneStatus.gitHygiene.mergedLocalBranches.includes("feature/done") && !hygieneStatus.gitHygiene.mergedLocalBranches.includes("feature/open") && !hygieneStatus.gitHygiene.mergedLocalBranches.includes("main"));
+check("hygiene counts prunable worktree admin entries", hygieneStatus.gitHygiene.prunableWorktreeCount === 1);
+check("hygiene omits base-behind without a remote", hygieneStatus.gitHygiene.baseBehind === undefined);
+// The list is capped while the count reflects reality.
+for (let i = 0; i < 12; i++) {
+	hgit(["switch", "main"]);
+	hgit(["switch", "-c", `feature/merged-${i}`]);
+	writeFileSync(join(hygieneRepo, `merged-${i}.txt`), `${i}\n`);
+	hgit(["add", `merged-${i}.txt`]);
+	hgit(["commit", "-m", `merged ${i}`]);
+	hgit(["switch", "main"]);
+	hgit(["merge", "--ff-only", `feature/merged-${i}`]);
+}
+// End on a merged, non-base current branch: the current-branch filter must
+// exclude it from the merged list independently of the base filter.
+hgit(["switch", "feature/merged-11"]);
+const cappedStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneRepo }, { sessionID: "s-hygiene-capped", worktree: hygieneRepo, directory: hygieneRepo } as any)));
+check("hygiene branch list is capped, counts reality, and excludes the merged current branch", cappedStatus.gitHygiene.mergedLocalBranchCount === 12 && cappedStatus.gitHygiene.mergedLocalBranches.length === 10 && !cappedStatus.gitHygiene.mergedLocalBranches.includes("feature/merged-11") && cappedStatus.gitHygiene.mergedLocalBranches.includes("feature/merged-10"));
+rmSync(hygieneRepo, { recursive: true, force: true });
+const hygieneNonGit = mkdtempSync(join(tmpdir(), "wg-hygiene-nongit-"));
+const nonGitStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneNonGit }, { sessionID: "s-hygiene-nongit", worktree: hygieneNonGit, directory: hygieneNonGit } as any)));
+check("hygiene snapshot is null outside a git repository", nonGitStatus.gitHygiene === null);
+rmSync(hygieneNonGit, { recursive: true, force: true });
+
+console.log("- Loaded plugin version visibility -");
+const expectedVersion = String((JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version);
+check("loadedPluginVersion reads the adjacent package manifest", loadedPluginVersion() === expectedVersion);
+check("loadedPluginVersion fails soft for an unreadable manifest", loadedPluginVersion(pathToFileURL(join(root, "wg-version-none", "src", "workflow-guard.ts")).href) === undefined);
+const versionStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: root }, { sessionID: "s-version", worktree: root, directory: root } as any)));
+check("guard_status exposes the loaded plugin version", versionStatus.pluginVersion === expectedVersion);
+const versionLogs: string[] = [];
+await WorkflowGuard({
+	directory: root,
+	worktree: root,
+	client: { app: { log: async (opts: { body: { message: string } }) => { versionLogs.push(opts.body.message); } } } as any,
+} as any);
+check("startup app log states the loaded plugin version", versionLogs.some((message) => message.startsWith(`Workflow Guard v${expectedVersion} plugin initialized for ${root}; `) && message.includes("managed config")));
+
 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");