opencode-workflow-guard 1.9.0 → 1.9.2

package/docs/superpowers/plans/2026-08-28-title-settle-default.md

@@ -0,0 +1,122 @@
+# Title Settle Default Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Workflow Guard's title-settle behavior enabled by default while preserving `titleSettleWorkaround: false` as an explicit opt-out.
+
+**Architecture:** Treat the missing setting consistently as enabled at both consumers: the continuation server hook and TUI project-option reader. Keep the existing bounded title-settle implementation unchanged; only its effective default changes.
+
+**Tech Stack:** TypeScript, OpenCode TUI plugin API, Node test harness, jsonc-parser.
+
+---
+
+### Task 1: Lock Down Default And Opt-Out Semantics
+
+**Files:**
+- Modify: `test/test.mts:1140-1155,2835-2860`
+
+- [ ] **Step 1: Change the TUI regression to expect title settling on without configuration**
+
+Before selecting the title-settle option, assert the missing setting reads as enabled. Then select its option callback and assert the persisted effective value becomes false:
+
+```ts
+registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
+check("title settle workaround project option defaults on", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === true);
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "titleSettleWorkaround")?.onSelect?.(fakeTuiApi.ui.dialog);
+check("tui project-options command can disable title settle workaround", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === false);
+```
+
+- [ ] **Step 2: Change continuation regressions to cover default-on and explicit opt-out**
+
+Use the existing title-settle continuation fixture around line 2844. Remove the requirement to write `{ titleSettleWorkaround: true }` for the positive case, and add a sibling case/fixture with `{ titleSettleWorkaround: false }` proving continuation does not wait for title settling when explicitly disabled. Preserve the existing assertions that title generation remains native and the wait remains bounded.
+
+- [ ] **Step 3: Run the unit harness to verify the new expectations fail**
+
+Run: `npm test`
+
+Expected: the new default-on assertions fail against current production code while unrelated checks remain green.
+
+### Task 2: Implement Enabled-Unless-False Semantics
+
+**Files:**
+- Modify: `src/workflow-guard-ui.ts:36-43`
+- Modify: `src/workflow-guard.ts:672`
+
+- [ ] **Step 1: Make the TUI reader default title settling to enabled**
+
+Update `readProjectOption` so both project memory and title settling are enabled unless explicitly false, while the other opt-in settings remain enabled only by explicit true:
+
+```ts
+const enabledByDefault = option === "projectMemory" || option === "titleSettleWorkaround";
+if (!existsSync(path)) return enabledByDefault;
+// parse existing config as before
+return enabledByDefault ? config?.[option] !== false : config?.[option] === true;
+```
+
+- [ ] **Step 2: Make continuation use the same effective default**
+
+Change the title-settle gate in `src/workflow-guard.ts` from:
+
+```ts
+const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround === true;
+```
+
+to:
+
+```ts
+const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround !== false;
+```
+
+- [ ] **Step 3: Run the unit harness**
+
+Run: `npm test`
+
+Expected: all checks pass, including default-enabled and explicit-false regressions.
+
+### Task 3: Document The New Default
+
+**Files:**
+- Modify: `docs/installation.md:103`
+- Modify: `docs/policies.md:86`
+- Modify: `.changeset/fix-project-option-toggles.md`
+
+- [ ] **Step 1: Update installation guidance**
+
+Replace the statement that title settling is off by default with text stating that it is on by default because Workflow Guard's automatic continuation can race OpenCode title generation, and that projects may opt out with `titleSettleWorkaround: false`.
+
+- [ ] **Step 2: Update policy documentation**
+
+Describe title settling as the default continuation behavior rather than opt-in behavior. Retain the guarantees that the wait is bounded and does not rewrite titles or provider/model parameters.
+
+- [ ] **Step 3: Expand the existing patch changeset**
+
+Make `.changeset/fix-project-option-toggles.md` mention both user-visible changes: functioning TUI toggles and title settling enabled by default with explicit opt-out.
+
+### Task 4: Verify The Final Tree
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Run type checking**
+
+Run: `npm run typecheck`
+
+Expected: exit 0 with no TypeScript errors.
+
+- [ ] **Step 2: Run the full unit/adversarial harness**
+
+Run: `npm test`
+
+Expected: all checks pass with 0 failures.
+
+- [ ] **Step 3: Run packaged installation verification**
+
+Run: `npm run test:install`
+
+Expected: all non-model-driven installation/runtime checks pass with 0 failures.
+
+- [ ] **Step 4: Check the diff**
+
+Run: `git diff --check`
+
+Expected: exit 0 with no whitespace errors.

