opencode-workflow-guard 1.14.0 → 1.15.0

package/src/lib/hygiene.ts

@@ -0,0 +1,66 @@
+import { spawnSync } from "node:child_process";
+import { checkBranchBaseIsUpToDate, currentGitBranch } from "../policies/git.ts";
+import { getCleanGitEnv } from "./worktree.ts";
+
+const MERGED_BASES = ["origin/main", "origin/master", "main", "master"];
+const MAX_LISTED_BRANCHES = 10;
+
+export interface GitHygieneSnapshot {
+	/** Local branches fully merged into the mainline, capped for bounded output. */
+	mergedLocalBranches: string[];
+	/** True count of merged local branches (the list above may be capped). */
+	mergedLocalBranchCount: number;
+	/** Worktree admin entries whose directory is missing (clearable via cleanupGitWorktree or git worktree prune). */
+	prunableWorktreeCount: number;
+	/** Commits the current branch's base line is ahead by, when a remote base exists. */
+	baseBehind?: number;
+	baseRef?: string;
+}
+
+function gitOut(args: string[], root: string): string | undefined {
+	const res = spawnSync("git", args, {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+		env: getCleanGitEnv(),
+	});
+	if (res.status !== 0) return undefined;
+	return res.stdout;
+}
+
+/**
+ * Read-only accumulation snapshot for guard_status: local branches already
+ * merged into the mainline, prunable worktree admin entries, and how far the
+ * current branch's base line is ahead. Hygiene itself stays manual — the
+ * guard reports, it never prunes or deletes branches on its own.
+ */
+export function gitHygieneSnapshot(root: string): GitHygieneSnapshot | undefined {
+	const current = currentGitBranch(root);
+	if (current === undefined) {
+		// Not a git repository (or git unavailable): no hygiene snapshot.
+		return undefined;
+	}
+	const snapshot: GitHygieneSnapshot = { mergedLocalBranches: [], mergedLocalBranchCount: 0, prunableWorktreeCount: 0 };
+	for (const base of MERGED_BASES) {
+		const out = gitOut(["branch", "--merged", base, "--format=%(refname:short)"], root);
+		if (out === undefined) continue;
+		const branches = out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((name) => name.length > 0 && name !== base && name !== current)
+			.sort();
+		snapshot.mergedLocalBranchCount = branches.length;
+		snapshot.mergedLocalBranches = branches.slice(0, MAX_LISTED_BRANCHES);
+		break;
+	}
+	const worktreeOut = gitOut(["worktree", "list", "--porcelain"], root);
+	if (worktreeOut !== undefined) {
+		snapshot.prunableWorktreeCount = worktreeOut.split("\n").filter((line) => line.startsWith("prunable")).length;
+	}
+	const behind = checkBranchBaseIsUpToDate(root);
+	if (behind.isBehind) {
+		snapshot.baseBehind = behind.count;
+		snapshot.baseRef = behind.baseRef;
+	}
+	return snapshot;
+}

package/src/lib/state.ts

@@ -3,7 +3,7 @@ import { 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";
-import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
+import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { normalizeLiveControlPlaneRoots } from "./live-control-plane.ts";
 import type {
 	TodoSdkClient,
@@ -104,15 +104,14 @@ export function recordMutation(sessionID?: string, actorSessionID?: string): voi
 		sessionMutationTimestamps.set(id, lastMutationTimestamp);
 		sessionMutationCounts.set(id, (sessionMutationCounts.get(id) ?? 0) + 1);
 		sessionVerifyResults.delete(id);
-		sessionReviews.delete(id);
-	}
-	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID || lastReview.targetSessionID === actorSessionID) {
-		lastReview = undefined;
-		try {
-			const p = getReviewCacheFilePath();
-			if (existsSync(p)) unlinkSync(p);
-		} catch {}
 	}
