pi-crew 0.2.3 → 0.2.4

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,81 +1,81 @@
-import { sleep } from "../utils/sleep.ts";
-import { throwIfCancelled } from "./cancellation.ts";
-
-export interface RetryPolicy {
-	maxAttempts: number;
-	backoffMs: number;
-	jitterRatio: number;
-	exponentialFactor: number;
-	retryableErrors?: string[];
-}
-
-export interface RetryAttemptInfo {
-	attempt: number;
-	attemptId: string;
-}
-
-export interface RetryHooks {
-	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number, info: RetryAttemptInfo) => void;
-	onRetryGivenUp?: (attempts: number, error: Error, info: RetryAttemptInfo) => void;
-	attemptId?: (attempt: number) => string;
-	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);
-}
-
-function retryAttemptInfo(attempt: number, hooks: RetryHooks): RetryAttemptInfo {
-	return { attempt, attemptId: hooks.attemptId?.(attempt) ?? `retry_attempt_${attempt}` };
-}
-
-export async function executeWithRetry<T>(fn: (attempt: number, info: RetryAttemptInfo) => 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) {
-		throwIfCancelled(hooks.signal);
-		const info = retryAttemptInfo(attempt, hooks);
-		try {
-			return await fn(attempt, info);
-		} catch (error) {
-			lastError = asError(error);
-			// Never retry if aborted — sleep() would immediately reject on every attempt.
-			if (hooks.signal?.aborted) {
-				hooks.onRetryGivenUp?.(attempt, lastError, info);
-				throw lastError;
-			}
-			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
-				hooks.onRetryGivenUp?.(attempt, lastError, info);
-				throw lastError;
-			}
-			const delay = calculateRetryDelay(attempt, normalized);
-			hooks.onAttemptFailed?.(attempt, lastError, delay, info);
-			try {
-				await sleep(delay, hooks.signal);
-			} catch (sleepError) {
-				if (hooks.signal?.aborted) throwIfCancelled(hooks.signal);
-				throw sleepError;
-			}
-		}
-	}
-	throw lastError ?? new Error("Retry failed without error.");
-}
+import { sleep } from "../utils/sleep.ts";
+import { throwIfCancelled } from "./cancellation.ts";
+
+export interface RetryPolicy {
+	maxAttempts: number;
+	backoffMs: number;
+	jitterRatio: number;
+	exponentialFactor: number;
+	retryableErrors?: string[];
+}
+
+export interface RetryAttemptInfo {
+	attempt: number;
+	attemptId: string;
+}
+
+export interface RetryHooks {
+	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number, info: RetryAttemptInfo) => void;
+	onRetryGivenUp?: (attempts: number, error: Error, info: RetryAttemptInfo) => void;
+	attemptId?: (attempt: number) => string;
+	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);
+}
+
+function retryAttemptInfo(attempt: number, hooks: RetryHooks): RetryAttemptInfo {
+	return { attempt, attemptId: hooks.attemptId?.(attempt) ?? `retry_attempt_${attempt}` };
+}
+
+export async function executeWithRetry<T>(fn: (attempt: number, info: RetryAttemptInfo) => 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) {
+		throwIfCancelled(hooks.signal);
+		const info = retryAttemptInfo(attempt, hooks);
+		try {
+			return await fn(attempt, info);
+		} catch (error) {
+			lastError = asError(error);
+			// Never retry if aborted — sleep() would immediately reject on every attempt.
+			if (hooks.signal?.aborted) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			const delay = calculateRetryDelay(attempt, normalized);
+			hooks.onAttemptFailed?.(attempt, lastError, delay, info);
+			try {
+				await sleep(delay, hooks.signal);
+			} catch (sleepError) {
+				if (hooks.signal?.aborted) throwIfCancelled(hooks.signal);
+				throw sleepError;
+			}
+		}
+	}
+	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 };
+}

package/src/runtime/run-tracker.ts

