pi-crew 0.1.0

package/src/runtime/process-status.ts

@@ -0,0 +1,25 @@
+export interface ProcessLiveness {
+	pid?: number;
+	alive: boolean;
+	detail: string;
+}
+
+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";
+}

package/src/runtime/task-runner.ts

@@ -0,0 +1,164 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { saveRunManifest, saveRunTasks } from "../state/state-store.ts";
+import { createTaskClaim } from "../state/task-claims.ts";
+import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { captureWorktreeDiff, prepareTaskWorkspace } from "../worktree/worktree-manager.ts";
+import { buildModelCandidates, formatModelAttemptNote, isRetryableModelFailure, type ModelAttemptSummary } from "./model-fallback.ts";
+import { parsePiJsonOutput, type ParsedPiJsonOutput } from "./pi-json-output.ts";
+import { runChildPi } from "./child-pi.ts";
+
+export interface TaskRunnerInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	task: TeamTaskState;
+	step: WorkflowStep;
+	agent: AgentConfig;
+	signal?: AbortSignal;
+	executeWorkers: boolean;
+}
+
+function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState): string {
+	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.",
+		"",
+		"Task:",
+		step.task.replaceAll("{goal}", manifest.goal),
+	].join("\n");
+}
+
+function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
+	return tasks.map((task) => task.id === updated.id ? updated : task);
+}
+
+export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	let manifest = input.manifest;
+	const workspace = prepareTaskWorkspace(manifest, input.task);
+	let task: TeamTaskState = {
+		...input.task,
+		cwd: workspace.cwd,
+		worktree: workspace.worktreePath && workspace.branch ? { path: workspace.worktreePath, branch: workspace.branch, reused: workspace.reused ?? false } : input.task.worktree,
+		status: "running",
+		startedAt: new Date().toISOString(),
+		claim: createTaskClaim(`task-runner:${input.task.id}`),
+		heartbeat: createWorkerHeartbeat(input.task.id),
+	};
+	let tasks = updateTask(input.tasks, task);
+	saveRunTasks(manifest, tasks);
+	appendEvent(manifest.eventsPath, { type: "task.started", runId: manifest.runId, taskId: task.id, data: { role: task.role, agent: task.agent, cwd: task.cwd, worktreePath: workspace.worktreePath, worktreeBranch: workspace.branch, worktreeReused: workspace.reused } });
+
+	const prompt = renderTaskPrompt(manifest, input.step, task);
+	const promptArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "prompt",
+		relativePath: `prompts/${task.id}.md`,
+		content: `${prompt}\n`,
+		producer: task.id,
+	});
+
+	let resultArtifact: ArtifactDescriptor;
+	let logArtifact: ArtifactDescriptor | undefined;
+	let exitCode: number | null = 0;
+	let error: string | undefined;
+	let modelAttempts: ModelAttemptSummary[] | undefined;
+	let parsedOutput: ParsedPiJsonOutput | undefined;
+
+	if (input.executeWorkers) {
+		const candidates = buildModelCandidates(input.step.model ?? input.agent.model, input.agent.fallbackModels, undefined);
+		const attemptModels = candidates.length > 0 ? candidates : [input.step.model ?? input.agent.model];
+		const logs: string[] = [];
+		let finalStdout = "";
+		let finalStderr = "";
+		modelAttempts = [];
+		for (let i = 0; i < attemptModels.length; i++) {
+			const model = attemptModels[i];
+			const childResult = await runChildPi({ cwd: task.cwd, task: prompt, agent: input.agent, model, signal: input.signal });
+			exitCode = childResult.exitCode;
+			finalStdout = childResult.stdout;
+			finalStderr = childResult.stderr;
+			parsedOutput = parsePiJsonOutput(childResult.stdout);
+			error = childResult.error || (childResult.exitCode && childResult.exitCode !== 0 ? childResult.stderr || `Child Pi exited with ${childResult.exitCode}` : undefined);
+			const attempt: ModelAttemptSummary = { model: model ?? "default", success: !error, exitCode, error };
+			modelAttempts.push(attempt);
+			logs.push(`MODEL ATTEMPT ${i + 1}: ${attempt.model}`, `success=${attempt.success}`, `exitCode=${attempt.exitCode ?? "null"}`, attempt.error ? `error=${attempt.error}` : "", "");
+			if (!error) break;
+			const nextModel = attemptModels[i + 1];
+			if (!nextModel || !isRetryableModelFailure(error)) break;
+			logs.push(formatModelAttemptNote(attempt, nextModel), "");
+		}
+		resultArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "result",
+			relativePath: `results/${task.id}.txt`,
+			content: parsedOutput?.finalText || finalStdout || finalStderr || "(no output)",
+			producer: task.id,
+		});
+		logArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "log",
+			relativePath: `logs/${task.id}.log`,
+			content: [...logs, `finalExitCode=${exitCode ?? "null"}`, `jsonEvents=${parsedOutput?.jsonEvents ?? 0}`, parsedOutput?.usage ? `usage=${JSON.stringify(parsedOutput.usage)}` : "", "", "STDOUT:", finalStdout, "", "STDERR:", finalStderr].join("\n"),
+			producer: task.id,
+		});
+	} else {
+		resultArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "result",
+			relativePath: `results/${task.id}.md`,
+			content: [
+				`# ${task.id}`,
+				"",
+				"Worker execution is disabled in this scaffold-safe run.",
+				"The prompt artifact contains the exact task that will be sent to a child Pi worker when execution is enabled.",
+			].join("\n"),
+			producer: task.id,
+		});
+	}
+
+	const diffArtifact = workspace.worktreePath ? writeArtifact(manifest.artifactsRoot, {
+		kind: "diff",
+		relativePath: `diffs/${task.id}.diff`,
+		content: captureWorktreeDiff(workspace.worktreePath),
+		producer: task.id,
+	}) : undefined;
+
+	task = {
+		...task,
+		status: error ? "failed" : "completed",
+		finishedAt: new Date().toISOString(),
+		exitCode,
+		modelAttempts,
+		usage: parsedOutput?.usage,
+		jsonEvents: parsedOutput?.jsonEvents,
+		error,
+		promptArtifact,
+		resultArtifact,
+		claim: undefined,
+		heartbeat: touchWorkerHeartbeat(task.heartbeat ?? createWorkerHeartbeat(task.id), { alive: false }),
+		...(logArtifact ? { logArtifact } : {}),
+	};
+	tasks = updateTask(tasks, task);
+	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, promptArtifact, resultArtifact, ...(logArtifact ? [logArtifact] : []), ...(diffArtifact ? [diffArtifact] : [])] };
+	saveRunManifest(manifest);
+	saveRunTasks(manifest, tasks);
+	appendEvent(manifest.eventsPath, { type: error ? "task.failed" : "task.completed", runId: manifest.runId, taskId: task.id, message: error });
+	return { manifest, tasks };
+}

