pi-crew 0.9.53 → 0.9.55

package/src/runtime/completion-guard.ts

@@ -0,0 +1,207 @@
+import * as fs from "node:fs";
+import type { TeamRunManifest, TeamTaskState } 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;
+}
+
+export 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) + "...";
+}

package/src/runtime/concurrency.ts

@@ -0,0 +1,58 @@
+import { DEFAULT_CONCURRENCY } from "../config/defaults.ts";
+
+export interface ResolveBatchConcurrencyInput {
+	workflowName: string;
+	workflowMaxConcurrency?: number;
+	teamMaxConcurrency?: number;
+	limitMaxConcurrentWorkers?: number;
+	allowUnboundedConcurrency?: boolean;
+	hardCap?: number;
+	readyCount: number;
+	workspaceMode?: "single" | "worktree";
+	readyRoles?: string[];
+}
+
+export interface BatchConcurrencyDecision {
+	maxConcurrent: number;
+	selectedCount: number;
+	defaultConcurrency: number;
+	reason: string;
+}
+
+export function defaultWorkflowConcurrency(workflowName: string, workflowMaxConcurrency?: number): number {
+	if (workflowMaxConcurrency !== undefined) return workflowMaxConcurrency;
+	if (workflowName === "parallel-research") return DEFAULT_CONCURRENCY.workflow.parallelResearch;
+	if (workflowName === "research") return DEFAULT_CONCURRENCY.workflow.research;
+	if (workflowName === "implementation") return DEFAULT_CONCURRENCY.workflow.implementation;
+	if (workflowName === "review") return DEFAULT_CONCURRENCY.workflow.review;
+	if (workflowName === "default") return DEFAULT_CONCURRENCY.workflow.default;
+	return DEFAULT_CONCURRENCY.fallback;
+}
+
+function positiveInteger(value: number | undefined): number | undefined {
+	if (value === undefined || !Number.isFinite(value)) return undefined;
+	return Math.max(1, Math.trunc(value));
+}
+
+export function resolveBatchConcurrency(input: ResolveBatchConcurrencyInput): BatchConcurrencyDecision {
+	const workflowMax = positiveInteger(input.workflowMaxConcurrency);
+	const defaultConcurrency = defaultWorkflowConcurrency(input.workflowName, workflowMax);
+	const limitMax = positiveInteger(input.limitMaxConcurrentWorkers);
+	const teamMax = positiveInteger(input.teamMaxConcurrency);
+	const requested = limitMax ?? teamMax ?? workflowMax ?? defaultWorkflowConcurrency(input.workflowName);
+	let source: "limit" | "team" | "workflow";
+	if (limitMax !== undefined) source = "limit";
+	else if (teamMax !== undefined) source = "team";
+	else source = "workflow";
+	const hardCap = positiveInteger(input.hardCap) ?? DEFAULT_CONCURRENCY.hardCap;
+	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap);
+	const readyCount = Math.max(0, Math.trunc(Number.isFinite(input.readyCount) ? input.readyCount : 0));
+	const cappedReason = maxConcurrent < requested ? `;capped:${hardCap}` : "";
+	const unboundedReason = input.allowUnboundedConcurrency && requested > hardCap ? `;unbounded:${hardCap}` : "";
+	return {
+		maxConcurrent,
+		selectedCount: readyCount === 0 ? 0 : Math.min(readyCount, maxConcurrent),
+		defaultConcurrency,
+		reason: `${source}:${requested}${cappedReason}${unboundedReason};ready:${readyCount}`,
+	};
+}

package/src/runtime/crash-classification.ts

