@maxiaochao/pi-toolkit 0.10.21 → 0.10.23

package/packages/herdr-subagents/src/reconcile.ts

@@ -2,25 +2,31 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import type { HerdrAutomation } from "./herdr.ts";
 import { isProcessAlive, type OwnerIdentity } from "./ownership.ts";
-import { writeJsonAtomic } from "./state.ts";
 import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
-import { applyReport, applyTaskStatus, isActiveStatus, normalizeNeedsInputReport, persistFailureReport, readReport, readRunRecord, readTaskRecord, type RunRecord, type TaskStatus } from "./records.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, persistFailureReport, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type RunRecord } from "./records.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import { attemptReportPath } from "./attempts.ts";
-
+import { writeJsonAtomic } from "./state.ts";
+import { withRunStateLock } from "./run-state.ts";
+import { aggregateTasksWithResume, claimResumeCleanup, memberOwnedBy, memberOwnerIsStale, readTaskEntries, type ResumeCleanupClaim } from "./resume-state.ts";
 
 export interface CancellationResult { cancelledRuns: number; cleanupErrors: string[]; }
 export interface ReconciliationResult { liveTasks: number; settledTasks: number; interruptedTasks: number; cancelledTasks: number; cleanupErrors: string[]; }
 
-async function closeRunTab(run: RunRecord, runFile: string, herdr: HerdrAutomation, cleanupErrors: string[]): Promise<void> {
-	if (!run.tabId) return;
+async function closeRunTab(run: RunRecord, runFile: string, herdr: HerdrAutomation, cleanupErrors: string[], claim?: ResumeCleanupClaim): Promise<void> {
+	const tabId = claim?.tabId ?? run.tabId;
+	if (!tabId) return;
 	const forceClose = new AbortController();
 	forceClose.abort(new Error("Owning parent Pi session is no longer active."));
 	const errorsBeforeCleanup = cleanupErrors.length;
 	try {
-		await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal: forceClose.signal, onError: (message) => cleanupErrors.push(message), errorPrefix: `Could not close Subagent tab ${run.tabId}` });
+		await cleanupRunTab({
+			herdr, tabId, runFile, runRecord: run, signal: forceClose.signal,
+			onError: (message) => cleanupErrors.push(message), errorPrefix: `Could not close Subagent tab ${tabId}`,
+			onClosed: claim ? (latest) => { if (latest.resume?.generation === claim.generation && latest.resume.phase === "closing") delete latest.resume; } : undefined,
+		});
 	} catch (error) {
-		if (cleanupErrors.length === errorsBeforeCleanup) cleanupErrors.push(`Could not close Subagent tab ${run.tabId}: ${error instanceof Error ? error.message : String(error)}`);
+		if (cleanupErrors.length === errorsBeforeCleanup) cleanupErrors.push(`Could not close Subagent tab ${tabId}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
 
@@ -34,32 +40,47 @@ export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomati
 	for (const runEntry of readdirSync(runsDirectory)) {
 		const runDirectory = join(runsDirectory, runEntry);
 		const runFile = join(runDirectory, "run.json");
-		let run: RunRecord;
-		try { run = await readRunRecord(runFile); }
-		catch (error) {
-			result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`);
-			continue;
-		}
-		if (options.runId && run.id !== options.runId) continue;
-		if (!isActiveStatus(run.status)) continue;
-		if (options.owner?.sessionId && run.ownerSessionId !== options.owner.sessionId) continue;
-		const now = new Date().toISOString();
-		const tasksDirectory = join(runDirectory, "tasks");
-		if (existsSync(tasksDirectory)) for (const taskEntry of readdirSync(tasksDirectory)) {
-			const taskFile = join(tasksDirectory, taskEntry, "task.json");
-			let task;
-			try { task = await readTaskRecord(taskFile); }
-			catch (error) {
-				result.cleanupErrors.push(`Could not cancel Subagent task ${taskFile}: ${error instanceof Error ? error.message : String(error)}`);
-				continue;
-			}
-			if (!isActiveStatus(task.status)) continue;
-			applyTaskStatus(task, "cancelled", { error: reason, at: now });
-			await writeJsonAtomic(taskFile, task);
-		}
-		applyRunStatus(run, "cancelled", { error: reason, at: now });
-		await writeJsonAtomic(runFile, run);
-		await closeRunTab(run, runFile, herdr, result.cleanupErrors);
+		let snapshot: RunRecord;
+		try { snapshot = await readRunRecord(runFile); } catch (error) { result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`); continue; }
+		if (options.runId && snapshot.id !== options.runId) continue;
+		let affected = false;
+		let claim: ResumeCleanupClaim | undefined;
+		let latest = snapshot;
+		try {
+			latest = await withRunStateLock(runFile, undefined, async (run) => {
+				const entries = await readTaskEntries(runDirectory);
+				if (run.resume?.phase === "active") {
+					for (const [taskId, member] of Object.entries(run.resume.active)) {
+						if (!memberOwnedBy(member, options.owner)) continue;
+						const entry = entries.find(({ task }) => task.id === taskId);
+						if (entry && (member.phase === "allocating" || entry.task.currentAttemptId === member.attemptId)) {
+							entry.task.currentAttemptId = member.attemptId;
+							if (isActiveStatus(entry.task.status) || member.phase === "allocating") {
+								applyTaskStatus(entry.task, "cancelled", { error: reason });
+								await writeJsonAtomic(join(entry.directory, "task.json"), entry.task);
+							}
+						}
+						delete run.resume.active[taskId];
+						affected = true;
+					}
+					applyRunStatus(run, aggregateTasksWithResume(entries.map(({ task }) => task), run.resume.active), { error: reason });
+					claim = claimResumeCleanup(run);
+					return run;
+				}
+				const ownerMatches = !options.owner?.sessionId || run.ownerSessionId === options.owner.sessionId;
+				if (!ownerMatches || !isActiveStatus(run.status)) return run;
+				for (const { directory, task } of entries) {
+					if (!isActiveStatus(task.status)) continue;
+					applyTaskStatus(task, "cancelled", { error: reason });
+					await writeJsonAtomic(join(directory, "task.json"), task);
+				}
+				applyRunStatus(run, "cancelled", { error: reason });
+				affected = true;
+				return run;
+			});
+		} catch (error) { result.cleanupErrors.push(`Could not cancel Subagent run ${snapshot.id}: ${error instanceof Error ? error.message : String(error)}`); continue; }
+		if (!affected) continue;
+		if (claim || (!latest.resume && latest.status === "cancelled")) await closeRunTab(latest, runFile, herdr, result.cleanupErrors, claim);
 		result.cancelledRuns += 1;
 	}
 	return result;
@@ -72,120 +93,120 @@ export async function reconcileSubagentRuns(cwd: string, herdr: HerdrAutomation,
 	for (const runEntry of readdirSync(runsDirectory)) {
 		const runDirectory = join(runsDirectory, runEntry);
 		const runFile = join(runDirectory, "run.json");
-		let run: RunRecord;
-		try { run = await readRunRecord(runFile); }
-		catch (error) {
-			result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`);
-			continue;
-		}
-		const differentOwner = owner?.sessionId !== undefined && run.ownerSessionId !== owner.sessionId;
-		if (differentOwner && run.ownerProcessId !== (owner?.processId ?? process.pid) && isProcessAlive(run.ownerProcessId)) continue;
-		for (const pendingTabId of [...(run.cleanupPendingTabIds ?? [])]) {
-			const errorsBeforeCleanup = result.cleanupErrors.length;
-			try {
-				await cleanupRunTab({ herdr, tabId: pendingTabId, runFile, runRecord: run, onError: (message) => result.cleanupErrors.push(message), errorPrefix: `Could not finish deferred cleanup for Herdr tab ${pendingTabId}` });
-			} catch (error) {
-				if (result.cleanupErrors.length === errorsBeforeCleanup) result.cleanupErrors.push(`Could not finish deferred cleanup for Herdr tab ${pendingTabId}: ${error instanceof Error ? error.message : String(error)}`);
-			}
+		let snapshot: RunRecord;
+		try { snapshot = await readRunRecord(runFile); } catch (error) { result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`); continue; }
+		for (const pendingTabId of [...(snapshot.cleanupPendingTabIds ?? [])]) {
+			try { await cleanupRunTab({ herdr, tabId: pendingTabId, runFile, runRecord: snapshot, onError: (message) => result.cleanupErrors.push(message), errorPrefix: `Could not finish deferred cleanup for Herdr tab ${pendingTabId}` }); }
+			catch (error) { result.cleanupErrors.push(`Could not finish deferred cleanup for Herdr tab ${pendingTabId}: ${error instanceof Error ? error.message : String(error)}`); }
 		}
-		if (!isActiveStatus(run.status)) continue;
 		const tasksDirectory = join(runDirectory, "tasks");
 		if (!existsSync(tasksDirectory)) {
-			const message = `Active Subagent run ${run.id} has no tasks directory.`;
+			const message = `Active Subagent run ${snapshot.id} has no tasks directory.`;
 			result.cleanupErrors.push(message);
-			applyRunStatus(run, "failed", { error: message });
-			await writeJsonAtomic(runFile, run);
-			await closeRunTab(run, runFile, herdr, result.cleanupErrors);
+			const failedRun = await withRunStateLock(runFile, undefined, (run) => applyRunStatus(run, "failed", { error: message }));
+			result.interruptedTasks += 1;
+			await closeRunTab(failedRun, runFile, herdr, result.cleanupErrors);
 			continue;
 		}
-		const statuses: TaskStatus[] = [];
-		let unreadableTasks = 0;
-		for (const taskEntry of readdirSync(tasksDirectory)) {
-			const taskFile = join(tasksDirectory, taskEntry, "task.json");
-			let task;
-			try { task = await readTaskRecord(taskFile); }
-			catch (error) {
-				result.cleanupErrors.push(`Could not inspect Subagent task ${taskFile}: ${error instanceof Error ? error.message : String(error)}`);
-				unreadableTasks += 1;
-				continue;
-			}
-			if (isActiveStatus(task.status)) {
-				const canonicalReportFile = join(tasksDirectory, taskEntry, "report.json");
-				let currentAttemptReport: string | undefined;
-				if (task.currentAttemptId) {
-					try { currentAttemptReport = attemptReportPath(join(tasksDirectory, taskEntry), task.currentAttemptId); }
-					catch (error) { result.cleanupErrors.push(`Invalid current attempt for Subagent task ${taskFile}: ${error instanceof Error ? error.message : String(error)}`); }
-				}
-				// Once an attempt is identified, the canonical report is only history from
-				// an earlier attempt until this attempt publishes its scoped report.
-				const reportFile = task.currentAttemptId ? currentAttemptReport : canonicalReportFile;
-				if (reportFile && existsSync(reportFile) && (task.status === "running" || task.status === "starting")) {
-					try {
-						const submittedReport = await readReport(reportFile);
-						const report = normalizeNeedsInputReport(submittedReport, Number(run.effectiveConcurrency) || 1);
-						if (task.currentAttemptId && report.attemptId !== task.currentAttemptId) throw new Error(`Report attempt '${report.attemptId ?? "unknown"}' does not match current attempt '${task.currentAttemptId}'.`);
-						applyReport(task, report, report.reportedAt ?? new Date().toISOString());
-						if (report !== submittedReport) await writeJsonAtomic(reportFile, report);
-						if (reportFile !== canonicalReportFile || report !== submittedReport) await writeJsonAtomic(canonicalReportFile, report);
-						result.settledTasks += 1;
-					} catch (error) {
-						const detail = error instanceof Error ? error.message : String(error);
-						result.cleanupErrors.push(`Invalid Subagent report ${reportFile}: ${detail}`);
-						await persistFailureReport(canonicalReportFile, { status: "failed", summary: "Recovered task had an invalid structured report.", documents: [], error: detail, reportedAt: new Date().toISOString() }, reportFile !== canonicalReportFile);
-						applyTaskStatus(task, "failed", { error: `Invalid structured report: ${detail}` });
-						result.settledTasks += 1;
-						result.interruptedTasks += 1;
+		let claim: ResumeCleanupClaim | undefined;
+		let closeRegular = false;
+		let latest = snapshot;
+		try {
+			latest = await withRunStateLock(runFile, undefined, async (run) => {
+				const entries = await readTaskEntries(runDirectory);
+				// Recover each historical member independently. A live sibling owner is never
+				// cancelled merely because another owner invokes reconciliation.
+				if (run.resume?.phase === "active") for (const [taskId, member] of Object.entries(run.resume.active)) {
+					const entry = entries.find(({ task }) => task.id === taskId);
+					if (!entry) { if (memberOwnerIsStale(member, owner)) delete run.resume.active[taskId]; continue; }
+					if (member.phase === "allocating" && entry.task.currentAttemptId === member.attemptId && isActiveStatus(entry.task.status)) member.phase = "running";
+					const attemptMatches = entry.task.currentAttemptId === member.attemptId;
+					if (!memberOwnerIsStale(member, owner)) continue;
+					const scopedResumeReport = attemptReportPath(entry.directory, member.attemptId);
+					if (existsSync(scopedResumeReport)) {
+						try {
+							const submitted = await readReport(scopedResumeReport);
+							if (submitted.attemptId !== member.attemptId) throw new Error(`Report attempt '${submitted.attemptId ?? "unknown"}' does not match resume member '${member.attemptId}'.`);
+							const report = submitted;
+							entry.task.currentAttemptId = member.attemptId;
+							const status = applyReport(entry.task, report, report.reportedAt);
+							await Promise.all([
+								writeJsonAtomic(join(entry.directory, "task.json"), entry.task),
+								writeJsonAtomic(join(entry.directory, "report.json"), report),
+							]);
+							if (status === "blocked") member.phase = "blocked";
+							else delete run.resume.active[taskId];
+							result.settledTasks += 1;
+							continue;
+						} catch (error) {
+							result.cleanupErrors.push(`Invalid historical resume report ${scopedResumeReport}: ${error instanceof Error ? error.message : String(error)}`);
+						}
 					}
-				}
-				if (differentOwner && isActiveStatus(task.status)) {
-					if (task.status === "blocked") {
-						const cancelledReport = {
-							status: "failed",
-							summary: "Blocked task was cancelled because its parent Pi session is no longer active.",
-							documents: [],
-							error: "Owning parent Pi session is no longer active.",
-							...(task.currentAttemptId ? { attemptId: task.currentAttemptId } : {}),
-							reportedAt: new Date().toISOString(),
-						} as const;
-						await persistFailureReport(canonicalReportFile, cancelledReport, true);
-						if (currentAttemptReport) await writeJsonAtomic(currentAttemptReport, cancelledReport);
+					if (member.phase === "allocating" || attemptMatches) {
+						entry.task.currentAttemptId = member.attemptId;
+						const reportFile = join(entry.directory, "report.json");
+						await settleAttemptFailure(entry.task, reportFile, { cancelled: true, error: "Historical resume owner disappeared before the attempt settled.", name: `${entry.task.name ?? entry.task.agent} follow-up`, replaceReport: true });
+						await writeJsonAtomic(join(entry.directory, "task.json"), entry.task);
+						result.cancelledTasks += 1; result.interruptedTasks += 1;
 					}
-					applyTaskStatus(task, "cancelled", { error: "Owning parent Pi session is no longer active." });
-					result.cancelledTasks += 1;
-					result.interruptedTasks += 1;
-				} else if (!differentOwner && (task.status === "running" || task.status === "starting")) {
-					let childIsLive = false;
-					if (task.paneId) {
-						try { childIsLive = await herdr.isTaskRunning(task.paneId); }
-						catch (error) {
-							result.cleanupErrors.push(`Could not inspect Subagent pane ${task.paneId}: ${error instanceof Error ? error.message : String(error)}`);
-							childIsLive = true;
+					delete run.resume.active[taskId];
+				}
+				const differentOwner = owner?.sessionId !== undefined && run.ownerSessionId !== owner.sessionId && (run.ownerProcessId === (owner.processId ?? process.pid) || !isProcessAlive(run.ownerProcessId));
+				for (const entry of entries) {
+					const task = entry.task;
+					const member = run.resume?.active[task.id];
+					if (member) continue;
+					if (!isActiveStatus(task.status)) continue;
+					const canonicalReportFile = join(entry.directory, "report.json");
+					let scopedReportFile: string | undefined;
+					if (task.currentAttemptId) try { scopedReportFile = attemptReportPath(entry.directory, task.currentAttemptId); } catch (error) { result.cleanupErrors.push(`Invalid current attempt for Subagent task ${task.id}: ${error instanceof Error ? error.message : String(error)}`); }
+					const reportFile = task.currentAttemptId ? scopedReportFile : canonicalReportFile;
+					if (reportFile && existsSync(reportFile) && (task.status === "running" || task.status === "starting")) {
+						try {
+							const submitted = await readReport(reportFile);
+							const report = submitted;
+							if (task.currentAttemptId && report.attemptId !== task.currentAttemptId) throw new Error(`Report attempt '${report.attemptId ?? "unknown"}' does not match current attempt '${task.currentAttemptId}'.`);
+							applyReport(task, report, report.reportedAt);
+							if (report !== submitted) await writeJsonAtomic(reportFile, report);
+							await writeJsonAtomic(canonicalReportFile, report);
+							result.settledTasks += 1;
+						} catch (error) {
+							const detail = error instanceof Error ? error.message : String(error);
+							result.cleanupErrors.push(`Invalid Subagent report ${reportFile}: ${detail}`);
+							await persistFailureReport(canonicalReportFile, { status: "failed", summary: "Recovered task had an invalid structured report.", documents: [], error: detail }, false);
+							applyTaskStatus(task, "failed", { error: `Invalid structured report: ${detail}` }); result.interruptedTasks += 1; result.settledTasks += 1;
 						}
+						if (differentOwner && task.status === "blocked") {
+							const cancelledReport = { status: "failed" as const, summary: "Blocked task was cancelled because its parent Pi session is no longer active.", documents: [], error: "Owning parent Pi session is no longer active.", ...(task.currentAttemptId ? { attemptId: task.currentAttemptId } : {}) };
+							await writeJsonAtomic(canonicalReportFile, cancelledReport);
+							if (scopedReportFile) await writeJsonAtomic(scopedReportFile, cancelledReport);
+							applyTaskStatus(task, "cancelled", { error: cancelledReport.error }); result.cancelledTasks += 1; result.interruptedTasks += 1;
+						}
+					} else if (differentOwner) {
+						applyTaskStatus(task, "cancelled", { error: "Owning parent Pi session is no longer active." }); result.cancelledTasks += 1; result.interruptedTasks += 1;
+					} else if (task.status === "running" || task.status === "starting") {
+						let live = false;
+						try { live = task.paneId ? await herdr.isTaskRunning(task.paneId) : false; } catch (error) { result.cleanupErrors.push(`Could not inspect Subagent pane ${task.paneId}: ${error instanceof Error ? error.message : String(error)}`); live = true; }
+						if (live) result.liveTasks += 1;
+						else { applyTaskStatus(task, "cancelled", { error: "Child pane disappeared before a structured report was recorded." }); result.cancelledTasks += 1; result.interruptedTasks += 1; }
 					}
-					if (childIsLive) result.liveTasks += 1;
-					else {
-						applyTaskStatus(task, "cancelled", { error: "Child pane disappeared before a structured report was recorded." });
-						result.cancelledTasks += 1;
-						result.interruptedTasks += 1;
-					}
+					await writeJsonAtomic(join(entry.directory, "task.json"), task);
 				}
-				await writeJsonAtomic(taskFile, task);
-			}
-			statuses.push(task.status);
-		}
-		if (unreadableTasks > 0) {
-			const message = `Could not reconcile ${unreadableTasks} unreadable task record${unreadableTasks === 1 ? "" : "s"}.`;
-			applyRunStatus(run, "failed", { error: message });
-			await writeJsonAtomic(runFile, run);
-			await closeRunTab(run, runFile, herdr, result.cleanupErrors);
-			result.interruptedTasks += unreadableTasks;
-			continue;
-		}
-		if (!statuses.some((status) => status === "running" || status === "starting")) {
-			applyRunStatus(run, aggregateTaskStatus(statuses));
-			await writeJsonAtomic(runFile, run);
-			if (differentOwner || run.status === "cancelled") await closeRunTab(run, runFile, herdr, result.cleanupErrors);
+				const refreshed = await readTaskEntries(runDirectory);
+				applyRunStatus(run, run.resume ? aggregateTasksWithResume(refreshed.map(({ task }) => task), run.resume.active) : aggregateTaskStatus(refreshed.map(({ task }) => task.status)));
+				claim = claimResumeCleanup(run);
+				closeRegular = !run.resume && !isActiveStatus(run.status) && (differentOwner || result.interruptedTasks > 0);
+				return run;
+			});
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			result.cleanupErrors.push(`Could not inspect Subagent task in ${tasksDirectory}: ${detail}`);
+			result.interruptedTasks += 1;
+			latest = await withRunStateLock(runFile, undefined, (run) => applyRunStatus(run, "failed", { error: detail }));
+			closeRegular = true;
 		}
+		if (claim) await closeRunTab(latest, runFile, herdr, result.cleanupErrors, claim);
+		else if (closeRegular) await closeRunTab(latest, runFile, herdr, result.cleanupErrors);
 	}
 	return result;
 }

package/packages/herdr-subagents/src/records.ts

@@ -4,6 +4,7 @@ import { writeJsonAtomic } from "./state.ts";
 
 export type TaskStatus = "starting" | "queued" | "running" | "blocked" | "completed" | "failed" | "cancelled";
 export type RunStatus = TaskStatus | "partial";
+export type TaskRuntimeState = "working" | "waiting_interaction" | "retrying" | "delivery_unknown";
 export const ACTIVE_STATUSES = new Set<RunStatus>(["starting", "queued", "running", "blocked"]);
 const SETTLED_RUN_STATUSES = new Set<RunStatus>(["completed", "partial", "failed", "cancelled"]);
 
@@ -16,17 +17,34 @@ export interface PersistedDocument {
 }
 
 export interface PersistedReport {
-	status: "completed" | "needs-input" | "failed";
+	status: "completed" | "blocked" | "failed";
 	summary: string;
 	documents: PersistedDocument[];
 	attemptId?: string;
 	error?: string;
 	question?: string;
-	failureKind?: "missing_input";
-	requiredInput?: string;
 	reportedAt?: string;
 }
 
+export interface ResumeMember {
+	paneId: string;
+	generation: number;
+	agentName: string;
+	attemptId: string;
+	ownerSessionId?: string;
+	ownerProcessId?: number;
+	ownerToken: string;
+	phase: "allocating" | "running" | "blocked";
+}
+
+export interface ResumeState {
+	generation: number;
+	phase: "active" | "closing";
+	tabId: string;
+	paneIds: string[];
+	active: Record<string, ResumeMember>;
+}
+
 export interface RunRecord {
 	id: string;
 	label: string;
@@ -47,10 +65,9 @@ export interface RunRecord {
 	staleTabIds?: string[];
 	question?: string;
 	error?: string;
-	failureKind?: "missing_input";
-	requiredInput?: string;
 	cleanupError?: string;
 	cleanupPendingTabIds?: string[];
+	resume?: ResumeState;
 }
 
 export interface TaskRecord {
@@ -80,6 +97,9 @@ export interface TaskRecord {
 	attempt?: number;
 	currentTurnFile?: string;
 	currentAttemptId?: string;
+	runtimeState?: TaskRuntimeState;
+	runtimeDiagnostic?: string;
+	runtimeUpdatedAt?: string;
 	question?: string;
 	error?: string;
 }
@@ -97,6 +117,9 @@ export interface TaskActivity {
 	elapsedMs?: number;
 	completedAt?: string;
 	updatedAt?: string;
+	runtimeState?: TaskRuntimeState;
+	runtimeDiagnostic?: string;
+	runtimeUpdatedAt?: string;
 }
 
 export function projectTaskActivity(task: TaskRecord, index = task.order - 1): TaskActivity {
@@ -113,6 +136,9 @@ export function projectTaskActivity(task: TaskRecord, index = task.order - 1): T
 		...(typeof task.elapsedMs === "number" ? { elapsedMs: task.elapsedMs } : {}),
 		...(task.completedAt ? { completedAt: task.completedAt } : {}),
 		...(task.updatedAt ? { updatedAt: task.updatedAt } : {}),
+		...(task.runtimeState ? { runtimeState: task.runtimeState } : {}),
+		...(task.runtimeDiagnostic ? { runtimeDiagnostic: task.runtimeDiagnostic } : {}),
+		...(task.runtimeUpdatedAt ? { runtimeUpdatedAt: task.runtimeUpdatedAt } : {}),
 	};
 }
 
@@ -172,20 +198,16 @@ export async function readTurnRecord(path: string): Promise<TurnRecord> {
 export function parseReport(value: unknown, source = "structured report"): PersistedReport {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Expected a JSON object in ${source}.`);
 	const report = value as Record<string, unknown>;
-	if (report.status !== "completed" && report.status !== "needs-input" && report.status !== "failed") throw new Error(`Invalid report status in ${source}.`);
+	if (report.status !== "completed" && report.status !== "blocked" && report.status !== "failed") throw new Error(`Invalid report status in ${source}.`);
 	if (typeof report.summary !== "string" || !report.summary.trim()) throw new Error(`Missing report summary in ${source}.`);
 	if (!Array.isArray(report.documents) || !report.documents.every((document) => {
 		if (!document || typeof document !== "object" || Array.isArray(document)) return false;
 		const entry = document as Record<string, unknown>;
 		return typeof entry.path === "string" && typeof entry.description === "string";
 	})) throw new Error(`Invalid report documents in ${source}.`);
-	if (report.status === "needs-input" && (typeof report.question !== "string" || !report.question.trim())) throw new Error(`Missing report question in ${source}.`);
+	if (report.status === "blocked" && (typeof report.question !== "string" || !report.question.trim())) throw new Error(`Missing report question in ${source}.`);
 	if (report.error !== undefined && typeof report.error !== "string") throw new Error(`Invalid report error in ${source}.`);
 	if (report.question !== undefined && typeof report.question !== "string") throw new Error(`Invalid report question in ${source}.`);
-	if (report.failureKind !== undefined && report.failureKind !== "missing_input") throw new Error(`Invalid report failureKind in ${source}.`);
-	if (report.requiredInput !== undefined && (typeof report.requiredInput !== "string" || !report.requiredInput.trim())) throw new Error(`Invalid report requiredInput in ${source}.`);
-	if (report.failureKind === "missing_input" && report.status !== "failed") throw new Error(`missing_input must be a failed report in ${source}.`);
-	if (report.failureKind === "missing_input" && (typeof report.requiredInput !== "string" || !report.requiredInput.trim())) throw new Error(`Missing report requiredInput in ${source}.`);
 	if (report.attemptId !== undefined && (typeof report.attemptId !== "string" || !report.attemptId.trim())) throw new Error(`Invalid report attemptId in ${source}.`);
 	return report as unknown as PersistedReport;
 }
