@maxiaochao/pi-toolkit 0.9.4 → 0.10.0

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

@@ -0,0 +1,224 @@
+import { spawn } from "node:child_process";
+
+export interface CreateTabRequest {
+	workspaceId: string;
+	cwd: string;
+	label: string;
+	env: Record<string, string>;
+	focus: boolean;
+	signal?: AbortSignal;
+}
+
+export interface StartAgentRequest {
+	name: string;
+	kind: "pi";
+	paneId: string;
+	args: string[];
+	signal?: AbortSignal;
+}
+
+export interface PromptAgentRequest {
+	target: string;
+	prompt: string;
+	signal?: AbortSignal;
+}
+
+export interface SplitPaneRequest {
+	paneId: string;
+	cwd: string;
+	direction: "right" | "down";
+	focus: boolean;
+	env?: Record<string, string>;
+	signal?: AbortSignal;
+}
+
+export interface HerdrAutomation {
+	createTab(request: CreateTabRequest): Promise<{ tabId: string; paneId: string }>;
+	startAgent(request: StartAgentRequest): Promise<void>;
+	promptAgent(request: PromptAgentRequest): Promise<{ status?: string }>;
+	splitPane(request: SplitPaneRequest): Promise<{ paneId: string }>;
+	renamePane(paneId: string, label: string, signal?: AbortSignal): Promise<void>;
+	renameTab(tabId: string, label: string, signal?: AbortSignal): Promise<void>;
+	focusPane(paneId: string, signal?: AbortSignal): Promise<void>;
+	isTabFocused(tabId: string, signal?: AbortSignal): Promise<boolean>;
+	waitForTabUnfocused(tabId: string, signal?: AbortSignal): Promise<void>;
+	paneExists(paneId: string, signal?: AbortSignal): Promise<boolean>;
+	isTaskRunning(paneId: string, signal?: AbortSignal): Promise<boolean>;
+	closeTab(tabId: string, signal?: AbortSignal): Promise<void>;
+}
+
+interface HerdrResponse {
+	result?: {
+		tab?: { tab_id?: string; focused?: boolean };
+		root_pane?: { pane_id?: string };
+		pane?: { pane_id?: string };
+		agent?: { status?: string };
+		process_info?: { foreground_processes?: Array<{ name?: string; argv?: string[] }> };
+	};
+}
+
+export class HerdrCommandError extends Error {
+	readonly args: string[];
+	readonly exitCode: number | null;
+	readonly stderr: string;
+
+	constructor(
+		message: string,
+		args: string[],
+		exitCode: number | null,
+		stderr: string,
+	) {
+		super(message);
+		this.name = "HerdrCommandError";
+		this.args = args;
+		this.exitCode = exitCode;
+		this.stderr = stderr;
+	}
+}
+
+async function runCommand(binary: string, args: string[], signal?: AbortSignal): Promise<string> {
+	return await new Promise<string>((resolve, reject) => {
+		let stdout = "";
+		let stderr = "";
+		let spawnError: Error | undefined;
+		const child = spawn(binary, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			env: process.env,
+			shell: false,
+		});
+		child.stdout.on("data", (chunk: Buffer | string) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", (error) => {
+			spawnError = error;
+		});
+		const abort = () => child.kill("SIGTERM");
+		const removeAbortListener = () => signal?.removeEventListener("abort", abort);
+		child.once("close", (code) => {
+			removeAbortListener();
+			if (spawnError) {
+				reject(new HerdrCommandError(spawnError.message, args, 1, stderr));
+				return;
+			}
+			if (code !== 0) {
+				const detail = stderr.trim() || stdout.trim() || `exit code ${code}`;
+				reject(new HerdrCommandError(`Herdr command failed: ${detail}`, args, code, stderr));
+				return;
+			}
+			resolve(stdout);
+		});
+
+		if (signal?.aborted) abort();
+		else signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+
+function parseResponse(output: string, operation: string): HerdrResponse {
+	try {
+		return JSON.parse(output) as HerdrResponse;
+	} catch {
+		throw new Error(`${operation} returned invalid JSON`);
+	}
+}
+
+export class CliHerdrAutomation implements HerdrAutomation {
+	private readonly binary: string;
+
+	constructor(binary = process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr") {
+		this.binary = binary;
+	}
+
+	async createTab(request: CreateTabRequest): Promise<{ tabId: string; paneId: string }> {
+		const args = ["tab", "create", "--workspace", request.workspaceId, "--cwd", request.cwd, "--label", request.label];
+		for (const [key, value] of Object.entries(request.env).sort(([left], [right]) => left.localeCompare(right))) {
+			args.push("--env", `${key}=${value}`);
+		}
+		args.push(request.focus ? "--focus" : "--no-focus");
+		const response = parseResponse(await runCommand(this.binary, args, request.signal), "herdr tab create");
+		const tabId = response.result?.tab?.tab_id;
+		const paneId = response.result?.root_pane?.pane_id;
+		if (!tabId || !paneId) throw new Error("herdr tab create omitted the tab or root pane id");
+		return { tabId, paneId };
+	}
+
+	async startAgent(request: StartAgentRequest): Promise<void> {
+		await runCommand(this.binary, ["agent", "start", request.name, "--kind", request.kind, "--pane", request.paneId, "--", ...request.args], request.signal);
+	}
+
+	async promptAgent(request: PromptAgentRequest): Promise<{ status?: string }> {
+		const response = parseResponse(
+			await runCommand(this.binary, ["agent", "prompt", request.target, request.prompt, "--wait"], request.signal),
+			"herdr agent prompt",
+		);
+		return { status: response.result?.agent?.status };
+	}
+
+	async splitPane(request: SplitPaneRequest): Promise<{ paneId: string }> {
+		const args = ["pane", "split", request.paneId, "--direction", request.direction, "--cwd", request.cwd, request.focus ? "--focus" : "--no-focus"];
+		for (const [key, value] of Object.entries(request.env ?? {}).sort(([left], [right]) => left.localeCompare(right))) args.push("--env", `${key}=${value}`);
+		const response = parseResponse(await runCommand(this.binary, args, request.signal), "herdr pane split");
+		const paneId = response.result?.pane?.pane_id;
+		if (!paneId) throw new Error("herdr pane split omitted the pane id");
+		return { paneId };
+	}
+
+	async renamePane(paneId: string, label: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["pane", "rename", paneId, label], signal);
+	}
+
+	async renameTab(tabId: string, label: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["tab", "rename", tabId, label], signal);
+	}
+
+	async focusPane(paneId: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["agent", "focus", paneId], signal);
+	}
+
+	async isTabFocused(tabId: string, signal?: AbortSignal): Promise<boolean> {
+		const response = parseResponse(await runCommand(this.binary, ["tab", "get", tabId], signal), "herdr tab get");
+		return response.result?.tab?.focused === true;
+	}
+
+	async waitForTabUnfocused(tabId: string, signal?: AbortSignal): Promise<void> {
+		while (await this.isTabFocused(tabId, signal)) {
+			await new Promise<void>((resolve, reject) => {
+				const onAbort = () => { clearTimeout(timer); reject(signal?.reason); };
+				const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, 500);
+				if (signal?.aborted) onAbort();
+				else signal?.addEventListener("abort", onAbort, { once: true });
+			});
+		}
+	}
+
+	async paneExists(paneId: string, signal?: AbortSignal): Promise<boolean> {
+		try { await runCommand(this.binary, ["pane", "get", paneId], signal); return true; }
+		catch (error) {
+			if (error instanceof HerdrCommandError && /pane[_ -]?not[_ -]?found|unknown pane/i.test(`${error.message}\n${error.stderr}`)) return false;
+			throw error;
+		}
+	}
+
+	async isTaskRunning(paneId: string, signal?: AbortSignal): Promise<boolean> {
+		try {
+			const response = parseResponse(await runCommand(this.binary, ["pane", "process-info", "--pane", paneId], signal), "herdr pane process-info");
+			return (response.result?.process_info?.foreground_processes ?? []).some((process) => {
+				if (process.name === "pi") return true;
+				return (process.argv ?? []).some((argument) => {
+					const normalized = argument.replaceAll("\\", "/");
+					const file = normalized.split("/").at(-1);
+					return file === "pi" || (/pi-coding-agent/.test(normalized) && /(?:^|\/)cli\.js$/.test(normalized)) || /pi-coding-agent\/dist\/bundle\//.test(normalized);
+				});
+			});
+		} catch (error) {
+			if (error instanceof HerdrCommandError && /pane[_ -]?not[_ -]?found|unknown pane/i.test(`${error.message}\n${error.stderr}`)) return false;
+			throw error;
+		}
+	}
+
+	async closeTab(tabId: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["tab", "close", tabId], signal);
+	}
+}

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

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+import { ownerRecord } from "./ownership.ts";
+import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskRecord, type TaskStatus } from "./records.ts";
+import { continuationSystemPrompt } from "./protocol.ts";
+import { isAbortError } from "./errors.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface HistoricalTask { order: number; id: string; name: string; agent: string; status: TaskStatus; summary?: string; question?: string; documents: PersistedDocument[]; recordDirectory: string; sessionFile: string; model?: string; thinking?: string; tools?: string[]; skills: string[]; access?: string; }
+export interface HistoricalRun { id: string; label: string; status: RunStatus; startedAt: string; completedAt?: string; effectiveConcurrency?: number; cleanupPendingTabIds?: string[]; tasks: HistoricalTask[]; recordDirectory: string; }
+
+export async function ensureRuntimeIgnored(cwd: string): Promise<void> {
+	const piDirectory = join(cwd, ".pi");
+	await mkdir(piDirectory, { recursive: true, mode: 0o700 });
+	const dotGit = join(cwd, ".git");
+	let ignoreFile = join(piDirectory, ".gitignore");
+	let line = "herdr-subagents/runs/";
+	if (existsSync(dotGit)) {
+		let gitDirectory = dotGit;
+		if (!statSync(dotGit).isDirectory()) {
+			const configured = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m)?.[1]?.trim();
+			if (configured) gitDirectory = isAbsolute(configured) ? configured : join(cwd, configured);
+		}
+		const commonDirectoryFile = join(gitDirectory, "commondir");
+		const commonDirectory = existsSync(commonDirectoryFile) ? join(gitDirectory, readFileSync(commonDirectoryFile, "utf8").trim()) : gitDirectory;
+		ignoreFile = join(commonDirectory, "info", "exclude");
+		line = "/.pi/herdr-subagents/runs/";
+		await mkdir(join(commonDirectory, "info"), { recursive: true });
+	}
+	const current = existsSync(ignoreFile) ? await readFile(ignoreFile, "utf8") : "";
+	if (current.split(/\r?\n/).includes(line)) return;
+	await appendFile(ignoreFile, `${current && !current.endsWith("\n") ? "\n" : ""}${line}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+export async function listSubagentHistory(cwd: string): Promise<HistoricalRun[]> {
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	if (!existsSync(runsDirectory)) return [];
+	const history: HistoricalRun[] = [];
+	for (const entry of readdirSync(runsDirectory).sort().reverse()) {
+		const directory = join(runsDirectory, entry);
+		try {
+			const run = await readRunRecord(join(directory, "run.json"));
+			const tasks: HistoricalTask[] = [];
+			let projectedStatus = run.status;
+			const tasksDirectory = join(directory, "tasks");
+			if (existsSync(tasksDirectory)) for (const taskEntry of readdirSync(tasksDirectory).sort()) {
+				const taskDirectory = join(tasksDirectory, taskEntry);
+				let task: TaskRecord;
+				try { task = await readTaskRecord(join(taskDirectory, "task.json")); }
+				catch (error) {
+					projectedStatus = "failed";
+					tasks.push({ order: tasks.length + 1, id: taskEntry, name: taskEntry, agent: "unknown", status: "failed", summary: `Invalid durable task: ${error instanceof Error ? error.message : String(error)}`, documents: [], recordDirectory: taskDirectory, sessionFile: join(taskDirectory, "session.jsonl"), skills: [] });
+					continue;
+				}
+				let report: { summary?: string; question?: string; documents: Array<{ path: string; description: string }> } = { documents: [] };
+				let historyStatus = task.status;
+				const reportFile = join(taskDirectory, "report.json");
+				if (existsSync(reportFile)) {
+					try { report = await readReport(reportFile); }
+					catch (error) {
+						historyStatus = "failed";
+						report = { summary: `Invalid durable report: ${error instanceof Error ? error.message : String(error)}`, documents: [] };
+					}
+				} else if (["completed", "failed", "blocked"].includes(task.status)) {
+					historyStatus = "failed";
+					report = { summary: `Missing structured report: ${reportFile}`, documents: [] };
+				}
+				tasks.push({ order: task.order ?? tasks.length + 1, id: task.id, name: task.name ?? task.agent ?? "worker", agent: task.agent ?? "worker", status: historyStatus, summary: report.summary, question: report.question, documents: report.documents ?? [], recordDirectory: taskDirectory, sessionFile: task.sessionFile, model: task.model, thinking: task.thinking, tools: task.tools, skills: task.skills ?? [], access: task.access });
+			}
+			history.push({ id: run.id, label: run.label, status: projectedStatus, startedAt: run.startedAt, completedAt: run.completedAt, effectiveConcurrency: run.effectiveConcurrency, cleanupPendingTabIds: run.cleanupPendingTabIds, tasks, recordDirectory: directory });
+		} catch (error) {
+			history.push({ id: entry, label: "Unreadable Subagent run", status: "failed", startedAt: "", tasks: [{ order: 1, id: `${entry}-invalid`, name: "Invalid durable run", agent: "unknown", status: "failed", summary: `Could not read Subagent history ${directory}: ${error instanceof Error ? error.message : String(error)}`, documents: [], recordDirectory: directory, sessionFile: join(directory, "session.jsonl"), skills: [] }], recordDirectory: directory });
+		}
+	}
+	return history;
+}
+
+export function historyText(history: HistoricalRun[]): string {
+	if (!history.length) return "No Subagent history in this project.";
+	return history.flatMap((run) => [`${run.id} · ${run.label} · ${run.status} · ${run.tasks.length} tasks`, ...run.tasks.map((task) => `  ${task.order}. ${task.name}: ${task.status}${task.summary ? ` — ${task.summary}` : ""}`)]).join("\n");
+}
+
+export async function cleanSubagentRun(cwd: string, runId: string): Promise<boolean> {
+	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
+	if (!run) return false;
+	if (isActiveStatus(run.status)) throw new Error(`Subagent run '${runId}' is still active and cannot be cleaned.`);
+	if (run.cleanupPendingTabIds?.length) throw new Error(`Subagent run '${runId}' is still waiting to clean up Herdr tabs ${run.cleanupPendingTabIds.join(", ")}.`);
+	await rm(run.recordDirectory, { recursive: true, force: false });
+	return true;
+}
+
+export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; }
+
+export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+	const runDirectory = await findRunDirectory(join(cwd, ".pi", "herdr-subagents", "runs"), runId);
+	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
+	const lockDirectory = join(runDirectory, ".resume.lock");
+	try { await mkdir(lockDirectory); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Subagent run '${runId}' already has a historical resume in progress (lock: ${lockDirectory}).`);
+		throw error;
+	}
+	try { return await resumeHistoricalTaskLocked(cwd, runId, taskNumber, prompt, options); }
+	finally { await rmdir(lockDirectory); }
+}
+
+async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const { signal, onCleanupError } = options;
+	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
+	const historical = run?.tasks.find((task) => task.order === taskNumber);
+	if (!run || !historical) throw new Error(`Unknown historical task ${runId}#${taskNumber}.`);
+	if (isActiveStatus(run.status)) throw new Error(`Subagent run '${runId}' is still active. Use action 'respond' for blocked work or wait for it to settle before resuming history.`);
+	if (run.cleanupPendingTabIds?.length) throw new Error(`Subagent run '${runId}' is still waiting to clean up Herdr tabs ${run.cleanupPendingTabIds.join(", ")}.`);
+	if (!existsSync(historical.sessionFile)) throw new Error(`Historical task ${runId}#${taskNumber} has no saved Pi session.`);
+	const taskFile = join(historical.recordDirectory, "task.json");
+	const task = await readTaskRecord(taskFile);
+	const attempt = Number(task.attempt ?? 1) + 1;
+	const turnsDirectory = join(historical.recordDirectory, "turns");
+	await mkdir(turnsDirectory, { recursive: true, mode: 0o700 });
+	const initialTurnFile = join(turnsDirectory, "01.json");
+	if (!existsSync(initialTurnFile)) {
+		const initialReportFile = join(historical.recordDirectory, "report.json");
+		let initialReport;
+		try { initialReport = await readReport(initialReportFile); }
+		catch (error) { initialReport = { status: "failed" as const, summary: `Previous structured report was unavailable: ${error instanceof Error ? error.message : String(error)}`, documents: [] }; }
+		await writeJsonAtomic(initialTurnFile, { attempt: 1, prompt: task.prompt, status: task.status, summary: initialReport.summary, question: initialReport.question, error: initialReport.error, documents: initialReport.documents ?? [], sessionFile: historical.sessionFile, startedAt: task.startedAt, completedAt: task.completedAt });
+	}
+	const turnFile = join(turnsDirectory, `${String(attempt).padStart(2, "0")}.json`);
+	const followupPrompt = join(historical.recordDirectory, "followup-system-prompt.md");
+	await writeTextAtomic(followupPrompt, `${continuationSystemPrompt(task.systemPrompt, "Continue the requested historical work.", "followup")}\n`);
+	let tab: { tabId: string; paneId: string } | undefined;
+	let failedAttempt: { status: "cancelled" | "failed"; report: PersistedReport; error: unknown } | undefined;
+	const agentName = liveAgentName(historical.id, attempt);
+	try {
+		let report: PersistedReport;
+		let status: "blocked" | "completed" | "failed";
+		try {
+			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: historical.recordDirectory };
+			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
+			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
+			await herdr.renamePane(tab.paneId, paneLabel, options.signal);
+			applyTaskStatus(task, "running");
+			Object.assign(task, { attempt, currentTurnFile: turnFile, tabId: tab.tabId, paneId: tab.paneId, paneLabel, agentName });
+			const activeRunFile = join(run.recordDirectory, "run.json");
+			const activeRunRecord = await readRunRecord(activeRunFile);
+			applyRunStatus(activeRunRecord, "running");
+			Object.assign(activeRunRecord, { ...ownerRecord(options.owner), tabId: tab.tabId, paneIds: [...new Set([...(activeRunRecord.paneIds ?? []), tab.paneId])] });
+			await Promise.all([
+				writeJsonAtomic(taskFile, task),
+				writeJsonAtomic(turnFile, { attempt, prompt, status: "running", sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, startedAt: new Date().toISOString() }),
+				writeJsonAtomic(activeRunFile, activeRunRecord),
+			]);
+			report = (await promptLiveAgent({ herdr, task: { ...task, id: historical.id, sessionFile: historical.sessionFile }, paneId: tab.paneId, prompt, systemPromptFile: followupPrompt, agentName, signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => options.onStalled?.(`${historical.name} appears stalled; it is still running.`) })).report;
+			status = applyReport(task, report);
+		} catch (error) {
+			const settled = await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
+				cancelled: isAbortError(error, signal),
+				error: error instanceof Error ? error.message : String(error),
+				name: `${historical.name} follow-up`,
+				replaceReport: true,
+			});
+			failedAttempt = { ...settled, error };
+			throw error;
+		}
+		await Promise.all([
+			writeJsonAtomic(taskFile, task),
+			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents ?? [], sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, completedAt: new Date().toISOString(), ...(report.question ? { question: report.question } : {}), ...(report.error ? { error: report.error } : {}) }),
+		]);
+		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
+		const aggregateStatus = aggregateTaskStatus((await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId)?.tasks.map((entry) => entry.status) ?? [status]);
+		applyRunStatus(runRecord, aggregateStatus, { question: report.question });
+		Object.assign(runRecord, { ...ownerRecord(options.owner), tabId: tab.tabId });
+		await writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord);
+		if (status !== "blocked") {
+			await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
+		}
+		return { runId, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const completedAt = new Date().toISOString();
+		const settled = failedAttempt ?? await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
+			cancelled: isAbortError(error, signal),
+			error: message,
+			name: `${historical.name} follow-up`,
+			at: completedAt,
+			replaceReport: true,
+		});
+		const { status, report } = settled;
+		task.attempt = attempt;
+		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
+		const aggregateStatus = status === "cancelled" ? "cancelled" : aggregateTaskStatus(run.tasks.map((entry) => entry.id === historical.id ? status : entry.status));
+		applyRunStatus(runRecord, aggregateStatus, { error: message });
+		Object.assign(runRecord, { ...ownerRecord(options.owner), ...(tab ? { tabId: tab.tabId } : {}) });
+		await Promise.all([
+			writeJsonAtomic(taskFile, task),
+			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents, error: message, sessionFile: historical.sessionFile, ...(tab ? { tabId: tab.tabId, paneId: tab.paneId } : {}), completedAt }),
+			writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord),
+		]);
+		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
+		throw error;
+	}
+}

