pi-crew 0.9.51 → 0.9.52

package/src/runtime/plan-templates.ts

@@ -1,201 +0,0 @@
-/**
- * Structured planning engine — template-based plan generation with verification.
- *
- * Pattern origin: plannotator/ — plan templates with task decomposition,
- * verification constraints, and pre-execution plan verification.
- *
- * Templates provide reusable plan structures that can be specialized
- * for different project types, replacing pure LLM-generated plans with
- * deterministic scaffolding + LLM refinement.
- */
-
-import { logInternalError } from "../utils/internal-error.ts";
-
-// ── Types ────────────────────────────────────────────────────────────────
-
-export interface PlanTemplate {
-	/** Template name (e.g., "standard-review", "full-implementation") */
-	name: string;
-	/** One-line description */
-	description: string;
-	/** Template phases */
-	phases: PlanPhase[];
-	/** Verification commands per phase (phaseName → command) */
-	verificationCommands: Record<string, string>;
-}
-
-export interface PlanPhase {
-	/** Phase name (e.g., "explore", "plan", "execute", "verify") */
-	name: string;
-	/** Agent role for this phase */
-	role: string;
-	/** Task description template — {{variables}} are substituted */
-	taskTemplate: string;
-	/** Maximum number of tasks in this phase */
-	maxTasks: number;
-	/** Dependencies on other phases */
-	dependsOn: string[];
-	/** Optional verification command */
-	verificationCommand?: string;
-}
-
-export interface RenderedPlan {
-	templateName: string;
-	phases: RenderedPhase[];
-	variables: Record<string, string>;
-}
-
-export interface RenderedPhase {
-	name: string;
-	role: string;
-	task: string;
-	dependsOn: string[];
-	verificationCommand?: string;
-}
-
-// ── Template Registry ────────────────────────────────────────────────────
-
-const templates = new Map<string, PlanTemplate>();
-
-/**
- * Register a plan template.
- */
-export function registerPlanTemplate(template: PlanTemplate): void {
-	templates.set(template.name, template);
-}
-
-/**
- * Get a registered template by name.
- */
-export function getPlanTemplate(name: string): PlanTemplate | undefined {
-	return templates.get(name);
-}
-
-/**
- * List all registered template names.
- */
-export function listPlanTemplates(): string[] {
-	return [...templates.keys()];
-}
-
-// ── Rendering ────────────────────────────────────────────────────────────
-
-/**
- * Render a plan template with variable substitution.
- *
- * Variables in task templates use {{variableName}} syntax.
- *
- * @param templateName - Name of the registered template
- * @param variables - Key-value pairs for substitution
- * @returns Rendered plan, or undefined if template not found
- */
-export function renderPlanTemplate(templateName: string, variables: Record<string, string>): RenderedPlan | undefined {
-	const template = templates.get(templateName);
-	if (!template) {
-		logInternalError("plan-templates", new Error(`Template not found: ${templateName}`));
-		return undefined;
-	}
-
-	const phases: RenderedPhase[] = template.phases.map((phase) => ({
-		name: phase.name,
-		role: phase.role,
-		task: substituteVariables(phase.taskTemplate, variables),
-		dependsOn: phase.dependsOn,
-		verificationCommand: phase.verificationCommand ?? template.verificationCommands[phase.name],
-	}));
-
-	return { templateName, phases, variables };
-}
-
-/**
- * Substitute {{variable}} placeholders in a template string.
- */
-function substituteVariables(template: string, variables: Record<string, string>): string {
-	return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
-		return variables[key] ?? match;
-	});
-}
-
-// ── Built-in Templates ───────────────────────────────────────────────────
-
-registerPlanTemplate({
-	name: "standard-review",
-	description: "Standard code review workflow: explore → review → verify",
-	phases: [
-		{
-			name: "explore",
-			role: "explorer",
-			taskTemplate: "Map the codebase and identify the key files related to: {{goal}}. Focus on: {{focusAreas}}.",
-			maxTasks: 1,
-			dependsOn: [],
-		},
-		{
-			name: "review",
-			role: "reviewer",
-			taskTemplate:
-				"Review the code identified in the explore phase for: {{goal}}. Check correctness, maintainability, and security.",
-			maxTasks: 1,
-			dependsOn: ["explore"],
-		},
-		{
-			name: "verify",
-			role: "verifier",
-			taskTemplate:
-				"Verify that all review findings are addressed. Run FAST checks (completes in <2 min): `npm run test:critical && npx tsc --noEmit`. Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Confirm: {{goal}} is achieved.",
-			maxTasks: 1,
-			dependsOn: ["review"],
-			verificationCommand: "npm run test:critical && npx tsc --noEmit",
-		},
-	],
-	verificationCommands: {
-		verify: "npm run test:critical && npx tsc --noEmit",
-	},
-});
-
-registerPlanTemplate({
-	name: "full-implementation",
-	description: "Full implementation workflow: explore → plan → execute → review → verify",
-	phases: [
-		{
-			name: "explore",
-			role: "explorer",
-			taskTemplate:
-				"Explore the codebase to understand the current state relevant to: {{goal}}. Identify affected files and patterns.",
-			maxTasks: 1,
-			dependsOn: [],
-		},
-		{
-			name: "plan",
-			role: "planner",
-			taskTemplate: "Create a detailed implementation plan for: {{goal}}. Break down into concrete steps with file-level changes.",
-			maxTasks: 1,
-			dependsOn: ["explore"],
-		},
-		{
-			name: "execute",
-			role: "executor",
-			taskTemplate: "Implement the plan for: {{goal}}. Make all planned changes, write tests, and ensure TypeScript compiles.",
-			maxTasks: 3,
-			dependsOn: ["plan"],
-		},
-		{
-			name: "review",
-			role: "reviewer",
-			taskTemplate: "Review the implementation of: {{goal}}. Check for correctness, security, performance, and code quality.",
-			maxTasks: 1,
-			dependsOn: ["execute"],
-		},
-		{
-			name: "verify",
-			role: "verifier",
-			taskTemplate:
-				"Verify the complete implementation of: {{goal}}. Run FAST checks (`npm run test:critical && npx tsc --noEmit`, completes in <2 min). Do NOT run `npm run test:unit` or `npm test` — too slow for in-loop verification (642 files, >4 min). Validate all acceptance criteria.",
-			maxTasks: 1,
-			dependsOn: ["review"],
-			verificationCommand: "npm run test:critical && npx tsc --noEmit",
-		},
-	],
-	verificationCommands: {
-		verify: "npm run test:critical && npx tsc --noEmit",
-	},
-});

