pi-crew 0.1.43 → 0.1.44

package/src/runtime/overflow-recovery.ts

@@ -0,0 +1,157 @@
+import { logInternalError } from "../utils/internal-error.ts";
+
+export type OverflowPhase = "none" | "compaction" | "retrying" | "recovered" | "failed";
+
+export interface OverflowRecoveryState {
+	taskId: string;
+	runId: string;
+	phase: OverflowPhase;
+	startedAt: number;
+	lastEventAt: number;
+	compactionCount: number;
+	retryCount: number;
+}
+
+export interface OverflowRecoveryCallbacks {
+	onPhaseChange?: (state: OverflowRecoveryState, previousPhase: OverflowPhase) => void;
+	onTimeout?: (state: OverflowRecoveryState) => void;
+}
+
+const PHASE_TIMEOUT_MS = 120_000; // 120 seconds per phase
+
+export class OverflowRecoveryTracker {
+	private states = new Map<string, OverflowRecoveryState>();
+	private timers = new Map<string, ReturnType<typeof setTimeout>>();
+	private callbacks: OverflowRecoveryCallbacks;
+
+	constructor(callbacks: OverflowRecoveryCallbacks = {}) {
+		this.callbacks = callbacks;
+	}
+
+	feedEvent(taskId: string, runId: string, eventType: string): OverflowPhase {
+		const existing = this.states.get(taskId);
+		const now = Date.now();
+
+		if (existing && existing.phase === "recovered") {
+			existing.lastEventAt = now;
+			return "recovered";
+		}
+		if (existing && existing.phase === "failed") {
+			existing.lastEventAt = now;
+			return "failed";
+		}
+
+		let phase: OverflowPhase = existing?.phase ?? "none";
+		let compactionCount = existing?.compactionCount ?? 0;
+		let retryCount = existing?.retryCount ?? 0;
+		const previousPhase = phase;
+
+		switch (eventType) {
+			case "compaction_start":
+				phase = "compaction";
+				compactionCount++;
+				break;
+			case "compaction_end":
+				// After compaction, we expect a retry; stay in compaction until retry starts
+				break;
+			case "auto_retry_start":
+				phase = "retrying";
+				retryCount++;
+				break;
+			case "auto_retry_end":
+				// After retry completes, the agent should produce a response
+				// We consider this recovered but don't finalize until agent_end
+				phase = "recovered";
+				break;
+			case "agent_end":
+				// If we were recovering and agent ends, we're recovered or failed
+				if (phase === "compaction" || phase === "retrying") {
+					phase = "failed";
+				}
+				break;
+			default:
+				// Unknown event type — no phase change
+				break;
+		}
+
+		const state: OverflowRecoveryState = {
+			taskId,
+			runId,
+			phase,
+			startedAt: existing?.startedAt ?? now,
+			lastEventAt: now,
+			compactionCount,
+			retryCount,
+		};
+
+		this.states.set(taskId, state);
+		this.resetTimeout(taskId);
+
+		if (previousPhase !== phase && this.callbacks.onPhaseChange) {
+			try {
+				this.callbacks.onPhaseChange(state, previousPhase);
+			} catch (error) {
+				logInternalError("overflow-recovery.onPhaseChange", error, `taskId=${taskId}`);
+			}
+		}
+
+		return phase;
+	}
+
+	getState(taskId: string): OverflowRecoveryState | undefined {
+		return this.states.get(taskId);
+	}
+
+	getPhase(taskId: string): OverflowPhase {
+		return this.states.get(taskId)?.phase ?? "none";
+	}
+
+	removeTask(taskId: string): void {
+		this.states.delete(taskId);
+		const timer = this.timers.get(taskId);
+		if (timer) {
+			clearTimeout(timer);
+			this.timers.delete(taskId);
+		}
+	}
+
+	dispose(): void {
+		for (const timer of this.timers.values()) clearTimeout(timer);
+		this.timers.clear();
+		this.states.clear();
+	}
+
+	private resetTimeout(taskId: string): void {
+		const existing = this.timers.get(taskId);
+		if (existing) clearTimeout(existing);
+
+		const timer = setTimeout(() => {
+			this.timers.delete(taskId);
+			const state = this.states.get(taskId);
+			if (!state) return;
+			if (state.phase === "recovered" || state.phase === "failed" || state.phase === "none") return;
+
+			const previousPhase = state.phase;
+			state.phase = "failed";
+			state.lastEventAt = Date.now();
+
+			if (this.callbacks.onTimeout) {
+				try {
+					this.callbacks.onTimeout(state);
+				} catch (error) {
+					logInternalError("overflow-recovery.onTimeout", error, `taskId=${taskId}`);
+				}
+			}
+			if (this.callbacks.onPhaseChange) {
+				try {
+					this.callbacks.onPhaseChange(state, previousPhase);
+				} catch (error) {
+					logInternalError("overflow-recovery.onPhaseChange-timeout", error, `taskId=${taskId}`);
+				}
+			}
+		}, PHASE_TIMEOUT_MS);
+
+		timer.unref();
+		this.timers.set(taskId, timer);
+	}
+}