package/src/runtime/team-runner.ts

@@ -0,0 +1,135 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { aggregateUsage, formatUsage } from "../state/usage.ts";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+import { runTeamTask } from "./task-runner.ts";
+
+export interface ExecuteTeamRunInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	team: TeamConfig;
+	workflow: WorkflowConfig;
+	agents: AgentConfig[];
+	executeWorkers: boolean;
+	signal?: AbortSignal;
+}
+
+function findReadyTask(tasks: TeamTaskState[]): TeamTaskState | undefined {
+	const completedStepIds = new Set(tasks.filter((task) => task.status === "completed").map((task) => task.stepId).filter((id): id is string => id !== undefined));
+	return tasks.find((task) => task.status === "queued" && task.dependsOn.every((dep) => completedStepIds.has(dep)));
+}
+
+function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
+	const step = workflow.steps.find((candidate) => candidate.id === task.stepId);
+	if (!step) throw new Error(`Workflow step '${task.stepId}' not found for task '${task.id}'.`);
+	return step;
+}
+
+function findAgent(agents: AgentConfig[], task: TeamTaskState): AgentConfig {
+	const agent = agents.find((candidate) => candidate.name === task.agent);
+	if (!agent) throw new Error(`Agent '${task.agent}' not found for task '${task.id}'.`);
+	return agent;
+}
+
+function markBlocked(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
+	return tasks.map((task) => task.status === "queued" ? { ...task, status: "skipped", error: reason, finishedAt: new Date().toISOString() } : task);
+}
+
+function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string): TeamRunManifest {
+	const counts = new Map<string, number>();
+	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	const progress = writeArtifact(manifest.artifactsRoot, {
+		kind: "progress",
+		relativePath: "progress.md",
+		producer,
+		content: [
+			`# pi-crew progress ${manifest.runId}`,
+			"",
+			`Status: ${manifest.status}`,
+			`Team: ${manifest.team}`,
+			`Workflow: ${manifest.workflow ?? "(none)"}`,
+			`Updated: ${new Date().toISOString()}`,
+			`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
+			"",
+			"## Tasks",
+			...tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
+			"",
+		].join("\n"),
+	});
+	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress] };
+}
+
+export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
+	let tasks = input.tasks;
+	manifest = writeProgress(manifest, tasks, "team-runner");
+	saveRunManifest(manifest);
+
+	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);
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "cancelled", "Run cancelled.");
+			return { manifest, tasks };
+		}
+
+		const failed = tasks.find((task) => task.status === "failed");
+		if (failed) {
+			tasks = markBlocked(tasks, `Blocked by failed task '${failed.id}'.`);
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
+			return { manifest, tasks };
+		}
+
+		const task = findReadyTask(tasks);
+		if (!task) {
+			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
+			return { manifest, tasks };
+		}
+
+		const step = findStep(input.workflow, task);
+		const agent = findAgent(input.agents, task);
+		const result = await runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
+		manifest = result.manifest;
+		tasks = result.tasks;
+		manifest = writeProgress(manifest, tasks, "team-runner");
+		saveRunManifest(manifest);
+	}
+
+	const failed = tasks.find((task) => task.status === "failed");
+	if (failed) {
+		manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
+	} else {
+		manifest = updateRunStatus(manifest, "completed", input.executeWorkers ? "Team workflow completed." : "Team workflow scaffold completed without launching child workers.");
+	}
+	manifest = writeProgress(manifest, tasks, "team-runner");
+	saveRunManifest(manifest);
+	const usage = aggregateUsage(tasks);
+	const summaryArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "summary",
+		relativePath: "summary.md",
+		producer: "team-runner",
+		content: [
+			`# pi-crew run ${manifest.runId}`,
+			"",
+			`Status: ${manifest.status}`,
+			`Team: ${manifest.team}`,
+			`Workflow: ${manifest.workflow ?? "(none)"}`,
+			`Goal: ${manifest.goal}`,
+			`Usage: ${formatUsage(usage)}`,
+			"",
+			"## Tasks",
+			...tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
+			"",
+		].join("\n"),
+	});
+	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, summaryArtifact] };
+	saveRunManifest(manifest);
+	saveRunTasks(manifest, tasks);
+	return { manifest, tasks };
+}

