@maxiaochao/pi-toolkit 0.9.6 → 0.10.0

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

@@ -0,0 +1,167 @@
+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 { cleanupRunTab } from "./tab-cleanup.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;
+	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}` });
+	} catch (error) {
+		if (cleanupErrors.length === errorsBeforeCleanup) cleanupErrors.push(`Could not close Subagent tab ${run.tabId}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export interface CancelActiveRunsOptions { reason?: string; owner?: OwnerIdentity; }
+
+export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomation, options: CancelActiveRunsOptions = {}): Promise<CancellationResult> {
+	const reason = options.reason ?? "Parent Pi session closed.";
+	const result: CancellationResult = { cancelledRuns: 0, cleanupErrors: [] };
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	if (!existsSync(runsDirectory)) return result;
+	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 (!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);
+		result.cancelledRuns += 1;
+	}
+	return result;
+}
+
+export async function reconcileSubagentRuns(cwd: string, herdr: HerdrAutomation, owner?: OwnerIdentity): Promise<ReconciliationResult> {
+	const result: ReconciliationResult = { liveTasks: 0, settledTasks: 0, interruptedTasks: 0, cancelledTasks: 0, cleanupErrors: [] };
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	if (!existsSync(runsDirectory)) return result;
+	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)}`);
+			}
+		}
+		if (!isActiveStatus(run.status)) continue;
+		const tasksDirectory = join(runDirectory, "tasks");
+		if (!existsSync(tasksDirectory)) {
+			const message = `Active Subagent run ${run.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);
+			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 reportFile = join(tasksDirectory, taskEntry, "report.json");
+				if (existsSync(reportFile) && (task.status === "running" || task.status === "starting")) {
+					try {
+						const report = await readReport(reportFile);
+						applyReport(task, report, report.reportedAt ?? new Date().toISOString());
+						result.settledTasks += 1;
+					} catch (error) {
+						const detail = error instanceof Error ? error.message : String(error);
+						result.cleanupErrors.push(`Invalid Subagent report ${reportFile}: ${detail}`);
+						await persistFailureReport(reportFile, { status: "failed", summary: "Recovered task had an invalid structured report.", documents: [], error: detail, reportedAt: new Date().toISOString() });
+						if (!differentOwner) {
+							applyTaskStatus(task, "failed", { error: `Invalid structured report: ${detail}` });
+							result.settledTasks += 1;
+							result.interruptedTasks += 1;
+						}
+					}
+				}
+				if (differentOwner && isActiveStatus(task.status)) {
+					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;
+						}
+					}
+					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(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 (differentOwner || !statuses.some((status) => status === "running" || status === "starting")) {
+			applyRunStatus(run, differentOwner ? "cancelled" : aggregateTaskStatus(statuses), { error: differentOwner ? "Owning parent Pi session is no longer active." : undefined });
+			await writeJsonAtomic(runFile, run);
+			if (differentOwner || run.status === "cancelled") await closeRunTab(run, runFile, herdr, result.cleanupErrors);
+		}
+	}
+	return result;
+}

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