package/src/runtime/process-status.ts

@@ -27,7 +27,7 @@ export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
 }
 
 export function isActiveRunStatus(status: string): boolean {
-	return status === "queued" || status === "planning" || status === "running";
+	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 {

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,
+	};
+}

package/src/runtime/stale-reconciler.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { checkProcessLiveness } from "./process-status.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { writeAtomicJson } from "../utils/atomic-write.ts";
+
+/**
+ * Result of reconciling a single stale run.
+ */
+export interface ReconcileResult {
+	runId: string;
+	/** What was found and what action was taken */
+	verdict: "healthy" | "result_exists" | "pid_dead" | "pid_alive_stale" | "no_status";
+	/** Whether repair was applied */
+	repaired: boolean;
+	/** Human-readable detail */
+	detail: string;
+}
+
+const STALE_ALIVE_PID_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Phase 1: Check if a result file already exists for the run.
+ * If so, the run completed but status wasn't updated — repair it.
+ */
+function checkResultFile(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+): { found: boolean; repaired: boolean } {
+	// Check if all tasks already have terminal status (result was written but manifest wasn't updated)
+	const allTerminal = tasks.length > 0 && tasks.every(
+		(t) => t.status === "completed" || t.status === "failed" || t.status === "cancelled" || t.status === "skipped",
+	);
+	if (allTerminal) {
+		return { found: true, repaired: false };
+	}
+	return { found: false, repaired: false };
+}
+
+/**
+ * Phase 2: Check PID liveness.
+ */
+function checkPidLiveness(pid: number | undefined): {
+	alive: boolean;
+	detail: string;
+} {
+	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
+		return { alive: false, detail: "no pid recorded" };
+	}
+	const liveness = checkProcessLiveness(pid);
+	return { alive: liveness.alive, detail: liveness.detail };
+}
+
+/**
+ * Phase 3: For dead PIDs, repair immediately.
+ * For alive PIDs, only mark stale if status hasn't updated in STALE_ALIVE_PID_MS.
+ */
+function evaluateStaleness(
+	manifest: TeamRunManifest,
+	pidAlive: boolean,
+	now: number,
+): { stale: boolean; reason: string } {
+	if (!pidAlive) {
+		return { stale: true, reason: "pid_dead" };
+	}
+	const updatedAt = new Date(manifest.updatedAt).getTime();
+	if (!Number.isFinite(updatedAt)) {
+		return { stale: false, reason: "updated_at_invalid" };
+	}
+	if (now - updatedAt > STALE_ALIVE_PID_MS) {
+		return { stale: true, reason: `alive_but_stale_${Math.round((now - updatedAt) / 3600_000)}h` };
+	}
+	return { stale: false, reason: "alive_and_recent" };
+}
+
+/**
+ * Repair a stale run by marking it as failed and cancelling running tasks.
+ */
+function repairStaleRun(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	reason: string,
+): TeamTaskState[] {
+	const now = new Date().toISOString();
+	const repairedTasks = tasks.map((task) => {
+		if (task.status === "running" || task.status === "queued" || task.status === "waiting") {
+			return {
+				...task,
+				status: "cancelled" as const,
+				finishedAt: now,
+				error: `Stale run reconciled: ${reason}`,
+			};
+		}
+		return task;
+	});
+
+	// Write repaired tasks atomically
+	const tasksPath = manifest.tasksPath;
+	if (tasksPath) {
+		try {
+			writeAtomicJson(tasksPath, repairedTasks);
+		} catch (error) {
+			logInternalError("stale-reconciler.repair-tasks", error, `runId=${manifest.runId}`);
+		}
+	}
+
+	return repairedTasks;
+}
+
+/**
+ * Three-phase stale run reconciliation.
+ *
+ * 1. Check if result already exists → use it
+ * 2. Check PID liveness
+ * 3. Dead PID → repair immediately; alive PID → only fail if stale > 24h
+ */
+export function reconcileStaleRun(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	now = Date.now(),
+): ReconcileResult {
+	const runId = manifest.runId;
+
+	// Phase 1: Check if results already exist
+	const phase1 = checkResultFile(manifest, tasks);
+	if (phase1.found) {
+		return {
+			runId,
+			verdict: "result_exists",
+			repaired: false,
+			detail: "All tasks already terminal — no repair needed",
+		};
+	}
+
+	// Phase 2: Check PID liveness
+	const pid = manifest.async?.pid;
+	const pidStatus = checkPidLiveness(pid);
+
+	if (pidStatus.detail === "no pid recorded") {
+		// No async PID — not an async run, check updatedAt staleness
+		const updatedAt = new Date(manifest.updatedAt).getTime();
+		if (Number.isFinite(updatedAt) && now - updatedAt > STALE_ALIVE_PID_MS) {
+			const repaired = repairStaleRun(manifest, tasks, "no_pid_stale");
+			return {
+				runId,
+				verdict: "no_status",
+				repaired: true,
+				detail: `No PID; stale ${Math.round((now - updatedAt) / 3600_000)}h; repaired ${repaired.filter((t) => t.status === "cancelled").length} tasks`,
+			};
+		}
+		return {
+			runId,
+			verdict: "no_status",
+			repaired: false,
+			detail: "No PID recorded; not stale enough to repair",
+		};
+	}
+
+	// Phase 3: Evaluate staleness
+	const staleness = evaluateStaleness(manifest, pidStatus.alive, now);
+	if (!staleness.stale) {
+		return {
+			runId,
+			verdict: "healthy",
+			repaired: false,
+			detail: `PID ${pid}: ${pidStatus.detail}, ${staleness.reason}`,
+		};
+	}
+
+	// Repair
+	const repaired = repairStaleRun(manifest, tasks, staleness.reason);
+	return {
+		runId,
+		verdict: pidStatus.alive ? "pid_alive_stale" : "pid_dead",
+		repaired: true,
+		detail: `PID ${pid}: ${pidStatus.detail}; ${staleness.reason}; repaired ${repaired.filter((t) => t.status === "cancelled").length} tasks`,
+	};
+}

