pi-crew 0.1.51 → 0.2.0

package/src/state/atomic-write.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { logInternalError } from "../utils/internal-error.ts";
+import { sleepSync } from "../utils/sleep.ts";
 
 const RETRYABLE_RENAME_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
 
@@ -40,25 +41,7 @@ function isSymlinkSafePath(filePath: string): boolean {
 	}
 }
 
-/**
- * Synchronous sleep using Atomics.wait (non-busy) with busy-wait fallback.
- *
- * WARNING: This blocks the Node.js main thread. Only used in atomic-write
- * rename retry path where sync I/O is required by the caller.
- * NOT safe to call from Pi extension async code paths.
- */
-function sleepSync(ms: number): void {
-	try {
-		const buffer = new SharedArrayBuffer(4);
-		Atomics.wait(new Int32Array(buffer), 0, 0, ms);
-	} catch {
-		// Fallback for environments without SharedArrayBuffer / Atomics.wait support.
-		const deadline = Date.now() + ms;
-		while (Date.now() < deadline) {
-			// Busy-wait — only used as last-resort, retry counts are capped.
-		}
-	}
-}
+
 
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
@@ -68,7 +51,7 @@ function isRetryableRenameError(error: unknown): boolean {
 	return Boolean(error && typeof error === "object" && "code" in error && RETRYABLE_RENAME_CODES.has(String((error as NodeJS.ErrnoException).code)));
 }
 