package/docs/superpowers/specs/2026-08-28-title-settle-default-design.md

@@ -0,0 +1,25 @@
+# Title Settle Default Design
+
+## Context
+
+Workflow Guard can automatically continue a root session that still owns unfinished todos. That synthetic continuation can race OpenCode's asynchronous native session-title generation. The existing `titleSettleWorkaround` behavior avoids the race by briefly waiting for native title generation, but it currently requires explicit opt-in even though Workflow Guard's continuation behavior creates the need for the workaround.
+
+## Decision
+
+Enable the title-settle behavior by default. A missing `titleSettleWorkaround` setting means enabled; `titleSettleWorkaround: false` remains an explicit project-level opt-out.
+
+The server and TUI must expose the same effective semantics. The project-options menu therefore renders Title settle workaround as On when the setting is absent, and selecting it persists `false`. Selecting it again persists `true`.
+
+No configuration migration is required. Existing projects that do not mention the setting acquire the safer default automatically, while projects already configured with `false` retain their behavior.
+
+## Scope
+
+- Change effective server behavior from `=== true` to enabled unless explicitly false.
+- Change the TUI project-option reader to report the same enabled-by-default value.
+- Preserve all existing bounded-wait, ownership, title, provider, and model behavior.
+- Update installation and policy documentation to describe the default and opt-out.
+- Update regression coverage for default-enabled behavior and explicit-false opt-out.
+
+## Verification
+
+Regression tests must prove that an unconfigured project uses title settling, explicit `false` bypasses title settling, and the TUI reports/toggles the same effective state. The repository typecheck, unit harness, and packaged-install test must remain green.

package/docs/testing.md

