opencode-workflow-guard 1.19.0 → 1.19.2

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);

package/src/policies/continuation.ts

@@ -19,6 +19,19 @@ type ContinuationState = {
 export type RalphOutcome = "running" | "completed" | "blocked" | "budget_exhausted" | "user_stopped";
 const states = new WeakMap<object, Map<string, ContinuationState>>();
 
+/**
+ * Whether the active client is the V2 shim, which can carry `delivery` and
+ * `resume` on a synthetic continuation. `session.synthetic` is the
+ * discriminator: the V2 shim supplies it, and the V1 SDK client does not
+ * declare it. `session.todo` is required alongside it only because this module
+ * reads todos through the same surface, so a client missing it cannot be the
+ * V2 shim for our purposes.
+ */
+function isV2Host(): boolean {
+	const session = getSdkClient()?.session as { synthetic?: unknown; todo?: unknown } | undefined;
+	return typeof session?.synthetic === "function" && typeof session?.todo === "function";
+}
+
 export async function waitForSessionTitle(sessionID: string): Promise<void> {
 	const session = getSdkClient()?.session;
 	if (typeof session?.get !== "function") return;
@@ -95,17 +108,34 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 			: "";
 
 		try {
-			await session.promptAsync({
-				path: { id: sessionID },
-				body: {
-					messageID,
-					parts: [{
-						type: "text",
-						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
-						synthetic: true,
-					}],
-				},
-			});
+			// Delivery and resume are stated explicitly so a V2 synthetic
+			// continuation does not depend on host defaults. `queue` keeps it in
+			// the session's inbox instead of steering an in-flight turn, and
+			// `resume: true` starts a run when the session is idle.
+			//
+			// The fields are V2-only. The V1 SDK body type declares neither
+			// (`SessionPromptAsyncData` in @opencode-ai/sdk), so adding them
+			// there would send unmodelled fields to a strict server. The V2
+			// client shim reads them off this same object, so the values travel
+			// without changing the V1 request shape.
+			const promptBody: {
+				messageID: string;
+				parts: Array<{ type: "text"; text: string; synthetic?: boolean }>;
+				delivery?: "steer" | "queue";
+				resume?: boolean;
+			} = {
+				messageID,
+				parts: [{
+					type: "text" as const,
+					text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
+					synthetic: true,
+				}],
+			};
+			if (isV2Host()) {
+				promptBody.delivery = "queue";
+				promptBody.resume = true;
+			}
+			await session.promptAsync({ path: { id: sessionID }, body: promptBody });
 			return true;
 		} catch {
 			state.counts.set(sessionID, count);