pi-crew 0.1.44 → 0.1.45

package/src/runtime/policy-engine.ts

@@ -1,79 +1,79 @@
-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}`);
-}
+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/progress-event-coalescer.ts

@@ -1,43 +1,43 @@
-export interface ProgressEventSummary {
-	eventType: string;
-	currentTool?: string;
-	toolCount?: number;
-	tokens?: number;
-	turns?: number;
-	activityState?: string;
-	lastActivityAt?: string;
-}
-
-export interface ProgressEventCoalesceDecision {
-	shouldAppend: boolean;
-	reason: string;
-}
-
-export interface ProgressEventCoalesceInput {
-	previous?: ProgressEventSummary;
-	next: ProgressEventSummary;
-	nowMs: number;
-	lastAppendMs?: number;
-	minIntervalMs: number;
-	force?: boolean;
-	tokenThreshold?: number;
-}
-
-const DEFAULT_TOKEN_THRESHOLD = 256;
-
-function numericIncrease(previous: number | undefined, next: number | undefined): number {
-	return next !== undefined && previous !== undefined ? next - previous : next !== undefined ? next : 0;
-}
-
-export function shouldAppendProgressEventUpdate(input: ProgressEventCoalesceInput): ProgressEventCoalesceDecision {
-	if (input.force) return { shouldAppend: true, reason: "force" };
-	if (!input.previous) return { shouldAppend: true, reason: "first" };
-	if (input.previous.activityState !== input.next.activityState) return { shouldAppend: true, reason: "activity_changed" };
-	if (input.previous.currentTool !== input.next.currentTool) return { shouldAppend: true, reason: "tool_changed" };
-	if (numericIncrease(input.previous.toolCount, input.next.toolCount) > 0) return { shouldAppend: true, reason: "tool_count_increased" };
-	if (numericIncrease(input.previous.turns, input.next.turns) > 0) return { shouldAppend: true, reason: "turns_increased" };
-	const tokenIncrease = numericIncrease(input.previous.tokens, input.next.tokens);
-	if (tokenIncrease >= (input.tokenThreshold ?? DEFAULT_TOKEN_THRESHOLD)) return { shouldAppend: true, reason: "tokens_increased" };
-	if (input.lastAppendMs === undefined || input.nowMs - input.lastAppendMs >= input.minIntervalMs) return { shouldAppend: true, reason: "interval" };
-	return { shouldAppend: false, reason: "coalesced" };
-}
+export interface ProgressEventSummary {
+	eventType: string;
+	currentTool?: string;
+	toolCount?: number;
+	tokens?: number;
+	turns?: number;
+	activityState?: string;
+	lastActivityAt?: string;
+}
+
+export interface ProgressEventCoalesceDecision {
+	shouldAppend: boolean;
+	reason: string;
+}
+
+export interface ProgressEventCoalesceInput {
+	previous?: ProgressEventSummary;
+	next: ProgressEventSummary;
+	nowMs: number;
+	lastAppendMs?: number;
+	minIntervalMs: number;
+	force?: boolean;
+	tokenThreshold?: number;
+}
+
+const DEFAULT_TOKEN_THRESHOLD = 256;
+
+function numericIncrease(previous: number | undefined, next: number | undefined): number {
+	return next !== undefined && previous !== undefined ? next - previous : next !== undefined ? next : 0;
+}
+
+export function shouldAppendProgressEventUpdate(input: ProgressEventCoalesceInput): ProgressEventCoalesceDecision {
+	if (input.force) return { shouldAppend: true, reason: "force" };
+	if (!input.previous) return { shouldAppend: true, reason: "first" };
+	if (input.previous.activityState !== input.next.activityState) return { shouldAppend: true, reason: "activity_changed" };
+	if (input.previous.currentTool !== input.next.currentTool) return { shouldAppend: true, reason: "tool_changed" };
+	if (numericIncrease(input.previous.toolCount, input.next.toolCount) > 0) return { shouldAppend: true, reason: "tool_count_increased" };
+	if (numericIncrease(input.previous.turns, input.next.turns) > 0) return { shouldAppend: true, reason: "turns_increased" };
+	const tokenIncrease = numericIncrease(input.previous.tokens, input.next.tokens);
+	if (tokenIncrease >= (input.tokenThreshold ?? DEFAULT_TOKEN_THRESHOLD)) return { shouldAppend: true, reason: "tokens_increased" };
+	if (input.lastAppendMs === undefined || input.nowMs - input.lastAppendMs >= input.minIntervalMs) return { shouldAppend: true, reason: "interval" };
+	return { shouldAppend: false, reason: "coalesced" };
+}

package/src/runtime/recovery-recipes.ts

@@ -1,74 +1,74 @@
-import type { PolicyDecision, PolicyDecisionReason } from "../state/types.ts";
-
-export type FailureScenario = "trust_prompt_unresolved" | "prompt_misdelivery" | "stale_branch" | "compile_red_cross_crate" | "mcp_handshake_failure" | "partial_plugin_startup" | "provider_failure" | "task_failed" | "worker_stale" | "green_unsatisfied";
-export type RecoveryStep = "accept_trust_prompt" | "redirect_prompt_to_agent" | "rebase_branch" | "clean_build" | "retry_mcp_handshake" | "restart_plugin" | "restart_worker" | "rerun_task" | "collect_verification_evidence" | "escalate_to_human";
-export type RecoveryResultState = "planned" | "skipped" | "escalation_required";
-
-export interface RecoveryRecipe {
-	scenario: FailureScenario;
-	steps: RecoveryStep[];
-	maxAttempts: number;
-	escalationPolicy: "alert_human" | "log_and_continue" | "abort";
-}
-
-export interface RecoveryLedgerEntry {
-	scenario: FailureScenario;
-	taskId?: string;
-	decisionReason: PolicyDecisionReason;
-	attempt: number;
-	state: RecoveryResultState;
-	steps: RecoveryStep[];
-	message: string;
-	createdAt: string;
-}
-
-export interface RecoveryLedger {
-	entries: RecoveryLedgerEntry[];
-}
-
-export function scenarioForPolicyReason(reason: PolicyDecisionReason): FailureScenario {
-	switch (reason) {
-		case "branch_stale": return "stale_branch";
-		case "worker_stale": return "worker_stale";
-		case "green_unsatisfied": return "green_unsatisfied";
-		case "task_failed": return "task_failed";
-		default: return "provider_failure";
-	}
-}
-
-export function recipeFor(scenario: FailureScenario): RecoveryRecipe {
-	switch (scenario) {
-		case "trust_prompt_unresolved": return { scenario, steps: ["accept_trust_prompt"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "prompt_misdelivery": return { scenario, steps: ["redirect_prompt_to_agent"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "stale_branch": return { scenario, steps: ["rebase_branch", "clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "compile_red_cross_crate": return { scenario, steps: ["clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "mcp_handshake_failure": return { scenario, steps: ["retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "abort" };
-		case "partial_plugin_startup": return { scenario, steps: ["restart_plugin", "retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "log_and_continue" };
-		case "worker_stale": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "green_unsatisfied": return { scenario, steps: ["collect_verification_evidence"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "task_failed": return { scenario, steps: ["rerun_task"], maxAttempts: 1, escalationPolicy: "alert_human" };
-		case "provider_failure": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
-	}
-}
-
-export function buildRecoveryLedger(decisions: PolicyDecision[], previous: RecoveryLedger = { entries: [] }): RecoveryLedger {
-	const entries = [...previous.entries];
-	for (const item of decisions) {
-		if (!["retry", "escalate", "block"].includes(item.action)) continue;
-		const scenario = scenarioForPolicyReason(item.reason);
-		const recipe = recipeFor(scenario);
-		const priorAttempts = entries.filter((entry) => entry.scenario === scenario && entry.taskId === item.taskId).length;
-		const attempt = priorAttempts + 1;
-		entries.push({
-			scenario,
-			taskId: item.taskId,
-			decisionReason: item.reason,
-			attempt,
-			state: attempt <= recipe.maxAttempts && item.action !== "block" ? "planned" : "escalation_required",
-			steps: attempt <= recipe.maxAttempts ? recipe.steps : ["escalate_to_human"],
-			message: item.message,
-			createdAt: new Date().toISOString(),
-		});
-	}
-	return { entries };
-}
+import type { PolicyDecision, PolicyDecisionReason } from "../state/types.ts";
+
+export type FailureScenario = "trust_prompt_unresolved" | "prompt_misdelivery" | "stale_branch" | "compile_red_cross_crate" | "mcp_handshake_failure" | "partial_plugin_startup" | "provider_failure" | "task_failed" | "worker_stale" | "green_unsatisfied";
+export type RecoveryStep = "accept_trust_prompt" | "redirect_prompt_to_agent" | "rebase_branch" | "clean_build" | "retry_mcp_handshake" | "restart_plugin" | "restart_worker" | "rerun_task" | "collect_verification_evidence" | "escalate_to_human";
+export type RecoveryResultState = "planned" | "skipped" | "escalation_required";
+
+export interface RecoveryRecipe {
+	scenario: FailureScenario;
+	steps: RecoveryStep[];
+	maxAttempts: number;
+	escalationPolicy: "alert_human" | "log_and_continue" | "abort";
+}
+
+export interface RecoveryLedgerEntry {
+	scenario: FailureScenario;
+	taskId?: string;
+	decisionReason: PolicyDecisionReason;
+	attempt: number;
+	state: RecoveryResultState;
+	steps: RecoveryStep[];
+	message: string;
+	createdAt: string;
+}
+
+export interface RecoveryLedger {
+	entries: RecoveryLedgerEntry[];
+}
+
+export function scenarioForPolicyReason(reason: PolicyDecisionReason): FailureScenario {
+	switch (reason) {
+		case "branch_stale": return "stale_branch";
+		case "worker_stale": return "worker_stale";
+		case "green_unsatisfied": return "green_unsatisfied";
+		case "task_failed": return "task_failed";
+		default: return "provider_failure";
+	}
+}
+
+export function recipeFor(scenario: FailureScenario): RecoveryRecipe {
+	switch (scenario) {
+		case "trust_prompt_unresolved": return { scenario, steps: ["accept_trust_prompt"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "prompt_misdelivery": return { scenario, steps: ["redirect_prompt_to_agent"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "stale_branch": return { scenario, steps: ["rebase_branch", "clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "compile_red_cross_crate": return { scenario, steps: ["clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "mcp_handshake_failure": return { scenario, steps: ["retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "abort" };
+		case "partial_plugin_startup": return { scenario, steps: ["restart_plugin", "retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "log_and_continue" };
+		case "worker_stale": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "green_unsatisfied": return { scenario, steps: ["collect_verification_evidence"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "task_failed": return { scenario, steps: ["rerun_task"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "provider_failure": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
+	}
+}
+
+export function buildRecoveryLedger(decisions: PolicyDecision[], previous: RecoveryLedger = { entries: [] }): RecoveryLedger {
+	const entries = [...previous.entries];
+	for (const item of decisions) {
+		if (!["retry", "escalate", "block"].includes(item.action)) continue;
+		const scenario = scenarioForPolicyReason(item.reason);
+		const recipe = recipeFor(scenario);
+		const priorAttempts = entries.filter((entry) => entry.scenario === scenario && entry.taskId === item.taskId).length;
+		const attempt = priorAttempts + 1;
+		entries.push({
+			scenario,
+			taskId: item.taskId,
+			decisionReason: item.reason,
+			attempt,
+			state: attempt <= recipe.maxAttempts && item.action !== "block" ? "planned" : "escalation_required",
+			steps: attempt <= recipe.maxAttempts ? recipe.steps : ["escalate_to_human"],
+			message: item.message,
+			createdAt: new Date().toISOString(),
+		});
+	}
+	return { entries };
+}

package/src/runtime/retry-executor.ts

@@ -1,64 +1,64 @@
-import { sleep } from "../utils/sleep.ts";
-
-export interface RetryPolicy {
-	maxAttempts: number;
-	backoffMs: number;
-	jitterRatio: number;
-	exponentialFactor: number;
-	retryableErrors?: string[];
-}
-
-export interface RetryHooks {
-	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number) => void;
-	onRetryGivenUp?: (attempts: number, error: Error) => void;
-	signal?: AbortSignal;
-}
-
-export const DEFAULT_RETRY_POLICY: RetryPolicy = { maxAttempts: 3, backoffMs: 1000, jitterRatio: 0.3, exponentialFactor: 2 };
-
-function asError(error: unknown): Error {
-	return error instanceof Error ? error : new Error(String(error));
-}
-
-function globToRegex(pattern: string): RegExp {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-	return new RegExp(`^${escaped}$`, "i");
-}
-
-function isRetryable(error: Error, policy: RetryPolicy): boolean {
-	const patterns = policy.retryableErrors ?? [];
-	if (!patterns.length) return true;
-	return patterns.some((pattern) => globToRegex(pattern).test(error.message));
-}
-
-export function calculateRetryDelay(attempt: number, policy: RetryPolicy = DEFAULT_RETRY_POLICY, random = Math.random): number {
-	const base = policy.backoffMs * Math.pow(policy.exponentialFactor, Math.max(0, attempt - 1));
-	const jitter = (random() * 2 - 1) * policy.jitterRatio * base;
-	return Math.max(0, base + jitter);
-}
-
-export async function executeWithRetry<T>(fn: (attempt: number) => Promise<T>, policy: RetryPolicy = DEFAULT_RETRY_POLICY, hooks: RetryHooks = {}): Promise<T> {
-	const normalized: RetryPolicy = { ...DEFAULT_RETRY_POLICY, ...policy, maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts) };
-	let lastError: Error | undefined;
-	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
-		if (hooks.signal?.aborted) throw new Error("Retry aborted.");
-		try {
-			return await fn(attempt);
-		} catch (error) {
-			lastError = asError(error);
-			// Never retry if aborted — sleep() would immediately reject on every attempt.
-			if (hooks.signal?.aborted) {
-				hooks.onRetryGivenUp?.(attempt, lastError);
-				throw lastError;
-			}
-			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
-				hooks.onRetryGivenUp?.(attempt, lastError);
-				throw lastError;
-			}
-			const delay = calculateRetryDelay(attempt, normalized);
-			hooks.onAttemptFailed?.(attempt, lastError, delay);
-			await sleep(delay, hooks.signal);
-		}
-	}
-	throw lastError ?? new Error("Retry failed without error.");
-}
+import { sleep } from "../utils/sleep.ts";
+
+export interface RetryPolicy {
+	maxAttempts: number;
+	backoffMs: number;
+	jitterRatio: number;
+	exponentialFactor: number;
+	retryableErrors?: string[];
+}
+
+export interface RetryHooks {
+	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number) => void;
+	onRetryGivenUp?: (attempts: number, error: Error) => void;
+	signal?: AbortSignal;
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = { maxAttempts: 3, backoffMs: 1000, jitterRatio: 0.3, exponentialFactor: 2 };
+
+function asError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+function globToRegex(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+function isRetryable(error: Error, policy: RetryPolicy): boolean {
+	const patterns = policy.retryableErrors ?? [];
+	if (!patterns.length) return true;
+	return patterns.some((pattern) => globToRegex(pattern).test(error.message));
+}
+
+export function calculateRetryDelay(attempt: number, policy: RetryPolicy = DEFAULT_RETRY_POLICY, random = Math.random): number {
+	const base = policy.backoffMs * Math.pow(policy.exponentialFactor, Math.max(0, attempt - 1));
+	const jitter = (random() * 2 - 1) * policy.jitterRatio * base;
+	return Math.max(0, base + jitter);
+}
+
+export async function executeWithRetry<T>(fn: (attempt: number) => Promise<T>, policy: RetryPolicy = DEFAULT_RETRY_POLICY, hooks: RetryHooks = {}): Promise<T> {
+	const normalized: RetryPolicy = { ...DEFAULT_RETRY_POLICY, ...policy, maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts) };
+	let lastError: Error | undefined;
+	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
+		if (hooks.signal?.aborted) throw new Error("Retry aborted.");
+		try {
+			return await fn(attempt);
+		} catch (error) {
+			lastError = asError(error);
+			// Never retry if aborted — sleep() would immediately reject on every attempt.
+			if (hooks.signal?.aborted) {
+				hooks.onRetryGivenUp?.(attempt, lastError);
+				throw lastError;
+			}
+			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
+				hooks.onRetryGivenUp?.(attempt, lastError);
+				throw lastError;
+			}
+			const delay = calculateRetryDelay(attempt, normalized);
+			hooks.onAttemptFailed?.(attempt, lastError, delay);
+			await sleep(delay, hooks.signal);
+		}
+	}
+	throw lastError ?? new Error("Retry failed without error.");
+}

package/src/runtime/role-permission.ts

@@ -1,39 +1,39 @@
-export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
-
-const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner", "writer"]);
-const WRITE_ROLES = new Set(["executor", "test-engineer"]);
-const READ_ONLY_COMMANDS = new Set(["cat", "head", "tail", "less", "more", "wc", "ls", "find", "grep", "rg", "awk", "sed", "echo", "printf", "which", "where", "whoami", "pwd", "env", "printenv", "date", "df", "du", "uname", "file", "stat", "diff", "sort", "uniq", "tr", "cut", "paste", "test", "true", "false", "type", "readlink", "realpath", "basename", "dirname", "sha256sum", "md5sum", "xxd", "hexdump", "od", "strings", "tree", "jq", "git", "gh"]);
-
-export interface PermissionCheckResult {
-	allowed: boolean;
-	mode: RolePermissionMode;
-	reason?: string;
-}
-
-export function permissionForRole(role: string): RolePermissionMode {
-	if (READ_ONLY_ROLES.has(role)) return "read_only";
-	if (WRITE_ROLES.has(role)) return "workspace_write";
-	return "workspace_write";
-}
-
-export function isReadOnlyCommand(command: string): boolean {
-	const first = command.trim().split(/\s+/)[0]?.split(/[\\/]/).pop() ?? "";
-	return READ_ONLY_COMMANDS.has(first) && !/\s(-i|--in-place)\b|\s>{1,2}\s|\brm\b|\bmv\b|\bcp\b|\b(?:npm|pnpm|yarn|bun)\s+(install|add|ci|remove)\b|\bgit\s+(commit|push|merge|rebase|reset|checkout|clean)\b/.test(command);
-}
-
-export function checkRolePermission(role: string, command: string): PermissionCheckResult {
-	const mode = permissionForRole(role);
-	if (mode === "read_only" && !isReadOnlyCommand(command)) return { allowed: false, mode, reason: `Role '${role}' is read-only and command may modify state.` };
-	return { allowed: true, mode };
-}
-
-export function currentCrewRole(env: NodeJS.ProcessEnv = process.env): string | undefined {
-	return env.PI_CREW_ROLE?.trim() || env.PI_TEAMS_ROLE?.trim() || undefined;
-}
-
-export function checkSubagentSpawnPermission(role: string | undefined): PermissionCheckResult {
-	if (!role) return { allowed: true, mode: "workspace_write" };
-	const mode = permissionForRole(role);
-	if (mode === "read_only") return { allowed: false, mode, reason: `Role '${role}' is read-only and cannot spawn additional subagents.` };
-	return { allowed: true, mode };
-}
+export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
+
+const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner", "writer"]);
+const WRITE_ROLES = new Set(["executor", "test-engineer"]);
+const READ_ONLY_COMMANDS = new Set(["cat", "head", "tail", "less", "more", "wc", "ls", "find", "grep", "rg", "awk", "sed", "echo", "printf", "which", "where", "whoami", "pwd", "env", "printenv", "date", "df", "du", "uname", "file", "stat", "diff", "sort", "uniq", "tr", "cut", "paste", "test", "true", "false", "type", "readlink", "realpath", "basename", "dirname", "sha256sum", "md5sum", "xxd", "hexdump", "od", "strings", "tree", "jq", "git", "gh"]);
+
+export interface PermissionCheckResult {
+	allowed: boolean;
+	mode: RolePermissionMode;
+	reason?: string;
+}
+
+export function permissionForRole(role: string): RolePermissionMode {
+	if (READ_ONLY_ROLES.has(role)) return "read_only";
+	if (WRITE_ROLES.has(role)) return "workspace_write";
+	return "workspace_write";
+}
+
+export function isReadOnlyCommand(command: string): boolean {
+	const first = command.trim().split(/\s+/)[0]?.split(/[\\/]/).pop() ?? "";
+	return READ_ONLY_COMMANDS.has(first) && !/\s(-i|--in-place)\b|\s>{1,2}\s|\brm\b|\bmv\b|\bcp\b|\b(?:npm|pnpm|yarn|bun)\s+(install|add|ci|remove)\b|\bgit\s+(commit|push|merge|rebase|reset|checkout|clean)\b/.test(command);
+}
+
+export function checkRolePermission(role: string, command: string): PermissionCheckResult {
+	const mode = permissionForRole(role);
+	if (mode === "read_only" && !isReadOnlyCommand(command)) return { allowed: false, mode, reason: `Role '${role}' is read-only and command may modify state.` };
+	return { allowed: true, mode };
+}
+
+export function currentCrewRole(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env.PI_CREW_ROLE?.trim() || env.PI_TEAMS_ROLE?.trim() || undefined;
+}
+
+export function checkSubagentSpawnPermission(role: string | undefined): PermissionCheckResult {
+	if (!role) return { allowed: true, mode: "workspace_write" };
+	const mode = permissionForRole(role);
+	if (mode === "read_only") return { allowed: false, mode, reason: `Role '${role}' is read-only and cannot spawn additional subagents.` };
+	return { allowed: true, mode };
+}