pi-crew 0.5.2 → 0.5.6

package/src/runtime/verification-gates.ts

@@ -0,0 +1,367 @@
+/**
+ * Verification Gates — ECC VERIFICATION_LOOP Pattern Implementation
+ * 
+ * Implements RED/GREEN phase gates for task verification.
+ * Sequential execution: cannot skip to Phase N+1 without Phase N passing.
+ * 
+ * Based on: docs/distillation/ECC-10-skills.md §2 (verification-loop)
+ * 
+ * @module verification-gates
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeArtifact } from "../state/artifact-store.ts";
+import type { VerificationContract, VerificationCommandResult, GreenLevel, ArtifactDescriptor } from "../state/types.ts";
+
+export interface PhaseGateResult {
+	phase: number;
+	name: string;
+	status: "passed" | "failed" | "skipped";
+	command: string;
+	exitCode?: number | null;
+	output?: string;
+	durationMs: number;
+	error?: string;
+}
+
+export interface PhaseGateBundle {
+	results: PhaseGateResult[];
+	totalDurationMs: number;
+	allPassed: boolean;
+	stoppedAt?: number; // phase number where stopped
+}
+
+/**
+ * Standard phase gate definitions for npm/TypeScript projects.
+ * Sequential enforcement: each phase must pass before proceeding.
+ */
+export const NPM_TYPESCRIPT_GATES: Array<{ name: string; command: string; critical: boolean }> = [
+	{ name: "build", command: "npm run build 2>&1 || true", critical: true },
+	{ name: "typecheck", command: "npx tsc --noEmit 2>&1 || true", critical: true },
+	{ name: "lint", command: "npm run lint 2>&1 || true", critical: false },
+	{ name: "tests", command: "npm test 2>&1 || true", critical: true },
+];
+
+/**
+ * Cargo/Rust project phase gates.
+ */
+export const CARGO_RUST_GATES: Array<{ name: string; command: string; critical: boolean }> = [
+	{ name: "check", command: "cargo check 2>&1 || true", critical: true },
+	{ name: "test", command: "cargo test 2>&1 || true", critical: true },
+	{ name: "clippy", command: "cargo clippy 2>&1 || true", critical: false },
+];
+
+/**
+ * Execute a single command and capture output.
+ */
+async function executeCommand(
+	command: string,
+	cwd: string,
+	timeoutMs: number = 120000,
+): Promise<{ exitCode: number | null; output: string; durationMs: number }> {
+	const start = Date.now();
+	let output = "";
+	let exitCode: number | null = null;
+
+	return new Promise((resolve) => {
+		// Use shell to handle compound commands
+		const shell = spawn("sh", ["-c", command], {
+			cwd,
+			timeout: timeoutMs,
+			env: { ...process.env, FORCE_COLOR: "0" },
+		});
+
+		shell.stdout?.on("data", (data) => {
+			output += data.toString();
+		});
+
+		shell.stderr?.on("data", (data) => {
+			output += data.toString();
+		});
+
+		shell.on("close", (code) => {
+			exitCode = code;
+			resolve({
+				exitCode,
+				output: output.slice(-100000), // Cap at 100KB
+				durationMs: Date.now() - start,
+			});
+		});
+
+		shell.on("error", (err) => {
+			resolve({
+				exitCode: -1,
+				output: `Execution error: ${err.message}`,
+				durationMs: Date.now() - start,
+			});
+		});
+
+		// Handle timeout
+		setTimeout(() => {
+			shell.kill("SIGKILL");
+			resolve({
+				exitCode: -1,
+				output: output + "\n[TIMEOUT: Command exceeded limit]",
+				durationMs: Date.now() - start,
+			});
+		}, timeoutMs);
+	});
+}
+
+/**
+ * Run phase gates sequentially, stopping on first critical failure.
+ * 
+ * @param gates - Array of phase gate definitions
+ * @param cwd - Working directory to execute commands in
+ * @param signal - Optional abort signal
+ * @param onPhase - Optional callback for each phase completion
+ * @returns Phase gate bundle with all results
+ */
+export async function runPhaseGates(
+	gates: Array<{ name: string; command: string; critical: boolean }>,
+	cwd: string,
+	signal?: AbortSignal,
+	onPhase?: (result: PhaseGateResult) => void,
+): Promise<PhaseGateBundle> {
+	const results: PhaseGateResult[] = [];
+	const startTime = Date.now();
+	let stoppedAt: number | undefined;
+
+	for (let i = 0; i < gates.length; i++) {
+		// Check abort signal
+		if (signal?.aborted) {
+			results.push({
+				phase: i + 1,
+				name: gates[i].name,
+				status: "skipped",
+				command: gates[i].command,
+				durationMs: 0,
+				error: "Aborted",
+			});
+			stoppedAt = i + 1;
+			break;
+		}
+
+		const gate = gates[i];
+		const phaseStart = Date.now();
+
+		// Execute the gate command
+		const { exitCode, output, durationMs } = await executeCommand(
+			gate.command,
+			cwd,
+			120000, // 2 minute timeout
+		);
+
+		const passed = exitCode === 0;
+		const result: PhaseGateResult = {
+			phase: i + 1,
+			name: gate.name,
+			status: passed ? "passed" : "failed",
+			command: gate.command,
+			exitCode,
+			output,
+			durationMs,
+			error: passed ? undefined : `Exit code: ${exitCode}`,
+		};
+
+		results.push(result);
+		onPhase?.(result);
+
+		// Stop on critical failure
+		if (!passed && gate.critical) {
+			stoppedAt = i + 1;
+			break;
+		}
+	}
+
+	return {
+		results,
+		totalDurationMs: Date.now() - startTime,
+		allPassed: results.every((r) => r.status === "passed"),
+		stoppedAt,
+	};
+}
+
+/**
+ * Execute verification commands from a task's verification contract.
+ * Maps the contract commands to phase gates and runs them sequentially.
+ * 
+ * @param contract - Verification contract with commands to execute
+ * @param cwd - Working directory
+ * @param runId - Run ID for artifact naming
+ * @param taskId - Task ID for artifact naming
+ * @param artifactsRoot - Artifacts root directory
+ * @param signal - Optional abort signal
+ * @returns Array of verification command results
+ */
+export async function executeVerificationCommands(
+	contract: VerificationContract,
+	cwd: string,
+	runId: string,
+	taskId: string,
+	artifactsRoot: string,
+	signal?: AbortSignal,
+): Promise<VerificationCommandResult[]> {
+	if (!contract.commands || contract.commands.length === 0) {
+		return [];
+	}
+
+	const results: VerificationCommandResult[] = [];
+
+	// Map commands to phase gates
+	const gates = contract.commands.map((cmd, index) => ({
+		name: `verification-${index + 1}`,
+		command: cmd,
+		critical: true, // All verification commands are critical by default
+	}));
+
+	// Create artifacts directory
+	const gatesDir = path.join(artifactsRoot, "verification-gates");
+	if (!fs.existsSync(gatesDir)) {
+		fs.mkdirSync(gatesDir, { recursive: true });
+	}
+
+	// Run phase gates
+	const bundle = await runPhaseGates(gates, cwd, signal, (phaseResult) => {
+		// Write phase artifact immediately for observability
+		const phaseArtifact = writeArtifact(artifactsRoot, {
+			kind: "log",
+			relativePath: `verification-gates/${taskId}-phase-${phaseResult.phase}-${phaseResult.name}.log`,
+			content: [
+				`# Phase ${phaseResult.phase}: ${phaseResult.name}`,
+				`Status: ${phaseResult.status.toUpperCase()}`,
+				`Command: ${phaseResult.command}`,
+				`Duration: ${phaseResult.durationMs}ms`,
+				phaseResult.exitCode != null ? `Exit Code: ${phaseResult.exitCode}` : "",
+				phaseResult.error ? `Error: ${phaseResult.error}` : "",
+				"",
+				"## Output",
+				phaseResult.output || "(no output)",
+			].join("\n"),
+			producer: taskId,
+		});
+
+		results.push({
+			cmd: phaseResult.command,
+			status: phaseResult.status === "passed" ? "passed" : "failed",
+			exitCode: phaseResult.exitCode,
+			outputArtifact: phaseArtifact,
+		});
+	});
+
+	// Write summary artifact
+	const summaryArtifact = writeArtifact(artifactsRoot, {
+		kind: "metadata",
+		relativePath: `verification-gates/${taskId}-summary.json`,
+		content: JSON.stringify(bundle, null, 2),
+		producer: taskId,
+	});
+
+	// Fill in any remaining results (in case of early exit)
+	for (let i = results.length; i < gates.length; i++) {
+		results.push({
+			cmd: gates[i].command,
+			status: "not_run",
+		});
+	}
+
+	return results;
+}
+
+/**
+ * Compute observed green level from verification results.
+ * Maps verification outcomes to green levels per ECC pattern.
+ * 
+ * @param commands - Array of verification command results
+ * @param requiredLevel - Required green level from contract
+ * @returns Observed green level
+ */
+export function computeGreenLevelFromResults(
+	commands: VerificationCommandResult[],
+	requiredLevel: GreenLevel,
+): GreenLevel {
+	if (commands.length === 0) {
+		return "none";
+	}
+
+	const passed = commands.filter((c) => c.status === "passed").length;
+	const failed = commands.filter((c) => c.status === "failed").length;
+	const notRun = commands.filter((c) => c.status === "not_run").length;
+
+	// If any critical verification failed, return none
+	if (failed > 0) {
+		return "none";
+	}
+
+	// If all passed, return the required level (capped at merge_ready)
+	if (passed === commands.length) {
+		return requiredLevel === "none" ? "targeted" : requiredLevel;
+	}
+
+	// Partial pass - return targeted
+	if (passed > 0) {
+		return "targeted";
+	}
+
+	// Nothing run
+	return "none";
+}
+
+/**
+ * Create a verification gate report artifact.
+ * Formatted for human review per ECC verification-loop pattern.
+ */
+export function createVerificationGateReport(
+	taskId: string,
+	contract: VerificationContract,
+	results: VerificationCommandResult[],
+	bundle: PhaseGateBundle,
+): string {
+	const lines = [
+		`# Verification Gate Report: ${taskId}`,
+		"",
+		`## Contract`,
+		`- Required Green Level: ${contract.requiredGreenLevel}`,
+		`- Allow Manual Evidence: ${contract.allowManualEvidence}`,
+		`- Commands: ${contract.commands.length}`,
+		"",
+		`## Results`,
+		"",
+		`| Phase | Command | Status | Exit Code | Duration |`,
+		`|-------|---------|--------|-----------|----------|`,
+	];
+
+	for (const result of results) {
+		const phaseIndex = results.indexOf(result) + 1;
+		const statusIcon = result.status === "passed" ? "✅" : result.status === "failed" ? "❌" : "⏭️";
+		lines.push(
+			`| ${phaseIndex} | \`${truncate(result.cmd, 40)}\` | ${statusIcon} ${result.status} | ${result.exitCode ?? "-"} | ${result.durationMs ?? 0}ms |`,
+		);
+	}
+
+	lines.push("");
+	lines.push(`## Summary`);
+	lines.push(`- Total Phases: ${bundle.results.length}`);
+	lines.push(`- Passed: ${bundle.results.filter((r) => r.status === "passed").length}`);
+	lines.push(`- Failed: ${bundle.results.filter((r) => r.status === "failed").length}`);
+	lines.push(`- Skipped: ${bundle.results.filter((r) => r.status === "skipped").length}`);
+	lines.push(`- Total Duration: ${bundle.totalDurationMs}ms`);
+	lines.push(`- All Passed: ${bundle.allPassed ? "YES ✅" : "NO ❌"}`);
+
+	if (bundle.stoppedAt) {
+		lines.push(`- Stopped At: Phase ${bundle.stoppedAt}`);
+	}
+
+	lines.push("");
+	lines.push("## VERIFICATION");
+	lines.push(bundle.allPassed ? "**PASSED** - All gates green ✅" : "**FAILED** - One or more gates red ❌");
+
+	return lines.join("\n");
+}
+
+function truncate(str: string, maxLen: number): string {
+	if (str.length <= maxLen) return str;
+	return str.slice(0, maxLen - 3) + "...";
+}

