opencode-workflow-guard 1.8.0 → 1.8.2

package/README.md

@@ -1,10 +1,12 @@
-# opencode-workflow-guard
+# OpenCode Workflow Guard
 
 [![npm](https://img.shields.io/npm/v/opencode-workflow-guard.svg)](https://www.npmjs.com/package/opencode-workflow-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://img.shields.io/badge/tests-415%2B%20passing-brightgreen.svg)](test/test.mts)
 
-OpenCode plugin enforcing workflow discipline, agent focus, and deterministic safety boundaries through **hard plugin hooks**, not prompt instructions that LLMs can ignore.
+Deterministic policy and enforcement layer for OpenCode. Workflow Guard enforces workflow and safety invariants through **hard plugin hooks**, not prompt instructions that LLMs can ignore.
+
+Workflow Guard is deliberately **not an agent harness**: it can constrain actions, record and explain decisions, and supply bounded context, but it does not plan, prioritize, delegate, or autonomously sequence the agent's work. Bounded continuation may resume an existing session with unfinished owned todos; it never chooses the next task or creates new work.
 
 ---
 
@@ -21,7 +23,9 @@ opencode plugin "opencode-workflow-guard@$VERSION" --global --force
 
 *Requires OpenCode >= 1.18.* OpenCode detects the package's server and TUI targets and updates both global configs. Use the same command after a release to upgrade; the explicit version gives OpenCode a fresh package-cache key. Restart OpenCode after installation. See [docs/installation.md](docs/installation.md) for details and links to the OpenCode plugin documentation.
 
-For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. Do not place the TUI module under the server `plugins/` directory.
+For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. The companion shows a `Workflow Guard` shield in the prompt bar and reflects blocked state without changing agent behavior. Do not place the TUI module under the server `plugins/` directory.
+
+![Workflow Guard status badge in the OpenCode TUI](docs/assets/workflow-guard-tui-badge.png)
 
 ### 2. Verification
 
@@ -61,70 +65,6 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 
 ---
 
-## Custom Tools Registered in OpenCode
-
-| Tool | Purpose |
-|---|---|
-| `guard_next_tasks` | Load `TODO.md`, or fall back to repository roadmap/plan/task Markdown when deciding what to work on next |
-| `guard_status` | Inspect active guardrails, current branch protection, and verification/review status |
-| `guard_why` | Simulate and explain whether a specific tool call or command would be blocked |
-| `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) |
-| `learning_checkpoint` | Rank high-value Socratic opportunities while respecting the session intervention budget |
-| `learning_record` | Persist concise evidence observed during a real learning interaction |
-| `project_memory_search` | Search current durable project knowledge in the local index |
-| `project_memory_record` | Record a durable fact, decision, constraint, or lesson with provenance |
-| `project_memory_export` | Explicitly promote selected records to repo-local human-readable JSONL |
-| `project_memory_import` | Import promoted repo-local knowledge into the local index |
-
-### Experimental Socratic Learning
-
-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. 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.
-
-Memory is supporting context, not authority. Superseded records are excluded from normal retrieval, recording and plugin imports reject content recognized by Workflow Guard's secret detector, and compaction injects at most eight recent current local records. Portable repository records are never injected automatically; they are available through explicit memory search after import. A local record tied to repository paths and a Git commit is omitted from compaction when those paths have committed, staged, or unstaged changes after that commit. Always prefer current repository state when it conflicts with historical memory.
-
----
-
-## Repository Tree
-
-```
-opencode-workflow-guard/
-├── src/                       # Production plugin sources
-│   ├── workflow-guard.ts      # Server plugin entrypoint (hook orchestrator & public exports)
-│   ├── workflow-guard-ui.ts   # Optional TUI companion prompt badge
-│   ├── policies/              # Modular policy implementations (task gate, git, secrets, boundary, ...)
-│   └── lib/                   # Engine services (state, verify, audit, review, worktree, utils, types)
-├── test/                      # Test suites
-│   ├── test.mts               # 415+ in-memory unit & adversarial tests
-│   └── test-e2e.mts           # npm tarball resolution + live runtime OpenCode loader tests
-├── docs/                      # In-depth documentation & guides
-│   ├── policies.md            # Complete 24-policy reference & overrides
-│   ├── installation.md        # Setup options, worktrees & permissions
-│   ├── troubleshooting.md     # Error diagnosis & bypass explanations
-│   └── testing.md             # Test architecture & coverage matrix
-├── .changeset/                # Fragment-based versioning & release changelogs
-├── ACKNOWLEDGEMENTS.md        # Open-source community credits & inspirations
-├── CONTRIBUTING.md            # Development guide, test patterns & PR rules
-├── CHANGELOG.md               # Version history
-└── SECURITY.md                # Vulnerability disclosure policy
-```
-
----
-
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.8.0",
-  "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
+  "version": "1.8.2",
+  "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
   "main": "src/workflow-guard.ts",

package/src/lib/audit.ts

@@ -1,7 +1,8 @@
 import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, readSync, closeSync, renameSync, statSync, readFileSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 import type { AuditEntry, VerifyResult } from "./types.ts";
 import { asRecord } from "./utils.ts";
 
@@ -17,6 +18,37 @@ 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;
+let verifiedHistoryState: { size: number; mtimeMs: number; ctimeMs: number; ino: number | bigint } | undefined;
+const lockDatabases = new Map<string, DatabaseSync>();
+
+function getVerifyHistoryState(): typeof verifiedHistoryState {
+	const stat = statSync(VERIFY_HISTORY_FILE);
+	return { size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino };
+}
+
+function sameVerifyHistoryState(a: typeof verifiedHistoryState, b: typeof verifiedHistoryState): boolean {
+	return a?.size === b?.size && a?.mtimeMs === b?.mtimeMs && a?.ctimeMs === b?.ctimeMs && a?.ino === b?.ino;
+}
+
+function withFileLock<T>(path: string, action: () => T): T {
+	let db = lockDatabases.get(path);
+	if (!db) {
+		const lockPath = `${path}.lock.sqlite`;
+		db = new DatabaseSync(lockPath);
+		db.exec("PRAGMA busy_timeout = 5000");
+		chmodSync(lockPath, 0o600);
+		lockDatabases.set(path, db);
+	}
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		const result = action();
+		db.exec("COMMIT");
+		return result;
+	} catch (error) {
+		try { db.exec("ROLLBACK"); } catch {}
+		throw error;
+	}
+}
 
 export function getAuditFilePath(): string {
 	return AUDIT_FILE;
@@ -30,7 +62,7 @@ export function getVerifyHistoryFilePath(): string {
 	return VERIFY_HISTORY_FILE;
 }
 
-function appendBoundedJsonl(path: string, value: unknown, maxBytes: number, retainBytes: number): void {
+function appendBoundedJsonlUnlocked(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);
@@ -46,31 +78,43 @@ function appendBoundedJsonl(path: string, value: unknown, maxBytes: number, reta
 	const text = buffer.toString("utf8");
 	const firstNewline = text.indexOf("\n");
 	const retained = firstNewline >= 0 ? text.slice(firstNewline + 1) : "";
-	const temp = `${path}.${process.pid}.tmp`;
+	const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
 	writeFileSync(temp, retained, { encoding: "utf8", mode: 0o600 });
 	renameSync(temp, path);
 }
 
+function appendBoundedJsonl(path: string, value: unknown, maxBytes: number, retainBytes: number): void {
+	withFileLock(path, () => appendBoundedJsonlUnlocked(path, value, maxBytes, retainBytes));
+}
+
+function verifyHistoryNeedsSanitation(): boolean {
+	if (!existsSync(VERIFY_HISTORY_FILE)) return false;
+	const state = getVerifyHistoryState();
+	if (sameVerifyHistoryState(verifiedHistoryState, state)) return false;
+	return 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" || !/^sha256:[0-9a-f]{64}$/.test(value.command) || typeof value.output !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value.output);
+		} catch {
+			return true;
+		}
+	});
+}
+
 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);
+		withFileLock(VERIFY_HISTORY_FILE, () => {
+			if (verifyHistoryNeedsSanitation()) writeFileSync(VERIFY_HISTORY_FILE, "", { encoding: "utf8", mode: 0o600 });
+			appendBoundedJsonlUnlocked(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);
+			const state = getVerifyHistoryState();
+			verifiedHistoryState = verifyHistoryNeedsSanitation() ? undefined : state;
+		});
 	} catch {}
 }
 

package/src/lib/project-memory.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { DatabaseSync } from "node:sqlite";
 import type { ProjectMemoryInput, ProjectMemoryKind, ProjectMemoryRecord, ProjectMemorySource, ReviewFollowup, ReviewFollowupInput } from "./types.ts";
 
@@ -45,6 +45,24 @@ export function isProjectMemoryFresh(memory: ProjectMemoryRecord, root: string):
 	return untracked.status === 0 && !untracked.stdout.trim();
 }
 
+function execGit(root: string, args: string[]): Promise<{ status: number; stdout: string }> {
+	return new Promise((resolve) => {
+		execFile("git", ["-C", root, ...args], { encoding: "utf8", timeout: 2_000 }, (error, stdout) => {
+			resolve({ status: error ? (typeof error.code === "number" ? error.code : -1) : 0, stdout });
+		});
+	});
+}
+
+export async function isProjectMemoryFreshAsync(memory: ProjectMemoryRecord, root: string): Promise<boolean> {
+	if (!memory.commit || memory.paths.length === 0) return true;
+	if (!/^[0-9a-f]{7,64}$/i.test(memory.commit)) return false;
+	const [diff, untracked] = await Promise.all([
+		execGit(root, ["diff", "--quiet", memory.commit, "--", ...memory.paths]),
+		execGit(root, ["ls-files", "--others", "--exclude-standard", "--", ...memory.paths]),
+	]);
+	return diff.status === 0 && untracked.status === 0 && !untracked.stdout.trim();
+}
+
 export function openProjectMemory(projectId: string, directory = getProjectMemoryDir()): ProjectMemoryStore {
 	if (!projectId || projectId.length > 200) throw new Error("Invalid project memory identity.");
 	mkdirSync(directory, { recursive: true, mode: 0o700 });

package/src/lib/tool-outcomes.ts

@@ -21,8 +21,11 @@ export interface ToolOutcome {
 	repeatedFailureCount?: number;
 }
 
+const MAX_TRACKED_CALLS = 4096;
+
 export class ToolOutcomeTracker {
 	private readonly terminalCalls = new Map<string, Set<string>>();
+	private readonly fallbackCalls = new Map<string, Set<string>>();
 	private readonly failures = new Map<string, { signature: string; count: number }>();
 
 	record(part: ToolOutcomePart): ToolOutcome | undefined {
@@ -35,7 +38,13 @@ export class ToolOutcomeTracker {
 			this.terminalCalls.set(part.sessionID, terminalCalls);
 		}
 		if (terminalCalls.has(part.callID)) return undefined;
+		const fallbackCalls = this.fallbackCalls.get(part.sessionID);
+		if (fallbackCalls?.delete(part.callID) && status === "completed") {
+			terminalCalls.add(part.callID);
+			return undefined;
+		}
 		terminalCalls.add(part.callID);
+		if (terminalCalls.size > MAX_TRACKED_CALLS) terminalCalls.delete(terminalCalls.values().next().value!);
 
 		const start = part.state?.time?.start;
 		const end = part.state?.time?.end;
@@ -53,8 +62,21 @@ export class ToolOutcomeTracker {
 		return { sessionID: part.sessionID, callID: part.callID, tool: part.tool, status, durationMs, repeatedFailureCount: count };
 	}
 
+	recordFallbackCompleted(sessionID: string, callID: string, tool: string, durationMs?: number): ToolOutcome | undefined {
+		if (this.terminalCalls.get(sessionID)?.has(callID) || this.fallbackCalls.get(sessionID)?.has(callID)) return undefined;
+		let fallbackCalls = this.fallbackCalls.get(sessionID);
+		if (!fallbackCalls) {
+			fallbackCalls = new Set();
+			this.fallbackCalls.set(sessionID, fallbackCalls);
+		}
+		fallbackCalls.add(callID);
+		if (fallbackCalls.size > MAX_TRACKED_CALLS) fallbackCalls.delete(fallbackCalls.values().next().value!);
+		return { sessionID, callID, tool, status: "completed", durationMs };
+	}
+
 	clearSession(sessionID: string): void {
 		this.failures.delete(sessionID);
 		this.terminalCalls.delete(sessionID);
+		this.fallbackCalls.delete(sessionID);
 	}
 }

package/src/lib/types.ts

@@ -12,7 +12,7 @@ export interface TodoSdkClient {
 		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
 		promptAsync?: (opts: {
 			path: { id: string };
-			body: { messageID?: string; parts: Array<{ type: "text"; text: string }> };
+			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }> };
 		}) => Promise<unknown>;
 	};
 	tui?: {

package/src/policies/continuation.ts

@@ -48,6 +48,7 @@ export async function continueUnfinishedSession(sessionID: string): Promise<bool
 					parts: [{
 						type: "text",
 						text: "Workflow Guard: unfinished todos remain. Continue working through them. If you need user input, use the question tool instead of ending the run.",
+						synthetic: true,
 					}],
 				},
 			});

package/src/workflow-guard.ts

@@ -131,7 +131,7 @@ export {
 	exportProjectKnowledge,
 	importProjectKnowledge,
 } from "./lib/project-memory.ts";
-import { ensureProjectMemoryExcluded, getProjectMemoryIdentity, getRecentProjectMemory, importProjectKnowledge, isProjectMemoryFresh, listReviewFollowups, openProjectMemory } from "./lib/project-memory.ts";
+import { ensureProjectMemoryExcluded, getProjectMemoryIdentity, getRecentProjectMemory, importProjectKnowledge, isProjectMemoryFreshAsync, listReviewFollowups, openProjectMemory } from "./lib/project-memory.ts";
 
 // ── Audit & durable verification cache ───────────────────────────────────────
 import {
@@ -416,15 +416,19 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 
 		"tool.execute.after": async (input, output) => {
 			const startedAt = toolLifecycle.finish(input.sessionID, input.callID);
-			audit({
-				ts: new Date().toISOString(),
-				sessionID: input.sessionID,
-				callID: input.callID,
-				tool: input.tool,
-				decision: "allow",
-				phase: "outcome",
-				durationMs: startedAt === undefined ? undefined : Date.now() - startedAt,
-			});
+			const outcome = toolOutcomes.recordFallbackCompleted(input.sessionID, input.callID, input.tool, startedAt === undefined ? undefined : Date.now() - startedAt);
+			if (outcome) {
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: outcome.sessionID,
+					callID: outcome.callID,
+					tool: outcome.tool,
+					decision: "allow",
+					phase: "outcome",
+					durationMs: outcome.durationMs,
+					reason: outcome.status,
+				});
+			}
 			releaseFileClaims(input.sessionID, input.callID);
 			if (input.tool === "read") {
 				const observation = toolLifecycle.takeReadObservation(input.sessionID, input.callID);
@@ -503,8 +507,10 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				contextBlocks.push(stateLines.join("\n"));
 				let projectKnowledge: ReturnType<typeof getRecentProjectMemory> = [];
 				try {
-					projectKnowledge = (projectMemory ? getRecentProjectMemory(projectMemory, 8) : [])
-						.filter((memory) => memory.source !== "portable" && isProjectMemoryFresh(memory, effectiveRoot));
+					const candidates = (projectMemory ? getRecentProjectMemory(projectMemory, 8) : [])
+						.filter((memory) => memory.source !== "portable");
+					const freshness = await Promise.all(candidates.map((memory) => isProjectMemoryFreshAsync(memory, effectiveRoot)));
+					projectKnowledge = candidates.filter((_, index) => freshness[index]);
 				} catch {}
 				if (projectKnowledge.length > 0) {
 					const lines = projectKnowledge.map((memory) => `- [${memory.kind}:${memory.id.slice(0, 8)}] ${memory.content.slice(0, 300)}`);