@maxiaochao/pi-toolkit 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2026-10-08 - v0.10.3
+
+- bundle herdr-subagents v0.4.0: add the live compact Fleet footer with authoritative metrics and refreshed media
+- Add the responsive below-editor Herdr Fleet monitor with real personas, task states, cumulative active durations, and authoritative child Pi token totals, including event-driven live updates and safe partial-JSONL handling.
+- Color running Fleet rows yellow and completed rows green, compact the shared metrics column instead of pushing it to the terminal edge, and update the published media with focus restoration after capture.
+
+## 2026-10-08 - v0.10.2
+
+- bundle herdr-subagents v0.3.0: split execution and control tools and unify task runs
+- Bundle the Herdr Subagents execution/control tool split and unified non-empty `tasks` input for single and multi-task runs.
+
 ## 2026-10-08 - v0.10.1
 
 - bundle herdr-subagents v0.2.1: add default thinking configuration and inline Herdr workflow video
@@ -178,6 +189,7 @@
 
 ## Unreleased
 
+- redesign bundled Todo as a branch-local execution plan with lifecycle-only model actions, expected-current guards, serialized calls, preserved branch history, and a live current-plan widget
 - let `/cache_export` switch between all history and individual compaction-defined Context segments, defaulting to the latest segment; cache-hit cumulative lines reset at compaction or model boundaries
 - add the independent `@maxiaochao/pi-codex-edit` package with model-aware Codex-style `apply_patch`
 - include the benchmark summary and interactive HTML architecture explainer

package/README.md

@@ -22,7 +22,7 @@ The root package embeds the child-package source snapshots listed below. Install
 
 | Package | Capability | Install | Update |
 |---|---|---|---|
