pi-crew 0.1.43 → 0.1.45

package/src/runtime/completion-guard.ts

@@ -1,4 +1,10 @@
 import * as fs from "node:fs";
+import type { TeamTaskState, TeamRunManifest } from "../state/types.ts";
+
+// ============================================================================
+// Phase 1.2: Completion Mutation Guard — detects tasks that claim success but
+// made no observable mutations. Used by task-runner.ts.
+// ============================================================================
 
 export interface CompletionMutationGuardInput {
 	role: string;
@@ -101,3 +107,84 @@ export function evaluateCompletionMutationGuard(input: CompletionMutationGuardIn
 		...(expectedMutation && !observedMutation ? { reason: "no_mutation_observed" as const } : {}),
 	};
 }
+
+// ============================================================================
+// Phase 11a: Artifact-based Completion Verification — a second layer that
+// checks whether a completed task actually produced meaningful artifacts.
+// ============================================================================
+
+/**
+ * Guard against false-positive task completions.
+ *
+ * Checks whether a task that claims success actually produced meaningful output.
+ * Returns a verification result with the green level (0-3) and any warnings.
+ */
+export interface CompletionVerifyResult {
+	/** 0 = no output, 1 = minimal, 2 = moderate, 3 = strong */
+	greenLevel: number;
+	/** Warnings about potentially incomplete work */
+	warnings: string[];
+}
+
+const MAX_OUTPUT_PREVIEW = 200;
+
+function isTrivialError(error: string | undefined): boolean {
+	if (!error) return false;
+	return error.trim().length === 0;
+}
+
+export function verifyTaskCompletion(
+	task: TeamTaskState,
+	manifest: TeamRunManifest,
+): CompletionVerifyResult {
+	const warnings: string[] = [];
+	let greenLevel = 0;
+
+	// Check 1: Has an error?
+	if (task.error && !isTrivialError(task.error)) {
+		return { greenLevel: 0, warnings: [`Task has error: ${task.error}`] };
+	}
+
+	// Check 2: Has result artifact?
+	if (task.resultArtifact) {
+		greenLevel += 1;
+	}
+
+	// Check 3: Has transcript?
+	if (task.transcriptArtifact) {
+		greenLevel += 1;
+	}
+
+	// Check 4: For implementation tasks, verify artifacts were actually produced
+	const runArtifacts = manifest.artifacts.filter(
+		(a) => a.producer === task.id || a.producer === task.agent,
+	);
+	if (runArtifacts.length > 0) {
+		greenLevel += 1;
+	} else if (greenLevel < 3) {
+		warnings.push("No run-level artifacts produced by this task");
+	}
+
+	// Check 5: Usage tracking — did the task actually consume tokens?
+	if (task.usage) {
+		const totalTokens = (task.usage.input ?? 0) + (task.usage.output ?? 0);
+		if (totalTokens === 0 && greenLevel < 3) {
+			warnings.push("Task reports zero token usage — may not have executed");
+		}
+	}
+
+	return {
+		greenLevel: Math.min(greenLevel, 3),
+		warnings,
+	};
+}
+
+/**
+ * Format a preview of task output for diagnostic display.
+ */
+export function formatOutputPreview(output: string | undefined): string {
+	if (!output) return "(no output)";
+	const trimmed = output.trim();
+	if (trimmed.length <= MAX_OUTPUT_PREVIEW) return trimmed;
+	return trimmed.slice(0, MAX_OUTPUT_PREVIEW) + "...";
+}

package/src/runtime/crash-recovery.ts

@@ -1,11 +1,13 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { appendEvent, scanSequence } from "../state/event-log.ts";
+import { withRunLockSync } from "../state/locks.ts";
 import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
 import type { ManifestCache } from "./manifest-cache.ts";
 import { checkProcessLiveness } from "./process-status.ts";
+import { reconcileStaleRun, type ReconcileResult } from "./stale-reconciler.ts";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -55,3 +57,31 @@ export function declineRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionConte
 	appendEvent(loaded.manifest.eventsPath, { type: "crew.run.recovery_declined", runId: plan.runId, message: "Interrupted run was not resumed.", data: { recoveredFromSeq: plan.lastEventSeq } });
 	updateRunStatus(loaded.manifest, "cancelled", "interrupted-not-resumed");
 }