+	// Review evidence is intentionally NOT erased here. Recorded approvals bind
+	// to the reviewed tracked content (commit hash + tracked worktree
+	// fingerprint), so freshness is re-evaluated against content at
+	// consumption time. Erasing on any mutation made an unrelated untracked
+	// scratch-file deletion (or a mutation in a sibling worktree) invalidate a
+	// valid approval and let a re-record silently fail to stick; any change to
+	// the reviewed tracked content still makes the evidence stale.
 }
 
 export function getMutationCount(sessionID?: string): number {
@@ -195,7 +194,7 @@ export function recordReviewResult(
 	passed: boolean,
 	targetSessionID?: string,
 	workspace?: string,
-): void {
+): ReviewResult {
 	const root = projectRootKey(workspace ?? getWorkspaceRoot());
 	lastReview = {
 		reviewer,
@@ -206,12 +205,15 @@ export function recordReviewResult(
 		workspace: root,
 		commitHash: getCurrentGitCommitHash(root),
 		gitStatus: getGitStatusSummary(root),
-		worktreeFingerprint: getGitWorktreeFingerprint(root),
+		// Bind to tracked repository content only: the review covered the
+		// reviewed diff, and untracked scratch files are not part of it.
+		worktreeFingerprint: getTrackedWorktreeFingerprint(root),
 	};
 	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
 	if (passed) {
 		persistReviewCache(lastReview);
 	}
+	return lastReview;
 }
 
 export function getLastReviewResult(): typeof lastReview {
@@ -328,6 +330,13 @@ export function isReviewRequired(root: string): boolean {
 	return cfg.requireReview !== false;
 }
 
+export function isSubagentReviewRequired(root: string): boolean {
+	const env = process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW?.toLowerCase();
+	if (env === "0" || env === "false" || env === "off") return false;
+	if (env === "1" || env === "true" || env === "on") return true;
+	return getProjectConfig(root).requireSubagentReview === true;
+}
+
 export function isDocumentationRequired(root: string): boolean {
 	if (process.env.WORKFLOW_GUARD_REQUIRE_DOCS === "1") return true;
 	const cfg = getProjectConfig(root);

package/src/lib/types.ts

@@ -9,7 +9,14 @@ export interface TodoSdkClient {
 	};
 	session?: {
 		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
-		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown } }>;
+		/**
+		 * The returned record's `data.time.idle` (ms epoch, server-recorded
+		 * when a session's turn ends; absent/zero while mid-turn) is the
+		 * stale-claim staleness boundary in src/policies/file-claims.ts. The
+		 * field is assumption-typed because the minimal SDK surface here does
+		 * not declare it; a missing, zero, or non-numeric value fails closed.
+		 */
+		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown; time?: { idle?: unknown } } }>;
 		promptAsync?: (opts: {
 			path: { id: string };
 			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }> };
@@ -34,6 +41,14 @@ export interface ProjectConfig {
 		timeoutMs?: number;
 	}>;
 	requireReview?: boolean;
+	/**
+	 * Opt-in strict mode for secondary reviews: when true, record_review
+	 * rejects approvals recorded by the root session itself, so a passing
+	 * verdict must come from a subagent session with a parent. Unset or false
+	 * keeps the documented relay flow where any session may record a verdict
+	 * that is then bound to the reviewed content.
+	 */
+	requireSubagentReview?: boolean;
 	requireDocumentation?: boolean;
 	/**
 	 * Absolute paths of the LIVE control plane (runtime `~/.config/opencode`,
@@ -122,6 +137,8 @@ export interface AuditEntry {
 	evidence?: {
 		mutation?: boolean;
 		targetPath?: string;
+		/** Owner of a released stale file claim (stale_claim_takeover audits). */
+		claimOwnerSessionID?: string;
 		verification?: {
 			command: string;
 			passed: boolean;
@@ -130,6 +147,17 @@ export interface AuditEntry {
 		};
 		allowLive?: boolean;
 		reviewVerdict?: "approved" | "changes_requested" | "rejected";
+		evidenceId?: string;
+		reviewer?: string;
+		reviewTimestamp?: number;
+		binding?: {
+			workspace?: string;
+			commitHash?: string;
+			worktreeFingerprint?: string;
+			recorderSessionID?: string;
+			recorderRole?: "root" | "subagent";
+			targetSessionID?: string;
+		};
 	};
 }
 

package/src/lib/v2-plugin.ts