-| [pi-todo](packages/todo/README.md) | Session plans, automatic task advancement, `/todos` | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
+| [pi-todo](packages/todo/README.md) | Branch-local execution plans, guarded advancement, `/todos` history | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
 | [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` |
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
 | [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` |

package/global/AGENTS.md

@@ -4,71 +4,54 @@ Behavioral guidelines to reduce common LLM coding mistakes. Project-specific ins
 
 ## 1. Think Before Coding
 
-**Surface tradeoffs. Name confusion instead of resolving it silently.**
+- Surface material assumptions, interpretations, and tradeoffs.
+- If unresolved ambiguity would materially change the result, ask. When no human is reachable, choose a defensible interpretation, state it, and proceed with verifiable criteria.
+- Prefer the simpler approach. Name conflicting requirements rather than silently compromising between them.
 
-- State your material assumptions explicitly.
-- If multiple interpretations exist, present them rather than picking one silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If requirements conflict (durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
-- When unresolved ambiguity would materially change the result, ask. When no human is reachable (headless, async, subagent), choose the interpretation you can defend, state it as an assumption, and proceed under Rule 4.
+## 2. Minimal Solution
 
-## 2. Simplicity First
+Understand the problem and relevant code flow before choosing the first rung that works:
 
-**YAGNI cuts what you don't need; KISS keeps what remains simple.**
+1. Skip functionality that is speculative or was not requested.
+2. Reuse an existing project abstraction when it encodes the required semantics.
+3. Otherwise use the standard library or a native platform feature.
+4. Otherwise use a direct dependency already declared by the project.
+5. Only then write the minimum custom code that works.
 
-- Build what was asked, for the callers that exist today.
-- Introduce an abstraction after repeated use reveals a stable concept.
+- Introduce abstractions only after repeated use reveals a stable concept.
+- Prefer boring, focused code; review long or deeply nested functions for splitting.
+- Never simplify away explicit requirements, trust-boundary validation, data-loss protection, security, or accessibility.
 - For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
-- Each function you write does one thing. If it runs past a couple of screens or nests past three levels, review whether splitting it improves clarity.
+- State the ceiling and upgrade trigger of any deliberate simplification that cuts a real corner.
 
-## 3. Surgical Changes
+## 3. Skill Boundaries
 
-**Touch only what you must. Clean up only your own mess.**
+After loading a skill, treat its documented interface as sufficient for normal use. Do not inspect the skill's implementation, installed executable, or package source unless the user asks to review, debug, or modify it; its documented behavior conflicts with observed behavior; or required usage details are missing from the skill.
 
-The test: every changed line traces to the user's request, or to a defect that request reveals.
+## 4. Read, Then Change Surgically
 
-- Match existing style, even if you'd do it differently.
-- Remove imports, variables, and functions that YOUR changes made unused. Leave pre-existing dead code in place and mention it.
+Before editing, read the affected public API and its immediate callers. For a bug, find every statically discoverable caller and relevant implementation.
 
-When fixing a bug, fix the root cause, not the symptom. Find where the defect actually lives:
-- Find every statically discoverable caller and relevant implementation; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
-- If the shared function is wrong, fix it once - do not scatter per-caller guards. Name the sibling callers the fix now affects.
-- If one caller is wrong, fix that caller - do not add defensive handling to a correct shared function.
+Every changed line traces to the user's request or to a defect that request reveals.
 
-## 4. Goal-Driven Execution
+- Match existing style.
+- Remove imports, variables, and functions that your changes make unused. Leave pre-existing dead code in place and mention it.
+- Fix a faulty shared function once and name affected sibling callers; if only one caller is wrong, fix that caller instead of guarding a correct shared function.
 
-**Define success criteria. Loop until verified.**
+## 5. Goal-Driven Execution
 
-Transform tasks into verifiable goals:
-- "Add validation" -> "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
-- "Refactor X" -> "Ensure tests pass before and after"
-- "Make X fast" -> "Write and test a simple reference implementation, then optimize against its results"
+- Turn work into checkable outcomes: reproduce bugs before fixing them, preserve behavior during refactors, and optimize against a tested reference implementation.
+- For multi-step or materially ambiguous work, state a brief plan and give every step its own verification.
+- Leave the smallest relevant runnable check for new or changed non-trivial logic. Do not introduce a test framework solely for that check.
 
-For multi-step or materially ambiguous tasks, state a brief plan where every step carries its own check:
-1. [Step] -> verify: [check]
+## 6. Fail Visibly
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-## 5. Read Before You Write
-
-**Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
-
-Before changing a file:
-- Read the file's exports and public API.
-- Read the immediate callers of the function you're modifying.
-
-## 6. Fail Visibly, Not Silently
-
-**Silent skips are failures.**
-
-- "Completed" is wrong if anything was silently skipped.
+- "Completed" is wrong if anything required was silently skipped.
 - "Tests pass" is wrong if any required test was skipped or not run.
-- If a required input, file, or tool is missing (or a step is impossible under the stated constraints), do NOT fabricate it to make a check pass. Report what is missing and what you need.
+- If a required input, file, or tool is missing, or a step is impossible under the stated constraints, report what is missing and what you need. Never fabricate it to make a check pass.
+
+## 7. Worktree Isolation
 
-## 7. Reuse Before Writing
+For a Git-repository task that coordinates substantial changes across multiple files or modules, or implements a feature intended for release, ask before editing whether to isolate it in a worktree. Skip the question when already in a linked worktree.
 
-**Before writing new code, check in order:**
-1. Reuse an existing project abstraction when it encodes project semantics. (If it is itself the bug, fix it once - see Rule 3.)
-2. Otherwise use the standard library or a direct dependency already declared by the project.
-3. Only then write it yourself.
+If the user agrees, read the `pi-worktree` skill and establish the worktree before changing code. When no human is reachable, create a worktree only when the task explicitly requests one.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.1",
-  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
+  "version": "0.10.3",
+  "description": "Personal pi coding agent toolkit: execution plans, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2026-10-08 - v0.4.0
+
+- add the live compact Fleet footer with authoritative metrics and refreshed media
+- Replace the below-editor task list with a compact responsive Fleet monitor showing authoritative persona, task status, cumulative active time, and true child Pi usage from assistant, tool-result, standalone usage, compaction, and branch-summary entries.
+- Update Fleet metrics from child-session file events, repaint elapsed time only while work runs, safely ignore malformed or partial JSONL tails, and dispose every watcher and timer with the widget.
+- Preserve exact-pane keyboard focus while extending blocked-response and historical-resume activity projections with durable timing and session metadata.
+- Use warning/yellow indicators for running Fleet rows and success/green indicators for completed rows, compact the shared metrics column instead of pushing it to the terminal edge, and publish media that demonstrates the live parent footer while restoring focus after capture.
+
+## 2026-10-08 - v0.3.0
+
+- split execution and control tools and unify task runs
+- Split execution and control into `herdr_subagents` and `herdr_subagents_control`; require a non-empty `tasks` array for new runs so one-item runs and batches share background and concurrency semantics.
+- Normalize legacy top-level single-task prompts into one-item task arrays before schema validation.
+
 ## 2026-10-08 - v0.2.1
 
 - add default thinking configuration and inline Herdr workflow video

package/packages/herdr-subagents/README.md

@@ -2,16 +2,15 @@
 
 A Pi extension that runs focused foreground or background work as normal interactive Pi Agents in visible Herdr panes. Full answers and sessions stay in project-local records while the parent receives only concise summaries and document paths.
 
-![A parent Pi conversation running three visible Herdr Subagents panes](docs/screenshot.png)
+![A parent Pi conversation showing the live Herdr Subagents Fleet footer](docs/screenshot.png)
 
 ## Demo
 
-The recording shows a real Pi conversation invoking a three-task read-only batch, Herdr opening one interactive Agent pane per task, and the compact results returning to the parent.
+The recording shows a real Pi conversation invoking a three-task read-only batch, the active Fleet footer in the parent, Herdr opening one interactive Agent pane per task, and the compact results returning to the parent.
 
 https://github.com/user-attachments/assets/8ddf3ae6-a11a-492b-9cae-d9496ba65b67
 
-The video starts a three-agent batch, focuses each live child pane in turn, then returns
-to the parent summary. The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
+The video starts a three-agent batch, focuses each live child pane in turn, captures the parent Fleet footer with yellow running indicators and true usage, then returns to the parent summary. Completed Fleet rows use green indicators. The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
 
 ## Requirements and install
 
@@ -29,7 +28,7 @@ pi update npm:@maxiaochao/pi-herdr-subagents
 
 The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
 
-Inside a Herdr workspace, the package registers `herdr_subagents` and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers neither, so the tool is absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
+Inside a Herdr workspace, the package registers `herdr_subagents`, `herdr_subagents_control`, and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers none of them, so these capabilities are absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
 
 The design replaces hidden print-mode subprocesses with ordinary interactive Pi Agents managed through Herdr, so delegated work stays visible, inspectable, resumable, and durably recorded.
 
@@ -38,16 +37,17 @@ The design replaces hidden print-mode subprocesses with ordinary interactive Pi
 Discover the effective personas first:
 
 ```text
-herdr_subagents({ action: "list" })
+herdr_subagents_control({ action: "list" })
 ```
 
 Then run one self-contained task:
 
 ```text
 herdr_subagents({
-  agent: "worker",
   label: "auth-review",
-  prompt: "Inspect the authentication flow and summarize the risks"
+  tasks: [
+    { name: "auth", agent: "worker", prompt: "Inspect the authentication flow and summarize the risks" }
+  ]
 })
 ```
 
@@ -64,25 +64,27 @@ herdr_subagents({
 })
 ```
 
-Set `background: true` to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+`tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
 
-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 same tool to continue the original session:
+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:
 
 ```text
-herdr_subagents({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
-While a batch is active, its task rows stay below the editor. 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.
+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 updates session usage from file events while one lightweight repaint timer advances running durations.
+
+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.
 
 ## History
 
-Run `/herdr-subagents history` or `herdr_subagents({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. 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({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents({ 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 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.
 
 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 refreshes rows and pane IDs as that task resumes and queued siblings start. 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.
+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.
 
 Foreground calls block until all children report completion, failure, or a request for input. 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.
 
@@ -250,9 +252,9 @@ Override the model for one task:
 
 ```text
 herdr_subagents({
-  agent: "reviewer",
-  model: "anthropic/claude-opus-4-1:high",
-  prompt: "Review the authorization boundary"
+  tasks: [
+    { name: "authorization", agent: "reviewer", model: "anthropic/claude-opus-4-1:high", prompt: "Review the authorization boundary" }
+  ]
 })
 ```
 

package/packages/herdr-subagents/TESTING.md

@@ -4,9 +4,9 @@
 
 1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests.
 2. `pi -ne -ns --no-session -e ./packages/herdr-subagents/extensions/herdr-subagents.ts` verifies extension loading.
-3. From a visible X11 Herdr client with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, and the final compact parent response.
+3. From a dedicated visible X11 Herdr client/window with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. Capture intentionally cycles through the live child panes, so avoid using that client/window for other work while recording; the script restores the previously focused pane afterward when it still exists. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, the active parent Fleet footer with yellow running indicators and real metrics, and the final compact parent response. The published screenshot must be the parent Fleet view, while the full WebM preserves the parent → three focused children → Fleet → parent sequence.
 4. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
-5. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → parent sequence.
+5. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → Fleet → parent sequence.
 
 ## Cases
 
@@ -16,10 +16,12 @@
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
-- Verify the flat public contract and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
+- Verify live token updates are file-event driven, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 136 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases 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 159 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases 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.

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

@@ -9,10 +9,10 @@ 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, type HerdrSubagentsBatchDetails, type HerdrSubagentsDetails, type HerdrSubagentsToolParams } from "../src/tool.ts";
-import { HerdrSubagentsParams } from "../src/parameters.ts";
+import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsDetails, type HerdrSubagentsRunParams } from "../src/tool.ts";
+import { HerdrSubagentsControlParams, HerdrSubagentsParams } from "../src/parameters.ts";
 import { HERDR_ACTIONS } from "../src/validation.ts";
-import { FleetController } from "../src/fleet-controller.ts";
+import { FleetController, type FleetWidgetRuntime } from "../src/fleet-controller.ts";
 import { isSettledRunStatus } from "../src/records.ts";
 
 const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
@@ -25,18 +25,32 @@ function statusVisual(status: string): { color: "success" | "warning" | "error"
 	return { color: "error", glyph: "✗" };
 }
 
-function renderToolCall(args: HerdrSubagentsToolParams, theme: Theme): Text {
-	if (args.action) {
-		const action = HERDR_ACTIONS[args.action];
-		const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
-		return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents ${args.action}`))}${runId}`, 0, 0);
-	}
-	if (args.tasks) return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} tasks`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
-	const agent = args.agent || "worker";
-	const label = args.label ? ` · ${String(args.label)}` : "";
-	const prompt = args.prompt ? String(args.prompt).replace(/\s+/g, " ") : "...";
-	const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}...` : prompt;
-	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", agent)}${theme.fg("muted", label)}\n  ${theme.fg("dim", preview)}`, 0, 0);
+function renderToolCall(args: HerdrSubagentsRunParams, theme: Theme): Text {
+	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} task${args.tasks.length === 1 ? "" : "s"}`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
+}
+
+function renderControlToolCall(args: HerdrSubagentsControlToolParams, theme: Theme): Text {
+	const action = HERDR_ACTIONS[args.action];
+	const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
+	return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents_control ${args.action}`))}${runId}`, 0, 0);
+}
+
+export function normalizeHerdrSubagentsArguments(args: unknown): HerdrSubagentsRunParams {
+	if (!args || typeof args !== "object") return args as HerdrSubagentsRunParams;
+	const legacy = args as Record<string, unknown>;
+	if (Array.isArray(legacy.tasks) || typeof legacy.prompt !== "string" || legacy.action !== undefined) return args as HerdrSubagentsRunParams;
+	if (Object.keys(legacy).some((key) => !["prompt", "agent", "label", "model", "background"].includes(key))) return args as HerdrSubagentsRunParams;
+	const label = typeof legacy.label === "string" ? legacy.label : undefined;
+	return {
+		tasks: [{
+			name: label || "task",
+			prompt: legacy.prompt,
+			...(typeof legacy.agent === "string" ? { agent: legacy.agent } : {}),
+			...(typeof legacy.model === "string" ? { model: legacy.model } : {}),
+		}],
+		...(label ? { label } : {}),
+		...(typeof legacy.background === "boolean" ? { background: legacy.background } : {}),
+	};
 }
 
 function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRenderResultOptions, theme: Theme): Container | Text {
@@ -49,20 +63,20 @@ function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRender
 		return container;
 	}
 	const details = result.details as HerdrSubagentsDetails | undefined;
-	if (!details?.agent) {
-		const content = result.content[0];
-		return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
-	}
-	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?.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;
 	}
-	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);
 }
 
 async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController): Promise<void> {
@@ -104,8 +118,10 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 export interface HerdrSubagentsExtensionDependencies {
 	herdr?: HerdrAutomation;
 	execute?: typeof executeHerdrSubagents;
+	executeControl?: typeof executeHerdrSubagentsControl;
 	isEditor?: (value: unknown) => boolean;
 	createFleetWidget?: (lines: string[]) => Container;
+	fleetWidgetRuntime?: FleetWidgetRuntime;
 }
 
 async function recoverParentSession(cwd: string, herdr: HerdrAutomation, owner: { sessionId?: string; processId: number }, notify: (message: string) => void): Promise<void> {
@@ -139,9 +155,10 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1" || process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) return;
 	const herdr = dependencies.herdr ?? new CliHerdrAutomation();
 	const execute = dependencies.execute ?? executeHerdrSubagents;
+	const executeControl = dependencies.executeControl ?? executeHerdrSubagentsControl;
 	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
 	const dispatcher = new RunDispatcher();
-	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget);
+	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget, dependencies.fleetWidgetRuntime);
 	const runControllers = new Map<string, AbortController>();
 	const inFlight = new Set<Promise<unknown>>();
 	let sessionController = new AbortController();
@@ -177,17 +194,17 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents",
 		label: "Herdr Subagents",
-		description: "Run one focused task or an ordered bounded-concurrency batch in visible interactive Herdr Pi Agents. Foreground calls block while workers run concurrently; background batches return a run ID immediately and publish completion later. 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. Foreground calls block, while background calls return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
-		promptGuidelines: ["Call action=list once before the first execution. Submit one prompt or an ordered tasks list; use concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
+		promptGuidelines: ["Call herdr_subagents_control with action=list once before the first execution. Submit an ordered tasks list; use one item for a single task and concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
 		parameters: HerdrSubagentsParams,
+		prepareArguments: normalizeHerdrSubagentsArguments,
 
-		async execute(_toolCallId, params: HerdrSubagentsToolParams, signal, onUpdate, ctx) {
+		async execute(_toolCallId, params: HerdrSubagentsRunParams, signal, onUpdate, ctx) {
 			const generation = sessionGeneration;
-			const runId = params.tasks ? randomUUID() : undefined;
-			const executionId = runId ?? params.runId ?? randomUUID();
+			const runId = randomUUID();
 			const controller = new AbortController();
-			runControllers.set(executionId, controller);
+			runControllers.set(runId, controller);
 			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background && signal ? [signal] : [])]);
 			const executeRun = async () => {
 				const result = await execute(params, runSignal, (update) => {
@@ -201,21 +218,6 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				fleet.sync(result.details);
 				return result;
 			};
-			if (!params.tasks) {
-				const promise = executeRun();
-				inFlight.add(promise);
-				const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
-				if (params.action === "respond") {
-					const details = result.details as { runId?: string; status?: string };
-					if (details.status === "blocked") fleet.sync(result.details);
-					else if (isSettledRunStatus(details.status)) {
-						fleet.clearRun(params.runId);
-						if (params.runId) dispatcher.release(params.runId);
-					}
-				}
-				return result;
-			}
-			if (!runId) throw new Error("Batch run ID was not allocated.");
 			if (params.background) await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
 			const promise = dispatcher.submit(runId, async () => {
 				const result = await executeRun().finally(async () => { if (params.background) await removeQueuedRun(ctx.cwd, runId); });
@@ -227,7 +229,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				return result;
 			});
 			inFlight.add(promise);
-			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); }).catch(() => undefined);
+			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(runId); }).catch(() => undefined);
 			if (params.background) {
 				void promise.then((result) => {
 					if (generation !== sessionGeneration) return;
@@ -248,6 +250,44 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 		renderResult: renderToolResult,
 	});
 
+	pi.registerTool({
+		name: "herdr_subagents_control",
+		label: "Herdr Subagents Control",
+		description: "Inspect Herdr personas and run history, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
+		promptSnippet: "Inspect and control Herdr subagent runs",
+		parameters: HerdrSubagentsControlParams,
+
+		async execute(_toolCallId, params: HerdrSubagentsControlToolParams, signal, onUpdate, ctx) {
+			const executionId = params.runId ?? randomUUID();
+			const controller = new AbortController();
+			runControllers.set(executionId, controller);
+			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(signal ? [signal] : [])]);
+			const promise = executeControl(params, runSignal, (update) => {
+				const details = update.details as HerdrSubagentsBatchDetails | undefined;
+				if (details?.activity) fleet.sync(details);
+				const updateText = update.content.find((item) => item.type === "text")?.text;
+				const updateDetails = update.details as { warning?: string };
+				if (updateDetails.warning || updateText?.includes("cleanup failed")) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
+				onUpdate?.(update);
+			}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid } });
+			inFlight.add(promise);
+			const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
+			fleet.sync(result.details);
+			if (params.action === "respond") {
+				const details = result.details as { status?: string };
+				if (details.status === "blocked") fleet.sync(result.details);
+				else if (isSettledRunStatus(details.status)) {
+					fleet.clearRun(params.runId);
+					if (params.runId) dispatcher.release(params.runId);
+				}
+			}
+			return result;
+		},
+
+		renderCall: renderControlToolCall,
+		renderResult: renderToolResult,
+	});
+
 	pi.registerCommand("herdr-subagents", {
 		description: "Inspect effective subagent agents, models, and settings",
 		getArgumentCompletions: (prefix) => ["active", "history", "agents", "models", "settings", "focus "].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),

package/packages/herdr-subagents/package.json

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

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

@@ -10,7 +10,7 @@ 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 { 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";
@@ -63,7 +63,7 @@ export interface BatchResult {
 	requestedConcurrency: number;
 	effectiveConcurrency: number;
 	tasks: BatchTaskResult[];
-	activity: Array<{ index: number; name: string; status: BatchTaskStatus; paneId?: string }>;
+	activity: TaskActivity[];
 	summary: string;
 	documents: HerdrSubagentsDocument[];
 	recordDirectory: string;
@@ -114,7 +114,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 	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" }));
+	const activity: BatchResult["activity"] = contexts.map((context, index) => projectTaskActivity(context.taskRecord, index));
 	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?.({
@@ -146,7 +146,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				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 };
+				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.`) });
 				agentName = prompted.agentName;
@@ -164,7 +164,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 } : {}), paneId, recordDirectory: context.taskDirectory, sessionFile: context.sessionFile };
-			activity[index] = { index, name: task.name, status, ...(paneId ? { paneId } : {}) };
+			activity[index] = projectTaskActivity(context.taskRecord, index);
 			settled += 1;
 			emit("running", `${settled}/${tasks.length} tasks settled.`);
 		};