-export function __test__renameWithRetry(tempPath: string, filePath: string, retries = 5, rename: (oldPath: string, newPath: string) => void = fs.renameSync): void {
+export function __test__renameWithRetry(tempPath: string, filePath: string, retries = 10, rename: (oldPath: string, newPath: string) => void = fs.renameSync): void {
 	let lastError: unknown;
 	for (let attempt = 0; attempt <= retries; attempt++) {
 		try {
@@ -77,13 +60,15 @@ export function __test__renameWithRetry(tempPath: string, filePath: string, retr
 		} catch (error) {
 			lastError = error;
 			if (!isRetryableRenameError(error) || attempt === retries) break;
-			sleepSync(Math.min(250, 10 * 2 ** attempt));
+			// Exponential backoff: 10ms, 20ms, 40ms, ..., capped at 500ms
+			// Windows EPERM on rename can take longer when multiple processes contend
+			sleepSync(Math.min(500, 10 * 2 ** attempt));
 		}
 	}
 	throw lastError;
 }
 
-export async function __test__renameWithRetryAsync(tempPath: string, filePath: string, retries = 5, rename: (oldPath: string, newPath: string) => Promise<void> = (source, destination) => fs.promises.rename(source, destination)): Promise<void> {
+export async function __test__renameWithRetryAsync(tempPath: string, filePath: string, retries = 10, rename: (oldPath: string, newPath: string) => Promise<void> = (source, destination) => fs.promises.rename(source, destination)): Promise<void> {
 	let lastError: unknown;
 	for (let attempt = 0; attempt <= retries; attempt++) {
 		try {
@@ -92,7 +77,7 @@ export async function __test__renameWithRetryAsync(tempPath: string, filePath: s
 		} catch (error) {
 			lastError = error;
 			if (!isRetryableRenameError(error) || attempt === retries) break;
-			await sleep(Math.min(250, 10 * 2 ** attempt));
+			await sleep(Math.min(500, 10 * 2 ** attempt));
 		}
 	}
 	throw lastError;
@@ -106,6 +91,12 @@ export function atomicWriteFile(filePath: string, content: string): void {
 	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
 	try {
 		const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
+		const openedStat = fs.fstatSync(fd);
+		if (!openedStat.isFile()) {
+			fs.closeSync(fd);
+			throw new Error(`Refusing to write: opened path is not a regular file: ${tempPath}`);
+		}
 		fs.writeSync(fd, content, undefined, "utf-8");
 		fs.closeSync(fd);
 		__test__renameWithRetry(tempPath, filePath);
@@ -125,7 +116,16 @@ export async function atomicWriteFileAsync(filePath: string, content: string): P
 	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
 	try {
-		await fs.promises.writeFile(tempPath, content, "utf-8");
+		const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+		const fd = await fs.promises.open(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
+		const openedStat = await fd.stat();
+		if (!openedStat.isFile()) {
+			await fd.close();
+			throw new Error(`Refusing to write: opened path is not a regular file: ${tempPath}`);
+		}
+		await fd.writeFile(content, "utf-8");
+		await fd.close();
 		try {
 			await __test__renameWithRetryAsync(tempPath, filePath);
 		} catch (renameError) {
@@ -166,6 +166,13 @@ export async function atomicWriteJsonAsync<T>(filePath: string, value: T): Promi
 }
 
 export function readJsonFile<T>(filePath: string): T | undefined {
-	if (!fs.existsSync(filePath)) return undefined;
-	return JSON.parse(fs.readFileSync(filePath, "utf-8")) as T;
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as T;
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			logInternalError("readJsonFile", err, `filePath=${filePath}`);
+		}
+		return undefined;
+	}
 }

package/src/state/contracts.ts

@@ -36,6 +36,7 @@ export const TEAM_EVENT_TYPES = [
 	"run.completed",
 	"run.failed",
 	"run.cancelled",
+	"task.created",
 	"task.started",
 	"task.progress",
 	"task.blocked",

package/src/state/event-reconstructor.ts

@@ -0,0 +1,217 @@
+/**
+ * Event reconstructor — rebuilds task state from the append-only event log.
+ *
+ * Primary use-case: crash recovery when tasks.json is corrupted or missing.
+ * The materialized tasks.json view is the primary source of truth; this
+ * module provides a fallback reconstruction path from events.jsonl.
+ *
+ * Distilled from pi-autoresearch's append-only event log pattern.
+ */
+import type { TeamEvent } from "./event-log.ts";
+import { readEvents } from "./event-log.ts";
+
+/** Task status values that can be reconstructed from lifecycle events. */
+const RECONSTRUCTABLE_STATUSES = new Set(["created", "queued", "running", "completed", "failed", "cancelled", "skipped", "waiting"]);
+
+/** Event types that carry task lifecycle state transitions. */
+const TASK_LIFECYCLE_EVENT_TYPES = new Set([
+	"task.created",
+	"task.started",
+	"task.completed",
+	"task.failed",
+	"task.skipped",
+	"task.cancelled",
+	"task.waiting",
+	"task.resumed",
+	"task.retried",
+	"task.blocked",
+	"task.progress",
+	"task.green",
+	"task.red",
+]);
+
+/** Terminal events that set finishedAt. */
+const TERMINAL_EVENTS = new Set(["task.completed", "task.failed", "task.cancelled", "task.skipped"]);
+
+/** Mapping from event type to the reconstructed task status. */
+const EVENT_STATUS_MAP: Readonly<Record<string, string>> = {
+	"task.created": "created",
+	"task.started": "running",
+	"task.completed": "completed",
+	"task.failed": "failed",
+	"task.skipped": "skipped",
+	"task.cancelled": "cancelled",
+	"task.waiting": "waiting",
+	"task.resumed": "running",
+	"task.retried": "queued",
+};
+
+/** Task state reconstructed purely from event log entries. */
+export interface ReconstructedTaskState {
+	/** Task identifier */
+	id: string;
+	/** Reconstructed status derived from the last lifecycle event */
+	status: string;
+	/** Timestamp of the task.started event, if observed */
+	startedAt?: string;
+	/** Timestamp of the terminal event (completed/failed/cancelled/skipped), if observed */
+	finishedAt?: string;
+	/** Error message from task.failed events */
+	error?: string;
+	/** Segment number from event data (for retry isolation) */
+	segment?: number;
+	/** Structured diagnostics from event data */
+	diagnostics?: Record<string, unknown>;
+	/** Numeric metrics from event data */
+	metrics?: Record<string, number>;
+}
+
+/** Result of reconstructing task state from events. */
+export interface ReconstructionResult {
+	/** Map of taskId → reconstructed task state */
+	tasks: Map<string, ReconstructedTaskState>;
+	/** Total number of events processed */
+	eventCount: number;
+	/** Number of malformed/unparseable events skipped */
+	corruptedCount: number;
+}
+
+/** Input: either a file path to read events from, or an in-memory array. */
+export type EventSource = string | TeamEvent[];
+
+function isTaskLifecycleEvent(event: TeamEvent): boolean {
+	return TASK_LIFECYCLE_EVENT_TYPES.has(event.type);
+}
+
+function statusFromEventType(eventType: string): string | undefined {
+	return EVENT_STATUS_MAP[eventType];
+}
+
+function safeNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function safeRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	return value as Record<string, unknown>;
+}
+
+function safeNumericRecord(value: unknown): Record<string, number> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	const record: Record<string, number> = {};
+	for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof val === "number" && Number.isFinite(val)) {
+			record[key] = val;
+		}
+	}
+	if (Object.keys(record).length === 0) {
+		return undefined;
+	}
+	return record;
+}
+
+function parseEventLine(line: string): TeamEvent | undefined {
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return undefined;
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (typeof parsed !== "object" || parsed === null) return undefined;
+		if (typeof parsed.type !== "string" || typeof parsed.runId !== "string") return undefined;
+		return parsed as TeamEvent;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Process a stream of validated TeamEvents into reconstructed task states.
+ * Shared logic for both file-based and line-based reconstruction.
+ */
+function processEvents(events: Iterable<TeamEvent>, eventCount: number, corruptedCount: number): ReconstructionResult {
+	const tasks = new Map<string, ReconstructedTaskState>();
+
+	for (const event of events) {
+		if (typeof event.taskId !== "string" || event.taskId.length === 0) continue;
+		if (!isTaskLifecycleEvent(event)) continue;
+
+		const taskId = event.taskId;
+		let task = tasks.get(taskId);
+		if (!task) {
+			task = { id: taskId, status: "created" };
+			tasks.set(taskId, task);
+		}
+
+		const newStatus = statusFromEventType(event.type);
+		if (newStatus && RECONSTRUCTABLE_STATUSES.has(newStatus)) {
+			task.status = newStatus;
+		}
+
+		if (event.type === "task.started") {
+			task.startedAt = event.time;
+		}
+
+		if (TERMINAL_EVENTS.has(event.type)) {
+			task.finishedAt = event.time;
+		}
+
+		if (event.type === "task.failed" && event.message) {
+			task.error = event.message;
+		}
+
+		if (event.data) {
+			const segment = safeNumber(event.data.segment);
+			if (segment !== undefined) task.segment = segment;
+
+			const diagnostics = safeRecord(event.data.diagnostics);
+			if (diagnostics !== undefined) task.diagnostics = diagnostics;
+
+			const metrics = safeNumericRecord(event.data.metrics);
+			if (metrics !== undefined) task.metrics = metrics;
+		}
+	}
+
+	return { tasks, eventCount, corruptedCount };
+}
+
+/**
+ * Reconstruct task states from an append-only event log.
+ *
+ * @param source - Either a file path to events.jsonl, or an array of TeamEvent objects
+ * @returns Reconstruction result with task map, counts
+ */
+export function reconstructTasksFromEvents(source: EventSource): ReconstructionResult {
+	const events: TeamEvent[] = typeof source === "string" ? readEvents(source) : source;
+	return processEvents(events, events.length, 0);
+}
+
+/**
+ * Reconstruct task states from raw JSONL lines (string array).
+ * Useful for testing without creating files.
+ *
+ * @param lines - Array of raw JSONL lines
+ * @returns Reconstruction result
+ */
+export function reconstructTasksFromLines(lines: string[]): ReconstructionResult {
+	let eventCount = 0;
+	let corruptedCount = 0;
+	const parsedEvents: TeamEvent[] = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0) continue;
+		const event = parseEventLine(trimmed);
+		if (event === undefined) {
+			corruptedCount++;
+			eventCount++;
+			continue;
+		}
+		parsedEvents.push(event);
+		eventCount++;
+	}
+
+	return processEvents(parsedEvents, eventCount, corruptedCount);
+}

package/src/state/locks.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { TeamRunManifest } from "./types.ts";
 import { DEFAULT_LOCKS } from "../config/defaults.ts";
+import { sleepSync } from "../utils/sleep.ts";
 
 export interface RunLockOptions {
 	staleMs?: number;
@@ -13,19 +14,7 @@ function lockPath(manifest: TeamRunManifest): string {
 	return path.join(manifest.stateRoot, "run.lock");
 }
 
-function sleepSync(ms: number): void {
-	try {
-		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-	} catch {
-		// Fallback for environments without SharedArrayBuffer / Atomics.wait support.
-		// Use a short busy-wait with yielding intervals instead of continuous spin.
-		const deadline = Date.now() + ms;
-		while (Date.now() < deadline) {
-			// Yield to event loop periodically — reduces CPU from 100% to ~1%
-			for (let i = 0; i < 1e6; i++) { /* busy micro-yield */ }
-		}
-	}
-}
+
 
 function parseCreatedAtFromLock(raw: string): number | undefined {
 	try {

package/src/state/mailbox.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { TeamRunManifest } from "./types.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 import { redactSecrets } from "../utils/redaction.ts";
+import { atomicWriteFile } from "./atomic-write.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
 export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
@@ -232,7 +233,7 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 
 function writeDeliveryState(manifest: TeamRunManifest, state: MailboxDeliveryState): void {
 	ensureRunMailbox(manifest);
-	fs.writeFileSync(deliveryFile(manifest, true), `${JSON.stringify(redactSecrets(state), null, 2)}\n`, "utf-8");
+	atomicWriteFile(deliveryFile(manifest, true), `${JSON.stringify(redactSecrets(state), null, 2)}\n`);
 }
 
 export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<MailboxMessage, "id" | "runId" | "createdAt" | "status"> & { id?: string; status?: MailboxMessageStatus }): MailboxMessage {
@@ -342,7 +343,7 @@ export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMes
 			}
 		}
 		if (found) {
-			fs.writeFileSync(filePath, `${updatedLines.join("\n")}\n`, "utf-8");
+			atomicWriteFile(filePath, `${updatedLines.join("\n")}\n`);
 			return;
 		}
 	}
@@ -384,7 +385,7 @@ export function validateMailbox(manifest: TeamRunManifest, options: { repair?: b
 			}
 		}
 		if (options.repair && validLines.length !== lines.length) {
-			fs.writeFileSync(filePath, `${validLines.join("\n")}${validLines.length ? "\n" : ""}`, "utf-8");
+			atomicWriteFile(filePath, `${validLines.join("\n")}${validLines.length ? "\n" : ""}`);
 			repaired.push(filePath);
 		}
 	}

package/src/state/state-store.ts

@@ -8,6 +8,7 @@ import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
 import { createRunId, createTaskId } from "../utils/ids.ts";
 import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
 import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { withRunLockSync, withRunLock } from "./locks.ts";
 import type { TeamConfig } from "../teams/team-config.ts";
 import type { WorkflowConfig } from "../workflows/workflow-config.ts";
 
@@ -180,32 +181,49 @@ export function createRunManifest(params: {
 }
 
 export function saveRunManifest(manifest: TeamRunManifest): void {
-	atomicWriteJson(path.join(manifest.stateRoot, "manifest.json"), manifest);
-	invalidateRunCache(manifest.stateRoot);
+	withRunLockSync(manifest, () => {
+		atomicWriteJson(path.join(manifest.stateRoot, "manifest.json"), manifest);
+		invalidateRunCache(manifest.stateRoot);
+	});
 }
 
 export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<void> {
-	await atomicWriteJsonAsync(path.join(manifest.stateRoot, "manifest.json"), manifest);
-	invalidateRunCache(manifest.stateRoot);
+	await withRunLock(manifest, async () => {
+		await atomicWriteJsonAsync(path.join(manifest.stateRoot, "manifest.json"), manifest);
+		invalidateRunCache(manifest.stateRoot);
+	});
 }
 
 export function saveRunTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]): void {
-	atomicWriteJson(manifest.tasksPath, tasks);
-	invalidateRunCache(manifest.stateRoot);
+	withRunLockSync(manifest, () => {
+		atomicWriteJson(manifest.tasksPath, tasks);
+		invalidateRunCache(manifest.stateRoot);
+	});
 }
 
 export async function saveRunTasksAsync(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<void> {
-	await atomicWriteJsonAsync(manifest.tasksPath, tasks);
-	invalidateRunCache(manifest.stateRoot);
+	await withRunLock(manifest, async () => {
+		await atomicWriteJsonAsync(manifest.tasksPath, tasks);
+		invalidateRunCache(manifest.stateRoot);
+	});
 }
 
-/** M8: Atomically save manifest + tasks and invalidate cache once to prevent stale reads between saves */
+/**
+ * Save manifest and tasks files with individual atomic writes.
+ *
+ * Note: The two writes are individually atomic (via rename) but not
+ * jointly atomic — a crash between writes can leave them inconsistent.
+ * This is acceptable because crash recovery detects and repairs
+ * inconsistent state on next session start.
+ */
 export async function saveManifestAndTasksAtomic(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<void> {
-	await Promise.all([
-		atomicWriteJsonAsync(path.join(manifest.stateRoot, "manifest.json"), manifest),
-		atomicWriteJsonAsync(manifest.tasksPath, tasks),
-	]);
-	invalidateRunCache(manifest.stateRoot);
+	await withRunLock(manifest, async () => {
+		await Promise.all([
+			atomicWriteJsonAsync(path.join(manifest.stateRoot, "manifest.json"), manifest),
+			atomicWriteJsonAsync(manifest.tasksPath, tasks),
+		]);
+		invalidateRunCache(manifest.stateRoot);
+	});
 }
 
 export interface UpdateRunStatusOptions {

package/src/state/task-claims.ts

@@ -1,44 +1,44 @@
-import { randomUUID } from "node:crypto";
-import type { TeamTaskState } from "./types.ts";
-
-export interface TaskClaimState {
-	owner: string;
-	token: string;
-	leasedUntil: string;
-}
-
-export function createTaskClaim(owner: string, leaseMs = 5 * 60_000, now = new Date()): TaskClaimState {
-	return { owner, token: randomUUID(), leasedUntil: new Date(now.getTime() + leaseMs).toISOString() };
-}
-
-export function isTaskClaimExpired(claim: TaskClaimState | undefined, now = new Date()): boolean {
-	if (!claim) return false;
-	const parsed = Date.parse(claim.leasedUntil);
-	// Corrupt or invalid date strings produce NaN — treat as expired immediately.
-	return Number.isFinite(parsed) ? parsed <= now.getTime() : true;
-}
-
-export function canUseTaskClaim(task: Pick<TeamTaskState, "claim">, owner: string, token: string, now = new Date()): boolean {
-	return task.claim?.owner === owner && task.claim.token === token && !isTaskClaimExpired(task.claim, now);
-}
-
-export function claimTask<T extends TeamTaskState>(task: T, owner: string, leaseMs?: number, now = new Date()): T {
-	if (task.claim && !isTaskClaimExpired(task.claim, now)) {
-		throw new Error(`Task '${task.id}' is already claimed by '${task.claim.owner}'.`);
-	}
-	return { ...task, claim: createTaskClaim(owner, leaseMs, now) };
-}
-
-export function releaseTaskClaim<T extends TeamTaskState>(task: T, owner: string, token: string, now = new Date()): T {
-	if (!canUseTaskClaim(task, owner, token, now)) {
-		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
-	}
-	return { ...task, claim: undefined };
-}
-
-export function transitionClaimedTaskStatus<T extends TeamTaskState>(task: T, owner: string, token: string, status: T["status"], now = new Date()): T {
-	if (!canUseTaskClaim(task, owner, token, now)) {
-		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
-	}
-	return { ...task, status };
-}
+import { randomUUID } from "node:crypto";
+import type { TeamTaskState } from "./types.ts";
+
+export interface TaskClaimState {
+	owner: string;
+	token: string;
+	leasedUntil: string;
+}
+
+export function createTaskClaim(owner: string, leaseMs = 5 * 60_000, now = new Date()): TaskClaimState {
+	return { owner, token: randomUUID(), leasedUntil: new Date(now.getTime() + leaseMs).toISOString() };
+}
+
+export function isTaskClaimExpired(claim: TaskClaimState | undefined, now = new Date()): boolean {
+	if (!claim) return false;
+	const parsed = Date.parse(claim.leasedUntil);
+	// Corrupt or invalid date strings produce NaN — treat as expired immediately.
+	return Number.isFinite(parsed) ? parsed <= now.getTime() : true;
+}
+
+export function canUseTaskClaim(task: Pick<TeamTaskState, "claim">, owner: string, token: string, now = new Date()): boolean {
+	return task.claim?.owner === owner && task.claim.token === token && !isTaskClaimExpired(task.claim, now);
+}
+
+export function claimTask<T extends TeamTaskState>(task: T, owner: string, leaseMs?: number, now = new Date()): T {
+	if (task.claim && !isTaskClaimExpired(task.claim, now)) {
+		throw new Error(`Task '${task.id}' is already claimed by '${task.claim.owner}'.`);
+	}
+	return { ...task, claim: createTaskClaim(owner, leaseMs, now) };
+}
+
+export function releaseTaskClaim<T extends TeamTaskState>(task: T, owner: string, token: string, now = new Date()): T {
+	if (!canUseTaskClaim(task, owner, token, now)) {
+		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
+	}
+	return { ...task, claim: undefined };
+}
+
+export function transitionClaimedTaskStatus<T extends TeamTaskState>(task: T, owner: string, token: string, status: T["status"], now = new Date()): T {
+	if (!canUseTaskClaim(task, owner, token, now)) {
+		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
+	}
+	return { ...task, status };
+}

package/src/state/types.ts

@@ -267,6 +267,15 @@ export interface TeamTaskState {
 		lastDecision?: PolicyDecision;
 	};
 	controlReservation?: ControlReservation;
+
+	/** Structured diagnostics per task (ASI pattern from pi-autoresearch). */
+	diagnostics?: Record<string, unknown>;
+
+	/** Segment counter for task retry isolation. Default 0 (first attempt). Incremented on retry. */
+	segment?: number;
+
+	/** Parsed metric key-values from worker output (CREW_METRIC lines). */
+	metrics?: Record<string, number>;
 }
 
 export interface ControlReservation {

package/src/state/usage.ts

@@ -1,29 +1,29 @@
-import type { TeamTaskState, UsageState } from "./types.ts";
-
-export function aggregateUsage(tasks: TeamTaskState[]): UsageState | undefined {
-	const total: UsageState = {};
-	let found = false;
-	for (const task of tasks) {
-		if (!task.usage) continue;
-		found = true;
-		total.input = (total.input ?? 0) + (task.usage.input ?? 0);
-		total.output = (total.output ?? 0) + (task.usage.output ?? 0);
-		total.cacheRead = (total.cacheRead ?? 0) + (task.usage.cacheRead ?? 0);
-		total.cacheWrite = (total.cacheWrite ?? 0) + (task.usage.cacheWrite ?? 0);
-		total.cost = (total.cost ?? 0) + (task.usage.cost ?? 0);
-		total.turns = (total.turns ?? 0) + (task.usage.turns ?? 0);
-	}
-	return found ? total : undefined;
-}
-
-export function formatUsage(usage: UsageState | undefined): string {
-	if (!usage) return "(none)";
-	const parts: string[] = [];
-	if (usage.input !== undefined) parts.push(`input=${usage.input}`);
-	if (usage.output !== undefined) parts.push(`output=${usage.output}`);
-	if (usage.cacheRead !== undefined) parts.push(`cacheRead=${usage.cacheRead}`);
-	if (usage.cacheWrite !== undefined) parts.push(`cacheWrite=${usage.cacheWrite}`);
-	if (usage.cost !== undefined && Number.isFinite(usage.cost)) parts.push(`cost=${usage.cost.toFixed(6)}`);
-	if (usage.turns !== undefined) parts.push(`turns=${usage.turns}`);
-	return parts.join(", ") || "(none)";
-}
+import type { TeamTaskState, UsageState } from "./types.ts";
+
+export function aggregateUsage(tasks: TeamTaskState[]): UsageState | undefined {
+	const total: UsageState = {};
+	let found = false;
+	for (const task of tasks) {
+		if (!task.usage) continue;
+		found = true;
+		total.input = (total.input ?? 0) + (task.usage.input ?? 0);
+		total.output = (total.output ?? 0) + (task.usage.output ?? 0);
+		total.cacheRead = (total.cacheRead ?? 0) + (task.usage.cacheRead ?? 0);
+		total.cacheWrite = (total.cacheWrite ?? 0) + (task.usage.cacheWrite ?? 0);
+		total.cost = (total.cost ?? 0) + (task.usage.cost ?? 0);
+		total.turns = (total.turns ?? 0) + (task.usage.turns ?? 0);
+	}
+	return found ? total : undefined;
+}
+
+export function formatUsage(usage: UsageState | undefined): string {
+	if (!usage) return "(none)";
+	const parts: string[] = [];
+	if (usage.input !== undefined) parts.push(`input=${usage.input}`);
+	if (usage.output !== undefined) parts.push(`output=${usage.output}`);
+	if (usage.cacheRead !== undefined) parts.push(`cacheRead=${usage.cacheRead}`);
+	if (usage.cacheWrite !== undefined) parts.push(`cacheWrite=${usage.cacheWrite}`);
+	if (usage.cost !== undefined && Number.isFinite(usage.cost)) parts.push(`cost=${usage.cost.toFixed(6)}`);
+	if (usage.turns !== undefined) parts.push(`turns=${usage.turns}`);
+	return parts.join(", ") || "(none)";
+}

package/src/subagents/async-entry.ts

@@ -1 +1 @@
-export * from "../runtime/async-runner.ts";
+export * from "../runtime/async-runner.ts";

package/src/subagents/index.ts

@@ -1,3 +1,3 @@
-export * from "./spawn.ts";
-export * from "./manager.ts";
-export * from "./async-entry.ts";
+export * from "./spawn.ts";
+export * from "./manager.ts";
+export * from "./async-entry.ts";

package/src/subagents/live/control.ts

@@ -1 +1 @@
-export * from "../../runtime/live-agent-control.ts";
+export * from "../../runtime/live-agent-control.ts";

package/src/subagents/live/manager.ts

@@ -1 +1 @@
-export * from "../../runtime/live-agent-manager.ts";
+export * from "../../runtime/live-agent-manager.ts";

package/src/subagents/live/realtime.ts

@@ -1 +1 @@
-export * from "../../runtime/live-control-realtime.ts";
+export * from "../../runtime/live-control-realtime.ts";