@maxiaochao/pi-toolkit 0.9.6 → 0.10.1

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 2026-10-08 - v0.10.1
+
+- bundle herdr-subagents v0.2.1: add default thinking configuration and inline Herdr workflow video
+- remove the bundled `calldiff` skill
+- add merged global/project `defaultThinking` for Herdr Subagents, below persona-specific thinking and above parent-session fallback
+- embed the Herdr workflow video directly in the GitHub README, retain the reproducible WebM source, and remove the GIF preview
+- document every Herdr Subagents settings and persona option, accepted values, defaults, configuration paths, examples, and exact precedence
+- add a full real-time Herdr Subagents WebM recording that focuses every child Agent pane before returning to the parent summary
+
+- replace the rendered Herdr transcript demo with a real UI recording of a parent Pi conversation opening and completing three concurrent interactive Agent panes
+
+## 2026-10-08 - v0.10.0
+
+- bundle herdr-subagents v0.2.0: replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows
+- replace Tiny Subagent's hidden print/shell execution with Herdr Subagents: visible interactive Pi Agents, one exclusive on-demand pane per task, Fleet keyboard navigation, durable blocked/history continuation, parent-session cancellation, and focus-safe batch tab cleanup
+- fix Herdr Subagents Fleet state after blocked responses, preserve the active task widget while later background runs queue, and share ownership, pane-allocation, and status-reduction logic across recovery paths
+
 ## 2026-10-08 - v0.9.6
 
 - bundle codex-edit v0.1.9: install the pinned Pi runtime for clean-runner publication tests

package/README.md

@@ -25,7 +25,7 @@ The root package embeds the child-package source snapshots listed below. Install
 | [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-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-tiny-subagent](packages/tiny-subagent/README.md) | One focused task in a fresh child Pi context | `pi install npm:@maxiaochao/pi-tiny-subagent` | `pi update npm:@maxiaochao/pi-tiny-subagent` |
