opencode-workflow-guard 1.19.0 → 1.19.1

package/src/lib/state.ts

@@ -81,6 +81,10 @@ export function clearTodoSessionState(sessionID: string): void {
 // instance must never outrank the call's own context or the host fallback.
 const sessionWorkspaceBound = new Set<string>();
 
+// Last directory the HOST named per session, so a repeated `session.updated`
+// costs one string comparison instead of a `git rev-parse` child process.
+const sessionHostDirectories = new Map<string, string>();
+
 export function setSessionWorkspace(sessionID: string, workspace: string): void {
 	if (!sessionID || !workspace) return;
 	const gitRoot = findGitRoot(workspace);
@@ -88,6 +92,18 @@ export function setSessionWorkspace(sessionID: string, workspace: string): void
 	sessionWorkspaceBound.add(sessionID);
 }
 
+/**
+ * Drop a deleted session's workspace binding and host-directory cache entry.
+ *
+ * Both are keyed by session id, so a deleted session can never read them again.
+ * Leaving them would grow both maps for the life of a long-lived server.
+ */
+export function forgetSessionWorkspace(sessionID: string): void {
+	sessionWorkspaces.delete(sessionID);
+	sessionWorkspaceBound.delete(sessionID);
+	sessionHostDirectories.delete(sessionID);
+}
+
 export function getSessionWorkspace(sessionID?: string): string | undefined {
 	if (!sessionID) return undefined;
 	return sessionWorkspaces.get(sessionID);
@@ -236,11 +252,74 @@ function auditWorkspaceRebind(sessionID: string, from: string | undefined, to: s
 		tool: "workspace.binding",
 		decision: "allow",
 		phase: "event",
-		reason: "workspace_rebind_host_worktree",
+		reason: source === "session-move" ? "workspace_rebind_session_move" : "workspace_rebind_host_worktree",
 		input: { from, to, source },
 	});
 }
 