@@ -0,0 +1,229 @@
+/**
+ * Crash Classification Taxonomy — pure function for categorizing worker exits.
+ *
+ * Distilled from gajae-code's `debug/crash-diagnostics.ts` (P0 item #1).
+ * Unlike the original, this module is pure: it does NOT write crash reports or
+ * touch the filesystem. The file-I/O layer is intentionally omitted; callers
+ * that want durable crash logs can layer them on top of {@link classifyProcessCrash}.
+ *
+ * The classification precedence (most-significant first) mirrors the
+ * reference implementation:
+ *
+ *   1. timeout          — process was terminated by the response-timeout guard
+ *   2. cancelled        — cooperative cancellation (AbortSignal) triggered exit
+ *   3. spawn_error      — child_process emitted an `error` event before `exit`
+ *   4. native_panic     — stderr indicates a native crash (SIGSEGV / abort / panic)
+ *   5. signal_exit      — the process was terminated by an OS signal
+ *   6. clean_exit       — exit code 0
+ *   7. non_zero_exit    — exit code != 0 (and != null)
+ *   8. protocol_exit    — exit code is null with no signal (protocol/stream
+ *                         ended before a normal exit was observed)
+ *   9. unknown          — defensive fallback (should not occur in practice)
+ *
+ * NOTE on timeout-vs-cancel precedence: when BOTH `timedOut` and `cancelled`
+ * are true, `timeout` wins (the timeout terminated the process). This matches
+ * gajae-code and the existing child-pi.ts response-timeout guard, which fires
+ * the hard kill and is the proximate cause.
+ */
+
+/**
+ * Categorical classification of why a worker process ended.
+ *
+ * @see classifyProcessCrash
+ */
+export type CrashClass =
+	| "clean_exit"
+	| "non_zero_exit"
+	| "signal_exit"
+	| "timeout"
+	| "cancelled"
+	| "spawn_error"
+	| "protocol_exit"
+	| "native_panic"
+	| "unknown";
+
+/**
+ * Inputs to {@link classifyProcessCrash}. All fields are optional/safe-defaulting
+ * so callers can pass a partial view (e.g. just `{ exitCode: 0 }`).
+ *
+ * Field semantics:
+ * - `exitCode`    — the OS exit code, or `null` when no code was observed.
+ * - `signal`      — the terminating signal name (e.g. `"SIGTERM"`) or `null`.
+ * - `cancelled`   — true when cooperative cancellation (AbortSignal) was requested.
+ * - `timedOut`    — true when the response-timeout guard fired (and likely killed).
+ * - `killed`      — true when the parent explicitly killed the child (best-effort).
+ * - `spawnError`  — truthy when the child emitted a spawn/process `error` event.
+ * - `stderrSnippet` — tail of captured stderr, used to detect native panics.
+ */
+export interface CrashClassificationInput {
+	exitCode?: number | null;
+	signal?: string | null;
+	cancelled?: boolean;
+	timedOut?: boolean;
+	killed?: boolean;
+	spawnError?: unknown;
+	stderrSnippet?: string;
+}
+
+/**
+ * Result of classifying an exit. `crashClass` is machine-readable;
+ * `reason` is a human-friendly one-liner suitable for logs/diagnostics.
+ */
+export interface CrashClassification {
+	crashClass: CrashClass;
+	reason: string;
+}
+
+// ── native-panic detection ──────────────────────────────────────────────────
+//
+// We look for a small, well-known set of native-crash signatures in the stderr
+// tail. This is deliberately conservative: false positives would mislabel
+// ordinary non-zero exits as native panics. The patterns are anchored on
+// substrings that do not appear in normal application output.
+
+interface NativePanicSignature {
+	/** Substring to search for (case-insensitive). */
+	pattern: string;
+	/** Human-readable class-specific reason suffix. */
+	label: string;
+}
+
+const NATIVE_PANIC_SIGNATURES: readonly NativePanicSignature[] = [
+	{ pattern: "sigsegv", label: "segmentation fault" },
+	{ pattern: "segfault", label: "segmentation fault" },
+	{ pattern: "segmentation fault", label: "segmentation fault" },
+	{ pattern: "sigabrt", label: "abort signal" },
+	{ pattern: "abort(", label: "abort" },
+	{ pattern: "fatal error", label: "V8/node fatal error" },
+	{ pattern: "panic:", label: "rust/go panic" },
+	{ pattern: "thread '", label: "rust panic (thread context)" },
+	{ pattern: "illegal instruction", label: "illegal instruction" },
+	{ pattern: "double free", label: "heap corruption (double free)" },
+];
+
+/**
+ * If the stderr tail contains a recognizable native-crash signature, return the
+ * matching label; otherwise `null`. Case-insensitive.
+ */
+function detectNativePanic(stderrSnippet: string | undefined): string | null {
+	if (!stderrSnippet) return null;
+	const lower = stderrSnippet.toLowerCase();
+	for (const sig of NATIVE_PANIC_SIGNATURES) {
+		if (lower.includes(sig.pattern)) return sig.label;
+	}
+	return null;
+}
+
+/** Normalize an optional/signal-ish value to `string | null`. */
+function normalizeSignal(signal: string | null | undefined): string | null {
+	return signal ?? null;
+}
+
+/**
+ * Classify a worker exit into a {@link CrashClass}.
+ *
+ * Pure: no I/O, no globals, no side effects. Deterministic given the same input.
+ * Safe to call from any context (including signal handlers).
+ *
+ * @example
+ * classifyProcessCrash({ exitCode: 0 })                       // → clean_exit
+ * classifyProcessCrash({ exitCode: 1 })                       // → non_zero_exit
+ * classifyProcessCrash({ signal: "SIGTERM" })                 // → signal_exit
+ * classifyProcessCrash({ timedOut: true, exitCode: null })    // → timeout
+ * classifyProcessCrash({ cancelled: true, exitCode: null })   // → cancelled
+ * classifyProcessCrash({ spawnError: new Error("ENOENT") })   // → spawn_error
+ * classifyProcessCrash({ exitCode: null })                    // → protocol_exit
+ * classifyProcessCrash({ exitCode: 139, signal: "SIGSEGV" })  // → signal_exit
+ * classifyProcessCrash({ exitCode: 134, stderrSnippet: "abort()" }) // → native_panic
+ */
+export function classifyProcessCrash(input: CrashClassificationInput): CrashClassification {
+	const exitCode = input.exitCode ?? null;
+	const signal = normalizeSignal(input.signal);
+
+	// 1. Timeout takes precedence: the response-timeout guard is the proximate
+	//    cause of death even if cancellation was also requested.
+	if (input.timedOut) {
+		return {
+			crashClass: "timeout",
+			reason: "process timed out (response timeout guard fired)",
+		};
+	}
+
+	// 2. Cooperative cancellation.
+	if (input.cancelled) {
+		return {
+			crashClass: "cancelled",
+			reason: "process was cancelled (abort requested)",
+		};
+	}
+
+	// 3. Spawn error: the child never started or emitted a process error.
+	if (input.spawnError !== undefined && input.spawnError !== null) {
+		return {
+			crashClass: "spawn_error",
+			reason: `spawn error: ${stringifyError(input.spawnError)}`,
+		};
+	}
+
+	// 4. Native panic from stderr (only when we have a signal/abnormal exit —
+	//    never reclassify a clean exit as a panic based on stderr noise).
+	const abnormalExit = signal !== null || (exitCode !== null && exitCode !== 0);
+	if (abnormalExit) {
+		const panic = detectNativePanic(input.stderrSnippet);
+		if (panic !== null) {
+			return {
+				crashClass: "native_panic",
+				reason: `native panic detected: ${panic}`,
+			};
+		}
+	}
+
+	// 5. Signal exit.
+	if (signal !== null) {
+		return {
+			crashClass: "signal_exit",
+			reason: `process exited after signal ${signal}`,
+		};
+	}
+
+	// 6. Clean exit.
+	if (exitCode === 0) {
+		return { crashClass: "clean_exit", reason: "process exited cleanly" };
+	}
+
+	// 7. Non-zero exit.
+	if (exitCode !== null) {
+		return {
+			crashClass: "non_zero_exit",
+			reason: `process exited with code ${exitCode}`,
+		};
+	}
+
+	// 8. Protocol exit: exitCode is null with no signal — the process stream
+	//    ended before a normal exit was observed (e.g. stdio closed unexpectedly).
+	//    If `killed` is true but no signal was recorded, treat as protocol_exit
+	//    (the kill may not have delivered a signal we could capture).
+	if (input.killed) {
+		return {
+			crashClass: "protocol_exit",
+			reason: "process was killed but no signal/exit code was captured",
+		};
+	}
+
+	// 8b. Truly null exitCode with no other context — protocol/stream ended early.
+	return {
+		crashClass: "protocol_exit",
+		reason: "process exited before protocol completion (exit code unknown)",
+	};
+}
+
+/** Render an unknown error value to a short message string. */
+function stringifyError(error: unknown): string {
+	if (error instanceof Error) return error.message || error.name;
+	if (typeof error === "string") return error;
+	try {
+		return String(error);
+	} catch {
+		return "(unstringifiable error)";
+	}
+}