opencode-workflow-guard 1.15.1 → 1.15.3

package/src/lib/state.ts

@@ -1,5 +1,5 @@
-import { realpathSync, existsSync, unlinkSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, unlinkSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
 import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
@@ -13,36 +13,21 @@ import type {
 } from "./types.ts";
 
 export let workspaceRoot = process.cwd();
-export let workspaceRootReal = workspaceRoot;
 interface RuntimeState {
 	workspaceRoot: string;
-	workspaceRootReal: string;
 	sdkClient: TodoSdkClient | undefined;
 	projectConfig: ProjectConfig;
 }
 const runtimeState = new AsyncLocalStorage<RuntimeState>();
 
-try {
-	workspaceRootReal = realpathSync(workspaceRoot);
-} catch {}
-
 export function setWorkspaceRoot(root: string): void {
 	workspaceRoot = root;
-	try {
-		workspaceRootReal = realpathSync(root);
-	} catch {
-		workspaceRootReal = root;
-	}
 }
 
 export function getWorkspaceRoot(): string {
 	return runtimeState.getStore()?.workspaceRoot ?? workspaceRoot;
 }
 
-export function getWorkspaceRootReal(): string {
-	return runtimeState.getStore()?.workspaceRootReal ?? workspaceRootReal;
-}
-
 export let sdkClient: TodoSdkClient | undefined;
 
 export function setSdkClient(client: unknown): void {
@@ -54,14 +39,9 @@ export function getSdkClient(): TodoSdkClient | undefined {
 }
 
 export function runWithRuntimeState<T>(root: string, client: unknown, fn: () => T): T {
-	let realRoot = root;
-	try {
-		realRoot = realpathSync(root);
-	} catch {}
 	return runtimeState.run(
 		{
 			workspaceRoot: root,
-			workspaceRootReal: realRoot,
 			sdkClient: client as TodoSdkClient | undefined,
 			projectConfig: loadProjectConfig(root),
 		},
@@ -76,11 +56,18 @@ const workspaceMutationCounts = new Map<string, number>();
 export const sessionMutationTimestamps = new Map<string, number>();
 export const sessionMutationCounts = new Map<string, number>();
 export const sessionWorkspaces = new Map<string, string>();
+// Sessions whose workspace was registered from their OWN context (tool-call
+// arguments or a host-provided per-call worktree). A session registered only
+// from the plugin-instance default is deliberately left unmarked: concurrent
+// loops share this process, and a value derived from the last-active plugin
+// instance must never outrank the call's own context or the host fallback.
+const sessionWorkspaceBound = new Set<string>();
 
 export function setSessionWorkspace(sessionID: string, workspace: string): void {
 	if (!sessionID || !workspace) return;
 	const gitRoot = findGitRoot(workspace);
 	sessionWorkspaces.set(sessionID, gitRoot ?? projectRootKey(workspace));
+	sessionWorkspaceBound.add(sessionID);
 }
 
 export function getSessionWorkspace(sessionID?: string): string | undefined {
@@ -88,6 +75,75 @@ export function getSessionWorkspace(sessionID?: string): string | undefined {
 	return sessionWorkspaces.get(sessionID);
 }
 
+/**
+ * The session's workspace only when it was registered from the session's own
+ * context (tool-call arguments or a host-provided per-call worktree), never a
+ * plugin-instance-default bootstrap. Policy decisions that bind evidence or
+ * confine boundaries must consult this variant: two concurrent loops share one
+ * guard process, and an unbound bootstrap entry may have been derived from
+ * another session's plugin instance.
+ */
+export function getSessionBoundWorkspace(sessionID?: string): string | undefined {
+	if (!sessionID) return undefined;
+	return sessionWorkspaceBound.has(sessionID) ? sessionWorkspaces.get(sessionID) : undefined;
+}
+
+/**
+ * Register a session's workspace from a tool call's own context. Candidates in
+ * priority order: tool-argument paths (workdir/filePath — the call's own
+ * target), then a host-provided per-call worktree/directory. A session that is
+ * already registered is never re-anchored from the plugin-instance fallback:
+ * under concurrent loops that fallback can belong to a different session's
+ * workspace, which is exactly how workspaces cross-contaminate. Only a
+ * session with no registration at all is bootstrapped from the fallback, and
+ * such a bootstrap stays unbound (never used to bind review evidence).
+ */
+export function registerSessionWorkspaceFromToolCall(
+	sessionID: string | undefined,
+	call: { workdir?: string; filePath?: string; hostWorktree?: string; toolWorktree: string },
+): void {
+	if (!sessionID) return;
+	const rawCandidate = call.workdir ?? call.filePath ?? call.hostWorktree;
+	if (rawCandidate) {
+		const candidatePath = isAbsolute(rawCandidate) ? rawCandidate : resolve(call.toolWorktree, rawCandidate);
+		const gitRoot = findGitRoot(candidatePath);
+		if (gitRoot) {
+			sessionWorkspaces.set(sessionID, gitRoot);
+			sessionWorkspaceBound.add(sessionID);
+		}
+		return;
+	}
+	if (sessionWorkspaces.has(sessionID)) return;
+	const gitRoot = findGitRoot(call.toolWorktree);
+	sessionWorkspaces.set(sessionID, gitRoot ?? projectRootKey(call.toolWorktree));
+}
+
+/**
+ * The session's workspace resolved from its own bindings only: a directly
+ * registered bound workspace, else the nearest bound parent workspace
+ * (subagent sessions inherit their parent's binding for relay flows). Returns
+ * undefined when neither exists — callers that must not guess (review verdict
+ * binding) treat that as "resolve nothing, ask for an explicit directory".
+ */
+export async function resolveSessionBoundWorkspace(sessionID?: string): Promise<string | undefined> {
+	if (!sessionID) return undefined;
+	const direct = getSessionBoundWorkspace(sessionID);
+	if (direct) return direct;
+	try {
+		const client = getSdkClient();
+		const session = client?.session;
+		const get = session?.get;
+		if (typeof get === "function") {
+			const result = await get.call(session, { path: { id: sessionID } });
+			const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
+			if (typeof parent === "string" && parent && sessionWorkspaceBound.has(parent)) {
+				return sessionWorkspaces.get(parent);
+			}
+		}
+	} catch {}
+	return undefined;
+}
+
 export let lastVerify: VerifyResult | undefined;
 export const sessionVerifyResults = new Map<string, NonNullable<VerifyResult>>();
 
@@ -228,10 +284,28 @@ export function getLastReviewResult(): typeof lastReview {
 
 export function getLastReviewResultForWorkspace(root: string): typeof lastReview {
 	const workspace = projectRootKey(root);
-	const candidates = [lastReview, ...sessionReviews.values()].filter(
-		(result): result is ReviewResult => result?.workspace != null && (projectRootKey(result.workspace) === workspace || isSameGitRepo(result.workspace, root)),
+	const all = [lastReview, ...sessionReviews.values()].filter(
+		(result): result is ReviewResult & { workspace: string } => result?.workspace != null,
 	);
-	const latest = candidates.reduce<ReviewResult | undefined>((best, result) => !best || result.timestamp > best.timestamp ? result : best, undefined);
+	// Exact worktree binding wins: concurrent loops sharing one repository
+	// (different worktrees) must consume their own approvals independently —
+	// a newer sibling-worktree review must never displace this worktree's
+	// between record_review and PR creation.
+	const exact = all.filter((result) => projectRootKey(result.workspace) === workspace);
+	let preferred = exact;
+	if (preferred.length === 0) {
+		const sameRepo = all.filter((result) => isSameGitRepo(result.workspace, root));
+		if (sameRepo.length > 0) {
+			// Among same-repo candidates, prefer the review whose tracked
+			// content matches THIS worktree (the PR preflight consumes the
+			// approval bound to the tree it would publish); recency only
+			// breaks ties.
+			const prFingerprint = getTrackedWorktreeFingerprint(root);
+			const contentMatched = prFingerprint ? sameRepo.filter((result) => result.worktreeFingerprint === prFingerprint) : [];
+			preferred = contentMatched.length > 0 ? contentMatched : sameRepo;
+		}
+	}
+	const latest = preferred.reduce<ReviewResult | undefined>((best, result) => !best || result.timestamp > best.timestamp ? result : best, undefined);
 	if (latest) return latest;
 	const diskCached = loadReviewCache();
 	if (diskCached?.workspace && (projectRootKey(diskCached.workspace) === workspace || isSameGitRepo(diskCached.workspace, root))) {
@@ -254,41 +328,36 @@ export async function resolveEffectiveWorkspace(options: {
 	directory?: string;
 	fallback?: string;
 }): Promise<string> {
+	// Intended precedence. Custom tools (resolveCallWorkspace) consult the
+	// explicit argument and the host per-call context BEFORE calling this, so
+	// inside this function the remaining order is: bound session workspace >
+	// host fallback > unbound bootstrap hint > global latch/cwd. A future
+	// direct caller passing a per-call `fallback` should apply the same
+	// host-context-first step that resolveCallWorkspace does.
 	if (options.directory) {
 		const gitRoot = findGitRoot(options.directory);
 		return gitRoot ?? projectRootKey(options.directory);
 	}
+	// 1. The session's own binding (direct, or inherited from a bound parent
+	// for relay flows) wins over every ambient fallback. Concurrent loops
+	// share one guard process; a fallback derived from the last-active
+	// plugin instance must never re-anchor another session's context.
+	const bound = await resolveSessionBoundWorkspace(options.sessionID);
+	if (bound) return bound;
 	const fallbackRoot = options.fallback ? projectRootKey(options.fallback) : undefined;
 	const isFallbackFsRoot = fallbackRoot ? resolve(fallbackRoot) === resolve(fallbackRoot, "..") : true;
 
+	// 2. The call's own host-provided per-call worktree/directory.
 	if (fallbackRoot && !isFallbackFsRoot) {
-		if (options.sessionID) {
-			const sessionWs = sessionWorkspaces.get(options.sessionID);
-			if (sessionWs && isSameGitRepo(sessionWs, fallbackRoot)) {
-				return sessionWs;
-			}
-		}
 		return fallbackRoot;
 	}
 
-	if (options.sessionID) {
-		const sessionWs = sessionWorkspaces.get(options.sessionID);
-		if (sessionWs) return sessionWs;
-		try {
-			const client = getSdkClient();
-			const session = client?.session;
-			const get = session?.get;
-			if (typeof get === "function") {
-				const result = await get.call(session, { path: { id: options.sessionID } });
-				const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
-				if (typeof parent === "string" && parent && sessionWorkspaces.has(parent)) {
-					const parentWs = sessionWorkspaces.get(parent)!;
-					sessionWorkspaces.set(options.sessionID, parentWs);
-					return parentWs;
-				}
-			}
-		} catch {}
-	}
+	// 3. Unbound bootstrap hint: the session was registered only from the
+	// plugin-instance default, so it carries no per-session authority and
+	// loses to any real fallback (step 2). It is still better than the raw
+	// global latch when the fallback is absent or the filesystem root.
+	const hintRoot = options.sessionID ? sessionWorkspaces.get(options.sessionID) : undefined;
+	if (hintRoot) return hintRoot;
 	const activeRoot = getWorkspaceRoot();
 	if (activeRoot && resolve(activeRoot) !== resolve(activeRoot, "..")) {
 		const gitRoot = findGitRoot(activeRoot);

package/src/lib/tool-lifecycle.ts

@@ -7,6 +7,9 @@ function invocationKey(sessionID: string, callID: string): string {
 
 export class ToolInvocationLifecycle {
 	private readonly postEditSnapshots = new Map<string, { root: string; snapshots: FileSnapshot[] }>();
+	// Shell-redirect pre-state snapshots: they seed freshness observations
+	// only and must never run the post-edit validators.
+	private readonly shellWriteSnapshots = new Map<string, { root: string; snapshots: FileSnapshot[] }>();
 	private readonly startedAt = new Map<string, number>();
 	private readonly readObservations = new Map<string, ReadObservation>();
 	private readonly recoveryRuns = new Map<string, number>();
@@ -44,6 +47,17 @@ export class ToolInvocationLifecycle {
 		return snapshots;
 	}
 
+	setShellWriteSnapshots(sessionID: string, callID: string, root: string, snapshots: FileSnapshot[]): void {
+		this.shellWriteSnapshots.set(invocationKey(sessionID, callID), { root, snapshots });
+	}
+
+	takeShellWriteSnapshots(sessionID: string, callID: string): { root: string; snapshots: FileSnapshot[] } | undefined {
+		const key = invocationKey(sessionID, callID);
+		const snapshots = this.shellWriteSnapshots.get(key);
+		this.shellWriteSnapshots.delete(key);
+		return snapshots;
+	}
+
 	setRecoveryRun(sessionID: string, run: number): void {
 		this.recoveryRuns.set(sessionID, run);
 	}
@@ -56,7 +70,7 @@ export class ToolInvocationLifecycle {
 
 	clearSession(sessionID: string): void {
 		const prefix = `${sessionID}\0`;
-		for (const map of [this.startedAt, this.readObservations, this.postEditSnapshots]) {
+		for (const map of [this.startedAt, this.readObservations, this.postEditSnapshots, this.shellWriteSnapshots]) {
 			for (const key of map.keys()) {
 				if (key.startsWith(prefix)) map.delete(key);
 			}

package/src/lib/v2-plugin.ts

@@ -25,8 +25,8 @@ import { findGitRoot, reloadProjectConfig } from "./project-config.ts";
 import {
 	setWorkspaceRoot,
 	setSdkClient,
-	getSessionWorkspace,
-	setSessionWorkspace,
+	getSessionBoundWorkspace,
+	registerSessionWorkspaceFromToolCall,
 	runWithRuntimeState,
 	getSessionMutationCount,
 	sessionVerifyResults,
@@ -48,7 +48,7 @@ import {
 } from "./project-memory.ts";
 import { secretIn } from "../policies/secrets.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./custom-tools.ts";
-import { isReadOnlyRole } from "./guard-dispatcher.ts";
+import { isReadOnlyRole, SHELL_TOOL_NAMES } from "./guard-dispatcher.ts";
 import { ToolInvocationLifecycle } from "./tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./tool-outcomes.ts";
 import { EDIT_TOOL_NAMES, fetchParentSession, fetchParentSessionID, effectiveTodos } from "../policies/todo.ts";
@@ -56,7 +56,9 @@ import { currentGitBranch, isProtectedBranchName } from "../policies/git.ts";
 import { checkCompletionClaims } from "../policies/completion.ts";
 import { releaseFileClaims } from "../policies/file-claims.ts";
 import { beginReadObservation, recordMutationObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
-import { editTargets, runPostEditValidators, snapshotFile } from "../policies/post-edit-validation.ts";
+import { editTargets, runPostEditValidators, snapshotFile, type FileSnapshot } from "../policies/post-edit-validation.ts";
+import { extractCommands, splitShellSegments } from "./shell.ts";
+import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, redirectMutationsIn } from "../policies/boundary.ts";
 import { audit, summarizeInput } from "./audit.ts";
 import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
 import { loadedPluginVersion } from "./version.ts";
@@ -193,10 +195,14 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				// wrap it so the V2 registry receives a real StandardSchemaV1.
 				input: z.object(definition.args as unknown as z.ZodRawShape),
 				execute: async (rawInput: unknown, toolContext: { sessionID: string; id: string }) => {
+					// Only a session-bound workspace counts as the tool's own
+					// context; an unbound entry is a plugin-instance bootstrap
+					// and must not be presented to the tools as one.
+					const boundWorktree = getSessionBoundWorkspace(toolContext.sessionID);
 					const result = await (definition.execute as (input: unknown, context: unknown) => Promise<unknown>)(rawInput, {
 						sessionID: toolContext.sessionID,
-						worktree: getSessionWorkspace(toolContext.sessionID) ?? effectiveRoot,
-						directory: effectiveRoot,
+						...(boundWorktree ? { worktree: boundWorktree } : {}),
+						directory: boundWorktree ?? effectiveRoot,
 					});
 					const text = typeof result === "string" ? result : (result as { output?: string } | undefined)?.output;
 					return {
@@ -218,7 +224,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 
 	// ── Deterministic enforcement ──
 	await ctx.tool.hook("execute.before", (event) => {
-		const toolWorktree = getSessionWorkspace(event.sessionID) || effectiveRoot;
+		const toolWorktree = getSessionBoundWorkspace(event.sessionID) || effectiveRoot;
 		return runWithRuntimeState(toolWorktree, client, async () => {
 			const args = event.input;
 			const reason = await guardToolCall(event.tool, args, {
@@ -239,11 +245,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 			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(event.sessionID, gitRoot);
-			}
+			registerSessionWorkspaceFromToolCall(event.sessionID, { workdir, filePath, toolWorktree });
 			if (event.tool === "read") {
 				const target = editTargets(args, toolWorktree)[0];
 				if (target) {
@@ -255,6 +257,31 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				const snapshots = editTargets(args, toolWorktree).map(snapshotFile);
 				if (snapshots.length) toolLifecycle.setPostEditSnapshots(event.sessionID, event.id, toolWorktree, snapshots);
 			}
+			if (SHELL_TOOL_NAMES.has(event.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. (V1 parity.)
+				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(event.sessionID, event.id, toolWorktree, snapshots);
+			}
 		});
 	});
 
@@ -279,6 +306,14 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 			if (observation) recordSuccessfulRead(observation, event.sessionID);
 		}
 		if (event.status === "error") return;
+		const shellPending = toolLifecycle.takeShellWriteSnapshots(event.sessionID, event.id);
+		if (shellPending) {
+			// Seed the session's observation of the bytes its shell redirect
+			// authored (LL-003); observation-only, validators are not run for
+			// shell writes, and the digest gate keeps no-op calls from
+			// seeding. (V1 parity.)
+			for (const before of shellPending.snapshots) recordMutationObservation(before.path, event.sessionID, before.digest);
+		}
 		const pending = toolLifecycle.takePostEditSnapshots(event.sessionID, event.id);
 		if (!pending) return;
 		await runWithRuntimeState(pending.root, client, async () => {

package/src/policies/boundary.ts

@@ -4,7 +4,6 @@ import { dirname, join, resolve } from "node:path";
 import type { ShellMutation } from "../lib/types.ts";
 import {
 	getWorkspaceRoot,
-	getWorkspaceRootReal,
 	recordMutation,
 } from "../lib/state.ts";
 import { prepareRedirectResidue, shellWords, unwrapShellCommand } from "../lib/shell.ts";
@@ -86,16 +85,32 @@ export function isPathOutsideWorkspace(targetPath: string, root: string): boolea
 	if (expanded === null) return true;
 	const resolved = resolve(root, expanded);
 	const normalizedRoot = root.endsWith("/") ? root : root + "/";
-	if (resolved !== root && !resolved.startsWith(normalizedRoot)) {
-		return true;
-	}
-	const realRootVal = getWorkspaceRootReal();
+	// A path is outside only when BOTH the lexical resolution and the
+	// canonical resolution are outside. The lexical verdict is therefore
+	// held instead of returned early: symlink aliases of the workspace
+	// itself (e.g. /home -> /var/home) resolve lexically outside but
+	// canonically inside, and must be accepted, while the canonical checks
+	// below keep blocking symlinks inside the workspace that point outside.
+	// When canonicalization is indeterminate (no existing ancestor), the
+	// lexical verdict stands (fail-closed).
+	const lexicallyOutside = resolved !== root && !resolved.startsWith(normalizedRoot);
+	// The boundary is resolved against the workspace THIS call declares (the
+	// `root` argument), never against a process-global latched root: concurrent
+	// loops share one guard process, and a latched root must not redefine
+	// another session's boundary. Symlink-awareness is preserved (ancestor
+	// walk below) by canonicalizing the declared root itself.
+	let realRootVal = root;
+	try {
+		realRootVal = realpathSync(root);
+	} catch {}
+	let canonicallyInside = false;
 	try {
 		const real = realpathSync(resolved);
 		const realRoot = realRootVal.endsWith("/") ? realRootVal : realRootVal + "/";
 		if (real !== realRootVal && !real.startsWith(realRoot)) {
 			return true;
 		}
+		canonicallyInside = true;
 	} catch {
 		let curr = resolved;
 		while (curr && curr !== "/" && curr !== ".") {
@@ -108,11 +123,15 @@ export function isPathOutsideWorkspace(targetPath: string, root: string): boolea
 				if (realParent !== realRootVal && !realParent.startsWith(realRoot)) {
 					return true;
 				}
+				canonicallyInside = true;
 				break;
 			} catch {}
 		}
 	}
-	return false;
+	// Relocated lexical verdict: reached only when canonicalization did not
+	// find the path outside, so a lexically-outside path that canonicalized
+	// inside (a symlink alias of the workspace) is no longer blocked here.
+	return lexicallyOutside && !canonicallyInside;
 }
 
 export function extractPatchPaths(patchText: string): string[] {
@@ -154,7 +173,7 @@ export function teeTargetsIn(segment: string): string[] {
 	return targets;
 }
 
-function redirectMutationsIn(segment: string): ShellMutation[] {
+export function redirectMutationsIn(segment: string): ShellMutation[] {
 	const mutations: ShellMutation[] = [];
 	// Redirect detection runs on the quote-stripped residue: quoted data
 	// spans are command data and their ">" characters are not redirects,

package/src/policies/changelog.ts

@@ -193,16 +193,114 @@ export function prBodyHasLiteralLineBreakEscapes(command: string): boolean {
 	return false;
 }
 
+/**
+ * Top-level package.json sections whose change requires a matching lockfile
+ * update: the dependency maps (including peerDependenciesMeta) plus every
+ * other section a supported package manager records in its lockfile
+ * (engines/packageManager, overrides/resolutions, the pnpm section with
+ * pnpm.overrides and pnpm.patchedDependencies, the workspace graph, and the
+ * project name/version stored in the lockfile root). A scripts-only or
+ * metadata-only manifest edit regenerates the lockfile byte-identical —
+ * demanding a lockfile change for it is unsatisfiable and must not block PR
+ * creation.
+ */
+const LOCKFILE_RELEVANT_MANIFEST_KEYS = new Set([
+	"name",
+	"version",
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies",
+	"peerDependenciesMeta",
+	"engines",
+	"packageManager",
+	"overrides",
+	"resolutions",
+	"workspaces",
+	// pnpm-specific top-level section: pnpm.overrides and
+	// pnpm.patchedDependencies are recorded in pnpm-lock.yaml.
+	"pnpm",
+]);
+
+/** Order-insensitive JSON comparison: dependency maps are semantically
+ * unordered, so reordering keys alone is not a lockfile-relevant change. */
+function canonicalJsonValue(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map(canonicalJsonValue).join(",")}]`;
+	const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJsonValue(item)}`).join(",")}}`;
+}
+
+function manifestTouchesLockfileRelevantKeys(oldSource: string | undefined, newSource: string | undefined): boolean {
+	try {
+		const parse = (source: string | undefined): Record<string, unknown> | undefined => {
+			if (source === undefined) return undefined;
+			const parsed = JSON.parse(source) as unknown;
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not a manifest object");
+			return parsed as Record<string, unknown>;
+		};
+		const oldManifest = parse(oldSource);
+		const newManifest = parse(newSource);
+		const keys = new Set([...Object.keys(oldManifest ?? {}), ...Object.keys(newManifest ?? {})]);
+		for (const key of keys) {
+			if (!LOCKFILE_RELEVANT_MANIFEST_KEYS.has(key)) continue;
+			if (canonicalJsonValue(oldManifest?.[key]) !== canonicalJsonValue(newManifest?.[key])) return true;
+		}
+		return false;
+	} catch {
+		return true; // unreadable manifest: fail closed and keep demanding the lockfile
+	}
+}
+
+function manifestSourceAt(root: string, revision: string, manifestPath: string): string | undefined {
+	const res = spawnSync("git", ["show", `${revision}:${manifestPath}`], { cwd: root, encoding: "utf8", timeout: 10_000 });
+	if (res.status !== 0) return undefined;
+	return res.stdout;
+}
+
+function workingTreeManifestSource(root: string, manifestPath: string): string | undefined {
+	try {
+		return readFileSync(resolve(root, manifestPath), "utf8");
+	} catch {
+		return undefined; // deleted from the working tree
+	}
+}
+
+/**
+ * Whether a manifest change demands a lockfile update. package.json is
+ * compared section-by-section (scripts-only edits pass); Cargo.toml and
+ * go.mod have no dependency-section parser here, so any change to them
+ * conservatively demands the lockfile (unchanged behavior).
+ */
+function manifestChangeRequiresLockfile(root: string, mergeBaseCommit: string | undefined, manifestPath: string): boolean {
+	if (!/(?:^|\/)package\.json$/.test(manifestPath)) return true;
+	let oldSource: string | undefined;
+	if (mergeBaseCommit) {
+		// Absent at the merge base means the manifest was introduced on this
+		// branch (or is untracked): the pre-branch state had no manifest, so
+		// every lockfile-relevant key it has counts as new.
+		oldSource = manifestSourceAt(root, mergeBaseCommit, manifestPath);
+	} else {
+		oldSource = manifestSourceAt(root, "HEAD", manifestPath);
+	}
+	const newSource = workingTreeManifestSource(root, manifestPath);
+	if (oldSource === undefined && newSource === undefined) return true;
+	return manifestTouchesLockfileRelevantKeys(oldSource, newSource);
+}
+
 export function checkLockfileSync(root: string): { isOutOfSync: boolean; manifest?: string; lockfile?: string; reason?: string } {
 	try {
 		let modifiedFiles: string[] = [];
+		let mergeBaseCommit: string | undefined;
 		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
 		for (const base of baseCandidates) {
 			const mergeBase = spawnSync("git", ["merge-base", "HEAD", base], { cwd: root, encoding: "utf8", timeout: 10_000 });
 			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
-			const diff = spawnSync("git", ["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`], { cwd: root, encoding: "utf8", timeout: 10_000 });
+			const baseCommit = mergeBase.stdout.trim();
+			const diff = spawnSync("git", ["diff", "--name-only", `${baseCommit}...HEAD`], { cwd: root, encoding: "utf8", timeout: 10_000 });
 			if (diff.status === 0 && diff.stdout.trim()) {
 				modifiedFiles = diff.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+				mergeBaseCommit = baseCommit;
 				break;
 			}
 		}
@@ -236,16 +334,19 @@ export function checkLockfileSync(root: string): { isOutOfSync: boolean; manifes
 		];
 
 		for (const item of manifestToLockfiles) {
-			const hasManifest = modifiedFiles.some((f) => item.manifest.test(f));
-			if (hasManifest) {
-				const hasLockfile = modifiedFiles.some((f) => item.lockfiles.test(f));
-				if (!hasLockfile) {
-					return {
-						isOutOfSync: true,
-						manifest: item.name,
-						reason: `Package manifest '${item.name}' was modified without updating its corresponding lockfile. Run the package manager install/lock command before opening a PR.`,
-					};
-				}
+			const manifestPaths = modifiedFiles.filter((f) => item.manifest.test(f));
+			if (manifestPaths.length === 0) continue;
+			const hasLockfile = modifiedFiles.some((f) => item.lockfiles.test(f));
+			if (hasLockfile) continue;
+			// Only a lockfile-relevant manifest change demands the lockfile: a
+			// scripts-only edit regenerates it byte-identical, so demanding one
+			// is unsatisfiable.
+			if (manifestPaths.some((manifestPath) => manifestChangeRequiresLockfile(root, mergeBaseCommit, manifestPath))) {
+				return {
+					isOutOfSync: true,
+					manifest: item.name,
+					reason: `Package manifest '${item.name}' was modified without updating its corresponding lockfile. Run the package manager install/lock command before opening a PR.`,
+				};
 			}
 		}
 	} catch {}

package/src/policies/git.ts

@@ -346,6 +346,24 @@ const BRANCH_CREATION_VALUELESS_FLAGS = new Set([
 	"--no-track",
 ]);
 
+// Shell redirections never determine the branch start point. Exact tokens
+// cover separated operators (`2> /dev/null`); the attached pattern covers
+// operators fused with their target (`2>/dev/null`, `2>&1`, `&>/dev/null`).
+// Valid refs cannot contain `<` or `>`, so no start point can be mistaken
+// for a redirection token.
+const BRANCH_REDIRECTION_OPERATORS = new Set([
+	"<",
+	">",
+	"<<",
+	">>",
+	"<<<",
+	"<&",
+	">&",
+	"&>",
+	"&>>",
+]);
+const BRANCH_REDIRECTION_ATTACHED_RE = /^(?:&|\d{1,2})?(?:>>|>|<<<|<<|>&|<&|<)[^<>]*$/;
+
 // Classifies the optional start-point operand of an already-matched branch
 // creation invocation (`git switch -c|--create` / `git checkout -b`). Returns
 // the explicit start point when present, `{ start: undefined }` when the
@@ -357,7 +375,15 @@ export function branchCreationStartPoint(rest: string): { start?: string } | und
 	const tokens = rest.split(/\s+/).filter(Boolean);
 	let sawCreate = false;
 	let named = false;
-	for (const token of tokens) {
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i]!;
+		if (BRANCH_REDIRECTION_OPERATORS.has(token) || /^\d{1,2}(?:>>|>|<<<|<<|>&|<&|<)$/.test(token)) {
+			// Separated redirection: its target word follows and is equally
+			// irrelevant to the start point.
+			i += 1;
+			continue;
+		}
+		if (BRANCH_REDIRECTION_ATTACHED_RE.test(token)) continue;
 		const indeterminate = /[$`"']/.test(token);
 		if (!sawCreate) {
 			if (token === "switch" || token === "checkout") continue;

package/src/policies/stale-write.ts

@@ -74,7 +74,7 @@ export function staleWriteReason(path: string, sessionID: string): string | unde
 	const observed = reads.get(sessionID)?.get(canonical);
 	if (!observed) {
 		if (!current) return undefined;
-		return `Blocked: existing file '${canonical}' has not been read by this session. Re-read it before editing or overwriting it.`;
+		return `Blocked: existing file '${canonical}' has not been read by this session. Re-read it before editing or overwriting it. If another session may own it, coordinate before writing.`;
 	}
 	if (!current || !equal(observed, current)) {
 		return `Blocked: file '${canonical}' changed since this session read it. Re-read it before editing or overwriting it.`;