@@ -194,18 +216,6 @@ export async function readReport(path: string): Promise<PersistedReport> {
 	return parseReport(await readObject(path), path);
 }
 
-export function normalizeNeedsInputReport(report: PersistedReport, effectiveConcurrency: number): PersistedReport {
-	if (report.status !== "needs-input" || effectiveConcurrency <= 1) return report;
-	return parseReport({
-		...report,
-		status: "failed",
-		error: `Missing required input: ${report.question}`,
-		failureKind: "missing_input",
-		requiredInput: report.question,
-		question: undefined,
-	}, "normalized concurrent input request");
-}
-
 export async function persistFailureReport(path: string, report: PersistedReport, replaceExisting = false): Promise<string | undefined> {
 	if (replaceExisting) {
 		await writeJsonAtomic(path, parseReport(report, "generated failure report"));
@@ -270,6 +280,7 @@ export async function settleAttemptFailure<T extends TaskRecord | TurnRecord>(
 	const status = options.cancelled ? "cancelled" : "failed";
 	const at = options.at ?? new Date().toISOString();
 	applyTaskStatus(record, status, { error: options.error, at });
+	if ("order" in record) clearTaskRuntime(record);
 	const report: PersistedReport = {
 		status: "failed",
 		summary: options.summary ?? `${options.name} ${options.cancelled ? "was cancelled" : "failed"}.`,
@@ -281,14 +292,21 @@ export async function settleAttemptFailure<T extends TaskRecord | TurnRecord>(
 	return { status, report };
 }
 
+export function clearTaskRuntime(record: TaskRecord): void {
+	delete record.runtimeState;
+	delete record.runtimeDiagnostic;
+	delete record.runtimeUpdatedAt;
+}
+
+export function applyTaskRuntime(record: TaskRecord, state: TaskRuntimeState, diagnostic?: string, at = new Date().toISOString()): void {
+	record.runtimeState = state;
+	record.runtimeUpdatedAt = at;
+	if (diagnostic) record.runtimeDiagnostic = diagnostic;
+	else delete record.runtimeDiagnostic;
+}
+
 export function applyReport(record: TaskRecord | TurnRecord, report: PersistedReport, completedAt = new Date().toISOString()): "blocked" | "completed" | "failed" {
-	const status = report.status === "needs-input" ? "blocked" : report.status;
-	applyTaskStatus(record, status, { at: completedAt, question: report.question, error: report.error });
-	if ("order" in record) {
-		if (report.failureKind) record.failureKind = report.failureKind;
-		else delete record.failureKind;
-		if (report.requiredInput) record.requiredInput = report.requiredInput;
-		else delete record.requiredInput;
-	}
-	return status;
+	applyTaskStatus(record, report.status, { at: completedAt, question: report.question, error: report.error });
+	if ("order" in record) clearTaskRuntime(record);
+	return report.status;
 }

package/packages/herdr-subagents/src/resume-state.ts

@@ -0,0 +1,46 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { isProcessAlive, type OwnerIdentity } from "./ownership.ts";
+import { aggregateTaskStatus, type AggregateRunStatus } from "./run-status.ts";
+import type { ResumeMember, RunRecord, TaskRecord, TaskStatus } from "./records.ts";
+import { readTaskRecord } from "./records.ts";
+
+export interface TaskEntry { directory: string; task: TaskRecord }
+export interface ResumeCleanupClaim { tabId: string; generation: number }
+
+export async function readTaskEntries(runDirectory: string): Promise<TaskEntry[]> {
+	return Promise.all(readdirSync(join(runDirectory, "tasks")).sort().map(async (entry) => {
+		const directory = join(runDirectory, "tasks", entry);
+		return { directory, task: await readTaskRecord(join(directory, "task.json")) };
+	}));
+}
+
+export function memberCoversTask(member: ResumeMember | undefined, task: TaskRecord): boolean {
+	if (!member) return false;
+	if (member.phase === "allocating") return true;
+	return member.attemptId === task.currentAttemptId && member.phase === "running";
+}
+
+export function aggregateTasksWithResume(tasks: readonly TaskRecord[], active: Record<string, ResumeMember> = {}): AggregateRunStatus {
+	return aggregateTaskStatus(tasks.map((task): TaskStatus => memberCoversTask(active[task.id], task) ? "running" : task.status));
+}
+
+export function memberOwnedBy(member: ResumeMember, owner?: OwnerIdentity): boolean {
+	if (!owner) return true;
+	if (owner.sessionId !== undefined && member.ownerSessionId !== owner.sessionId) return false;
+	if (owner.processId !== undefined && member.ownerProcessId !== owner.processId) return false;
+	return true;
+}
+
+export function memberOwnerIsStale(member: ResumeMember, currentOwner?: OwnerIdentity): boolean {
+	if (currentOwner && memberOwnedBy(member, currentOwner)) return false;
+	if (currentOwner?.sessionId && member.ownerSessionId && currentOwner.sessionId !== member.ownerSessionId && member.ownerProcessId === currentOwner.processId) return true;
+	return !isProcessAlive(member.ownerProcessId);
+}
+
+export function claimResumeCleanup(run: RunRecord): ResumeCleanupClaim | undefined {
+	if (!run.resume || run.resume.phase !== "active" || Object.keys(run.resume.active).length > 0) return undefined;
+	run.resume.phase = "closing";
+	run.cleanupPendingTabIds = [...new Set([...(run.cleanupPendingTabIds ?? []), run.resume.tabId])];
+	return { tabId: run.resume.tabId, generation: run.resume.generation };
+}