package/src/runtime/supervisor-contact.ts

@@ -0,0 +1,59 @@
+import type { TeamRunManifest } from "../state/types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface SupervisorContactPayload {
+	runId: string;
+	taskId: string;
+	reason: "decision_needed" | "clarification" | "approval" | "error_escalation" | "custom";
+	message: string;
+	data?: Record<string, unknown>;
+	timestamp: string;
+}
+
+/**
+ * Record a supervisor contact event from a child task.
+ * This represents a child→parent communication where the child needs
+ * a decision, clarification, or approval to continue.
+ */
+export function recordSupervisorContact(manifest: TeamRunManifest, payload: Omit<SupervisorContactPayload, "timestamp">): void {
+	const fullPayload: SupervisorContactPayload = {
+		...payload,
+		timestamp: new Date().toISOString(),
+	};
+	try {
+		appendEvent(manifest.eventsPath, {
+			type: "supervisor.contact",
+			runId: manifest.runId,
+			taskId: payload.taskId,
+			data: fullPayload as unknown as Record<string, unknown>,
+		});
+	} catch (error) {
+		logInternalError("supervisor-contact.record", error, `runId=${manifest.runId} taskId=${payload.taskId}`);
+	}
+}
+
+/**
+ * Parse a supervisor contact request from child Pi stdout.
+ * Detects structured JSON lines with type "supervisor_contact".
+ */
+export function parseSupervisorContactFromLine(line: string): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
+	if (!line.trim()) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	if (record.type !== "supervisor_contact" && record.type !== "crew_supervisor_contact") return undefined;
+	return {
+		taskId: typeof record.taskId === "string" ? record.taskId : "",
+		reason: typeof record.reason === "string" && ["decision_needed", "clarification", "approval", "error_escalation", "custom"].includes(record.reason)
+			? record.reason as SupervisorContactPayload["reason"]
+			: "custom",
+		message: typeof record.message === "string" ? record.message : String(record.message ?? ""),
+		data: record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data as Record<string, unknown> : undefined,
+	};
+}