package/packages/herdr-subagents/src/live-agent.ts

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { HerdrAutomation } from "./herdr.ts";
+import type { HerdrSubagentsReport } from "./runner.ts";
+import { parseReport } from "./records.ts";
+
+export interface LiveTaskRecord {
+	id: string;
+	name?: string;
+	agent?: string;
+	sessionFile: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills?: string[];
+}
+
+export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
+	const args = [
+		"--approve",
+		"--session", task.sessionFile,
+		"--name", `Subagent: ${task.name ?? task.agent ?? "worker"}`,
+		"--no-extensions",
+		"--extension", fileURLToPath(new URL("../extensions/subagent-report.ts", import.meta.url)),
+		"--no-skills",
+		"--append-system-prompt", systemPromptFile,
+	];
+	if (task.model) args.push("--model", task.model);
+	if (task.thinking) args.push("--thinking", task.thinking);
+	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "subagent_report"])].join(","));
+	for (const skill of task.skills ?? []) args.push("--skill", skill);
+	return args;
+}
+
+export function liveAgentName(taskId: string, attempt = 1): string {
+	return `herdr-subagent-${taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 12)}-${attempt}`;
+}
+
+export async function promptLiveAgent(options: {
+	herdr: HerdrAutomation;
+	task: LiveTaskRecord;
+	paneId: string;
+	prompt: string;
+	systemPromptFile: string;
+	agentName?: string;
+	attempt?: number;
+	signal?: AbortSignal;
+	start?: boolean;
+	stalledWarningMs?: number;
+	onStalled?: () => void;
+}): Promise<{ report: HerdrSubagentsReport; agentName: string }> {
+	const taskDirectory = dirname(options.task.sessionFile);
+	const reportFile = join(taskDirectory, "report.json");
+	await rm(reportFile, { force: true });
+	const agentName = options.agentName ?? liveAgentName(options.task.id, options.attempt);
+	if (options.start !== false) {
+		await options.herdr.startAgent({
+			name: agentName,
+			kind: "pi",
+			paneId: options.paneId,
+			args: childPiArgs(options.task, options.systemPromptFile),
+			signal: options.signal,
+		});
+	}
+	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
+	let promptError: unknown;
+	try { await options.herdr.promptAgent({ target: agentName, prompt: options.prompt, signal: options.signal }); }
+	catch (error) { promptError = error; }
+	finally { if (stalledTimer) clearTimeout(stalledTimer); }
+	if (!existsSync(reportFile)) {
+		if (promptError) throw promptError;
+		throw new Error("Child Pi settled but did not submit a subagent_report.");
+	}
+	let value: unknown;
+	try { value = JSON.parse(await readFile(reportFile, "utf8")); }
+	catch {
+		if (promptError) throw new Error(`${promptError instanceof Error ? promptError.message : String(promptError)}; Child Pi also submitted an invalid subagent_report.`);
+		throw new Error("Child Pi submitted an invalid subagent_report.");
+	}
+	try { return { report: parseReport(value, "child subagent_report") as HerdrSubagentsReport, agentName }; }
+	catch (error) {
+		const detail = `Child Pi submitted an invalid subagent_report: ${error instanceof Error ? error.message : String(error)}`;
+		throw new Error(promptError ? `${promptError instanceof Error ? promptError.message : String(promptError)}; ${detail}` : detail);
+	}
+}

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

