pi-crew 0.1.28 → 0.1.30

package/src/runtime/concurrency.ts

@@ -5,6 +5,8 @@ export interface ResolveBatchConcurrencyInput {
 	workflowMaxConcurrency?: number;
 	teamMaxConcurrency?: number;
 	limitMaxConcurrentWorkers?: number;
+	allowUnboundedConcurrency?: boolean;
+	hardCap?: number;
 	readyCount: number;
 	workspaceMode?: "single" | "worktree";
 	readyRoles?: string[];
@@ -40,11 +42,15 @@ export function resolveBatchConcurrency(input: ResolveBatchConcurrencyInput): Ba
 	if (limitMax !== undefined) source = "limit";
 	else if (teamMax !== undefined) source = "team";
 	else source = "workflow";
+	const hardCap = positiveInteger(input.hardCap) ?? DEFAULT_CONCURRENCY.hardCap;
+	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap);
 	const readyCount = Math.max(0, Math.trunc(input.readyCount));
+	const cappedReason = maxConcurrent < requested ? `;capped:${hardCap}` : "";
+	const unboundedReason = input.allowUnboundedConcurrency && requested > hardCap ? `;unbounded:${hardCap}` : "";
 	return {
-		maxConcurrent: requested,
-		selectedCount: readyCount === 0 ? 0 : Math.min(readyCount, requested),
+		maxConcurrent,
+		selectedCount: readyCount === 0 ? 0 : Math.min(readyCount, maxConcurrent),
 		defaultConcurrency,
-		reason: `${source}:${requested};ready:${readyCount}`,
+		reason: `${source}:${requested}${cappedReason}${unboundedReason};ready:${readyCount}`,
 	};
 }

package/src/runtime/crew-agent-records.ts