+
+/**
+ * Run 3-phase stale reconciliation on all active runs.
+ * Returns results for each reconciled run.
+ */
+export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache, now = Date.now()): ReconcileResult[] {
+	const results: ReconcileResult[] = [];
+	for (const manifest of manifestCache.list(50)) {
+		if (manifest.status !== "running") continue;
+		const loaded = loadRunManifestById(cwd, manifest.runId);
+		if (!loaded) continue;
+		// Use lock to prevent race with cancel/status handlers modifying the same run
+		withRunLockSync(loaded.manifest, () => {
+			// Re-read inside lock to get freshest data
+			const fresh = loadRunManifestById(cwd, manifest.runId);
+			if (!fresh || fresh.manifest.status !== "running") return;
+			const result = reconcileStaleRun(fresh.manifest, fresh.tasks, now);
+			if (result.repaired) {
+				updateRunStatus(fresh.manifest, "failed", `Stale run reconciled: ${result.detail}`);
+				appendEvent(fresh.manifest.eventsPath, { type: "crew.run.reconciled_stale", runId: manifest.runId, message: result.detail, data: { verdict: result.verdict } });
+			}
+			if (result.verdict !== "healthy") {
+				results.push(result);
+			}
+		});
+	}
+	return results;
+}

package/src/runtime/crew-agent-records.ts

@@ -70,6 +70,14 @@ export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
 	}
 }
 
+export async function readCrewAgentsAsync(manifest: TeamRunManifest): Promise<CrewAgentRecord[]> {
+	try {
+		return JSON.parse(await fs.promises.readFile(agentsPath(manifest), "utf-8")) as CrewAgentRecord[];
+	} catch {
+		return [];
+	}
+}
+
 export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
 	atomicWriteJson(agentsPath(manifest), redactSecrets(records));

package/src/runtime/crew-agent-runtime.ts

@@ -2,7 +2,7 @@ import type { TeamTaskStatus } from "../state/contracts.ts";
 import type { CrewActivityState, ModelRoutingState, UsageState } from "../state/types.ts";
 
 export type CrewRuntimeKind = "scaffold" | "child-process" | "live-session";
-export type CrewAgentStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "stopped";
+export type CrewAgentStatus = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "stopped";
 
 export interface CrewAgentRecentTool {
 	tool: string;
@@ -54,5 +54,6 @@ export function taskStatusToAgentStatus(status: TeamTaskStatus): CrewAgentStatus
 	if (status === "failed") return "failed";
 	if (status === "cancelled" || status === "skipped") return "cancelled";
 	if (status === "running") return "running";
+	if (status === "waiting") return "waiting";
 	return "queued";
 }

package/src/runtime/delivery-coordinator.ts