@@ -0,0 +1,99 @@
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { loadRunManifestById } from "../state/state-store.ts";
+import { isFinishedRunStatus } from "./process-status.ts";
+
+export interface ActiveRunPromise {
+	promise: Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }>;
+	resolve: (value: { manifest: TeamRunManifest; tasks: TeamTaskState[] }) => void;
+	reject: (reason: unknown) => void;
+}
+
+const activeRunPromises = new Map<string, ActiveRunPromise>();
+
+export function registerRunPromise(runId: string): ActiveRunPromise {
+	let resolve!: (value: { manifest: TeamRunManifest; tasks: TeamTaskState[] }) => void;
+	let reject!: (reason: unknown) => void;
+	const promise = new Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }>((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	const entry: ActiveRunPromise = { promise, resolve, reject };
+	activeRunPromises.set(runId, entry);
+	return entry;
+}
+
+export function resolveRunPromise(runId: string, result: { manifest: TeamRunManifest; tasks: TeamTaskState[] }): void {
+	const entry = activeRunPromises.get(runId);
+	if (entry) {
+		entry.resolve(result);
+		activeRunPromises.delete(runId);
+	}
+}
+
+export function rejectRunPromise(runId: string, reason: unknown): void {
+	const entry = activeRunPromises.get(runId);
+	if (entry) {
+		entry.reject(reason);
+		activeRunPromises.delete(runId);
+	}
+}
+
+/**
+ * Wait for a team run to reach a terminal status.
+ * - If the run is already finished on disk, returns immediately.
+ * - If a foreground promise is registered for this runId, awaits it.
+ * - Otherwise falls back to lightweight fs.watchFile-based waiting.
+ */
+export async function waitForRun(
+	runId: string,
+	cwd: string,
+	options: { timeoutMs?: number; pollIntervalMs?: number } = {},
+): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	const { timeoutMs = 300_000, pollIntervalMs = 500 } = options;
+	const deadline = Date.now() + timeoutMs;
+
+	// Fast path: already terminal on disk
+	const loaded = loadRunManifestById(cwd, runId);
+	if (loaded && isFinishedRunStatus(loaded.manifest.status)) {
+		return loaded;
+	}
+
+	// Medium path: foreground promise registered in this process
+	const entry = activeRunPromises.get(runId);
+	if (entry) {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const timeoutPromise = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => reject(new Error(`waitForRun timed out after ${timeoutMs}ms`)), timeoutMs);
+		});
+		try {
+			return await Promise.race([entry.promise, timeoutPromise]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	// Slow path: background run — poll with exponential backoff capped at pollIntervalMs
+	let attempt = 0;
+	while (Date.now() < deadline) {
+		const fresh = loadRunManifestById(cwd, runId);
+		if (fresh && isFinishedRunStatus(fresh.manifest.status)) {
+			return fresh;
+		}
+		const delay = Math.min(pollIntervalMs, 50 * 2 ** Math.min(attempt, 6)); // max ~3.2s
+		await new Promise((r) => setTimeout(r, delay));
+		attempt++;
+	}
+
+	throw new Error(`waitForRun timed out after ${timeoutMs}ms`);
+}
+
+export function hasActiveRunPromise(runId: string): boolean {
+	return activeRunPromises.has(runId);
+}
+
+export function clearRunPromisesForTest(): void {
+	for (const entry of activeRunPromises.values()) {
+		entry.reject(new Error("Cleared by test"));
+	}
+	activeRunPromises.clear();
+}

package/src/runtime/runtime-policy.ts

@@ -0,0 +1,21 @@
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
+import { currentCrewDepth } from "./pi-args.ts";
+
+/**
+ * Resolve the effective runtime kind for a given task role using isolation policy.
+ * - scaffold is never overridden — scaffold stays scaffold.
+ * - If already nested (PI_CREW_DEPTH > 0), force child-process to avoid live-session nesting issues.
+ * - If the role appears in `isolationPolicy.isolatedRoles`, use child-process (crash isolation).
+ * - Otherwise, use `isolationPolicy.defaultRuntime` when configured, then fall back to globalKind.
+ */
+export function resolveTaskRuntimeKind(globalKind: CrewRuntimeKind, role: string, isolationPolicy: CrewRuntimeConfig["isolationPolicy"], env: NodeJS.ProcessEnv = process.env): CrewRuntimeKind {
+	if (globalKind === "scaffold") return "scaffold";
+	// Safety: when already inside a pi-crew worker (depth > 0), never nest live-session.
+	// Live-session creates in-process Pi agent sessions, which would recursively
+	// try to use pi-crew, leading to "Cannot read properties of undefined" errors.
+	if (globalKind === "live-session" && currentCrewDepth(env) > 0) return "child-process";
+	const isolatedRoles = isolationPolicy?.isolatedRoles ?? [];
+	if (isolatedRoles.includes(role)) return "child-process";
+	return isolationPolicy?.defaultRuntime ?? globalKind;
+}