opencode-workflow-guard 1.15.5 → 1.16.0

package/src/lib/v2-todo.ts

@@ -2,12 +2,27 @@
  * V2 todo reconstruction shared by the plugin entrypoint and its V1 SDK
  * adapter.
  *
- * OpenCode V2 exposes no todo endpoint, and its builtin tool registry has no
- * `todowrite` (the V1 name). Todo state therefore only exists when an ACP agent
- * supplies its own `todowrite` tool. This module reads that state from session
- * message history and distinguishes "definitively empty" from "cannot
- * determine", which the policy layer relies on to decide whether to enforce the
- * active-todo gate.
+ * Version boundary, because the two generations need different treatment:
+ *
+ * - **OpenCode 2.0.x** exposes no todo endpoint and its builtin tool registry
+ *   has no `todowrite` (the V1 name). Todo state only exists when an ACP agent
+ *   supplies its own `todowrite` tool, so the list is reconstructed from
+ *   session message history.
+ * - **OpenCode 2.1.x** reintroduces a builtin `todowrite` behind the
+ *   `experimental.todo` config key. When that tool is registered, a session
+ *   with no todo part has never planned, which must gate mutations rather than
+ *   fail open.
+ *
+ * Capability is therefore probed, not inferred from history: `detectTodoCapability`
+ * asks the host's tool registry (`ctx.tool.list()`) whether `todowrite` is
+ * registered. History tells you whether a session planned; the registry tells
+ * you whether planning was possible. Only the second question decides whether
+ * an empty list means "not yet planned" or "cannot plan".
+ *
+ * This module distinguishes "definitively empty" from "cannot determine", which
+ * the policy layer relies on to decide whether to enforce the active-todo gate.
+ * Todos are never evidence: a `todowrite` call replaces the whole list, so a
+ * model can mark everything completed without doing the work.
  */
 
 import type { TodoItem } from "./types.ts";
@@ -19,6 +34,50 @@ export interface TodoScanContext {
 	};
 }
 
