opencode-workflow-guard 1.5.1 → 1.7.0

package/README.md

@@ -12,7 +12,13 @@ OpenCode plugin enforcing workflow discipline, agent focus, and deterministic sa
 
 ### 1. Installation
 
-Add to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:
+Run the setup command to register both the server guard and TUI companion globally:
+
+```bash
+npx opencode-workflow-guard setup
+```
+
+For server-only setup, add the package to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -23,9 +29,9 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
 }
 ```
 
-*Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for full setup options and TUI companion badge configuration.
+*Requires OpenCode >= 1.18.* Restart OpenCode after setup. See [docs/installation.md](docs/installation.md) for full setup options.
 
-For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json` as well. Do not use `opencode-workflow-guard/ui`; npm parses that unscoped slash form as GitHub shorthand rather than a package export, which can trigger Git credential prompts. The package exposes OpenCode's native `./server` and `./tui` entrypoints so the package root is sufficient in both configs.
+For the optional TUI badge, configure `"opencode-workflow-guard/tui"` in `tui.json`. The package root is the server plugin; TUI plugin specs are resolved as written and must use the exported `./tui` entrypoint. Do not place the TUI module under the server `plugins/` directory.
 
 ### 2. Verification
 
@@ -43,7 +49,7 @@ WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run model-driven OpenCode
 The plugin enforces **24 deterministic policy rules** across four main pillars:
 
 * **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, and requires PR changelogs / changesets.
-* **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
+* **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks concurrent direct edits to the same canonical file across sessions, requires same-session fresh reads before `edit`/`write` can replace existing files, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
 * **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and `../` escape checks), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (`vim`, `nano`, `sudo`), and guards against dangerous package manager flags.
 
@@ -57,6 +63,7 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 |---|---|
 | [**Policy Reference**](docs/policies.md) | Comprehensive specification of all 24 enforced policies, invariants, and override semantics |
 | [**Installation & Configuration**](docs/installation.md) | Setup options, global vs. local install, worktree isolation, and project configuration |
+| [**Managed Deployment**](docs/managed-deployment.md) | Administrator-managed OpenCode policy, platform locations, and startup diagnostics |
 | [**Troubleshooting**](docs/troubleshooting.md) | Diagnosing policy blocks, common false positives, and emergency override procedures |
 | [**Testing Architecture**](docs/testing.md) | Test harness design, adversarial regression matrix, and CI verification |
 | [**Contributing Guide**](CONTRIBUTING.md) | Development workflow, coding conventions, test requirements, and changeset PR rules |
@@ -74,6 +81,8 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 | `guard_audit` | View recent audit log entries recorded in `workflow-guard.jsonl` |
 | `guard_review_rubric` | Generate the 5-axis secondary review rubric for the current branch diff |
 | `record_review` | Record a secondary reviewer subagent's verdict evaluated against the review rubric |
+| `guard_review_followups` | List durable local P2/P3 review findings that remain open across sessions |
+| `guard_review_followup_resolve` | Resolve a durable review finding after its underlying issue is fixed and verified |
 | `guard_worktree_create` | Create an isolated git worktree directory for concurrent subagent execution |
 | `guard_worktree_cleanup` | Snapshot-commit remaining changes and remove an isolated worktree directory |
 | `learning_profile` | Inspect the evidence-based local learner profile (when learning mode is enabled) |
@@ -86,13 +95,13 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 
 ### Experimental Socratic Learning
 
-Learning mode is opt-in and advisory: it never blocks tool calls or weakens deterministic guardrails. Enable it by setting `WORKFLOW_GUARD_LEARNING=1` in the user environment before OpenCode starts. Project configuration cannot enable learning or expose the global profile on its own. `maxLearningInterventions` defaults to 3 per session and can be set to `0` in `.opencode/workflow-guard.json[c]` to suppress checkpoints.
+Learning mode is opt-in and advisory: it never blocks tool calls or weakens deterministic guardrails. Enable it with `learning: true` in `.opencode/workflow-guard.json[c]` or through `/guard-options`; `WORKFLOW_GUARD_LEARNING=1` in the user environment also enables it regardless of project configuration. `maxLearningInterventions` defaults to 3 per session and can be set to `0` to suppress checkpoints.
 
 The learner profile is global to the local user and follows the XDG data convention: `$XDG_DATA_HOME/opencode/workflow-guard/learner-profile.json`, or `~/.local/share/opencode/workflow-guard/learner-profile.json` when `XDG_DATA_HOME` is unset. It stores distilled concept evidence, session/project provenance, and progression (`exposed` through `critique`), not conversation transcripts or numeric grades. Unobserved concepts remain unknown rather than being labeled knowledge gaps. Back up or delete this file independently from project repositories as desired.
 
 ### Project Memory
 