@@ -0,0 +1,213 @@
+import { existsSync } from "node:fs";
+import { readFile, rename } from "node:fs/promises";
+import { writeJsonAtomic } from "./state.ts";
+
+export type TaskStatus = "starting" | "queued" | "running" | "blocked" | "completed" | "failed" | "cancelled";
+export type RunStatus = TaskStatus | "partial";
+export const ACTIVE_STATUSES = new Set<RunStatus>(["starting", "queued", "running", "blocked"]);
+const SETTLED_RUN_STATUSES = new Set<RunStatus>(["completed", "partial", "failed", "cancelled"]);
+
+export function isActiveStatus(status: RunStatus): boolean { return ACTIVE_STATUSES.has(status); }
+export function isSettledRunStatus(status: unknown): status is Exclude<RunStatus, "starting" | "queued" | "running" | "blocked"> { return SETTLED_RUN_STATUSES.has(status as RunStatus); }
+
+export interface PersistedDocument {
+	path: string;
+	description: string;
+}
+
+export interface PersistedReport {
+	status: "completed" | "needs-input" | "failed";
+	summary: string;
+	documents: PersistedDocument[];
+	error?: string;
+	question?: string;
+	reportedAt?: string;
+}
+
+export interface RunRecord {
+	id: string;
+	label: string;
+	status: RunStatus;
+	cwd?: string;
+	ownerSessionId?: string;
+	ownerProcessId?: number;
+	requestedConcurrency?: number;
+	effectiveConcurrency?: number;
+	stalledWarningSeconds?: number;
+	taskIds?: string[];
+	paneIds?: string[];
+	startedAt?: string;
+	updatedAt?: string;
+	completedAt?: string;
+	tabId?: string;
+	paneId?: string;
+	staleTabIds?: string[];
+	question?: string;
+	error?: string;
+	cleanupError?: string;
+	cleanupPendingTabIds?: string[];
+}
+
+export interface TaskRecord {
+	id: string;
+	runId: string;
+	order: number;
+	name?: string;
+	status: TaskStatus;
+	prompt?: string;
+	agent?: string;
+	access?: "read" | "write";
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills?: string[];
+	systemPrompt?: string;
+	sessionFile?: string;
+	startedAt?: string;
+	updatedAt?: string;
+	completedAt?: string;
+	tabId?: string;
+	paneId?: string;
+	paneLabel?: string;
+	agentName?: string;
+	attempt?: number;
+	currentTurnFile?: string;
+	question?: string;
+	error?: string;
+}
+
+export interface TurnRecord {
+	attempt: number;
+	prompt?: string;
+	status: TaskStatus;
+	summary?: string;
+	documents?: PersistedDocument[];
+	sessionFile?: string;
+	startedAt?: string;
+	completedAt?: string;
+	tabId?: string;
+	paneId?: string;
+	agentName?: string;
+	question?: string;
+	error?: string;
+	events?: Array<Record<string, unknown>>;
+}
+
+async function readObject(path: string): Promise<Record<string, unknown>> {
+	const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Expected a JSON object in ${path}.`);
+	return parsed as Record<string, unknown>;
+}
+
+const TASK_STATUSES = new Set<TaskStatus>(["starting", "queued", "running", "blocked", "completed", "failed", "cancelled"]);
+const RUN_STATUSES = new Set<RunStatus>([...TASK_STATUSES, "partial"]);
+function requireString(record: Record<string, unknown>, field: string, path: string): void {
+	if (typeof record[field] !== "string" || !(record[field] as string).trim()) throw new Error(`Missing ${field} in ${path}.`);
+}
+
+export async function readRunRecord(path: string): Promise<RunRecord> {
+	const record = await readObject(path);
+	requireString(record, "id", path);
+	requireString(record, "label", path);
+	if (!RUN_STATUSES.has(record.status as RunStatus)) throw new Error(`Invalid run status in ${path}.`);
+	return record as unknown as RunRecord;
+}
+
+export async function readTaskRecord(path: string): Promise<TaskRecord> {
+	const record = await readObject(path);
+	requireString(record, "id", path);
+	requireString(record, "runId", path);
+	if (!Number.isInteger(record.order) || Number(record.order) < 1) throw new Error(`Invalid task order in ${path}.`);
+	if (!TASK_STATUSES.has(record.status as TaskStatus)) throw new Error(`Invalid task status in ${path}.`);
+	return record as unknown as TaskRecord;
+}
+
+export async function readTurnRecord(path: string): Promise<TurnRecord> {
+	const record = await readObject(path);
+	if (!Number.isInteger(record.attempt) || Number(record.attempt) < 1) throw new Error(`Invalid turn attempt in ${path}.`);
+	if (!TASK_STATUSES.has(record.status as TaskStatus)) throw new Error(`Invalid turn status in ${path}.`);
+	return record as unknown as 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 (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.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}.`);
+	return report as unknown as PersistedReport;
+}
+
+export async function readReport(path: string): Promise<PersistedReport> {
+	return parseReport(await readObject(path), path);
+}
+
+export async function persistFailureReport(path: string, report: PersistedReport, replaceExisting = false): Promise<string | undefined> {
+	if (replaceExisting) {
+		await writeJsonAtomic(path, parseReport(report, "generated failure report"));
+		return undefined;
+	}
+	let archivedPath: string | undefined;
+	if (existsSync(path)) {
+		try { await readReport(path); return undefined; }
+		catch {
+			archivedPath = `${path}.invalid-${Date.now()}`;
+			await rename(path, archivedPath);
+		}
+	}
+	await writeJsonAtomic(path, parseReport(report, "generated failure report"));
+	return archivedPath;
+}
+
+export function applyLifecycleStatus<T extends { status: string; question?: string; error?: string; updatedAt?: string; completedAt?: string }>(
+	record: T,
+	status: RunStatus,
+	options: { question?: string; error?: string; at?: string } = {},
+): T {
+	const at = options.at ?? new Date().toISOString();
+	delete record.question;
+	delete record.error;
+	delete record.updatedAt;
+	delete record.completedAt;
+	Object.assign(record, { status });
+	if (status === "blocked") Object.assign(record, { updatedAt: at, ...(options.question ? { question: options.question } : {}) });
+	else if (isActiveStatus(status)) Object.assign(record, { updatedAt: at });
+	else Object.assign(record, { completedAt: at, ...(options.error ? { error: options.error } : {}) });
+	return record;
+}
+
+export function applyTaskStatus<T extends TaskRecord | TurnRecord>(record: T, status: TaskStatus, options: { question?: string; error?: string; at?: string } = {}): T {
+	return applyLifecycleStatus(record, status, options);
+}
+
+export async function settleAttemptFailure<T extends TaskRecord | TurnRecord>(
+	record: T,
+	reportPath: string,
+	options: { cancelled: boolean; error: string; name: string; summary?: string; at?: string; replaceReport?: boolean },
+): Promise<{ status: "cancelled" | "failed"; report: PersistedReport }> {
+	const status = options.cancelled ? "cancelled" : "failed";
+	const at = options.at ?? new Date().toISOString();
+	applyTaskStatus(record, status, { error: options.error, at });
+	const report: PersistedReport = {
+		status: "failed",
+		summary: options.summary ?? `${options.name} ${options.cancelled ? "was cancelled" : "failed"}.`,
+		documents: [],
+		error: options.error,
+		reportedAt: at,
+	};
+	await persistFailureReport(reportPath, report, options.replaceReport);
+	return { status, report };
+}
+
+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;
+}

