opencode-workflow-guard 1.18.1 → 1.19.1

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/git.ts

@@ -9,6 +9,8 @@ import {
 import {
 	unwrapShellWords,
 	splitShellSegments,
+	shellPrefixAssignments,
+	resolveGitRepoSelector,
 } from "../lib/shell.ts";
 
 export const PROTECTED_BRANCHES = new Set(["main", "master"]);
@@ -45,6 +47,10 @@ const GIT_DIR_OPTION_TAKES_VALUE = new Set([
 ]);
 const GIT_DIR_OPTION_PREFIXED =
 	/^(--git-dir=|--work-tree=|--namespace=|-c\S|--config-env=)/;
+// Git also accepts the attached short forms (`-C/path`, `-C~`). An unparsed
+// `-C` leaves the repository at the assumed base, which judges the write in the
+// wrong checkout, so the attached form is read as a claim like the spaced one.
+const GIT_DIR_SHORT_ATTACHED = /^-C(.+)$/;
 const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
 	"--version",
 	"--help",
@@ -60,44 +66,88 @@ const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
 	"--exec-path",
 ]);
 
-const GIT_ENV_DIR_RE =
-	/(?:^|\s)(?:env\s+(?:-\S+\s+)*)?(?:GIT_DIR|GIT_WORK_TREE|GIT_COMMON_DIR)=(?:"([^"]*)"|'([^']*)'|(\S+))/;
+// Repository selection from the environment. It is read from the assignments
+// that precede the command word, never from the rest of the command text. A
+// bare `GIT_DIR=` used to be matched anywhere in the string, so an unquoted
+// commit message such as `git commit -m GIT_DIR=/repo` claimed an explicit
+// repository. That was harmless while the value only picked a base directory,
+// but `explicitRepoDir` is now a fact the permission seat trusts, so the claim
+// must be real. A `-c` config override is deliberately not a repository
+// selector: `GIT_DIR` is an environment variable, not a git config key.
+const GIT_REPO_ENV_ASSIGNMENT = /^(?:GIT_DIR|GIT_WORK_TREE|GIT_COMMON_DIR)=(.*)$/s;
 
