@maxiaochao/pi-toolkit 0.10.21 → 0.10.23

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-12 - v0.10.23
+
+- bundle herdr-subagents v0.4.9: Stabilize concurrency checks on slower CI runners.
+## 2026-10-12 - v0.10.22
+
+- bundle herdr-subagents v0.4.8: make blocking behave identically in serial and parallel runs and let respond continue a named failed task from its saved session
+- bundle Herdr Subagents runtime telemetry and concurrent historical-resume lifecycle fixes without conflating Herdr UI blocking with business blocking
+- bundle Herdr Subagents failed-task continuation: answer a named failed task from its saved Pi session while its batch still runs, without closing shared tabs or restarting queued siblings
+- bundle the Herdr Subagents three-outcome child contract (`completed`, `blocked`, `failed`): blocking now works identically in serial and parallel runs, keeps queued work with the batch that owns it, and always needs an explicit task number to answer
+
 ## 2026-10-10 - v0.10.21
 
 - bundle herdr-subagents v0.4.7: fix blocked-run scheduling and limit interactive blocking to serial runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "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,25 @@
+## 2026-10-12 - v0.4.9
+
+- Stabilize concurrency checks on slower CI runners.
+## 2026-10-12 - v0.4.8
+
+- make blocking behave identically in serial and parallel runs and let respond continue a named failed task from its saved session
+- add durable Herdr runtime telemetry without treating UI `blocked` as business blocked; preserve late reports after delivery-unknown prompt timeouts and fail only explicit terminal paths without a valid report
+- allow different historical tasks in one run to resume concurrently in a shared tab while fencing task writers, aggregate state, and final cleanup
+- reserve `retrying` display support without fabricating retries from ambiguous Pi lifecycle events
+- remove the unreachable single-task execution path so every task settles through the batch runner; legacy top-level prompts are still normalized into one-item task arrays
+- settle a batch through the run lock so a concurrent writer's `run.json` changes are no longer overwritten from a stale in-memory copy
+- let `respond` continue an explicitly named failed task from its saved Pi session, reusing its live pane when one survives, while its batch is still running
+- keep a settling batch from finishing the run or closing its tab while a continued task is still working, and from restarting queued siblings it still owns
+- claim a continued task before any pane work so a sibling that settles first cannot close the tab the continuation is about to use
+- report a still-queued sibling as running work instead of inventing an input request with no question
+- require the task number on every `respond` so an answer never selects a task implicitly
+- rename the child report status `needs-input` to `blocked` and reduce the child contract to `completed`, `blocked`, and `failed`
+- let a task block at any concurrency instead of downgrading concurrent input requests to `missing_input` failures, and drop `failureKind`/`requiredInput`
+- give a batch sole ownership of its queued tasks so answering one blocked lane can no longer start a queued sibling the batch is about to run
+- settle a batch against the task records for any lane that was answered while its siblings were still running, instead of reporting a stale question and keeping its tab open
+- settle a continued run's status through the run lock instead of overwriting it from a stale copy
+
 ## 2026-10-10 - v0.4.7
 
 - fix blocked-run scheduling and limit interactive blocking to serial runs

package/packages/herdr-subagents/README.md

@@ -78,21 +78,29 @@ The snapshot reports the aggregate run state and every task's state, including a
 
 Run controls accept the complete run UUID, the saved run-directory name, or any unique UUID prefix. Results always return the canonical complete UUID.
 