package/src/runtime/policy-engine.ts

@@ -1,115 +0,0 @@
-import type { CrewLimitsConfig } from "../config/config.ts";
-import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { evaluateGreenContract } from "./green-contract.ts";
-import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
-
-export interface PolicyEngineInput {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	limits?: CrewLimitsConfig;
-	now?: Date;
-}
-
-function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
-	return {
-		action,
-		reason,
-		message,
-		taskId,
-		createdAt: new Date().toISOString(),
-	};
-}
-
-function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
-	let depth = 0;
-	let current = task.graph?.parentId;
-	const seen = new Set<string>();
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		depth += 1;
-		current = tasksById.get(current)?.graph?.parentId;
-	}
-	return depth;
-}
-
-export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
-	const decisions: PolicyDecision[] = [];
-	const maxTasksPerRun = Number.isFinite(input.limits?.maxTasksPerRun) ? input.limits!.maxTasksPerRun : undefined;
-	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
-		decisions.push(
-			decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`),
-		);
-	}
-	const runningCount = input.tasks.filter((task) => task.status === "running").length;
-	const maxConcurrentWorkers = Number.isFinite(input.limits?.maxConcurrentWorkers) ? input.limits!.maxConcurrentWorkers : undefined;
-	if (maxConcurrentWorkers !== undefined && runningCount > maxConcurrentWorkers) {
-		decisions.push(
-			decision(
-				"block",
-				"limit_exceeded",
-				`Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${maxConcurrentWorkers}.`,
-			),
-		);
-	}
-	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
-
-	for (const task of input.tasks) {
-		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
-			decisions.push(
-				decision(
-					"block",
-					"limit_exceeded",
-					`Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`,
-					task.id,
-				),
-			);
-		}
-		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
-			decisions.push(
-				decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id),
-			);
-		}
-		if (task.status === "failed") {
-			const retryCount = task.policy?.retryCount ?? 0;
-			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
-			decisions.push(
-				decision(
-					retryCount < maxRetries ? "retry" : "escalate",
-					"task_failed",
-					task.error ? `Task failed: ${task.error}` : "Task failed.",
-					task.id,
-				),
-			);
-		}
-		if (
-			(task.status === "running" || task.status === "queued") &&
-			task.heartbeat &&
-			task.heartbeat.alive !== false &&
-			isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)
-		) {
-			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
-		}
-		if (task.taskPacket?.verification) {
-			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
-			if (!outcome.satisfied && task.status === "completed") {
-				decisions.push(
-					decision(
-						"block",
-						"green_unsatisfied",
-						`Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`,
-						task.id,
-					),
-				);
-			}
-		}
-	}
-
-	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
-		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
-	}
-	return decisions;
-}
-
-export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
-	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
-}

package/src/runtime/post-checks.ts

@@ -1,142 +0,0 @@
-/**
- * Post-task backpressure checks — runs a configurable shell script after
- * task completion to verify workspace health before proceeding.
- *
- * Distilled from pi-autoresearch's post-check / backpressure pattern.
- */
-import { execFileSync } from "node:child_process";
-import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
-import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
-import { resolveShellForScript } from "../utils/resolve-shell.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-
-/** Default timeout for post-check scripts (5 minutes). */
-const DEFAULT_TIMEOUT_MS = 300_000;
-
-/** Environment variable name for the post-check script path. */
-const POST_CHECK_SCRIPT_ENV = "PI_CREW_POST_CHECK_SCRIPT";
-
-/**
- * Configuration for a post-task check.
- */
-export interface PostCheckConfig {
-	/** Path to the shell script to execute. */
-	scriptPath: string;
-	/** Timeout in milliseconds. Defaults to 300000 (5 minutes). */
-	timeoutMs: number;
-}
-
-/**
- * Result of running a post-task check.
- */
-export interface PostCheckResult {
-	/** Whether the check passed (exit code 0). */
-	passed: boolean;
-	/** Combined stdout + stderr from the script. */
-	output: string;
-	/** Wall-clock duration of the check in milliseconds. */
-	durationMs: number;
-	/** Whether the check timed out. */
-	timedOut: boolean;
-}
-
-/**
- * Resolve the effective post-check script path.
- * Prefers config.scriptPath; falls back to the PI_CREW_POST_CHECK_SCRIPT env var.
- */
-function resolveScriptPath(config: PostCheckConfig): string | undefined {
-	if (config.scriptPath && config.scriptPath.length > 0) {
-		return config.scriptPath;
-	}
-	return process.env[POST_CHECK_SCRIPT_ENV];
-}
-
-/**
- * Run a post-task backpressure check script.
- *
- * Executes the configured bash script and returns a structured result.
- * If no script path is available (neither config nor env var), the check
- * passes by default with a note.
- *
- * **Security note:** The script path is validated to stay within `cwd`.
- * Scripts that escape the working directory are rejected.
- *
- * @param config - Post-check configuration (script path and timeout)
- * @param cwd - Working directory for script execution
- * @returns PostCheckResult with pass/fail status, output, and timing
- */
-export async function runPostCheck(config: PostCheckConfig, cwd: string): Promise<PostCheckResult> {
-	const scriptPath = resolveScriptPath(config);
-	const timeoutMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
-
-	if (!scriptPath) {
-		return {
-			passed: true,
-			output: "No post-check script configured; skipping.",
-			durationMs: 0,
-			timedOut: false,
-		};
-	}
-
-	// M-1 fix (code-review 2026-06-23): use the project's safe-path primitive instead
-	// of a hand-rolled path.resolve + startsWith check. The lexical check passed a
-	// symlinked cwd/scripts -> /usr/local/bin, but execFileSync followed the symlink
-	// and executed a script outside the working directory. resolveRealContainedPath
-	// walks ancestors with O_NOFOLLOW and re-validates after realpath, defeating
-	// symlink-traversal attacks. Throws if the resolved path escapes cwd.
-	resolveRealContainedPath(cwd, scriptPath);
-
-	const startTime = Date.now();
-
-	return new Promise<PostCheckResult>((resolve) => {
-		try {
-			const { command, args } = resolveShellForScript(scriptPath);
-			const output = execFileSync(command, args, {
-				cwd,
-				timeout: timeoutMs,
-				encoding: "utf-8",
-				maxBuffer: 10 * 1024 * 1024, // 10 MB
-				env: {
-					...sanitizeEnvSecrets(process.env, {
-						allowList: ["PATH", "HOME", "USER", ...WINDOWS_ESSENTIAL_ENV_VARS, "TMPDIR", "LANG", "LC_ALL", "PI_CREW_*"],
-					}),
-					PI_CREW_POST_CHECK: "1",
-				},
-			});
-
-			const durationMs = Date.now() - startTime;
-			resolve({
-				passed: true,
-				output: output.trim(),
-				durationMs,
-				timedOut: false,
-			});
-		} catch (error: unknown) {
-			const durationMs = Date.now() - startTime;
-
-			// Determine if this was a timeout
-			// execFileSync throws with code 'ETIMEDOUT' or sets killed:true on timeout
-			const isTimedOut =
-				Boolean((error as NodeJS.ErrnoException & { killed?: boolean }).killed) ||
-				(error as NodeJS.ErrnoException).code === "ETIMEDOUT";
-
-			let output = "";
-			if (error instanceof Error) {
-				const execError = error as NodeJS.ErrnoException & {
-					stdout?: string;
-					stderr?: string;
-				};
-				output = [execError.stdout ?? "", execError.stderr ?? "", execError.message ?? ""].join("\n").trim();
-			} else {
-				output = String(error);
-			}
-
-			resolve({
-				passed: false,
-				output,
-				durationMs,
-				timedOut: isTimedOut,
-			});
-		}
-	});
-}

package/src/runtime/post-exit-stdio-guard.ts

@@ -1,104 +0,0 @@
-import type { ChildProcess } from "node:child_process";
-
-interface PostExitStdioGuardOptions {
-	idleMs: number;
-	hardMs: number;
-}
-
-export interface ChildWithPipedStdio {
-	stdout: ChildProcess["stdout"];
-	stderr: ChildProcess["stderr"];
-	on: ChildProcess["on"];
-	/** Set by Node after the child exits. Used to detect a post-exit attach. */
-	exitCode?: number | null;
-	signalCode?: NodeJS.Signals | null;
-}
-
-export interface ChildWithKill {
-	kill(signal?: NodeJS.Signals | number): boolean;
-}
-
-export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
-	try {
-		return child.kill(signal);
-	} catch {
-		return false;
-	}
-}
-
-export function attachPostExitStdioGuard(child: ChildWithPipedStdio, options: PostExitStdioGuardOptions): () => void {
-	const { idleMs, hardMs } = options;
-	let exited = false;
-	let stdoutEnded = false;
-	let stderrEnded = false;
-	let idleTimer: ReturnType<typeof setTimeout> | undefined;
-	let hardTimer: ReturnType<typeof setTimeout> | undefined;
-
-	const destroyUnendedStdio = (): void => {
-		if (!stdoutEnded) {
-			try {
-				child.stdout?.destroy();
-			} catch {}
-		}
-		if (!stderrEnded) {
-			try {
-				child.stderr?.destroy();
-			} catch {}
-		}
-	};
-
-	const clearTimers = (): void => {
-		if (idleTimer) {
-			clearTimeout(idleTimer);
-			idleTimer = undefined;
-		}
-		if (hardTimer) {
-			clearTimeout(hardTimer);
-			hardTimer = undefined;
-		}
-	};
-
-	const armIdleTimer = () => {
-		if (!exited) return;
-		if (idleTimer) clearTimeout(idleTimer);
-		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
-		idleTimer.unref();
-	};
-
-	child.stdout?.on("data", armIdleTimer);
-	child.stderr?.on("data", armIdleTimer);
-	child.stdout?.on("end", () => {
-		stdoutEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-	child.stderr?.on("end", () => {
-		stderrEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-
-	const armHardTimer = (): void => {
-		if (hardTimer) return;
-		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
-		hardTimer.unref();
-	};
-	const onExit = (): void => {
-		exited = true;
-		armIdleTimer();
-		armHardTimer();
-	};
-	// The guard is normally attached from INSIDE the child's 'exit' handler
-	// (child-pi.ts), i.e. AFTER the child has already exited. A listener
-	// registered with child.on('exit') during the in-flight 'exit' dispatch
-	// will NOT fire (Node clones the listener array before iterating), so
-	// relying on it alone makes this guard a no-op and can hang the run if a
-	// descendant process holds the stdio pipes open. When a prior exit is
-	// detectable (exitCode/signalCode already set by Node), arm immediately.
-	if (child.exitCode != null || child.signalCode != null) {
-		onExit();
-	}
-	child.on("exit", onExit);
-	child.on("close", clearTimers);
-	child.on("error", clearTimers);
-
-	return clearTimers;
-}