@maxiaochao/pi-toolkit 0.10.14 → 0.10.17

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2026-10-10 - v0.10.17
+
+- bundle herdr-subagents v0.4.5: fix transient retry lifecycle, attempt isolation, and recovery semantics
+- bundle Herdr Subagents lifecycle and attempt-isolation fixes so provider retries cannot create false failed tasks or overwrite newer attempts
+
+## 2026-10-10 - v0.10.16
+
+- tapd skill: handle large attachment timeouts without misdiagnosing download failures
+
+## 2026-10-09 - v0.10.15
+
+- redesign the TAPD skill around executable workflows, explicit workspace and JSON contracts, and safe attachment handling
+
 ## 2026-10-09 - v0.10.14
 
 - bundle worktree v0.3.2: continue Agent tasks automatically after switching into a worktree

package/README.md

@@ -87,7 +87,7 @@ bash scripts/install.sh
 | `pdlog` | Decompress and inspect Pudu `.pdlog` files |
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
 | `agent-team` | Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents |
-| `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
+| `tapd` | Investigate and operate on TAPD items with workspace, evidence, and safe-download guardrails |
 
 Package-specific skills, such as `pi-worktree`, are documented by their child package.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.14",
+  "version": "0.10.17",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-10-10 - v0.4.5
+
+- fix transient retry lifecycle, attempt isolation, and recovery semantics
+- prevent transient Herdr states from finalizing live child attempts
+- Report authoritative child Pi lifecycle state even under `--no-extensions`, wait through provider retry/fallback until the matching structured report arrives, and bind every report to a unique attempt ID.
+- Reconcile matching attempt reports after interruption, serialize blocked responses, keep blocked results non-error, and preserve business outcomes when tab cleanup fails.
+- Aggregate mixed failed/cancelled task sets as partial instead of hiding one terminal outcome.
+
 ## 2026-10-09 - v0.4.4
 
 - return failed foreground batches early while surviving subagents continue in background

package/packages/herdr-subagents/README.md

@@ -82,6 +82,8 @@ A child missing required information reports `needs-input` with an exact questio
 herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
+Blocked is a normal control state, not a failed tool call. Only terminal failure, cancellation, or a partial aggregate is returned as a tool error.
+
 Cancel one active or queued run with `herdr_subagents_control({ action: "cancel", runId: "<run-id>" })`. Cancellation aborts its live child prompts, archives active or queued tasks as cancelled, closes its run tab, and leaves unrelated runs alone.
 
 While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and refreshes session usage from both file events and the running one-second timer.
@@ -96,13 +98,13 @@ Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({
 
 Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
 
-The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task or resuming saved history refreshes authoritative persona, timing, session, status, and pane projections as work advances. Active duration accumulates only while the task is running, excluding time spent queued or waiting for an answer. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning. An already-missing tab is treated as successfully cleaned, so retries are idempotent.
+The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task or resuming saved history refreshes authoritative persona, timing, session, status, and pane projections as work advances. Active duration accumulates only while the task is running, excluding time spent queued or waiting for an answer. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning without changing the completed/failed business result. An already-missing tab is treated as successfully cleaned, so retries are idempotent.
 
-Foreground calls wait until all children report completion or a request for input when no task fails. On the first task failure, they return early as described above while the surviving children continue. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane.
+Foreground calls wait until all children report completion or a request for input when no task fails. On the first task failure, they return early as described above while the surviving children continue. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane. The child extension reports Pi's authoritative `agent_start`/`agent_settled` lifecycle to Herdr, so provider retry and fallback screens cannot end a task early through screen detection alone.
 
 ## Reports and records
 
-The child must finish through the package's structured `subagent_report` tool. The parent receives only:
+The child must finish through the package's structured `subagent_report` tool. Every prompt gets a unique attempt ID; the child commits to an attempt-specific report, and the parent accepts only the matching report before updating the canonical task result. A late report from an older retry, response, or historical follow-up cannot settle a newer attempt. The parent receives only:
 
 - completion or failure status
 - a concise summary
@@ -115,7 +117,7 @@ The complete result is not copied into the parent model context. Each run is ret
 .pi/herdr-subagents/runs/<run>/tasks/<task>/
 ```
 