-Project memory keeps durable working knowledge between sessions without treating conversation history as project truth. Facts, decisions, constraints, and lessons are stored in a local SQLite/FTS5 index under `$XDG_DATA_HOME/opencode/workflow-guard/project-memory/`, or `~/.local/share/opencode/workflow-guard/project-memory/` when `XDG_DATA_HOME` is unset. Git repositories are identified from their common Git directory, so linked worktrees share the same local project index.
+Project memory keeps durable working knowledge between sessions without treating conversation history as project truth. It is enabled by default and can be disabled with `projectMemory: false` or through `/guard-options`. Facts, decisions, constraints, and lessons are stored in a local SQLite/FTS5 index under `$XDG_DATA_HOME/opencode/workflow-guard/project-memory/`, or `~/.local/share/opencode/workflow-guard/project-memory/` when `XDG_DATA_HOME` is unset. Git repositories are identified from their common Git directory, so linked worktrees share the same local project index.
 
 The local index is private working memory. Nothing from it is committed automatically. `project_memory_export` promotes only the explicitly selected current record IDs to `.opencode/memory/project-memory.jsonl`, a human-readable portable representation that another clone can import. The plugin adds `.opencode/memory/` to the clone-local `.git/info/exclude` by default; teams that deliberately want to version promoted knowledge can remove that exclusion or force-add the JSONL file. SQLite databases themselves should not be committed.
 