@@ -159,6 +159,7 @@ export function recordFromTask(manifest: TeamRunManifest, task: TeamTaskState, r
 		toolUses: task.agentProgress?.toolCount,
 		jsonEvents: task.jsonEvents,
 		model: modelFromTask(task),
+		routing: task.modelRouting,
 		usage: task.usage,
 		progress: task.agentProgress,
 		error: task.error,

package/src/runtime/crew-agent-runtime.ts

@@ -1,5 +1,5 @@
 import type { TeamTaskStatus } from "../state/contracts.ts";
-import type { UsageState } from "../state/types.ts";
+import type { ModelRoutingState, UsageState } from "../state/types.ts";
 
 export type CrewRuntimeKind = "scaffold" | "child-process" | "live-session";
 export type CrewAgentStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "stopped";
@@ -43,6 +43,7 @@ export interface CrewAgentRecord {
 	toolUses?: number;
 	jsonEvents?: number;
 	model?: string;
+	routing?: ModelRoutingState;
 	usage?: UsageState;
 	progress?: CrewAgentProgress;
 	error?: string;

package/src/runtime/model-fallback.ts

@@ -219,7 +219,13 @@ function isAvailableModel(model: string, availableModels: AvailableModelInfo[] |
 	return availableModels.some((entry) => entry.id === baseModel);
 }
 
-export function buildConfiguredModelCandidates(input: {
+export interface ConfiguredModelRouting {
+	requested?: string;
+	candidates: string[];
+	reason?: string;
+}
+
+export function buildConfiguredModelRouting(input: {
 	overrideModel?: string;
 	stepModel?: string;
 	agentModel?: string;
@@ -227,18 +233,29 @@ export function buildConfiguredModelCandidates(input: {
 	parentModel?: unknown;
 	modelRegistry?: unknown;
 	cwd?: string;
-}): string[] {
+}): ConfiguredModelRouting {
 	const registryModels = availableModelInfosFromRegistry(input.modelRegistry);
 	const configModels = configuredModelInfosFromPiConfig(input.cwd);
 	const availableModels = registryModels && registryModels.length > 0 ? registryModels : configModels.length > 0 ? configModels : registryModels;
 	const parentModel = modelStringFromUnknown(input.parentModel);
 	const preferredProvider = parentModel?.split("/")[0] ?? availableModels?.[0]?.provider;
-	if (availableModels && availableModels.length === 0) return [];
+	const requested = [input.overrideModel, input.stepModel, input.agentModel, parentModel].find((model): model is string => Boolean(model?.trim()));
+	if (availableModels && availableModels.length === 0) return { requested, candidates: [], reason: "no configured Pi models available" };
 	const rawModels = availableModels
 		? [input.overrideModel, input.stepModel, input.agentModel, ...(input.fallbackModels ?? []), parentModel, ...availableModels.map((model) => model.fullId)]
 		: [input.overrideModel, parentModel];
 	const configuredModels = rawModels
 		.filter((model): model is string => Boolean(model?.trim()))
 		.filter((model) => isAvailableModel(model.trim(), availableModels));
-	return buildModelCandidates(configuredModels[0], configuredModels.slice(1), availableModels, preferredProvider);
+	const candidates = buildModelCandidates(configuredModels[0], configuredModels.slice(1), availableModels, preferredProvider);
+	const reason = requested && candidates[0] && resolveModelCandidate(requested, availableModels, preferredProvider) !== candidates[0]
+		? "requested model unavailable; selected configured Pi fallback"
+		: candidates.length > 1
+			? "configured Pi fallback chain"
+			: undefined;
+	return { requested, candidates, reason };
+}
+
+export function buildConfiguredModelCandidates(input: Parameters<typeof buildConfiguredModelRouting>[0]): string[] {
+	return buildConfiguredModelRouting(input).candidates;
 }

package/src/runtime/pi-args.ts

@@ -93,10 +93,12 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 			PI_CREW_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
 			PI_CREW_DEPTH: String(parentDepth + 1),
 			PI_CREW_MAX_DEPTH: String(maxDepth),
+			PI_CREW_ROLE: input.agent.name,
 			PI_TEAMS_INHERIT_PROJECT_CONTEXT: input.agent.inheritProjectContext ? "1" : "0",
 			PI_TEAMS_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
 			PI_TEAMS_DEPTH: String(parentDepth + 1),
 			PI_TEAMS_MAX_DEPTH: String(maxDepth),
+			PI_TEAMS_ROLE: input.agent.name,
 		},
 		tempDir,
 	};

package/src/runtime/process-status.ts

@@ -1,5 +1,6 @@
 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;

package/src/runtime/role-permission.ts

@@ -26,3 +26,14 @@ export function checkRolePermission(role: string, command: string): PermissionCh
 	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/task-runner/live-executor.ts

@@ -0,0 +1,98 @@
+import * as fs from "node:fs";
+import type { AgentConfig } from "../../agents/agent-config.ts";
+import type { CrewRuntimeConfig } from "../../config/config.ts";
+import { writeArtifact } from "../../state/artifact-store.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { WorkflowStep } from "../../workflows/workflow-config.ts";
+import { appendCrewAgentEvent, appendCrewAgentOutput, emptyCrewAgentProgress, recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
+import { createStartupEvidence, type WorkerStartupEvidence } from "../worker-startup.ts";
+import { runLiveSessionTask } from "../live-session-runtime.ts";
+import { shouldAppendProgressEventUpdate, type ProgressEventSummary } from "../progress-event-coalescer.ts";
+import { applyAgentProgressEvent, applyUsageToProgress, progressEventSummary, shouldFlushProgressEvent } from "./progress.ts";
+import type { ParsedPiJsonOutput } from "../pi-json-output.ts";
+
+export interface RunLiveTaskInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	task: TeamTaskState;
+	step: WorkflowStep;
+	agent: AgentConfig;
+	prompt: string;
+	signal?: AbortSignal;
+	runtimeConfig?: CrewRuntimeConfig;
+	parentContext?: string;
+	parentModel?: unknown;
+	modelRegistry?: unknown;
+}
+
+export interface RunLiveTaskOutput {
+	task: TeamTaskState;
+	tasks: TeamTaskState[];
+	startupEvidence: WorkerStartupEvidence;
+	exitCode: number | null;
+	error?: string;
+	parsedOutput?: ParsedPiJsonOutput;
+	resultArtifact: ArtifactDescriptor;
+	logArtifact?: ArtifactDescriptor;
+	transcriptArtifact?: ArtifactDescriptor;
+}
+
+function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
+	return tasks.map((task) => task.id === updated.id ? updated : task);
+}
+
+export async function runLiveTask(input: RunLiveTaskInput): Promise<RunLiveTaskOutput> {
+	const { manifest, step, agent, prompt } = input;
+	let task = input.task;
+	let tasks = input.tasks;
+	const transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
+	let lastAgentRecordPersistedAt = 0;
+	let lastRunProgressPersistedAt = 0;
+	let lastRunProgressSummary: ProgressEventSummary | undefined;
+	const persistLiveProgress = (event: unknown, force = false): void => {
+		const now = Date.now();
+		if (force || shouldFlushProgressEvent(event) || now - lastAgentRecordPersistedAt >= 500) {
+			upsertCrewAgent(manifest, recordFromTask(manifest, task, "live-session"));
+			lastAgentRecordPersistedAt = now;
+		}
+		const summary = progressEventSummary(task, event);
+		const decision = shouldAppendProgressEventUpdate({ previous: lastRunProgressSummary, next: summary, nowMs: now, lastAppendMs: lastRunProgressPersistedAt || undefined, minIntervalMs: 1000, force });
+		if (decision.shouldAppend) {
+			appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, taskId: task.id, data: { ...summary, coalesceReason: decision.reason } });
+			lastRunProgressSummary = summary;
+			lastRunProgressPersistedAt = now;
+		}
+	};
+	const attemptStartedAt = new Date();
+	const liveResult = await runLiveSessionTask({
+		manifest,
+		task,
+		step,
+		agent,
+		prompt,
+		signal: input.signal,
+		transcriptPath,
+		runtimeConfig: input.runtimeConfig,
+		parentContext: input.parentContext,
+		parentModel: input.parentModel,
+		modelRegistry: input.modelRegistry,
+		onOutput: (text) => appendCrewAgentOutput(manifest, task.id, text),
+		onEvent: (event) => {
+			appendCrewAgentEvent(manifest, task.id, event);
+			task = { ...task, agentProgress: applyAgentProgressEvent(task.agentProgress ?? emptyCrewAgentProgress(), event, task.startedAt) };
+			tasks = updateTask(tasks, task);
+			persistLiveProgress(event);
+		},
+	});
+	const startupEvidence = createStartupEvidence({ command: "live-session", startedAt: attemptStartedAt, finishedAt: new Date(), promptSentAt: attemptStartedAt, promptAccepted: liveResult.exitCode === 0 && !liveResult.error, stderr: liveResult.stderr, error: liveResult.error, exitCode: liveResult.exitCode });
+	const exitCode = liveResult.exitCode;
+	const error = liveResult.error || (liveResult.exitCode && liveResult.exitCode !== 0 ? liveResult.stderr || `Live session exited with ${liveResult.exitCode}` : undefined);
+	const parsedOutput = { finalText: liveResult.stdout, textEvents: liveResult.stdout ? [liveResult.stdout] : [], jsonEvents: liveResult.jsonEvents, usage: liveResult.usage };
+	if (liveResult.usage) task = { ...task, usage: liveResult.usage, agentProgress: applyUsageToProgress(task.agentProgress, liveResult.usage) };
+	persistLiveProgress({ type: "attempt_finished" }, true);
+	const resultArtifact = writeArtifact(manifest.artifactsRoot, { kind: "result", relativePath: `results/${task.id}.txt`, content: liveResult.stdout || liveResult.stderr || "(no output)", producer: task.id });
+	const logArtifact = writeArtifact(manifest.artifactsRoot, { kind: "log", relativePath: `logs/${task.id}.log`, content: [`runtime=live-session`, `finalExitCode=${exitCode ?? "null"}`, `jsonEvents=${liveResult.jsonEvents}`, liveResult.usage ? `usage=${JSON.stringify(liveResult.usage)}` : "", "", "STDOUT:", liveResult.stdout, "", "STDERR:", liveResult.stderr].join("\n"), producer: task.id });
+	const transcriptArtifact = fs.existsSync(transcriptPath) ? writeArtifact(manifest.artifactsRoot, { kind: "log", relativePath: `transcripts/${task.id}.jsonl`, content: fs.readFileSync(transcriptPath, "utf-8"), producer: task.id }) : undefined;
+	return { task, tasks, startupEvidence, exitCode, error: error || undefined, parsedOutput, resultArtifact, logArtifact, transcriptArtifact };
+}

