@maxiaochao/pi-toolkit 0.9.6 → 0.10.0

package/packages/herdr-subagents/extensions/subagent-report.ts

@@ -0,0 +1,65 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resultPathForAttempt } from "../src/result-path.ts";
+
+const ReportParams = Type.Object({
+	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
+	summary: Type.String({ minLength: 1, description: "One concise paragraph for the parent agent." }),
+	result: Type.String({ description: "Complete final result. Stored on disk and excluded from the parent context." }),
+	documents: Type.Optional(Type.Array(Type.Object({
+		path: Type.String({ minLength: 1, description: "Path to a document produced or consulted by this task." }),
+		description: Type.String({ minLength: 1, description: "Short description of the document." }),
+	}))),
+	error: Type.Optional(Type.String({ minLength: 1, description: "Failure detail when status is failed." })),
+	question: Type.Optional(Type.String({ minLength: 1, description: "Exact question when status is needs-input." })),
+});
+
+function writeAtomic(path: string, content: string): void {
+	const temporary = `${path}.tmp-${process.pid}`;
+	writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, path);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "subagent_report",
+		label: "Subagent Report",
+		description: "Finish this delegated task by saving its complete result and returning only a compact structured report to the parent.",
+		parameters: ReportParams,
+		async execute(_toolCallId, params) {
+			const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
+			if (!taskDirectory) throw new Error("PI_HERDR_SUBAGENTS_TASK_DIR is not set");
+			mkdirSync(taskDirectory, { recursive: true, mode: 0o700 });
+			let attempt = 1;
+			const task = JSON.parse(readFileSync(resolve(taskDirectory, "task.json"), "utf8")) as { attempt?: unknown };
+			if (Number.isInteger(task.attempt) && Number(task.attempt) > 1) attempt = Number(task.attempt);
+			const resultPath = resultPathForAttempt(taskDirectory, attempt);
+			if (attempt > 1) mkdirSync(resolve(taskDirectory, "turns"), { recursive: true, mode: 0o700 });
+			writeAtomic(resultPath, params.result);
+			const documents = (params.documents ?? []).map((document) => ({
+				path: resolve(process.cwd(), document.path),
+				description: document.description,
+			}));
+			if (!documents.some((document) => document.path === resultPath)) {
+				documents.unshift({ path: resultPath, description: "Complete task result" });
+			}
+			const report = {
+				status: params.status,
+				summary: params.summary,
+				documents,
+				...(params.error ? { error: params.error } : {}),
+				...(params.question ? { question: params.question } : {}),
+				reportedAt: new Date().toISOString(),
+			};
+			writeAtomic(resolve(taskDirectory, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+			return {
+				content: [{ type: "text" as const, text: `${params.status}: ${params.summary}` }],
+				details: report,
+				terminate: true,
+			};
+		},
+	});
+}

package/packages/{tiny-subagent → herdr-subagents}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@maxiaochao/pi-tiny-subagent",
-  "version": "0.1.1",
-  "description": "A tiny Pi subagent tool with package-local personas and detailed process errors.",
+  "name": "@maxiaochao/pi-herdr-subagents",
+  "version": "0.2.0",
+  "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -12,6 +12,7 @@
     "extensions",
     "src",
     "agents",
+    "tests",
     "docs",
     "README.md",
     "TESTING.md",