@@ -0,0 +1,56 @@
+# Testing & Verification Guide
+
+This repository includes both in-memory unit tests and live runtime installation tests.
+
+---
+
+## Test Commands
+
+### 1. Build & Typecheck
+Runs strict TypeScript compilation checks across all source and test files:
+```bash
+npm run typecheck   # or: npm run build
+```
+
+### 2. In-Memory Unit Tests
+Runs the comprehensive unit and adversarial tests covering all guard policies, lifecycle validation, subagent parent-chain resolution, privilege-isolated verification, and path/symlink boundary checks:
+```bash
+npm test            # runs test.mts with isolated XDG state/data (Node >= 22.18)
+```
+
+### 3. OpenCode Runtime & Install Tests
+Packs the npm tarball, installs it into an isolated project to verify the modular entrypoint resolves, then copies the server source into an isolated `.opencode/workflow-guard-source/` directory and exposes its `WorkflowGuard` plugin function through an explicitly registered `.opencode/plugins/` adapter. A provider-free config probe verifies OpenCode resolves that local plugin before the opt-in model-driven `opencode run` probes exercise its hooks:
+```bash
+npm run test:install # package install + provider-free OpenCode loader check
+WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # also run model-driven policy probes with OpenCode's most recently selected model
+```
+Package and loader checks remain deterministic. Live probes explicitly select the first entry in OpenCode's persisted recent-model state (`${XDG_STATE_HOME:-~/.local/state}/opencode/model.json`) instead of silently inheriting the configured default model. Set `WORKFLOW_GUARD_LIVE_MODEL=provider/model` to override that selection; provider credentials still come from the normal OpenCode environment. If the selected model provider rejects a live prompt before guard behavior can run because credits, rate limits, capacity, or overload make the provider unavailable, that live case is reported as unavailable rather than as a guard failure. Other live-runtime failures still fail the suite.
+
+### 4. Full Verification Suite
+Runs typecheck, unit tests, and live runtime installation tests in sequence:
+```bash
+npm run test:all
+```
+
+---
+
+## Test Suite Coverage
+
+| Test Group | Checks |
+|---|---|
+| **Policy 1: Native Todo Gate** | Verifies edits are blocked when todos are missing, completed, or cancelled, and allowed when `pending` or `in_progress` todos exist. |
+| **Policy 1: Lifecycle** | Verifies flexible task completion, concurrent `in_progress` tasks (single-focus rule removed), and silent deletion prevention. |
+| **Policy 1: Subagent Inheritance** | Verifies subagents walk up the `parentID` hierarchy to inherit parent/grandparent todos, and handles cycle termination. |
+| **Policies 2 & 7: Git Branches** | Verifies push blocking on `main`/`master`, feature-branch editing allowances, and git commit gates. |
+| **Policy 3: PR Changelog** | Verifies `gh pr create` requires a changelog in body or diff. |
+| **Policy 4: Live Commands** | Verifies destructive CLI command blocking across Kubernetes, Terraform, Helm, cloud CLIs, and databases, plus user-set `WORKFLOW_GUARD_ALLOW_LIVE=1` override. |
+| **Policy 5: MCP Mutations** | Verifies GitHub/Azure mutating MCP tools are blocked while read-only tools pass. |
+| **Policy 6: Settings Tamper** | Verifies protection of `opencode.json`, `~/.config/opencode/*`, and `opencode auth`. |
+| **Policy 8: Workspace Boundary** | Verifies path traversal (`../`), symlinks, and absolute path escape protection in `edit`, `write`, `apply_patch`, and shell mutations. |
+| **Policy 10: Evidence Verification** | Verifies isolated verification execution, timeout handling, scrubbed environment, and finalization gating on fresh passing tests. |
+| **Adversarial Invariants** | Verifies defense against compound shell mutations, symlink escapes, chained git normalization, verify script abuse, and external repo mutations. |
+| **Audit & Permission Events** | Verifies the typed `permission.ask` hook, permission replies, and command journaling in the audit trail. |
+| **Completion Claims & Tool Honesty** | Verifies the claims-vs-evidence detector (missing/failing/stale/fresh states), `experimental.text.complete` journaling, and `tool.definition` enrichment idempotence. |
+| **Compaction & TUI Feedback** | Verifies active task injection in `experimental.session.compacting`, the static TUI badge, guard block warning toasts, and clean error propagation. |
+| **Runtime Instance Isolation** | Verifies concurrent plugin instances keep workspace root and SDK client state isolated via `runWithRuntimeState`. |
+| **Modular Exports & Shape** | Verifies V1 `PluginModule` `{ id, server }` structure, modular policy imports, and `output.args` hook contract. |

package/docs/troubleshooting.md

