pi-crew 0.1.49 → 0.2.0

package/src/runtime/child-pi.ts

@@ -8,7 +8,7 @@ import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { DEFAULT_CHILD_PI } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
-import { redactJsonLine } from "../utils/redaction.ts";
+import { redactJsonLine, SECRET_KEY_PATTERN } from "../utils/redaction.ts";
 
 const POST_EXIT_STDIO_GUARD_MS = DEFAULT_CHILD_PI.postExitStdioGuardMs;
 const FINAL_DRAIN_MS = DEFAULT_CHILD_PI.finalDrainMs;
@@ -110,9 +110,14 @@ export interface ChildPiRunResult {
 }
 
 export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
+	// Filter out env vars whose keys match secret patterns to avoid leaking credentials to child processes
+	const filteredEnv: Record<string, string> = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (value !== undefined && !SECRET_KEY_PATTERN.test(key)) filteredEnv[key] = value;
+	}
 	return {
 		cwd,
-		env: { ...env, PI_CREW_PARENT_PID: String(process.pid) },
+		env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
 		stdio: ["ignore", "pipe", "pipe"],
 		detached: process.platform !== "win32",
 		windowsHide: true,

package/src/runtime/compaction-summary.ts

@@ -0,0 +1,271 @@
+/**
+ * Deterministic compaction summary — builds a markdown summary of a pi-crew run
+ * from manifest.json, tasks.json, and the tail of events.jsonl.
+ *
+ * Distilled from pi-autoresearch's compaction-summary pattern.
+ */
+
+class GiantLineFallbackError extends Error { constructor() { super("GIANT_LINE_FALLBACK"); this.name = "GiantLineFallbackError"; } }
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { readJsonFile } from "../state/atomic-write.ts";
+import type { TeamEvent } from "../state/event-log.ts";
+
+/** Maximum number of events to read from the tail of events.jsonl. */
+const MAX_TAIL_EVENTS = 100;
+
+/** Maximum number of completed tasks to include in the "Recent Results" section. */
+const MAX_RECENT_RESULTS = 10;
+
+/** Paths relevant to building a compaction summary for a run. */
+export interface SummaryPaths {
+	manifestPath: string;
+	tasksPath: string;
+	eventsPath: string;
+	stateRoot: string;
+}
+
+/**
+ * Derive the standard summary-relevant paths from a state root directory.
+ * Mirrors pi-autoresearch's `autoresearchSummaryPathsFor()`.
+ */
+export function summaryPathsFor(stateRoot: string): SummaryPaths {
+	return {
+		stateRoot,
+		manifestPath: path.join(stateRoot, "manifest.json"),
+		tasksPath: path.join(stateRoot, "tasks.json"),
+		eventsPath: path.join(stateRoot, "events.jsonl"),
+	};
+}
+
+/**
+ * Read the last N lines from a text file.
+ * Uses reverse buffer reading to avoid loading the entire file into memory.
+ * For files larger than TAIL_MAX_READ bytes, only the last chunk is read.
+ */
+const TAIL_MAX_READ = 256 * 1024; // 256KB — enough for ~1000 lines of JSONL
+const MAX_FALLBACK_READ = 2 * 1024 * 1024; // 2MB — safety limit for giant-line fallback
+function readTailLines(filePath: string, maxLines: number): string[] {
+	if (!fs.existsSync(filePath)) return [];
+	try {
+		const stat = fs.statSync(filePath);
+		const fileSize = stat.size;
+		if (fileSize === 0) return [];
+
+		// For small files, just read everything
+		if (fileSize <= TAIL_MAX_READ) {
+			const content = fs.readFileSync(filePath, "utf-8");
+			return content.split("\n").filter((line) => line.trim().length > 0).slice(-maxLines);
+		}
+
+		// For large files, read only the last chunk.
+		// Search backwards from the read boundary for a newline to avoid
+		// splitting mid-line or mid-multibyte UTF-8 character.
+		const fd = fs.openSync(filePath, "r");
+		try {
+			const readSize = Math.min(fileSize, TAIL_MAX_READ);
+			const readOffset = fileSize - readSize;
+			const buf = Buffer.alloc(readSize);
+			fs.readSync(fd, buf, 0, readSize, readOffset);
+
+			// Find the first newline in the buffer to avoid partial lines.
+			// This also handles multibyte UTF-8 safety — we start after a
+			// newline boundary which is always a clean character boundary.
+			let start = 0;
+			if (readOffset > 0) {
+				const firstNewline = buf.indexOf("\n");
+				if (firstNewline >= 0) {
+					start = firstNewline + 1;
+				} else {
+					// No newline found in the entire tail chunk — single giant line.
+					// Fall back to reading the full file to avoid data loss.
+					// Note: fd will be closed by the outer finally block.
+					throw new GiantLineFallbackError();
+				}
+			}
+
+			const content = buf.toString("utf-8", start, readSize);
+			const lines = content.split("\n").filter((line) => line.trim().length > 0);
+			return lines.slice(-maxLines);
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch (err) {
+		// Giant-line fallback: fd already closed by finally above.
+		if (err instanceof GiantLineFallbackError) {
+			const stat = fs.statSync(filePath);
+			if (stat.size > MAX_FALLBACK_READ) return [];
+			const content = fs.readFileSync(filePath, "utf-8");
+			return content.split("\n").filter((line) => line.trim().length > 0).slice(-maxLines);
+		}
+		return [];
+	}
+}
+
+/**
+ * Parse JSONL lines into TeamEvent objects, skipping malformed lines.
+ */
+function parseEvents(lines: string[]): TeamEvent[] {
+	const events: TeamEvent[] = [];
+	for (const line of lines) {
+		try {
+			const parsed = JSON.parse(line.trim());
+			if (typeof parsed === "object" && parsed !== null && typeof parsed.type === "string" && typeof parsed.runId === "string") {
+				events.push(parsed as TeamEvent);
+			}
+		} catch {
+			// Skip malformed lines
+		}
+	}
+	return events;
+}
+
+/**
+ * Compute a human-readable duration between two ISO timestamp strings.
+ */
+function formatDuration(startIso?: string, endIso?: string): string {
+	if (!startIso) return "—";
+	const start = new Date(startIso).getTime();
+	if (Number.isNaN(start)) return "—";
+	const end = endIso ? new Date(endIso).getTime() : Date.now();
+	if (Number.isNaN(end)) return "—";
+	const diffMs = end - start;
+	if (diffMs < 0) return "—";
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const remainingSeconds = seconds % 60;
+	if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
+	const hours = Math.floor(minutes / 60);
+	const remainingMinutes = minutes % 60;
+	return `${hours}h ${remainingMinutes}m`;
+}
+
+/**
+ * Build a deterministic compaction summary for a pi-crew run.
+ *
+ * Reads manifest.json, tasks.json, and the tail of events.jsonl to produce
+ * a self-contained markdown summary suitable for context injection.
+ *
+ * @param stateRoot - Path to the run's state root directory
+ * @returns Markdown-formatted compaction summary
+ */
+export function buildCompactionSummary(stateRoot: string): string {
+	const paths = summaryPathsFor(stateRoot);
+
+	// Read manifest
+	const manifest = readJsonFile<TeamRunManifest>(paths.manifestPath);
+
+	// Read tasks
+	const tasks = readJsonFile<TeamTaskState[]>(paths.tasksPath) ?? [];
+
+	// Read tail events
+	const tailLines = readTailLines(paths.eventsPath, MAX_TAIL_EVENTS);
+	const tailEvents = parseEvents(tailLines);
+
+	const sections: string[] = [];
+
+	// Section: Run Metadata
+	sections.push("# Run Summary");
+	if (manifest) {
+		sections.push("");
+		sections.push("## Run Metadata");
+		sections.push(`- **Run ID**: ${manifest.runId}`);
+		sections.push(`- **Team**: ${manifest.team}`);
+		if (manifest.workflow) {
+			sections.push(`- **Workflow**: ${manifest.workflow}`);
+		}
+		if (manifest.goal) {
+			sections.push(`- **Goal**: ${manifest.goal.replace(/\n/g, " ").slice(0, 500)}`);
+		}
+		sections.push(`- **Status**: ${manifest.status}`);
+		sections.push(`- **Created**: ${manifest.createdAt}`);
+		sections.push(`- **Updated**: ${manifest.updatedAt}`);
+		if (manifest.workspaceMode) {
+			sections.push(`- **Workspace Mode**: ${manifest.workspaceMode}`);
+		}
+	} else {
+		sections.push("");
+		sections.push("## Run Metadata");
+		sections.push("- **Status**: manifest unavailable");
+	}
+
+	// Section: Task Progress Table
+	sections.push("");
+	sections.push("## Task Progress");
+	if (tasks.length > 0) {
+		sections.push("");
+		sections.push("| ID | Role | Status | Duration |");
+		sections.push("|---|---|---|---|");
+		for (const task of tasks) {
+			const taskId = task.id;
+			const role = task.role || "—";
+			const status = task.status || "—";
+			const duration = formatDuration(task.startedAt, task.finishedAt);
+			sections.push(`| ${taskId} | ${role} | ${status} | ${duration} |`);
+		}
+	} else {
+		sections.push("");
+		sections.push("No tasks recorded.");
+	}
+
+	// Section: Recent Task Results
+	const completedTasks = tasks
+		.filter((t) => t.status === "completed" || t.status === "failed")
+		.slice(-MAX_RECENT_RESULTS);
+
+	if (completedTasks.length > 0) {
+		sections.push("");
+		sections.push("## Recent Task Results");
+		for (const task of completedTasks) {
+			sections.push("");
+			sections.push(`### ${task.id} (${task.status})`);
+			if (task.error) {
+				sections.push(`- **Error**: ${task.error}`);
+			}
+			if (task.diagnostics && Object.keys(task.diagnostics).length > 0) {
+				sections.push("- **Diagnostics**:");
+				for (const [key, value] of Object.entries(task.diagnostics)) {
+					sections.push(`  - ${key}: ${JSON.stringify(value)}`);
+				}
+			}
+			if (task.metrics && Object.keys(task.metrics).length > 0) {
+				sections.push("- **Metrics**:");
+				for (const [key, value] of Object.entries(task.metrics)) {
+					sections.push(`  - ${key}: ${value}`);
+				}
+			}
+		}
+	}
+
+	// Section: Next Steps (pending/queued tasks)
+	const pendingStatuses = new Set(["queued", "waiting", "running"]);
+	const pendingTasks = tasks.filter(
+		(t) => pendingStatuses.has(t.status),
+	);
+	if (pendingTasks.length > 0) {
+		sections.push("");
+		sections.push("## Next Steps");
+		sections.push("");
+		for (const task of pendingTasks) {
+			const title = task.title || task.role || "Untitled";
+			sections.push(`- [${task.status}] ${task.id}: ${title}`);
+		}
+	}
+
+	// Section: Tail Events Summary
+	if (tailEvents.length > 0) {
+		sections.push("");
+		sections.push(`## Recent Events (last ${tailEvents.length})`);
+		sections.push("");
+		for (const event of tailEvents.slice(-10)) {
+			const taskPart = event.taskId ? ` task=${event.taskId}` : "";
+			const msgPart = event.message ? ` — ${event.message}` : "";
+			sections.push(`- [${event.time}] ${event.type}${taskPart}${msgPart}`);
+		}
+	}
+
+	return sections.join("\n");
+}

package/src/runtime/completion-guard.ts

@@ -1,190 +1,190 @@
-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;
-	taskText?: string;
-	transcriptPath?: string;
-	stdout?: string;
-}
-
-export interface CompletionMutationGuardResult {
-	expectedMutation: boolean;
-	observedMutation: boolean;
-	reason?: "no_mutation_observed";
-	observedTools: string[];
-}
-
-const MUTATING_ROLES = new Set(["executor", "test-engineer"]);
-const MUTATING_TOOLS = new Set(["edit", "write", "multi_edit", "apply_patch", "replace_in_file", "insert", "delete_files", "create_file", "overwrite", "patch"]);
-const READ_ONLY_COMMANDS = /^(pwd|ls|dir|cat|type|sed|grep|rg|find|git\s+(status|diff|log|show|branch|remote|rev-parse|ls-files)|npm\s+(test|run\s+(typecheck|check|lint|test|ci))|node\s+--test)\b/i;
-const MUTATING_COMMANDS = /\b(rm\s+-|del\s+|erase\s+|mv\s+|move\s+|cp\s+|copy\s+|mkdir\b|touch\b|git\s+(add|commit|push|reset|clean|checkout|switch|merge|rebase|stash)|npm\s+(install|i|uninstall|publish|version)|pnpm\s+(add|install|remove)|yarn\s+(add|install|remove)|python\b.*>|node\b.*>|echo\b.*>|Set-Content|Out-File|sed\s+-i|tee\b|dd\b.*of=|wget\b.*-O|curl\b.*-o)\b/i;
-const READ_ONLY_HINTS = /\b(read-only|no edits?|do not edit|không sửa|khong sua|chỉ đọc|chi doc|plan only|chỉ lập plan|review only|audit only)\b/i;
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-}
-
-function commandText(value: unknown): string {
-	const record = asRecord(value);
-	if (!record) return typeof value === "string" ? value : "";
-	for (const key of ["command", "cmd", "script", "input"]) {
-		const raw = record[key];
-		if (typeof raw === "string") return raw;
-	}
-	return JSON.stringify(record);
-}
-
-function isMutatingTool(tool: string, args: unknown): boolean {
-	const normalized = tool.toLowerCase();
-	if (MUTATING_TOOLS.has(normalized)) return true;
-	if (normalized === "bash" || normalized === "shell" || normalized === "powershell") {
-		const command = commandText(args).trim();
-		if (!command) return false;
-		// Check mutating patterns first: sed -i is mutating even though plain sed is read-only.
-		if (MUTATING_COMMANDS.test(command)) return true;
-		if (READ_ONLY_COMMANDS.test(command)) return false;
-		// If the command doesn't match either list, treat unknown bash calls as potentially mutating.
-		return true;
-	}
-	return false;
-}
-
-function collectToolCallsFromEvent(event: unknown): Array<{ tool: string; args?: unknown }> {
-	const record = asRecord(event);
-	if (!record) return [];
-	const calls: Array<{ tool: string; args?: unknown }> = [];
-	const directTool = record.toolName ?? record.name ?? record.tool;
-	if (typeof directTool === "string" && (record.type === "tool_execution_start" || record.type === "toolCall" || record.type === "tool_call")) {
-		calls.push({ tool: directTool, args: record.args ?? record.input });
-	}
-	const content = Array.isArray(record.content) ? record.content : asRecord(record.message)?.content;
-	if (Array.isArray(content)) {
-		for (const part of content) {
-			const item = asRecord(part);
-			if (!item) continue;
-			const tool = item.name ?? item.toolName ?? item.tool;
-			if (typeof tool === "string" && (item.type === "toolCall" || item.type === "tool_call" || item.type === "tool_execution_start")) calls.push({ tool, args: item.input ?? item.args });
-		}
-	}
-	return calls;
-}
-
-function transcriptText(input: CompletionMutationGuardInput): string {
-	if (input.transcriptPath && fs.existsSync(input.transcriptPath)) return fs.readFileSync(input.transcriptPath, "utf-8");
-	return input.stdout ?? "";
-}
-
-export function expectsImplementationMutation(input: Pick<CompletionMutationGuardInput, "role" | "taskText">): boolean {
-	if (!MUTATING_ROLES.has(input.role)) return false;
-	return !READ_ONLY_HINTS.test(input.taskText ?? "");
-}
-
-export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
-	const expectedMutation = expectsImplementationMutation(input);
-	const observedTools: string[] = [];
-	let observedMutation = false;
-	const text = transcriptText(input);
-	for (const line of text.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		let event: unknown;
-		try { event = JSON.parse(trimmed); } catch { continue; }
-		for (const call of collectToolCallsFromEvent(event)) {
-			observedTools.push(call.tool);
-			if (isMutatingTool(call.tool, call.args)) observedMutation = true;
-		}
-	}
-	return {
-		expectedMutation,
-		observedMutation,
-		observedTools,
-		...(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) + "...";
-}
+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;
+	taskText?: string;
+	transcriptPath?: string;
+	stdout?: string;
+}
+
+export interface CompletionMutationGuardResult {
+	expectedMutation: boolean;
+	observedMutation: boolean;
+	reason?: "no_mutation_observed";
+	observedTools: string[];
+}
+
+const MUTATING_ROLES = new Set(["executor", "test-engineer"]);
+const MUTATING_TOOLS = new Set(["edit", "write", "multi_edit", "apply_patch", "replace_in_file", "insert", "delete_files", "create_file", "overwrite", "patch"]);
+const READ_ONLY_COMMANDS = /^(pwd|ls|dir|cat|type|sed|grep|rg|find|git\s+(status|diff|log|show|branch|remote|rev-parse|ls-files)|npm\s+(test|run\s+(typecheck|check|lint|test|ci))|node\s+--test)\b/i;
+const MUTATING_COMMANDS = /\b(rm\s+-|del\s+|erase\s+|mv\s+|move\s+|cp\s+|copy\s+|mkdir\b|touch\b|git\s+(add|commit|push|reset|clean|checkout|switch|merge|rebase|stash)|npm\s+(install|i|uninstall|publish|version)|pnpm\s+(add|install|remove)|yarn\s+(add|install|remove)|python\b.*>|node\b.*>|echo\b.*>|Set-Content|Out-File|sed\s+-i|tee\b|dd\b.*of=|wget\b.*-O|curl\b.*-o)\b/i;
+const READ_ONLY_HINTS = /\b(read-only|no edits?|do not edit|không sửa|khong sua|chỉ đọc|chi doc|plan only|chỉ lập plan|review only|audit only)\b/i;
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function commandText(value: unknown): string {
+	const record = asRecord(value);
+	if (!record) return typeof value === "string" ? value : "";
+	for (const key of ["command", "cmd", "script", "input"]) {
+		const raw = record[key];
+		if (typeof raw === "string") return raw;
+	}
+	return JSON.stringify(record);
+}
+
+function isMutatingTool(tool: string, args: unknown): boolean {
+	const normalized = tool.toLowerCase();
+	if (MUTATING_TOOLS.has(normalized)) return true;
+	if (normalized === "bash" || normalized === "shell" || normalized === "powershell") {
+		const command = commandText(args).trim();
+		if (!command) return false;
+		// Check mutating patterns first: sed -i is mutating even though plain sed is read-only.
+		if (MUTATING_COMMANDS.test(command)) return true;
+		if (READ_ONLY_COMMANDS.test(command)) return false;
+		// If the command doesn't match either list, treat unknown bash calls as potentially mutating.
+		return true;
+	}
+	return false;
+}
+
+function collectToolCallsFromEvent(event: unknown): Array<{ tool: string; args?: unknown }> {
+	const record = asRecord(event);
+	if (!record) return [];
+	const calls: Array<{ tool: string; args?: unknown }> = [];
+	const directTool = record.toolName ?? record.name ?? record.tool;
+	if (typeof directTool === "string" && (record.type === "tool_execution_start" || record.type === "toolCall" || record.type === "tool_call")) {
+		calls.push({ tool: directTool, args: record.args ?? record.input });
+	}
+	const content = Array.isArray(record.content) ? record.content : asRecord(record.message)?.content;
+	if (Array.isArray(content)) {
+		for (const part of content) {
+			const item = asRecord(part);
+			if (!item) continue;
+			const tool = item.name ?? item.toolName ?? item.tool;
+			if (typeof tool === "string" && (item.type === "toolCall" || item.type === "tool_call" || item.type === "tool_execution_start")) calls.push({ tool, args: item.input ?? item.args });
+		}
+	}
+	return calls;
+}
+
+function transcriptText(input: CompletionMutationGuardInput): string {
+	if (input.transcriptPath && fs.existsSync(input.transcriptPath)) return fs.readFileSync(input.transcriptPath, "utf-8");
+	return input.stdout ?? "";
+}
+
+export function expectsImplementationMutation(input: Pick<CompletionMutationGuardInput, "role" | "taskText">): boolean {
+	if (!MUTATING_ROLES.has(input.role)) return false;
+	return !READ_ONLY_HINTS.test(input.taskText ?? "");
+}
+
+export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
+	const expectedMutation = expectsImplementationMutation(input);
+	const observedTools: string[] = [];
+	let observedMutation = false;
+	const text = transcriptText(input);
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let event: unknown;
+		try { event = JSON.parse(trimmed); } catch { continue; }
+		for (const call of collectToolCallsFromEvent(event)) {
+			observedTools.push(call.tool);
+			if (isMutatingTool(call.tool, call.args)) observedMutation = true;
+		}
+	}
+	return {
+		expectedMutation,
+		observedMutation,
+		observedTools,
+		...(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) + "...";
+}