package/src/runtime/task-runner.ts

@@ -27,6 +27,7 @@ import { checkpointTask, persistSingleTaskUpdate, updateTask } from "./task-runn
 import { cleanResultText, isFinalChildEvent } from "./task-runner/result-utils.ts";
 import { evaluateCompletionMutationGuard } from "./completion-guard.ts";
 import { appendTaskAttentionEvent } from "./attention-events.ts";
+import { parseSupervisorContactFromLine, recordSupervisorContact } from "./supervisor-contact.ts";
 
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
@@ -44,6 +45,8 @@ export interface TaskRunnerInput {
 	modelOverride?: string;
 	limits?: CrewLimitsConfig;
 	dependencyContextText?: string;
+	/** Optional callback for JSON events from child Pi. Used for overflow recovery tracking. */
+	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
 }
 
 export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
@@ -154,12 +157,23 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 				onStdoutLine: (line) => {
 					appendCrewAgentOutput(manifest, task.id, line);
 					persistHeartbeat();
+					// Check for supervisor contact requests from child Pi
+					const contact = parseSupervisorContactFromLine(line);
+					if (contact) {
+						recordSupervisorContact(manifest, { runId: manifest.runId, ...contact });
+					}
 				},
 				onJsonEvent: (event) => {
 					appendCrewAgentEvent(manifest, task.id, event);
 					persistHeartbeat();
 					task = { ...task, agentProgress: applyAgentProgressEvent(task.agentProgress ?? emptyCrewAgentProgress(), event, task.startedAt) };
 					tasks = updateTask(tasks, task);
+					// Feed overflow recovery tracker
+					if (input.onJsonEvent) {
+						try {
+							input.onJsonEvent(task.id, manifest.runId, event);
+						} catch { /* overflow tracking errors should not affect task */ }
+					}
 					if (!finalCheckpointWritten && isFinalChildEvent(event)) {
 						finalCheckpointWritten = true;
 						({ task, tasks } = checkpointTask(manifest, tasks, task, "child-stdout-final"));

package/src/runtime/team-runner.ts

@@ -43,6 +43,8 @@ export interface ExecuteTeamRunInput {
 	signal?: AbortSignal;
 	reliability?: CrewReliabilityConfig;
 	metricRegistry?: MetricRegistry;
+	/** Optional callback for JSON events from child Pi. Used for overflow recovery tracking. */
+	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
 }
 
 function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
@@ -68,7 +70,7 @@ function mergeArtifacts(items: ArtifactDescriptor[]): ArtifactDescriptor[] {
 }
 
 function isNonTerminalTaskStatus(status: TeamTaskState["status"]): boolean {
-	return status === "queued" || status === "running";
+	return status === "queued" || status === "running" || status === "waiting";
 }
 
 function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskState): boolean {
@@ -483,7 +485,7 @@ function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskS
 }
 
 function cancelPlanTasks(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
-	return tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: reason, graph: task.graph ? { ...task.graph, queue: "done" } : undefined } : task);
+	return tasks.map((task) => task.status === "queued" || task.status === "running" || task.status === "waiting" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: reason, graph: task.graph ? { ...task.graph, queue: "done" } : undefined } : task);
 }
 
 function hasPendingMutatingAdaptiveTask(tasks: TeamTaskState[]): boolean {
@@ -533,7 +535,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 
 	while (tasks.some((task) => task.status === "queued")) {
 		if (input.signal?.aborted) {
-			tasks = tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: "Run cancelled." } : task);
+			tasks = tasks.map((task) => task.status === "queued" || task.status === "running" || task.status === "waiting" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: "Run cancelled." } : task);
 			await saveRunTasksAsync(manifest, tasks);
 			manifest = updateRunStatus(manifest, "cancelled", "Run cancelled.");
 			return { manifest, tasks };