@@ -0,0 +1,84 @@
+# Troubleshooting Guide
+
+Common issues, root causes, and solutions when using `opencode-workflow-guard`.
+
+---
+
+### 1. `plugin config hook failed` / `Unexpected server error` on startup
+
+- **Symptoms:** OpenCode crashes or reports `Unexpected server error` when starting a session, with logs showing `TypeError: undefined is not an object (evaluating '...event')`.
+- **Root Cause:** OpenCode 1.18+'s legacy loader treats *every exported function* in a plugin module as a separate plugin instance. If a plugin exports helper functions (like `guardToolCall` or `setWorkspaceRoot`) alongside a default function, OpenCode calls them as plugins, pushes `undefined` into the hook registry, and crashes event dispatch on `session.created`.
+- **Solution:** Ensure `src/workflow-guard.ts` uses the V1 `PluginModule` export format (`export default { id: "workflow-guard", server: WorkflowGuard } satisfies PluginModule`). File plugins require an explicit `id` string.
+
+---
+
+### 2. Edits Blocked: `Blocked: no active todo item`
+
+- **Symptoms:** The agent attempts an edit (`edit`, `write`, `apply_patch`) and receives a block message directing it to create a task list.
+- **Root Cause:** Policy 1 blocks file-editing tools until the session's native todo list (`GET /session/:id/todo`) contains at least one task with status `pending` or `in_progress`.
+- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits will block again until a new breakdown is created for subsequent work.
+
+---
+
+### 3. Multiple tasks are `in_progress`
+
+- **Symptoms:** A task list contains multiple `in_progress` items during parallel work.
+- **Root Cause:** This is supported. Policy 1 permits multiple tasks to be `in_progress` so independent work and subagents can proceed concurrently.
+- **Solution:** No correction is required. Keep each active item in every replacement list until it is explicitly marked `completed` or `cancelled`.
+
+---
+
+### 4. `Blocked todowrite: active task '...' was removed`
+
+- **Symptoms:** `todowrite` is blocked after an active item disappears from the submitted list.
+- **Root Cause:** Each `todowrite` call replaces the complete list. Policy 1 therefore requires active tasks to be explicitly completed or cancelled rather than silently omitted. Independent items may otherwise be completed out of order.
+- **Solution:** Keep the task in the list and mark it `completed` or `cancelled` before removing it in a later request.
+
+---
+
+### 5. Edits Blocked: `Blocked: the workspace is on a protected branch (main/master)`
+
+- **Symptoms:** Direct edits or git commit/merge commands are rejected.
+- **Root Cause:** Policy 7 requires all code modifications to happen on a feature branch.
+- **Solution:** Switch to a feature branch (`git switch -c feat/my-feature`) before making changes.
+
+---
+
+### 6. Edits Blocked: `Blocked: file path '...' escapes workspace root`
+
+- **Symptoms:** Edits targeting files with `../` or external absolute paths are rejected.
+- **Root Cause:** Policy 8 prevents directory traversal outside the workspace root.
+- **Solution:** Ensure all target file paths resolve within the project directory.
+
+---
+
+### 7. Subagents Cannot Edit Files
+
+- **Symptoms:** A subagent spawned via `task` fails to edit files.
+- **Root Cause:** OpenCode disables `todowrite` for subagents by default.
+- **Solution:** The guard automatically walks up the `parentID` session hierarchy so subagents inherit the parent session's active tasks. Ensure the parent session has active tasks before a subagent attempts guarded mutations.
+
+---
+
+### 8. Destructive Commands Blocked (`kubectl`, `terraform`, `psql`, etc.)
+
+- **Symptoms:** A CLI command is rejected with a live-system mutation warning.
+- **Root Cause:** Policy 4 blocks destructive cloud, database, and infrastructure operations.
+- **Solution:** To intentionally run a live command, set `WORKFLOW_GUARD_ALLOW_LIVE=1` in the environment before launching OpenCode. There is no in-command override; an agent cannot grant this permission to itself.
+
+---
+
+### 9. TUI plugin is missing or remains on an older release
+
+- **Symptoms:** Workflow Guard does not appear in the TUI, or npm reports a newer Workflow Guard release while OpenCode still runs an older one.
+- **Root Cause:** OpenCode caches npm plugins. A bare package name is resolved as `@latest`, but an already-populated package cache can continue using the version that originally populated that cache key. Running `npm update` in `~/.config/opencode` does not update this OpenCode-managed plugin installation.
+- **Solution:** Use OpenCode's documented plugin installer with the explicit version you want. `--force` replaces the configured plugin version, and the explicit version gives OpenCode a new package-cache key:
+
+```bash
+VERSION=$(npm view opencode-workflow-guard version)
+opencode plugin "opencode-workflow-guard@$VERSION" --global --force
+```
+
+OpenCode documents `opencode plugin <module>` as installing a plugin and updating its config, with `--global` for global config and `--force` to replace an existing plugin version: https://opencode.ai/docs/cli/#plugin. Its plugin documentation also describes npm plugins as OpenCode-managed, cached installations: https://opencode.ai/docs/plugins/#how-plugins-are-installed.
+
+After the command reports `Detected server + tui targets`, confirm it reports replacements/additions for both the OpenCode and TUI config files, then restart OpenCode. Manual cache deletion should not be necessary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,10 @@
   },
   "files": [
     "bin/",
+    "docs/",
     "src/",
+    "test/",
+    "tsconfig.json",
     "README.md",
     "LICENSE",
     "ACKNOWLEDGEMENTS.md"

package/src/workflow-guard-ui.ts

@@ -35,11 +35,12 @@ type ProjectToggle = "recoveryCheckpoints" | "projectMemory" | "learning" | "tit
 
 export function readProjectOption(root: string, option: ProjectToggle): boolean {
 	const path = projectConfigPath(root);
-	if (!existsSync(path)) return option === "projectMemory";
+	const enabledByDefault = option === "projectMemory" || option === "titleSettleWorkaround";
+	if (!existsSync(path)) return enabledByDefault;
 	const errors: ParseError[] = [];
 	const config = parse(readFileSync(path, "utf8"), errors, { allowTrailingComma: true });
 	if (errors.length > 0) throw new Error(`Invalid Workflow Guard project config: ${path}`);
-	return option === "projectMemory" ? config?.projectMemory !== false : config?.[option] === true;
+	return enabledByDefault ? config?.[option] !== false : config?.[option] === true;
 }
 
 function writeProjectOption(root: string, option: ProjectToggle, enabled: boolean): string {
@@ -89,23 +90,22 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				const learning = readProjectOption(root, "learning");
 				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
 				const ralphMode = readProjectOption(root, "ralphMode");
+				const toggle = (key: ProjectToggle) => {
+					const enabled = !readProjectOption(root, key);
+					const path = writeProjectOption(root, key, enabled);
+					api.ui.dialog.clear();
+					api.ui.toast({ variant: "success", title: "Workflow Guard", message: `Saved ${key} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.` });
+				};
 				api.ui.dialog.replace(() => api.ui.DialogSelect({
 					title: "Workflow Guard Project Options",
 					current: undefined,
 					options: [
-						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints" },
-						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory" },
-						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools" },
-						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title" },
-						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos" },
+						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints", onSelect: () => toggle("recoveryCheckpoints") },
+						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory", onSelect: () => toggle("projectMemory") },
+						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools", onSelect: () => toggle("learning") },
+						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title", onSelect: () => toggle("titleSettleWorkaround") },
+						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos", onSelect: () => toggle("ralphMode") },
 					],
-					onSelect: (option) => {
-						const key = option.value as ProjectToggle;
-						const enabled = !readProjectOption(root, key);
-						const path = writeProjectOption(root, key, enabled);
-						api.ui.dialog.clear();
-						api.ui.toast({ variant: "success", title: "Workflow Guard", message: `Saved ${key} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.` });
-					},
 				}));
 			},
 		}],

package/src/workflow-guard.ts

@@ -669,7 +669,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					if (recoveryRun !== undefined) {
 						finalizeRecoveryCheckpoint(effectiveRoot, sessionID, recoveryRun);
 					}
-					const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround === true;
+					const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround !== false;
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => continueUnfinishedSession(sessionID, settleTitle));
 				}
 			}

package/test/run-test.mjs

@@ -0,0 +1,13 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testHome = mkdtempSync(join(tmpdir(), "workflow-guard-test-home-"));
+process.env.XDG_STATE_HOME = join(testHome, "state");
+process.env.XDG_DATA_HOME = join(testHome, "data");
+
+try {
+	await import("./test.mts");
+} finally {
+	rmSync(testHome, { recursive: true, force: true });
+}