pi-crew 0.1.37 → 0.1.39

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

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

@@ -1,108 +1,122 @@
-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 const CLEANUP_MARKER_FILE = ".last-cleanup";
-
-export interface ArtifactWriteOptions {
-	kind: ArtifactDescriptor["kind"];
-	relativePath: string;
-	content: string;
-	producer: string;
-	retention?: ArtifactDescriptor["retention"];
-}
-
-export interface ArtifactCleanupOptions {
-	maxAgeDays: number;
-	maxAgeMs?: number;
-	markerFile?: string;
-	scanGraceMs?: number;
-}
-
-function parseAgeDays(value: unknown): number | undefined {
-	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
-	return Math.floor(value);
-}
-
-function nowMs(): number {
-	return Date.now();
-}
-
-function readMarkerMtime(artifactsRoot: string, markerFile: string): number | undefined {
-	try {
-		return fs.statSync(path.join(artifactsRoot, markerFile)).mtimeMs;
-	} catch {
-		return undefined;
-	}
-}
-
-function shouldCleanup(artifactsRoot: string, markerFile: string, scanGraceMs: number): boolean {
-	const marker = readMarkerMtime(artifactsRoot, markerFile);
-	if (marker === undefined) return true;
-	return nowMs() - marker >= scanGraceMs;
-}
-
-export function writeCleanupMarker(artifactsRoot: string, markerFile: string): void {
-	fs.mkdirSync(artifactsRoot, { recursive: true });
-	fs.writeFileSync(path.join(artifactsRoot, markerFile), String(nowMs()), "utf-8");
-}
-
-export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactCleanupOptions): void {
-	if (!fs.existsSync(artifactsRoot)) return;
-	const maxAgeDays = parseAgeDays(options.maxAgeDays);
-	if (maxAgeDays === undefined) return;
-	const markerFile = options.markerFile ?? CLEANUP_MARKER_FILE;
-	const scanGraceMs = options.scanGraceMs ?? 24 * 60 * 60 * 1000;
-	if (!shouldCleanup(artifactsRoot, markerFile, scanGraceMs)) return;
-	const maxAgeMs = options.maxAgeMs ?? maxAgeDays * 24 * 60 * 60 * 1000;
-	const cutoff = nowMs() - maxAgeMs;
-	let didCleanup = false;
-	try {
-		const entries = fs.readdirSync(artifactsRoot, { withFileTypes: true });
-		for (const entry of entries) {
-			if (entry.name === markerFile) continue;
-			const target = path.join(artifactsRoot, entry.name);
-			try {
-				const stat = fs.statSync(target);
-				if (stat.mtimeMs >= cutoff) continue;
-				if (stat.isDirectory()) {
-					fs.rmSync(target, { recursive: true, force: true });
-				} else {
-					fs.unlinkSync(target);
-				}
-				didCleanup = true;
-			} catch {
-				// Ignore cleanup races and permission issues in best-effort mode.
-			}
-		}
-		writeCleanupMarker(artifactsRoot, markerFile);
-	} catch {
-		// Ignore unreadable roots in best-effort mode.
-	}
-	if (!didCleanup) writeCleanupMarker(artifactsRoot, markerFile);
-}
-
-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",
-	};
-}
+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";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+function hashContent(content: string): string {
+	return createHash("sha256").update(content).digest("hex");
+}
+
+export const CLEANUP_MARKER_FILE = ".last-cleanup";
+
+export interface ArtifactWriteOptions {
+	kind: ArtifactDescriptor["kind"];
+	relativePath: string;
+	content: string;
+	producer: string;
+	retention?: ArtifactDescriptor["retention"];
+}
+
+export interface ArtifactCleanupOptions {
+	maxAgeDays: number;
+	maxAgeMs?: number;
+	markerFile?: string;
+	scanGraceMs?: number;
+}
+
+function parseAgeDays(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+	return Math.floor(value);
+}
+
+function nowMs(): number {
+	return Date.now();
+}
+
+function readMarkerMtime(artifactsRoot: string, markerFile: string): number | undefined {
+	try {
+		return fs.statSync(path.join(artifactsRoot, markerFile)).mtimeMs;
+	} catch {
+		return undefined;
+	}
+}
+
+function shouldCleanup(artifactsRoot: string, markerFile: string, scanGraceMs: number): boolean {
+	const marker = readMarkerMtime(artifactsRoot, markerFile);
+	if (marker === undefined) return true;
+	return nowMs() - marker >= scanGraceMs;
+}
+
+export function writeCleanupMarker(artifactsRoot: string, markerFile: string): void {
+	fs.mkdirSync(artifactsRoot, { recursive: true });
+	fs.writeFileSync(path.join(artifactsRoot, markerFile), String(nowMs()), "utf-8");
+}
+
+export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactCleanupOptions): void {
+	if (!fs.existsSync(artifactsRoot)) return;
+	const maxAgeDays = parseAgeDays(options.maxAgeDays);
+	if (maxAgeDays === undefined) return;
+	const markerFile = options.markerFile ?? CLEANUP_MARKER_FILE;
+	const scanGraceMs = options.scanGraceMs ?? 24 * 60 * 60 * 1000;
+	if (!shouldCleanup(artifactsRoot, markerFile, scanGraceMs)) return;
+	const maxAgeMs = options.maxAgeMs ?? maxAgeDays * 24 * 60 * 60 * 1000;
+	const cutoff = nowMs() - maxAgeMs;
+	let didCleanup = false;
+	try {
+		const entries = fs.readdirSync(artifactsRoot, { withFileTypes: true });
+		for (const entry of entries) {
+			if (entry.name === markerFile) continue;
+			const target = path.join(artifactsRoot, entry.name);
+			try {
+				const stat = fs.statSync(target);
+				if (stat.mtimeMs >= cutoff) continue;
+				if (stat.isDirectory()) {
+					fs.rmSync(target, { recursive: true, force: true });
+				} else {
+					fs.unlinkSync(target);
+				}
+				didCleanup = true;
+			} catch {
+				// Ignore cleanup races and permission issues in best-effort mode.
+			}
+		}
+		writeCleanupMarker(artifactsRoot, markerFile);
+	} catch {
+		// Ignore unreadable roots in best-effort mode.
+	}
+	if (!didCleanup) writeCleanupMarker(artifactsRoot, markerFile);
+}
+
+function resolveInside(baseDir: string, relativePath: string): string {
+	const normalizedRelativePath = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	if (!normalizedRelativePath || normalizedRelativePath.split("/").some((segment) => segment === "..") || path.isAbsolute(normalizedRelativePath)) {
+		throw new Error(`Invalid artifact path: ${relativePath}`);
+	}
+	const base = path.resolve(baseDir);
+	const resolved = path.resolve(base, normalizedRelativePath);
+	const relative = path.relative(base, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Invalid artifact path: ${relativePath}`);
+	return resolved;
+}
+
+export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptions): ArtifactDescriptor {
+	const filePath = resolveInside(artifactsRoot, options.relativePath);
+	fs.mkdirSync(artifactsRoot, { recursive: true });
+	if (fs.lstatSync(artifactsRoot).isSymbolicLink()) throw new Error(`Path is outside ${path.dirname(artifactsRoot)}: ${artifactsRoot}`);
+	resolveRealContainedPath(path.dirname(artifactsRoot), path.basename(artifactsRoot));
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	resolveRealContainedPath(artifactsRoot, path.dirname(filePath));
+	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/contracts.ts

@@ -1,105 +1,105 @@
-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.progress",
-	"task.blocked",
-	"task.green",
-	"task.red",
-	"task.completed",
-	"task.failed",
-	"task.cancelled",
-	"task.skipped",
-	"review.approved",
-	"review.rejected",
-	"policy.action",
-	"policy.escalated",
-	"recovery.attempted",
-	"recovery.escalated",
-	"branch.stale",
-	"mailbox.timeout",
-	"worktree.cleanup",
-	"worktree.dirty",
-	"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",
-	"task.cancelled",
-	"task.skipped",
-	"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);
-}
+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.progress",
+	"task.blocked",
+	"task.green",
+	"task.red",
+	"task.completed",
+	"task.failed",
+	"task.cancelled",
+	"task.skipped",
+	"review.approved",
+	"review.rejected",
+	"policy.action",
+	"policy.escalated",
+	"recovery.attempted",
+	"recovery.escalated",
+	"branch.stale",
+	"mailbox.timeout",
+	"worktree.cleanup",
+	"worktree.dirty",
+	"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",
+	"task.cancelled",
+	"task.skipped",
+	"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);
+}