package/src/runtime/worker-heartbeat.ts

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

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

@@ -0,0 +1,100 @@
+import { Type } from "typebox";
+
+const SkillOverride = Type.Unsafe({
+	type: ["string", "array", "boolean"],
+	items: { type: "string" },
+	description: "Skill name(s) to inject, array of skill names, or false to disable role defaults.",
+});
+
+export const TeamToolParams = Type.Object({
+	action: Type.Optional(Type.Union([
+		Type.Literal("run"),
+		Type.Literal("plan"),
+		Type.Literal("status"),
+		Type.Literal("list"),
+		Type.Literal("get"),
+		Type.Literal("cancel"),
+		Type.Literal("resume"),
+		Type.Literal("create"),
+		Type.Literal("update"),
+		Type.Literal("delete"),
+		Type.Literal("doctor"),
+		Type.Literal("cleanup"),
+		Type.Literal("events"),
+		Type.Literal("artifacts"),
+		Type.Literal("worktrees"),
+		Type.Literal("forget"),
+		Type.Literal("summary"),
+		Type.Literal("prune"),
+		Type.Literal("export"),
+		Type.Literal("import"),
+		Type.Literal("imports"),
+		Type.Literal("help"),
+		Type.Literal("validate"),
+		Type.Literal("config"),
+		Type.Literal("init"),
+		Type.Literal("recommend"),
+		Type.Literal("autonomy"),
+		Type.Literal("api"),
+	], { description: "Team action. Defaults to 'list' when omitted." })),
+	resource: Type.Optional(Type.Union([
+		Type.Literal("agent"),
+		Type.Literal("team"),
+		Type.Literal("workflow"),
+	], { description: "Resource kind for get/create/update/delete/list. Defaults to all for list." })),
+	team: Type.Optional(Type.String({ description: "Team name, e.g. default or implementation." })),
+	workflow: Type.Optional(Type.String({ description: "Workflow name, e.g. default or review." })),
+	role: Type.Optional(Type.String({ description: "Role name to run directly within a team." })),
+	agent: Type.Optional(Type.String({ description: "Agent name to inspect or run directly." })),
+	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." })),
+	async: Type.Optional(Type.Boolean({ description: "Run in background when execution support is enabled." })),
+	workspaceMode: Type.Optional(Type.Union([
+		Type.Literal("single"),
+		Type.Literal("worktree"),
+	], { description: "Workspace isolation mode. Worktree mode is planned after MVP." })),
+	context: Type.Optional(Type.Union([
+		Type.Literal("fresh"),
+		Type.Literal("fork"),
+	], { description: "Child context mode for workers." })),
+	cwd: Type.Optional(Type.String({ description: "Working directory override." })),
+	model: Type.Optional(Type.String({ description: "Model override for direct runs." })),
+	skill: Type.Optional(SkillOverride),
+	scope: Type.Optional(Type.Union([
+		Type.Literal("user"),
+		Type.Literal("project"),
+		Type.Literal("both"),
+	], { description: "Resource scope for discovery or management." })),
+	config: Type.Optional(Type.Unsafe({ description: "Resource config for management actions." })),
+	dryRun: Type.Optional(Type.Boolean({ description: "Preview a management mutation without writing files." })),
+	confirm: Type.Optional(Type.Boolean({ description: "Required for destructive management actions." })),
+	force: Type.Optional(Type.Boolean({ description: "Override reference checks for destructive management actions." })),
+	keep: Type.Optional(Type.Integer({ minimum: 0, description: "Number of finished runs to keep for prune." })),
+	updateReferences: Type.Optional(Type.Boolean({ description: "When renaming agents or workflows, update team references in the same project/user scope." })),
+});
+
+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";
+	resource?: "agent" | "team" | "workflow";
+	team?: string;
+	workflow?: string;
+	role?: string;
+	agent?: string;
+	goal?: string;
+	task?: string;
+	runId?: string;
+	async?: boolean;
+	workspaceMode?: "single" | "worktree";
+	context?: "fresh" | "fork";
+	cwd?: string;
+	model?: string;
+	skill?: string | string[] | boolean;
+	scope?: "user" | "project" | "both";
+	config?: unknown;
+	dryRun?: boolean;
+	confirm?: boolean;
+	force?: boolean;
+	keep?: number;
+	updateReferences?: boolean;
+}

