opencode-workflow-guard 1.15.1 → 1.15.3

package/src/workflow-guard.ts

@@ -15,12 +15,14 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { join } from "node:path";
 import { loadedPluginVersion } from "./lib/version.ts";
-import { editTargets, runPostEditValidators, snapshotFile } from "./policies/post-edit-validation.ts";
+import { editTargets, runPostEditValidators, snapshotFile, type FileSnapshot } from "./policies/post-edit-validation.ts";
 import { claimFiles, releaseFileClaims } from "./policies/file-claims.ts";
+import { extractCommands, splitShellSegments } from "./lib/shell.ts";
+import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, redirectMutationsIn } from "./policies/boundary.ts";
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
-import { guardToolCallImpl, isReadOnlyRole } from "./lib/guard-dispatcher.ts";
+import { guardToolCallImpl, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
@@ -84,6 +86,9 @@ import {
 	sessionReviews,
 	setSessionWorkspace,
 	getSessionWorkspace,
+	getSessionBoundWorkspace,
+	registerSessionWorkspaceFromToolCall,
+	resolveSessionBoundWorkspace,
 	resolveEffectiveWorkspace,
 } from "./lib/state.ts";
 import { findGitRoot, isSameGitRepo, loadProjectConfig, reloadProjectConfig, stripJsonComments } from "./lib/project-config.ts";
@@ -116,6 +121,9 @@ export {
 	resetReviewState,
 	setSessionWorkspace,
 	getSessionWorkspace,
+	getSessionBoundWorkspace,
+	registerSessionWorkspaceFromToolCall,
+	resolveSessionBoundWorkspace,
 	resolveEffectiveWorkspace,
 	findGitRoot,
 	isSameGitRepo,
@@ -448,12 +456,16 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 		tool: createCustomTools({ effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client: ctx.client }),
 
 		"tool.execute.before": async (input, output) => {
-			const toolWorktree =
+			const hostWorktree =
 				(input as { worktree?: string })?.worktree ||
 				(input as { directory?: string })?.directory ||
 				(output as { worktree?: string })?.worktree ||
-				(output as { directory?: string })?.directory ||
-				effectiveRoot;
+				(output as { directory?: string })?.directory;
+			// Session-bound workspace before the plugin-instance fallback:
+			// concurrent loops share this process, and a fallback derived from
+			// the last-active instance must not re-anchor another session's
+			// policy context.
+			const toolWorktree = hostWorktree || getSessionBoundWorkspace(input.sessionID) || effectiveRoot;
 			const toolAgent =
 				(input as { agent?: string })?.agent ||
 				(output as { agent?: string })?.agent;
@@ -480,11 +492,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 					const record = asRecord(args);
 					const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
 					const filePath = typeof record?.filePath === "string" ? record.filePath : (typeof record?.path === "string" ? record.path : undefined);
-					const candidatePath = workdir ?? filePath ?? toolWorktree;
-					if (candidatePath) {
-						const gitRoot = findGitRoot(candidatePath);
-						if (gitRoot) setSessionWorkspace(input.sessionID, gitRoot);
-					}
+					registerSessionWorkspaceFromToolCall(input.sessionID, { workdir, filePath, hostWorktree, toolWorktree });
 				}
 				if (input.tool === "read") {
 					const target = editTargets(args, toolWorktree)[0];
@@ -497,6 +505,32 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 					const snapshots = editTargets(args, toolWorktree).map(snapshotFile);
 					if (snapshots.length) toolLifecycle.setPostEditSnapshots(input.sessionID, input.callID, toolWorktree, snapshots);
 				}
+				if (SHELL_TOOL_NAMES.has(input.tool)) {
+					// An allowed shell redirect authors the target's bytes exactly
+					// like edit/write (LL-003), so pre-register each redirect
+					// target's pre-state and seed the session's freshness
+					// observation after the call succeeds. Observation only: shell
+					// writes never run the post-edit validators.
+					const record = asRecord(args);
+					const shellWorkdir = typeof record?.workdir === "string" ? record.workdir : undefined;
+					const shellCwd = shellWorkdir ? resolve(toolWorktree, shellWorkdir) : toolWorktree;
+					const snapshots: FileSnapshot[] = [];
+					for (const command of extractCommands(args)) {
+						for (const segment of splitShellSegments(command)) {
+							for (const mutation of redirectMutationsIn(segment)) {
+								const target = mutation.target ?? "";
+								if (!target || target === "/dev/null") continue;
+								const expanded = expandShellTargetPath(target);
+								if (!expanded) continue;
+								const resolvedTarget = resolve(shellCwd, expanded);
+								if (resolvedTarget === OPENCODE_SCRATCH_DIR || resolvedTarget.startsWith(OPENCODE_SCRATCH_DIR + "/")) continue;
+								if (isPathOutsideWorkspace(resolvedTarget, toolWorktree)) continue;
+								snapshots.push(snapshotFile(resolvedTarget));
+							}
+						}
+					}
+					if (snapshots.length) toolLifecycle.setShellWriteSnapshots(input.sessionID, input.callID, toolWorktree, snapshots);
+				}
 			});
 		},
 
@@ -520,6 +554,14 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 				const observation = toolLifecycle.takeReadObservation(input.sessionID, input.callID);
 				if (observation) recordSuccessfulRead(observation, input.sessionID);
 			}