@@ -0,0 +1,154 @@
+import type { NotificationDescriptor } from "../extension/notification-router.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface PendingDelivery {
+	runId: string;
+	payload: unknown;
+	timestamp: number;
+	type: "result" | "notification" | "steer";
+	generation?: number;
+}
+
+export interface DeliveryCoordinatorDeps {
+	/** Emit an event to the active Pi event bus. */
+	emit?: (event: string, data: unknown) => void;
+	/** Send a follow-up message to the active session (for notifications). */
+	sendFollowUp?: (title: string, body: string) => void;
+	/** Send a wake-up message to the active session (for async results). */
+	sendWakeUp?: (message: string) => void;
+}
+
+const PENDING_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+export class DeliveryCoordinator {
+	private ownerSessionId: string | undefined;
+	private active = false;
+	private generation = 0;
+	private pending: PendingDelivery[] = [];
+	private readonly deps: DeliveryCoordinatorDeps;
+	private ttlTimer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(deps: DeliveryCoordinatorDeps) {
+		this.deps = deps;
+		this.ttlTimer = setInterval(() => this.evictExpired(), 60_000);
+		this.ttlTimer.unref();
+	}
+
+	activate(sessionId: string): void {
+		this.ownerSessionId = sessionId;
+		this.active = true;
+		this.flushQueuedResults();
+	}
+
+	deactivate(): void {
+		this.active = false;
+		this.ownerSessionId = undefined;
+		this.generation += 1;
+	}
+
+	isActive(): boolean {
+		return this.active;
+	}
+
+	getPendingCount(): number {
+		return this.pending.length;
+	}
+
+	deliverResult(runId: string, result: unknown): void {
+		if (this.active && this.deps.emit) {
+			try {
+				this.deps.emit("pi-crew:run-result", result);
+				return;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverResult", error, `runId=${runId}`);
+			}
+		}
+		this.enqueue({ runId, payload: result, timestamp: Date.now(), type: "result" });
+	}
+
+	deliverNotification(notification: NotificationDescriptor): void {
+		let delivered = false;
+		if (this.active && this.deps.sendFollowUp) {
+			try {
+				this.deps.sendFollowUp(notification.title, notification.body ?? "");
+				delivered = true;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverNotification", error, `id=${notification.id}`);
+			}
+		}
+		if (delivered) {
+			if (this.deps.emit) {
+				try {
+					this.deps.emit("pi-crew:notification", notification);
+				} catch { /* secondary delivery, ignore errors */ }
+			}
+			return;
+		}
+		this.enqueue({ runId: notification.runId ?? "", payload: notification, timestamp: Date.now(), type: "notification" });
+	}
+
+	deliverSteer(runId: string, message: string): void {
+		if (this.active && this.deps.sendWakeUp) {
+			try {
+				this.deps.sendWakeUp(message);
+				return;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverSteer", error, `runId=${runId}`);
+			}
+		}
+		this.enqueue({ runId, payload: message, timestamp: Date.now(), type: "steer" });
+	}
+
+	flushQueuedResults(): void {
+		if (!this.active || this.pending.length === 0) return;
+		const batch = this.pending.splice(0);
+		for (const delivery of batch) {
+			if (delivery.generation !== undefined && delivery.generation !== this.generation) {
+				logInternalError("delivery-coordinator.flush.stale", undefined, `runId=${delivery.runId} type=${delivery.type}`);
+				continue;
+			}
+			try {
+				switch (delivery.type) {
+					case "result":
+						this.deliverResult(delivery.runId, delivery.payload);
+						break;
+					case "notification": {
+						const notification = delivery.payload as NotificationDescriptor;
+						this.deliverNotification(notification);
+						break;
+					}
+					case "steer": {
+						const message = typeof delivery.payload === "string" ? delivery.payload : String(delivery.payload);
+						this.deliverSteer(delivery.runId, message);
+						break;
+					}
+				}
+			} catch (error) {
+				logInternalError("delivery-coordinator.flush", error, `runId=${delivery.runId} type=${delivery.type}`);
+			}
+		}
+	}
+
+	dispose(): void {
+		this.deactivate();
+		this.pending.length = 0;
+		if (this.ttlTimer) {
+			clearInterval(this.ttlTimer);
+			this.ttlTimer = undefined;
+		}
+	}
+
+	private enqueue(delivery: PendingDelivery): void {
+		this.pending.push({ ...delivery, generation: this.generation });
+	}
+
+	private evictExpired(): void {
+		const cutoff = Date.now() - PENDING_TTL_MS;
+		const before = this.pending.length;
+		this.pending = this.pending.filter((d) => d.timestamp > cutoff);
+		const evicted = before - this.pending.length;
+		if (evicted > 0) {
+			logInternalError("delivery-coordinator.evict", undefined, `evicted=${evicted} remaining=${this.pending.length}`);
+		}
+	}
+}

package/src/runtime/direct-run.ts