package/src/state/artifact-store.ts

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import type { ArtifactDescriptor } from "./types.ts";
+import { atomicWriteFile } from "./atomic-write.ts";
+
+function hashContent(content: string): string {
+	return createHash("sha256").update(content).digest("hex");
+}
+
+export interface ArtifactWriteOptions {
+	kind: ArtifactDescriptor["kind"];
+	relativePath: string;
+	content: string;
+	producer: string;
+	retention?: ArtifactDescriptor["retention"];
+}
+
+export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptions): ArtifactDescriptor {
+	const normalizedRelativePath = options.relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	if (normalizedRelativePath.startsWith("../") || path.isAbsolute(normalizedRelativePath)) {
+		throw new Error(`Invalid artifact path: ${options.relativePath}`);
+	}
+	const filePath = path.join(artifactsRoot, normalizedRelativePath);
+	atomicWriteFile(filePath, options.content);
+	const stats = fs.statSync(filePath);
+	return {
+		kind: options.kind,
+		path: filePath,
+		createdAt: new Date().toISOString(),
+		producer: options.producer,
+		sizeBytes: stats.size,
+		contentHash: hashContent(options.content),
+		retention: options.retention ?? "run",
+	};
+}

package/src/state/atomic-write.ts

@@ -0,0 +1,18 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function atomicWriteFile(filePath: string, content: string): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+	fs.writeFileSync(tempPath, content, "utf-8");
+	fs.renameSync(tempPath, filePath);
+}
+
+export function atomicWriteJson<T>(filePath: string, value: T): void {
+	atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function readJsonFile<T>(filePath: string): T | undefined {
+	if (!fs.existsSync(filePath)) return undefined;
+	return JSON.parse(fs.readFileSync(filePath, "utf-8")) as T;
+}

package/src/state/contracts.ts

@@ -0,0 +1,88 @@
+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 type TeamTaskStatus = typeof TEAM_TASK_STATUSES[number];
+
+export const TEAM_TERMINAL_RUN_STATUSES: ReadonlySet<TeamRunStatus> = new Set(["blocked", "completed", "failed", "cancelled"]);
+export const TEAM_TERMINAL_TASK_STATUSES: ReadonlySet<TeamTaskStatus> = new Set(["completed", "failed", "cancelled", "skipped"]);
+
+export const TEAM_RUN_STATUS_TRANSITIONS: Readonly<Record<TeamRunStatus, readonly TeamRunStatus[]>> = {
+	queued: ["planning", "running", "cancelled", "failed"],
+	planning: ["running", "blocked", "cancelled", "failed"],
+	running: ["blocked", "completed", "failed", "cancelled"],
+	blocked: ["running", "cancelled", "failed"],
+	completed: ["running", "cancelled"],
+	failed: ["running", "cancelled"],
+	cancelled: ["running"],
+};
+
+export const TEAM_TASK_STATUS_TRANSITIONS: Readonly<Record<TeamTaskStatus, readonly TeamTaskStatus[]>> = {
+	queued: ["running", "cancelled", "skipped", "failed"],
+	running: ["completed", "failed", "cancelled", "queued"],
+	completed: ["queued"],
+	failed: ["queued", "cancelled"],
+	cancelled: ["queued"],
+	skipped: ["queued", "cancelled"],
+};
+
+export const TEAM_EVENT_TYPES = [
+	"run.created",
+	"run.queued",
+	"run.planning",
+	"run.running",
+	"run.blocked",
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"task.started",
+	"task.completed",
+	"task.failed",
+	"worktree.cleanup",
+	"async.spawned",
+	"async.started",
+	"async.completed",
+	"async.failed",
+	"async.stale",
+] as const;
+export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
+
+export const TEAM_WAKEABLE_EVENT_TYPES: ReadonlySet<TeamEventType> = new Set([
+	"run.blocked",
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"task.completed",
+	"task.failed",
+	"async.completed",
+	"async.failed",
+	"async.stale",
+]);
+
+export function isTeamRunStatus(value: unknown): value is TeamRunStatus {
+	return typeof value === "string" && TEAM_RUN_STATUSES.includes(value as TeamRunStatus);
+}
+
+export function isTeamTaskStatus(value: unknown): value is TeamTaskStatus {
+	return typeof value === "string" && TEAM_TASK_STATUSES.includes(value as TeamTaskStatus);
+}
+
+export function isTerminalRunStatus(status: TeamRunStatus): boolean {
+	return TEAM_TERMINAL_RUN_STATUSES.has(status);
+}
+
+export function isTerminalTaskStatus(status: TeamTaskStatus): boolean {
+	return TEAM_TERMINAL_TASK_STATUSES.has(status);
+}
+
+export function canTransitionRunStatus(from: TeamRunStatus, to: TeamRunStatus): boolean {
+	return from === to || (TEAM_RUN_STATUS_TRANSITIONS[from]?.includes(to) ?? false);
+}
+
+export function canTransitionTaskStatus(from: TeamTaskStatus, to: TeamTaskStatus): boolean {
+	return from === to || (TEAM_TASK_STATUS_TRANSITIONS[from]?.includes(to) ?? false);
+}
+
+export function isWakeableTeamEventType(type: TeamEventType): boolean {
+	return TEAM_WAKEABLE_EVENT_TYPES.has(type);
+}

package/src/state/event-log.ts

@@ -0,0 +1,27 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface TeamEvent {
+	time: string;
+	type: string;
+	runId: string;
+	taskId?: string;
+	message?: string;
+	data?: Record<string, unknown>;
+}
+
+export function appendEvent(eventsPath: string, event: Omit<TeamEvent, "time">): TeamEvent {
+	fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+	const fullEvent: TeamEvent = { time: new Date().toISOString(), ...event };
+	fs.appendFileSync(eventsPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+	return fullEvent;
+}
+
+export function readEvents(eventsPath: string): TeamEvent[] {
+	if (!fs.existsSync(eventsPath)) return [];
+	return fs.readFileSync(eventsPath, "utf-8")
+		.split("\n")
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map((line) => JSON.parse(line) as TeamEvent);
+}

package/src/state/locks.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "./types.ts";
+
+export interface RunLockOptions {
+	staleMs?: number;
+}
+
+const DEFAULT_STALE_MS = 30_000;
+
+function lockPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "run.lock");
+}
+
+export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, options: RunLockOptions = {}): T {
+	const filePath = lockPath(manifest);
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	try {
+		if (fs.existsSync(filePath)) {
+			const stat = fs.statSync(filePath);
+			if (Date.now() - stat.mtimeMs <= staleMs) {
+				throw new Error(`Run '${manifest.runId}' is locked by another operation.`);
+			}
+			fs.rmSync(filePath, { force: true });
+		}
+		fs.writeFileSync(filePath, JSON.stringify({ runId: manifest.runId, pid: process.pid, createdAt: new Date().toISOString() }, null, 2), { flag: "wx" });
+		return fn();
+	} finally {
+		try {
+			fs.rmSync(filePath, { force: true });
+		} catch {
+			// Best-effort lock cleanup.
+		}
+	}
+}
+
+export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promise<T>, options: RunLockOptions = {}): Promise<T> {
+	return withRunLockSync(manifest, () => fn(), options);
+}