-The task directory contains the full result, structured report, task metadata, system prompt, and persistent Pi session. Run-level metadata is stored in the parent run directory.
+The task directory contains the full result, canonical structured report, attempt-scoped reports and lifecycle markers, task metadata, system prompt, and persistent Pi session. Run-level metadata is stored in the parent run directory.
 
 ## Configuration and personas
 

package/packages/herdr-subagents/TESTING.md

@@ -27,7 +27,9 @@
 - Verify selected active/queued run cancellation, blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, idempotent missing-tab cleanup, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify `status(runId)` isolates one run, projects queue-only state, prefers durable state over a stale queue record, exposes blocked questions, marks terminal states settled, rejects unknown IDs, and leaves full `history` semantics unchanged.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
+- Simulate a false screen-settled return while the authoritative Pi lifecycle remains working, then write the report later and verify the task completes without a transient failed state.
+- Verify reports are bound to unique attempt IDs, blocked results are not tool errors, duplicate blocked responses are serialized, mixed failed/cancelled aggregates remain partial, and cleanup failures never overwrite business outcomes.
 
 ## Latest baseline
 
-All 179 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases plus the extension-contract lifecycle simulations must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 194 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, lifecycle, attempt-isolation, and persona cases plus the extension-contract lifecycle simulations must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed a read-only package inspection with matching durable attempt/report IDs and automatic tab cleanup.

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