@@ -1,35 +1,35 @@
-import type { AgentConfig } from "../agents/agent-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import type { TeamConfig } from "../teams/team-config.ts";
-import type { WorkflowConfig } from "../workflows/workflow-config.ts";
-
-export function isDirectRun(manifest: Pick<TeamRunManifest, "team" | "workflow">): boolean {
-	return manifest.workflow === "direct-agent";
-}
-
-export function directTeamAndWorkflowFromRun(manifest: TeamRunManifest, tasks: TeamTaskState[], agents: AgentConfig[]): { team: TeamConfig; workflow: WorkflowConfig } | undefined {
-	if (!isDirectRun(manifest)) return undefined;
-	const firstTask = tasks[0];
-	const agentName = firstTask?.agent ?? (manifest.team.replace(/^direct-/, "") || "executor");
-	const agent = agents.find((candidate) => candidate.name === agentName);
-	const role = firstTask?.role ?? "agent";
-	const stepId = firstTask?.stepId ?? "01_agent";
-	return {
-		team: {
-			name: manifest.team,
-			description: `Direct subagent run for ${agentName}`,
-			source: "builtin",
-			filePath: "<generated>",
-			roles: [{ name: role, agent: agentName, description: agent?.description }],
-			defaultWorkflow: "direct-agent",
-			workspaceMode: manifest.workspaceMode,
-		},
-		workflow: {
-			name: manifest.workflow ?? "direct-agent",
-			description: `Direct task for ${agentName}`,
-			source: "builtin",
-			filePath: "<generated>",
-			steps: [{ id: stepId, role, task: "{goal}", model: firstTask?.model }],
-		},
-	};
-}
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+
+export function isDirectRun(manifest: Pick<TeamRunManifest, "team" | "workflow">): boolean {
+	return manifest.workflow === "direct-agent";
+}
+
+export function directTeamAndWorkflowFromRun(manifest: TeamRunManifest, tasks: TeamTaskState[], agents: AgentConfig[]): { team: TeamConfig; workflow: WorkflowConfig } | undefined {
+	if (!isDirectRun(manifest)) return undefined;
+	const firstTask = tasks[0];
+	const agentName = firstTask?.agent ?? (manifest.team.replace(/^direct-/, "") || "executor");
+	const agent = agents.find((candidate) => candidate.name === agentName);
+	const role = firstTask?.role ?? "agent";
+	const stepId = firstTask?.stepId ?? "01_agent";
+	return {
+		team: {
+			name: manifest.team,
+			description: `Direct subagent run for ${agentName}`,
+			source: "builtin",
+			filePath: "<generated>",
+			roles: [{ name: role, agent: agentName, description: agent?.description }],
+			defaultWorkflow: "direct-agent",
+			workspaceMode: manifest.workspaceMode,
+		},
+		workflow: {
+			name: manifest.workflow ?? "direct-agent",
+			description: `Direct task for ${agentName}`,
+			source: "builtin",
+			filePath: "<generated>",
+			steps: [{ id: stepId, role, task: "{goal}", model: firstTask?.model }],
+		},
+	};
+}

package/src/runtime/foreground-control.ts