@@ -0,0 +1,18 @@
+import type { BatchResult } from "./batch-runner.ts";
+import type { HerdrAutomation } from "./herdr.ts";
+
+export function activityCounts(run: Pick<BatchResult, "activity">): Record<"running" | "queued" | "blocked" | "failed" | "completed", number> {
+	const count = (status: string) => run.activity.filter((task) => task.status === status).length;
+	return { running: count("running"), queued: count("queued"), blocked: count("blocked"), failed: count("failed"), completed: count("completed") };
+}
+
+export function activeRunText(run: Pick<BatchResult, "label" | "runId" | "activity">): string {
+	return [`${run.label} (${run.runId})`, ...run.activity.map((task) => `${task.index + 1}. ${task.name}: ${task.status}`)].join("\n");
+}
+
+export async function focusActiveTask(run: Pick<BatchResult, "activity"> | undefined, taskNumber: number, herdr: HerdrAutomation): Promise<boolean> {
+	const task = run?.activity.find((candidate) => candidate.index === taskNumber - 1);
+	if (!task?.paneId) return false;
+	await herdr.focusPane(task.paneId);
+	return true;
+}

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

@@ -0,0 +1,17 @@
+export interface OwnerIdentity {
+	sessionId?: string;
+	processId?: number;
+}
+
+export function ownerRecord(owner?: OwnerIdentity): { ownerSessionId?: string; ownerProcessId?: number } {
+	return {
+		...(owner?.sessionId ? { ownerSessionId: owner.sessionId } : {}),
+		...(owner?.processId ? { ownerProcessId: owner.processId } : {}),
+	};
+}
+
+export function isProcessAlive(pid: unknown): boolean {
+	if (!Number.isInteger(pid) || Number(pid) <= 0) return false;
+	try { process.kill(Number(pid), 0); return true; }
+	catch { return false; }
+}

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