+/** Minimal tool-registry surface needed to probe for `todowrite`. */
+export interface TodoCapabilityContext {
+	tool?: {
+		list?: () => Promise<unknown>;
+	};
+}
+
+/**
+ * Whether this host can plan at all.
+ *
+ * - `available`: the registry reports `todowrite`, so an empty list means the
+ *   session never planned and the gate must enforce.
+ * - `unavailable`: the registry answered and has no `todowrite`, so the gate
+ *   must fail open or builtin-only sessions deadlock.
+ * - `unknown`: the registry could not be read. Treat as unavailable for
+ *   enforcement, but say so out loud (the caller logs once per session).
+ */
+export type TodoCapability = "available" | "unavailable" | "unknown";
+
+/**
+ * Probe the host's tool registry for `todowrite`.
+ *
+ * Tool ids on the host are effective names, so a namespaced or prefixed
+ * registration (`todowrite`, `todo.write`) still counts. A registry that throws
+ * or is absent reports `unknown` rather than `unavailable`, because "we could
+ * not ask" must never be reported as "the host said no".
+ */
+export async function detectTodoCapability(ctx: TodoCapabilityContext | undefined): Promise<TodoCapability> {
+	const list = ctx?.tool?.list;
+	if (typeof list !== "function") return "unknown";
+	try {
+		const entries = await list.call(ctx!.tool);
+		if (!Array.isArray(entries)) return "unknown";
+		return entries.some((entry) => {
+			const name = (entry as { name?: unknown; id?: unknown } | undefined)?.name ?? (entry as { id?: unknown } | undefined)?.id;
+			return typeof name === "string" && /^todowrite$/i.test(name);
+		})
+			? "available"
+			: "unavailable";
+	} catch {
+		return "unknown";
+	}
+}
+
 /**
  * V2 tool parts carry the tool name in `tool` (the V1 field was `name`); ACP
  * agents may still report either shape, so accept both.
@@ -29,6 +88,66 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
 	return undefined;
 }
 
+/**
+ * Proven capability per plugin instance, for reporting and for the fail-open
+ * warning. Held on `globalThis` via `Symbol.for` because OpenCode can load the
+ * same package from two module paths (a cache copy plus a source checkout), and
+ * the capability answer must agree between them.
+ */
+const TODO_CAPABILITY = Symbol.for("opencode-workflow-guard.todo-capability.v1");
+const capabilityRegistry = globalThis as unknown as Record<symbol, TodoCapability | undefined>;
+
+/** Last probed capability. `unknown` before setup, which fails open. */
+export function recordedTodoCapability(): TodoCapability {
+	return capabilityRegistry[TODO_CAPABILITY] ?? "unknown";
+}
+
+/**
+ * Record the probed capability. Returns the previous value so the caller can
+ * tell whether this is the first probe for the process.
+ */
+export function recordTodoCapability(capability: TodoCapability): TodoCapability {
+	const previous = recordedTodoCapability();
+	capabilityRegistry[TODO_CAPABILITY] = capability;
+	return previous;
+}
+
+export function resetTodoCapabilityForTesting(): void {
+	delete capabilityRegistry[TODO_CAPABILITY];
+}
+
+/**
+ * Sessions already warned about the fail-open path. Bounded: the warning is
+ * once per session, and a process that outlives thousands of sessions must not
+ * leak a set for every one of them.
+ */
+const WARNED_SESSIONS = Symbol.for("opencode-workflow-guard.todo-warned.v2");
+const warnedRegistry = globalThis as unknown as Record<symbol, Set<string> | undefined>;
+const warnedSessions: Set<string> =
+	warnedRegistry[WARNED_SESSIONS] ?? (warnedRegistry[WARNED_SESSIONS] = new Set());
+const MAX_WARNED_SESSIONS = 512;
+
+/**
+ * Report the active-todo gate failing open, once per session.
+ *
+ * Silent fail-open is how a rails policy becomes decorative: the gate stops
+ * enforcing and nothing says so. Returns true when this call was the first for
+ * the session, so the caller can journal it exactly once.
+ */
+export function reportTodoGateFailOpen(sessionID: string | undefined, capability: TodoCapability): boolean {
+	const key = sessionID ?? "<no-session>";
+	if (warnedSessions.has(key)) return false;
+	if (warnedSessions.size >= MAX_WARNED_SESSIONS) warnedSessions.clear();
+	warnedSessions.add(key);
+	try {
+		console.warn(
+			`[workflow-guard] warn: active-todo gate is not enforcing for session ${key}: ` +
+				`todoCapability=${capability}. Mutations are allowed without an active todo.`,
+		);
+	} catch {}
+	return true;
+}
+
 /**
  * Reconstruct one session's current todo list from its message history. The
  * newest applied `todowrite` tool call's input is the current state.
@@ -37,7 +156,13 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
  * - `TodoItem[]` when a `todowrite` part defines the list, including `[]` when
  *   the newest applied call emptied it;
  * - `undefined` when todo state is unknown: the history cannot be read, or the
- *   session contains no `todowrite` part at all (no todo capability).
+ *   session contains no `todowrite` part and the capability is absent.
+ *
+ * `capability` decides what an empty history means. When the host reports
+ * `available`, a session with no `todowrite` part has never planned, so the
+ * result is `[]` and the mutation gate enforces. When it is `unavailable` or
+ * `unknown`, an empty history stays `undefined` so builtin-only sessions fail
+ * open instead of deadlocking on a tool they cannot call.
  *
  * Callers must treat `undefined` as "cannot determine" (fail open) and `[]` as
  * "definitively no active todos" (enforce). Collapsing the two is what
@@ -46,6 +171,7 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
 export async function scanSessionTodos(
 	ctx: TodoScanContext,
 	sessionID: string,
+	capability: TodoCapability = "unknown",
 ): Promise<TodoItem[] | undefined> {
 	try {
 		const messages = (await ctx.session.context({ sessionID })) as unknown as Array<{ content?: unknown }>;
@@ -66,6 +192,10 @@ export async function scanSessionTodos(
 				if (Array.isArray(todos)) return todos as TodoItem[];
 			}
 		}
+		// No applied `todowrite` part. With a registered tool that means the
+		// session never planned, which must gate. Without one, the session
+		// cannot plan at all, so the gate has nothing to enforce.
+		if (capability === "available") return [];
 		// A `todowrite` part exists but none is applied yet (e.g. still
 		// streaming): the list is in flux, report it as empty rather than
 		// unknown so the gate stays closed until the write settles.

package/src/lib/version.ts

@@ -19,3 +19,25 @@ export function loadedPluginVersion(moduleUrl: string = import.meta.url): string
 		return undefined;
 	}
 }
+
+/**
+ * The OpenCode release this build is qualified against, read from the pinned
+ * `@opencode/plugin` dependency in the same manifest.
+ *
+ * Pinning the host API stops an unreviewed major from floating in, but a
+ * published guard can still be installed into a host that is newer or older
+ * than the one it was verified on. Reporting the qualified pair next to the
+ * loaded host version makes that mismatch visible before it becomes a silent
+ * no-op, which is the failure mode the migration guide names.
+ */
+export function qualifiedHostVersion(moduleUrl: string = import.meta.url): string | undefined {
+	try {
+		const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", moduleUrl)), "utf8")) as {
+			dependencies?: Record<string, unknown>;
+		};
+		const pinned = manifest.dependencies?.["@opencode/plugin"];
+		return typeof pinned === "string" && /^\d+\.\d+\.\d+/.test(pinned) ? pinned : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/lib/worktree.ts

@@ -197,6 +197,40 @@ export function createGitWorktree(
 	}
 }
 