@@ -1,82 +1,82 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { appendEvent } from "../state/event-log.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { checkProcessLiveness, isActiveRunStatus } from "./process-status.ts";
-import { readCrewAgents } from "./crew-agent-records.ts";
-
-export type ForegroundControlRequestType = "interrupt" | "status";
-
-export interface ForegroundControlStatus {
-	runId: string;
-	status: TeamRunManifest["status"];
-	active: boolean;
-	asyncPid?: number;
-	asyncAlive?: boolean;
-	runningTasks: string[];
-	runningAgents: string[];
-	controlPath: string;
-	lastRequest?: ForegroundControlRequest;
-}
-
-export interface ForegroundControlRequest {
-	id: string;
-	type: ForegroundControlRequestType;
-	createdAt: string;
-	reason: string;
-	acknowledged: boolean;
-}
-
-export function foregroundControlPath(manifest: TeamRunManifest): string {
-	return path.join(manifest.stateRoot, "foreground-control.json");
-}
-
-function readLastRequest(controlPath: string): ForegroundControlRequest | undefined {
-	if (!fs.existsSync(controlPath)) return undefined;
-	try {
-		const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
-		return parsed.requests?.at(-1);
-	} catch {
-		return undefined;
-	}
-}
-
-export function readForegroundControlStatus(manifest: TeamRunManifest, tasks: TeamTaskState[]): ForegroundControlStatus {
-	const controlPath = foregroundControlPath(manifest);
-	const asyncAlive = manifest.async?.pid !== undefined ? checkProcessLiveness(manifest.async.pid).alive : undefined;
-	return {
-		runId: manifest.runId,
-		status: manifest.status,
-		active: isActiveRunStatus(manifest.status),
-		asyncPid: manifest.async?.pid,
-		asyncAlive,
-		runningTasks: tasks.filter((task) => task.status === "running").map((task) => task.id),
-		runningAgents: readCrewAgents(manifest).filter((agent) => agent.status === "running").map((agent) => agent.id),
-		controlPath,
-		lastRequest: readLastRequest(controlPath),
-	};
-}
-
-export function writeForegroundInterruptRequest(manifest: TeamRunManifest, reason = "User requested foreground interrupt."): ForegroundControlRequest {
-	const controlPath = foregroundControlPath(manifest);
-	let requests: ForegroundControlRequest[] = [];
-	if (fs.existsSync(controlPath)) {
-		try {
-			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
-			requests = Array.isArray(parsed.requests) ? parsed.requests : [];
-		} catch {
-			requests = [];
-		}
-	}
-	const request: ForegroundControlRequest = {
-		id: `fg_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`,
-		type: "interrupt",
-		createdAt: new Date().toISOString(),
-		reason,
-		acknowledged: false,
-	};
-	fs.mkdirSync(path.dirname(controlPath), { recursive: true });
-	fs.writeFileSync(controlPath, `${JSON.stringify({ requests: [...requests, request] }, null, 2)}\n`, "utf-8");
-	appendEvent(manifest.eventsPath, { type: "foreground.interrupt_requested", runId: manifest.runId, message: reason, data: { requestId: request.id, controlPath } });
-	return request;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { checkProcessLiveness, isActiveRunStatus } from "./process-status.ts";
+import { readCrewAgents } from "./crew-agent-records.ts";
+
+export type ForegroundControlRequestType = "interrupt" | "status";
+
+export interface ForegroundControlStatus {
+	runId: string;
+	status: TeamRunManifest["status"];
+	active: boolean;
+	asyncPid?: number;
+	asyncAlive?: boolean;
+	runningTasks: string[];
+	runningAgents: string[];
+	controlPath: string;
+	lastRequest?: ForegroundControlRequest;
+}
+
+export interface ForegroundControlRequest {
+	id: string;
+	type: ForegroundControlRequestType;
+	createdAt: string;
+	reason: string;
+	acknowledged: boolean;
+}
+
+export function foregroundControlPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "foreground-control.json");
+}
+
+function readLastRequest(controlPath: string): ForegroundControlRequest | undefined {
+	if (!fs.existsSync(controlPath)) return undefined;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+		return parsed.requests?.at(-1);
+	} catch {
+		return undefined;
+	}
+}
+
+export function readForegroundControlStatus(manifest: TeamRunManifest, tasks: TeamTaskState[]): ForegroundControlStatus {
+	const controlPath = foregroundControlPath(manifest);
+	const asyncAlive = manifest.async?.pid !== undefined ? checkProcessLiveness(manifest.async.pid).alive : undefined;
+	return {
+		runId: manifest.runId,
+		status: manifest.status,
+		active: isActiveRunStatus(manifest.status),
+		asyncPid: manifest.async?.pid,
+		asyncAlive,
+		runningTasks: tasks.filter((task) => task.status === "running").map((task) => task.id),
+		runningAgents: readCrewAgents(manifest).filter((agent) => agent.status === "running").map((agent) => agent.id),
+		controlPath,
+		lastRequest: readLastRequest(controlPath),
+	};
+}
+
+export function writeForegroundInterruptRequest(manifest: TeamRunManifest, reason = "User requested foreground interrupt."): ForegroundControlRequest {
+	const controlPath = foregroundControlPath(manifest);
+	let requests: ForegroundControlRequest[] = [];
+	if (fs.existsSync(controlPath)) {
+		try {
+			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+			requests = Array.isArray(parsed.requests) ? parsed.requests : [];
+		} catch {
+			requests = [];
+		}
+	}
+	const request: ForegroundControlRequest = {
+		id: `fg_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`,
+		type: "interrupt",
+		createdAt: new Date().toISOString(),
+		reason,
+		acknowledged: false,
+	};
+	fs.mkdirSync(path.dirname(controlPath), { recursive: true });
+	fs.writeFileSync(controlPath, `${JSON.stringify({ requests: [...requests, request] }, null, 2)}\n`, "utf-8");
+	appendEvent(manifest.eventsPath, { type: "foreground.interrupt_requested", runId: manifest.runId, message: reason, data: { requestId: request.id, controlPath } });
+	return request;
+}