+| [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` |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
@@ -66,7 +66,6 @@ bash scripts/install.sh
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
 | `agent-team` | Run cross-vendor adversarial review through Herdr |
 | `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
-| `calldiff` | Diff call stacks across commits |
 
 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.9.6",
+  "version": "0.10.1",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -15,7 +15,7 @@
     "packages/todo",
     "packages/cache-export",
     "packages/codex-edit",
-    "packages/tiny-subagent",
+    "packages/herdr-subagents",
     "packages/worktree",
     "themes",
     "README.md",
@@ -34,7 +34,7 @@
       "./packages/cache-export/extensions/cache-export.ts",
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
-      "./packages/tiny-subagent/extensions/tiny-subagent.ts"
+      "./packages/herdr-subagents/extensions/herdr-subagents.ts"
     ],
     "skills": [
       "./skills",
@@ -57,8 +57,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/tiny-subagent test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/tiny-subagent/extensions/tiny-subagent.ts",
+    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/herdr-subagents/CHANGELOG.md

@@ -0,0 +1,50 @@
+## 2026-10-08 - v0.2.1
+
+- add default thinking configuration and inline Herdr workflow video
+- Add merged global/project `defaultThinking`, below persona-specific thinking and above parent-session fallback, with effective source reporting.
+- Embed the workflow video directly in the GitHub README, retain the reproducible WebM source, and remove the GIF preview.
+- Expand the README with every settings and persona option, accepted values, defaults, paths, examples, and exact model, thinking, skills, and definition precedence.
+- Add a full WebM recording that focuses all three live child Agent panes before returning to the parent summary.
+- Replace the rendered transcript media with a real Herdr UI recording that follows a parent Pi conversation through a three-Agent batch and final compact response.
+
+## 2026-10-08 - v0.2.0
+
+- replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows
+- Skip tool and command registration outside a Herdr workspace so unavailable Subagent capabilities do not enter the model context.
+- Preserve newly allocated panes when blocked runs resume, stop blindly retrying Herdr resource-creating commands after uncertain failures, and prevent concurrent historical resumes from writing the same Pi session.
+- Isolate malformed queue/history entries so healthy active runs and durable history remain recoverable, and share durable attempt settlement plus task projection contracts across execution modes.
+- Retain blocked Fleet and dispatcher ownership after stateless response errors, and include public test entrypoints in the published package.
+- Preserve every pending stale-tab cleanup across repeated pane migrations, retry all of them during startup reconciliation, and surface allocator cleanup failures through batch updates.
+- Keep persisted reports authoritative even when Herdr transport fails after submission, persist failure reports for historical follow-ups, reject resume attempts against active or cleanup-pending runs, recover terminal deferred cleanup on startup, preserve cancelled ownership on shutdown, keep recovered Agent attempts aligned with durable turns, archive malformed turns, remove rejected background queue entries, support Pi enhanced keyboard sequences and authoritative status rendering, centralize lifecycle metadata, surface control-plane and cleanup failures, merge deferred cleanup against current durable state, and force-close focused tabs when parent shutdown is already active.
+- Share strict report parsing across live and recovered paths, validate durable task ordering, surface unreadable queue/history records, reconcile prior sessions even within one Pi process, keep settled Fleet rows navigable, preserve surviving sibling panes during dead-pane recovery, and retain cleanup diagnostics.
+- Keep queued and blocked siblings alive when one blocked response fails, centralize authoritative run-status transitions, and bind focus-deferred tab cleanup to parent-session shutdown.
+- Retain dispatcher and Fleet ownership while a batch is blocked, centralize task/turn transitions, surface transient pane lookup failures, and notify deferred single-task cleanup failures.
+- Fail reconciliation when task records are unreadable, archive malformed child reports before replacing them with valid failure records, and keep durable history and saved-session follow-up usable.
+- Keep startup reconciliation moving past truncated child reports, resume dispatch after recovery errors, clear stale blocked fields after authoritative follow-ups, and surface deferred cleanup failures.
+- Stream Fleet row and pane updates while a blocked answer resumes work and releases queued siblings.
+- Keep the active Fleet widget stable when another background run is queued, refresh rows and pane navigation after blocked responses, and cover the public extension UI/input wiring with injectable dependencies.
+- Centralize parent ownership, run-status aggregation, and serialized pane allocation across initial, continued, recovered, and historical runs.
+- Run every initial task, blocked response, recovered task, and historical follow-up as a visible interactive Pi Agent through Herdr Agent start/prompt; remove print mode, pane shell injection, completion markers, and marker polling.
+- Give every started task a new on-demand pane, retain completed panes until the batch settles, and then close the whole tab with focus-safe cleanup.
+- Add a flat fully described tool schema with runtime mode validation and a Fleet-style task list with direct keyboard pane navigation.
+- Continue historical sessions as durable turns of the same logical task, and cancel/archive unfinished work when the parent Pi session closes.
+- Persist and reconcile queued/running work across parent shutdown, avoid retrying uncertain startup operations, preserve post-submit failures, warn without timing out stalled children, and atomically replace state snapshots.
+- Add compact project-local history, saved-session follow-ups in new Herdr tabs, explicit per-run cleanup, unlimited retention, and generated-state Git exclusion.
+- Support structured `needs-input` reports, preserve blocked panes and sessions, and resume the original child with `action: respond`.
+- Queue background batches behind one active run, return stable IDs immediately, keep progress visible, and send one compact run-level parent notification.
+- Show active run counts in a persistent widget, expose compact `/herdr-subagents active` and pane focus navigation, update progress labels, and defer cleanup while a completed tab is focused.
+- Execute ordered read-only batches with FIFO bounded concurrency, stable result order, and sibling failure isolation; force write-capable runs to serial execution.
+- Add built-in worker, explorer, and reviewer personas with project/global/package discovery precedence.
+- Add merged global and project model, thinking, skill, and concurrency settings plus `/herdr-subagents` discovery commands.
+- Run one synchronous subagent in a dedicated, unfocused Herdr tab and close it after completion.
+- Require a structured child report and return only its summary and document paths to the parent.
+- Persist run/task metadata, the full result, and the child Pi session under `.pi/herdr-subagents/runs`.
+
+## 2026-09-30 - v0.1.1
+
+- Add standalone testing documentation and production-runner screenshot/demo media.
+- Align the package manifest and root bundle with the shared workspace source.
+
+## 2026-09-01 - v0.1.0
+
+- initial release

package/packages/herdr-subagents/README.md

@@ -0,0 +1,283 @@
+# @maxiaochao/pi-herdr-subagents
+
+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)
+
+## 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.
+
+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).
+
+## Requirements and install
+
+Run Pi inside Herdr, then install the package:
+
+```bash
+pi install npm:@maxiaochao/pi-herdr-subagents
+```
+
+Update an existing standalone installation with:
+
+```bash
+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.
+
+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.
+
+## Usage
+
+Discover the effective personas first:
+
+```text
+herdr_subagents({ 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"
+})
+```
+
+Or submit an ordered foreground batch:
+
+```text
+herdr_subagents({
+  label: "security-review",
+  concurrency: 3,
+  tasks: [
+    { name: "auth", agent: "reviewer", prompt: "Review authentication" },
+    { name: "sessions", agent: "explorer", prompt: "Trace session storage" }
+  ]
+})
+```
+
+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.
+
+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:
+
+```text
+herdr_subagents({ 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.
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+## Reports and records
+
+The child must finish through the package's structured `subagent_report` tool. The parent receives only:
+
+- completion or failure status
+- a concise summary
+- paths to useful documents
+- the task-record location
+
+The complete result is not copied into the parent model context. Each run is retained under:
+
+```text
+.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.
+
+## Configuration and personas
+
+Herdr Subagents loads settings and persona definitions from separate files:
+
+| Scope | Settings | Persona definitions |
+| --- | --- | --- |
+| Project | `.pi/herdr-subagents.json` | `.pi/herdr-subagents/agents/*.md` |
+| Global | `~/.pi/agent/herdr-subagents.json` | `~/.pi/agent/herdr-subagents/agents/*.md` |
+| Package | built-in defaults | installed package `agents/*.md` |
+
+Project JSON values recursively override global JSON values. The built-in setting defaults are `defaultConcurrency: 1`, `maxConcurrency: 4`, and `stalledWarningSeconds: 300`. `defaultModel` and `defaultThinking` are unset, so the parent Pi model and its thinking level are inherited unless another setting wins.
+
+### Settings file option reference
+
+These are all supported top-level fields in `herdr-subagents.json`:
+
+| Option | Accepted value | Default | Effect |
+| --- | --- | --- | --- |
+| `defaultConcurrency` | Positive integer | `1` | Number of read-only tasks allowed to run together when a batch call omits `concurrency`. It is capped to `maxConcurrency`. |
+| `maxConcurrency` | Positive integer | `4` | Hard ceiling for requested/default batch concurrency. A batch containing any write-capable persona still runs serially. |
+| `stalledWarningSeconds` | Positive integer | `300` | Seconds before a still-running child emits a warning. This is not a timeout and does not stop the child. |
+| `defaultModel` | Non-empty Pi model string, normally `provider/model` | Unset | Model used when neither JSON persona settings nor persona Markdown select one. If unset, the parent model is inherited. Use `/herdr-subagents models` to list authenticated models. |
+| `defaultThinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Unset | Thinking level below persona-specific settings. Provider/model support can vary. If unset, parent thinking is inherited only when the parent model is also inherited. |
+| `personas` | Object keyed by an existing persona name | `{}` | Per-persona JSON overrides described below. This does not create a persona; a matching Markdown definition must exist. |
+
+Known fields with an invalid JSON type, an empty required string, or a non-positive integer are ignored with a diagnostic shown by `/herdr-subagents settings`. Model IDs, thinking-level compatibility, and skill availability are ultimately validated by Pi when the child starts. When `defaultConcurrency` exceeds `maxConcurrency`, the effective default is reduced to the maximum.
+
+Each `personas.<name>` object supports exactly these overrides:
+
+| Option | Accepted value | Effect |
+| --- | --- | --- |
+| `model` | Non-empty Pi model string | Overrides the model from the effective persona Markdown and `defaultModel`. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Overrides persona Markdown and `defaultThinking`. The value is passed to Pi's `--thinking` option. |
+| `skills` | Array of non-empty strings | Replaces the entire lower-precedence skill list. Use `[]` to clear inherited skills. Each item is passed to child Pi as `--skill`. |
+
+JSON persona overrides cannot change `name`, `description`, `access`, `tools`, or the system prompt; define those in persona Markdown.
+
+A global configuration can establish shared defaults:
+
+```json
+{
+  "defaultConcurrency": 2,
+  "maxConcurrency": 4,
+  "stalledWarningSeconds": 300,
+  "defaultModel": "anthropic/claude-sonnet-4-5",
+  "defaultThinking": "medium",
+  "personas": {
+    "explorer": {
+      "model": "anthropic/claude-haiku-4-5",
+      "thinking": "medium",
+      "skills": ["code-search"]
+    },
+    "reviewer": {
+      "thinking": "high",
+      "skills": ["code-review"]
+    }
+  }
+}
+```
+
+The project file can override only the fields that differ. Persona fields are merged by persona name:
+
+```json
+{
+  "defaultConcurrency": 3,
+  "stalledWarningSeconds": 600,
+  "defaultThinking": "high",
+  "personas": {
+    "explorer": {
+      "model": "openai/gpt-5.2"
+    },
+    "reviewer": {
+      "skills": ["security-review", "code-review"]
+    }
+  }
+}
+```
+
+The package includes these personas:
+
+| Persona | Access | Built-in tools | Intended use |
+| --- | --- | --- | --- |
+| `worker` | write | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` | Focused implementation work |
+| `explorer` | read | `read`, `bash`, `grep`, `find`, `ls` | Fast codebase investigation |
+| `reviewer` | read | `read`, `bash`, `grep`, `find`, `ls` | Correctness and maintainability review |
+
+Persona definitions use Markdown frontmatter followed by the child system prompt. For example, save this as `.pi/herdr-subagents/agents/security-reviewer.md`:
+
+```md
+---
+name: security-reviewer
+description: Read-only reviewer for security risks
+access: read
+model: anthropic/claude-sonnet-4-5
+thinking: high
+tools: read, bash, grep, find, ls
+skills: security-review, code-review
+---
+
+Review the assigned scope without modifying files. Report concrete risks and evidence.
+```
+
+Persona Markdown supports these frontmatter fields:
+
+| Field | Accepted value | Required/default | Effect |
+| --- | --- | --- | --- |
+| `name` | Non-empty string | Required | Persona identifier used by `agent`. Names must be unique within one persona directory. |
+| `description` | Non-empty string | Required | Description shown to the parent when agents are listed. |
+| `access` | `read` or `write` | `write` | Scheduling declaration. Any batch containing `write` is forced to concurrency one. `read` permits parallel scheduling but does not itself remove tools. |
+| `model` | Non-empty Pi model string | Unset | Persona model default. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Unset | Persona thinking default passed to Pi's `--thinking` option. |
+| `tools` | Non-empty comma-separated list, optionally bracketed | Child Pi defaults | Restricts built-in tools. Supported names are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, and `powershell`. `subagent_report` is always added. |
+| `skills` | Comma-separated list, optionally bracketed | None | Skills loaded explicitly into child Pi; automatic skill discovery is disabled. |
+
+The Markdown body after the frontmatter is the child system prompt and may be empty. To make a custom persona operationally read-only, set `access: read` **and** choose an appropriate `tools` allowlist; `access` alone is not a tool sandbox. Model names and skill values are passed to Pi, so they must be available in the installed Pi environment.
+
+Persona Markdown definitions use replacement precedence, not field merging. A same-name project definition replaces the entire global or package definition:
+
+1. project `.pi/herdr-subagents/agents/*.md`
+2. global `~/.pi/agent/herdr-subagents/agents/*.md`
+3. package built-ins
+
+### Model and persona-option precedence
+
+The child model is selected in this exact order:
+
+1. `model` on the task or call
+2. project `personas.<name>.model` JSON setting
+3. global `personas.<name>.model` JSON setting
+4. `model` in the effective persona Markdown frontmatter
+5. effective `defaultModel` JSON setting (project overrides global)
+6. parent Pi model
+
+The child thinking level is selected in this order:
+
+1. project `personas.<name>.thinking` JSON setting
+2. global `personas.<name>.thinking` JSON setting
+3. `thinking` in the effective persona Markdown frontmatter
+4. effective `defaultThinking` JSON setting (project overrides global)
+5. parent Pi thinking level when the child also inherits the parent model
+
+Thinking has no call-level override. `skills` uses the first three persona-level steps and has no global default; a project `skills` array replaces, rather than appends to, the global or Markdown list.
+
+Override the model for one task:
+
+```text
+herdr_subagents({
+  agent: "reviewer",
+  model: "anthropic/claude-opus-4-1:high",
+  prompt: "Review the authorization boundary"
+})
+```
+
+Each task in a batch can select its own model:
+
+```text
+herdr_subagents({
+  concurrency: 2,
+  tasks: [
+    { name: "map", agent: "explorer", model: "anthropic/claude-haiku-4-5", prompt: "Map the request flow" },
+    { name: "review", agent: "reviewer", model: "anthropic/claude-sonnet-4-5", prompt: "Review input validation" }
+  ]
+})
+```
+
+Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents settings` to inspect effective values and their sources.
+
+## Recovery and failures
+
+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.
+
+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.
+
+## Development and tests
+
+See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements.

package/packages/herdr-subagents/TESTING.md

@@ -0,0 +1,25 @@
+# Herdr Subagents test strategy
+
+## Flow
+
+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.
+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.
+
+## Cases
+
+- Resolve package, global, and project personas and validate frontmatter/configuration.
+- Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
+- 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.
+- 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 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.

package/packages/herdr-subagents/agents/explorer.md

@@ -0,0 +1,8 @@
+---
+name: explorer
+description: Read-only explorer for fast codebase investigation
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Investigate the assigned question without modifying files. Report concrete evidence and useful paths.

package/packages/herdr-subagents/agents/reviewer.md

@@ -0,0 +1,8 @@
+---
+name: reviewer
+description: Read-only reviewer for correctness and maintainability risks
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Review the assigned work without modifying files. Report actionable findings with concrete evidence.

package/packages/{tiny-subagent → herdr-subagents}/agents/worker.md

@@ -1,6 +1,7 @@
 ---
 name: worker
 description: General-purpose worker for one focused task
+access: write
 tools: read, bash, edit, write, grep, find, ls
 ---