-A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the control tool to continue the original session:
+Every child reports exactly one of three outcomes. `completed` and `failed` are terminal; `blocked` means the child is still alive in its pane but needs the parent agent to answer or decide something before it can go on. A blocked task keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent with an exact question. Answer through the control tool to continue the original session:
 
 ```text
-herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+herdr_subagents_control({ action: "respond", runId: "<run-id>", task: 1, 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.
 
-Blocking is limited to effectively serial runs (`effectiveConcurrency: 1`), where task order can depend on the answer. In a concurrent read-only run, tasks must be independent: a task that requests input is recorded as `failed` with `failureKind: "missing_input"` and `requiredInput`, while its independent siblings continue. This prevents a blocked concurrent task from holding the parent tool call behind unrelated long-running siblings.
+Blocking works the same way at any concurrency: a blocked task never holds up its independent siblings, which keep running and settling normally. A blocked run does keep the dispatcher slot until you respond or cancel it, so another foreground run started meanwhile is refused with the blocking run ID and a background run stays queued. That is what keeps a second write-capable run from editing the repository behind an unanswered question.
 
-Only work owned by the current parent session's main dispatcher can remain blocked. Historical follow-ups that need more input settle as `missing_input` failures, and startup reconciliation cancels blocked work whose parent session disappeared; neither path creates an unowned blocked run.
+A failed task is not a dead end. Name it explicitly to continue its original Pi session with another message, even while the rest of its batch is still running:
+
+```text
+herdr_subagents_control({ action: "respond", runId: "<run-id>", task: 2, answer: "Use the staging credentials and retry." })
+```
+
+The task resumes in its own live pane when that pane still hosts its child, and otherwise restarts from the saved session in a new pane. `task` is always required so an answer never picks a task implicitly. A task whose child never produced a saved Pi session cannot be continued and says so; submit a new run instead. Continuing a failed task never starts its batch's queued siblings, which the running batch still owns. While a continued task is working, its run stays `running` and its Herdr tab stays open even if the batch that created it has already settled.
+
+Blocked work always belongs to a live parent session. A historical follow-up may block too, keeping its shared resume tab until you answer it. Startup reconciliation cancels blocked work whose parent session disappeared, so no blocked run is ever left without an owner.
 
 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.
+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, business status or current runtime telemetry, 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. Herdr `blocked` is shown neutrally as `waiting_interaction` while the task remains `running`; only a child `subagent_report` with `status=blocked` makes the business task `blocked`. Prompt-delivery timeouts appear as `delivery_unknown` while a working live child is still allowed to publish its authoritative report. 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.
 
 With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback. Inside every child Agent, press `Alt+P` or run `/parent` to return to the exact parent Agent pane; the shortcut is also shown in the child footer.
 
@@ -100,7 +108,7 @@ With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a tas
 
 Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list the full compact project-local run and task archive after Herdr tabs close. History does not accept a run ID and is not a status interface. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
 
-Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents_control({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
+Continue a saved conversation with `herdr_subagents_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Different settled tasks from the same run may resume concurrently in distinct panes of one shared resume tab; the same task remains single-writer and rejects a second resume. Remove only a selected archive with `herdr_subagents_control({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
 
 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.
 
@@ -112,7 +120,7 @@ Foreground calls wait until all children report completion or a request for inpu
 
 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
+- `completed`, `blocked`, or `failed` status
 - a concise summary
 - paths to useful documents
 - the task-record location
@@ -299,7 +307,7 @@ Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents s
 
 Queued background submissions are persisted before dispatch. Closing the parent Pi session cancels queued, running, and blocked work, records `cancelled`, and closes the owned run tab. On the next Pi start, stale active records and queued submissions from a prior parent session are reconciled to a terminal state, including when Pi reused the same process, and leaked tabs are cleaned up when possible. Missing, truncated, or structurally invalid child reports become explicit failures or cancellation diagnostics; recovery errors are reported without leaving new submissions paused.
 
-Tab, pane, and child startup commands are not automatically retried: an error may arrive after Herdr already created the resource. A failure after prompt submission is preserved and never automatically rerun. Historical follow-ups exclude concurrent resumes of the same run with an atomic `.resume.lock` directory; if Pi crashes without releasing it, confirm no Agent is still using that run before removing the lock manually. `stalledWarningSeconds` emits a warning without killing long-running work. Run/task/report snapshots use atomic replacement so interruption cannot expose half-written JSON.
+Tab, pane, and child startup commands are not automatically retried: an error may arrive after Herdr already created the resource. Recovery is best effort, not complete: Herdr 0.9.2 has no idempotency key for tab creation or pane splitting, so a `SIGKILL` after the external resource is created but before its ID is durably persisted can leave an orphan that cannot be identified for cleanup. A failure after prompt submission is preserved and never automatically rerun. Historical follow-ups use a recoverable task-scoped `.resume.lock`, so different tasks can continue concurrently without allowing two writers for one saved session. Herdr exposes no retrying state, and Pi exposes no reliable public auto-retry hook, so `retrying` is supported by the runtime schema and Fleet but is not fabricated from ambiguous lifecycle events. `stalledWarningSeconds` emits a warning without killing long-running work. Run/task/report snapshots use atomic replacement so interruption cannot expose half-written JSON.
 
 The child does not inherit parent extensions, parent conversation, or unconfigured skills, but normal project context files still apply. It uses the same Pi installation, provider configuration, model catalog, and credentials as the parent.
 

package/packages/herdr-subagents/RESUME-LIFECYCLE-DESIGN.md

@@ -0,0 +1,84 @@
+# Historical resume and Herdr lifecycle design
+
+## Invariants
+
+- A task session has one writer. `tasks/<task>/.resume.lock` is held for the whole
+  historical turn, so a second resume of that task fails immediately.
+- Different settled tasks in one run may resume concurrently. They share one new
+  resume tab and each owns a distinct pane.
+- `run.json` is changed only while holding the short-lived `run/.state.lock`.
+  The lock covers shared tab allocation, active-resume membership, aggregate
+  status, and final cleanup ownership; it never covers an Agent turn.
+- A structured `subagent_report` is the authority for business completion,
+  failure, or `needs-input`. Herdr UI state is runtime telemetry only.
+
+## Durable resume state
+
+`run.json.resume` contains the shared resume tab identity and an `active` map
+from task id to pane, generation, attempt, owner identity/token, and phase. The
+first entrant creates the tab while holding the run lock and uses its root pane.
+Later entrants split a pane in that tab. Allocation is first persisted as
+`allocating`; after task/turn records durably identify the attempt it advances to
+`running`. Reconciliation can therefore fail an abandoned allocation or promote
+a fully persisted attempt after a crash at either boundary.
+
+When a turn settles, its task/report/turn are persisted first. Under the run
+lock, the task is then removed from `resume.active`, all task files are read to
+derive the run status, and the caller that observes an empty map claims final
+tab cleanup. A failed turn removes only itself; siblings keep running. A
+`needs-input` turn stays represented by its blocked task/pane until `respond`
+settles it. Tab cleanup occurs only when no resume task is running or blocked.
+
+The run lock prepares its owner metadata in a private directory and atomically
+publishes the complete lock directory. Contenders wait with abort support. A
+legacy ownerless initialization has an explicit expiry lease and is reclaimed
+only after directory-identity revalidation; a dead-owner lock is atomically
+renamed away before retry. Task locks use the same stale-owner recovery but
+contention is reported instead of waited on.
+
+## Recovery and cancellation
+
+Reconciliation validates each `resume.active` member against its attempt and
+task record: dead panes/processes become failed or cancelled using the existing
+attempt failure rules, stale members are removed under the run lock, and the
+last remover atomically claims the generation's tab cleanup. Cancellation is
+member-scoped by owner and attempt, so one parent cannot cancel a sibling
+owner's turn. Every `run.json` reconciliation/cancellation update is a locked
+read-modify-write.
+
+This recovery is best effort, not complete. Herdr 0.9.2 provides no idempotency
+key for tab creation or pane splitting. If the process receives `SIGKILL` after
+Herdr creates the external resource but before its ID is durably persisted, the
+resource cannot be identified by this state machine and may remain orphaned.
+
+## Herdr runtime projection
+
+`agent prompt --wait` can return `idle`, `done`, or `blocked`; `agent get` exposes
+`working`, `blocked`, `idle`, `done`, or `unknown`. While a prompt is pending we
+poll that state and persist/emit a separate runtime state:
+
+- `working` -> `working`
+- `blocked` -> `waiting_interaction` (Task remains `running`)
+- `agent_prompt_stalled`/timeout -> `delivery_unknown`; while the attempt state
+  is `working` and the child process is alive, wait for its report and never resend
+- `idle`/`done` with a valid report -> use the report's business terminal state
+- `idle`/`done` without a report after a short file-publication grace -> Task `failed`
+- prompt/process/API terminal error without a valid report -> Task `failed`
+- `agent get` query failure -> diagnostic only; continue waiting for report or
+  independent pane/process evidence
+
+When a scoped report appears, its waiter aborts and explicitly awaits the
+outstanding `agent prompt --wait` command before returning. Runtime writes
+revalidate the current attempt and active task status, so late transport
+telemetry cannot overwrite a report-derived terminal state.
+
+Herdr's `blocked` is not converted to business Task `blocked`; only a valid
+`subagent_report(status="needs-input")` does that. Runtime state, pane id, and a
+short diagnostic are exposed in task records, activity, and Fleet without replacing
+Task status.
+
+`retrying` is reserved in the runtime schema and Fleet renderer but is not emitted
+by the current child extension. Herdr has no retrying state, and Pi's public
+extension lifecycle does not expose an auto-retry hook or a reliable `willRetry`
+field. Inferring it from `agent_end`/`agent_start` would also label ordinary queued
+continuations as retries, so the implementation deliberately does not fabricate it.

package/packages/herdr-subagents/TESTING.md

@@ -18,7 +18,9 @@
 - Shut down the parent while a handed-off sibling is active and verify it is cancelled and joined, durable queue state is removed, and no stale follow-up is sent.
 - Verify all-success foreground batches still wait for every task and explicit `background: true` submissions still return immediately.
 - Verify a blocked dispatcher owner immediately rejects both newly submitted and already-queued foreground runs with its full run ID, keeps explicit background runs queued, and removes queued foreground runs when their caller cancels.
-- Verify only effectively serial runs can block; concurrent input requests settle as structured `missing_input` failures, including owner-loss reconciliation, while independent siblings continue.
+- Verify a parallel task blocks exactly like a serial one, keeping its question, attempt-scoped report, and tab while an independent sibling completes, that answering it settles and closes the run, and that reconciliation treats a blocked report identically at any concurrency.
+- Verify two lanes of one parallel batch can block at once, that each question is exposed in turn as they are answered, and that the run closes only after the last answer.
+- Answer a blocked lane while a sibling of the same parallel batch is still running and verify the batch keeps sole ownership of its queued tasks, runs them exactly once, and then settles and closes its tab against the task records rather than its own stale blocked snapshot, carrying no lifecycle field the blocked record left behind.
 - Verify historical follow-ups cannot create unowned blocked work and owner-loss reconciliation cancels serial blocked work instead of reconstructing hidden dispatcher ownership.
 - Verify all paths use interactive Agent start/prompt without print mode, shell injection, markers, or pane reuse.
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism, including three concurrent `analyst` tasks with independent task-level models.
@@ -29,10 +31,18 @@
 - Verify live token updates are file-event driven and polled on each running one-second tick, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - 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.
+- Verify historical follow-ups allow different tasks to share one resume tab while preserving one session writer per task, and active resume membership keeps aggregate status running before the sibling task record is persisted.
+- Verify Herdr `blocked` projects only `waiting_interaction`, prompt-delivery timeout projects `delivery_unknown` and accepts a late report, terminal API/process errors without reports fail, and `retrying` remains a display-only running runtime state until a reliable lifecycle source exists.
 - 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.
+- Verify settling a batch merges run state written concurrently under the run lock instead of overwriting `run.json` from a stale in-memory copy.
+- Verify an explicitly named failed task continues from its saved Pi session: it reuses its own live pane while its batch still runs, restarts in a new pane when that pane is gone, refuses to continue without a saved session, is never selected by an unqualified response, and does not start queued siblings that the running batch still owns.
+- Verify a settling batch adopts the task records on disk, so a continued task keeps its run `running` and its Herdr tab open instead of being overwritten by the batch's own stale view.
+- Verify a continuation claims its task before touching any pane, so a sibling continuation that finishes first leaves the shared tab open, and only the last one to settle closes it.
+- Verify a sibling that is still queued is reported as running work rather than as an invented input request with no question.
+- Verify a continued task may ask for input, becomes an ordinary blocked task, and is then answerable without naming its number.
+- Verify `respond` refuses completed, cancelled, queued, running, and nonexistent tasks without touching Herdr or the run record.
 
 ## Latest baseline
 
-All 198 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.
+All 246 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/herdr-subagents.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
-import { Container, Editor, Spacer, Text } from "@earendil-works/pi-tui";
+import { Container, Editor, Text } from "@earendil-works/pi-tui";
 import { loadSubagentConfiguration } from "../src/config.ts";
 import { CliHerdrAutomation, type HerdrAutomation } from "../src/herdr.ts";
 import { activeRunText } from "../src/monitor.ts";
@@ -9,7 +9,7 @@ import { RunDispatcher } from "../src/dispatcher.ts";
 import { historyText, listSubagentHistory } from "../src/history.ts";
 import { cancelQueuedRuns, loadQueuedRuns, persistQueuedRun, removeQueuedRun } from "../src/queued-runs.ts";
 import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
-import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsDetails, type HerdrSubagentsRunParams } from "../src/tool.ts";
+import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsRunParams } from "../src/tool.ts";
 import { HerdrSubagentsControlParams, HerdrSubagentsParams } from "../src/parameters.ts";
 import { HERDR_ACTIONS } from "../src/validation.ts";
 import { FleetController, type FleetWidgetRuntime } from "../src/fleet-controller.ts";
@@ -62,19 +62,6 @@ function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRender
 		for (const task of batch.tasks) container.addChild(new Text(`${statusVisual(task.status).glyph} ${task.name}: ${task.summary}`, 0, 0));
 		return container;
 	}
-	const details = result.details as HerdrSubagentsDetails | undefined;
-	if (details?.agent) {
-		const container = new Container();
-		container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(statusVisual(details.status).color, details.status)}`, 0, 0));
-		container.addChild(new Text(details.summary, 0, 0));
-		if (details.documents.length > 0) {
-			container.addChild(new Spacer(1));
-			for (const document of details.documents) container.addChild(new Text(theme.fg("muted", `${document.description}: ${document.path}`), 0, 0));
-		}
-		if (details.recordDirectory) container.addChild(new Text(theme.fg("dim", `Record: ${details.recordDirectory}`), 0, 0));
-		if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
-		return container;
-	}
 	const content = result.content[0];
 	return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
 }
