@maxiaochao/pi-toolkit 0.10.20 → 0.10.22

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, 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,108 +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)) {
-				let recoveredCurrentReport = false;
-				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 report = await readReport(reportFile);
-						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());
-						recoveredCurrentReport = reportFile !== canonicalReportFile;
-						if (reportFile !== canonicalReportFile) 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 (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;
 					}
+					delete run.resume.active[taskId];
 				}
-				if (differentOwner && isActiveStatus(task.status) && !(recoveredCurrentReport && task.status === "blocked")) {
-					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;
+				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,7 +17,7 @@ export interface PersistedDocument {
 }
 
 export interface PersistedReport {
-	status: "completed" | "needs-input" | "failed";
+	status: "completed" | "blocked" | "failed";
 	summary: string;
 	documents: PersistedDocument[];
 	attemptId?: string;
@@ -25,6 +26,25 @@ export interface PersistedReport {
 	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,6 +67,7 @@ export interface RunRecord {
 	error?: string;
 	cleanupError?: string;
 	cleanupPendingTabIds?: string[];
+	resume?: ResumeState;
 }
 
 export interface TaskRecord {
@@ -76,6 +97,9 @@ export interface TaskRecord {
 	attempt?: number;
 	currentTurnFile?: string;
 	currentAttemptId?: string;
+	runtimeState?: TaskRuntimeState;
+	runtimeDiagnostic?: string;
+	runtimeUpdatedAt?: string;
 	question?: string;
 	error?: string;
 }
@@ -93,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 {
@@ -109,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 } : {}),
 	};
 }
 
@@ -168,14 +198,14 @@ 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.attemptId !== undefined && (typeof report.attemptId !== "string" || !report.attemptId.trim())) throw new Error(`Invalid report attemptId in ${source}.`);
@@ -250,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"}.`,
@@ -261,8 +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 });
-	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 };
+}

package/packages/herdr-subagents/src/run-locator.ts