@@ -0,0 +1,21 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+export const HerdrSubagentsParams = Type.Object({
+	action: Type.Optional(StringEnum(["list", "respond", "history", "resume", "cleanup"] as const, { description: "Operation mode. Omit it to execute one task or a batch." })),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, or cleanup." })),
+	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
+	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
+	prompt: Type.Optional(Type.String({ minLength: 1, description: "Task prompt for single execution, or follow-up prompt for resume." })),
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for single execution. Defaults to worker." })),
+	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
+	model: Type.Optional(Type.String({ minLength: 1, description: "Optional Pi model override, for example provider/model:high." })),
+	tasks: Type.Optional(Type.Array(Type.Object({
+		name: Type.String({ minLength: 1, maxLength: 48, description: "Short task name shown in the pane and task list." }),
+		prompt: Type.String({ minLength: 1, description: "Self-contained prompt for this task." }),
+		agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for this task. Defaults to worker." })),
+		model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
+	}), { minItems: 1, description: "Ordered tasks for bounded-concurrency batch execution." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents in a batch." })),
+	background: Type.Optional(Type.Boolean({ description: "Return a run ID immediately while the batch continues in this parent session." })),
+}, { additionalProperties: false });

package/packages/{tiny-subagent → herdr-subagents}/src/personas.ts

@@ -17,6 +17,9 @@ export interface AgentDefinition {
 	description: string;
 	model?: string;
 	tools?: string[];
+	access?: "read" | "write";
+	thinking?: string;
+	skills?: string[];
 	systemPrompt: string;
 	filePath: string;
 }
@@ -70,24 +73,32 @@ export function parseAgentMarkdown(content: string, filePath = "<memory>"): Agen
 	}
 
 	const model = fields.get("model")?.trim() || undefined;
+	const rawAccess = fields.get("access")?.trim();
+	if (rawAccess && rawAccess !== "read" && rawAccess !== "write") throw new Error("frontmatter access must be read or write");
+	const access = rawAccess as "read" | "write" | undefined;
+	const thinking = fields.get("thinking")?.trim() || undefined;
+	const skills = fields.has("skills") ? parseList(fields.get("skills") ?? "") : undefined;
 	return {
 		name,
 		description,
 		...(model ? { model } : {}),
 		...(tools ? { tools } : {}),
+		...(access ? { access } : {}),
+		...(thinking ? { thinking } : {}),
+		...(skills ? { skills } : {}),
 		systemPrompt: lines.slice(end + 1).join("\n").trim(),
 		filePath,
 	};
 }
 
-export function discoverPackageAgents(agentsDir: string): AgentDiscovery {
+export function discoverPackageAgents(agentsDir: string, optional = false): AgentDiscovery {
 	const agents: AgentDefinition[] = [];
 	const diagnostics: string[] = [];
 	let entries: string[];
 	try {
 		entries = readdirSync(agentsDir).filter((entry) => entry.endsWith(".md")).sort();
 	} catch (error) {
-		return { agents, diagnostics: [`Cannot read persona directory ${agentsDir}: ${error instanceof Error ? error.message : String(error)}`] };
+		return { agents, diagnostics: optional ? [] : [`Cannot read persona directory ${agentsDir}: ${error instanceof Error ? error.message : String(error)}`] };
 	}
 
 	const names = new Set<string>();

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

@@ -0,0 +1,23 @@
+export type ReportPromptKind = "initial" | "resumed" | "followup";
+
+const TURN_INTRO: Record<ReportPromptKind, string> = {
+	initial: "",
+	resumed: "This is a resumed turn.",
+	followup: "This is a new turn in the same logical task.",
+};
+
+export function reportProtocolPrompt(systemPrompt: string, kind: ReportPromptKind = "initial"): string {
+	return [
+		TURN_INTRO[kind],
+		systemPrompt.trim(),
+		"",
+		"When this turn is finished, call subagent_report exactly once for this turn.",
+		"Put the complete final answer in result, a concise parent-facing paragraph in summary, and list any useful document paths.",
+		"Use status=needs-input with question when missing information prevents progress, or status=failed with an error when the task cannot be completed.",
+	].filter((line, index) => line || index > 1).join("\n").trim();
+}
+
+export function continuationSystemPrompt(originalPrompt: string | undefined, instruction: string, kind: Exclude<ReportPromptKind, "initial">): string {
+	if (!originalPrompt?.trim()) return reportProtocolPrompt(instruction, kind);
+	return [TURN_INTRO[kind], originalPrompt.trim(), "", instruction.trim()].join("\n").trim();
+}