@@ -1,10 +1,12 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import net from "node:net";
+import { dirname, 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";
+import { resultPathForAttemptId } from "../src/result-path.ts";
 import { PARENT_PANE_ENV } from "../src/live-agent.ts";
+import { attemptReportPath, attemptStatePath, requireAttemptId, type AttemptState } from "../src/attempts.ts";
 
 const RETURN_SHORTCUT = "alt+p";
 
@@ -33,12 +35,52 @@ const ReportParams = Type.Object({
 });
 
 function writeAtomic(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 	const temporary = `${path}.tmp-${process.pid}`;
 	writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
 	renameSync(temporary, path);
 }
 
+function currentAttemptId(taskDirectory: string): string {
+	const task = JSON.parse(readFileSync(resolve(taskDirectory, "task.json"), "utf8")) as { currentAttemptId?: unknown };
+	return requireAttemptId(task.currentAttemptId);
+}
+
+function writeAttemptState(taskDirectory: string, attemptId: string, state: AttemptState): void {
+	writeAtomic(attemptStatePath(taskDirectory, attemptId), `${JSON.stringify({ attemptId, state, at: new Date().toISOString() }, null, 2)}\n`);
+}
+
+let herdrReportSeq = Date.now() * 1000;
+
+function reportHerdrState(state: "working" | "blocked" | "idle", message?: string): void {
+	const socketPath = process.env.HERDR_SOCKET_PATH;
+	const paneId = process.env.HERDR_PANE_ID;
+	if (process.env.HERDR_ENV !== "1" || !socketPath || !paneId) return;
+	const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+	const socket = net.createConnection(endpoint);
+	socket.on("error", () => undefined);
+	socket.on("connect", () => socket.end(`${JSON.stringify({ id: `herdr:subagent:${Date.now()}:${Math.random().toString(36).slice(2)}`, method: "pane.report_agent", params: { pane_id: paneId, source: "herdr:pi", agent: "pi", state, message, seq: ++herdrReportSeq } })}\n`));
+}
+
 export default function (pi: ExtensionAPI) {
+	let activeAttemptId: string | undefined;
+	let blockedCount = 0;
+	pi.on("before_agent_start", async () => {
+		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
+		if (!taskDirectory) return;
+		activeAttemptId = currentAttemptId(taskDirectory);
+		writeAttemptState(taskDirectory, activeAttemptId, "working");
+	});
+	pi.on("agent_start", () => reportHerdrState("working"));
+	pi.on("agent_settled", (_event, ctx) => {
+		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
+		if (taskDirectory && activeAttemptId) writeAttemptState(taskDirectory, activeAttemptId, "settled");
+		if (ctx?.isIdle?.() === true) reportHerdrState("idle");
+	});
+	pi.events.on("herdr:blocked", (data: { active?: boolean; label?: string }) => {
+		blockedCount = Math.max(0, blockedCount + (data?.active ? 1 : -1));
+		reportHerdrState(blockedCount > 0 ? "blocked" : "working", blockedCount > 0 ? data?.label : undefined);
+	});
 	pi.registerCommand("parent", {
 		description: "Return focus to the parent Agent pane",
 		async handler(_args, ctx) { await returnToParent(pi, ctx); },
@@ -58,12 +100,9 @@ export default function (pi: ExtensionAPI) {
 		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");
+			const attemptId = activeAttemptId ?? currentAttemptId(taskDirectory);
 			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 });
+			const resultPath = resultPathForAttemptId(taskDirectory, attemptId);
 			writeAtomic(resultPath, params.result);
 			const documents = (params.documents ?? []).map((document) => ({
 				path: resolve(process.cwd(), document.path),
@@ -73,6 +112,7 @@ export default function (pi: ExtensionAPI) {
 				documents.unshift({ path: resultPath, description: "Complete task result" });
 			}
 			const report = {
+				attemptId,
 				status: params.status,
 				summary: params.summary,
 				documents,
@@ -80,7 +120,7 @@ export default function (pi: ExtensionAPI) {
 				...(params.question ? { question: params.question } : {}),
 				reportedAt: new Date().toISOString(),
 			};
-			writeAtomic(resolve(taskDirectory, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+			writeAtomic(attemptReportPath(taskDirectory, attemptId), `${JSON.stringify(report, null, 2)}\n`);
 			return {
 				content: [{ type: "text" as const, text: `${params.status}: ${params.summary}` }],
 				details: report,

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

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

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+const ATTEMPT_ID = /^[a-f0-9-]{36}$/i;
+
+export type AttemptState = "working" | "settled";
+
+export function createAttemptId(): string { return randomUUID(); }
+
+export function requireAttemptId(value: unknown): string {
+	if (typeof value !== "string" || !ATTEMPT_ID.test(value)) throw new Error("Subagent attempt has no valid attempt ID.");
+	return value;
+}
+
+export function attemptReportPath(taskDirectory: string, attemptId: string): string {
+	return join(taskDirectory, "reports", `${requireAttemptId(attemptId)}.json`);
+}
+
+export function attemptStatePath(taskDirectory: string, attemptId: string): string {
+	return join(taskDirectory, "attempts", `${requireAttemptId(attemptId)}.json`);
+}

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

@@ -13,7 +13,7 @@ import { RunPaneAllocator } from "./run-pane-allocator.ts";
 import { applyReport, applyTaskStatus, projectTaskActivity, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskActivity, 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 { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
 import { isAbortError } from "./errors.ts";
 
 export interface BatchTask {
@@ -150,6 +150,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				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;
+				context.taskRecord.currentAttemptId = prompted.attemptId;
 				report = prompted.report;
 				status = applyReport(context.taskRecord, report);
 			} catch (error) {
@@ -190,9 +191,10 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 		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." : blocked ? `${blocked.name} needs input: ${blocked.question}` : failed ? `${tasks.length - failed}/${tasks.length} tasks completed; ${failed} failed.` : `${tasks.length}/${tasks.length} tasks completed.`;
+		const completed = settledResults.filter((result) => result.status === "completed").length;
+		const cancelled = settledResults.filter((result) => result.status === "cancelled").length;
+		const status = aggregateTaskStatus(activity.map((entry) => entry.status)) as BatchResult["status"];
+		const summary = status === "cancelled" ? "Subagent batch cancelled." : blocked ? `${blocked.name} needs input: ${blocked.question}` : status === "partial" ? `${completed}/${tasks.length} tasks completed; ${failed} failed; ${cancelled} cancelled.` : failed ? `${completed}/${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 };
@@ -203,19 +205,11 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 	} 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) => 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;
-			}
+			await cleanupRunTab({
+				herdr, tabId, runFile, runRecord, signal: options.signal,
+				errorPrefix: "Task results settled, but Herdr tab cleanup failed",
+				onError: (message) => options.onCleanupError?.(message),
+			});
 		}
 	}
 }

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

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
-import { mkdir, rename } from "node:fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { continueQueuedRun } from "./continue-run.ts";
@@ -7,7 +8,7 @@ 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 { isProcessAlive, ownerRecord } from "./ownership.ts";
 import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
 import { applyReport, applyTaskStatus, isActiveStatus, persistFailureReport, projectTaskActivity, readReport, readRunRecord, readTaskRecord, readTurnRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskActivity, type TaskRecord, type TaskStatus, type TurnRecord } from "./records.ts";
 import { isAbortError } from "./errors.ts";
@@ -32,6 +33,36 @@ export interface ResumeBlockedResult {
 	tabId?: string;
 }
 
+interface ResponseLock { token?: string; processId?: unknown; sessionId?: unknown; createdAt?: unknown; }
+
+async function readResponseLock(lockFile: string): Promise<ResponseLock | undefined> {
+	try {
+		const lock = JSON.parse(await readFile(lockFile, "utf8")) as unknown;
+		return lock && typeof lock === "object" ? lock as ResponseLock : undefined;
+	} catch { return undefined; }
+}
+
+async function releaseResponseLock(lockFile: string, token: string): Promise<void> {
+	if ((await readResponseLock(lockFile))?.token !== token) return;
+	try { await unlink(lockFile); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+
+async function acquireResponseLock(lockFile: string, runId: string, owner?: OwnerIdentity): Promise<string> {
+	const token = randomUUID();
+	try {
+		await writeFile(lockFile, `${JSON.stringify({ token, processId: process.pid, sessionId: owner?.sessionId, createdAt: new Date().toISOString() })}\n`, { flag: "wx", mode: 0o600 });
+		return token;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		const lock = await readResponseLock(lockFile);
+		if (lock && Number.isInteger(lock.processId) && !isProcessAlive(lock.processId)) {
+			throw new Error(`Subagent run '${runId}' has a stale blocked-response lock from process ${lock.processId}; remove ${lockFile} and retry.`);
+		}
+		throw new Error(`Subagent run '${runId}' already has a blocked response in progress (lock: ${lockFile}).`);
+	}
+}
+
 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"))));
@@ -71,7 +102,7 @@ async function projectSettledRun(runDirectory: string, runFile: string, run: Run
 	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" });
+	if (runStatus !== "blocked" && run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, onError: onCleanupError });
 	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) => projectTaskActivity(entry, index));
 	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 ?? "") }));
@@ -79,11 +110,18 @@ async function projectSettledRun(runDirectory: string, runFile: string, run: Run
 }
 
 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 lockFile = join(runDirectory, ".respond.lock");
+	const lockToken = await acquireResponseLock(lockFile, runId, options.owner);
+	try { return await respondToBlockedTaskLocked(cwd, runId, answer, runDirectory, options); }
+	finally { await releaseResponseLock(lockFile, lockToken); }
+}
+
+async function respondToBlockedTaskLocked(cwd: string, runId: string, answer: string, runDirectory: string, options: RespondToBlockedTaskOptions): Promise<ResumeBlockedResult> {
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const { taskNumber, signal, onCleanupError } = options;
 	const runFile = join(runDirectory, "run.json");
 	const run = await readRunRecord(runFile);
 	const taskDirectories = readdirSync(join(runDirectory, "tasks")).sort().map((entry) => join(runDirectory, "tasks", entry));
@@ -131,7 +169,9 @@ export async function respondToBlockedTask(cwd: string, runId: string, answer: s
 	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;
+		const prompted = 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.`) });
+		task.currentAttemptId = prompted.attemptId;
+		report = prompted.report;
 		status = applyReport(task, report);
 	} catch (error) {
 		attemptError = error;
@@ -158,7 +198,7 @@ export async function respondToBlockedTask(cwd: string, runId: string, answer: s
 				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" });
+			if (run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal, onError: onCleanupError });
 			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() });

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

@@ -48,7 +48,9 @@ export async function continueQueuedRun(runDirectory: string, herdr: HerdrAutoma
 			Object.assign(task, { tabId: run.tabId, paneId, paneLabel, agentName, attempt: Number(task.attempt ?? 0) + 1, startedAt: new Date().toISOString() });
 			await writeJsonAtomic(taskFile, task);
 			await options.onUpdate?.();
-			const report = (await promptLiveAgent({ herdr, task: { ...task, id: task.id, sessionFile: task.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: join(directory, "system-prompt.md"), agentName, signal: options.signal, stalledWarningMs: run.stalledWarningSeconds ? Number(run.stalledWarningSeconds) * 1000 : undefined, onStalled: () => options.onStalled?.(`${task.name ?? task.agent} appears stalled; it is still running.`) })).report;
+			const prompted = await promptLiveAgent({ herdr, task: { ...task, id: task.id, sessionFile: task.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: join(directory, "system-prompt.md"), agentName, signal: options.signal, stalledWarningMs: run.stalledWarningSeconds ? Number(run.stalledWarningSeconds) * 1000 : undefined, onStalled: () => options.onStalled?.(`${task.name ?? task.agent} appears stalled; it is still running.`) });
+			task.currentAttemptId = prompted.attemptId;
+			const report = prompted.report;
 			applyReport(task, report);
 		} catch (error) {
 			await settleAttemptFailure(task, reportFile, {
@@ -79,9 +81,9 @@ export async function continueQueuedRun(runDirectory: string, herdr: HerdrAutoma
 		}
 	}
 	const statuses = await Promise.all(taskDirectories.map(async (directory) => (await readTaskRecord(join(directory, "task.json"))).status));
-	applyRunStatus(run, options.signal?.aborted ? "cancelled" : aggregateTaskStatus(statuses));
+	applyRunStatus(run, aggregateTaskStatus(statuses));
 	await writeJsonAtomic(runFile, run);
 	if (options.cleanup !== false && run.status !== "blocked" && run.tabId) {
-		await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal: options.signal, onError: options.onCleanupError, failureStatus: "failed" });
+		await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal: options.signal, onError: options.onCleanupError });
 	}
 }

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

@@ -161,7 +161,9 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 			]);
 			const runningActivity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
 			options.onUpdate?.({ runId, label: run.label, status: "running", summary: `${historical.name} is continuing.`, documents: [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity: runningActivity });
-			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;
+			const prompted = 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.`) });
+			task.currentAttemptId = prompted.attemptId;
+			report = prompted.report;
 			status = applyReport(task, report);
 		} catch (error) {
 			const settled = await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
@@ -183,7 +185,7 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		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" });
+			await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError });
 		}
 		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
 		return { runId, label: run.label, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity };
@@ -210,7 +212,7 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		]);
 		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
 		options.onUpdate?.({ runId, label: run.label, status, summary: report.summary, documents: report.documents, tabId: tab?.tabId ?? "", paneId: tab?.paneId ?? "", sessionFile: historical.sessionFile, activity });
-		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
+		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError });
 		throw error;
 	}
 }

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

@@ -1,10 +1,12 @@
 import { existsSync } from "node:fs";
-import { readFile, rm } from "node:fs/promises";
+import { mkdir, readFile, rename } 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";
+import { attemptReportPath, attemptStatePath, createAttemptId, type AttemptState } from "./attempts.ts";
+import { writeJsonAtomic } from "./state.ts";
 
 export interface LiveTaskRecord {
 	id: string;
@@ -15,6 +17,7 @@ export interface LiveTaskRecord {
 	thinking?: string;
 	tools?: string[];
 	skills?: string[];
+	currentAttemptId?: string;
 }
 
 export const PARENT_PANE_ENV = "PI_HERDR_SUBAGENTS_PARENT_PANE_ID";
@@ -61,10 +64,17 @@ export async function promptLiveAgent(options: {
 	start?: boolean;
 	stalledWarningMs?: number;
 	onStalled?: () => void;
-}): Promise<{ report: HerdrSubagentsReport; agentName: string }> {
+}): Promise<{ report: HerdrSubagentsReport; agentName: string; attemptId: string }> {
 	const taskDirectory = dirname(options.task.sessionFile);
 	const reportFile = join(taskDirectory, "report.json");
-	await rm(reportFile, { force: true });
+	const taskFile = join(taskDirectory, "task.json");
+	const attemptId = createAttemptId();
+	const attemptReportFile = attemptReportPath(taskDirectory, attemptId);
+	const attemptStateFile = attemptStatePath(taskDirectory, attemptId);
+	await Promise.all([mkdir(dirname(attemptReportFile), { recursive: true, mode: 0o700 }), mkdir(dirname(attemptStateFile), { recursive: true, mode: 0o700 })]);
+	const durableTask = JSON.parse(await readFile(taskFile, "utf8")) as Record<string, unknown>;
+	durableTask.currentAttemptId = attemptId;
+	await writeJsonAtomic(taskFile, durableTask);
 	const agentName = options.agentName ?? liveAgentName(options.task.id, options.attempt);
 	if (options.start !== false) {
 		await options.herdr.startAgent({
@@ -80,18 +90,50 @@ export async function promptLiveAgent(options: {
 	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)) {
+	while (!existsSync(attemptReportFile)) {
+		let state: AttemptState | undefined;
+		if (existsSync(attemptStateFile)) {
+			try {
+				const value = JSON.parse(await readFile(attemptStateFile, "utf8")) as { attemptId?: unknown; state?: unknown };
+				if (value.attemptId === attemptId && (value.state === "working" || value.state === "settled")) state = value.state;
+			} catch { /* a concurrent atomic replacement will be retried */ }
+		}
+		if (state === "working") {
+			try {
+				if (!(await options.herdr.isTaskRunning(options.paneId, options.signal))) {
+					if (promptError) throw promptError;
+					throw new Error("Child Pi stopped while its authoritative attempt state was still working and did not submit a subagent_report.");
+				}
+			} catch (error) {
+				if (error === promptError || (error instanceof Error && error.message.startsWith("Child Pi stopped while"))) throw error;
+				// A transient liveness query is not evidence that the child stopped.
+			}
+			await new Promise<void>((resolve, reject) => {
+				const onAbort = () => { clearTimeout(timer); reject(options.signal?.reason ?? new Error("Subagent attempt aborted.")); };
+				const timer = setTimeout(() => { options.signal?.removeEventListener("abort", onAbort); resolve(); }, 100);
+				if (options.signal?.aborted) onAbort();
+				else options.signal?.addEventListener("abort", onAbort, { once: true });
+			});
+			continue;
+		}
 		if (promptError) throw promptError;
-		throw new Error("Child Pi settled but did not submit a subagent_report.");
+		throw new Error(state === "settled" ? "Child Pi settled but did not submit a subagent_report." : "Child Pi stopped without an authoritative lifecycle state and did not submit a subagent_report.");
 	}
 	let value: unknown;
-	try { value = JSON.parse(await readFile(reportFile, "utf8")); }
+	try { value = JSON.parse(await readFile(attemptReportFile, "utf8")); }
 	catch {
+		await rename(attemptReportFile, `${reportFile}.invalid-${Date.now()}`).catch(() => undefined);
 		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 }; }
+	try {
+		const report = parseReport(value, "child subagent_report") as HerdrSubagentsReport;
+		if (report.attemptId !== attemptId) throw new Error(`Report belongs to attempt '${report.attemptId ?? "unknown"}', expected '${attemptId}'.`);
+		await writeJsonAtomic(reportFile, report);
+		return { report, agentName, attemptId };
+	}
 	catch (error) {
+		await rename(attemptReportFile, `${reportFile}.invalid-${Date.now()}`).catch(() => undefined);
 		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/reconcile.ts

@@ -6,6 +6,7 @@ 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";
+import { attemptReportPath } from "./attempts.ts";
 
 
 export interface CancellationResult { cancelledRuns: number; cleanupErrors: string[]; }
@@ -109,24 +110,34 @@ export async function reconcileSubagentRuns(cwd: string, herdr: HerdrAutomation,
 				continue;
 			}
 			if (isActiveStatus(task.status)) {
-				const reportFile = join(tasksDirectory, taskEntry, "report.json");
-				if (existsSync(reportFile) && (task.status === "running" || task.status === "starting")) {
+				let recoveredCurrentReport = false;
+				const canonicalReportFile = join(tasksDirectory, taskEntry, "report.json");
+				let currentAttemptReport: string | undefined;
+				if (task.currentAttemptId) {
+					try { currentAttemptReport = attemptReportPath(join(tasksDirectory, taskEntry), task.currentAttemptId); }
+					catch (error) { result.cleanupErrors.push(`Invalid current attempt for Subagent task ${taskFile}: ${error instanceof Error ? error.message : String(error)}`); }
+				}
+				// Once an attempt is identified, the canonical report is only history from
+				// an earlier attempt until this attempt publishes its scoped report.
+				const reportFile = task.currentAttemptId ? currentAttemptReport : canonicalReportFile;
+				if (reportFile && existsSync(reportFile) && (task.status === "running" || task.status === "starting")) {
 					try {
 						const report = await readReport(reportFile);
+						if (task.currentAttemptId && report.attemptId !== task.currentAttemptId) throw new Error(`Report attempt '${report.attemptId ?? "unknown"}' does not match current attempt '${task.currentAttemptId}'.`);
 						applyReport(task, report, report.reportedAt ?? new Date().toISOString());
+						recoveredCurrentReport = reportFile !== canonicalReportFile;
+						if (reportFile !== canonicalReportFile) await writeJsonAtomic(canonicalReportFile, report);
 						result.settledTasks += 1;
 					} catch (error) {
 						const detail = error instanceof Error ? error.message : String(error);
 						result.cleanupErrors.push(`Invalid Subagent report ${reportFile}: ${detail}`);
-						await persistFailureReport(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;
-						}
+						await persistFailureReport(canonicalReportFile, { status: "failed", summary: "Recovered task had an invalid structured report.", documents: [], error: detail, reportedAt: new Date().toISOString() }, reportFile !== canonicalReportFile);
+						applyTaskStatus(task, "failed", { error: `Invalid structured report: ${detail}` });
+						result.settledTasks += 1;
+						result.interruptedTasks += 1;
 					}
 				}
-				if (differentOwner && isActiveStatus(task.status)) {
+				if (differentOwner && isActiveStatus(task.status) && !(recoveredCurrentReport && task.status === "blocked")) {
 					applyTaskStatus(task, "cancelled", { error: "Owning parent Pi session is no longer active." });
 					result.cancelledTasks += 1;
 					result.interruptedTasks += 1;
@@ -158,8 +169,8 @@ export async function reconcileSubagentRuns(cwd: string, herdr: HerdrAutomation,
 			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 });
+		if (!statuses.some((status) => status === "running" || status === "starting")) {
+			applyRunStatus(run, aggregateTaskStatus(statuses));
 			await writeJsonAtomic(runFile, run);
 			if (differentOwner || run.status === "cancelled") await closeRunTab(run, runFile, herdr, result.cleanupErrors);
 		}