package/src/schema/team-tool-schema.ts

@@ -68,6 +68,9 @@ export const TeamToolParams = Type.Object({
 				Type.Literal("orchestrate"),
 				Type.Literal("schedule"),
 				Type.Literal("scheduled"),
+				Type.Literal("anchor"),
+				Type.Literal("auto-summarize"),
+				Type.Literal("auto_boomerang"),
 			],
 			{ description: "Team action. Defaults to 'list' when omitted." },
 		),
@@ -204,6 +207,32 @@ export const TeamToolParams = Type.Object({
 	once: Type.Optional(
 		Type.Union([Type.String(), Type.Number()], { description: "ISO timestamp or epoch ms for a one-time scheduled run." }),
 	),
+	excludeContextBash: Type.Optional(
+		Type.Boolean({
+			description: "Mark certain bash commands as excludeFromContext to reduce context tokens (default: false).",
+		}),
+	),
+	// Budget tracking options
+	budgetTotal: Type.Optional(
+		Type.Number({
+			description: "Total token budget for the run. When set, enables budget tracking with default 80% warning and 95% abort thresholds.",
+			minimum: 1,
+		}),
+	),
+	budgetWarning: Type.Optional(
+		Type.Number({
+			description: "Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
+			minimum: 0,
+			maximum: 1,
+		}),
+	),
+	budgetAbort: Type.Optional(
+		Type.Number({
+			description: "Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
+			minimum: 0,
+			maximum: 1,
+		}),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -287,4 +316,12 @@ export interface TeamToolParamsValue {
 	cron?: string;
 	interval?: number;
 	once?: string | number;
+	/** Mark certain bash commands as excludeFromContext to reduce context tokens (default: false). */
+	excludeContextBash?: boolean;
+	/** Total token budget for the run. When set, enables budget tracking. */
+	budgetTotal?: number;
+	/** Budget warning threshold as a fraction (0-1). Default: 0.8. */
+	budgetWarning?: number;
+	/** Budget abort threshold as a fraction (0-1). Default: 0.95. */
+	budgetAbort?: number;
 }

package/src/skills/discover-skills.ts

@@ -6,6 +6,9 @@ import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "..
 
 const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
 
+const CACHE_TTL_MS = 30_000; // 30 seconds
+let cache: { skills: SkillDescriptor[]; cachedAt: number; cwd: string } | null = null;
+
 export interface SkillDescriptor {
 	name: string;
 	description: string;
@@ -28,6 +31,7 @@ function frontmatterDescription(content: string): string | undefined {
 }
 
 export function discoverSkills(cwd: string): SkillDescriptor[] {
+	if (cache && cache.cwd === cwd && Date.now() - cache.cachedAt < CACHE_TTL_MS) return cache.skills;
 	const results: SkillDescriptor[] = [];
 	for (const dir of listSkillDirs(cwd)) {
 		if (!fs.existsSync(dir.root)) continue;
@@ -63,5 +67,6 @@ export function discoverSkills(cwd: string): SkillDescriptor[] {
 			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
 		}
 	}
+	cache = { skills: results, cachedAt: Date.now(), cwd };
 	return results;
 }

package/src/state/active-run-registry.ts

@@ -10,6 +10,9 @@ import { sharedScanCache } from "../utils/scan-cache.ts";
 import { sleepSync } from "../utils/sleep.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 
+/** Magic bytes prefix for binary registry to prevent deserialization of hostile files. */
+const BINARY_MAGIC = Buffer.from("PICREW2BIN", "utf-8");
+
 export interface ActiveRunRegistryEntry {
 	runId: string;
 	cwd: string;
@@ -111,7 +114,11 @@ export function readActiveRunRegistry(maxEntries = DEFAULT_CACHE.manifestMaxEntr
 	// corrupt; this lets a 2-release migration co-exist with old readers.
 	try {
 		const buf = fs.readFileSync(registryBinaryPath());
-		parsed = deserialize(buf);
+		// Security: verify magic bytes before deserializing to prevent RCE from hostile files
+		if (buf.length < BINARY_MAGIC.length || !buf.slice(0, BINARY_MAGIC.length).equals(BINARY_MAGIC)) {
+			throw new Error("Invalid binary registry: missing magic bytes");
+		}
+		parsed = deserialize(buf.slice(BINARY_MAGIC.length));
 	} catch {
 		try {
 			parsed = JSON.parse(fs.readFileSync(registryPath(), "utf-8"));
@@ -135,7 +142,7 @@ function writeEntries(entries: ActiveRunRegistryEntry[]): void {
 	atomicWriteJson(registryPath(), trimmed);
 	try {
 		const tempBin = `${registryBinaryPath()}.${process.pid}.${Date.now()}.tmp`;
-		fs.writeFileSync(tempBin, serialize(trimmed));
+		fs.writeFileSync(tempBin, Buffer.concat([BINARY_MAGIC, serialize(trimmed)]));
 		fs.renameSync(tempBin, registryBinaryPath());
 	} catch (error) {
 		logInternalError("active-run-registry.binary-write", error);

package/src/state/contracts.ts

@@ -67,6 +67,15 @@ export const TEAM_EVENT_TYPES = [
 	"task.resumed",
 	"task.retried",
 	"supervisor.contact",
+	// Budget tracking events
+	"budget.initialized",
+	"budget.warning",
+	"budget.exhausted",
+	// Phase tracking events
+	"phase.started",
+	"phase.completed",
+	"phase.skipped",
+	"phase.failed",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
 

package/src/state/crew-init.ts

@@ -108,9 +108,9 @@ export async function ensureCrewDirectory(cwd: string): Promise<void> {
 	];
 
 	for (const dir of dirs) {
-		if (!fs.existsSync(dir)) {
-			fs.mkdirSync(dir, { recursive: true });
-		}
+		// Use mkdirSync directly with recursive:true to avoid TOCTOU race.
+		// This is atomic and doesn't require existsSync check.
+		fs.mkdirSync(dir, { recursive: true });
 	}
 
 	// 2. Create .gitkeep placeholders in directories that should be tracked