pi-crew 0.1.41 → 0.1.44

package/src/runtime/process-status.ts

@@ -1,56 +1,56 @@
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-export { hasAsyncStartMarker } from "./async-marker.ts";
-
-export interface ProcessLiveness {
-	pid?: number;
-	alive: boolean;
-	detail: string;
-}
-
-const ORPHANED_ACTIVE_RUN_MS = 10 * 60 * 1000;
-
-export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
-	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
-		return { pid, alive: false, detail: "no pid recorded" };
-	}
-	try {
-		process.kill(pid, 0);
-		return { pid, alive: true, detail: "process is alive" };
-	} catch (error) {
-		const nodeError = error as NodeJS.ErrnoException;
-		if (nodeError.code === "EPERM") return { pid, alive: true, detail: "process exists but permission is denied" };
-		if (nodeError.code === "ESRCH") return { pid, alive: false, detail: "process does not exist" };
-		const message = error instanceof Error ? error.message : String(error);
-		return { pid, alive: false, detail: message };
-	}
-}
-
-export function isActiveRunStatus(status: string): boolean {
-	return status === "queued" || status === "planning" || status === "running";
-}
-
-export function isLikelyOrphanedActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now(), staleMs = ORPHANED_ACTIVE_RUN_MS): boolean {
-	if (!isActiveRunStatus(run.status)) return false;
-	if (run.async?.pid !== undefined) return false;
-	const updatedAt = new Date(run.updatedAt).getTime();
-	if (!Number.isFinite(updatedAt) || now - updatedAt < staleMs) return false;
-	if (agents.length === 0) return run.summary === "Creating workflow prompts and placeholder results.";
-	return agents.every((agent) => agent.status === "queued" && !agent.completedAt && !agent.progress);
-}
-
-function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
-	if (agent.status !== "running" && agent.status !== "queued") return false;
-	return Boolean(agent.statusPath || agent.eventsPath || agent.outputPath || agent.progress || agent.toolUses || agent.jsonEvents);
-}
-
-export function hasStaleAsyncProcess(run: TeamRunManifest): boolean {
-	if (!isActiveRunStatus(run.status) || !run.async) return false;
-	return !checkProcessLiveness(run.async.pid).alive;
-}
-
-export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
-	if (!isActiveRunStatus(run.status) || hasStaleAsyncProcess(run) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
-	if (agents.length === 0) return true;
-	return agents.some(hasDurableActiveAgentEvidence);
-}
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+export { hasAsyncStartMarker } from "./async-marker.ts";
+
+export interface ProcessLiveness {
+	pid?: number;
+	alive: boolean;
+	detail: string;
+}
+
+const ORPHANED_ACTIVE_RUN_MS = 10 * 60 * 1000;
+
+export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
+	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
+		return { pid, alive: false, detail: "no pid recorded" };
+	}
+	try {
+		process.kill(pid, 0);
+		return { pid, alive: true, detail: "process is alive" };
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code === "EPERM") return { pid, alive: true, detail: "process exists but permission is denied" };
+		if (nodeError.code === "ESRCH") return { pid, alive: false, detail: "process does not exist" };
+		const message = error instanceof Error ? error.message : String(error);
+		return { pid, alive: false, detail: message };
+	}
+}
+
+export function isActiveRunStatus(status: string): boolean {
+	return status === "queued" || status === "planning" || status === "running" || status === "waiting";
+}
+
+export function isLikelyOrphanedActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now(), staleMs = ORPHANED_ACTIVE_RUN_MS): boolean {
+	if (!isActiveRunStatus(run.status)) return false;
+	if (run.async?.pid !== undefined) return false;
+	const updatedAt = new Date(run.updatedAt).getTime();
+	if (!Number.isFinite(updatedAt) || now - updatedAt < staleMs) return false;
+	if (agents.length === 0) return run.summary === "Creating workflow prompts and placeholder results.";
+	return agents.every((agent) => agent.status === "queued" && !agent.completedAt && !agent.progress);
+}
+
+function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
+	if (agent.status !== "running" && agent.status !== "queued") return false;
+	return Boolean(agent.statusPath || agent.eventsPath || agent.outputPath || agent.progress || agent.toolUses || agent.jsonEvents);
+}
+
+export function hasStaleAsyncProcess(run: TeamRunManifest): boolean {
+	if (!isActiveRunStatus(run.status) || !run.async) return false;
+	return !checkProcessLiveness(run.async.pid).alive;
+}
+
+export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
+	if (!isActiveRunStatus(run.status) || hasStaleAsyncProcess(run) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
+	if (agents.length === 0) return true;
+	return agents.some(hasDurableActiveAgentEvidence);
+}

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

