opencode-workflow-guard 1.14.1 → 1.15.1

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";
@@ -74,6 +75,7 @@ import {
 	checkLockfileSync,
 	branchHasDocumentationChange,
 	isDocumentationRequired,
+	loadedPluginVersion,
 	isReviewRequired,
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
@@ -678,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" })));
 
@@ -897,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-"));
@@ -1406,22 +1600,19 @@ const fakeV2TuiCtx = {
 	ui: { slot: (claim: { append: string; render: () => unknown }) => { v2SlotClaims.push(claim); } },
 };
 await WorkflowGuardTuiV2(fakeV2TuiCtx as any);
-check("v2 tui companion registers home and prompt status slots", v2SlotClaims.filter((claim) => claim.append === "home.footer.status" || claim.append === "prompt.footer.status").length === 2);
+check("v2 tui companion registers only the prompt footer status slot", v2SlotClaims.filter((claim) => claim.append === "home.footer.status" || claim.append === "prompt.footer.status").length === 1 && v2SlotClaims.some((claim) => claim.append === "prompt.footer.status"));
 const diagLogPath = join(process.env.XDG_STATE_HOME!, "opencode", "workflow-guard-ui.log");
 const diagLogText = () => readFileSync(diagLogPath, "utf8");
 check("v2 tui companion logs module load and setup with app version", diagLogText().includes("module load:") && diagLogText().includes("setup: app=9.9.9-test"));
-const v2HomeRender = v2SlotClaims.find((claim) => claim.append === "home.footer.status")!.render;
+const v2StatusRender = v2SlotClaims.find((claim) => claim.append === "prompt.footer.status")!.render;
 // In a plain Node process there is no OpenTUI renderer, so badge() throws the
 // same "No renderer found" the long-running-session bug produced in the TUI.
-check("v2 slot render returns null instead of throwing when the render context is unavailable", v2HomeRender() === null);
-check("v2 slot failure log records probes and stack", diagLogText().includes("render home.footer.status FAILED (1/3)") && diagLogText().includes("owner=null") && diagLogText().includes("useContext(RendererContext): MISSING") && diagLogText().includes("  stack: "));
-for (let i = 0; i < 6; i++) v2HomeRender();
-const v2FailuresLogged = diagLogText().split("\n").filter((line) => line.includes("render home.footer.status FAILED (")).length;
+check("v2 slot render returns null instead of throwing when the render context is unavailable", v2StatusRender() === null);
+check("v2 slot failure log records probes and stack", diagLogText().includes("render prompt.footer.status FAILED (1/3)") && diagLogText().includes("owner=null") && diagLogText().includes("useContext(RendererContext): MISSING") && diagLogText().includes("  stack: "));
+for (let i = 0; i < 6; i++) v2StatusRender();
+const v2FailuresLogged = diagLogText().split("\n").filter((line) => line.includes("render prompt.footer.status FAILED (")).length;
 check("v2 slot failure logging is bounded to 3 per success epoch", v2FailuresLogged === 3);
 check("v2 slot failure suppression notice is logged once", diagLogText().split("still failing after 3 logged failures").length === 2);
-const v2PromptRender = v2SlotClaims.find((claim) => claim.append === "prompt.footer.status")!.render;
-check("v2 prompt status slot also degrades to null on render failure", v2PromptRender() === null);
-
 
 // ── Adversarial tests & hardened invariants ──
 console.log("- Adversarial tests & hardened invariants -");
@@ -2427,6 +2618,36 @@ check(
 );
 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
@@ -2677,6 +2898,119 @@ check("PR blocked when only the reviewed commit drifted, with a commit-specific
 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({
@@ -2786,6 +3120,39 @@ spawnSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: conf
 const baseUpToDateCheck = checkBranchBaseIsUpToDate(conflictRepo);
 check("checkBranchBaseIsUpToDate passes when equal to remote", !baseUpToDateCheck.isBehind);
 
+// Policy 20: branch creation start-point awareness. Advance the simulated
+// remote past the current branch so HEAD is stale, then verify that an
+// explicit fresh start point clears the gate while startless and
+// indeterminate creations still fail (closed).
+spawnSync("git", ["switch", "-c", "wg-origin-advance"], { cwd: conflictRepo });
+writeFileSync(join(conflictRepo, "file.txt"), "remote advance content\n");
+spawnSync("git", ["commit", "-am", "remote advance"], { cwd: conflictRepo });
+spawnSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: conflictRepo });
+spawnSync("git", ["switch", "feat/conflict-branch"], { cwd: conflictRepo });
+const staleHeadCheck = checkBranchBaseIsUpToDate(conflictRepo);
+check(
+	"checkBranchBaseIsUpToDate attributes the stale current branch and working remedies",
+	staleHeadCheck.isBehind &&
+		staleHeadCheck.baseRef === "origin/main" &&
+		(staleHeadCheck.reason ?? "").includes("'feat/conflict-branch'") &&
+		(staleHeadCheck.reason ?? "").includes("git rebase origin/main"),
+);
+const freshStartCheck = checkBranchBaseIsUpToDate(conflictRepo, ["origin/main"]);
+check("checkBranchBaseIsUpToDate accepts an explicit start point containing the remote default", !freshStartCheck.isBehind);
+const staleStartSha = spawnSync("git", ["rev-parse", "HEAD"], { cwd: conflictRepo, encoding: "utf8" }).stdout!.trim();
+const staleStartCheck = checkBranchBaseIsUpToDate(conflictRepo, [staleStartSha]);
+check("checkBranchBaseIsUpToDate blocks an explicit stale start point", staleStartCheck.isBehind && (staleStartCheck.reason ?? "").includes("start point"));
+const unresolvableCheck = checkBranchBaseIsUpToDate(conflictRepo, ["$WG_START_REF"]);
+check("checkBranchBaseIsUpToDate fails closed on an unresolvable start point", unresolvableCheck.isBehind && (unresolvableCheck.reason ?? "").includes("could not be resolved"));
+const mixedStartCheck = checkBranchBaseIsUpToDate(conflictRepo, ["origin/main", undefined]);
+check("checkBranchBaseIsUpToDate keeps the head check when a creation lacks a start point", mixedStartCheck.isBehind && (mixedStartCheck.reason ?? "").includes("'feat/conflict-branch'"));
+check("git switch -c without a start point is blocked on a stale branch", blocked(await shell("git switch -c wg-start-stale")));
+check("git switch -c origin/main with a stale branch is allowed", !blocked(await shell("git switch -c wg-start-fresh origin/main")));
+check("git checkout -b origin/main with a stale branch is allowed", !blocked(await shell("git checkout -b wg-checkout-fresh origin/main")));
+check("wrapper git switch -c origin/main keeps the fresh start point exemption", !blocked(await shell("env git switch -c wg-wrapper-fresh origin/main")));
+check("variable start point fails closed on a stale branch", blocked(await shell("git switch -c wg-start-var $WG_REF")));
+check("plain git branch is not treated as guarded branch creation", !blocked(await shell("git branch wg-plain-branch origin/main")));
+
 // Lockfile synchronization tests
 const lockRepo = mkdtempSync(join(tmpdir(), "wg-lock-repo-"));
 spawnSync("git", ["init", "-b", "main"], { cwd: lockRepo });
@@ -4254,6 +4621,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");