package/src/runtime/green-contract.ts

@@ -1,46 +1,46 @@
-import type { GreenLevel, VerificationContract, VerificationEvidence } from "../state/types.ts";
-
-const GREEN_ORDER: Record<GreenLevel, number> = {
-	none: 0,
-	targeted: 1,
-	package: 2,
-	workspace: 3,
-	merge_ready: 4,
-};
-
-export interface GreenContractOutcome {
-	requiredGreenLevel: GreenLevel;
-	observedGreenLevel: GreenLevel;
-	satisfied: boolean;
-}
-
-export function greenLevelSatisfies(observed: GreenLevel, required: GreenLevel): boolean {
-	return GREEN_ORDER[observed] >= GREEN_ORDER[required];
-}
-
-export function evaluateGreenContract(contract: VerificationContract, evidence?: VerificationEvidence): GreenContractOutcome {
-	const observedGreenLevel = evidence?.observedGreenLevel ?? "none";
-	return {
-		requiredGreenLevel: contract.requiredGreenLevel,
-		observedGreenLevel,
-		satisfied: greenLevelSatisfies(observedGreenLevel, contract.requiredGreenLevel),
-	};
-}
-
-export function inferGreenLevelFromTask(success: boolean, contract: VerificationContract): GreenLevel {
-	if (!success) return "none";
-	if (contract.requiredGreenLevel === "none") return "none";
-	return contract.allowManualEvidence ? contract.requiredGreenLevel : "targeted";
-}
-
-export function createVerificationEvidence(contract: VerificationContract, success: boolean, notes: string): VerificationEvidence {
-	const observedGreenLevel = inferGreenLevelFromTask(success, contract);
-	const outcome = evaluateGreenContract(contract, { requiredGreenLevel: contract.requiredGreenLevel, observedGreenLevel, satisfied: false, commands: [], notes });
-	return {
-		requiredGreenLevel: contract.requiredGreenLevel,
-		observedGreenLevel,
-		satisfied: outcome.satisfied,
-		commands: contract.commands.map((cmd) => ({ cmd, status: "not_run" as const })),
-		notes,
-	};
-}
+import type { GreenLevel, VerificationContract, VerificationEvidence } from "../state/types.ts";
+
+const GREEN_ORDER: Record<GreenLevel, number> = {
+	none: 0,
+	targeted: 1,
+	package: 2,
+	workspace: 3,
+	merge_ready: 4,
+};
+
+export interface GreenContractOutcome {
+	requiredGreenLevel: GreenLevel;
+	observedGreenLevel: GreenLevel;
+	satisfied: boolean;
+}
+
+export function greenLevelSatisfies(observed: GreenLevel, required: GreenLevel): boolean {
+	return GREEN_ORDER[observed] >= GREEN_ORDER[required];
+}
+
+export function evaluateGreenContract(contract: VerificationContract, evidence?: VerificationEvidence): GreenContractOutcome {
+	const observedGreenLevel = evidence?.observedGreenLevel ?? "none";
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: greenLevelSatisfies(observedGreenLevel, contract.requiredGreenLevel),
+	};
+}
+
+export function inferGreenLevelFromTask(success: boolean, contract: VerificationContract): GreenLevel {
+	if (!success) return "none";
+	if (contract.requiredGreenLevel === "none") return "none";
+	return contract.allowManualEvidence ? contract.requiredGreenLevel : "targeted";
+}
+
+export function createVerificationEvidence(contract: VerificationContract, success: boolean, notes: string): VerificationEvidence {
+	const observedGreenLevel = inferGreenLevelFromTask(success, contract);
+	const outcome = evaluateGreenContract(contract, { requiredGreenLevel: contract.requiredGreenLevel, observedGreenLevel, satisfied: false, commands: [], notes });
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: outcome.satisfied,
+		commands: contract.commands.map((cmd) => ({ cmd, status: "not_run" as const })),
+		notes,
+	};
+}