package/packages/herdr-subagents/src/result-path.ts

@@ -0,0 +1,7 @@
+import { resolve } from "node:path";
+
+export function resultPathForAttempt(taskDirectory: string, attempt: number): string {
+	return attempt > 1
+		? resolve(taskDirectory, "turns", `${String(attempt).padStart(2, "0")}-result.md`)
+		: resolve(taskDirectory, "result.md");
+}

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

@@ -0,0 +1,19 @@
+import { existsSync, readdirSync } from "node:fs";
+import { 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 errors: 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;
+		} catch (error) {
+			errors.push(`${runFile}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	if (errors.length) throw new Error(`Could not inspect Subagent runs while looking for '${runId}': ${errors.join("; ")}`);
+	return undefined;
+}

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

@@ -0,0 +1,78 @@
+import type { HerdrAutomation } from "./herdr.ts";
+import { writeJsonAtomic } from "./state.ts";
+import type { RunRecord } from "./records.ts";
+import { applyRunStatus } from "./run-status.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+
+interface RunPaneAllocatorOptions {
+	herdr: HerdrAutomation;
+	run: RunRecord;
+	runFile: string;
+	signal?: AbortSignal;
+	validateExistingPane?: boolean;
+	onCleanupError?: (message: string) => void;
+}
+
+export class RunPaneAllocator {
+	private allocation = Promise.resolve();
+	private readonly paneIds: string[];
+	private lastPaneId?: string;
+	private readonly options: RunPaneAllocatorOptions;
+
+	constructor(options: RunPaneAllocatorOptions) {
+		this.options = options;
+		this.paneIds = Array.isArray(options.run.paneIds) ? [...options.run.paneIds] : [];
+		this.lastPaneId = this.paneIds.at(-1);
+	}
+
+	get tabId(): string | undefined { return this.options.run.tabId; }
+
+	async allocate(taskDirectory: string): Promise<string> {
+		let paneId = "";
+		this.allocation = this.allocation.then(async () => {
+			const { herdr, run, runFile, signal } = this.options;
+			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: 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);
+				}
+				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;
+					});
+				}
+			} 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;
+			}
+			this.lastPaneId = paneId;
+			this.paneIds.push(paneId);
+			applyRunStatus(run, "running");
+			run.paneIds = [...this.paneIds];
+			await writeJsonAtomic(runFile, run);
+		});
+		await this.allocation;
+		return paneId;
+	}
+}

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

@@ -0,0 +1,23 @@
+import { applyLifecycleStatus, type RunStatus, type TaskStatus } from "./records.ts";
+
+export type AggregateRunStatus = Exclude<RunStatus, "starting" | "queued">;
+export type PersistedRunStatus = RunStatus;
+
+export function aggregateTaskStatus(statuses: readonly TaskStatus[]): AggregateRunStatus {
+	if (statuses.length === 0) return "failed";
+	if (statuses.some((status) => status === "running" || status === "starting")) return "running";
+	if (statuses.some((status) => status === "blocked" || status === "queued")) return "blocked";
+	const completed = statuses.some((status) => status === "completed");
+	if (statuses.some((status) => status === "cancelled")) return completed ? "partial" : "cancelled";
+	if (statuses.some((status) => status === "failed")) return completed ? "partial" : "failed";
+	if (statuses.every((status) => status === "completed")) return "completed";
+	throw new Error(`Cannot aggregate unknown task status: ${statuses.join(", ")}`);
+}
+
+export function applyRunStatus<T extends { status: string; question?: string; error?: string; updatedAt?: string; completedAt?: string }>(
+	run: T,
+	status: PersistedRunStatus,
+	options: { question?: string; error?: string; at?: string } = {},
+): T {
+	return applyLifecycleStatus(run, status, options);
+}