+			const shellPending = toolLifecycle.takeShellWriteSnapshots(input.sessionID, input.callID);
+			if (shellPending) {
+				// An allowed shell redirect authored these bytes (LL-003): seed
+				// the session's observation so a follow-up edit needs no
+				// redundant re-read. The digest gate keeps no-op/failed calls
+				// from seeding; validators are intentionally not run here.
+				for (const before of shellPending.snapshots) recordMutationObservation(before.path, input.sessionID, before.digest);
+			}
 			const pending = toolLifecycle.takePostEditSnapshots(input.sessionID, input.callID);
 			if (!pending) return;
 			await runWithRuntimeState(pending.root, ctx.client, async () => {

package/test/test-e2e.mts

@@ -220,12 +220,24 @@ const runV2Probes = async (ctx: any) => {
 \tconst guardWhy = byId("guard_why");
 \tconst pick = (r: any) => (typeof r?.content === "string" ? r.content : JSON.stringify(r));
 \tconst statusRes = guardStatus ? await guardStatus.execute({}, headlessToolContext) : undefined;
-\tconst whyRes = guardWhy ? await guardWhy.execute({ tool: "bash", input: { command: "git push origin main" } }, headlessToolContext) : undefined;
+\tconst whyProbes: Record<string, { tool: string; input: Record<string, unknown> }> = {
+\t\tgit: { tool: "bash", input: { command: "git push origin main" } },
+\t\t"secrets-read": { tool: "read", input: { filePath: ".env" } },
+\t\t"secrets-shell": { tool: "bash", input: { command: "cat .env" } },
+\t\t"boundary-write": { tool: "write", input: { filePath: "../outside_escaped.txt", content: "probe" } },
+\t\t"shell-tty": { tool: "bash", input: { command: "vim notes.txt" } },
+\t};
+\tconst whyResults: Record<string, any> = {};
+\tfor (const [name, probe] of Object.entries(whyProbes)) {
+\t\tconst res = guardWhy ? await guardWhy.execute(probe, headlessToolContext) : undefined;
+\t\twhyResults[name] = res === undefined ? null : JSON.parse(pick(res));
+\t}
 \twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({
 \t\ttools: tools.map((t: any) => t.id),
 \t\ttodowriteEnriched: Boolean(todowrite?.description?.includes("Workflow Guard lifecycle")),
 \t\tstatus: JSON.parse(pick(statusRes)),
-\t\twhy: JSON.parse(pick(whyRes)),
+\t\twhy: whyResults.git,
+\t\twhyProbes: whyResults,
 \t}) + "\\n");
 \twriteFileSync(${JSON.stringify(initializedMarker)}, "initialized\\n");
 };
@@ -235,8 +247,19 @@ const runV1Probes = async (ctx: any) => {
 \tconst directory = ctx?.location?.directory ?? ctx?.directory ?? process.cwd();
 \tconst toolCtx = { sessionID: "headless-e2e", directory, worktree: directory };
 \tconst status = await hooks.tool?.guard_status?.execute({}, toolCtx);
-\tconst why = await hooks.tool?.guard_why?.execute({ tool: "bash", input: { command: "git push origin main" } }, toolCtx);
-\twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({ status: JSON.parse(String(status)), why: JSON.parse(String(why)) }) + "\\n");
+\tconst whyProbes: Record<string, { tool: string; input: Record<string, unknown> }> = {
+\t\tgit: { tool: "bash", input: { command: "git push origin main" } },
+\t\t"secrets-read": { tool: "read", input: { filePath: ".env" } },
+\t\t"secrets-shell": { tool: "bash", input: { command: "cat .env" } },
+\t\t"boundary-write": { tool: "write", input: { filePath: "../outside_escaped.txt", content: "probe" } },
+\t\t"shell-tty": { tool: "bash", input: { command: "vim notes.txt" } },
+\t};
+\tconst whyResults: Record<string, any> = {};
+\tfor (const [name, probe] of Object.entries(whyProbes)) {
+\t\tconst res = await hooks.tool?.guard_why?.execute(probe, toolCtx);
+\t\twhyResults[name] = res === undefined ? null : JSON.parse(String(res));
+\t}
+\twriteFileSync(${JSON.stringify(accountabilityMarker)}, JSON.stringify({ status: JSON.parse(String(status)), why: whyResults.git, whyProbes: whyResults }) + "\\n");
 \twriteFileSync(${JSON.stringify(initializedMarker)}, "initialized\\n");
 \treturn hooks;
 };
@@ -266,6 +289,18 @@ check("local plugin adapter and source copied successfully", existsSync(localAda
 spawnSync("git", ["init", "-b", "feat/install-verification"], { cwd: testDir });
 spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: testDir });
 spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: testDir });