@@ -1,19 +1,34 @@
 import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { readRunRecord } from "./records.ts";
 
 export async function findRunDirectory(runsDirectory: string, runId: string): Promise<string | undefined> {
 	if (!existsSync(runsDirectory)) return undefined;
+	const reference = basename(runId.trim());
 	const errors: string[] = [];
+	const matches: Array<{ id: string; directory: string }> = [];
 	for (const entry of readdirSync(runsDirectory)) {
 		const directory = join(runsDirectory, entry);
 		const runFile = join(directory, "run.json");
 		try {
-			if ((await readRunRecord(runFile)).id === runId) return directory;
+			const id = (await readRunRecord(runFile)).id;
+			if (id === reference || entry === reference) return directory;
+			if (id.startsWith(reference) || entry.endsWith(`-${reference}`)) matches.push({ id, directory });
 		} catch (error) {
 			errors.push(`${runFile}: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
+	if (matches.length === 1) return matches[0].directory;
+	if (matches.length > 1) throw new Error(`Ambiguous Subagent run reference '${runId}': ${matches.map((match) => match.id).join(", ")}.`);
 	if (errors.length) throw new Error(`Could not inspect Subagent runs while looking for '${runId}': ${errors.join("; ")}`);
 	return undefined;
 }
+
+export function resolveRunIdReference(reference: string, candidates: readonly string[]): string | undefined {
+	const trimmed = basename(reference.trim());
+	const exact = candidates.find((candidate) => candidate === trimmed);
+	if (exact) return exact;
+	const matches = [...new Set(candidates.filter((candidate) => candidate.startsWith(trimmed)))];
+	if (matches.length > 1) throw new Error(`Ambiguous Subagent run reference '${reference}': ${matches.join(", ")}.`);
+	return matches[0];
+}

package/packages/herdr-subagents/src/run-pane-allocator.ts

@@ -1,5 +1,5 @@
 import type { HerdrAutomation } from "./herdr.ts";
-import { writeJsonAtomic } from "./state.ts";
+import { withRunStateLock } from "./run-state.ts";
 import type { RunRecord } from "./records.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
@@ -33,45 +33,47 @@ export class RunPaneAllocator {
 		this.allocation = this.allocation.then(async () => {
 			const { herdr, run, runFile, signal } = this.options;
 			const env = childEnvironment(taskDirectory);
-			let anchorExists = Boolean(run.tabId && this.lastPaneId);
-			if (anchorExists && this.options.validateExistingPane) {
-				const survivingPaneIds: string[] = [];
-				for (const existingPaneId of this.paneIds) {
-					if (await herdr.paneExists(existingPaneId, signal)) survivingPaneIds.push(existingPaneId);
+			const allocated = await withRunStateLock(runFile, signal, async (latest) => {
+				const currentPaneIds = [...(latest.paneIds ?? [])];
+				let lastPaneId = currentPaneIds.at(-1);
+				let anchorExists = Boolean(latest.tabId && lastPaneId);
+				if (anchorExists && this.options.validateExistingPane) {
+					const surviving: string[] = [];
+					for (const existingPaneId of currentPaneIds) if (await herdr.paneExists(existingPaneId, signal)) surviving.push(existingPaneId);
+					currentPaneIds.splice(0, currentPaneIds.length, ...surviving);
+					lastPaneId = currentPaneIds.at(-1);
+					anchorExists = Boolean(lastPaneId);
 				}
-				this.paneIds.splice(0, this.paneIds.length, ...survivingPaneIds);
-				this.lastPaneId = this.paneIds.at(-1);
-				anchorExists = Boolean(this.lastPaneId);
-			}
-			if (!anchorExists) {
-				const staleTabId = run.tabId;
-				const tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd: run.cwd, label: `SA · ${run.label}`, env, focus: false, signal });
-				run.tabId = tab.tabId;
-				paneId = tab.paneId;
-				this.paneIds.splice(0);
-				if (staleTabId && staleTabId !== tab.tabId) {
-					run.staleTabIds = [...new Set([...(run.staleTabIds ?? []), staleTabId])];
-					await writeJsonAtomic(runFile, run);
-					await cleanupRunTab({
-						herdr, tabId: staleTabId, runFile, runRecord: run, signal, onError: this.options.onCleanupError,
-						errorPrefix: `Could not close stale Herdr tab ${staleTabId}`,
-							onClosed: (latest) => {
-							latest.staleTabIds = latest.staleTabIds?.filter((id) => id !== staleTabId);
-							if (!latest.staleTabIds?.length) delete latest.staleTabIds;
-						},
-					}).catch((error) => {
-						if (!this.options.onCleanupError) throw error;
-					});
+				let staleTabId: string | undefined;
+				if (!anchorExists) {
+					staleTabId = latest.tabId;
+					const tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd: latest.cwd, label: `SA · ${latest.label}`, env, focus: false, signal });
+					latest.tabId = tab.tabId;
+					paneId = tab.paneId;
+					currentPaneIds.splice(0);
+					if (staleTabId && staleTabId !== tab.tabId) latest.staleTabIds = [...new Set([...(latest.staleTabIds ?? []), staleTabId])];
+				} else {
+					paneId = (await herdr.splitPane({ paneId: lastPaneId as string, cwd: latest.cwd, direction: currentPaneIds.length % 2 ? "right" : "down", focus: false, env, signal })).paneId;
 				}
-			} else {
-				const split = await herdr.splitPane({ paneId: this.lastPaneId as string, cwd: run.cwd, direction: this.paneIds.length % 2 ? "right" : "down", focus: false, env, signal });
-				paneId = split.paneId;
+				currentPaneIds.push(paneId);
+				applyRunStatus(latest, "running");
+				latest.paneIds = currentPaneIds;
+				return { latest, staleTabId: staleTabId && staleTabId !== latest.tabId ? staleTabId : undefined };
+			});
+			this.paneIds.splice(0, this.paneIds.length, ...(allocated.latest.paneIds ?? []));
+			this.lastPaneId = this.paneIds.at(-1);
+			Object.assign(run, allocated.latest);
+			if (allocated.staleTabId) {
+				const staleTabId = allocated.staleTabId;
+				await cleanupRunTab({
+					herdr, tabId: staleTabId, runFile, runRecord: run, signal, onError: this.options.onCleanupError,
+					errorPrefix: `Could not close stale Herdr tab ${staleTabId}`,
+					onClosed: (latest) => {
+						latest.staleTabIds = latest.staleTabIds?.filter((id) => id !== staleTabId);
+						if (!latest.staleTabIds?.length) delete latest.staleTabIds;
+					},
+				}).catch((error) => { if (!this.options.onCleanupError) throw error; });
 			}
-			this.lastPaneId = paneId;
-			this.paneIds.push(paneId);
-			applyRunStatus(run, "running");
-			run.paneIds = [...this.paneIds];
-			await writeJsonAtomic(runFile, run);
 		});
 		await this.allocation;
 		return paneId;