@@ -579,7 +581,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 			async (task) => {
 				const step = findStep(workflow, task);
 				const agent = findAgent(input.agents, task);
-				const baseInput = { manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers, runtimeKind: input.runtime?.kind, runtimeConfig: input.runtimeConfig, parentContext: input.parentContext, parentModel: input.parentModel, modelRegistry: input.modelRegistry, modelOverride: input.modelOverride, limits: input.limits };
+				const baseInput = { manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers, runtimeKind: input.runtime?.kind, runtimeConfig: input.runtimeConfig, parentContext: input.parentContext, parentModel: input.parentModel, modelRegistry: input.modelRegistry, modelOverride: input.modelOverride, limits: input.limits, onJsonEvent: input.onJsonEvent };
 				if (input.reliability?.autoRetry !== true) return withCorrelation(childCorrelation(manifest.runId, task.id), () => runTeamTask(baseInput));
 				let lastFailed: { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined;
 				const attemptsSoFar: TaskAttemptState[] = [...(task.attempts ?? [])];

package/src/schema/config-schema.ts

@@ -58,6 +58,7 @@ export const AgentOverrideSchema = Type.Object({
 	fallbackModels: Type.Optional(Type.Union([Type.Array(Type.String({ minLength: 1 })), Type.Literal(false)])),
 	thinking: Type.Optional(Type.Union([Type.String({ minLength: 1 }), Type.Literal(false)])),
 	tools: Type.Optional(Type.Union([Type.Array(Type.String({ minLength: 1 })), Type.Literal(false)])),
+	skills: Type.Optional(Type.Union([Type.Array(Type.String({ minLength: 1 })), Type.Literal(false)])),
 }, { additionalProperties: false });
 
 export const PiTeamsAgentsConfigSchema = Type.Object({

package/src/schema/team-tool-schema.ts

@@ -24,6 +24,7 @@ export const TeamToolParams = Type.Object({
 		Type.Literal("get"),
 		Type.Literal("cancel"),
 		Type.Literal("resume"),
+		Type.Literal("respond"),
 		Type.Literal("create"),
 		Type.Literal("update"),
 		Type.Literal("delete"),
@@ -59,6 +60,8 @@ export const TeamToolParams = Type.Object({
 	goal: Type.Optional(Type.String({ description: "High-level objective for a team run." })),
 	task: Type.Optional(Type.String({ description: "Concrete task text for direct role/agent execution." })),
 	runId: Type.Optional(Type.String({ description: "Run ID for status, cancel, or resume." })),
+	taskId: Type.Optional(Type.String({ description: "Task ID for respond action." })),
+	message: Type.Optional(Type.String({ description: "Message for respond action." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background when execution support is enabled." })),
 	workspaceMode: Type.Optional(Type.Union([
 		Type.Literal("single"),
@@ -85,7 +88,7 @@ export const TeamToolParams = Type.Object({
 });
 
 export interface TeamToolParamsValue {
-	action?: "run" | "plan" | "status" | "list" | "get" | "cancel" | "resume" | "create" | "update" | "delete" | "doctor" | "cleanup" | "events" | "artifacts" | "worktrees" | "forget" | "summary" | "prune" | "export" | "import" | "imports" | "help" | "validate" | "config" | "init" | "recommend" | "autonomy" | "api" | "settings";
+	action?: "run" | "plan" | "status" | "list" | "get" | "cancel" | "resume" | "respond" | "create" | "update" | "delete" | "doctor" | "cleanup" | "events" | "artifacts" | "worktrees" | "forget" | "summary" | "prune" | "export" | "import" | "imports" | "help" | "validate" | "config" | "init" | "recommend" | "autonomy" | "api" | "settings";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;
@@ -94,6 +97,8 @@ export interface TeamToolParamsValue {
 	goal?: string;
 	task?: string;
 	runId?: string;
+	taskId?: string;
+	message?: string;
 	async?: boolean;
 	workspaceMode?: "single" | "worktree";
 	context?: "fresh" | "fork";

package/src/state/contracts.ts

@@ -1,7 +1,7 @@
 export const TEAM_RUN_STATUSES = ["queued", "planning", "running", "blocked", "completed", "failed", "cancelled"] as const;
 export type TeamRunStatus = typeof TEAM_RUN_STATUSES[number];
 
-export const TEAM_TASK_STATUSES = ["queued", "running", "completed", "failed", "cancelled", "skipped"] as const;
+export const TEAM_TASK_STATUSES = ["queued", "running", "waiting", "completed", "failed", "cancelled", "skipped"] as const;
 export type TeamTaskStatus = typeof TEAM_TASK_STATUSES[number];
 
 export const TEAM_TERMINAL_RUN_STATUSES: ReadonlySet<TeamRunStatus> = new Set(["blocked", "completed", "failed", "cancelled"]);
@@ -19,7 +19,8 @@ export const TEAM_RUN_STATUS_TRANSITIONS: Readonly<Record<TeamRunStatus, readonl
 
 export const TEAM_TASK_STATUS_TRANSITIONS: Readonly<Record<TeamTaskStatus, readonly TeamTaskStatus[]>> = {
 	queued: ["running", "cancelled", "skipped", "failed"],
-	running: ["completed", "failed", "cancelled", "queued"],
+	running: ["completed", "failed", "cancelled", "queued", "waiting"],
+	waiting: ["running", "completed", "failed", "cancelled"],
 	completed: ["queued"],
 	failed: ["queued", "cancelled"],
 	cancelled: ["queued"],
@@ -59,6 +60,9 @@ export const TEAM_EVENT_TYPES = [
 	"async.completed",
 	"async.failed",
 	"async.stale",
+	"task.waiting",
+	"task.resumed",
+	"supervisor.contact",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
 

package/src/ui/crew-widget.ts

@@ -100,12 +100,12 @@ function agentsFor(run: TeamRunManifest): CrewAgentRecord[] {
 	}
 }
 
-export function activeWidgetRuns(cwd: string, manifestCache?: ManifestCache, snapshotCache?: RunSnapshotCache): WidgetRun[] {
-	const runs = manifestCache ? manifestCache.list(20) : listRecentRuns(cwd, 20);
+export function activeWidgetRuns(cwd: string, manifestCache?: ManifestCache, snapshotCache?: RunSnapshotCache, preloadedManifests?: TeamRunManifest[]): WidgetRun[] {
+	const runs = preloadedManifests ?? (manifestCache ? manifestCache.list(20) : listRecentRuns(cwd, 20));
 	return runs
 		.map((run) => {
 			try {
-				const snapshot = snapshotCache?.refreshIfStale(run.runId);
+				const snapshot = snapshotCache?.get(run.runId) ?? snapshotCache?.refreshIfStale(run.runId);
 				return snapshot ? { run: snapshot.manifest, agents: snapshot.agents, snapshot } : { run, agents: agentsFor(run) };
 			} catch {
 				return { run, agents: agentsFor(run) };
@@ -279,11 +279,12 @@ export function updateCrewWidget(
 	config?: CrewUiConfig,
 	manifestCache?: ManifestCache,
 	snapshotCache?: RunSnapshotCache,
+	preloadedManifests?: TeamRunManifest[],
 ): void {
 	if (!ctx.hasUI) return;
 	state.frame += 1;
 	const maxLines = config?.widgetMaxLines ?? MAX_LINES_DEFAULT;
-	const runs = activeWidgetRuns(ctx.cwd, manifestCache, snapshotCache);
+	const runs = activeWidgetRuns(ctx.cwd, manifestCache, snapshotCache, preloadedManifests);
 	const lines = buildCrewWidgetLines(ctx.cwd, state.frame, maxLines, runs, state.notificationCount ?? 0);
 	const placement = config?.widgetPlacement ?? "aboveEditor";
 	ctx.ui.setStatus(STATUS_KEY, lines.length ? statusSummary(runs) : undefined);