package/bin/opencode-workflow-guard.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse, modify, applyEdits } from "jsonc-parser";
+
+const SERVER_SPEC = "opencode-workflow-guard";
+const TUI_SPEC = "opencode-workflow-guard/tui";
+
+function configHome() {
+	return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+function existingConfig(base, name) {
+	const json = join(base, name + ".json");
+	const jsonc = join(base, name + ".jsonc");
+	return existsSync(json) ? json : existsSync(jsonc) ? jsonc : json;
+}
+
+function preparePluginUpdate(path, schema, spec) {
+	const source = existsSync(path) ? readFileSync(path, "utf8") : `{
+  "$schema": "${schema}"
+}\n`;
+	const errors = [];
+	const config = parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+	if (errors.length > 0 || !config || typeof config !== "object" || Array.isArray(config)) {
+		throw new Error(`Cannot update invalid config: ${path}`);
+	}
+	if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+		throw new Error(`Cannot update ${path}: "plugin" must be an array`);
+	}
+	const plugins = config.plugin ?? [];
+	if (plugins.some((entry) => entry === spec || (Array.isArray(entry) && entry[0] === spec))) return undefined;
+	return applyEdits(source, modify(source, ["plugin", plugins.length], spec, {
+		formattingOptions: { insertSpaces: true, tabSize: 2 },
+	}));
+}
+
+if (process.argv[2] !== "setup" || process.argv.length > 3) {
+	console.error("Usage: opencode-workflow-guard setup");
+	process.exitCode = 1;
+} else {
+	try {
+		const base = join(configHome(), "opencode");
+		const serverPath = existingConfig(base, "opencode");
+		const tuiPath = existingConfig(base, "tui");
+		const serverUpdate = preparePluginUpdate(serverPath, "https://opencode.ai/config.json", SERVER_SPEC);
+		const tuiUpdate = preparePluginUpdate(tuiPath, "https://opencode.ai/tui.json", TUI_SPEC);
+		mkdirSync(base, { recursive: true });
+		if (serverUpdate !== undefined) writeFileSync(serverPath, serverUpdate);
+		if (tuiUpdate !== undefined) writeFileSync(tuiPath, tuiUpdate);
+		console.log(`Workflow Guard configured in ${serverPath} and ${tuiPath}.`);
+		console.log("Restart OpenCode to load both plugins.");
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",
   "main": "src/workflow-guard.ts",
+  "bin": {
+    "opencode-workflow-guard": "./bin/opencode-workflow-guard.mjs"
+  },
   "exports": {
     ".": "./src/workflow-guard.ts",
     "./server": "./src/workflow-guard.ts",
@@ -18,6 +21,7 @@
     "url": "git+https://github.com/ultus-net/opencode-workflow-guard.git"
   },
   "files": [
+    "bin/",
     "src/",
     "README.md",
     "LICENSE",
@@ -41,7 +45,8 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.18.21",
-    "@opentui/solid": "^0.5.6"
+    "@opentui/solid": "^0.5.6",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.1",

package/src/lib/audit.ts

@@ -1,4 +1,5 @@
-import { appendFileSync, existsSync, mkdirSync, openSync, readSync, closeSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, readSync, closeSync, renameSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AuditEntry, VerifyResult } from "./types.ts";
@@ -11,6 +12,11 @@ const AUDIT_DIR = join(
 );
 const AUDIT_FILE = join(AUDIT_DIR, "workflow-guard.jsonl");
 const VERIFY_CACHE_FILE = join(AUDIT_DIR, "last-verify.json");
+const VERIFY_HISTORY_FILE = join(AUDIT_DIR, "verify-history.jsonl");
+const MAX_AUDIT_BYTES = 4 * 1024 * 1024;
+const RETAIN_AUDIT_BYTES = 2 * 1024 * 1024;
+const MAX_VERIFY_HISTORY_BYTES = 1024 * 1024;
+const RETAIN_VERIFY_HISTORY_BYTES = 512 * 1024;
 
 export function getAuditFilePath(): string {
 	return AUDIT_FILE;
@@ -20,6 +26,65 @@ export function getVerifyCacheFilePath(): string {
 	return VERIFY_CACHE_FILE;
 }
 
+export function getVerifyHistoryFilePath(): string {
+	return VERIFY_HISTORY_FILE;
+}
+
+function appendBoundedJsonl(path: string, value: unknown, maxBytes: number, retainBytes: number): void {
+	appendFileSync(path, JSON.stringify(value) + "\n", { encoding: "utf8", mode: 0o600 });
+	chmodSync(path, 0o600);
+	const stat = statSync(path);
+	if (stat.size <= maxBytes) return;
+	const fd = openSync(path, "r");
+	const size = Math.min(retainBytes, stat.size);
+	const buffer = Buffer.alloc(size);
+	try {
+		readSync(fd, buffer, 0, size, stat.size - size);
+	} finally {
+		closeSync(fd);
+	}
+	const text = buffer.toString("utf8");
+	const firstNewline = text.indexOf("\n");
+	const retained = firstNewline >= 0 ? text.slice(firstNewline + 1) : "";
+	const temp = `${path}.${process.pid}.tmp`;
+	writeFileSync(temp, retained, { encoding: "utf8", mode: 0o600 });
+	renameSync(temp, path);
+}
+
+export function persistVerifyHistory(verifyData: NonNullable<VerifyResult>): void {
+	try {
+		mkdirSync(AUDIT_DIR, { recursive: true });
+		if (existsSync(VERIFY_HISTORY_FILE)) {
+			const legacy = readFileSync(VERIFY_HISTORY_FILE, "utf8").split("\n").some((line) => {
+				if (!line.trim()) return false;
+				try {
+					const value = JSON.parse(line) as { command?: unknown; output?: unknown };
+					return typeof value.command !== "string" || !value.command.startsWith("sha256:") || typeof value.output !== "string" || !value.output.startsWith("sha256:");
+				} catch {
+					return true;
+				}
+			});
+			if (legacy) writeFileSync(VERIFY_HISTORY_FILE, "", { encoding: "utf8", mode: 0o600 });
+		}
+		appendBoundedJsonl(VERIFY_HISTORY_FILE, {
+			...verifyData,
+			command: `sha256:${createHash("sha256").update(verifyData.command).digest("hex")}`,
+			output: `sha256:${createHash("sha256").update(verifyData.output).digest("hex")}`,
+		}, MAX_VERIFY_HISTORY_BYTES, RETAIN_VERIFY_HISTORY_BYTES);
+	} catch {}
+}
+
+export function getRecentVerifyHistory(limit = 10): NonNullable<VerifyResult>[] {
+	try {
+		if (!existsSync(VERIFY_HISTORY_FILE)) return [];
+		return readFileSync(VERIFY_HISTORY_FILE, "utf8").trim().split("\n").slice(-Math.max(0, limit)).reverse().flatMap((line) => {
+			try { return [JSON.parse(line) as NonNullable<VerifyResult>]; } catch { return []; }
+		});
+	} catch {
+		return [];
+	}
+}
+
 /**
  * Persists passing verification evidence to disk so session restarts
  * or multi-agent handoffs retain valid verification state.
@@ -27,7 +92,8 @@ export function getVerifyCacheFilePath(): string {
 export function persistVerifyCache(verifyData: NonNullable<VerifyResult>): void {
 	try {
 		mkdirSync(AUDIT_DIR, { recursive: true });
-		writeFileSync(VERIFY_CACHE_FILE, JSON.stringify(verifyData, null, 2), "utf8");
+		writeFileSync(VERIFY_CACHE_FILE, JSON.stringify(verifyData, null, 2), { encoding: "utf8", mode: 0o600 });
+		chmodSync(VERIFY_CACHE_FILE, 0o600);
 	} catch {}
 }
 
@@ -87,7 +153,7 @@ export function getRecentAuditEntries(limit = 10): AuditEntry[] {
 export function audit(entry: AuditEntry): void {
 	try {
 		mkdirSync(AUDIT_DIR, { recursive: true });
-		appendFileSync(AUDIT_FILE, JSON.stringify(entry) + "\n", "utf8");
+		appendBoundedJsonl(AUDIT_FILE, entry, MAX_AUDIT_BYTES, RETAIN_AUDIT_BYTES);
 	} catch {
 		// Logging must never break the guard.
 	}
@@ -96,15 +162,17 @@ export function audit(entry: AuditEntry): void {
 export function logDecision(
 	tool: string,
 	input: unknown,
-	context: { sessionID?: string } | undefined,
+	context: { sessionID?: string; callID?: string } | undefined,
 	reason: string | undefined,
 	evidence?: AuditEntry["evidence"],
 ): void {
 	audit({
 		ts: new Date().toISOString(),
 		sessionID: context?.sessionID,
+		callID: context?.callID,
 		tool,
 		decision: reason ? "block" : "allow",
+		phase: "decision",
 		reason,
 		input: summarizeInput(input),
 		evidence,
@@ -113,7 +181,7 @@ export function logDecision(
 
 export function summarizeInput(input: unknown): unknown {
 	const record = asRecord(input);
-	if (!record) return typeof input === "string" ? input.slice(0, 200) : input;
+	if (!record) return typeof input === "string" ? summarizeSensitiveText(input) : input;
 	if (typeof record.response === "string") {
 		return {
 			sessionID: record.sessionID,
@@ -121,9 +189,16 @@ export function summarizeInput(input: unknown): unknown {
 			response: record.response,
 		};
 	}
-	if (typeof record.command === "string") return { command: record.command.slice(0, 200) };
+	if (typeof record.command === "string") return { command: summarizeSensitiveText(record.command) };
 	if (typeof record.filePath === "string") return { filePath: record.filePath };
 	if (typeof record.path === "string") return { path: record.path };
-	if (typeof record.patchText === "string") return { patchText: record.patchText.slice(0, 200) };
+	if (typeof record.patchText === "string") return { patchText: summarizeSensitiveText(record.patchText) };
 	return { keys: Object.keys(record) };
 }
+
+function summarizeSensitiveText(value: string): { bytes: number; sha256: string } {
+	return {
+		bytes: Buffer.byteLength(value, "utf8"),
+		sha256: createHash("sha256").update(value).digest("hex"),
+	};
+}

package/src/lib/checkpoint.ts

@@ -0,0 +1,308 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { getGitWorktreeFingerprint } from "./verify.ts";
+import { getCleanGitEnv } from "./worktree.ts";
+
+export interface RecoveryCheckpoint {
+	sessionID: string;
+	run: number;
+	ref: string;
+	kind: "commit" | "stash";
+	createdAt: number;
+	endFingerprint?: string;
+	endAt?: number;
+}
+
+interface CheckpointStore {
+	workspace: string;
+	checkpoints: RecoveryCheckpoint[];
+}
+
+const MAX_RECOVERY_CHECKPOINTS = 100;
+
+const gitIdentityEnv = {
+	GIT_AUTHOR_NAME: "OpenCode Workflow Guard",
+	GIT_AUTHOR_EMAIL: "workflow-guard@localhost",
+	GIT_COMMITTER_NAME: "OpenCode Workflow Guard",
+	GIT_COMMITTER_EMAIL: "workflow-guard@localhost",
+};
+
+function git(workspace: string, args: string[], env: NodeJS.ProcessEnv = {}): string {
+	if (gitForTesting) return gitForTesting(workspace, args, env);
+	return execFileSync("git", ["-C", workspace, ...args], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		env: { ...getCleanGitEnv(), ...gitIdentityEnv, ...env },
+	}).trim();
+}
+
+let gitForTesting: ((workspace: string, args: string[], env?: NodeJS.ProcessEnv) => string) | undefined;
+
+export function setCheckpointGitForTesting(runner?: typeof gitForTesting): void {
+	gitForTesting = runner;
+}
+
+function gitDir(workspace: string): string {
+	const value = git(workspace, ["rev-parse", "--path-format=absolute", "--git-dir"]);
+	return resolve(workspace, value);
+}
+
+function metadataPath(workspace: string): string {
+	return join(gitDir(workspace), "workflow-guard", "recovery-checkpoints.json");
+}
+
+function isRecoveryCheckpoint(value: unknown): value is RecoveryCheckpoint {
+	if (!value || typeof value !== "object") return false;
+	const entry = value as Record<string, unknown>;
+	return typeof entry.sessionID === "string"
+		&& Number.isInteger(entry.run) && (entry.run as number) >= 0
+		&& typeof entry.ref === "string" && entry.ref.length > 0
+		&& (entry.kind === "commit" || entry.kind === "stash")
+		&& typeof entry.createdAt === "number" && Number.isFinite(entry.createdAt)
+		&& (entry.endFingerprint === undefined || typeof entry.endFingerprint === "string")
+		&& (entry.endAt === undefined || (typeof entry.endAt === "number" && Number.isFinite(entry.endAt)));
+}
+
+function loadStore(workspace: string): CheckpointStore {
+	const path = metadataPath(workspace);
+	if (!existsSync(path)) return { workspace: resolve(workspace), checkpoints: [] };
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8")) as CheckpointStore;
+		if (value.workspace === resolve(workspace) && Array.isArray(value.checkpoints) && value.checkpoints.every(isRecoveryCheckpoint)) return value;
+	} catch {}
+	throw new Error("Recovery checkpoint metadata is corrupt; refusing to overwrite existing recovery information.");
+}
+
+function saveStore(workspace: string, store: CheckpointStore): void {
+	const path = metadataPath(workspace);
+	mkdirSync(dirname(path), { recursive: true });
+	const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	writeFileSync(temp, JSON.stringify(store, null, 2));
+	renameSync(temp, path);
+}
+
+function withStoreLock<T>(workspace: string, action: () => T): T {
+	const path = metadataPath(workspace);
+	mkdirSync(dirname(path), { recursive: true });
+	const lockPath = `${path}.lock`;
+	let lock: number;
+	try {
+		lock = openSync(lockPath, "wx", 0o600);
+	} catch {
+		throw new Error("Recovery checkpoint metadata is busy; refusing an unsafe concurrent update.");
+	}
+	try {
+		writeFileSync(lock, String(process.pid));
+		return action();
+	} finally {
+		closeSync(lock);
+		try { unlinkSync(lockPath); } catch {}
+	}
+}
+
+function updateStore<T>(workspace: string, update: (store: CheckpointStore) => T): T {
+	return withStoreLock(workspace, () => {
+		const store = loadStore(workspace);
+		const result = update(store);
+		saveStore(workspace, store);
+		return result;
+	});
+}
+
+function pruneCheckpoints(workspace: string, store: CheckpointStore): void {
+	if (store.checkpoints.length <= MAX_RECOVERY_CHECKPOINTS) return;
+	const sorted = [...store.checkpoints].sort((a, b) => a.createdAt - b.createdAt);
+	const remove = sorted.slice(0, sorted.length - MAX_RECOVERY_CHECKPOINTS);
+	const removed = new Set(remove.map((entry) => `${entry.sessionID}\0${entry.run}`));
+	for (const entry of remove) {
+		try { git(workspace, ["update-ref", "-d", privateRef(entry.sessionID, entry.run)]); } catch {}
+	}
+	store.checkpoints = store.checkpoints.filter((entry) => !removed.has(`${entry.sessionID}\0${entry.run}`));
+}
+
+function recoveryBoundaryFingerprint(workspace: string): string | undefined {
+	const worktree = getGitWorktreeFingerprint(workspace);
+	if (!worktree) return undefined;
+	try {
+		return createHash("sha256").update(git(workspace, ["rev-parse", "HEAD"])).update("\0").update(worktree).digest("hex");
+	} catch {
+		return undefined;
+	}
+}
+
+function privateRef(sessionID: string, run: number): string {
+	const session = createHash("sha256").update(sessionID).digest("hex");
+	return `refs/workflow-guard/checkpoints/${session}/${run}`;
+}
+
+function commitTree(workspace: string, tree: string, parents: string[], message: string): string {
+	const args = ["commit-tree", tree];
+	for (const parent of parents) args.push("-p", parent);
+	args.push("-m", message);
+	return git(workspace, args);
+}
+
+function captureUntracked(workspace: string): string | undefined {
+	const paths = execFileSync("git", ["-C", workspace, "ls-files", "--others", "--exclude-standard", "-z"], {
+		encoding: "buffer",
+		stdio: ["ignore", "pipe", "pipe"],
+		env: getCleanGitEnv(),
+	});
+	if (paths.length === 0) return undefined;
+	const temp = mkdtempSync(join(tmpdir(), "workflow-guard-checkpoint-"));
+	try {
+		const index = join(temp, "index");
+		const pathspec = join(temp, "paths");
+		writeFileSync(pathspec, paths);
+		const env = { GIT_INDEX_FILE: index };
+		git(workspace, ["add", "--force", `--pathspec-from-file=${pathspec}`, "--pathspec-file-nul"], env);
+		const tree = git(workspace, ["write-tree"], env);
+		return commitTree(workspace, tree, [], "untracked files on workflow-guard checkpoint");
+	} finally {
+		rmSync(temp, { recursive: true, force: true });
+	}
+}
+
+export function createRecoveryCheckpoint(workspace: string, sessionID: string, run: number): RecoveryCheckpoint | undefined {
+	try {
+		const root = resolve(workspace);
+		return withStoreLock(root, () => {
+			const store = loadStore(root);
+			const existing = store.checkpoints.find((entry) => entry.sessionID === sessionID && entry.run === run);
+			if (existing) return existing;
+			const head = git(root, ["rev-parse", "HEAD"]);
+			const message = `workflow-guard checkpoint session=${sessionID} run=${run}`;
+			const tracked = git(root, ["stash", "create", message]);
+			const untracked = captureUntracked(root);
+			let ref = tracked || head;
+			let kind: RecoveryCheckpoint["kind"] = tracked ? "stash" : "commit";
+			if (untracked) {
+				let tree: string;
+				let base: string;
+				let indexParent: string;
+				if (tracked) {
+					tree = git(root, ["rev-parse", `${tracked}^{tree}`]);
+					base = git(root, ["rev-parse", `${tracked}^1`]);
+					indexParent = git(root, ["rev-parse", `${tracked}^2`]);
+				} else {
+					base = head;
+					tree = git(root, ["rev-parse", `${head}^{tree}`]);
+					indexParent = commitTree(root, tree, [head], `index on ${message}`);
+				}
+				ref = commitTree(root, tree, [base, indexParent, untracked], message);
+				kind = "stash";
+			}
+			git(root, ["update-ref", privateRef(sessionID, run), ref]);
+			const checkpoint: RecoveryCheckpoint = { sessionID, run, ref, kind, createdAt: Date.now() };
+			store.checkpoints.push(checkpoint);
+			pruneCheckpoints(root, store);
+			saveStore(root, store);
+			return checkpoint;
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+export function finalizeRecoveryCheckpoint(workspace: string, sessionID: string, run: number): boolean {
+	try {
+		const endFingerprint = recoveryBoundaryFingerprint(workspace);
+		if (!endFingerprint) return false;
+		return updateStore(workspace, (store) => {
+			const checkpoint = store.checkpoints.find((entry) => entry.sessionID === sessionID && entry.run === run);
+			if (!checkpoint) return false;
+			checkpoint.endFingerprint = endFingerprint;
+			checkpoint.endAt = Date.now();
+			return true;
+		});
+	} catch {
+		return false;
+	}
+}
+
+export function listRecoveryCheckpoints(workspace: string, sessionID: string): RecoveryCheckpoint[] {
+	try {
+		return loadStore(workspace).checkpoints.filter((entry) => entry.sessionID === sessionID);
+	} catch {
+		return [];
+	}
+}
+
+export function nextRecoveryRun(workspace: string, sessionID: string): number {
+	const runs = listRecoveryCheckpoints(workspace, sessionID).map((entry) => entry.run);
+	return runs.length ? Math.max(...runs) + 1 : 1;
+}
+
+export function restoreRecoveryCheckpoint(
+	workspace: string,
+	sessionID: string,
+	run: number,
+): { ok: boolean; error?: string } {
+	const root = resolve(workspace);
+	try {
+		return withStoreLock(root, () => {
+			let transactionRef: string | undefined;
+			let originalHead: string | undefined;
+			try {
+				const store = loadStore(root);
+				const checkpoint = store.checkpoints.find((entry) => entry.sessionID === sessionID && entry.run === run);
+				if (!checkpoint) return { ok: false, error: `No recovery checkpoint exists for run ${run}.` };
+				if (!checkpoint.endFingerprint) return { ok: false, error: `Run ${run} has not reached an idle recovery boundary.` };
+				if (recoveryBoundaryFingerprint(root) !== checkpoint.endFingerprint) {
+					return { ok: false, error: "Workspace changed after this run reached its recovery boundary; refusing to overwrite intervening work." };
+				}
+				if (!checkpoint.endAt || store.checkpoints.some((entry) => entry.sessionID !== sessionID && (!entry.endAt || entry.endAt >= checkpoint.createdAt))) {
+					return { ok: false, error: "Another session ran at or after this checkpoint; refusing cross-session recovery." };
+				}
+				git(root, ["cat-file", "-e", `${checkpoint.ref}^{commit}`]);
+				originalHead = git(root, ["rev-parse", "HEAD"]);
+				const transaction = `refs/workflow-guard/restore-transactions/${randomUUID()}`;
+				const beforeStash = (() => { try { return git(root, ["rev-parse", "refs/stash"]); } catch { return ""; } })();
+				git(root, ["stash", "push", "--include-untracked", "--message", "workflow-guard restore transaction"]);
+				const afterStash = (() => { try { return git(root, ["rev-parse", "refs/stash"]); } catch { return ""; } })();
+				if (afterStash && afterStash !== beforeStash) {
+					git(root, ["update-ref", transaction, afterStash]);
+					transactionRef = transaction;
+					git(root, ["stash", "drop", "stash@{0}"]);
+				}
+				git(root, ["clean", "-fd"]);
+				if (checkpoint.kind === "stash") {
+					const base = git(root, ["rev-parse", `${checkpoint.ref}^1`]);
+					git(root, ["reset", "--hard", base]);
+					git(root, ["stash", "apply", "--index", checkpoint.ref]);
+				} else {
+					git(root, ["reset", "--hard", checkpoint.ref]);
+				}
+				if (transactionRef) git(root, ["update-ref", "-d", transactionRef]);
+				return { ok: true };
+			} catch (error) {
+				let rollbackError: unknown;
+				if (originalHead) {
+					try {
+						git(root, ["reset", "--hard", originalHead]);
+						if (transactionRef) {
+							git(root, ["clean", "-fd"]);
+							git(root, ["stash", "apply", "--index", transactionRef]);
+							try {
+								if (git(root, ["rev-parse", "refs/stash"]) === git(root, ["rev-parse", transactionRef])) {
+									git(root, ["stash", "drop", "stash@{0}"]);
+								}
+							} catch {}
+							git(root, ["update-ref", "-d", transactionRef]);
+						}
+					} catch (error) {
+						rollbackError = error;
+					}
+				}
+				const primary = error instanceof Error ? error.message : String(error);
+				const rollback = rollbackError instanceof Error ? rollbackError.message : rollbackError === undefined ? undefined : String(rollbackError);
+				return { ok: false, error: rollback ? `${primary} Recovery rollback also failed: ${rollback}` : primary };
+			}
+		});
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}