opencode-workflow-guard 1.18.0 → 1.18.1

package/docs/policies.md

@@ -104,6 +104,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - When the agent attempts to mark **every** task completed (finalizing the request), the guard requires passing verification evidence.
 - Verification executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. The command comes from the `WORKFLOW_GUARD_VERIFY` env, the project `verifyCommand`, or an auto-detected test or typecheck runner across ecosystems. Auto-detection covers `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini` or `pyproject.toml` (`pytest`), and `deno.json` (`deno test`). Environment configuration takes precedence over project configuration.
 - The verification timeout defaults to 30 seconds. Raise it per project with `verifyTimeoutMs` in `.opencode/workflow-guard.json`, or per environment with `WORKFLOW_GUARD_VERIFY_TIMEOUT_MS`, which wins over project config. Non-positive values are ignored and fall back to the default. Raise the timeout for suites that legitimately exceed the default, for example this repository's own unit suite.
+- A timeout is reported as `verification_timed_out`, not `verification_failed`. Both block finalization, because neither produced a passing result. They differ in what the agent is told: a timeout says the result is unknown and names the limit and the remedy, while a failure names the failing output. Calling a timeout a failure sent agents looking for an assertion that never ran, and the fix for a timeout is a longer limit rather than a code change.
 - Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` with `*`, `**`, and `?` wildcards. Brace expansion and character classes are not supported. Each entry also accepts a non-empty `command` and an optional positive `timeoutMs`. Invalid entries are reported as advisory feedback rather than silently ignored. Matching commands run from the workspace root with the same scrubbed verification environment. Validator failures and timeouts are appended to the edit result as advisory feedback. They do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list. Subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
 - Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent. Set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider and model parameters.

package/docs/testing.md

@@ -47,7 +47,7 @@ npm run test:all
 | **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. |
+| **Policy 10: Evidence Verification** | Verifies isolated verification execution, timeout handling, scrubbed environment, and finalization gating on fresh passing tests. A timeout blocks finalization under its own code, and its reason names the limit and the remedy instead of claiming a failing test. |
 | **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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/guard-dispatcher.ts

@@ -153,6 +153,17 @@ function logBlock(message: string, simulate = false): void {
 	} catch {}
 }
 
+/**
+ * Render a verification timeout limit for the block reason.
+ *
+ * Sub-second limits are exercised by tests, and a bare `Math.round(ms/1000)`
+ * reports those as "0s", which reads as no limit at all.
+ */
+function formatTimeoutLimit(timeoutMs: number | undefined): string {
+	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return "the verification timeout";
+	return timeoutMs < 1000 ? `${timeoutMs}ms` : `${Math.round(timeoutMs / 1000)}s`;
+}
+
 export async function guardToolCallImpl(
 	toolName: string,
 	input: unknown,
@@ -256,10 +267,20 @@ export async function guardToolCallImpl(
 						const result = await runVerify(command, currentRoot, resolveVerifyTimeoutMs(currentRoot));
 						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
-							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
-							const reason = `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
+							// A timeout is not a failing test. Both block
+							// finalization, but naming a failure sends the
+							// agent chasing an assertion that never ran, and
+							// the remedy is a longer limit rather than a code
+							// change. The tail is snipped as passing output on
+							// that path, because snipVerifyOutput labels a
+							// failing run with a "Verification Failed" header
+							// that would restate the misattribution.
+							const tail = snipVerifyOutput(result.output, result.timedOut === true).slice(-500);
+							const reason = result.timedOut
+								? `Blocked todowrite: verification did not finish within ${formatTimeoutLimit(result.timeoutMs)} so the result is unknown rather than failing (${command}). Raise the limit in the project .opencode/workflow-guard.json (verifyTimeoutMs) or with WORKFLOW_GUARD_VERIFY_TIMEOUT_MS, then complete the tasks again; output tail: ${tail}`
+								: `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
 							logPolicyBlock(`[workflow-guard] ${reason}`);
-							return block("verification", "verification_failed", reason);
+							return block("verification", result.timedOut ? "verification_timed_out" : "verification_failed", reason);
 						}
 					}
 				}

package/src/lib/verify.ts

@@ -231,11 +231,26 @@ export function resolveVerifyTimeoutMs(root: string): number {
 	return typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? configured : 30_000;
 }
 
+export interface VerifyRun {
+	passed: boolean;
+	output: string;
+	durationMs: number;
+	/**
+	 * Set when the command was killed at the timeout rather than exiting on its
+	 * own. A timeout is not a failing assertion: it says nothing about whether
+	 * the change is correct, and the remedy is a longer limit, not a code fix.
+	 * Callers that report a reason must attribute it, or the agent chases a
+	 * failure that does not exist.
+	 */
+	timedOut?: boolean;
+	timeoutMs?: number;
+}
+
 export async function runVerify(
 	command: string,
 	root: string,
 	timeoutMs = 30_000,
-): Promise<{ passed: boolean; output: string; durationMs: number }> {
+): Promise<VerifyRun> {
 	const start = Date.now();
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 
@@ -294,6 +309,8 @@ export async function runVerify(
 					passed: false,
 					output: output + `\n(Verification timed out after ${Math.round(timeoutMs / 1000)}s)`,
 					durationMs: Date.now() - start,
+					timedOut: true,
+					timeoutMs,
 				});
 			});
 		}, timeoutMs);

package/test/test.mts

@@ -2336,6 +2336,66 @@ check(
 	blocked(failFinalRes),
 );
 
+// A timeout is not a failing test. Both block finalization, but the reason
+// must name the timeout and its remedy. Reporting a timeout as "verification
+// is failing" sends the agent looking for a failing assertion that does not
+// exist, and the real fix is a longer timeout rather than a code change.
+console.log("- Policy 10: verification timeout attribution -");
+// The verify env overrides beat project config, so a developer with either one
+// exported (the docs recommend doing exactly that for this repo's suite) would
+// otherwise make these checks measure their shell instead of the guard.
+const prevTimeoutVerifyEnv = process.env.WORKFLOW_GUARD_VERIFY;
+const prevTimeoutLimitEnv = process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS;
+delete process.env.WORKFLOW_GUARD_VERIFY;
+delete process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS;
+const verifyTimeoutRepo = mkdtempSync(join(tmpdir(), "wg-verify-timeout-finalize-"));
+mkdirSync(join(verifyTimeoutRepo, ".opencode"), { recursive: true });
+// The command prints far more than snipVerifyOutput's line budget, so the
+// tail exercises the snipper rather than a short literal output.
+writeFileSync(
+	join(verifyTimeoutRepo, ".opencode", "workflow-guard.json"),
+	JSON.stringify({
+		verifyCommand: "node -e \"for (let i = 0; i < 60; i++) console.log('noise ' + i); setTimeout(() => {}, 5000)\"",
+		verifyTimeoutMs: 50,
+	}),
+);
+reloadProjectConfig(verifyTimeoutRepo);
+setWorkspaceRoot(verifyTimeoutRepo);
+resetVerifyState();
+todo("s-verify-timeout", item("timeout work", "in_progress"));
+await call(
+	"edit",
+	{ filePath: join(verifyTimeoutRepo, "code.ts"), content: "timeout" },
+	{ sessionID: "s-verify-timeout" },
+);
+const timeoutFinalRes = await call(
+	"todowrite",
+	{ todos: [item("timeout work", "completed")] },
+	{ sessionID: "s-verify-timeout" },
+);
+check("verification timeout blocks finalization", blocked(timeoutFinalRes));
+check(
+	"verification timeout is not reported as a failing test",
+	!String(timeoutFinalRes).includes("verification is failing"),
+);
+check(
+	"a timed-out tail carries no failure header that restates the misattribution",
+	!String(timeoutFinalRes).includes("Verification Failed"),
+);
+check(
+	"verification timeout names the elapsed limit at the precision it was set",
+	String(timeoutFinalRes).includes("timed out") && String(timeoutFinalRes).includes("50ms"),
+);
+check(
+	"verification timeout names a remedy the agent can actually apply",
+	String(timeoutFinalRes).includes("verifyTimeoutMs") && String(timeoutFinalRes).includes("WORKFLOW_GUARD_VERIFY_TIMEOUT_MS"),
+);
+setWorkspaceRoot(verifyRepo);
+reloadProjectConfig(verifyRepo);
+if (prevTimeoutVerifyEnv !== undefined) process.env.WORKFLOW_GUARD_VERIFY = prevTimeoutVerifyEnv;
+if (prevTimeoutLimitEnv !== undefined) process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS = prevTimeoutLimitEnv;
+rmSync(verifyTimeoutRepo, { recursive: true, force: true });
+
 // A subagent mutation governed by the parent's todos must invalidate the
 // parent's cached verification result.
 writeFileSync(