package/src/runtime/task-runner/progress.ts

@@ -0,0 +1,111 @@
+import type { UsageState } from "../../state/types.ts";
+import type { CrewAgentProgress } from "../crew-agent-runtime.ts";
+import { emptyCrewAgentProgress } from "../crew-agent-records.ts";
+import type { ProgressEventSummary } from "../progress-event-coalescer.ts";
+import type { TeamTaskState } from "../../state/types.ts";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function textFromContent(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	const text: string[] = [];
+	for (const part of content) {
+		const obj = asRecord(part);
+		if (!obj) continue;
+		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
+		else if (typeof obj.content === "string") text.push(obj.content);
+	}
+	return text;
+}
+
+function eventText(event: unknown): string[] {
+	const obj = asRecord(event);
+	if (!obj) return [];
+	const text: string[] = [];
+	if (typeof obj.text === "string") text.push(obj.text);
+	if (typeof obj.output === "string") text.push(obj.output);
+	text.push(...textFromContent(obj.content));
+	const message = asRecord(obj.message);
+	if (message) text.push(...textFromContent(message.content));
+	return text.filter((entry) => entry.trim());
+}
+
+function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function eventUsage(event: unknown): { input?: number; output?: number; turns?: number } | undefined {
+	const obj = asRecord(event);
+	if (!obj) return undefined;
+	const direct = { input: numberField(obj, ["input", "inputTokens", "input_tokens"]), output: numberField(obj, ["output", "outputTokens", "output_tokens"]), turns: numberField(obj, ["turns", "turnCount", "turn_count"]) };
+	if (Object.values(direct).some((value) => value !== undefined)) return direct;
+	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+		const nested = eventUsage(obj[key]);
+		if (nested) return nested;
+	}
+	const message = asRecord(obj.message);
+	return message ? eventUsage(message.usage) : undefined;
+}
+
+function previewArgs(args: unknown): string | undefined {
+	if (!args) return undefined;
+	try {
+		const text = typeof args === "string" ? args : JSON.stringify(args);
+		return text.length > 240 ? `${text.slice(0, 240)}…` : text;
+	} catch {
+		return undefined;
+	}
+}
+
+export function applyUsageToProgress(progress: CrewAgentProgress | undefined, usage: UsageState | undefined): CrewAgentProgress | undefined {
+	if (!usage) return progress;
+	const base = progress ?? emptyCrewAgentProgress();
+	return { ...base, tokens: (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0), turns: usage.turns ?? base.turns };
+}
+
+export function shouldFlushProgressEvent(event: unknown): boolean {
+	const type = asRecord(event)?.type;
+	return type === "tool_execution_start" || type === "tool_execution_end" || type === "message_end" || type === "tool_result_end";
+}
+
+export function progressEventSummary(task: TeamTaskState, event: unknown): ProgressEventSummary {
+	const type = asRecord(event)?.type;
+	return { eventType: typeof type === "string" ? type : "event", currentTool: task.agentProgress?.currentTool, toolCount: task.agentProgress?.toolCount, tokens: task.agentProgress?.tokens, turns: task.agentProgress?.turns, activityState: task.agentProgress?.activityState, lastActivityAt: task.agentProgress?.lastActivityAt };
+}
+
+export function applyAgentProgressEvent(progress: CrewAgentProgress, event: unknown, startedAt: string | undefined): CrewAgentProgress {
+	const obj = asRecord(event);
+	const now = new Date().toISOString();
+	const next: CrewAgentProgress = { ...progress, recentTools: [...progress.recentTools], recentOutput: [...progress.recentOutput], lastActivityAt: now, activityState: "active" };
+	if (startedAt) next.durationMs = Date.now() - new Date(startedAt).getTime();
+	if (obj?.type === "tool_execution_start") {
+		next.toolCount += 1;
+		next.currentTool = typeof obj.toolName === "string" ? obj.toolName : typeof obj.name === "string" ? obj.name : "tool";
+		next.currentToolArgs = previewArgs(obj.args);
+		next.currentToolStartedAt = now;
+	}
+	if (obj?.type === "tool_execution_end") {
+		if (next.currentTool) next.recentTools.push({ tool: next.currentTool, args: next.currentToolArgs, endedAt: now });
+		next.currentTool = undefined;
+		next.currentToolArgs = undefined;
+		next.currentToolStartedAt = undefined;
+	}
+	if ((obj?.type === "tool_execution_error" || obj?.type === "tool_execution_failed") && next.currentTool) next.failedTool = next.currentTool;
+	const usage = eventUsage(event);
+	if (usage) {
+		next.tokens = (usage.input ?? 0) + (usage.output ?? 0);
+		next.turns = usage.turns ?? next.turns;
+	}
+	const text = eventText(event);
+	if (text.length > 0) next.recentOutput.push(...text.flatMap((entry) => entry.split(/\r?\n/)).filter(Boolean).slice(-10));
+	if (next.recentTools.length > 25) next.recentTools.splice(0, next.recentTools.length - 25);
+	if (next.recentOutput.length > 50) next.recentOutput.splice(0, next.recentOutput.length - 50);
+	return next;
+}