+/**
+ * Rebind a session to the workspace the HOST says it now occupies.
+ *
+ * `session_move` (and the equivalent host move command) relocates a session
+ * between checkouts. Without this the binding stayed on the old checkout, so
+ * every later boundary, branch, and PR decision judged the tree the session had
+ * left: the move looked like it had no effect. A host move is an explicit
+ * boundary statement from the host, in the same class as a per-call worktree,
+ * so it may widen an already-bound session. It is journaled for that reason.
+ *
+ * The hard part is telling a move from a routine update. `session.updated` is a
+ * hot event, emitted for title and cost changes, and it names the session's
+ * creation directory. A session bound to a LINKED WORKTREE by its own tool-call
+ * `workdir` legitimately differs from that directory, so treating every update
+ * as a move pulled the session back to the checkout it had deliberately left.
+ * Three signals therefore count, and nothing else does:
+ *
+ * - The host announced the relocation itself (`moved: true`, from
+ *   `session.moved`).
+ * - The directory the host names now differs from the one it named last for
+ *   this session.
+ * - The named repository is a DIFFERENT repository from the bound workspace. A
+ *   linked worktree is the same repository, so this catches the cross-repository
+ *   move that a first observation would otherwise miss on OpenCode 1.x, which
+ *   has no move event.
+ *
+ * The last directory is remembered so a repeated update costs one string
+ * comparison instead of a `git rev-parse` child process. The cache stores a
+ * directory that actually resolved to a repository root: an unresolved
+ * directory is not cached, so a later event for the same path retries instead
+ * of being suppressed forever.
+ */
+export function rebindSessionWorkspaceFromHost(
+	sessionID: string | undefined,
+	directory: string | undefined,
+	options: { moved?: boolean } = {},
+): void {
+	if (!sessionID || !directory) return;
+	const gitRoot = findGitRoot(directory);
+	if (!gitRoot) return;
+	const previousHostDirectory = sessionHostDirectories.get(sessionID);
+	sessionHostDirectories.set(sessionID, directory);
+	const previous = sessionWorkspaces.get(sessionID);
+	const moved =
+		options.moved === true
+		|| (previousHostDirectory !== undefined && previousHostDirectory !== directory)
+		|| (previous !== undefined && gitRoot !== previous && !isSameGitRepo(gitRoot, previous));
+	if (!moved) {
+		if (sessionWorkspaceBound.has(sessionID)) return;
+		// A bootstrap entry that was never bound still needs binding: the host
+		// just named the session's real directory.
+		sessionWorkspaces.set(sessionID, gitRoot);
+		sessionWorkspaceBound.add(sessionID);
+		return;
+	}
+	if (previous === gitRoot) {
+		sessionWorkspaceBound.add(sessionID);
+		return;
+	}
+	setSessionWorkspace(sessionID, gitRoot);
+	auditWorkspaceRebind(sessionID, previous, gitRoot, "session-move");
+}
+
 /**
  * Durable record of a refused widening. The refusal itself is the boundary
  * policy's decision; this entry exists so an operator can tell whether a

package/src/lib/types.ts

@@ -247,6 +247,13 @@ export interface AuditEntry {
 export interface GitInvocation {
 	repoDir: string;
 	rest: string;
+	/**
+	 * True when the command text itself names the repository (`-C`,
+	 * `--git-dir`, `--work-tree`, `GIT_DIR=`). False means `repoDir` is only
+	 * the invocation's assumed base directory, which is the shell's working
+	 * directory and not a fact the command string carries.
+	 */
+	explicitRepoDir?: boolean;
 }
 
 export interface ShellMutation {

package/src/lib/v2-plugin.ts

@@ -28,6 +28,8 @@ import {
 	setWorkspaceRoot,
 	setSdkClient,
 	getSessionBoundWorkspace,
+	rebindSessionWorkspaceFromHost,
+	forgetSessionWorkspace,
 	registerSessionWorkspaceFromToolCall,
 	runWithRuntimeState,
 	getSessionMutationCount,
@@ -841,6 +843,23 @@ async function handleV2Event(
 		return;
 	}
 
+	if (event.type === "session.moved") {
+		// `session_move` relocates a session between checkouts, and the host
+		// announces it. On the pinned 2.2.0 SDK the V2 union carries
+		// `session.moved` and no `session.updated`, and the move event itself
+		// names the destination: `data.sessionID` plus
+		// `data.location.directory`. Without this rebind the session kept
+		// judging the tree it left.
+		const data = event.data as {
+			sessionID?: unknown;
+			location?: { directory?: unknown };
+		} | undefined;
+		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
+		const directory = typeof data?.location?.directory === "string" ? data.location.directory : undefined;
+		rebindSessionWorkspaceFromHost(sessionID, directory, { moved: true });
+		return;
+	}
+
 	if (event.type === "session.idle") {
 		const data = event.data as { sessionID?: unknown } | undefined;
 		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
@@ -870,6 +889,7 @@ async function handleV2Event(
 			clearTodoSessionState(sessionID);
 			toolLifecycle.takeRecoveryRun(sessionID);
 			await runWithRuntimeState(effectiveRoot, client, () => clearContinuationState(sessionID));
+			forgetSessionWorkspace(sessionID);
 		}
 		return;
 	}

package/src/policies/boundary.ts

@@ -2,14 +2,16 @@ import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { ShellMutation } from "../lib/types.ts";
+import type { ShellSegmentPlan } from "../lib/shell.ts";
 import {
 	getWorkspaceRoot,
 	recordMutation,
 } from "../lib/state.ts";
-import { prepareRedirectResidue, shellWords, unwrapShellCommand } from "../lib/shell.ts";
+import { isLeadingEvalSegment, maskDataHeredocBodies, prepareRedirectResidue, planShellSegments, shellWords, unwrapShellCommand } from "../lib/shell.ts";
 import { isCollaborationInvocation, isProtectedPath, PROTECTED_PATH_REASON } from "./tamper.ts";
 import { isSecretPath, secretIn } from "./secrets.ts";
-import { onProtectedBranch, branchGuardReason } from "./git.ts";
+import { isGitTreeWriteText, branchGuardReason, onProtectedBranch, parseGitInvocation } from "./git.ts";
+import { isSameGitRepo } from "../lib/project-config.ts";
 import {
 	effectiveTodos,
 	effectiveTodoOwnerSessionID,
@@ -372,8 +374,265 @@ function stripQuotedSpans(segment: string): string {
 	return segment.replace(/'[^'\n]*'/g, " ").replace(/"[^"\n]*"/g, " ");
 }
 
+/**
+ * A segment that changes a tree this session may not judge: a mutation or git
+ * write whose directory could not be resolved (`cd $DIR && git commit`) or
+ * whose directory is a foreign repository (`cd /other-repo && rm -rf dist`).
+ *
+ * Relative targets in such a segment would be validated against the session's
+ * own checkout while the command changes another tree. That is the defect a
+ * shell-level `cd` used to hide, so it is refused rather than judged.
+ */
+export function foreignSegmentMutationReason(
+	segments: ShellSegmentPlan[],
+	workspaceRoot: string,
+): string | undefined {
+	for (const { segment, root } of segments) {
+		const mutation = detectShellMutation(segment);
+		const gitWrite = isGitTreeWrite(segment, root ?? workspaceRoot);
+		if (!mutation && !gitWrite) continue;
+		if (root === undefined) {
+			return `Blocked: the command changes directory to a target that cannot be determined without executing shell expansion, then runs a mutation (${mutation?.what ?? "git write"}). Indeterminate destinations are treated as outside the workspace root (${workspaceRoot}). Use a literal directory inside the workspace.`;
+		}
+		if (!isPathOutsideWorkspace(root, workspaceRoot) || isSameGitRepo(root, workspaceRoot)) continue;
+		return `Blocked: the command changes into '${root}' and mutates it (${mutation?.what ?? "git write"}), but that directory is outside workspace root (${workspaceRoot}) and is not a linked worktree of this repository. Relative targets there cannot be validated against the tree the command would actually change. Run the command from inside the workspace instead.`;
+	}
+	return undefined;
+}
+
+function isGitTreeWrite(segment: string, baseDir: string): boolean {
+	const invocation = parseGitInvocation(segment.trim(), baseDir);
+	if (!invocation) return false;
+	return isGitTreeWriteText(`git ${invocation.rest}`);
+}
+
+/**
+ * The working directory an inline interpreter payload names for the commands it
+ * runs.
+ *
+ * `execSync('git commit', {cwd: '<dir>'})` carries the tree directly instead of
+ * changing directory first, so the payload walk alone cannot see it. The match
+ * is anchored to a spawn-family call or `process.chdir`, because a bare `cwd:`
+ * key in an unrelated object literal does not choose a working directory.
+ *
+ * A named directory that is not a literal (`{cwd: process.env.OTHER}`) is
+ * reported as indeterminate rather than ignored, matching the shell rule that
+ * an unresolvable destination fails closed for a mutation.
+ */
+export type PayloadWorkingRoot =
+	| { status: "none" }
+	| { status: "resolved"; root: string }
+	| { status: "indeterminate"; raw: string };
+
+// Only a call site that actually spawns a process names a working directory.
+// `execSync`, `spawn`, and friends are unambiguous. A bare `exec` is guarded by
+// its preceding token so `regex.exec(str, {cwd: …})` is not a spawn, while
+// `child_process.exec(...)` still is. A bare `cwd:` key in an unrelated object
+// literal names no working directory at all.
+const SPAWN_CALLEE = String.raw`(?:(?:child_process|cp)\.)?(?:execSync|execFileSync|spawnSync|execFile|spawn|fork)|(?:child_process|cp)\.exec|(?<![.\w$])exec`;
+const PROCESS_CHDIR = /\bprocess\s*\.\s*chdir\s*\(\s*([^)]+?)\s*\)/;
+
+/**
+ * The argument text of every spawn-family call, found with a balanced scan.
+ *
+ * A flat `[^)]*` stopped at the first closing paren, so
+ * `execSync(require('path').join('a','b'), {cwd: '/other'})` matched nothing and
+ * its foreign `cwd` went unchecked.
+ */
+function spawnCallArguments(payload: string): string[] {
+	const spans: string[] = [];
+	const callee = new RegExp(String.raw`(?:${SPAWN_CALLEE})\s*\(`, "g");
+	for (let match = callee.exec(payload); match; match = callee.exec(payload)) {
+		let depth = 0;
+		let quote: string | undefined;
+		const start = match.index + match[0].length - 1;
+		for (let i = start; i < payload.length; i += 1) {
+			const char = payload[i]!;
+			if (quote) {
+				if (char === quote && payload[i - 1] !== "\\") quote = undefined;
+				continue;
+			}
+			if (char === "'" || char === '"' || char === "`") {
+				quote = char;
+				continue;
+			}
+			if (char === "(") depth += 1;
+			else if (char === ")") {
+				depth -= 1;
+				if (depth === 0) {
+					spans.push(payload.slice(start + 1, i));
+					break;
+				}
+			}
+		}
+		callee.lastIndex = Math.max(callee.lastIndex, start + 1);
+	}
+	return spans;
+}
+
+/**
+ * The `cwd` of the call's own options object, ignoring a nested one.
+ *
+ * The argument text is split at top-level commas, and only an argument that is
+ * itself an object literal contributes. Without that, `execSync(fn({cwd: '<a>'}),
+ * {cwd: '<b>'})` read the nested object's key first and reported a workspace
+ * directory for a call that actually ran in `<b>`.
+ */
+function callOwnCwd(args: string): string | undefined {
+	let depth = 0;
+	let quote: string | undefined;
+	const topLevel: string[] = [];
+	let current = "";
+	for (let i = 0; i < args.length; i += 1) {
+		const char = args[i]!;
+		if (quote) {
+			if (char === quote && args[i - 1] !== "\\") quote = undefined;
+			current += char;
+			continue;
+		}
+		if (char === "'" || char === '"' || char === "`") {
+			quote = char;
+			current += char;
+			continue;
+		}
+		if (char === "{" || char === "[" || char === "(") depth += 1;
+		else if (char === "}" || char === "]" || char === ")") depth -= 1;
+		if (char === "," && depth === 0) {
+			topLevel.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	topLevel.push(current);
+	for (const argument of topLevel) {
+		const trimmed = argument.trim();
+		if (!trimmed.startsWith("{")) continue;
+		const match = /\bcwd\s*:\s*([^,}]+)/.exec(trimmed);
+		if (match?.[1]) return match[1].trim();
+	}
+	return undefined;
+}
+
+export function payloadWorkingRoot(payload: string): PayloadWorkingRoot {
+	const cwdValues = spawnCallArguments(payload)
+		.map(callOwnCwd)
+		.filter((value): value is string => value !== undefined);
+	const chdir = PROCESS_CHDIR.exec(payload)?.[1]?.trim();
+	if (chdir) cwdValues.push(chdir);
+	// Every call's directory has to agree. Two different trees, or one that is
+	// not a literal, means the payload's real directory is not determinable, and
+	// a mutation then fails closed rather than trusting the first one found.
+	const roots = new Set<string>();
+	for (const raw of cwdValues) {
+		const literal = /^(["'`])([^"'`]*)\1$/.exec(raw);
+		if (!literal?.[2]) return { status: "indeterminate", raw };
+		roots.add(literal[2]);
+	}
+	if (roots.size === 0) return { status: "none" };
+	if (roots.size > 1) return { status: "indeterminate", raw: [...roots].join(", ") };
+	return { status: "resolved", root: [...roots][0]! };
+}
+
+function payloadMutates(payload: string): boolean {
+	if (detectShellMutation(payload)) return true;
+	return isGitTreeWriteText(payload);
+}
+
+/**
+ * A segment-level git invocation whose repository is outside the workspace.
+ *
+ * The dispatcher applies this check to top-level commands. A payload was never
+ * routed through it, so `bash -c 'git -C <other> commit'` reached a foreign
+ * repository: the `-C` form carries no `cd`, and `isGitTreeWriteText` reads the
+ * `git <verb>` text without resolving the flag.
+ */
+function foreignGitRepositoryIn(segment: string, baseDir: string, workspaceRoot: string): string | undefined {
+	for (const raw of segment.split(/[\n|;&]+/)) {
+		const invocation = parseGitInvocation(raw.trim(), baseDir);
+		if (!invocation) continue;
+		if (!isGitTreeWriteText(`git ${invocation.rest}`)) continue;
+		const repoDir = invocation.repoDir;
+		const foreign = hasUnresolvableVariable(repoDir)
+			|| (isPathOutsideWorkspace(repoDir, workspaceRoot) && !isSameGitRepo(repoDir, workspaceRoot));
+		if (foreign) return repoDir;
+	}
+	return undefined;
+}
+
+/**
+ * The tree a nested interpreter payload changes, when that tree is one this
+ * session may not judge.
+ *
+ * A payload never reaches the top-level segment walk: `bash -c 'cd <other> &&
+ * git commit'` is one shell word to the outer shell, so its nested `cd` and
+ * mutation were invisible. `extractPayloads` and `writesIn` are injected so
+ * this policy does not import the interpreter scanner back.
+ */
+export function nestedPayloadMutationReason(
+	extractPayloads: (segment: string) => string[],
+	writesIn: (payload: string) => string[],
+	command: string,
+	baseDir: string,
+	workspaceRoot: string,
+	depth = 0,
+): string | undefined {
+	// Nesting deeper than this is not modelled. A launcher chain that deep is
+	// refused rather than skipped, so the cap cannot become a way through.
+	if (depth > 8) {
+		return `Blocked: inline interpreter scripts are nested deeper than the ${8} levels this check models, so the tree they mutate cannot be determined. Run the command from a single script file inside the workspace instead.`;
+	}
+	for (const { segment, root } of planShellSegments(command, baseDir, (s) => {
+		// `eval` runs in the current shell, so its body's `cd` moves later
+		// segments. Only an `eval` body counts here; another launcher's payload
+		// runs in a child process and cannot move this shell.
+		return isLeadingEvalSegment(s) ? extractPayloads(s)[0] : undefined;
+	})) {
+		const payloads = extractPayloads(segment);
+		if (payloads.length === 0) continue;
+		// A launcher whose directory is indeterminate must not be assumed to be
+		// the workspace root: `cd $DIR && node -e "writeFileSync('x')"` would then
+		// read as a workspace write. The payload's own relative targets cannot be
+		// validated against a tree this walk could not resolve, so a mutation
+		// fails closed, matching the shell rule for the same shape.
+		const launcherRoot = root;
+		if (launcherRoot === undefined) {
+			const mutates = payloads.some((payload) => writesIn(payload).length > 0 || payloadMutates(payload));
+			if (mutates) {
+				return `Blocked: the command changes directory to a target that cannot be determined without executing shell expansion, then runs an inline interpreter script that mutates. Indeterminate destinations are treated as outside the workspace root (${workspaceRoot}). Use a literal directory inside the workspace.`;
+			}
+			continue;
+		}
+		for (const payload of payloads) {
+			const foreignRepo = foreignGitRepositoryIn(payload, launcherRoot, workspaceRoot);
+			if (foreignRepo) {
+				return `Blocked: the inline interpreter script runs a git write against '${foreignRepo}', outside workspace root (${workspaceRoot}) and not a linked worktree of this repository. Run the command from inside the workspace instead.`;
+			}
+			const nested = foreignSegmentMutationReason(planShellSegments(payload, launcherRoot), workspaceRoot);
+			if (nested) return nested;
+			// A payload can launch another interpreter: `bash -c "bash -c 'cd
+			// <other> && git commit'"` only extracts its own quoted body. Re-plan
+			// each payload until the nesting bottoms out.
+			const inner = nestedPayloadMutationReason(extractPayloads, writesIn, payload, launcherRoot, workspaceRoot, depth + 1);
+			if (inner) return inner;
+			const declared = payloadWorkingRoot(payload);
+			if (declared.status === "none") continue;
+			if (writesIn(payload).length === 0 && !payloadMutates(payload)) continue;
+			if (declared.status === "indeterminate") {
+				return `Blocked: the inline interpreter script runs a mutating command in a working directory that cannot be determined without executing the script (${declared.raw}). Indeterminate destinations are treated as outside the workspace root (${workspaceRoot}). Use a literal directory inside the workspace.`;
+			}
+			const targetRoot = resolve(launcherRoot, declared.root);
+			if (!isPathOutsideWorkspace(targetRoot, workspaceRoot) || isSameGitRepo(targetRoot, workspaceRoot)) continue;
+			return `Blocked: the inline interpreter script runs a mutating command in '${targetRoot}', outside workspace root (${workspaceRoot}) and not a linked worktree of this repository. Relative targets there cannot be validated against the tree the command would actually change. Run the command from inside the workspace instead.`;
+		}
+	}
+	return undefined;
+}
+
 export function detectShellMutation(command: string): ShellMutation | undefined {
-	for (const rawSegment of command.split(/[\n|;&]+/)) {
+	// A heredoc body no command executes is prose. Splitting it on its newlines
+	// read a documented command shape as a real one.
+	for (const rawSegment of maskDataHeredocBodies(command).split(/[\n|;&]+/)) {
 		const segment = isCollaborationInvocation(rawSegment) ? stripQuotedSpans(rawSegment) : rawSegment;
 		const simpleMutations = simpleFilesystemMutations(segment);
 		if (simpleMutations.length > 0) return simpleMutations[0];
@@ -395,15 +654,39 @@ export async function guardShellMutation(
 	command: string,
 	sessionID: string | undefined,
 	record = true,
+	shellRoot?: string,
+	evalBody?: (segment: string) => string | undefined,
 ): Promise<string | undefined> {
-	const root = getWorkspaceRoot();
+	// Judge the tree the command RUNS in. A linked worktree of this repository
+	// is a legitimate workdir, and its branch or relative targets are not the
+	// session checkout's: validating against that checkout blocked a mutation
+	// in a feature worktree as if it happened on the primary `main`.
+	const workspaceRoot = getWorkspaceRoot();
+	const root = shellRoot ?? workspaceRoot;
+	const plan = planShellSegments(command, root, evalBody);
+	// The foreign-tree gate runs here too, so this function is safe when called
+	// on its own: an indeterminate or foreign `cd` is refused instead of silently
+	// falling back to judging relative targets against the wrong tree.
+	const foreignReason = foreignSegmentMutationReason(plan, workspaceRoot);
+	if (foreignReason) return foreignReason;
 	let hasMutation = false;
-	for (const rawSegment of command.split(/[\n|;&]+/)) {
+	for (const { segment, root: segmentRoot } of plan) {
+		// `cd` earlier in the command moves this segment, so its relative targets
+		// resolve against the tree it actually changes. An indeterminate `cd` was
+		// already refused above.
+		const runRoot = segmentRoot ?? root;
+		// Both trees are this workspace: the checkout the command runs in and the
+		// session's own checkout. Absolute paths into either are legitimate, so a
+		// target is outside only when it leaves both.
+		const outsideWorkspace = (target: string): boolean =>
+			isPathOutsideWorkspace(target, runRoot) && isPathOutsideWorkspace(target, workspaceRoot);
 		// Same residue analysis as detectShellMutation: quoted arguments of
 		// gh/glab/az PR/issue commands are command data, not shell redirects,
-		// while unquoted redirects still get full validation below.
-		const segment = isCollaborationInvocation(rawSegment) ? stripQuotedSpans(rawSegment) : rawSegment;
-		const secretSource = secretSourceInFilesystemCommand(segment);
+		// while unquoted redirects still get full validation below. A heredoc body
+		// that no command executes is prose, so its lines are not judged either.
+		const masked = maskDataHeredocBodies(segment);
+		const cleanSegment = isCollaborationInvocation(masked) ? stripQuotedSpans(masked) : masked;
+		const secretSource = secretSourceInFilesystemCommand(cleanSegment);
 		if (secretSource) {
 			return `Blocked: shell command would copy, move, or link sensitive file '${secretSource}' under a non-secret name.`;
 		}
@@ -411,36 +694,36 @@ export async function guardShellMutation(
 		// sources must respect the same boundaries as mutation targets: no
 		// moving files in from outside the workspace, no moving protected
 		// (settings/plugin) files to innocuous names.
-		const transfer = filesystemTransferInfo(segment);
-		if (transfer && shellWords(unwrapShellCommand(segment))[0] === "mv") {
+		const transfer = filesystemTransferInfo(cleanSegment);
+		if (transfer && shellWords(unwrapShellCommand(cleanSegment))[0] === "mv") {
 			for (const source of transfer.sources) {
 				if (isProtectedPath(source)) {
 					return PROTECTED_PATH_REASON;
 				}
-				if (isPathOutsideWorkspace(source, root)) {
+				if (outsideWorkspace(source)) {
 					if (hasUnresolvableVariable(source)) {
-						return `Blocked: mv source '${source}' contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${root}). Use a literal workspace-relative path.`;
+						return `Blocked: mv source '${source}' contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${workspaceRoot}). Use a literal workspace-relative path.`;
 					}
-					return `Blocked: mv would remove source '${source}' from outside the workspace root (${root}). File mutations must stay within the workspace.`;
+					return `Blocked: mv would remove source '${source}' from outside the workspace root (${workspaceRoot}). File mutations must stay within the workspace.`;
 				}
 			}
 		}
-		const simpleMutations = simpleFilesystemMutations(segment);
-		const teeTargets = teeTargetsIn(segment);
+		const simpleMutations = simpleFilesystemMutations(cleanSegment);
+		const teeTargets = teeTargetsIn(cleanSegment);
 		const teeMutations: ShellMutation[] = teeTargets.map((target) => ({
 			kind: "command" as const,
 			target,
 			what: `tee to '${target}'`,
 		}));
-		const redirectMutations = redirectMutationsIn(segment.trim());
+		const redirectMutations = redirectMutationsIn(cleanSegment.trim());
 		const mutations = [...simpleMutations, ...teeMutations, ...redirectMutations];
 		if (mutations.length === 0) {
-			const fallbackMutation = shellMutationIn(segment.trim());
+			const fallbackMutation = shellMutationIn(cleanSegment.trim());
 			if (fallbackMutation) mutations.push(fallbackMutation);
 		}
 		for (const mutation of mutations) {
 			hasMutation = true;
-			const secret = secretIn(segment);
+			const secret = secretIn(cleanSegment);
 			if (secret) {
 				return `Blocked: shell file mutation payload appears to contain a ${secret}. Secrets must not be written to disk from agent commands.`;
 			}
@@ -448,19 +731,19 @@ export async function guardShellMutation(
 			if (target && isProtectedPath(target)) {
 				return PROTECTED_PATH_REASON;
 			}
-			if (target && isPathOutsideWorkspace(target, root)) {
+			if (target && outsideWorkspace(target)) {
 				// The workspace boundary has no override: a write outside the
 				// workspace is out of bounds even with WORKFLOW_GUARD_ALLOW_LIVE
 				// (that override covers live-system commands, not the boundary).
 				if (hasUnresolvableVariable(target)) {
-					return `Blocked: shell mutation '${mutation.what}' targets '${target}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${root}). Use a literal workspace-relative path.`;
+					return `Blocked: shell mutation '${mutation.what}' targets '${target}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${workspaceRoot}). Use a literal workspace-relative path.`;
 				}
-				if (isEnvironmentScratchTarget(target, root)) {
-					return `Blocked: shell mutation '${mutation.what}' targets '${target}' under ${OPENCODE_SCRATCH_DIR}, the environment scratch directory the workspace boundary does not cover; write scratch as an untracked file inside the workspace root (${root}) instead (for example .tmp-notes.md).`;
+				if (isEnvironmentScratchTarget(target, runRoot)) {
+					return `Blocked: shell mutation '${mutation.what}' targets '${target}' under ${OPENCODE_SCRATCH_DIR}, the environment scratch directory the workspace boundary does not cover; write scratch as an untracked file inside the workspace root (${workspaceRoot}) instead (for example .tmp-notes.md).`;
 				}
-				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${root}). All changes must stay within the workspace.`;
+				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${workspaceRoot}). All changes must stay within the workspace.`;
 			}
-			if (onProtectedBranch(root)) {
+			if (onProtectedBranch(runRoot)) {
 				return branchGuardReason();
 			}
 			const todos = await effectiveTodos(sessionID);