+// Project configuration loads from .opencode/workflow-guard.json[c]; sentinel
+// values prove the real runtime reads project config (guard_status echoes it)
+// instead of silently falling back to defaults. Both fields are behaviorally
+// inert for every harness probe: no PR is created, record_review is not
+// called, and verifyCommand is left unset so the all-done verification gate
+// still finds no configured command in this configless test project.
+writeFileSync(join(testDir, ".opencode", "workflow-guard.json"), JSON.stringify({
+	protectedBranches: ["e2e-config-probe-branch"],
+	requireReview: false,
+	learning: true,
+	recoveryCheckpoints: true,
+}, null, 2) + "\n");
 
 const runtimeEnv: NodeJS.ProcessEnv = {
 	...process.env,
@@ -276,6 +311,10 @@ const runtimeEnv: NodeJS.ProcessEnv = {
 delete runtimeEnv.OPENCODE_PID;
 delete runtimeEnv.OPENCODE_PURE;
 delete runtimeEnv.OPENCODE;
+// The learning config key must stay load-bearing: an inherited
+// WORKFLOW_GUARD_LEARNING=1 would register the learning tools without the
+// sentinel config file being read (review P2, tool-surface iteration).
+delete runtimeEnv.WORKFLOW_GUARD_LEARNING;
 if (isOpenCodeV2) {
 	// V2 runs a shared managed service on a fixed default port. Each run uses
 	// its own isolated XDG dirs, so pick a run-unique port to keep concurrent
@@ -357,12 +396,28 @@ try {
 	headlessAccountability = JSON.parse(readFileSync(accountabilityMarker, "utf8"));
 } catch {}
 check("headless OpenCode runtime exposes structured guard status and why without TUI", headlessAccountability?.status?.workspaceRoot === testDir && headlessAccountability?.why?.policy === "git" && headlessAccountability?.why?.code === "protected_branch_push");
+const whyProbe = (name: string): any => headlessAccountability?.whyProbes?.[name];
+check("headless guard_why simulates secret read policy via read tool", whyProbe("secrets-read")?.policy === "secrets" && whyProbe("secrets-read")?.code === "secret_read" && whyProbe("secrets-read")?.status === "blocked");
+check("headless guard_why simulates secret read policy via shell", whyProbe("secrets-shell")?.policy === "secrets" && whyProbe("secrets-shell")?.code === "secret_read" && whyProbe("secrets-shell")?.status === "blocked");
+check("headless guard_why simulates workspace boundary policy via write tool", whyProbe("boundary-write")?.policy === "boundary" && whyProbe("boundary-write")?.code === "workspace_escape" && whyProbe("boundary-write")?.status === "blocked");
+check("headless guard_why simulates interactive tty shell-safety policy", whyProbe("shell-tty")?.policy === "shell-safety" && whyProbe("shell-tty")?.code === "interactive_tty" && whyProbe("shell-tty")?.status === "blocked");
+check("headless guard_status reports project config loaded from .opencode/workflow-guard.json", headlessAccountability?.status?.projectConfig?.protectedBranches?.[0] === "e2e-config-probe-branch" && headlessAccountability?.status?.projectConfig?.requireReview === false);
 if (isOpenCodeV2) {
 	// The V2 adapter runs the shipped setup(ctx) for real; verify the
 	// registered tool surface. Builtin description enrichment is best-effort:
 	// builtins are not visible to ctx.tool.list() during plugin setup, so
 	// todowriteEnriched is reported but not asserted.
 	check("V2 setup registers custom guard tools", (headlessAccountability?.tools ?? []).includes("guard_status") && (headlessAccountability?.tools ?? []).includes("guard_why"));
+	const expectedGuardTools = [
+		"guard_status", "guard_why", "guard_audit", "guard_next_tasks", "record_review",
+		"guard_review_rubric", "guard_review_followups", "guard_review_followup_resolve",
+		"guard_worktree_create", "guard_worktree_cleanup",
+		"project_memory_record", "project_memory_search", "project_memory_export", "project_memory_import",
+		"learning_checkpoint", "learning_profile", "learning_record", "guard_recovery_restore",
+	];
+	const missingGuardTools = expectedGuardTools.filter((id) => !(headlessAccountability?.tools ?? []).includes(id));
+	check("V2 setup registers the full config-gated guard tool surface", missingGuardTools.length === 0);
+	if (missingGuardTools.length > 0) console.log("  missing guard tools: " + missingGuardTools.join(", "));
 	console.log(`  note: builtin todowrite description enriched under V2: ${headlessAccountability?.todowriteEnriched === true ? "yes" : "unknown at setup time"}`);
 }
 

package/test/test.mts

@@ -45,6 +45,8 @@ import {
 	persistReviewCache,
 	setSessionWorkspace,
 	getSessionWorkspace,
+	getSessionBoundWorkspace,
+	registerSessionWorkspaceFromToolCall,
 	resolveEffectiveWorkspace,
 	getLastReviewResultForWorkspace,
 	isSameGitRepo,
@@ -729,6 +731,34 @@ check("tee -- flag separator outside workspace is blocked", blocked(await call("
 check("multi-target tee with an outside path is blocked", blocked(await call("bash", { command: "echo x | tee in.txt /tmp/wg-outside-tee" }, { sessionID: "s-active" })));
 check("tee --append within workspace is allowed with todos", !(await call("bash", { command: "echo x | tee --append src/a.ts" }, { sessionID: "s-active" })));
 
+// Regression (device audit, workspace_escape): symlink aliases of the
+// workspace itself. An absolute target that is lexically outside the root
+// but canonically inside (the alias resolves back into the workspace) must
+// be accepted, while symlinks inside the workspace pointing outside stay
+// blocked. Machine-independent: the alias is built inside the fixture
+// instead of relying on host aliasing such as /home -> /var/home.
+const aliasDir = mkdtempSync(join(tmpdir(), "wg-boundary-alias-"));
+mkdirSync(join(aliasDir, "real"), { recursive: true });
+symlinkSync(aliasDir, join(aliasDir, "alias"), "dir");
+writeFileSync(join(aliasDir, "real", "existing.txt"), "keep\n");
+symlinkSync("/etc", join(aliasDir, "real", "escape"));
+setWorkspaceRoot(join(aliasDir, "real"));
+check("write through symlink alias of the workspace is allowed (new file)", !(await call("write", { filePath: join(aliasDir, "alias", "real", "new-file.txt"), content: "x" }, { sessionID: "s-active" })));
+// The write gate also applies stale-write protection (existing files need a
+// prior session read), so seed the observation by reading through the alias.
+// Plugin setup latches the process root to its directory/worktree
+// (workflow-guard.ts setWorkspaceRoot on setup), so re-latch the alias
+// workspace root before the gated checks.
+const boundaryAliasPlugin = await WorkflowGuard({ directory: root, worktree: root, client: fakeClient as any } as any);
+setWorkspaceRoot(join(aliasDir, "real"));
+await boundaryAliasPlugin["tool.execute.before"]?.({ tool: "read", sessionID: "s-active", callID: "alias-read" }, { args: { filePath: join(aliasDir, "alias", "real", "existing.txt") } } as any);
+await boundaryAliasPlugin["tool.execute.after"]?.({ tool: "read", sessionID: "s-active", callID: "alias-read", args: { filePath: join(aliasDir, "alias", "real", "existing.txt") } } as any, { title: "existing.txt", output: "keep", metadata: {} } as any);
+check("write through symlink alias of the workspace is allowed (existing file)", !(await call("write", { filePath: join(aliasDir, "alias", "real", "existing.txt"), content: "updated" }, { sessionID: "s-active" })));
+check("write through escaping symlink to an outside file stays blocked", blocked(await call("write", { filePath: join(aliasDir, "real", "escape", "passwd"), content: "x" }, { sessionID: "s-active" })));
+check("new file through an escaping symlink stays blocked", blocked(await call("write", { filePath: join(aliasDir, "real", "escape", "wg-escape-new.txt"), content: "x" }, { sessionID: "s-active" })));
+rmSync(aliasDir, { recursive: true, force: true });
+setWorkspaceRoot(root);
+
 console.log("- Compaction focus preservation & TUI toast -");
 const boundedCompaction = buildCompactionContext("## Operational Guard State\n- critical", ["## Active Tasks\n" + "a".repeat(10_000), "## Project Memory\nshould-not-fit"], 500);
 check("compaction packer enforces its total context budget", boundedCompaction.length === 500);
@@ -1226,6 +1256,72 @@ try {
 	noopEditBlocked = String(error).includes("has not been read");
 }
 check("a no-op mutation does not seed an observation for a later edit", noopEditBlocked);
+// LL-003 extension: an allowed shell redirect authors the target's bytes
+// exactly like edit/write, so the follow-up edit/write of the file it wrote
+// needs no redundant read. Seeding stays byte-change-gated: a /dev/null
+// redirect seeds nothing and an identical-bytes rewrite seeds nothing.
+const shellSession = "s-stale-shell";
+todo(shellSession, item("write scratch file via shell redirect", "in_progress"));
+const shellAuthoredPath = join(staleDir, "shell-authored.ts");
+await staleBefore?.({ tool: "bash", sessionID: shellSession, callID: "shell-write" }, { args: { command: "echo x > shell-authored.ts" } });
+writeFileSync(shellAuthoredPath, "x\n");
+await staleAfter?.({ tool: "bash", sessionID: shellSession, callID: "shell-write", args: {} }, { title: "bash", output: "x", metadata: {} });
+let shellAuthoredWriteAllowed = true;
+try {
+	await staleBefore?.({ tool: "write", sessionID: shellSession, callID: "shell-write-followup" }, { args: { filePath: shellAuthoredPath, content: "next" } });
+} catch {
+	shellAuthoredWriteAllowed = false;
+}
+check("an allowed shell redirect seeds the observation so its authored file can be written without a read", shellAuthoredWriteAllowed);
+await staleAfter?.({ tool: "write", sessionID: shellSession, callID: "shell-write-followup", args: {} }, { title: "write", output: "written", metadata: {} });
+const shellUnrelatedSession = "s-stale-shell-unrelated";
+todo(shellUnrelatedSession, item("edit file untouched by shell", "in_progress"));
+const shellUnrelatedPath = join(staleDir, "shell-untouched.ts");
+writeFileSync(shellUnrelatedPath, "observed");
+await staleBefore?.({ tool: "bash", sessionID: shellUnrelatedSession, callID: "shell-devnull" }, { args: { command: "echo x > /dev/null" } });
+await staleAfter?.({ tool: "bash", sessionID: shellUnrelatedSession, callID: "shell-devnull", args: {} }, { title: "bash", output: "x", metadata: {} });
+let shellUnrelatedWriteBlocked = false;
+try {
+	await staleBefore?.({ tool: "write", sessionID: shellUnrelatedSession, callID: "shell-untouched-write" }, { args: { filePath: shellUnrelatedPath, content: "next" } });
+} catch (error) {
+	shellUnrelatedWriteBlocked = String(error).includes("has not been read");
+}
+check("a shell redirect to /dev/null seeds nothing, so an unobserved file stays blocked", shellUnrelatedWriteBlocked);
+const shellNoopSession = "s-stale-shell-noop";
+todo(shellNoopSession, item("no-op shell redirect", "in_progress"));
+const shellNoopPath = join(staleDir, "shell-noop.ts");
+writeFileSync(shellNoopPath, "x\n");
+await staleBefore?.({ tool: "bash", sessionID: shellNoopSession, callID: "shell-noop" }, { args: { command: "echo x > shell-noop.ts" } });
+writeFileSync(shellNoopPath, "x\n");
+await staleAfter?.({ tool: "bash", sessionID: shellNoopSession, callID: "shell-noop", args: {} }, { title: "bash", output: "x", metadata: {} });
+let shellNoopWriteBlocked = false;
+try {
+	await staleBefore?.({ tool: "write", sessionID: shellNoopSession, callID: "shell-noop-write" }, { args: { filePath: shellNoopPath, content: "changed" } });
+} catch (error) {
+	shellNoopWriteBlocked = String(error).includes("has not been read");
+}
+check("a no-op shell redirect (identical bytes) does not seed an observation", shellNoopWriteBlocked);
+// Path-spelling alias convergence: an observation seeded through one
+// absolute spelling of a file must authorize the mutation requested through
+// a symlink-aliased spelling of the same file (canonicalPath convergence).
+const staleAliasDir = mkdtempSync(join(tmpdir(), "wg-stale-alias-"));
+const staleAliasRealDir = join(staleAliasDir, "real");
+mkdirSync(staleAliasRealDir);
+symlinkSync(staleAliasRealDir, join(staleAliasDir, "alias"));
+const aliasRealPath = join(staleAliasRealDir, "aliased.ts");
+writeFileSync(aliasRealPath, "observed");
+todo("s-stale-alias", item("edit aliased file", "in_progress"));
+await staleBefore?.({ tool: "read", sessionID: "s-stale-alias", callID: "alias-read", worktree: staleAliasDir } as any, { args: { filePath: aliasRealPath } });
+await staleAfter?.({ tool: "read", sessionID: "s-stale-alias", callID: "alias-read", args: { filePath: aliasRealPath } }, { title: "aliased.ts", output: "observed", metadata: {} });
+let aliasWriteAllowed = true;
+try {
+	await staleBefore?.({ tool: "write", sessionID: "s-stale-alias", callID: "alias-write", worktree: staleAliasDir } as any, { args: { filePath: join(staleAliasDir, "alias", "aliased.ts"), content: "next" } });
+} catch {
+	aliasWriteAllowed = false;
+}
+check("a read observed through one path spelling authorizes the write through its symlink alias", aliasWriteAllowed);
+await staleAfter?.({ tool: "write", sessionID: "s-stale-alias", callID: "alias-write", args: {} }, { title: "write", output: "written", metadata: {} });
+rmSync(staleAliasDir, { recursive: true, force: true });
 const staleAlternateRoot = mkdtempSync(join(tmpdir(), "wg-stale-root-"));
 writeFileSync(join(staleAlternateRoot, "relative.ts"), "observed");
 todo("s-stale-root", item("edit relative file", "in_progress"));
@@ -1735,6 +1831,10 @@ check("dynamic shell syntax detects IFS construction", dynamicShellSyntaxIn("git
 check("dynamic shell syntax detects ambiguous whitespace", dynamicShellSyntaxIn("git\rpush") !== undefined && dynamicShellSyntaxIn("git\u00a0push") !== undefined);
 check("dynamic shell syntax detects malformed quote boundaries", dynamicShellSyntaxIn("echo 'unterminated") !== undefined && dynamicShellSyntaxIn("echo trailing\\") !== undefined);
 check("dynamic shell syntax preserves quoted literals", dynamicShellSyntaxIn("printf '%s' '$(literal) `literal` <(literal) $IFS'") === undefined);
+const substitutionBlock = await guardToolDecision("bash", { command: "echo $(dangerous)" }, { sessionID: "s-dynamic-syntax" });
+check("substitution block names the construct and remedy", substitutionBlock.status === "blocked" && substitutionBlock.code === "dynamic_shell_syntax" && substitutionBlock.message.includes("process substitution") && substitutionBlock.message.includes("guard_why"));
+const quotingBlock = await guardToolDecision("bash", { command: "echo 'unterminated" }, { sessionID: "s-dynamic-syntax" });
+check("malformed quoting block names the construct and remedy", quotingBlock.status === "blocked" && quotingBlock.code === "dynamic_shell_syntax" && quotingBlock.message.includes("balanced quoting"));
 check(
 	"runVerify terminates timed-out verification commands safely",
 	!verifyTimeout.passed && verifyTimeout.output.includes("timed out"),
@@ -3152,6 +3252,27 @@ check("git checkout -b origin/main with a stale branch is allowed", !blocked(awa
 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")));
+// Redirection tokens are never start points (audit regression: `git switch
+// -c feat/x 2>&1` classified the trailing `2>` left by `&`-segment splitting
+// as an explicit start point and failed closed).
+const redirStale = await shell("git switch -c wg-redir-stale 2>/dev/null");
+check(
+	"redirect to /dev/null is not a start point on a stale branch (still stale-blocked)",
+	blocked(redirStale) && (redirStale as string).includes("'feat/conflict-branch'") && !(redirStale as string).includes("'2>'"),
+);
+spawnSync("git", ["switch", "-c", "wg-redir-base", "origin/main"], { cwd: conflictRepo });
+check("attached stderr redirect is not a start point on a fresh branch", !blocked(await shell("git switch -c wg-redir-null 2>/dev/null")));
+check("separated stdout redirect is not a start point on a fresh branch", !blocked(await shell("git checkout -b wg-redir-out > /dev/null")));
+check("fd duplication 2>&1 left by &-segment splitting is not a start point", !blocked(await shell("git switch -c wg-redir-dup 2>&1")));
+check("separated fd stderr redirect is not a start point on a fresh branch", !blocked(await shell("git switch -c wg-redir-sep 2> /dev/null")));
+check("explicit start point before a redirect stays effective", !blocked(await shell("git switch -c wg-redir-after origin/main 2>&1")));
+spawnSync("git", ["switch", "feat/conflict-branch"], { cwd: conflictRepo });
+const staleShaRedirect = await shell(`git switch -c wg-stale-redir ${staleStartSha} >/dev/null`);
+check(
+	"explicit stale start point is still classified behind a redirect",
+	blocked(staleShaRedirect) && (staleShaRedirect as string).includes("start point") && (staleShaRedirect as string).includes(staleStartSha),
+);
+check("variable start point behind a redirect still fails closed", blocked(await shell("git switch -c wg-var-redir $WG_REF 2>/dev/null")));
 
 // Lockfile synchronization tests
 const lockRepo = mkdtempSync(join(tmpdir(), "wg-lock-repo-"));
@@ -3169,6 +3290,219 @@ writeFileSync(join(lockRepo, "package-lock.json"), "{\"name\":\"demo\",\"version
 check("checkLockfileSync passes when lockfile is updated", !checkLockfileSync(lockRepo).isOutOfSync);
 rmSync(lockRepo, { recursive: true, force: true });
 
+// Lockfile synchronization tracks lockfile-relevant manifest sections, not
+// the mere presence of package.json in the branch diff. A scripts-only edit
+// (the documented curation act of adding a suite to a test script) regenerates
+// package-lock.json byte-identical, so demanding a lockfile change for it is
+// unsatisfiable; dependency/engines/packageManager changes still demand one.
+const scriptLockRepo = mkdtempSync(join(tmpdir(), "wg-lock-scripts-"));
+spawnSync("git", ["init", "-b", "main"], { cwd: scriptLockRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: scriptLockRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: scriptLockRepo });
+const scriptManifestBase = { name: "demo", version: "1.0.0", scripts: { test: "node test.mjs" } };
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify(scriptManifestBase, null, 2) + "\n");
+writeFileSync(join(scriptLockRepo, "package-lock.json"), JSON.stringify({ name: "demo", version: "1.0.0", lockfileVersion: 3 }, null, 2) + "\n");
+// A nested manifest already present at the merge base, so its scripts-only
+// edit on the branch is a true edit (not a new manifest).
+mkdirSync(join(scriptLockRepo, "packages", "app"), { recursive: true });
+const nestedManifestBase = { name: "app", version: "0.0.0", scripts: { build: "node build.mjs" } };
+writeFileSync(join(scriptLockRepo, "packages", "app", "package.json"), JSON.stringify(nestedManifestBase, null, 2) + "\n");
+spawnSync("git", ["add", "-A"], { cwd: scriptLockRepo });
+spawnSync("git", ["commit", "-qm", "init"], { cwd: scriptLockRepo });
+spawnSync("git", ["switch", "-c", "feat/scripts-only"], { cwd: scriptLockRepo });
+const scriptManifestEdited = JSON.parse(JSON.stringify(scriptManifestBase)) as typeof scriptManifestBase;
+scriptManifestEdited.scripts.test = "node test.mjs && node test-ci.mjs";
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify(scriptManifestEdited, null, 2) + "\n");
+check("checkLockfileSync passes an uncommitted scripts-only manifest edit", !checkLockfileSync(scriptLockRepo).isOutOfSync);
+spawnSync("git", ["commit", "-qam", "curate test suite"], { cwd: scriptLockRepo });
+check("checkLockfileSync passes a committed scripts-only manifest edit", !checkLockfileSync(scriptLockRepo).isOutOfSync);
+// The observed false positive: a scripts-only edit alongside a lockfile that
+// npm rewrote byte-identical (present in the diff set, yet unchanged in
+// content — the old check demanded exactly this unsatisfiable combination).
+writeFileSync(join(scriptLockRepo, "package-lock.json"), readFileSync(join(scriptLockRepo, "package-lock.json"), "utf8"));
+check("checkLockfileSync passes a byte-identical lockfile rewrite next to a scripts-only edit", !checkLockfileSync(scriptLockRepo).isOutOfSync);
+// A nested manifest's scripts-only edit passes too.
+const nestedManifestEdited = JSON.parse(JSON.stringify(nestedManifestBase)) as typeof nestedManifestBase;
+nestedManifestEdited.scripts.build = "node build.mjs && node verify.mjs";
+writeFileSync(join(scriptLockRepo, "packages", "app", "package.json"), JSON.stringify(nestedManifestEdited, null, 2) + "\n");
+check("checkLockfileSync passes a scripts-only nested manifest edit", !checkLockfileSync(scriptLockRepo).isOutOfSync);
+// Contract pins: sections the lockfile records still demand the lockfile.
+const scriptsAfterNesting = scriptManifestEdited.scripts;
+const relevantManifest = { name: "demo", version: "1.0.0", scripts: scriptsAfterNesting };
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, dependencies: { "left-pad": "^1.3.0" } }, null, 2) + "\n");
+check("checkLockfileSync flags a dependencies change without a lockfile update", checkLockfileSync(scriptLockRepo).isOutOfSync);
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, engines: { node: ">=22" } }, null, 2) + "\n");
+check("checkLockfileSync flags an engines change without a lockfile update", checkLockfileSync(scriptLockRepo).isOutOfSync);
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, packageManager: "pnpm@9.0.0" }, null, 2) + "\n");
+check("checkLockfileSync flags a packageManager change without a lockfile update", checkLockfileSync(scriptLockRepo).isOutOfSync);
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, devDependencies: { typescript: "^5.0.0" } }, null, 2) + "\n");
+check("checkLockfileSync flags a devDependencies change without a lockfile update", checkLockfileSync(scriptLockRepo).isOutOfSync);
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, pnpm: { overrides: { "left-pad": "^1.3.0" } } }, null, 2) + "\n");
+check("checkLockfileSync flags a pnpm-overrides change without a lockfile update", checkLockfileSync(scriptLockRepo).isOutOfSync);
+// And a relevant change WITH the lockfile updated passes.
+writeFileSync(join(scriptLockRepo, "package.json"), JSON.stringify({ ...relevantManifest, dependencies: { "left-pad": "^1.3.0" } }, null, 2) + "\n");
+writeFileSync(join(scriptLockRepo, "package-lock.json"), JSON.stringify({ name: "demo", version: "1.0.0", lockfileVersion: 3, dependencies: { "left-pad": "^1.3.0" } }, null, 2) + "\n");
+check("checkLockfileSync passes when the lockfile is updated alongside a relevant change", !checkLockfileSync(scriptLockRepo).isOutOfSync);
+rmSync(scriptLockRepo, { recursive: true, force: true });
+
+// Concurrent loops share ONE guard process: workspace resolution must come
+// from the call's own context or the session's own binding, never from the
+// last-active plugin instance. Two plugin instances in this process simulate
+// the two loops; instance B's roots must never re-anchor session A's context.
+const isoRepoA = mkdtempSync(join(tmpdir(), "wg-iso-a-"));
+spawnSync("git", ["init", "-b", "main"], { cwd: isoRepoA });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: isoRepoA });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: isoRepoA });
+writeFileSync(join(isoRepoA, "seed.txt"), "loop a\n");
+spawnSync("git", ["add", "-A"], { cwd: isoRepoA });
+spawnSync("git", ["commit", "-qm", "init a"], { cwd: isoRepoA });
+spawnSync("git", ["switch", "-c", "feat/iso-a"], { cwd: isoRepoA });
+const isoRepoB = mkdtempSync(join(tmpdir(), "wg-iso-b-"));
+spawnSync("git", ["init", "-b", "loop/other-loop"], { cwd: isoRepoB });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: isoRepoB });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: isoRepoB });
+writeFileSync(join(isoRepoB, "seed.txt"), "loop b\n");
+spawnSync("git", ["add", "-A"], { cwd: isoRepoB });
+spawnSync("git", ["commit", "-qm", "init b"], { cwd: isoRepoB });
+const isoPluginA = await WorkflowGuard({ directory: isoRepoA, worktree: isoRepoA, client: fakeClient as any, project: {} as any, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const isoPluginB = await WorkflowGuard({ directory: isoRepoB, worktree: isoRepoB, client: fakeClient as any, project: {} as any, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const isoHookOf = (plugin: unknown) => (plugin as { "tool.execute.before"?: (input: unknown, output: unknown) => Promise<unknown> })["tool.execute.before"];
+// Session A binds to repoA from its OWN call context (an edit/read target
+// inside repoA delivered through the call arguments).
+await isoHookOf(isoPluginA)?.({ sessionID: "s-iso-shared", tool: "read", callID: "c-iso-1" }, { args: { filePath: join(isoRepoA, "seed.txt") } });
+check("a session binds to its workspace from its own call context", getSessionBoundWorkspace("s-iso-shared") === isoRepoA);
+// The other loop's plugin instance must not re-anchor it from its own root.
+await isoHookOf(isoPluginB)?.({ sessionID: "s-iso-shared", tool: "bash", callID: "c-iso-2" }, { args: { command: "ls -la" } });
+check("an instance-derived fallback never re-anchors a bound session", getSessionBoundWorkspace("s-iso-shared") === isoRepoA);
+const isoStatus = JSON.parse(String(await isoPluginB.tool?.guard_status?.execute({}, { sessionID: "s-iso-shared" } as any)));
+check("guard_status resolves the session's own workspace under plugin-instance drift", isoStatus.workspaceRoot === isoRepoA && isoStatus.branch === "feat/iso-a");
+const isoStatusExplicit = JSON.parse(String(await isoPluginB.tool?.guard_status?.execute({ directory: isoRepoB }, { sessionID: "s-iso-shared" } as any)));
+check("guard_status honors an explicit directory over the session binding", isoStatusExplicit.workspaceRoot === isoRepoB && isoStatusExplicit.branch === "loop/other-loop");
+check("resolveEffectiveWorkspace keeps a bound session off a foreign fallback", (await resolveEffectiveWorkspace({ sessionID: "s-iso-shared", fallback: isoRepoB })) === isoRepoA);
+check("resolveEffectiveWorkspace keeps fallback semantics for an unbound session", (await resolveEffectiveWorkspace({ sessionID: "s-iso-unbound", fallback: isoRepoB })) === isoRepoB);
+// Policy decisions follow the call's own context: a boundary write inside the
+// session's repo passes even while the other loop's root is the fallback.
+todo("s-iso-shared", item("iso work", "in_progress"));
+const isoWrite = await guardToolDecision("write", { filePath: join(isoRepoA, "scratch.txt"), content: "safe" }, { sessionID: "s-iso-shared" });
+check("boundary checks use the session's own workspace, not the other loop's root", isoWrite.status === "allowed");
+if (isoWrite.status !== "allowed") console.log("   blocked:", isoWrite.message);
+// Review verdict binding is never guessed: no explicit directory, no session
+// binding, no per-call worktree — the verdict is rejected, not latched.
+const unboundReview = await isoPluginA.tool?.record_review?.execute(
+	{ reviewer: "no-binding", summary: "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ sessionID: "s-iso-unbound-recorder" } as any,
+);
+check(
+	"record_review rejects a verdict it cannot bind instead of latching a root",
+	typeof unboundReview === "string" && unboundReview.includes("rejected") && unboundReview.includes("never bound to a guessed root") && !unboundReview.includes("APPROVED"),
+);
+const unboundReviewAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-iso-unbound-recorder");
+check("unbindingable verdict audited as review_binding_unresolved", unboundReviewAudit?.reason === "review_binding_unresolved");
+// A bound session records through the OTHER loop's plugin instance: the
+// verdict binds to the session's own workspace, not the instance root.
+const isoBoundReview = await isoPluginB.tool?.record_review?.execute(
+	{ reviewer: "drift-proof", summary: "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.", passed: true },
+	{ sessionID: "s-iso-shared" } as any,
+);
+check(
+	"record_review binds to the session's own workspace, not the other loop's instance root",
+	typeof isoBoundReview === "string" && isoBoundReview.includes("APPROVED") && isoBoundReview.includes(isoRepoA) && !isoBoundReview.includes(isoRepoB),
+);
+rmSync(isoRepoA, { recursive: true, force: true });
+rmSync(isoRepoB, { recursive: true, force: true });
+resetReviewState();
+setWorkspaceRoot(root);
+
+// Review bindings are consumed per WORKTREE, not per repository-recency: two
+// loops sharing one repo must not displace each other's approvals between
+// record_review and PR creation.
+const raceRepo = join(root, "wg-race-repo");
+mkdirSync(raceRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: raceRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: raceRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: raceRepo });
+writeFileSync(join(raceRepo, "seed.txt"), "base\n");
+spawnSync("git", ["add", "-A"], { cwd: raceRepo });
+spawnSync("git", ["commit", "-qm", "base"], { cwd: raceRepo });
+mkdirSync(join(raceRepo, ".opencode"), { recursive: true });
+writeFileSync(join(raceRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true }));
+spawnSync("git", ["switch", "-c", "feat/race-a"], { cwd: raceRepo });
+writeFileSync(join(raceRepo, "a.txt"), "loop a change\n");
+spawnSync("git", ["add", "-A"], { cwd: raceRepo });
+spawnSync("git", ["commit", "-qm", "loop a change"], { cwd: raceRepo });
+const prevWorktreeDirRace = process.env.WORKFLOW_GUARD_WORKTREE_DIR;
+process.env.WORKFLOW_GUARD_WORKTREE_DIR = join(root, "wg-race-worktrees");
+const raceWtRes = createGitWorktree("feat/race-b", "HEAD", raceRepo);
+check("race: sibling worktree created", raceWtRes.success && typeof raceWtRes.worktreePath === "string");
+const raceWt = raceWtRes.worktreePath!;
+writeFileSync(join(raceWt, "b.txt"), "loop b change\n");
+spawnSync("git", ["add", "-A"], { cwd: raceWt });
+spawnSync("git", ["commit", "-qm", "loop b change"], { cwd: raceWt });
+const raceSummary = "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.";
+// Loop A records first; loop B records a NEWER review for the sibling
+// worktree. Each worktree must keep consuming its OWN approval.
+resetReviewState();
+recordReviewResult("reviewer-A", raceSummary, true, "s-race-a", raceRepo);
+recordReviewResult("reviewer-B", raceSummary, true, "s-race-b", raceWt);
+check("loop A consumes its own worktree review, not the newer sibling review", getLastReviewResultForWorkspace(raceRepo)?.reviewer === "reviewer-A");
+check("loop B consumes its own worktree review", getLastReviewResultForWorkspace(raceWt)?.reviewer === "reviewer-B");
+resetReviewState();
+recordReviewResult("reviewer-B", raceSummary, true, "s-race-b", raceWt);
+recordReviewResult("reviewer-A", raceSummary, true, "s-race-a", raceRepo);
+check("loop A keeps its own review when it was recorded first", getLastReviewResultForWorkspace(raceRepo)?.reviewer === "reviewer-A");
+check("loop B keeps its own review when it was recorded last", getLastReviewResultForWorkspace(raceWt)?.reviewer === "reviewer-B");
+// Preflight consumption with the remote state stubbed off: loop A's PR must
+// pass while the sibling loop's newer review exists, and must FAIL with a
+// worktree-mismatch cause when only the sibling review is present.
+const racePrevPath = process.env.PATH;
+const raceBin = join(root, "wg-race-bin");
+mkdirSync(raceBin, { recursive: true });
+writeFileSync(join(raceBin, "gh"), "#!/bin/sh\nexit 1\n");
+writeFileSync(join(raceBin, "az"), "#!/bin/sh\nexit 1\n");
+chmodSync(join(raceBin, "gh"), 0o755);
+chmodSync(join(raceBin, "az"), 0o755);
+process.env.PATH = `${raceBin}:${racePrevPath ?? ""}`;
+const racePrBody = "gh pr create --title 'fix: race' --body 'Changelog: race'";
+try {
+	const racePrA = await call("bash", { command: racePrBody, workdir: raceRepo }, { sessionID: "s-race-a", worktree: raceRepo, directory: raceRepo });
+	check("loop A's PR passes preflight while the sibling loop's newer review exists", !blocked(racePrA));
+	if (blocked(racePrA)) console.log("   blocked:", racePrA);
+	const racePrB = await call("bash", { command: racePrBody, workdir: raceWt }, { sessionID: "s-race-b", worktree: raceWt, directory: raceWt });
+	check("loop B's PR passes preflight independently", !blocked(racePrB));
+	if (blocked(racePrB)) console.log("   blocked:", racePrB);
+	// Negative control: only the sibling review present -> the mismatch is
+	// named instead of displacing the other loop's evidence.
+	resetReviewState();
+	recordReviewResult("reviewer-B", raceSummary, true, "s-race-b", raceWt);
+	const racePrOnlyB = await call("bash", { command: racePrBody, workdir: raceRepo }, { sessionID: "s-race-a", worktree: raceRepo, directory: raceRepo });
+	check(
+		"loop A's PR is blocked on the sibling review alone, naming the worktree mismatch",
+		blocked(racePrOnlyB) && String(racePrOnlyB).includes("does not match the current worktree contents"),
+	);
+	// Same-repo fallback still rescues content-identical trees: a review
+	// recorded from a worktree whose tracked content equals this one applies,
+	// even when a NEWER sibling review does not match this content.
+	const raceWtSameContentRes = createGitWorktree("feat/race-same", "feat/race-a", raceRepo);
+	const raceWtSame = raceWtSameContentRes.worktreePath!;
+	resetReviewState();
+	recordReviewResult("reviewer-same", raceSummary, true, "s-race-same", raceRepo);
+	recordReviewResult("reviewer-B", raceSummary, true, "s-race-b", raceWt);
+	check(
+		"a same-repo review whose tracked content matches this worktree is preferred over a newer mismatching one",
+		getLastReviewResultForWorkspace(raceWtSame)?.reviewer === "reviewer-same",
+	);
+	rmSync(raceWtSame, { recursive: true, force: true });
+} finally {
+	process.env.PATH = racePrevPath;
+}
+if (prevWorktreeDirRace === undefined) delete process.env.WORKFLOW_GUARD_WORKTREE_DIR;
+else process.env.WORKFLOW_GUARD_WORKTREE_DIR = prevWorktreeDirRace;
+rmSync(join(root, "wg-race-worktrees"), { recursive: true, force: true });
+rmSync(raceBin, { recursive: true, force: true });
+rmSync(raceRepo, { recursive: true, force: true });
+resetReviewState();
+setWorkspaceRoot(root);
+
 // 14. Documentation Review & Synchronization Guard (Policy 21)
 console.log("- Policy 21: Documentation Review & Synchronization Guard -");
 const docRepo = mkdtempSync(join(tmpdir(), "wg-doc-repo-"));