@@ -195,7 +182,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents",
 		label: "Herdr Subagents",
-		description: "Run one or more ordered tasks in visible interactive Herdr Pi Agents. Use one tasks item for a single task. Independent read-only tasks may run concurrently; write-capable runs are serialized. Only effectively serial runs can pause for input; concurrent input requests become missing_input failures while independent siblings continue. Foreground calls wait for the batch unless a task fails, when the run continues in the background and returns its run ID immediately. Explicit background calls always return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
+		description: "Run one or more ordered tasks in visible interactive Herdr Pi Agents. Use one tasks item for a single task. Independent read-only tasks may run concurrently; write-capable runs are serialized. A task that needs the parent agent to answer or decide something reports blocked at any concurrency, keeps its live pane, and lets its independent siblings continue; answer it with herdr_subagents_control respond, which a blocked run waits for before another foreground run can start. Foreground calls wait for the batch unless a task fails, when the run continues in the background and returns its run ID immediately. Explicit background calls always return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
 		parameters: HerdrSubagentsParams,
 		prepareArguments: normalizeHerdrSubagentsArguments,
@@ -328,7 +315,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents_control",
 		label: "Herdr Subagents Control",
-		description: "Inspect Herdr personas, query one run by ID, list run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use status for one run and history only for the full archive. Use herdr_subagents to start new work.",
+		description: "Inspect Herdr personas, query one run by ID, list run history, cancel active or queued work, answer a blocked task or continue a failed one with respond, resume a saved task, or remove a selected archived run. Continuing a failed task requires its task number and works while the rest of its batch still runs. Use status for one run and history only for the full archive. Use herdr_subagents to start new work.",
 		parameters: HerdrSubagentsControlParams,
 
 		async execute(_toolCallId, params: HerdrSubagentsControlToolParams, signal, onUpdate, ctx) {

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

@@ -23,7 +23,7 @@ async function returnToParent(pi: ExtensionAPI, ctx: { ui: { notify(message: str
 }
 
 const ReportParams = Type.Object({
-	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
+	status: StringEnum(["completed", "blocked", "failed"] as const, { description: "Outcome of this turn. completed: the task is finished. blocked: you have a specific question or decision the parent agent must answer before you can continue, and the run should stay open waiting for it. failed: this task cannot be completed, so the run should not wait for an answer." }),
 	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({
@@ -31,7 +31,7 @@ const ReportParams = Type.Object({
 		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." })),
+	question: Type.Optional(Type.String({ minLength: 1, description: "Exact question for the parent agent when status is blocked." })),
 });
 
 function writeAtomic(path: string, content: string): void {

package/packages/herdr-subagents/package.json

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

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

@@ -3,17 +3,18 @@ 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, normalizeNeedsInputReport, projectTaskActivity, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, projectTaskActivity, readReport, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
 import { reportProtocolPrompt } from "./protocol.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
+import { acquireDirectoryLock, adoptRecord, queueLockPath, withRunStateLock, type DirectoryLock } from "./run-state.ts";
+import { aggregateTasksWithResume, readTaskEntries } from "./resume-state.ts";
 import { isAbortError } from "./errors.ts";
 import { attemptReportPath } from "./attempts.ts";
 
@@ -49,11 +50,9 @@ export interface BatchTaskResult {
 	name: string;
 	status: Exclude<BatchTaskStatus, "queued" | "running">;
 	summary: string;
-	documents: HerdrSubagentsDocument[];
+	documents: PersistedDocument[];
 	error?: string;
 	question?: string;
-	failureKind?: "missing_input";
-	requiredInput?: string;
 	paneId: string;
 	recordDirectory: string;
 	sessionFile: string;
@@ -68,7 +67,7 @@ export interface BatchResult {
 	tasks: BatchTaskResult[];
 	activity: TaskActivity[];
 	summary: string;
-	documents: HerdrSubagentsDocument[];
+	documents: PersistedDocument[];
 	recordDirectory: string;
 	tabId?: string;
 	question?: string;
@@ -132,11 +131,33 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 		tabId = paneAllocator.tabId;
 		return paneId;
 	};
+	// Settling the run must not be cancellable, so the terminal status is never written under options.signal.
+	let settledAggregate: RunStatus | undefined;
+	const persistRunStatus = async (status: BatchResult["status"], lifecycle: { question?: string; error?: string }, force = false) => {
+		settledAggregate = await withRunStateLock(runFile, undefined, async (run) => {
+			let effective: RunStatus = status;
+			try {
+				// Task records are more current than this batch's own view once a follow-up continues a
+				// settled task. A thrown batch still forces its outcome, but never over live work.
+				const observed = aggregateTasksWithResume((await readTaskEntries(runDirectory)).map((entry) => entry.task), run.resume?.active);
+				if (!force || isActiveStatus(observed)) effective = observed;
+			} catch (error) {
+				options.onCleanupError?.(`Could not inspect task records while settling the run; used this batch's own view: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			applyRunStatus(run, effective, lifecycle);
+			adoptRecord(runRecord, run);
+			return effective;
+		});
+	};
 
 	emit("starting", `Starting up to ${effectiveConcurrency} interactive Pi Agent${effectiveConcurrency === 1 ? "" : "s"}...`);
 	let nextIndex = 0;
 	let settled = 0;
+	let queueLock: DirectoryLock | undefined;
 	try {
+		// One batch lane blocking does not stop the others, so this batch keeps starting queued tasks.
+		// Holding the queue lock for its whole life keeps a concurrent response from starting them too.
+		queueLock = await acquireDirectoryLock(queueLockPath(runDirectory), { wait: false });
 		const runOne = async (index: number): Promise<void> => {
 			const task = tasks[index];
 			const context = contexts[index];
@@ -153,11 +174,14 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				await writeJsonAtomic(context.taskFile, context.taskRecord);
 				activity[index] = projectTaskActivity(context.taskRecord, index);
 				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.`) });
+				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.`), onRuntimeUpdate: (updated) => {
+					Object.assign(context.taskRecord, updated);
+					activity[index] = projectTaskActivity(context.taskRecord, index);
+					emit("running", `${settled}/${tasks.length} tasks settled.`);
+				} });
 				agentName = prompted.agentName;
 				context.taskRecord.currentAttemptId = prompted.attemptId;
-				report = normalizeNeedsInputReport(prompted.report, effectiveConcurrency);
-				if (report !== prompted.report) await Promise.all([writeJsonAtomic(context.reportFile, report), writeJsonAtomic(attemptReportPath(context.taskDirectory, prompted.attemptId), report)]);
+				report = prompted.report;
 				status = applyReport(context.taskRecord, report);
 			} catch (error) {
 				const settled = await settleAttemptFailure(context.taskRecord, context.reportFile, {
@@ -170,7 +194,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 			}
 			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 } : {}), ...(report.failureKind ? { failureKind: report.failureKind } : {}), ...(report.requiredInput ? { requiredInput: report.requiredInput } : {}), paneId, recordDirectory: context.taskDirectory, sessionFile: context.sessionFile };
+			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] = projectTaskActivity(context.taskRecord, index);
 			settled += 1;
 			emit("running", `${settled}/${tasks.length} tasks settled.`);
@@ -194,6 +218,24 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				await writeJsonAtomic(contexts[index].taskFile, contexts[index].taskRecord);
 			}
 		}
+		// A response can settle a lane this batch left blocked while its independent siblings were still
+		// running, so adopt the task records before reporting an outcome this batch no longer owns.
+		for (let index = 0; index < results.length; index += 1) {
+			if (results[index]?.status !== "blocked") continue;
+			let latest: TaskRecord;
+			let report: PersistedReport;
+			try { [latest, report] = await Promise.all([readTaskRecord(contexts[index].taskFile), readReport(contexts[index].reportFile)]); }
+			catch { continue; }
+			if (latest.status === "blocked" || isActiveStatus(latest.status)) continue;
+			adoptRecord(contexts[index].taskRecord, latest);
+			activity[index] = projectTaskActivity(contexts[index].taskRecord, index);
+			const previous = results[index];
+			results[index] = {
+				index: previous.index, name: previous.name, status: latest.status as BatchTaskResult["status"],
+				summary: report.summary, documents: report.documents ?? [], ...(report.error ? { error: report.error } : {}),
+				paneId: previous.paneId, recordDirectory: previous.recordDirectory, sessionFile: previous.sessionFile,
+			};
+		}
 		const settledResults = results.filter(Boolean);
 		const blocked = settledResults.find((result) => result.status === "blocked");
 		const failed = settledResults.filter((result) => result.status === "failed").length;
@@ -201,15 +243,14 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 		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);
+		await persistRunStatus(status, { question: blocked?.question });
 		return { ok: status === "completed", status, runId, label: options.label, requestedConcurrency, effectiveConcurrency, tasks: settledResults, activity, summary, documents: settledResults.flatMap((result) => result.documents), recordDirectory: runDirectory, tabId, ...(blocked?.question ? { question: blocked.question, allowedActions: ["respond", "cancel"] } : {}) };
 	} catch (error) {
-		applyRunStatus(runRecord, options.signal?.aborted ? "cancelled" : "failed", { error: error instanceof Error ? error.message : String(error) });
-		await writeJsonAtomic(runFile, runRecord);
+		await persistRunStatus(options.signal?.aborted ? "cancelled" : "failed", { error: error instanceof Error ? error.message : String(error) }, true);
 		throw error;
 	} finally {
-		const keepTab = !options.signal?.aborted && activity.some((entry) => entry.status === "blocked" || entry.status === "queued" || entry.status === "running");
+		await queueLock?.release();
+		const keepTab = !options.signal?.aborted && (activity.some((entry) => entry.status === "blocked" || entry.status === "queued" || entry.status === "running") || (settledAggregate !== undefined && isActiveStatus(settledAggregate)));
 		if (tabId && !keepTab) {
 			await cleanupRunTab({
 				herdr, tabId, runFile, runRecord, signal: options.signal,