@@ -46,6 +46,11 @@ export async function executeWithRetry<T>(fn: (attempt: number) => Promise<T>, p
 			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;

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|\bnpm\s+install\b|\bgit\s+(commit|push|merge|rebase|reset|checkout)\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/runtime-resolver.ts

@@ -41,7 +41,7 @@ export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJ
 			probe(),
 			new Promise<{ available: boolean; reason: string }>((resolve) => {
 				timer = setTimeout(() => resolve({ available: false, reason: `Timed out probing optional Pi SDK live-session runtime after ${timeoutMs}ms.` }), timeoutMs);
-				timer.unref?.();
+				timer.unref();
 			}),
 		]);
 	} finally {

package/src/runtime/session-resources.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { logInternalError } from "../utils/internal-error.ts";
+
+/**
+ * Try to register a cleanup function with Pi's session resource cleanup API (v0.72+).
+ * Falls back to returning undefined if the API is not available.
+ *
+ * The returned function (if defined) can be called to unregister the cleanup.
+ */
+export function tryRegisterSessionCleanup(pi: ExtensionAPI, cleanup: () => void): (() => void) | undefined {
+	const api = pi as unknown as Record<string, unknown>;
+	const registerFn = api["registerSessionResourceCleanup"];
+	if (typeof registerFn === "function") {
+		try {
+			const unregister = (registerFn as (fn: () => void) => (() => void) | void)(cleanup);
+			if (typeof unregister === "function") return unregister;
+			// API returned void — cleanup is registered but cannot be unregistered
+			return undefined;
+		} catch (error) {
+			logInternalError("session-resources.register", error);
+			return undefined;
+		}
+	}
+	return undefined;
+}

package/src/runtime/session-snapshot.ts

@@ -0,0 +1,59 @@
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+
+/**
+ * Creates a lightweight snapshot of task state for event emission.
+ * Prevents mutation-during-callback issues by copying relevant fields.
+ */
+export function snapshotTaskState(task: TeamTaskState): Readonly<TeamTaskState> {
+	return {
+		...task,
+		dependsOn: [...task.dependsOn],
+		usage: task.usage ? { ...task.usage } : undefined,
+		agentProgress: task.agentProgress ? { ...task.agentProgress } : undefined,
+		heartbeat: task.heartbeat ? { ...task.heartbeat } : undefined,
+		modelAttempts: task.modelAttempts?.map((a) => ({ ...a })),
+		modelRouting: task.modelRouting ? { ...task.modelRouting } : undefined,
+		claim: task.claim ? { ...task.claim } : undefined,
+		checkpoint: task.checkpoint ? { ...task.checkpoint } : undefined,
+		attempts: task.attempts?.map((a) => ({ ...a })),
+		worktree: task.worktree ? { ...task.worktree } : undefined,
+	};
+}
+
+/**
+ * Session state snapshot for persistence before session switches.
+ * Captures the minimal set of data needed to resume operations.
+ */
+export interface SessionStateSnapshot {
+	/** ISO timestamp of the snapshot */
+	capturedAt: string;
+	/** Active run IDs at time of snapshot */
+	activeRunIds: string[];
+	/** Number of pending deliveries */
+	pendingDeliveryCount: number;
+	/** Session generation counter */
+	sessionGeneration: number;
+	/** Summary of active tasks by status */
+	taskSummary: Record<string, number>;
+}
+
+/**
+ * Create a session state snapshot for pre-switch persistence.
+ */
+export function createSessionSnapshot(
+	activeRuns: TeamRunManifest[],
+	pendingDeliveryCount: number,
+	sessionGeneration: number,
+): SessionStateSnapshot {
+	const taskSummary: Record<string, number> = {};
+	for (const run of activeRuns) {
+		taskSummary[run.status] = (taskSummary[run.status] ?? 0) + 1;
+	}
+	return {
+		capturedAt: new Date().toISOString(),
+		activeRunIds: activeRuns.map((r) => r.runId),
+		pendingDeliveryCount,
+		sessionGeneration,
+		taskSummary,
+	};
+}