pi-crew 0.1.49 → 0.2.0

package/src/runtime/task-runner/run-projection.ts

@@ -1,104 +1,104 @@
-import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
-import type { MailboxMessage } from "../../state/mailbox.ts";
-import type { ArtifactDescriptor } from "../../state/types.ts";
-
-export interface RunProjectionSource {
-	kind: "events" | "mailbox" | "artifacts" | "ui_metadata" | "runtime_metadata";
-	bounded: boolean;
-	reference?: string;
-}
-
-export interface RunProjectionResult {
-	sources: RunProjectionSource[];
-	summary: string;
-	injectedAsContext: boolean;
-}
-
-/**
- * Transform run context before a worker starts.
- * Builds a bounded projection of durable history that will be available
- * to the worker as reference context, not as instructions.
- *
- * Rules:
- * - Durable history retains events, mailbox, artifacts, UI/runtime metadata.
- * - Worker prompt gets a bounded projection (truncated/summarized).
- * - UI/runtime events are not prompt text unless explicitly selected.
- */
-export function transformRunContextBeforeWorkerStart(input: {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	pendingMailbox: MailboxMessage[];
-	artifacts: ArtifactDescriptor[];
-	maxEvents?: number;
-	maxMailboxMessages?: number;
-	maxArtifactRefs?: number;
-}): RunProjectionResult {
-	const maxEvents = input.maxEvents ?? 20;
-	const maxMailbox = input.maxMailboxMessages ?? 10;
-	const maxArtifacts = input.maxArtifactRefs ?? 15;
-
-	const sources: RunProjectionSource[] = [];
-	const lines: string[] = [];
-
-	// Project a bounded slice of task history
-	const completedTasks = input.tasks.filter((t) => t.status === "completed" || t.status === "failed");
-	if (completedTasks.length > 0) {
-		const tasks = completedTasks.slice(0, maxEvents);
-		sources.push({ kind: "events", bounded: true, reference: `tasks:${tasks.length}/${completedTasks.length}` });
-		lines.push(`Previous tasks (${tasks.length}/${completedTasks.length}):`);
-		for (const task of tasks) {
-			lines.push(`- ${task.id}: ${task.status}${task.error ? ` (${task.error})` : ""}`);
-		}
-	}
-
-	// Project pending mailbox that is relevant to this worker
-	if (input.pendingMailbox.length > 0) {
-		const messages = input.pendingMailbox.slice(0, maxMailbox);
-		sources.push({ kind: "mailbox", bounded: true, reference: `mailbox:${messages.length}/${input.pendingMailbox.length}` });
-		lines.push(`Pending messages (${messages.length}/${input.pendingMailbox.length}):`);
-		for (const msg of messages) {
-			lines.push(`- ${msg.kind ?? "message"}: ${msg.body.slice(0, 100)}`);
-		}
-	}
-
-	// Project artifact references (not content)
-	if (input.artifacts.length > 0) {
-		const artifacts = input.artifacts.slice(0, maxArtifacts);
-		sources.push({ kind: "artifacts", bounded: true, reference: `artifacts:${artifacts.length}/${input.artifacts.length}` });
-		lines.push(`Available artifacts (${artifacts.length}/${input.artifacts.length}):`);
-		for (const art of artifacts) {
-			lines.push(`- ${art.kind} (${art.producer})`);
-		}
-	}
-
-	// Metadata markers — not injected as prompt instructions
-	sources.push({ kind: "ui_metadata", bounded: false, reference: "excluded_from_prompt" });
-	sources.push({ kind: "runtime_metadata", bounded: false, reference: "excluded_from_prompt" });
-
-	return {
-		sources,
-		summary: lines.join("\n"),
-		injectedAsContext: true,
-	};
-}
-
-/**
- * Convert run history to a bounded worker prompt section.
- * Same logic as transformRunContextBeforeWorkerStart but returns
- * the prompt text directly for embedding in the worker prompt.
- */
-export function convertRunHistoryToWorkerPrompt(input: {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	pendingMailbox: MailboxMessage[];
-	artifacts: ArtifactDescriptor[];
-}): string {
-	const projection = transformRunContextBeforeWorkerStart(input);
-	if (!projection.summary) return "";
-	return [
-		"## Run Context (bounded projection)",
-		projection.summary,
-		"",
-		`Projection sources: ${projection.sources.map((s) => s.kind).join(", ")}`,
-	].join("\n");
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { MailboxMessage } from "../../state/mailbox.ts";
+import type { ArtifactDescriptor } from "../../state/types.ts";
+
+export interface RunProjectionSource {
+	kind: "events" | "mailbox" | "artifacts" | "ui_metadata" | "runtime_metadata";
+	bounded: boolean;
+	reference?: string;
+}
+
+export interface RunProjectionResult {
+	sources: RunProjectionSource[];
+	summary: string;
+	injectedAsContext: boolean;
+}
+
+/**
+ * Transform run context before a worker starts.
+ * Builds a bounded projection of durable history that will be available
+ * to the worker as reference context, not as instructions.
+ *
+ * Rules:
+ * - Durable history retains events, mailbox, artifacts, UI/runtime metadata.
+ * - Worker prompt gets a bounded projection (truncated/summarized).
+ * - UI/runtime events are not prompt text unless explicitly selected.
+ */
+export function transformRunContextBeforeWorkerStart(input: {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	pendingMailbox: MailboxMessage[];
+	artifacts: ArtifactDescriptor[];
+	maxEvents?: number;
+	maxMailboxMessages?: number;
+	maxArtifactRefs?: number;
+}): RunProjectionResult {
+	const maxEvents = input.maxEvents ?? 20;
+	const maxMailbox = input.maxMailboxMessages ?? 10;
+	const maxArtifacts = input.maxArtifactRefs ?? 15;
+
+	const sources: RunProjectionSource[] = [];
+	const lines: string[] = [];
+
+	// Project a bounded slice of task history
+	const completedTasks = input.tasks.filter((t) => t.status === "completed" || t.status === "failed");
+	if (completedTasks.length > 0) {
+		const tasks = completedTasks.slice(0, maxEvents);
+		sources.push({ kind: "events", bounded: true, reference: `tasks:${tasks.length}/${completedTasks.length}` });
+		lines.push(`Previous tasks (${tasks.length}/${completedTasks.length}):`);
+		for (const task of tasks) {
+			lines.push(`- ${task.id}: ${task.status}${task.error ? ` (${task.error})` : ""}`);
+		}
+	}
+
+	// Project pending mailbox that is relevant to this worker
+	if (input.pendingMailbox.length > 0) {
+		const messages = input.pendingMailbox.slice(0, maxMailbox);
+		sources.push({ kind: "mailbox", bounded: true, reference: `mailbox:${messages.length}/${input.pendingMailbox.length}` });
+		lines.push(`Pending messages (${messages.length}/${input.pendingMailbox.length}):`);
+		for (const msg of messages) {
+			lines.push(`- ${msg.kind ?? "message"}: ${msg.body.slice(0, 100)}`);
+		}
+	}
+
+	// Project artifact references (not content)
+	if (input.artifacts.length > 0) {
+		const artifacts = input.artifacts.slice(0, maxArtifacts);
+		sources.push({ kind: "artifacts", bounded: true, reference: `artifacts:${artifacts.length}/${input.artifacts.length}` });
+		lines.push(`Available artifacts (${artifacts.length}/${input.artifacts.length}):`);
+		for (const art of artifacts) {
+			lines.push(`- ${art.kind} (${art.producer})`);
+		}
+	}
+
+	// Metadata markers — not injected as prompt instructions
+	sources.push({ kind: "ui_metadata", bounded: false, reference: "excluded_from_prompt" });
+	sources.push({ kind: "runtime_metadata", bounded: false, reference: "excluded_from_prompt" });
+
+	return {
+		sources,
+		summary: lines.join("\n"),
+		injectedAsContext: true,
+	};
+}
+
+/**
+ * Convert run history to a bounded worker prompt section.
+ * Same logic as transformRunContextBeforeWorkerStart but returns
+ * the prompt text directly for embedding in the worker prompt.
+ */
+export function convertRunHistoryToWorkerPrompt(input: {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	pendingMailbox: MailboxMessage[];
+	artifacts: ArtifactDescriptor[];
+}): string {
+	const projection = transformRunContextBeforeWorkerStart(input);
+	if (!projection.summary) return "";
+	return [
+		"## Run Context (bounded projection)",
+		projection.summary,
+		"",
+		`Projection sources: ${projection.sources.map((s) => s.kind).join(", ")}`,
+	].join("\n");
 }

package/src/runtime/task-runner/state-helpers.ts

@@ -1,22 +1,22 @@
-import type { TaskCheckpointState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
-import { loadRunManifestById, saveRunTasks } from "../../state/state-store.ts";
-import { recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
-
-export function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
-	return tasks.map((task) => task.id === updated.id ? updated : task);
-}
-
-export function persistSingleTaskUpdate(manifest: TeamRunManifest, fallbackTasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
-	const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
-	const merged = updateTask(latest, updated);
-	saveRunTasks(manifest, merged);
-	return merged;
-}
-
-export function checkpointTask(manifest: TeamRunManifest, tasks: TeamTaskState[], task: TeamTaskState, phase: TaskCheckpointState["phase"], childPid?: number): { task: TeamTaskState; tasks: TeamTaskState[] } {
-	const checkpoint: TaskCheckpointState = { phase, updatedAt: new Date().toISOString(), ...(childPid ? { childPid } : task.checkpoint?.childPid ? { childPid: task.checkpoint.childPid } : {}) };
-	const nextTask = { ...task, checkpoint };
-	const nextTasks = persistSingleTaskUpdate(manifest, updateTask(tasks, nextTask), nextTask);
-	upsertCrewAgent(manifest, recordFromTask(manifest, nextTask, "child-process"));
-	return { task: nextTask, tasks: nextTasks };
-}
+import type { TaskCheckpointState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import { loadRunManifestById, saveRunTasks } from "../../state/state-store.ts";
+import { recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
+
+export function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
+	return tasks.map((task) => task.id === updated.id ? updated : task);
+}
+
+export function persistSingleTaskUpdate(manifest: TeamRunManifest, fallbackTasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
+	const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
+	const merged = updateTask(latest, updated);
+	saveRunTasks(manifest, merged);
+	return merged;
+}
+
+export function checkpointTask(manifest: TeamRunManifest, tasks: TeamTaskState[], task: TeamTaskState, phase: TaskCheckpointState["phase"], childPid?: number): { task: TeamTaskState; tasks: TeamTaskState[] } {
+	const checkpoint: TaskCheckpointState = { phase, updatedAt: new Date().toISOString(), ...(childPid ? { childPid } : task.checkpoint?.childPid ? { childPid: task.checkpoint.childPid } : {}) };
+	const nextTask = { ...task, checkpoint };
+	const nextTasks = persistSingleTaskUpdate(manifest, updateTask(tasks, nextTask), nextTask);
+	upsertCrewAgent(manifest, recordFromTask(manifest, nextTask, "child-process"));
+	return { task: nextTask, tasks: nextTasks };
+}

package/src/runtime/team-runner.ts

@@ -13,12 +13,14 @@ import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.
 import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts";
 import { buildRecoveryLedger } from "./recovery-recipes.ts";
 import { buildTaskGraphIndex, refreshTaskGraphQueues, taskGraphSnapshot } from "./task-graph-scheduler.ts";
+import { buildExecutionPlan as buildDagExecutionPlan, getReadyTasks as getDagReadyTasks, type TaskNode } from "./task-graph.ts";
 import { checkBranchFreshness } from "../worktree/branch-freshness.ts";
 import { aggregateTaskOutputs } from "./task-output-context.ts";
 import { saveCrewAgents } from "./crew-agent-records.ts";
 import { recordsForMaterializedTasks } from "./task-display.ts";
 import { deliverGroupJoin, resolveGroupJoinMode } from "./group-join.ts";
 import { runTeamTask } from "./task-runner.ts";
+import { createWorkflowStateMachine, validatePhasePreconditions, transitionPhase, type PhaseState, type PhaseGuardContext } from "./workflow-state.ts";
 import { executeWithRetry, DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retry-executor.ts";
 import { appendDeadletter } from "./deadletter.ts";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
@@ -83,6 +85,12 @@ function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskState):
 	// contain stale queued/running copies of tasks that another worker already
 	// completed. Never let those stale snapshots regress durable task state.
 	if (!isNonTerminalTaskStatus(current.status) && isNonTerminalTaskStatus(updated.status)) return false;
+	// Prevent a stale completed task from overwriting a fresher one.
+	if (current.finishedAt && updated.finishedAt) {
+		const currentFinished = new Date(current.finishedAt).getTime();
+		const updatedFinished = new Date(updated.finishedAt).getTime();
+		if (!Number.isNaN(currentFinished) && !Number.isNaN(updatedFinished) && updatedFinished < currentFinished) return false;
+	}
 	return updated.status !== current.status || updated.finishedAt !== current.finishedAt || updated.startedAt !== current.startedAt || Boolean(updated.resultArtifact) || Boolean(updated.error) || Boolean(updated.modelAttempts?.length) || Boolean(updated.usage) || Boolean(updated.attempts?.length);
 }
 
@@ -158,7 +166,13 @@ export function __test__parseAdaptivePlan(text: string, allowedRoles: string[]):
 	return phases.length ? { phases } : undefined;
 }
 
-function closeUnbalancedJson(raw: string): string {
+interface CloseUnbalancedJsonResult {
+	text: string;
+	status: "repaired" | "unstable";
+	warning?: string;
+}
+
+function closeUnbalancedJson(raw: string): CloseUnbalancedJsonResult {
 	let result = raw.trim();
 	const stack: string[] = [];
 	let inString = false;
@@ -182,7 +196,11 @@ function closeUnbalancedJson(raw: string): string {
 		else if ((char === "}" || char === "]") && stack.at(-1) === char) stack.pop();
 	}
 	while (stack.length) result += stack.pop();
-	return result;
+	// If still in a string, the JSON string was truncated — values may be semantically different
+	if (inString) {
+		return { text: result, status: "unstable", warning: "JSON string was truncated — values may be incorrect" };
+	}
+	return { text: result, status: "repaired" };
 }
 
 function salvageCompletePhaseObjects(raw: string): unknown | undefined {
@@ -249,7 +267,8 @@ function adaptiveRoleAlias(role: string, allowed: Set<string>): string | undefin
 export function __test__repairAdaptivePlan(text: string, allowedRoles: string[]): { plan?: AdaptivePlan; repaired: boolean; reason?: string } {
 	const raw = extractAdaptivePlanJson(text);
 	if (!raw) return { repaired: false, reason: "missing-json" };
-	const candidates = [raw, closeUnbalancedJson(raw)];
+	const closeResult = closeUnbalancedJson(raw);
+	const candidates = [raw, closeResult.text];
 	let parsed: unknown;
 	let salvageUsed = false;
 	for (const candidate of candidates) {
@@ -270,7 +289,7 @@ export function __test__repairAdaptivePlan(text: string, allowedRoles: string[])
 	const allowed = new Set(allowedRoles);
 	const phases: AdaptivePlanPhase[] = [];
 	let total = 0;
-	let repaired = salvageUsed || raw !== closeUnbalancedJson(raw);
+	let repaired = salvageUsed || raw !== closeResult.text;
 	for (const [phaseIndex, phaseRaw] of phasesRaw.entries()) {
 		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) continue;
 		const phaseObj = phaseRaw as { name?: unknown; tasks?: unknown };
@@ -504,6 +523,24 @@ function hasPendingMutatingAdaptiveTask(tasks: TeamTaskState[]): boolean {
 	return tasks.some((task) => task.status === "queued" && task.adaptive && isMutatingTask(task));
 }
 
+/**
+ * Check whether any task uses explicit `dependsOn` that would benefit from DAG-based
+ * execution planning. If so, build an execution plan and use `getDagReadyTasks`
+ * to augment the ready-set selection.
+ */
+function dagReadyTaskIds(tasks: TeamTaskState[], completedIds: Set<string>): string[] | null {
+	const hasExplicitDeps = tasks.some((t) => t.dependsOn.length > 0);
+	if (!hasExplicitDeps) return null;
+	const nodes: TaskNode[] = tasks.map((t) => ({
+		id: t.id,
+		dependsOn: t.dependsOn,
+		phase: t.adaptive?.phase ?? t.stepId,
+	}));
+	const plan = buildDagExecutionPlan(nodes);
+	if (plan.hasCycle) return null; // fall back to existing scheduler
+	return getDagReadyTasks(plan, completedIds);
+}
+
 export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	let workflow = input.workflow;
 	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
@@ -578,6 +615,15 @@ async function executeTeamRunCore(
 	const runtimeKind = input.runtime?.kind ?? (input.executeWorkers ? "child-process" : "scaffold");
 	saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
 
+	// Build a workflow phase state machine from workflow steps for precondition tracking.
+	const workflowPhases: PhaseState[] = workflow.steps.map((step): PhaseState => ({
+		name: step.id,
+		status: "pending",
+		inputs: step.reads === false ? [] : Array.isArray(step.reads) ? step.reads : [],
+		outputs: step.output === false ? [] : step.output ? [step.output] : [],
+	}));
+	let wfMachine = createWorkflowStateMachine(workflowPhases);
+
 	while (tasks.some((task) => task.status === "queued")) {
 		if (input.signal?.aborted) {
 			const cancelReason = cancellationReasonFromSignal(input.signal);
@@ -608,13 +654,41 @@ async function executeTeamRunCore(
 		}
 
 		const snapshot = taskGraphSnapshot(tasks, queueIndex);
-		const readyRoles = snapshot.ready.map((taskId) => tasks.find((task) => task.id === taskId)?.role).filter((role): role is string => Boolean(role));
-		const concurrency = resolveBatchConcurrency({ workflowName: workflow.name, workflowMaxConcurrency: workflow.maxConcurrency, teamMaxConcurrency: input.team.maxConcurrency, limitMaxConcurrentWorkers: input.limits?.maxConcurrentWorkers, allowUnboundedConcurrency: input.limits?.allowUnboundedConcurrency, readyCount: snapshot.ready.length, workspaceMode: manifest.workspaceMode, readyRoles });
+
+		// DAG-based execution plan: when tasks have explicit dependsOn, use the
+		// topological wave planner to determine ready tasks. Fall back to the
+		// existing task-graph-scheduler when no explicit deps exist (backward compat).
+		const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
+		const dagReady = dagReadyTaskIds(tasks, completedIds);
+		const effectiveReady = dagReady ?? snapshot.ready;
+
+		// Workflow phase precondition check (non-blocking: log warnings only).
+		if (wfMachine.currentPhaseIndex < wfMachine.phases.length) {
+			const completedArtifacts = manifest.artifacts.filter((a) => a.kind === "result" || a.kind === "summary").map((a) => a.path);
+			const previousPhaseStatus = wfMachine.currentPhaseIndex > 0 ? (wfMachine.phases[wfMachine.currentPhaseIndex - 1]?.status ?? "pending") : "completed";
+			const wfContext: PhaseGuardContext = {
+				completedArtifacts,
+				previousPhaseStatus,
+				taskResults: tasks.filter((t) => t.status === "completed").map((t) => ({ taskId: t.id, status: t.status, outputPath: t.resultArtifact?.path })),
+			};
+			const preconditions = validatePhasePreconditions(wfMachine, wfContext);
+			if (!preconditions.ready) {
+				appendEvent(manifest.eventsPath, { type: "workflow.preconditions", runId: manifest.runId, message: `Workflow phase '${wfMachine.phases[wfMachine.currentPhaseIndex]?.name}' is missing inputs: ${preconditions.blocking.join(", ")}`, data: { phaseIndex: wfMachine.currentPhaseIndex, phaseName: wfMachine.phases[wfMachine.currentPhaseIndex]?.name, blocking: preconditions.blocking } });
+			} else {
+				// Advance the machine past completed phases.
+				while (wfMachine.currentPhaseIndex < wfMachine.phases.length && wfMachine.phases[wfMachine.currentPhaseIndex]?.status === "completed") {
+					wfMachine = { ...wfMachine, currentPhaseIndex: wfMachine.currentPhaseIndex + 1 };
+				}
+			}
+		}
+
+		const readyRoles = effectiveReady.map((taskId) => tasks.find((task) => task.id === taskId)?.role).filter((role): role is string => Boolean(role));
+		const concurrency = resolveBatchConcurrency({ workflowName: workflow.name, workflowMaxConcurrency: workflow.maxConcurrency, teamMaxConcurrency: input.team.maxConcurrency, limitMaxConcurrentWorkers: input.limits?.maxConcurrentWorkers, allowUnboundedConcurrency: input.limits?.allowUnboundedConcurrency, readyCount: effectiveReady.length, workspaceMode: manifest.workspaceMode, readyRoles });
 		if (concurrency.reason.includes(";unbounded:")) {
 			appendEvent(manifest.eventsPath, { type: "limits.unbounded", runId: manifest.runId, message: "Unbounded worker concurrency was explicitly enabled for this run.", data: { concurrencyReason: concurrency.reason, maxConcurrent: concurrency.maxConcurrent } });
 		}
 		const approvalPending = isPlanApprovalPending(manifest);
-		const readyIds = approvalPending ? snapshot.ready : snapshot.ready.slice(0, concurrency.selectedCount);
+		const readyIds = approvalPending ? effectiveReady : effectiveReady.slice(0, concurrency.selectedCount);
 		const candidateBatch = readyIds.map((id) => tasks.find((task) => task.id === id)).filter((task): task is TeamTaskState => Boolean(task));
 		const readyBatch = approvalPending ? candidateBatch.filter((task) => !isMutatingTask(task)).slice(0, concurrency.selectedCount) : candidateBatch;
 		if (readyBatch.length === 0) {
@@ -642,6 +716,9 @@ async function executeTeamRunCore(
 			}
 		}
 		const batchTasks = readyBatch.filter((task) => tasks.find((t) => t.id === task.id && t.status !== "skipped"));
+		if (batchTasks.length > 1) {
+			appendEvent(manifest.eventsPath, { type: "task.parallel_start", runId: manifest.runId, message: `Launching ${batchTasks.length} tasks in PARALLEL (concurrency=${concurrency.selectedCount}): ${batchTasks.map((t) => `${t.role}(${t.id})`).join(", ")}`, data: { taskIds: batchTasks.map((t) => t.id), roles: batchTasks.map((t) => t.role), concurrency: concurrency.selectedCount } });
+		}
 		const results = await mapConcurrent(
 			batchTasks,
 			concurrency.selectedCount,
@@ -717,6 +794,48 @@ async function executeTeamRunCore(
 		if (results.length === 0) break;
 		manifest = { ...results.at(-1)!.manifest, artifacts: mergeArtifacts([manifest.artifacts, ...results.map((item) => item.manifest.artifacts)].flat()) };
 		tasks = __test__mergeTaskUpdates(tasks, results);
+
+		// Advance workflow phases whose tasks are all in terminal state
+		const terminalStatuses = new Set(["completed", "failed", "skipped", "cancelled"]);
+		const phaseTaskMap = new Map<string, string[]>();
+		for (const task of tasks) {
+			if (!task.stepId) continue;
+			const existing = phaseTaskMap.get(task.stepId) ?? [];
+			existing.push(task.id);
+			phaseTaskMap.set(task.stepId, existing);
+		}
+		for (let pi = wfMachine.currentPhaseIndex; pi < wfMachine.phases.length; pi++) {
+			const phase = wfMachine.phases[pi]!;
+			const phaseTaskIds = phaseTaskMap.get(phase.name) ?? [];
+			if (phaseTaskIds.length === 0) continue;
+			const allTerminal = phaseTaskIds.every((taskId) => {
+				const task = tasks.find((t) => t.id === taskId);
+				return task ? terminalStatuses.has(task.status) : false;
+			});
+			if (!allTerminal) break;
+			if (phase.status !== "completed" && phase.status !== "failed" && phase.status !== "skipped") {
+				const completedArtifacts = manifest.artifacts.filter((a) => a.kind === "result" || a.kind === "summary").map((a) => a.path);
+				const previousPhaseStatus = pi > 0 ? (wfMachine.phases[pi - 1]?.status ?? "pending") : "completed";
+				const wfContext: PhaseGuardContext = {
+					completedArtifacts,
+					previousPhaseStatus,
+					taskResults: tasks.filter((t) => t.status === "completed").map((t) => ({ taskId: t.id, status: t.status, outputPath: t.resultArtifact?.path })),
+				};
+				// Determine phase transition status based on individual task outcomes
+				const phaseTasks = phaseTaskIds.map((taskId) => tasks.find((t) => t.id === taskId)).filter((t): t is NonNullable<typeof t> => t !== undefined);
+				const hasFailedOrCancelled = phaseTasks.some((t) => t.status === "failed" || t.status === "cancelled");
+				const phaseStatus = hasFailedOrCancelled ? "failed" : "completed";
+				const transition = transitionPhase(wfMachine, pi, phaseStatus, wfContext);
+				wfMachine = transition.machine;
+				if (transition.guardResult && !transition.guardResult.allowed) {
+					appendEvent(manifest.eventsPath, { type: "workflow.phase_guard_blocked", runId: manifest.runId, message: `Workflow phase '${phase.name}' guard blocked: ${transition.guardResult.reason ?? "unknown"}`, data: { phaseIndex: pi, phaseName: phase.name, reason: transition.guardResult.reason } });
+					break;
+				}
+				appendEvent(manifest.eventsPath, { type: phaseStatus === "failed" ? "workflow.phase_failed" : "workflow.phase_completed", runId: manifest.runId, message: `Workflow phase '${phase.name}' ${phaseStatus}.`, data: { phaseIndex: pi, phaseStatus } });
+			}
+			wfMachine = { ...wfMachine, currentPhaseIndex: pi + 1 };
+		}
+
 		const cancelledResult = results.find((item) => item.manifest.status === "cancelled");
 		if (cancelledResult || input.signal?.aborted) {
 			const reason = input.signal?.aborted ? cancellationReasonFromSignal(input.signal) : undefined;

package/src/runtime/worker-heartbeat.ts

@@ -1,21 +1,21 @@
-export interface WorkerHeartbeatState {
-	workerId: string;
-	pid?: number;
-	lastSeenAt: string;
-	lastStdoutAt?: string;
-	lastEventAt?: string;
-	turnCount?: number;
-	alive?: boolean;
-}
-
-export function createWorkerHeartbeat(workerId: string, pid?: number, now = new Date()): WorkerHeartbeatState {
-	return { workerId, pid, lastSeenAt: now.toISOString(), alive: true };
-}
-
-export function touchWorkerHeartbeat(heartbeat: WorkerHeartbeatState, updates: Partial<Omit<WorkerHeartbeatState, "workerId">> = {}, now = new Date()): WorkerHeartbeatState {
-	return { ...heartbeat, ...updates, lastSeenAt: now.toISOString() };
-}
-
-export function isWorkerHeartbeatStale(heartbeat: WorkerHeartbeatState, staleMs: number, now = new Date()): boolean {
-	return now.getTime() - Date.parse(heartbeat.lastSeenAt) > staleMs;
-}
+export interface WorkerHeartbeatState {
+	workerId: string;
+	pid?: number;
+	lastSeenAt: string;
+	lastStdoutAt?: string;
+	lastEventAt?: string;
+	turnCount?: number;
+	alive?: boolean;
+}
+
+export function createWorkerHeartbeat(workerId: string, pid?: number, now = new Date()): WorkerHeartbeatState {
+	return { workerId, pid, lastSeenAt: now.toISOString(), alive: true };
+}
+
+export function touchWorkerHeartbeat(heartbeat: WorkerHeartbeatState, updates: Partial<Omit<WorkerHeartbeatState, "workerId">> = {}, now = new Date()): WorkerHeartbeatState {
+	return { ...heartbeat, ...updates, lastSeenAt: now.toISOString() };
+}
+
+export function isWorkerHeartbeatStale(heartbeat: WorkerHeartbeatState, staleMs: number, now = new Date()): boolean {
+	return now.getTime() - Date.parse(heartbeat.lastSeenAt) > staleMs;
+}

package/src/runtime/worker-startup.ts

@@ -1,57 +1,57 @@
-export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
-export type StartupFailureClassification = "trust_required" | "prompt_misdelivery" | "prompt_acceptance_timeout" | "transport_dead" | "worker_crashed" | "unknown";
-
-export interface WorkerStartupEvidence {
-	lastLifecycleState: WorkerLifecycleState;
-	command: string;
-	promptSentAt?: string;
-	promptAccepted: boolean;
-	trustPromptDetected: boolean;
-	transportHealthy: boolean;
-	childProcessAlive: boolean;
-	elapsedMs: number;
-	classification: StartupFailureClassification;
-	stderrPreview?: string;
-}
-
-export function detectTrustPrompt(text: string): boolean {
-	const lowered = text.toLowerCase();
-	return lowered.includes("do you trust") || lowered.includes("trust this") || lowered.includes("untrusted") || lowered.includes("workspace trust") || lowered.includes("allow this folder");
-}
-
-export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
-	if (!evidence.transportHealthy) return "transport_dead";
-	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
-	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
-	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
-	if (evidence.stderrPreview?.toLowerCase().includes("command not found") || evidence.stderrPreview?.toLowerCase().includes("not recognized")) return "prompt_misdelivery";
-	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
-	return "unknown";
-}
-
-export function createStartupEvidence(input: {
-	command: string;
-	startedAt: Date;
-	finishedAt?: Date;
-	promptSentAt?: Date;
-	promptAccepted?: boolean;
-	stderr?: string;
-	error?: string;
-	exitCode?: number | null;
-}): WorkerStartupEvidence {
-	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
-	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
-	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
-	const base: Omit<WorkerStartupEvidence, "classification"> = {
-		lastLifecycleState: input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0) ? "failed" : input.finishedAt ? "finished" : "running",
-		command: input.command,
-		promptSentAt: input.promptSentAt?.toISOString(),
-		promptAccepted: input.promptAccepted ?? !input.error,
-		trustPromptDetected,
-		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
-		childProcessAlive,
-		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
-		stderrPreview,
-	};
-	return { ...base, classification: classifyStartupFailure(base) };
-}
+export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
+export type StartupFailureClassification = "trust_required" | "prompt_misdelivery" | "prompt_acceptance_timeout" | "transport_dead" | "worker_crashed" | "unknown";
+
+export interface WorkerStartupEvidence {
+	lastLifecycleState: WorkerLifecycleState;
+	command: string;
+	promptSentAt?: string;
+	promptAccepted: boolean;
+	trustPromptDetected: boolean;
+	transportHealthy: boolean;
+	childProcessAlive: boolean;
+	elapsedMs: number;
+	classification: StartupFailureClassification;
+	stderrPreview?: string;
+}
+
+export function detectTrustPrompt(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return lowered.includes("do you trust") || lowered.includes("trust this") || lowered.includes("untrusted") || lowered.includes("workspace trust") || lowered.includes("allow this folder");
+}
+
+export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
+	if (!evidence.transportHealthy) return "transport_dead";
+	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
+	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
+	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
+	if (evidence.stderrPreview?.toLowerCase().includes("command not found") || evidence.stderrPreview?.toLowerCase().includes("not recognized")) return "prompt_misdelivery";
+	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
+	return "unknown";
+}
+
+export function createStartupEvidence(input: {
+	command: string;
+	startedAt: Date;
+	finishedAt?: Date;
+	promptSentAt?: Date;
+	promptAccepted?: boolean;
+	stderr?: string;
+	error?: string;
+	exitCode?: number | null;
+}): WorkerStartupEvidence {
+	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
+	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
+	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
+	const base: Omit<WorkerStartupEvidence, "classification"> = {
+		lastLifecycleState: input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0) ? "failed" : input.finishedAt ? "finished" : "running",
+		command: input.command,
+		promptSentAt: input.promptSentAt?.toISOString(),
+		promptAccepted: input.promptAccepted ?? !input.error,
+		trustPromptDetected,
+		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
+		childProcessAlive,
+		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
+		stderrPreview,
+	};
+	return { ...base, classification: classifyStartupFailure(base) };
+}