package/src/runtime/task-runner/prompt-builder.ts

@@ -0,0 +1,72 @@
+import type { AgentConfig } from "../../agents/agent-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { WorkflowStep } from "../../workflows/workflow-config.ts";
+import { buildMemoryBlock } from "../agent-memory.ts";
+import { permissionForRole } from "../role-permission.ts";
+import { renderTaskPacket } from "../task-packet.ts";
+
+function readOnlyRoleInstructions(role: string): string {
+	if (permissionForRole(role) !== "read_only") return "";
+	return [
+		"# READ-ONLY ROLE CONTRACT",
+		"You are running in READ-ONLY mode for this task.",
+		"- Do not create, modify, delete, move, or copy files.",
+		"- Do not use shell redirects, heredocs, in-place edits, package installs, git commit/merge/rebase/reset/checkout, or other state-mutating commands.",
+		"- If implementation changes are needed, report exact recommendations instead of applying them.",
+		"- Prefer read/grep/find/listing tools and read-only git inspection commands.",
+	].join("\n");
+}
+
+export function coordinationBridgeInstructions(task: TeamTaskState): string {
+	return [
+		"# Crew Coordination Channel",
+		`Mailbox target for this task: ${task.id}`,
+		"Use the run mailbox contract for coordination with the leader/orchestrator:",
+		"- If blocked or uncertain, report the blocker in your final result and, when mailbox tools/API are available, send an inbox/outbox message addressed to the leader.",
+		"- If nudged, answer with current status, blocker, or smallest next step.",
+		"- Treat inherited/dependency context as reference-only; do not continue the parent conversation directly.",
+		"- Completion handoff should include: DONE/FAILED, summary, changed/read files, verification evidence, and remaining risks.",
+	].join("\n");
+}
+
+function inputDependencyContext(task: TeamTaskState): string {
+	return (task as TeamTaskState & { dependencyContextText?: string }).dependencyContextText ?? "";
+}
+
+export function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState, agent?: AgentConfig): string {
+	const memoryBlock = agent?.memory ? buildMemoryBlock(agent.name, agent.memory, task.cwd, Boolean(agent.tools?.some((tool) => tool === "write" || tool === "edit"))) : "";
+	return [
+		"# pi-crew Worker Runtime Context",
+		`Run ID: ${manifest.runId}`,
+		`Team: ${manifest.team}`,
+		`Workflow: ${manifest.workflow ?? "(none)"}`,
+		`State root: ${manifest.stateRoot}`,
+		`Artifacts root: ${manifest.artifactsRoot}`,
+		`Events path: ${manifest.eventsPath}`,
+		`Task ID: ${task.id}`,
+		`Task cwd: ${task.cwd}`,
+		`Workspace mode: ${manifest.workspaceMode}`,
+		"",
+		`Goal:\n${manifest.goal}`,
+		"",
+		`Step: ${step.id}`,
+		`Role: ${step.role}`,
+		"",
+		"Protocol:",
+		"- Stay within the task scope unless the prompt explicitly says otherwise.",
+		"- Report blockers and verification evidence in the final result.",
+		"- Do not claim completion without evidence.",
+		"- Follow the Task Packet contract below; escalate if any contract field is impossible to satisfy.",
+		"",
+		readOnlyRoleInstructions(task.role),
+		"",
+		coordinationBridgeInstructions(task),
+		"",
+		task.taskPacket ? renderTaskPacket(task.taskPacket) : "",
+		"",
+		(inputDependencyContext(task) || ""),
+		memoryBlock,
+		"Task:",
+		step.task.replaceAll("{goal}", manifest.goal),
+	].join("\n");
+}

package/src/runtime/task-runner/result-utils.ts

@@ -0,0 +1,14 @@
+export function cleanResultText(text: string | undefined): string | undefined {
+	const trimmed = text?.trim();
+	if (!trimmed) return undefined;
+	const doneIndex = trimmed.lastIndexOf("\nDONE\n");
+	if (doneIndex >= 0) return trimmed.slice(doneIndex + 1).trim();
+	if (trimmed === "DONE" || trimmed.startsWith("DONE\n")) return trimmed;
+	const fencedPromptIndex = trimmed.lastIndexOf("</file>");
+	if (fencedPromptIndex >= 0 && fencedPromptIndex < trimmed.length - 7) return trimmed.slice(fencedPromptIndex + 7).trim() || trimmed;
+	return trimmed;
+}
+
+export function isFinalChildEvent(event: unknown): boolean {
+	return Boolean(event && typeof event === "object" && !Array.isArray(event) && (event as Record<string, unknown>).type === "message_end");
+}

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

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