@@ -55,10 +55,11 @@ import { EDIT_TOOL_NAMES, fetchParentSession, fetchParentSessionID, effectiveTod
 import { currentGitBranch, isProtectedBranchName } from "../policies/git.ts";
 import { checkCompletionClaims } from "../policies/completion.ts";
 import { releaseFileClaims } from "../policies/file-claims.ts";
-import { beginReadObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
+import { beginReadObservation, recordMutationObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
 import { editTargets, runPostEditValidators, snapshotFile } from "../policies/post-edit-validation.ts";
 import { audit, summarizeInput } from "./audit.ts";
 import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
+import { loadedPluginVersion } from "./version.ts";
 import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, recordUserMessage } from "../policies/continuation.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, nextRecoveryRun } from "./checkpoint.ts";
 import { buildCompactionContext, guardToolCall } from "../workflow-guard.ts";
@@ -175,7 +176,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	}
 
 	try {
-		console.log(`[workflow-guard] info: Workflow Guard plugin initialized for ${effectiveRoot}; provenance is plugin-local in V2`);
+		console.log(`[workflow-guard] info: Workflow Guard v${loadedPluginVersion() ?? "unknown"} plugin initialized for ${effectiveRoot}; provenance is plugin-local in V2`);
 	} catch {}
 
 	const toolLifecycle = new ToolInvocationLifecycle();
@@ -281,6 +282,9 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		const pending = toolLifecycle.takePostEditSnapshots(event.sessionID, event.id);
 		if (!pending) return;
 		await runWithRuntimeState(pending.root, client, async () => {
+			// Seed the session's observation of the bytes it just mutated so a
+			// follow-up edit needs no redundant re-read (V1 parity).
+			for (const before of pending.snapshots) recordMutationObservation(before.path, event.sessionID, before.digest);
 			const reports = await Promise.all(pending.snapshots.map((before) => runPostEditValidators(pending.root, before)));
 			const report = reports.filter((value): value is string => Boolean(value)).join("\n\n");
 			if (!report) return;

package/src/lib/verify.ts

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, type Hash } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { dynamicShellSyntaxIn, normalize } from "./shell.ts";
@@ -141,6 +141,35 @@ function warnFingerprintSkip(root: string, file: string, detail: string): void {
 	} catch {}
 }
 
+/**
+ * Content hash over tracked repository content only: the index listing
+ * (staged/tracked blob hashes) plus the worktree-vs-index diff (unstaged
+ * edits). Review evidence binds to this fingerprint, not to the full one:
+ * untracked scratch files are not part of the reviewed diff, so creating,
+ * modifying, or deleting them must never invalidate a recorded approval.
+ */
+function trackedContentHash(root: string): Hash | undefined {
+	const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	if (staged.status !== 0 || unstaged.status !== 0) return undefined;
+	return createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+}
+
+export function getTrackedWorktreeFingerprint(root: string): string | undefined {
+	try {
+		return trackedContentHash(root)?.digest("hex");
+	} catch {}
+	return undefined;
+}
+
 export function getGitWorktreeFingerprint(root: string): string | undefined {
 	try {
 		// Index listing captures the exact staged/tracked content (blob hashes);
@@ -148,23 +177,14 @@ export function getGitWorktreeFingerprint(root: string): string | undefined {
 		// contents cover files git does not yet track. Together these bind the
 		// fingerprint to file contents regardless of whether HEAD exists, so
 		// freshly initialized (commitless) repositories are covered too.
-		const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
+		const hash = trackedContentHash(root);
+		if (!hash) return undefined;
 		const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
 		});
-		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
-		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+		if (untracked.status !== 0) return undefined;
 		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
 			// The path itself is always part of the fingerprint, so a skipped
 			// entry still binds its presence even when its contents do not.

package/src/lib/version.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The version of the package this module was loaded from, read from the
+ * adjacent package.json (the package ships TypeScript source, so the manifest
+ * always sits two levels above src/). Fail-soft: an unreadable or malformed
+ * manifest (for example a bundled or relocated copy without package.json)
+ * yields undefined, and callers surface that absence rather than guessing.
+ * This exists because OpenCode resolves configured bare package names through
+ * Node's parent-directory lookup from its configuration location, so the
+ * loaded copy can silently differ from a globally npm-installed one.
+ */
+export function loadedPluginVersion(moduleUrl: string = import.meta.url): string | undefined {
+	try {
+		const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", moduleUrl)), "utf8")) as { version?: unknown };
+		return typeof manifest.version === "string" && manifest.version ? manifest.version : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/lib/worktree.ts

@@ -1,5 +1,5 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, symlinkSync } from "node:fs";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve, sep } from "node:path";
 import { getWorkspaceRoot } from "./state.ts";
@@ -63,6 +63,89 @@ function localBranchExists(branch: string, root: string): boolean {
 	return res.status === 0;
 }
 
+/**
+ * Worktree timeout: WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS env wins, then the
+ * 15s default. Large checkouts can exceed 15s; without this the killed
+ * `git worktree add` left the branch behind with only its stderr progress
+ * text as the reported reason.
+ */
+export function resolveWorktreeTimeoutMs(): number {
+	const envValue = Number(process.env.WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS);
+	return Number.isFinite(envValue) && envValue > 0 ? envValue : 15_000;
+}
+
+/** git exit status is the failure signal; stderr is only context (progress lines land there too). */
+function describeGitFailure(operation: string, res: SpawnSyncReturns<string>): string {
+	const status = res.status === null
+		? `null (killed${res.signal ? ` via ${res.signal}` : ""}${res.error ? `: ${res.error.message}` : ""})`
+		: String(res.status);
+	const stderrTail = (res.stderr ?? "").trim().split("\n").filter(Boolean).slice(-3).join("; ");
+	return `git ${operation} failed (exit status ${status})${stderrTail ? `: ${stderrTail}` : ""}`;
+}
+
+/**
+ * Rolls back the partial state of a failed `git worktree add`. git creates
+ * the branch ref before the worktree checkout, so a failure after that point
+ * (target path collision, killed checkout, hook error) leaves a dangling
+ * branch and possibly stale worktree admin entries behind. Deletion of the
+ * branch only happens when this call created it.
+ */
+function rollbackFailedWorktreeAdd(options: { branch: string; branchCreatedByUs: boolean; targetPath: string; existedBefore: boolean; root: string }): string {
+	const { branch, branchCreatedByUs, targetPath, existedBefore, root } = options;
+	const notes: string[] = [];
+	try {
+		const registered = (registeredWorktreePaths(root) ?? []).map((path) => resolve(path));
+		const targetRegistered = registered.includes(resolve(targetPath));
+		if (targetRegistered && !existedBefore && existsSync(targetPath)) {
+			// Only a worktree this call registered may be force-removed. A
+			// pre-existing registered worktree at the same sanitized path
+			// (duplicate name, concurrent subagents, feat/x vs feat:x) is the
+			// reason the add failed - it must never be destroyed by rollback.
+			spawnSync("git", ["worktree", "remove", "--force", targetPath], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+		}
+		if (!existedBefore) {
+			// Clear stale worktree admin entries left by an interrupted add for
+			// this new path. Scoped to the new-path case so unrelated
+			// worktrees on temporarily unavailable paths are never pruned.
+			spawnSync("git", ["worktree", "prune"], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+		}
+		if (!existedBefore && existsSync(targetPath)) {
+			// git may have partially populated the directory before failing.
+			// It did not exist before this call, so removing it is safe; a
+			// pre-existing path (e.g. the reason the add failed) is left alone.
+			try { rmSync(targetPath, { recursive: true, force: true }); } catch {}
+		}
+		if (branchCreatedByUs) {
+			// After the deregistration above: a branch cannot be deleted while
+			// still checked out in a worktree.
+			const deleteRes = spawnSync("git", ["branch", "-D", branch], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (deleteRes.status !== 0) {
+				notes.push(`the created branch '${branch}' could not be rolled back and was left in place; delete it manually if it is not needed`);
+			}
+		}
+	} catch {
+		if (branchCreatedByUs) {
+			notes.push(`the created branch '${branch}' may remain; delete it manually if it is not needed`);
+		}
+	}
+	return notes.join("; ");
+}
+
 export function createGitWorktree(
 	branch: string,
 	baseBranch = "HEAD",
@@ -77,12 +160,13 @@ export function createGitWorktree(
 
 	const storageBase = getWorktreeStorageDir(root);
 	const targetPath = join(storageBase, branch.replace(/[/\\:]/g, "-"));
+	const existedBefore = existsSync(targetPath);
 
 	try {
 		mkdirSync(storageBase, { recursive: true });
 
-		const exists = localBranchExists(branch, root);
-		const gitArgs = exists
+		const branchAlreadyExisted = localBranchExists(branch, root);
+		const gitArgs = branchAlreadyExisted
 			? ["worktree", "add", targetPath, branch]
 			: ["worktree", "add", "-b", branch, targetPath, baseBranch];
 
@@ -90,10 +174,12 @@ export function createGitWorktree(
 			cwd: root,
 			env: getCleanGitEnv(),
 			encoding: "utf8",
-			timeout: 15_000,
+			timeout: resolveWorktreeTimeoutMs(),
 		});
 		if (addRes.status !== 0) {
-			return { success: false, error: addRes.stderr.trim() || `git worktree add failed` };
+			const rollbackNote = rollbackFailedWorktreeAdd({ branch, branchCreatedByUs: !branchAlreadyExisted, targetPath, existedBefore, root });
+			const error = describeGitFailure("worktree add", addRes) + (rollbackNote ? `; ${rollbackNote}` : "");
+			return { success: false, error };
 		}
 
 		// Symlink the parent's node_modules so tooling works without a fresh install.
@@ -131,16 +217,44 @@ export function cleanupGitWorktree(
 	root = getWorkspaceRoot(),
 ): { success: boolean; error?: string } {
 	try {
+		const resolved = resolve(worktreePath);
+		const storageBase = resolve(getWorktreeStorageDir(root));
 		if (!existsSync(worktreePath)) {
-			return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
+			// A registered worktree whose directory is gone (manual removal, a
+			// crashed add, external cleanup) still holds a stale admin entry that
+			// keeps it in `git worktree list` as prunable, and must still be
+			// cleanable. Anything outside storage or unregistered is refused.
+			// The primary working tree is never at risk: prune only removes
+			// admin dirs under .git/worktrees/<id>, which the main tree lacks.
+			if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
+				return {
+					success: false,
+					error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
+				};
+			}
+			const registeredMissing = registeredWorktreePaths(root);
+			if (!registeredMissing) {
+				return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
+			}
+			if (!registeredMissing.map((path) => resolve(path)).includes(resolved)) {
+				return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
+			}
+			const prune = spawnSync("git", ["worktree", "prune"], {
+				cwd: root,
+				env: getCleanGitEnv(),
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+			if (prune.status !== 0) {
+				return { success: false, error: describeGitFailure("worktree prune", prune) };
+			}
+			return { success: true };
 		}
 
 		// Ownership validation: the path must live under the configured worktree
 		// storage directory AND be a registered worktree of this repository. This
 		// refuses arbitrary directories, other repos' worktrees, and the primary
 		// working tree - cleanup must never be an unrestricted delete primitive.
-		const resolved = resolve(worktreePath);
-		const storageBase = resolve(getWorktreeStorageDir(root));
 		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
 			return {
 				success: false,

package/src/policies/boundary.ts

@@ -53,6 +53,33 @@ export function expandShellTargetPath(targetPath: string): string | null {
 	return out;
 }
 
+/**
+ * A mutation/redirect target whose expansion is indeterminate (it contains an
+ * unresolvable `$VARIABLE` reference): the boundary treats such destinations
+ * as outside the workspace, and block messages attribute that cause instead
+ * of the generic escape message.
+ */
+export function hasUnresolvableVariable(targetPath: string): boolean {
+	return expandShellTargetPath(targetPath) === null;
+}
+
+/**
+ * The OpenCode harness designates this directory as the agents' scratch
+ * space ("pre-created and approved for external access"), but the workspace
+ * boundary is workspace-absolute and does not cover it. Targets under it get
+ * a cause-attributed block message so agents stop treating the block as a
+ * guard bug and write scratch as untracked files inside the workspace
+ * instead. Message-only: the boundary decision itself is unchanged.
+ */
+export const OPENCODE_SCRATCH_DIR = "/tmp/opencode";
+
+export function isEnvironmentScratchTarget(targetPath: string, root: string): boolean {
+	const expanded = expandShellTargetPath(targetPath);
+	if (expanded === null) return false;
+	const resolved = resolve(root, expanded);
+	return resolved === OPENCODE_SCRATCH_DIR || resolved.startsWith(OPENCODE_SCRATCH_DIR + "/");
+}
+
 export function isPathOutsideWorkspace(targetPath: string, root: string): boolean {
 	if (!targetPath) return false;
 	const expanded = expandShellTargetPath(targetPath);
@@ -372,6 +399,9 @@ export async function guardShellMutation(
 					return PROTECTED_PATH_REASON;
 				}
 				if (isPathOutsideWorkspace(source, root)) {
+					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 would remove source '${source}' from outside the workspace root (${root}). File mutations must stay within the workspace.`;
 				}
 			}
@@ -403,6 +433,12 @@ export async function guardShellMutation(
 				// 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.`;
+				}
+				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).`;
+				}
 				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${root}). All changes must stay within the workspace.`;
 			}
 			if (onProtectedBranch(root)) {

package/src/policies/file-claims.ts

@@ -1,9 +1,13 @@
 import { readlinkSync, realpathSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import { audit } from "../lib/audit.ts";
+import { getSdkClient } from "../lib/state.ts";
 
 interface FileClaim {
 	sessionID: string;
 	callID: string;
+	/** Creation timestamp; a claim older than its owner's last idle is stale. */
+	ts: number;
 }
 
 const claims = new Map<string, FileClaim>();
@@ -36,8 +40,14 @@ export function claimFiles(paths: string[], sessionID: string, callID: string):
 	const conflict = fileClaimConflictReason(canonical, sessionID);
 	if (conflict) return conflict;
 	for (const path of canonical) {
-		if (!claims.has(path)) {
-			claims.set(path, { sessionID, callID });
+		const existing = claims.get(path);
+		if (!existing) {
+			claims.set(path, { sessionID, callID, ts: Date.now() });
+		} else if (existing.sessionID === sessionID) {
+			// The same session re-claiming the path refreshes the claim so the
+			// timestamp (and callID) reflect the in-flight call: stale-takeover
+			// never fires for it, and the after-hook release matches.
+			claims.set(path, { sessionID, callID, ts: Date.now() });
 		}
 	}
 	return undefined;
@@ -54,6 +64,62 @@ export function fileClaimConflictReason(paths: string[], sessionID: string): str
 	return undefined;
 }
 
+/**
+ * A claim is normally released by its owning tool call (after-hook) or by the
+ * owner's session.idle/session.deleted events. When an idle release is missed,
+ * the claim would otherwise block every other session forever. A claim created
+ * BEFORE its owner's last recorded idle timestamp cannot belong to an
+ * in-flight tool call — that call finished before the turn ended — so it is
+ * provably stale and is released with an audited takeover. Without an SDK
+ * client, or when the owner record cannot be read, nothing is released:
+ * fail-closed keeps live two-session protection intact. Clock skew between
+ * this process and the server is not expected for a local (same-host)
+ * service: negative skew fails closed; forward skew could make fresh claims
+ * look stale and is accepted for that deployment. Concurrent claimants can
+ * emit duplicate takeover audits (append-only, harmless). Release is
+ * per-claim: only claims whose ts is provably stale are dropped, re-read
+ * AFTER the lookup round-trip so an owner that re-claimed (and refreshed) a
+ * path meanwhile keeps its live claim.
+ */
+export async function releaseStaleFileClaims(paths: string[], claimantSessionID: string): Promise<void> {
+	const canonical = [...new Set(paths.map((path) => canonicalPath(path)))];
+	const staleOwners = new Map<string, string>();
+	for (const path of canonical) {
+		const existing = claims.get(path);
+		if (existing && existing.sessionID !== claimantSessionID && !staleOwners.has(existing.sessionID)) {
+			staleOwners.set(existing.sessionID, path);
+		}
+	}
+	if (staleOwners.size === 0) return;
+	const client = getSdkClient();
+	const session = client?.session;
+	const get = session?.get;
+	if (!session || typeof get !== "function") return;
+	for (const [ownerSessionID] of staleOwners) {
+		try {
+			const result = await get.call(session, { path: { id: ownerSessionID } });
+			const idle = (result as { data?: { time?: { idle?: unknown } } } | undefined)?.data?.time?.idle;
+			if (typeof idle !== "number" || idle <= 0) continue;
+			// Release every claim of this owner that is provably stale. Each
+			// claim is re-read after the lookup round-trip so an owner that
+			// re-claimed (and refreshed) a path meanwhile keeps its live claim.
+			for (const [claimPath, claim] of [...claims]) {
+				if (claim.sessionID !== ownerSessionID || claim.ts >= idle) continue;
+				claims.delete(claimPath);
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: claimantSessionID,
+					tool: "file-claims",
+					decision: "allow",
+					phase: "event",
+					reason: "stale_claim_takeover",
+					evidence: { mutation: false, targetPath: claimPath, claimOwnerSessionID: ownerSessionID },
+				});
+			}
+		} catch {}
+	}
+}
+
 export function releaseFileClaims(sessionID: string, callID?: string): void {
 	for (const [path, claim] of claims) {
 		if (claim.sessionID === sessionID && (callID === undefined || claim.callID === callID)) {