-export function parseGitInvocation(command: string): GitInvocation | undefined {
-	const root = getWorkspaceRoot();
+/**
+ * The repository an environment assignment selects, or undefined.
+ *
+ * Only assignments that the shell unwrapper actually consumed before the
+ * command word count. A value that merely appears inside an argument cannot be
+ * mistaken for one.
+ */
+function repoEnvironmentOverride(command: string): string | undefined {
+	for (const assignment of shellPrefixAssignments(command)) {
+		const match = GIT_REPO_ENV_ASSIGNMENT.exec(assignment);
+		if (match?.[1]) return match[1];
+	}
+	return undefined;
+}
+
+/**
+ * Parse one git invocation.
+ *
+ * `baseDir` is the directory the command actually runs in: a shell call's
+ * `workdir`, resolved against the call's workspace by the caller. It defaults
+ * to the ambient workspace root for callers that only classify command text.
+ * Without it, `git push` inside a linked worktree was resolved against the
+ * session-bound checkout, so every branch-state check judged the wrong tree.
+ *
+ * `explicitRepoDir` records whether the command text named the repository
+ * itself. A caller that cannot see `workdir` uses that flag to tell a fact
+ * from an assumption.
+ */
+export function parseGitInvocation(command: string, baseDir?: string): GitInvocation | undefined {
+	const root = baseDir ?? getWorkspaceRoot();
 	const tokens = unwrapShellWords(command);
 	if (tokens[0] !== "git") return undefined;
 	let i = 1;
 	let repoDir = root;
 	let sawDirOption = false;
 
-	const envDirMatch = command.match(GIT_ENV_DIR_RE);
-	if (envDirMatch) {
-		const envVal = envDirMatch[1] ?? envDirMatch[2] ?? envDirMatch[3];
-		if (envVal) {
-			repoDir = resolve(root, envVal);
-			sawDirOption = true;
-		}
+	const envDirValue = repoEnvironmentOverride(command);
+	if (envDirValue) {
+		repoDir = resolveGitRepoSelector(root, envDirValue);
+		sawDirOption = true;
 	}
 
 	while (i < tokens.length) {
 		const tok = tokens[i]!;
 		if (GIT_DIR_OPTION_TAKES_VALUE.has(tok)) {
 			const value = tokens[i + 1];
-			if (value === undefined) return { repoDir, rest: "" };
-			if (tok === "-C" || tok === "--git-dir" || tok === "--work-tree") {
-				repoDir = resolve(root, value);
+			const namesRepository = tok === "-C" || tok === "--git-dir" || tok === "--work-tree";
+			// A trailing `-C` with no value names no repository, but the flag is
+			// still present in the text. Report it as a claim so both seats agree
+			// the command is unclassifiable rather than one judging it and the
+			// other deferring it. `-c` and `--config-env` name no repository.
+			if (value === undefined) return { repoDir, rest: "", explicitRepoDir: sawDirOption || namesRepository };
+			if (namesRepository) {
+				repoDir = resolveGitRepoSelector(root, value);
 				sawDirOption = true;
 			}
 			i += 2;
 			continue;
 		}
+		const attached = GIT_DIR_SHORT_ATTACHED.exec(tok);
+		if (attached) {
+			repoDir = resolveGitRepoSelector(root, attached[1]!);
+			sawDirOption = true;
+			i += 1;
+			continue;
+		}
 		if (GIT_DIR_OPTION_PREFIXED.test(tok)) {
 			if (tok.startsWith("--git-dir=")) {
-				repoDir = resolve(root, tok.slice("--git-dir=".length));
+				repoDir = resolveGitRepoSelector(root, tok.slice("--git-dir=".length));
 				sawDirOption = true;
 			} else if (tok.startsWith("--work-tree=")) {
-				repoDir = resolve(root, tok.slice("--work-tree=".length));
+				repoDir = resolveGitRepoSelector(root, tok.slice("--work-tree=".length));
 				sawDirOption = true;
 			}
 			i += 1;
@@ -109,8 +159,7 @@ export function parseGitInvocation(command: string): GitInvocation | undefined {
 		}
 		break;
 	}
-	if (!sawDirOption) repoDir = root;
-	return { repoDir, rest: tokens.slice(i).join(" ") };
+	return { repoDir, rest: tokens.slice(i).join(" "), explicitRepoDir: sawDirOption };
 }
 
 export function normalizeGitCommands(command: string): string {
@@ -125,6 +174,17 @@ export function normalizeGitCommands(command: string): string {
 export const GIT_WRITE_RE =
 	/\bgit\s+(add|rm|mv|commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+tag\s+(?!--?list\b|-l\b)(?:[^|;&]*\s)?(?:-d\b|--delete\b)|\bgit\s+checkout\s+(?!-b\b)|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
 
+/**
+ * True when `text` invokes git in a way that changes a tree's refs or content.
+ *
+ * One predicate for every caller: the shell segment walk, the nested payload
+ * check, and the foreign-workdir gate. Keeping copies is how the payload check
+ * drifted wider than the segment check once already.
+ */
+export function isGitTreeWriteText(text: string): boolean {
+	return GIT_WRITE_RE.test(text) || GIT_BRANCH_CREATE_RE.test(text) || /\bgit\s+push\b/.test(text);
+}
+
 export function currentGitBranch(root: string): string | undefined {
 	const result = spawnSync("git", ["branch", "--show-current"], {
 		cwd: root,
@@ -304,14 +364,76 @@ export function isBranchAlreadyMergedOrClosed(
 	return { merged: false };
 }
 
-export function checkMergeConflicts(root: string): {
+/**
+ * The source branch a PR-creation command names, if any.
+ *
+ * `gh` names it with `--head`/`-H`, and Azure DevOps with `--source-branch`.
+ * Fork forms carry an `owner:` prefix; a ref cannot contain `:`, so the last
+ * segment is the local branch name the caller looks up. Callers fall back to
+ * the invoking checkout when the branch is not checked out anywhere locally.
+ */
+export function prSourceBranch(command: string): string | undefined {
+	const words = unwrapShellWords(command);
+	let source: string | undefined;
+	for (let i = 0; i < words.length; i++) {
+		const word = words[i]!;
+		let raw: string | undefined;
+		if (word === "--head" || word === "-H" || word === "--source-branch") {
+			raw = words[i + 1];
+		} else if (/^--(?:head|source-branch)=/.test(word)) {
+			raw = word.slice(word.indexOf("=") + 1);
+		} else if (/^-H\S/.test(word)) {
+			raw = word.slice(2);
+		}
+		if (raw === undefined) continue;
+		const branch = raw.includes(":") ? raw.slice(raw.lastIndexOf(":") + 1) : raw;
+		if (branch) source = branch;
+	}
+	return source;
+}
+
+/**
+ * Which checkout of this repository has `branch` checked out, if any.
+ *
+ * A PR is evaluated against the tree the branch actually lives in, not against
+ * whatever the caller's checkout happens to hold. Linked worktrees are the
+ * normal case: a session may sit in the primary checkout while the reviewed
+ * branch is checked out in an isolated worktree.
+ */
+export function findWorktreeForBranch(root: string, branch: string): string | undefined {
+	const target = branch.replace(/^refs\/heads\//, "").trim();
+	if (!target) return undefined;
+	const res = spawnSync("git", ["worktree", "list", "--porcelain"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+	});
+	if (res.status !== 0) return undefined;
+	let current: string | undefined;
+	for (const line of res.stdout.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			current = line.slice("worktree ".length).trim();
+			continue;
+		}
+		if (line.startsWith("branch ") && current) {
+			if (line.slice("branch ".length).trim().replace(/^refs\/heads\//, "") === target) return current;
+		}
+	}
+	return undefined;
+}
+
+export function checkMergeConflicts(root: string, ref?: string): {
 	hasConflicts: boolean;
 	baseBranch?: string;
 	reason?: string;
 } {
+	// A branch that is not checked out anywhere still has to be judged; the
+	// caller passes its ref, and HEAD stands in only when no ref was named.
+	const subject = typeof ref === "string" && ref.trim() ? ref.trim() : "HEAD";
+	const subjectLabel = subject === "HEAD" ? "" : `Branch '${subject}'`;
 	const candidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
 	for (const base of candidates) {
-		const mergeBaseRes = spawnSync("git", ["merge-base", "HEAD", base], {
+		const mergeBaseRes = spawnSync("git", ["merge-base", subject, base], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
@@ -319,7 +441,7 @@ export function checkMergeConflicts(root: string): {
 		if (mergeBaseRes.status !== 0 || !mergeBaseRes.stdout.trim()) continue;
 		const mergeBase = mergeBaseRes.stdout.trim();
 
-		const treeRes = spawnSync("git", ["merge-tree", mergeBase, "HEAD", base], {
+		const treeRes = spawnSync("git", ["merge-tree", mergeBase, subject, base], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 10_000,
@@ -328,7 +450,7 @@ export function checkMergeConflicts(root: string): {
 			return {
 				hasConflicts: true,
 				baseBranch: base,
-				reason: `Branch has merge conflicts with base branch '${base}'. Rebase or merge '${base}' to resolve all conflicts before opening a PR or handing off.`,
+				reason: `${subjectLabel || "Branch"} has merge conflicts with base branch '${base}'. Rebase or merge '${base}' to resolve all conflicts before opening a PR or handing off.`,
 			};
 		}
 	}