pi-crew 0.9.53 → 0.9.55

package/src/runtime/plan-templates.ts

@@ -0,0 +1,201 @@
+/**
+ * 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

@@ -0,0 +1,115 @@
+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

@@ -0,0 +1,142 @@
+/**
+ * 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

@@ -0,0 +1,109 @@
+import type { ChildProcess } from "node:child_process";
+import { logInternalError } from "../utils/internal-error.ts";
+
+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 (error) {
+				logInternalError("post-exit-stdio-guard.stdout-destroy", error, undefined, "debug");
+			}
+		}
+		if (!stderrEnded) {
+			try {
+				child.stderr?.destroy();
+			} catch (error) {
+				logInternalError("post-exit-stdio-guard.stderr-destroy", error, undefined, "debug");
+			}
+		}
+	};
+
+	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;
+}