opencode-workflow-guard 1.14.1 → 1.15.1

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

package/src/policies/git.ts

@@ -335,29 +335,152 @@ export function checkMergeConflicts(root: string): {
 	return { hasConflicts: false };
 }
 
-export function checkBranchBaseIsUpToDate(root: string): {
+const BRANCH_CREATION_VALUELESS_FLAGS = new Set([
+	"-f",
+	"--force",
+	"--discard-changes",
+	"-m",
+	"--merge",
+	"-q",
+	"--quiet",
+	"--no-track",
+]);
+
+// 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
+// invocation creates a branch from the current HEAD, and `undefined` when the
+// shape cannot be confidently classified — the caller must then fail closed to
+// the HEAD-based staleness check. Indeterminate tokens (variables, quotes,
+// unknown or value-taking flags) are never classified.
+export function branchCreationStartPoint(rest: string): { start?: string } | undefined {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let sawCreate = false;
+	let named = false;
+	for (const token of tokens) {
+		const indeterminate = /[$`"']/.test(token);
+		if (!sawCreate) {
+			if (token === "switch" || token === "checkout") continue;
+			if (token === "-c" || token === "--create" || token === "-b") {
+				sawCreate = true;
+				continue;
+			}
+			if (token.startsWith("--create=")) {
+				sawCreate = true;
+				named = true;
+				continue;
+			}
+			if (!token.startsWith("--") && token.length > 2 && (token.startsWith("-c") || token.startsWith("-b"))) {
+				sawCreate = true;
+				named = true;
+				continue;
+			}
+			if (token.startsWith("-")) {
+				if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+				return undefined;
+			}
+			return undefined;
+		}
+		if (!named) {
+			if (token.startsWith("-")) {
+				if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+				return undefined;
+			}
+			if (indeterminate) return undefined;
+			named = true;
+			continue;
+		}
+		if (token.startsWith("-")) {
+			if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+			return undefined;
+		}
+		if (indeterminate) return undefined;
+		return { start: token };
+	}
+	return sawCreate ? { start: undefined } : undefined;
+}
+
+// A branch created from an explicit start point that already contains the
+// remote default is fresh by construction, so the current branch's staleness
+// is irrelevant for it; every provided start point must resolve and contain
+// the base, and any missing start point keeps the HEAD-based check. Start
+// points that cannot be resolved fail closed. Block reasons name what was
+// actually checked and remedies that work under the guard.
+function evaluateBranchCreationStarts(
+	root: string,
+	base: string,
+	startPoints: ReadonlyArray<string>,
+): { isBehind: true; baseRef: string; reason: string } | undefined {
+	for (const startPoint of startPoints) {
+		const resolved = spawnSync("git", ["rev-parse", "--verify", "--quiet", startPoint], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (resolved.status !== 0 || !resolved.stdout.trim()) {
+			return {
+				isBehind: true,
+				baseRef: base,
+				reason: `the explicit start point '${startPoint}' could not be resolved as a commit, so freshness cannot be classified (fail closed). Use a literal branch name or ref as the start point.`,
+			};
+		}
+		const startSha = resolved.stdout.trim();
+		const contains = spawnSync("git", ["merge-base", "--is-ancestor", base, startSha], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (contains.status !== 0) {
+			const behind = spawnSync("git", ["rev-list", `${startSha}..${base}`, "--count"], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			const behindCount = parseInt((behind.stdout ?? "").trim(), 10);
+			return {
+				isBehind: true,
+				baseRef: base,
+				reason: `the explicit start point '${startPoint}' is ${isNaN(behindCount) ? "" : `${behindCount} `}commit(s) behind ${base}. Create the branch from ${base}, or from any ref that contains it, instead.`,
+			};
+		}
+	}
+	return undefined;
+}
+
+export function checkBranchBaseIsUpToDate(
+	root: string,
+	startPoints?: ReadonlyArray<string | undefined>,
+): {
 	isBehind: boolean;
 	count?: number;
 	baseRef?: string;
 	reason?: string;
 } {
+	const classified = startPoints && startPoints.length > 0 ? startPoints : undefined;
 	for (const base of ["origin/HEAD", "origin/main", "origin/master"]) {
 		const res = spawnSync("git", ["rev-list", `HEAD..${base}`, "--count"], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
 		});
-		if (res.status === 0 && res.stdout.trim()) {
-			const count = parseInt(res.stdout.trim(), 10);
-			if (!isNaN(count) && count > 0) {
-				return {
-					isBehind: true,
-					count,
-					baseRef: base,
-					reason: `Local base branch is ${count} commit(s) behind remote (${base}). Run 'git pull' or 'git fetch' on main before creating a fresh feature branch to prevent upstream conflicts.`,
-				};
-			}
+		if (res.status !== 0 || !res.stdout.trim()) continue;
+		const count = parseInt(res.stdout.trim(), 10);
+		if (isNaN(count)) continue;
+		const explicit = (classified ?? []).filter((startPoint): startPoint is string => startPoint !== undefined);
+		if (explicit.length > 0) {
+			const startBlock = evaluateBranchCreationStarts(root, base, explicit);
+			if (startBlock) return startBlock;
+		}
+		if (count > 0 && (!classified || classified.some((startPoint) => startPoint === undefined))) {
+			const branch = currentGitBranch(root) || "detached HEAD";
+			return {
+				isBehind: true,
+				count,
+				baseRef: base,
+				reason: `current branch '${branch}' is ${count} commit(s) behind remote default (${base}), so a branch created from it starts stale. Update this branch first (git rebase ${base} or git merge --ff-only ${base}), or create the new branch from ${base} directly.`,
+			};
 		}
+		return { isBehind: false };
 	}
 	return { isBehind: false };
 }

package/src/workflow-guard-ui.ts

@@ -2,7 +2,7 @@
  * Workflow Guard TUI companion plugin for OpenCode V2 (CLI plugin API).
  *
  * - Registers the `/guard-options` palette + slash command to toggle project options.
- * - Renders the Workflow Guard badge in the home and prompt footer status slots.
+ * - Renders the Workflow Guard badge in the prompt footer status slot.
  *
  * The V1 entrypoint (`WorkflowGuardTui`) remains for OpenCode 1.x TUI clients.
  */
@@ -277,7 +277,6 @@ export const WorkflowGuardTuiV2 = (ctx: TuiContext) => {
 			},
 		});
 	};
-	registerBadgeSlot("home.footer.status");
 	registerBadgeSlot("prompt.footer.status");
 	diagRender("probe-after-setup");
 

package/src/workflow-guard.ts

@@ -14,6 +14,7 @@ import { WorkflowGuardV2 } from "./lib/v2-plugin.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { join } from "node:path";
+import { loadedPluginVersion } from "./lib/version.ts";
 import { editTargets, runPostEditValidators, snapshotFile } from "./policies/post-edit-validation.ts";
 import { claimFiles, releaseFileClaims } from "./policies/file-claims.ts";
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
@@ -70,6 +71,7 @@ import {
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
+	isSubagentReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
 	isLearningEnabled,
@@ -103,6 +105,7 @@ export {
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
+	isSubagentReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
 	isLearningEnabled,
@@ -189,6 +192,8 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 		: "managed config location is unknown on this platform; plugin provenance is not verified by the OpenCode V1 API";
 }
 
+export { loadedPluginVersion } from "./lib/version.ts";
+
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
 	detectVerifyCommand,
@@ -431,7 +436,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			body: {
 				service: "workflow-guard",
 				level: "info",
-				message: `Workflow Guard plugin initialized for ${effectiveRoot}; ${managedConfigDiagnostic()}`,
+				message: `Workflow Guard v${loadedPluginVersion() ?? "unknown"} plugin initialized for ${effectiveRoot}; ${managedConfigDiagnostic()}`,
 			},
 		});
 	} catch {}