+/**
+ * Validate a worktree directory the HOST created before the guard accepts it.
+ *
+ * The host is a widening authority only in the sense that it may choose the
+ * directory (its configured `worktree.directory`). It is never an authority
+ * that the directory is safe: the guard re-checks the filesystem and the git
+ * registration itself, and refuses the primary working tree. A host adapter
+ * that returns a bogus path therefore fails closed.
+ */
+export function validateHostWorktreeDirectory(
+	directory: string,
+	root = getWorkspaceRoot(),
+): { ok: boolean; error?: string } {
+	if (!directory || typeof directory !== "string") {
+		return { ok: false, error: "Host worktree create returned no directory." };
+	}
+	const resolved = resolve(directory);
+	if (!existsSync(resolved)) {
+		return { ok: false, error: `Host declared worktree '${directory}' does not exist.` };
+	}
+	const registered = registeredWorktreePaths(root);
+	if (!registered) {
+		return { ok: false, error: "Failed to list registered worktrees - cannot validate the host worktree." };
+	}
+	const resolvedRegistered = registered.map((path) => resolve(path));
+	if (!resolvedRegistered.includes(resolved)) {
+		return { ok: false, error: `Host declared worktree '${directory}' is not a registered worktree of this repository.` };
+	}
+	if (resolvedRegistered[0] === resolved) {
+		return { ok: false, error: "Host declared the primary working tree as a worktree - refusing." };
+	}
+	return { ok: true };
+}
+
 function registeredWorktreePaths(root: string): string[] | undefined {
 	const res = spawnSync("git", ["worktree", "list", "--porcelain"], {
 		cwd: root,
@@ -215,23 +249,37 @@ function registeredWorktreePaths(root: string): string[] | undefined {
 export function cleanupGitWorktree(
 	worktreePath: string,
 	root = getWorkspaceRoot(),
+	options?: {
+		/**
+		 * Directories the HOST declares as its worktrees for this project
+		 * (`ctx.worktree.list`). This is the only way cleanup may reach a
+		 * worktree outside the guard's own storage directory: the host is the
+		 * authority that the directory belongs to its inventory, and the
+		 * registration and primary-tree checks below still apply. Omitting the
+		 * list keeps the original storage-only behaviour.
+		 */
+		hostWorktrees?: readonly string[];
+	},
 ): { success: boolean; error?: string } {
 	try {
 		const resolved = resolve(worktreePath);
 		const storageBase = resolve(getWorktreeStorageDir(root));
+		const hostOwned = Boolean(options?.hostWorktrees?.some((path) => resolve(path) === resolved));
+		const withinStorage = resolved === storageBase || resolved.startsWith(storageBase + sep);
+		if (!withinStorage && !hostOwned) {
+			return {
+				success: false,
+				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}) and is not a host-declared worktree.`,
+			};
+		}
 		if (!existsSync(worktreePath)) {
 			// A registered worktree whose directory is gone (manual removal, a
 			// crashed add, external cleanup) still holds a stale admin entry that
 			// keeps it in `git worktree list` as prunable, and must still be
-			// cleanable. Anything outside storage or unregistered is refused.
-			// The primary working tree is never at risk: prune only removes
-			// admin dirs under .git/worktrees/<id>, which the main tree lacks.
-			if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
-				return {
-					success: false,
-					error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
-				};
-			}
+			// cleanable. Anything outside storage (unless the host declares it)
+			// or unregistered is refused. The primary working tree is never at
+			// risk: prune only removes admin dirs under .git/worktrees/<id>,
+			// which the main tree lacks.
 			const registeredMissing = registeredWorktreePaths(root);
 			if (!registeredMissing) {
 				return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
@@ -252,15 +300,10 @@ export function cleanupGitWorktree(
 		}
 
 		// Ownership validation: the path must live under the configured worktree
-		// storage directory AND be a registered worktree of this repository. This
-		// refuses arbitrary directories, other repos' worktrees, and the primary
-		// working tree - cleanup must never be an unrestricted delete primitive.
-		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
-			return {
-				success: false,
-				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
-			};
-		}
+		// storage directory (or be declared by the host) AND be a registered
+		// worktree of this repository. This refuses arbitrary directories, other
+		// repos' worktrees, and the primary working tree - cleanup must never be
+		// an unrestricted delete primitive.
 		const registered = registeredWorktreePaths(root);
 		if (!registered) {
 			return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };

package/src/policies/mcp.ts

@@ -3,7 +3,13 @@ export const MCP_MUTATION_VERB_RE =
 export const MCP_READ_ONLY_RE =
 	/(?:^|_)(?:get|list|search|show|query|describe|find|read|status|diff|log)(?:_|$)/;
 
-export const GUARDED_MCP_SERVERS = new Set([
+/**
+ * Static guarded live-system server tokens.
+ *
+ * These stay in force regardless of host inventory, because tool names are
+ * model-supplied text and the MCP policy is a live-system rail.
+ */
+export const GUARDED_MCP_SERVERS: ReadonlySet<string> = new Set([
 	"github",
 	"gh",
 	"azure",
@@ -13,12 +19,51 @@ export const GUARDED_MCP_SERVERS = new Set([
 	"azuredevops",
 ]);
 
+/**
+ * Tokens learned from the HOST's MCP inventory (`ctx.mcp.list()`), offered by
+ * `lib/mcp-inventory.ts` when a server connects or its tools change.
+ *
+ * Widen-only. A server the operator removed contributes nothing new, but the
+ * static defaults above are never narrowed, so removing a server cannot
+ * unguard a tool that still names it. Empty on hosts without the API, which
+ * leaves behaviour identical to the static list.
+ *
+ * Held on `globalThis` via `Symbol.for` because OpenCode can load the same
+ * package from two distinct module paths (a cache copy plus a source
+ * checkout), and each copy would otherwise get its own set.
+ */
+const HOST_GUARDED_MCP_TOKENS = Symbol.for("opencode-workflow-guard.mcp-tokens.v1");
+const tokenRegistry = globalThis as unknown as Record<symbol, Set<string> | undefined>;
+const hostGuardedMcpTokens: Set<string> =
+	tokenRegistry[HOST_GUARDED_MCP_TOKENS] ?? (tokenRegistry[HOST_GUARDED_MCP_TOKENS] = new Set());
+
+/** Register host-declared server tokens. Returns the tokens that were new. */
+export function addGuardedMcpTokens(tokens: Iterable<string>): string[] {
+	const added: string[] = [];
+	for (const token of tokens) {
+		const normalized = String(token).toLowerCase().trim();
+		if (!normalized || GUARDED_MCP_SERVERS.has(normalized) || hostGuardedMcpTokens.has(normalized)) continue;
+		hostGuardedMcpTokens.add(normalized);
+		added.push(normalized);
+	}
+	return added;
+}
+
+export function resetGuardedMcpTokensForTesting(): void {
+	hostGuardedMcpTokens.clear();
+}
+
+/** Effective guarded token set: static defaults plus host-declared widening. */
+export function guardedMcpServers(): ReadonlySet<string> {
+	return new Set([...GUARDED_MCP_SERVERS, ...hostGuardedMcpTokens]);
+}
+
 export function mcpMutationTool(toolName: string): string | undefined {
 	if (!MCP_MUTATION_VERB_RE.test(toolName) || MCP_READ_ONLY_RE.test(toolName)) {
 		return undefined;
 	}
 	const tokens = toolName.toLowerCase().split(/[^a-z0-9]+/);
-	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t))) {
+	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t) || hostGuardedMcpTokens.has(t))) {
 		return "GitHub/Azure DevOps";
 	}
 	return undefined;

package/src/policies/tamper.ts

@@ -11,7 +11,7 @@ export const PROTECTED_PATH_REASON =
 	"these manually in configuration or the UI.";
 
 const GT = String.fromCharCode(62);
-const V_LIST = ["sed\\s+-i", "tee", "mv", "cp", "rm", "chmod", "chown", "ln", "install", "truncate", "dd"].join("|");
+const V_LIST = ["sed\\s+-i", "tee", "mv", "cp", "rm", "chmod", "chown", "ln", "install", "truncate", "dd", "patch", "perl\\s+-[^\\s]*i"].join("|");
 const C_LIST = ["open" + "code\\.jsonc?", "\\.config\\/open" + "code", "\\.open" + "code\\/"].join("|");
 const U_LIST = ["\\.config\\/open" + "code\\/(?:plugins|ui)\\/"].join("|");
 

package/src/policies/todo.ts

@@ -1,5 +1,5 @@
 import type { TodoItem } from "../lib/types.ts";
-import { getSessionMutationCount, getSdkClient, getSubagentMutationBudget } from "../lib/state.ts";
+import { getSessionMutationCount, getSdkClient, getSubagentMutationBudget, todoTaskStarts } from "../lib/state.ts";
 
 export const EDIT_TOOL_NAMES = new Set(["edit", "write", "patch", "apply_patch"]);
 export const ACTIVE_TODO_STATUSES = new Set(["pending", "in_progress"]);
@@ -94,6 +94,221 @@ export function hasActiveTodo(todos: TodoItem[]): boolean {
 	return todos.some((todo) => ACTIVE_TODO_STATUSES.has(String(todo.status ?? "")));
 }
 
+/**
+ * Explicit read-only escape. A task whose text carries this marker completes
+ * without a mutation in its window. Every use is journaled, so an agent that
+ * marks real work read-only leaves a visible trail instead of passing silently.
+ */
+export const READ_ONLY_TODO_MARKER = /\[read[-_ ]?only\]/i;
+
+export function isReadOnlyTodo(todo: TodoItem): boolean {
+	return READ_ONLY_TODO_MARKER.test(String(todo.content ?? ""));
+}
+
+/**
+ * Task identity: trimmed content with the read-only marker removed.
+ *
+ * The marker is an annotation about a task, not part of which task it is. An
+ * agent that planned a task and only then discovers it is read-only appends the
+ * marker; that must not read as deleting one task and inventing another, or the
+ * documented remedy would be blocked by the no-silent-deletion rule. It also
+ * keeps the task's window, so annotating instead of re-planning loses nothing.
+ */
+export function todoTaskKey(todo: TodoItem): string {
+	return String(todo.content ?? "")
+		.replace(READ_ONLY_TODO_MARKER, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/** Raw task text, for messages the model has to match against its own list. */
+function todoTaskLabel(todo: TodoItem): string {
+	return String(todo.content ?? "").trim();
+}
+
+/**
+ * Record when each active task entered its current active window, in the
+ * session's mutation count. Completion evidence is judged against this.
+ *
+ * Call this only for a `todowrite` the guard allowed: a blocked write never
+ * becomes the task list, so it must not move a task's start.
+ */
+export function recordTodoTaskStarts(
+	starts: Map<string, number>,
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+	mutationCount: number,
+): void {
+	const previouslyActive = new Set<string>();
+	for (const todo of previousTodos ?? []) {
+		if (ACTIVE_TODO_STATUSES.has(String(todo.status ?? ""))) previouslyActive.add(todoTaskKey(todo));
+	}
+	const live = new Set<string>();
+	for (const todo of nextTodos) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (ACTIVE_TODO_STATUSES.has(String(todo.status ?? ""))) {
+			live.add(key);
+			// A task keeps its original window across rewrites and status
+			// changes within the active set. A task returning to active after
+			// finishing starts a fresh window.
+			if (!previouslyActive.has(key) || !starts.has(key)) starts.set(key, mutationCount);
+		}
+	}
+	// Finished or dropped tasks close their window; a later task with the
+	// same text starts clean instead of inheriting stale evidence.
+	for (const key of [...starts.keys()]) {
+		if (!live.has(key)) starts.delete(key);
+	}
+}
+
+/**
+ * Completion evidence, enforced: a task may not move to `completed` unless the
+ * session mutated at least once inside that task's active window. One mutation
+ * cannot vouch for several completions, so N completions need N mutations
+ * counted from the earliest of them.
+ *
+ * Read-only tasks are the documented escape: they carry `[read-only]` in their
+ * text and complete freely. Todos are still not authority on finalization; the
+ * verification gate remains the authority there.
+ *
+ * Tasks are matched to their prior occurrence by count, not by last-write-wins,
+ * so duplicate content cannot hide a new completion behind an already-completed
+ * item of the same text.
+ *
+ * Returns the tasks that still lack evidence. An empty list means the write may
+ * proceed.
+ */
+export function unverifiedTodoCompletions(
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+	starts: Map<string, number>,
+	mutationCount: number,
+): string[] {
+	// Each prior occurrence can absorb at most one new item of the same key. A
+	// prior `completed` occurrence absorbs a new `completed` item silently; any
+	// other prior occurrence leaves the new item as a fresh claim.
+	const absorbable = new Map<string, number>();
+	const absorbCompleted = new Map<string, number>();
+	for (const todo of previousTodos ?? []) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		absorbable.set(key, (absorbable.get(key) ?? 0) + 1);
+		if (String(todo.status ?? "") === "completed") {
+			absorbCompleted.set(key, (absorbCompleted.get(key) ?? 0) + 1);
+		}
+	}
+
+	const claimed: Array<{ task: string; start: number }> = [];
+	for (const todo of nextTodos) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (String(todo.status ?? "") !== "completed") continue;
+		const completedBefore = absorbCompleted.get(key) ?? 0;
+		if (completedBefore > 0) {
+			// An unchanged completed item, not a new claim.
+			absorbCompleted.set(key, completedBefore - 1);
+			const remaining = absorbable.get(key) ?? 0;
+			if (remaining > 0) absorbable.set(key, remaining - 1);
+			continue;
+		}
+		const remaining = absorbable.get(key) ?? 0;
+		if (remaining > 0) absorbable.set(key, remaining - 1);
+		if (isReadOnlyTodo(todo)) continue;
+		claimed.push({ task: todoTaskLabel(todo), start: starts.get(key) ?? 0 });
+	}
+
+	if (claimed.length === 0) return [];
+	// Each completion needs its own distinct mutation inside its own window.
+	// Checking only the earliest start would let mutations spent before a later
+	// task began vouch for it. Sorted by window start, a claim can only be
+	// satisfied if the window from that point still holds at least one mutation
+	// per remaining claim; the first failure marks an infeasible suffix, since
+	// every task after it has an equal or narrower window.
+	claimed.sort((a, b) => a.start - b.start);
+	for (let index = 0; index < claimed.length; index++) {
+		const remainingClaims = claimed.length - index;
+		if (mutationCount - claimed[index]!.start < remainingClaims) {
+			return claimed.slice(index).map((claim) => claim.task);
+		}
+	}
+	return [];
+}
+
+export function readOnlyTodoCompletions(
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+): string[] {
+	// Count prior occurrences by key and how many were already completed. An
+	// item carrying the marker is journaled when it is a new completion, which
+	// includes the common case of annotating an already-planned task.
+	const completedBefore = new Map<string, number>();
+	for (const todo of previousTodos ?? []) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (String(todo.status ?? "") === "completed") completedBefore.set(key, (completedBefore.get(key) ?? 0) + 1);
+	}
+	const readOnly: string[] = [];
+	for (const todo of nextTodos) {
+		if (String(todo.status ?? "") !== "completed" || !isReadOnlyTodo(todo)) continue;
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		const unchanged = completedBefore.get(key) ?? 0;
+		if (unchanged > 0) {
+			completedBefore.set(key, unchanged - 1);
+			continue;
+		}
+		readOnly.push(todoTaskLabel(todo));
+	}
+	return readOnly;
+}
+
+export function todoCompletionBlockReason(blocked: string[]): string {
+	const tasks = blocked.map((task) => `'${task}'`).join(", ");
+	return (
+		`Blocked todowrite: ${blocked.length === 1 ? "task" : "tasks"} ${tasks} marked completed without enough recorded work in the task window. ` +
+		"Complete the task's work first, then mark it completed. " +
+		"If the task was genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text and mark it completed. " +
+		"Use `cancelled` for work that was deliberately dropped."
+	);
+}
+
+/**
+ * Read-only view of a session's task evidence, for `guard_status`. Reports what
+ * the completion gate would decide now, so the requirement is visible before it
+ * blocks anything.
+ */
+export async function todoEvidenceReport(sessionID: string | undefined): Promise<{
+	active: number;
+	completed: number;
+	tasksWithoutRecordedWork: string[];
+	readOnlyTasks: string[];
+}> {
+	if (!sessionID) return { active: 0, completed: 0, tasksWithoutRecordedWork: [], readOnlyTasks: [] };
+	const todos = await effectiveTodos(sessionID);
+	if (!todos) return { active: 0, completed: 0, tasksWithoutRecordedWork: [], readOnlyTasks: [] };
+	const starts = todoTaskStarts(sessionID);
+	const count = getSessionMutationCount(sessionID);
+	const active = todos.filter((todo) => ACTIVE_TODO_STATUSES.has(String(todo.status ?? "")));
+	const tasksWithoutRecordedWork: string[] = [];
+	const readOnlyTasks: string[] = [];
+	for (const todo of active) {
+		const label = todoTaskLabel(todo);
+		if (!label) continue;
+		if (isReadOnlyTodo(todo)) {
+			readOnlyTasks.push(label);
+			continue;
+		}
+		if (count <= (starts.get(todoTaskKey(todo)) ?? 0)) tasksWithoutRecordedWork.push(label);
+	}
+	return {
+		active: active.length,
+		completed: todos.filter((todo) => String(todo.status ?? "") === "completed").length,
+		tasksWithoutRecordedWork,
+		readOnlyTasks,
+	};
+}
+
 export function validateTodoLifecycle(
 	newTodos: TodoItem[],
 	existingTodos: TodoItem[] | undefined,
@@ -115,26 +330,26 @@ export function validateTodoLifecycle(
 			const isReviewObligation = (content: string) => reviewObligation.test(content) && !(remediationAction.test(content) && reviewReference.test(content) && remediationSubject.test(content));
 			const newContentCounts = new Map<string, number>();
 			for (const todo of newTodos) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				newContentCounts.set(content, (newContentCounts.get(content) ?? 0) + 1);
 			}
 			const retainedReviewCounts = new Map<string, number>();
 			for (const todo of activeNew) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				retainedReviewCounts.set(content, (retainedReviewCounts.get(content) ?? 0) + 1);
 			}
 			let retainedReviewObligations = 0;
 			for (const todo of activeExisting) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				const remaining = retainedReviewCounts.get(content) ?? 0;
 				if (remaining > 0 && isReviewObligation(content)) {
 					retainedReviewCounts.set(content, remaining - 1);
 					retainedReviewObligations++;
 				}
 			}
-			let replacementReviewObligations = activeNew.filter((t) => isReviewObligation(String(t.content ?? ""))).length - retainedReviewObligations;
+			let replacementReviewObligations = activeNew.filter((t) => isReviewObligation(todoTaskKey(t))).length - retainedReviewObligations;
 			const missing = activeExisting.find((todo) => {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				const remaining = newContentCounts.get(content) ?? 0;
 				if (remaining === 0 && isReviewObligation(content) && replacementReviewObligations > 0) {
 					replacementReviewObligations--;