@@ -21,11 +22,11 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
-    "directory": "packages/tiny-subagent"
+    "directory": "packages/herdr-subagents"
   },
   "pi": {
     "extensions": [
-      "./extensions/tiny-subagent.ts"
+      "./extensions/herdr-subagents.ts"
     ]
   },
   "peerDependencies": {
@@ -36,7 +37,7 @@
   },
   "scripts": {
     "test": "node --experimental-strip-types tests/run-tests.mjs",
-    "load-test": "pi -ne -ns --no-session -e ./extensions/tiny-subagent.ts"
+    "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./extensions/herdr-subagents.ts"
   },
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
+import type { PersonaAccess } from "./config.ts";
+import type { HerdrSubagentsDocument } from "./runner.ts";
+import { ensureRuntimeIgnored } from "./history.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic } from "./state.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+import { ownerRecord } from "./ownership.ts";
+import { RunPaneAllocator } from "./run-pane-allocator.ts";
+import { applyReport, applyTaskStatus, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus } from "./records.ts";
+import { reportProtocolPrompt } from "./protocol.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import { applyRunStatus } from "./run-status.ts";
+import { isAbortError } from "./errors.ts";
+
+export interface BatchTask {
+	name: string;
+	prompt: string;
+	agent: string;
+	access: PersonaAccess;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills: string[];
+	systemPrompt: string;
+}
+
+export interface BatchOptions {
+	runId?: string;
+	label: string;
+	concurrency: number;
+	maxConcurrency: number;
+	stalledWarningSeconds?: number;
+	cwd: string;
+	signal?: AbortSignal;
+	herdr?: HerdrAutomation;
+	owner?: OwnerIdentity;
+	onUpdate?: (result: BatchResult) => void;
+	onCleanupError?: (message: string) => void;
+}
+
+type BatchTaskStatus = Exclude<TaskStatus, "starting">;
+export interface BatchTaskResult {
+	index: number;
+	name: string;
+	status: Exclude<BatchTaskStatus, "queued" | "running">;
+	summary: string;
+	documents: HerdrSubagentsDocument[];
+	error?: string;
+	question?: string;
+	paneId: string;
+	recordDirectory: string;
+	sessionFile: string;
+}
+export interface BatchResult {
+	ok: boolean;
+	status: "starting" | "running" | "blocked" | "completed" | "partial" | "failed" | "cancelled";
+	runId: string;
+	label: string;
+	requestedConcurrency: number;
+	effectiveConcurrency: number;
+	tasks: BatchTaskResult[];
+	activity: Array<{ index: number; name: string; status: BatchTaskStatus; paneId?: string }>;
+	summary: string;
+	documents: HerdrSubagentsDocument[];
+	recordDirectory: string;
+	tabId?: string;
+}
+
+type TaskContext = {
+	taskId: string;
+	taskDirectory: string;
+	sessionFile: string;
+	reportFile: string;
+	taskFile: string;
+	systemPromptFile: string;
+	taskRecord: TaskRecord;
+};
+
+function timestamp(): string { return new Date().toISOString(); }
+export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchOptions): Promise<BatchResult> {
+	if (!tasks.length) throw new Error("At least one task is required.");
+	if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) throw new Error("Herdr Subagents must run from a Pi session inside Herdr.");
+	const runId = options.runId ?? randomUUID();
+	const requestedConcurrency = Math.max(1, Math.floor(options.concurrency));
+	const effectiveConcurrency = tasks.some((task) => task.access === "write") ? 1 : Math.min(requestedConcurrency, options.maxConcurrency, tasks.length);
+	const runDirectory = join(options.cwd, ".pi", "herdr-subagents", "runs", `${timestamp().replace(/[-:.]/g, "").replace("Z", "Z-")}${runId.slice(0, 8)}`);
+	const runFile = join(runDirectory, "run.json");
+	await ensureRuntimeIgnored(options.cwd);
+	await mkdir(join(runDirectory, "tasks"), { recursive: true, mode: 0o700 });
+	const contexts: TaskContext[] = await Promise.all(tasks.map(async (task, index) => {
+		const taskId = randomUUID();
+		const taskDirectory = join(runDirectory, "tasks", `${String(index + 1).padStart(2, "0")}-${taskId.slice(0, 8)}`);
+		const sessionFile = join(taskDirectory, "session.jsonl");
+		const systemPromptFile = join(taskDirectory, "system-prompt.md");
+		const taskRecord: TaskRecord = {
+			id: taskId, runId, order: index + 1, name: task.name, status: "queued", prompt: task.prompt,
+			agent: task.agent, access: task.access, model: task.model, thinking: task.thinking,
+			tools: task.tools, skills: task.skills, systemPrompt: reportProtocolPrompt(task.systemPrompt), sessionFile,
+		};
+		await mkdir(taskDirectory, { recursive: true, mode: 0o700 });
+		await writeFile(systemPromptFile, String(taskRecord.systemPrompt), { encoding: "utf8", mode: 0o600 });
+		const taskFile = join(taskDirectory, "task.json");
+		await writeJsonAtomic(taskFile, taskRecord);
+		return { taskId, taskDirectory, sessionFile, reportFile: join(taskDirectory, "report.json"), taskFile, systemPromptFile, taskRecord };
+	}));
+	const runRecord: RunRecord = {
+		id: runId, label: options.label, status: "starting", cwd: options.cwd, ...ownerRecord(options.owner), requestedConcurrency,
+		effectiveConcurrency, stalledWarningSeconds: options.stalledWarningSeconds, startedAt: timestamp(), taskIds: contexts.map((context) => context.taskId), paneIds: [],
+	};
+	await writeJsonAtomic(runFile, runRecord);
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const results = new Array<BatchTaskResult>(tasks.length);
+	const activity: BatchResult["activity"] = tasks.map((task, index) => ({ index, name: task.name, status: "queued" }));
+	let tabId: string | undefined;
+	const paneAllocator = new RunPaneAllocator({ herdr, run: runRecord, runFile, signal: options.signal, onCleanupError: options.onCleanupError });
+	const emit = (status: BatchResult["status"], summary: string) => options.onUpdate?.({
+		ok: false, status, runId, label: options.label, requestedConcurrency, effectiveConcurrency,
+		tasks: results.filter(Boolean), activity: activity.map((entry) => ({ ...entry })), summary,
+		documents: results.filter(Boolean).flatMap((result) => result.documents), recordDirectory: runDirectory, tabId,
+	});
+	const allocatePane = async (index: number): Promise<string> => {
+		const paneId = await paneAllocator.allocate(contexts[index].taskDirectory);
+		tabId = paneAllocator.tabId;
+		return paneId;
+	};
+
+	emit("starting", `Starting up to ${effectiveConcurrency} interactive Pi Agent${effectiveConcurrency === 1 ? "" : "s"}...`);
+	let nextIndex = 0;
+	let settled = 0;
+	try {
+		const runOne = async (index: number): Promise<void> => {
+			const task = tasks[index];
+			const context = contexts[index];
+			let paneId = "";
+			let agentName = liveAgentName(context.taskId);
+			let report: PersistedReport;
+			let status: BatchTaskResult["status"];
+			try {
+				paneId = await allocatePane(index);
+				const paneLabel = `${String(index + 1).padStart(2, "0")} · ${task.name}`;
+				await herdr.renamePane(paneId, paneLabel, options.signal);
+				applyTaskStatus(context.taskRecord, "running");
+				Object.assign(context.taskRecord, { tabId, paneId, paneLabel, agentName, startedAt: timestamp() });
+				await writeJsonAtomic(context.taskFile, context.taskRecord);
+				activity[index] = { index, name: task.name, status: "running", paneId };
+				emit("running", `${settled}/${tasks.length} tasks settled.`);
+				const prompted = await promptLiveAgent({ herdr, task: { ...task, id: context.taskId, sessionFile: context.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: context.systemPromptFile, agentName, signal: options.signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => emit("running", `${task.name} appears stalled; it is still running.`) });
+				agentName = prompted.agentName;
+				report = prompted.report;
+				status = applyReport(context.taskRecord, report);
+			} catch (error) {
+				const settled = await settleAttemptFailure(context.taskRecord, context.reportFile, {
+					cancelled: isAbortError(error, options.signal),
+					error: error instanceof Error ? error.message : String(error),
+					name: task.name,
+				});
+				report = settled.report;
+				status = settled.status;
+			}
+			Object.assign(context.taskRecord, { paneId, agentName });
+			await writeJsonAtomic(context.taskFile, context.taskRecord);
+			results[index] = { index, name: task.name, status, summary: report.summary, documents: report.documents, ...(report.error ? { error: report.error } : {}), ...(report.question ? { question: report.question } : {}), paneId, recordDirectory: context.taskDirectory, sessionFile: context.sessionFile };
+			activity[index] = { index, name: task.name, status, ...(paneId ? { paneId } : {}) };
+			settled += 1;
+			emit("running", `${settled}/${tasks.length} tasks settled.`);
+		};
+		const worker = async () => {
+			while (!options.signal?.aborted) {
+				const index = nextIndex++;
+				if (index >= tasks.length) return;
+				await runOne(index);
+				if (results[index]?.status === "blocked") return;
+			}
+		};
+		await Promise.all(Array.from({ length: effectiveConcurrency }, worker));
+		if (options.signal?.aborted) {
+			for (let index = 0; index < tasks.length; index += 1) {
+				if (activity[index].status !== "queued") continue;
+				activity[index].status = "cancelled";
+				Object.assign(contexts[index].taskRecord, { status: "cancelled", completedAt: timestamp(), error: "Parent Pi session closed." });
+				await writeJsonAtomic(contexts[index].taskFile, contexts[index].taskRecord);
+			}
+		}
+		const settledResults = results.filter(Boolean);
+		const blocked = settledResults.find((result) => result.status === "blocked");
+		const failed = settledResults.filter((result) => result.status === "failed").length;
+		const cancelled = options.signal?.aborted || activity.some((entry) => entry.status === "cancelled");
+		const status: BatchResult["status"] = cancelled ? "cancelled" : blocked || activity.some((entry) => entry.status === "queued") ? "blocked" : failed === 0 ? "completed" : failed === tasks.length ? "failed" : "partial";
+		const summary = status === "cancelled" ? "Subagent batch cancelled because the parent Pi session closed." : blocked ? `${blocked.name} needs input: ${blocked.question}` : failed ? `${tasks.length - failed}/${tasks.length} tasks completed; ${failed} failed.` : `${tasks.length}/${tasks.length} tasks completed.`;
+		applyRunStatus(runRecord, status, { question: blocked?.question });
+		await writeJsonAtomic(runFile, runRecord);
+		return { ok: status === "completed", status, runId, label: options.label, requestedConcurrency, effectiveConcurrency, tasks: settledResults, activity, summary, documents: settledResults.flatMap((result) => result.documents), recordDirectory: runDirectory, tabId };
+	} catch (error) {
+		applyRunStatus(runRecord, options.signal?.aborted ? "cancelled" : "failed", { error: error instanceof Error ? error.message : String(error) });
+		await writeJsonAtomic(runFile, runRecord);
+		throw error;
+	} finally {
+		const keepTab = !options.signal?.aborted && activity.some((entry) => entry.status === "blocked" || entry.status === "queued" || entry.status === "running");
+		if (tabId && !keepTab) {
+			try {
+				await cleanupRunTab({
+					herdr, tabId, runFile, runRecord, signal: options.signal, failureStatus: "failed",
+					errorPrefix: "Task results settled, but Herdr tab cleanup failed",
+					onError: (message) => { emit("failed", message); options.onCleanupError?.(message); },
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				const cleanupError = new Error(`Task results settled, but Herdr tab cleanup failed: ${message}`) as Error & { recordDirectory: string; runId: string };
+				cleanupError.recordDirectory = runDirectory;
+				cleanupError.runId = runId;
+				throw cleanupError;
+			}
+		}
+	}
+}

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

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
+import { continueQueuedRun } from "./continue-run.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, persistFailureReport, readReport, readRunRecord, readTaskRecord, readTurnRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus, type TurnRecord } from "./records.ts";
+import { isAbortError } from "./errors.ts";
+import { continuationSystemPrompt } from "./protocol.ts";
+import { RunPaneAllocator } from "./run-pane-allocator.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface RespondToBlockedTaskOptions { herdr?: HerdrAutomation; taskNumber?: number; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; onWarning?: (message: string) => void; onStalled?: (message: string) => void; onUpdate?: (result: ResumeBlockedResult) => void; }
+export interface ResumeBlockedResult {
+	ok: boolean;
+	runId: string;
+	label: string;
+	status: "blocked" | "completed" | "partial" | "failed" | "cancelled";
+	summary: string;
+	question?: string;
+	documents: PersistedDocument[];
+	recordDirectory: string;
+	requestedConcurrency: number;
+	effectiveConcurrency: number;
+	tasks?: Array<{ index: number; name: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; error?: string; question?: string; paneId: string; recordDirectory: string; sessionFile: string }>;
+	activity?: Array<{ index: number; name: string; status: TaskStatus; paneId?: string }>;
+	tabId?: string;
+}
+
+async function emitProgress(options: RespondToBlockedTaskOptions, runDirectory: string, run: RunRecord, taskDirectories: string[], summary: string): Promise<void> {
+	if (!options.onUpdate) return;
+	const tasks = await Promise.all(taskDirectories.map((directory) => readTaskRecord(join(directory, "task.json"))));
+	options.onUpdate({
+		ok: false,
+		runId: run.id,
+		label: run.label,
+		status: "blocked",
+		summary,
+		documents: [],
+		recordDirectory: runDirectory,
+		requestedConcurrency: Number(run.requestedConcurrency ?? 1),
+		effectiveConcurrency: Number(run.effectiveConcurrency ?? 1),
+		activity: tasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: entry.paneId } : {}) })),
+		...(run.tabId ? { tabId: run.tabId } : {}),
+	});
+}
+
+async function projectSettledRun(runDirectory: string, runFile: string, run: RunRecord, taskDirectories: string[], herdr: HerdrAutomation, onCleanupError?: (message: string) => void): Promise<ResumeBlockedResult> {
+	const finalTasks = await Promise.all(taskDirectories.map((directory) => readTaskRecord(join(directory, "task.json"))));
+	const finalReports = await Promise.all(taskDirectories.map(async (directory, index) => {
+		const reportFile = join(directory, "report.json");
+		if (!existsSync(reportFile) && (finalTasks[index].status === "queued" || finalTasks[index].status === "cancelled")) return { status: "failed" as const, summary: finalTasks[index].error ?? (finalTasks[index].status === "queued" ? "Task is still queued." : "Task was cancelled."), documents: [] };
+		try { return await readReport(reportFile); }
+		catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			const failedReport = { status: "failed" as const, summary: `Could not read task report: ${detail}`, documents: [], error: detail };
+			applyReport(finalTasks[index], failedReport);
+			await Promise.all([writeJsonAtomic(join(directory, "task.json"), finalTasks[index]), persistFailureReport(reportFile, failedReport)]);
+			return failedReport;
+		}
+	}));
+	const aggregateStatus = aggregateTaskStatus(finalTasks.map((entry) => entry.status));
+	const runStatus = aggregateStatus === "running" ? "blocked" : aggregateStatus;
+	const blockedIndex = finalTasks.findIndex((entry) => entry.status === "blocked");
+	const blockedReport = blockedIndex >= 0 ? finalReports[blockedIndex] : undefined;
+	run = await readRunRecord(runFile);
+	applyRunStatus(run, runStatus, { question: blockedReport?.question });
+	await writeJsonAtomic(runFile, run);
+	if (runStatus !== "blocked" && run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, onError: onCleanupError, failureStatus: "failed" });
+	const summary = runStatus === "completed" ? "All tasks completed after the answer." : runStatus === "blocked" ? `${finalTasks[blockedIndex]?.name ?? "Task"} needs input: ${blockedReport?.question ?? "Input required."}` : finalReports.map((entry, index) => `${finalTasks[index].name}: ${entry.summary}`).join("\n");
+	const activity = finalTasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: String(entry.paneId) } : {}) }));
+	const tasks = finalTasks.map((entry, index) => ({ index, name: activity[index].name, status: entry.status, summary: String(finalReports[index].summary ?? "Task has no report."), documents: finalReports[index].documents ?? [], ...(entry.error ? { error: String(entry.error) } : {}), ...(entry.question ? { question: String(entry.question) } : {}), paneId: String(entry.paneId ?? ""), recordDirectory: taskDirectories[index], sessionFile: String(entry.sessionFile ?? "") }));
+	return { ok: runStatus === "completed", runId: run.id, label: String(run.label ?? "batch"), status: runStatus, summary, ...(blockedReport?.question ? { question: blockedReport.question } : {}), documents: finalReports.flatMap((entry) => entry.documents ?? []), recordDirectory: runDirectory, requestedConcurrency: Number(run.requestedConcurrency ?? run.effectiveConcurrency ?? 1), effectiveConcurrency: Number(run.effectiveConcurrency ?? 1), tasks, activity, ...(run.tabId ? { tabId: String(run.tabId) } : {}) };
+}
+
+export async function respondToBlockedTask(cwd: string, runId: string, answer: string, options: RespondToBlockedTaskOptions = {}): Promise<ResumeBlockedResult> {
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const { taskNumber, signal, onCleanupError } = options;
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	const runDirectory = await findRunDirectory(runsDirectory, runId);
+	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
+	const runFile = join(runDirectory, "run.json");
+	const run = await readRunRecord(runFile);
+	const taskDirectories = readdirSync(join(runDirectory, "tasks")).sort().map((entry) => join(runDirectory, "tasks", entry));
+	let taskDirectory: string | undefined;
+	let task: TaskRecord | undefined;
+	for (const directory of taskDirectories) {
+		const candidate = await readTaskRecord(join(directory, "task.json"));
+		if (candidate.status === "blocked" && (!taskNumber || candidate.order === taskNumber)) { taskDirectory = directory; task = candidate; break; }
+	}
+	if (!taskDirectory || !task) throw new Error(`Run '${runId}' has no blocked task.`);
+	Object.assign(run, ownerRecord(options.owner));
+	const previousReport = await readReport(join(taskDirectory, "report.json"));
+	const turnsDirectory = join(taskDirectory, "turns");
+	await mkdir(turnsDirectory, { recursive: true, mode: 0o700 });
+	const resumePrompt = join(taskDirectory, "resume-system-prompt.md");
+	await writeTextAtomic(resumePrompt, `${continuationSystemPrompt(task.systemPrompt, "Continue from the supplied answer.", "resumed")}\n`);
+	let paneId = String(task.paneId ?? "");
+	let agentName = String(task.agentName ?? liveAgentName(task.id));
+	let live = Boolean(paneId) && await herdr.paneExists(paneId, signal) && await herdr.isTaskRunning(paneId, signal);
+	if (!live) {
+		const paneAllocator = new RunPaneAllocator({ herdr, run, runFile, signal, validateExistingPane: true, onCleanupError });
+		paneId = await paneAllocator.allocate(taskDirectory);
+		agentName = liveAgentName(task.id, Number(task.attempt ?? 1) + 1);
+		task.attempt = Number(task.attempt ?? 1) + 1;
+		await herdr.renamePane(paneId, `${String(task.order).padStart(2, "0")} · ${task.name ?? task.agent}`, signal);
+	}
+	const attempt = Number(task.attempt ?? 1);
+	const turnFile = live && task.currentTurnFile ? String(task.currentTurnFile) : join(turnsDirectory, `${String(attempt).padStart(2, "0")}.json`);
+	let turn: TurnRecord = { attempt, prompt: task.prompt, status: "blocked", summary: previousReport.summary, question: previousReport.question, documents: previousReport.documents ?? [], sessionFile: task.sessionFile, startedAt: task.startedAt };
+	if (existsSync(turnFile)) {
+		try { turn = await readTurnRecord(turnFile); }
+		catch (error) {
+			const archivedPath = `${turnFile}.invalid-${Date.now()}`;
+			await rename(turnFile, archivedPath);
+			options.onWarning?.(`Archived invalid durable turn ${turnFile} at ${archivedPath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	turn.events = [...(Array.isArray(turn.events) ? turn.events : []), { type: "answer", text: answer, at: new Date().toISOString() }];
+	task.currentTurnFile = turnFile;
+	applyTaskStatus(task, "running");
+	Object.assign(task, { tabId: run.tabId, paneId, agentName });
+	await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(runFile, run), writeJsonAtomic(turnFile, turn)]);
+	await emitProgress(options, runDirectory, run, taskDirectories, `${task.name ?? task.agent} is continuing after input.`);
+	let report: PersistedReport;
+	let status: "blocked" | "completed" | "failed" | "cancelled";
+	let attemptError: unknown;
+	try {
+		report = (await promptLiveAgent({ herdr, task: { ...task, id: task.id, sessionFile: task.sessionFile }, paneId, prompt: answer, systemPromptFile: resumePrompt, agentName, start: !live, signal, stalledWarningMs: run.stalledWarningSeconds ? Number(run.stalledWarningSeconds) * 1000 : undefined, onStalled: () => options.onStalled?.(`${task.name ?? task.agent} appears stalled; it is still running.`) })).report;
+		status = applyReport(task, report);
+	} catch (error) {
+		attemptError = error;
+		const settled = await settleAttemptFailure(task, join(taskDirectory, "report.json"), {
+			cancelled: isAbortError(error, signal),
+			error: error instanceof Error ? error.message : String(error),
+			name: `${task.name ?? task.agent} response`,
+			replaceReport: true,
+		});
+		report = settled.report;
+		status = settled.status;
+	}
+	if (attemptError && isAbortError(attemptError, signal)) {
+		const message = attemptError instanceof Error ? attemptError.message : String(attemptError);
+			applyTaskStatus(task, "cancelled", { error: message });
+			applyRunStatus(run, "cancelled", { error: message });
+			applyTaskStatus(turn, "cancelled", { error: message });
+			for (const siblingDirectory of taskDirectories) {
+				if (siblingDirectory === taskDirectory) continue;
+				const siblingFile = join(siblingDirectory, "task.json");
+				const sibling = await readTaskRecord(siblingFile);
+				if (!isActiveStatus(sibling.status)) continue;
+				applyTaskStatus(sibling, "cancelled", { error: "Parent Pi session closed." });
+				await writeJsonAtomic(siblingFile, sibling);
+			}
+			await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(runFile, run), writeJsonAtomic(turnFile, turn)]);
+			if (run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal, onError: onCleanupError, failureStatus: "failed" });
+			return { ok: false, runId, label: String(run.label ?? "batch"), status: "cancelled", summary: "Subagent response cancelled.", documents: [], recordDirectory: runDirectory, requestedConcurrency: Number(run.requestedConcurrency ?? 1), effectiveConcurrency: Number(run.effectiveConcurrency ?? 1), ...(run.tabId ? { tabId: String(run.tabId) } : {}) };
+	}
+	turn.events.push({ type: "report", status, summary: report.summary, question: report.question, error: report.error, at: new Date().toISOString() });
+	Object.assign(turn, { summary: report.summary, documents: report.documents ?? [] });
+	applyReport(turn, report);
+	await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(turnFile, turn)]);
+	await emitProgress(options, runDirectory, run, taskDirectories, `${task.name ?? task.agent} ${status}.`);
+	if (status !== "blocked") {
+		applyRunStatus(run, "queued");
+		await writeJsonAtomic(runFile, run);
+		await continueQueuedRun(runDirectory, herdr, { cleanup: false, signal, onStalled: options.onStalled, onCleanupError, onUpdate: () => emitProgress(options, runDirectory, run, taskDirectories, "Queued tasks are continuing.") });
+	}
+	return projectSettledRun(runDirectory, runFile, run, taskDirectories, herdr, onCleanupError);
+}

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

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { discoverPackageAgents, type AgentDefinition } from "./personas.ts";
+
+export type PersonaAccess = "read" | "write";
+export interface PersonaConfig { model?: string; thinking?: string; skills?: string[]; }
+export interface SubagentConfig {
+	defaultConcurrency: number;
+	maxConcurrency: number;
+	stalledWarningSeconds: number;
+	defaultModel?: string;
+	personas: Record<string, PersonaConfig>;
+}
+export interface EffectivePersona extends AgentDefinition {
+	source: "project" | "global" | "package";
+	access: PersonaAccess;
+	model?: string;
+	modelSource: string;
+	thinking?: string;
+	thinkingSource: string;
+	skills: string[];
+	skillsSource: string;
+}
+export interface SubagentConfiguration {
+	settings: SubagentConfig;
+	settingSources: Record<string, string>;
+	personas: EffectivePersona[];
+	diagnostics: string[];
+}
+interface ConfigFile {
+	defaultConcurrency?: number;
+	maxConcurrency?: number;
+	stalledWarningSeconds?: number;
+	defaultModel?: string;
+	personas?: Record<string, PersonaConfig>;
+}
+export interface ConfigurationPaths {
+	globalConfig?: string;
+	projectConfig?: string;
+	globalAgents?: string;
+	projectAgents?: string;
+}
+const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, personas: {} };
+
+function readConfig(path: string, source: string, diagnostics: string[]): ConfigFile {
+	if (!existsSync(path)) return {};
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected a JSON object");
+		return value as ConfigFile;
+	} catch (error) {
+		diagnostics.push(`${source} configuration ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return {};
+	}
+}
+
+function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, sources: Record<string, string>, diagnostics: string[]): SubagentConfig {
+	const result: SubagentConfig = { ...base, personas: { ...base.personas } };
+	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds"] as const) {
+		const value = input[key];
+		if (value === undefined) continue;
+		if (!Number.isInteger(value) || Number(value) <= 0) { diagnostics.push(`${source} ${key} must be a positive integer`); continue; }
+		result[key] = value as number;
+		sources[key] = source;
+	}
+	if (input.defaultModel !== undefined) {
+		if (typeof input.defaultModel === "string" && input.defaultModel.trim()) { result.defaultModel = input.defaultModel.trim(); sources.defaultModel = source; }
+		else diagnostics.push(`${source} defaultModel must be a non-empty string`);
+	}
+	if (input.personas !== undefined) {
+		if (!input.personas || typeof input.personas !== "object" || Array.isArray(input.personas)) diagnostics.push(`${source} personas must be an object`);
+		else for (const [name, raw] of Object.entries(input.personas)) {
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) { diagnostics.push(`${source} persona '${name}' must be an object`); continue; }
+			const valid: PersonaConfig = {};
+			for (const field of ["model", "thinking"] as const) {
+				const value = raw[field];
+				if (value === undefined) continue;
+				if (typeof value === "string" && value.trim()) valid[field] = value.trim();
+				else diagnostics.push(`${source} persona '${name}' ${field} must be a non-empty string`);
+			}
+			if (raw.skills !== undefined) {
+				if (Array.isArray(raw.skills) && raw.skills.every((value) => typeof value === "string" && value.trim())) valid.skills = raw.skills.map((value) => value.trim());
+				else diagnostics.push(`${source} persona '${name}' skills must be an array of non-empty strings`);
+			}
+			input.personas[name] = valid;
+			result.personas[name] = { ...(result.personas[name] ?? {}), ...valid };
+			for (const field of Object.keys(valid)) sources[`personas.${name}.${field}`] = source;
+		}
+	}
+	return result;
+}
+
+export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: string, parentModel?: string, paths: ConfigurationPaths = {}): SubagentConfiguration {
+	const diagnostics: string[] = [];
+	const globalConfigPath = paths.globalConfig ?? join(homedir(), ".pi", "agent", "herdr-subagents.json");
+	const projectConfigPath = paths.projectConfig ?? join(cwd, ".pi", "herdr-subagents.json");
+	const globalAgentsDirectory = paths.globalAgents ?? join(dirname(globalConfigPath), "herdr-subagents", "agents");
+	const projectAgentsDirectory = paths.projectAgents ?? join(cwd, ".pi", "herdr-subagents", "agents");
+	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in" };
+	const globalInput = readConfig(globalConfigPath, "global", diagnostics);
+	const projectInput = readConfig(projectConfigPath, "project", diagnostics);
+	const globalSettings = mergeConfig(DEFAULTS, globalInput, "global", settingSources, diagnostics);
+	const settings = mergeConfig(globalSettings, projectInput, "project", settingSources, diagnostics);
+	if (settings.defaultConcurrency > settings.maxConcurrency) { diagnostics.push("defaultConcurrency exceeds maxConcurrency; maxConcurrency is used"); settings.defaultConcurrency = settings.maxConcurrency; }
+	const layers = [
+		{ source: "package" as const, discovery: discoverPackageAgents(packageAgentsDirectory) },
+		{ source: "global" as const, discovery: discoverPackageAgents(globalAgentsDirectory, true) },
+		{ source: "project" as const, discovery: discoverPackageAgents(projectAgentsDirectory, true) },
+	];
+	const definitions = new Map<string, { definition: AgentDefinition; source: "project" | "global" | "package" }>();
+	for (const layer of layers) { diagnostics.push(...layer.discovery.diagnostics); for (const definition of layer.discovery.agents) definitions.set(definition.name, { definition, source: layer.source }); }
+	const personas = [...definitions.values()].map(({ definition, source }): EffectivePersona => {
+		const globalPersona = globalInput.personas?.[definition.name] ?? {};
+		const projectPersona = projectInput.personas?.[definition.name] ?? {};
+		const model = projectPersona.model ?? globalPersona.model ?? definition.model ?? settings.defaultModel ?? parentModel;
+		const modelSource = projectPersona.model ? "project persona" : globalPersona.model ? "global persona" : definition.model ? `${source} persona` : settings.defaultModel ? settingSources.defaultModel : parentModel ? "parent session" : "unresolved";
+		const thinking = projectPersona.thinking ?? globalPersona.thinking ?? definition.thinking;
+		const thinkingSource = projectPersona.thinking ? "project persona" : globalPersona.thinking ? "global persona" : definition.thinking ? `${source} persona` : "default";
+		const skills = projectPersona.skills ?? globalPersona.skills ?? definition.skills ?? [];
+		const skillsSource = projectPersona.skills ? "project persona" : globalPersona.skills ? "global persona" : definition.skills ? `${source} persona` : "none";
+		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource };
+	}).sort((left, right) => left.name.localeCompare(right.name));
+	return { settings, settingSources, personas, diagnostics };
+}