pi-herdr-agents 1.5.1 → 1.7.0

package/AGENTS.md

@@ -4,7 +4,7 @@ These instructions apply to humans and coding agents changing `pi-herdr-agents`.
 
 ## What this package is
 
-`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous Pi child agents and approved read-only review workflows exclusively in Herdr. Ordinary runs use dedicated Herdr panes/tabs. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch. Legacy role definitions that request an external CLI fail before Herdr creates resources.
+`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous Pi child agents exclusively in Herdr. Ordinary runs group child panes in extension-owned `Agents` tabs by default. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch. Legacy role definitions that request an external CLI fail before Herdr creates resources.
 
 The extension is fire-and-forget: `subagent` returns an acknowledgement, and completion is delivered to the parent automatically. Never add polling guidance that tells callers to sleep, tail sessions, or repeatedly check status.
 
@@ -12,28 +12,29 @@ The extension is fire-and-forget: `subagent` returns an acknowledgement, and com
 
 - [`README.md`](./README.md) — canonical installation, API, configuration, lifecycle, and agent-authoring reference
 - [`docs/README.md`](docs/README.md) — map of shipped contracts, active design, ADRs, and background research
-- [`CONTEXT.md`](CONTEXT.md) — workflow domain language and prototype evidence; read it before changing workflow design
+- [`CONTEXT.md`](CONTEXT.md) — workflow-domain glossary; read it before changing orchestration design
 - [`docs/adr/0003-installable-role-packs.md`](docs/adr/0003-installable-role-packs.md) — installable role-pack discovery, precedence, and collision contract
 - [`docs/worktree-subagents.md`](docs/worktree-subagents.md) — canonical worktree operating, review, recovery, and cleanup guide
 - [`RELEASING.md`](RELEASING.md) — release checks and publishing procedure
 
-Bundled role prompts live in [`agents/`](agents/). The native `/skill:orchestrate` workflow authoring skill lives at [`skills/orchestrate/SKILL.md`](skills/orchestrate/SKILL.md). The `/plan` orchestration prompt lives at [`pi-extension/subagents/plan-skill.md`](pi-extension/subagents/plan-skill.md).
+Bundled role prompts live in [`agents/`](agents/). The native `/skill:orchestrate` public-review fan-out skill lives at [`skills/orchestrate/SKILL.md`](skills/orchestrate/SKILL.md). The `/plan` orchestration prompt lives at [`pi-extension/subagents/plan-skill.md`](pi-extension/subagents/plan-skill.md).
 
 ## Code map
 
 - `pi-extension/subagents/index.ts` — public tools/commands, agent discovery, launch/watch lifecycle, completion delivery, worktree manifests and handoffs
-- `pi-extension/subagents/herdr.ts` — Herdr CLI argument construction and response parsing
+- `pi-extension/subagents/herdr.ts` — Herdr CLI calls, response parsing, and ID-based Agents tab placement and capacity
 - `pi-extension/subagents/terminal.ts` — terminal adapter used by the lifecycle
 - `pi-extension/subagents/lifecycle.ts`, `status.ts`, `activity.ts` — process/turn state and widget projection
+- `pi-extension/subagents/wake.ts`, `supervision.ts`, `supervision-config.ts` — file wake-ups, shared pane reconciliation, polling fallback, and supervision configuration
+- `pi-extension/subagents/persistent-config.ts` — strict persistent-specialist cap configuration
 - `pi-extension/subagents/completion.ts`, `session.ts`, `subagent-done.ts` — child completion, transcript handling, `caller_ping`, and `subagent_done`
-- `pi-extension/subagents/workflow.ts`, `workflow-worker.js` — workflow preparation, ownership, journal, lifecycle, and Worker execution
-- `CONTEXT.md` — domain glossary and validated prototype evidence for active design
+- `CONTEXT.md` — orchestration-domain glossary
 - `docs/adr/` — hard-to-reverse architectural decisions
 - `docs/research/` — evidence and alternatives, never the shipped contract
 - `test/test.ts` — unit tests for public subagent extension seams
-- `test/workflow.test.ts` — unit tests for workflow preparation, execution, and cancellation
 - `test/package-skill.test.js` — bundled skill and package manifest contract test
 - `test/integration/` — real Herdr and Pi lifecycle tests using the deterministic provider by default
+- `test/bench/supervision-bench.mjs` — manual isolated-Herdr supervision transport benchmark; raw samples stay in `/tmp/issue29-bench/`
 
 ## Worktree contract
 
@@ -72,8 +73,7 @@ When behavior changes, update every affected surface in the same commit:
 - `/plan` orchestration policy → `pi-extension/subagents/plan-skill.md`
 - contributor/release verification → this file, `.pi/skills/run-integration-tests/SKILL.md`, or `RELEASING.md`
 - domain terminology → `CONTEXT.md`
-- hard-to-reverse workflow trade-offs → the relevant ADR; do not create an ADR for every design question
-- active orchestrated-review design → `docs/orchestrated-review-workflow-plan.md`
+- hard-to-reverse orchestration trade-offs → the relevant ADR; do not create an ADR for every design question
 - architectural evidence and alternatives only → research docs, clearly marked when later decisions supersede them
 
 Do not copy the full worktree guide into every role prompt. Keep canonical detail in the guide and add only the role-specific rule an agent needs while running.
@@ -105,7 +105,7 @@ Use `PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run te
 Before committing:
 
 - inspect `git status` and the final diff;
-- confirm the package preview includes `CHANGELOG.md`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, `skills/orchestrate/adversarial-review-example.js`, and `pi-extension/subagents/workflow-worker.js`, while excluding plans, journals, sessions, prototypes, generated evidence, and local config;
+- confirm the package preview includes `CHANGELOG.md`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, and `skills/orchestrate/adversarial-review-example.js`, while excluding `pi-extension/subagents/workflow-worker.js`, plans, journals, sessions, prototypes, generated evidence, and local config;
 - run `npm pack --dry-run` when package contents or documentation paths changed;
 - confirm that no generated plans, journals, sessions, provider configuration, test scripts, or review artifacts are staged; and
 - confirm that no accidental empty directory exists at the repository root:

package/CHANGELOG.md

@@ -7,7 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.5.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.0...v1.5.1)
+## [v1.7.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.6.0...v1.7.0)
+
+### Merged
+
+- feat(subagents): checkout-aware Agents tabs and safe cleanup (#33) [`#43`](https://github.com/giuseppecrj/pi-herdr-agents/pull/43)
+- feat: no-progress advisories for active subagents (#40) [`#41`](https://github.com/giuseppecrj/pi-herdr-agents/pull/41)
+- fix(subagents): measure recovered hang duration and track outstanding tool calls [`#40`](https://github.com/giuseppecrj/pi-herdr-agents/pull/40)
+
+### Commits
+
+- feat(subagents): group agents by checkout with safe pane cleanup (#33) [`59a1075`](https://github.com/giuseppecrj/pi-herdr-agents/commit/59a10756722e7cce3b2ded07db6e1adb04abb0ab)
+- fix(subagents): preserve delivery cleanup and live caller identity (#33) [`26987c5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/26987c58a2c882f31a0d935d7e97ce9dd8c4cce8)
+- feat(subagents): no-progress hang advisories for active children (#40) [`1ebf356`](https://github.com/giuseppecrj/pi-herdr-agents/commit/1ebf356521dd46dd6ee035fe3ebba0262992f399)
+- fix(subagents): keep no-progress recovery guidance evidence-based (#40) [`9cbf155`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9cbf155e291c063f70ef86800ef3bfe3c742c6c6)
+- test(integration): hang advisory coverage (#40) [`075f4fe`](https://github.com/giuseppecrj/pi-herdr-agents/commit/075f4feb17938df28a92fa00851d606e5a83b258)
+- fix(subagents): preserve boundary-aligned records in bounded session tails (#40) [`f096fdb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f096fdb681921e9ab460610d53e456758802725f)
+
+## [v1.6.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.1...v1.6.0) - 2026-09-08
+
+### Merged
+
+- feat: event-driven supervision with file wake-ups and batched reconciliation (#29) [`#39`](https://github.com/giuseppecrj/pi-herdr-agents/pull/39)
+- fix(subagents): never downgrade a queued reconciliation to a wake [`#29`](https://github.com/giuseppecrj/pi-herdr-agents/pull/29)
+- feat: persistent subagents with turn-based task delivery (#32) [`#37`](https://github.com/giuseppecrj/pi-herdr-agents/pull/37)
+- fix(subagents): fail closed after an unconfirmed persistent stop [`#32`](https://github.com/giuseppecrj/pi-herdr-agents/pull/32)
+- fix(subagents): close persistent delivery and stop-retry edge cases [`#32`](https://github.com/giuseppecrj/pi-herdr-agents/pull/32)
+- refactor!: remove the workflow subsystem (#31) [`#36`](https://github.com/giuseppecrj/pi-herdr-agents/pull/36)
+- refactor!: remove the workflow subsystem [`#31`](https://github.com/giuseppecrj/pi-herdr-agents/pull/31)
+
+### Commits
+
+- feat(subagents): turn-based task delivery for persistent specialists (#32) [`820a7dc`](https://github.com/giuseppecrj/pi-herdr-agents/commit/820a7dcebf5cf1b2d36435c39388702d238410f1)
+- feat(subagents): file wake-ups and batched supervision reconciliation (#29) [`cbd42ed`](https://github.com/giuseppecrj/pi-herdr-agents/commit/cbd42ed0df09276d0859436e53657c6af9ba848d)
+- feat(subagents): subagent_stop, specialist cap, and crash notices (#32) [`73267af`](https://github.com/giuseppecrj/pi-herdr-agents/commit/73267afbd279f8796dd8b13b92a16de6aba65562)
+- feat(subagents): subagent_send and specialist visibility (#32) [`5542341`](https://github.com/giuseppecrj/pi-herdr-agents/commit/554234161a25c5868b1b6744a05914d816a61823)
+- fix(subagents): retain persistent task and stop evidence (#32) [`154bc1f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/154bc1f202e3e90e0a42ef5687964c69bbbbc68e)
+- test(integration): persistent specialist lifecycle coverage (#32) [`526ae46`](https://github.com/giuseppecrj/pi-herdr-agents/commit/526ae46ffe56205919d8eb6f1ba94020c2e4d378)
+- feat(subagents): supervision benchmark and docs (#29) [`97fb7a3`](https://github.com/giuseppecrj/pi-herdr-agents/commit/97fb7a3b6b2445faa452fce7d72008cf8173adc5)
+- test(integration): event-driven supervision fault coverage (#29) [`f9d2603`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f9d260388c8e494da6d70bb524341f1ba2edd637)
+- fix(subagents): keep legacy polling honest and close supervision handles (#29) [`256a32c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/256a32c572e8c7349e8faa820d8c9cc9f5f11395)
+- fix(subagents): enforce single-task busy state for persistent specialists (#32) [`c2fa33f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c2fa33f5a367ca7b79ab9635ef9d41f1ea165c31)
+- fix(subagents): scope pane snapshots to registered owners and confirm absence (#29) [`c73a132`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c73a13211f743dc881c506226f457c6a5045e41b)
+- feat(subagents): persistent specialist docs, glossary, and integration coverage (#32) [`e0f052d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e0f052da7b717a9c4c21ae1d83172acb1a27452c)
+- fix(subagents): guard terminal evidence against racing semantic records (#29) [`f2e41f7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f2e41f74f185c13a89b49301e226e04948d4c088)
+- chore: release v1.6.0 [`8a18189`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8a181890479f46d5955d4f1bac3be759a2d39010)
+- fix(subagents): type-safe validation for persistent sidecar, ledger, and config parsing [`fe81be5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/fe81be5ca76eba504ff59fcf46ba3e9499753a70)
+- fix(orchestrate): parse review reports out of wrapped public delivery [`9f11918`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9f11918a407be39388999feeee16970e9d888105)
+- fix(subagents): close stopped persistent specialist panes (#32) [`8d0b6e7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8d0b6e7e9703fd7416e8ddc0ffb97dc26d48ab6b)
+- docs(context): define child wake-up signal and result delivery terms [`a3c159e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a3c159e2056d13be5697494a13bcb84bdcf92bab)
+- docs(subagents): clarify persistent help requests (#32) [`16e9363`](https://github.com/giuseppecrj/pi-herdr-agents/commit/16e9363180cf49b5e03003f5ea1e57b38ac8adbd)
+- docs(release): require workflow-worker.js absence in the pack preview (#31) [`9d40cc0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9d40cc0f3aa08ce203a720947bf097a4b66c9357)
+
+## [v1.5.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.0...v1.5.1) - 2026-09-05
 
 ### Merged
 
@@ -20,6 +72,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - fix(roles): reject malformed capability declarations (#27) [`0d263b8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0d263b8867e1708288302e0f9a5c9b806c810345)
 - fix(workflows): join child cleanup before terminal delivery (#25) [`e928817`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e9288172b8037b39ed04107ad0729292ea596a8f)
 - test(integration): assert cwd and session delivery structurally (#28) [`ec277ff`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ec277ff9ddf4b309edb1f12942acac68ee295eb2)
+- chore: release v1.5.1 [`ebef265`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ebef2657b0b21177373868d83d66965fdf77febd)
 
 ## [v1.5.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.2...v1.5.0) - 2026-09-05
 

package/CONTEXT.md

@@ -1,189 +1,101 @@
-# Feature Delivery
-
-This context defines language for the shipped first-flow workflow runtime and deferred follow-up. [`README.md`](./README.md) is authoritative for shipped behavior; [`docs/orchestrated-review-workflow-plan.md`](./docs/orchestrated-review-workflow-plan.md) records the shipped implementation and deferred work. The workflow coordinates existing subagent roles without becoming a general-purpose workflow engine.
+# Orchestration glossary
 
 ## Language
 
-**Feature-delivery workflow**:
-A bounded, user-approved plan that coordinates work needed to deliver one feature and ends in reviewable evidence.
-_Avoid_: General task graph, orchestrator agent
-
-**Workflow script**:
-The per-run `workflow.js` containing a runner-validated JSON metadata block and the user-approved executable strategy.
-_Avoid_: Execution plan, generic script, inferred policy
-
-**Workflow metadata**:
-The JSON block at the start of a workflow script that the runner parses and validates before loading any executable JavaScript.
-_Avoid_: Evaluated metadata, inferred policy
-
-**Approved runtime**:
-A mandatory exact `provider/model` reference and thinking level declared in workflow metadata; every execution node must resolve to one of these approved runtimes. Missing values fail preparation rather than inheriting parent or role defaults. All subagent and workflow execution is Pi-backed.
-_Avoid_: Runtime tiers, external CLI adapter, silent fallback, inherited runtime
-
 **Pi subagent runtime**:
-The single execution path for fresh and resumed children. `launchPiSubagent()` owns the complete Pi and Herdr launch transaction; completion uses Pi sidecar evidence first and the terminal exit marker as fallback.
+The single execution path for fresh and resumed children. `launchPiSubagent()`
+owns the complete Pi and Herdr launch transaction; completion uses Pi sidecar
+evidence first and the terminal exit marker as fallback.
 _Avoid_: Runtime dispatch, adapter registry, split launch ownership
 
-**Legacy external CLI role**:
-An old role definition that contains `cli`. Discovery reports a migration diagnostic, and launch fails before Herdr creates a pane or worktree. Remove `cli` and `cli-model`, then select the model through Pi provider/model routing.
-_Avoid_: Silent Pi reinterpretation, compatibility adapter
-
-**Run journal**:
-The runner-owned append-only `run.jsonl` that starts with approval binding the workflow-script hash, canonical repository identity, and committed base, then records observed node calls and results. Exactly one terminal event contains the bounded runtime envelope; a following delivery event references it without duplicating the task result.
-_Avoid_: User-authored plan, mutable audit log, duplicated result
-
-**Terminal lifecycle**:
-Every workflow terminal path stops queued work and accounts for active read and review panes before checkout disposal and final delivery. Completed panes close after result capture while child session files and run evidence remain. Unconfirmed child exit retains the checkout and ends failed with `cancel_termination_failed`. Writer-worktree retention belongs to a deferred writer workflow.
-_Avoid_: Retaining every clean pane, deleting review evidence
-
-**Restart boundary**:
-Workflow ownership survives Pi lifecycle transitions handled inside the same process, including `/reload`. A full process restart performs interruption reconciliation only: it marks a stale run interrupted, retains sessions, journals, branches, and worktrees as evidence, and requires a newly approved run. There is no replay, restart of children, cleanup, or history surface.
-_Avoid_: Automatic replay, durable workflow manager, lost-artifact claim
-
-**Execution artifact directory**:
-The project-local `.pi/plans/<run>/` directory that keeps its workflow script and run journal together.
-_Avoid_: Session-only state, runner-global artifacts
-
-**Execution run**:
-One immutable orchestration attempt with its own unique artifact directory; a retry or revised plan creates a new run that can reference its predecessor. Approval binds the canonical repository root, Git common directory, and committed base SHA. Read-only execution nodes share a run-owned checkout pinned to that identity.
-_Avoid_: Overwritten feature directory, mutable run history, parent-checkout reads, SHA-only repository ambiguity
-
-**Execution source**:
-A user-selected PRD, ticket set, URL, or combination that the orchestration skill reads before preparation. Local paths must resolve inside the approved repository; remote or tracker content is materialized into the exact approved script or prompt evidence rather than fetched by workflow children. Metadata source strings are provenance, not runtime read authority.
-_Avoid_: Required ticket conversion, fixed ticket graph, runtime refetch, path escape
-
-**Orchestration skill**:
-The user-facing native Pi skill bundled with this package that accepts an execution source, derives a workflow script, and invokes the runner only after approval. Its adversarial branch is a disclosed procedure in the same skill, not another engine or role.
-_Avoid_: Extension command, separate skill package, raw runner API, child-authored workflow
-
-**Adversarial review procedure**:
-The preferred `orchestrate` branch for exact approved review: two routine or three distinct-lens high-risk discovery reviewers, candidate-dependent cross-family verification, then fresh synthesis. It uses the existing runner and SDK.
-_Avoid_: Fixed `3 + 3 + 1`, confidence vote, new workflow engine
-
-**Compatibility review coordinator**:
-The transitional `adversarial-reviewer` role for public asynchronous child launches. It stays open across automatic result steers, counts terminal child envelopes by name, and calls `subagent_done` only after synthesis. Its Bash-enabled inspection contract is behavioral rather than an enforced read-only capability boundary.
-_Avoid_: Preferred hardened path, enforced read-only runner, auto-exit coordinator
-
-**Source resolution**:
-The orchestration skill reads an execution source through capabilities already available to the parent; the extension has no built-in tracker client and stops when the source is inaccessible.
-_Avoid_: Required tracker integration, silent fallback
+**Child wake-up signal**:
+An internal indication that prompts fresh inspection of an owned child. It does
+not itself establish completion, failure, or a help request.
+_Avoid_: Completion result, user alert
 
-**Execution node**:
-A bounded planned subagent run that may cover one, part of one, or several source tickets while retaining source traceability. The shipped first flow accepts only `kind: "review"`; `read` and `write` remain deferred kinds for later workflows.
-_Avoid_: Ticket, untracked child run, inferred effect, first-flow read/write node
+**Child result delivery**:
+The parent-facing handoff of a child run's observed outcome and available
+evidence. Receiving it does not establish that the work is correct or accepted.
+_Avoid_: Wake-up signal, acceptance
 
-**Review node**:
-A declared workflow execution identity that pins one role, exact runtime, and
-thinking level. Node IDs are unique within a workflow; several nodes can use
-the same role.
-_Avoid_: Role identity, implicit runtime, duplicate-role prohibition
+**No-progress advisory**:
+An internal warning that an active child shows no durable progress in its session
+JSONL or activity snapshot. It is advisory only and never changes the child's
+outcome or triggers recovery.
+_Avoid_: Hang verdict, automatic recovery, stall replacement
 
-**Writer lane (deferred)**:
-A possible later single write node and retained worktree; it is not part of the first review-only workflow and requires separate evidence and approval.
-_Avoid_: First-flow writer, parallel writers, shared-checkout writer
-
-**Read-only fan-out**:
-The shipped first flow runs bounded parallel review nodes, then one fresh synthesis node. A later writer workflow may define separate pre-write and post-write review stages.
-_Avoid_: Unbounded fan-out, first-flow writer, reviewing through a writer
-
-**Code-oriented orchestration**:
-The parent writes JavaScript against a narrow capability API so intermediate subagent results stay in code and only the final useful result returns to the parent context, similar in shape to Cloudflare Code Mode.
-_Avoid_: Direct parent turn per child result, broad generated tool API, security-equivalence claim
-
-**Workflow SDK**:
-The extension-private JavaScript API that workflow scripts use to launch and await policy-checked execution nodes through the existing subagent lifecycle. V1 exposes only `agent()` and `log()`; scripts use ordinary JavaScript control flow and `Promise.all`.
-_Avoid_: Public `subagent()` tool, third-party package API, speculative helper framework
-
-**Tool derivation**:
-The runner computes each node's effective tools from its resolved role, the hard maximum for its declared kind, and extension deny rules; `agent()` has no script-controlled `tools` option. Workflow children receive the exact derived list without public child-control tools such as `caller_ping`.
-_Avoid_: Script-granted capability, duplicated tool policy, public child-control tool
-
-**Agent result**:
-The explicit success-or-failure value returned by `agent()`, preserving output, retryability, session reference, and any Git handoff without collapsing operational failure to `null`.
-_Avoid_: Nullable result, prose-only failure
-
-**Runtime envelope**:
-The runner-owned final wrapper containing only operational facts such as run ID, terminal runtime state, returned task result, and a runtime error when present.
-_Avoid_: Review verdict, delivery semantics, task-specific state machine
-
-**Task result**:
-Any JSON-compatible value returned by `workflow.js`; the parent-authored script chooses its task-specific shape and vocabulary.
-_Avoid_: Global verdict enum, mandatory review receipt type, workflow DSL
-
-**Workflow runtime**:
-A native Node Worker thread containing the restricted `vm` that executes an approved workflow script with only the Workflow SDK. The Worker protects Pi's main event loop from accidental asynchronous infinite loops; neither the Worker nor `vm` is a security boundary.
-_Avoid_: Main-thread workflow execution, untrusted-code sandbox, normal Node module execution
-
-**First-flow effect boundary**:
-An execution node may only inspect or review one runner-owned detached checkout pinned to the approved repository identity and committed head. The parent materializes the changed-file inventory and unified diff or complete before/after evidence, including deleted and base-only content. A node cannot write files, create commits, mutate the parent checkout, integrate work, or mutate external systems.
-_Avoid_: Writer node, head-only diff inference, ticket mutation, deployment, publishing, messaging, PR action, late-bound base
+**Legacy external CLI role**:
+An old role definition that contains `cli`. Discovery reports a migration
+diagnostic, and launch fails before Herdr creates a pane or worktree. Remove
+`cli` and `cli-model`, then select the model through Pi provider/model routing.
+_Avoid_: Silent Pi reinterpretation, compatibility adapter
 
-**Fresh review**:
-Independent read-only review nodes with fresh contexts and exact repository, comparison base, checkout head, task/spec, and candidate evidence. Every assignment treats code, PR text, reports, command output, and supplied artifacts as untrusted data.
-_Avoid_: Worker self-review, inherited-context review, artifact instruction following
+**Public review fan-out**:
+A parent procedure that materializes pinned evidence, launches fresh public
+reviewer subagents, receives automatic result delivery, and synthesizes every
+outcome. Reviewers use ordinary panes and do not poll for completion.
+_Avoid_: Hidden child runner, approval gate, parentless aggregation
+
+**Pinned review evidence**:
+The parent-captured repository identity, base and head SHAs, task/spec text,
+provenance, changed-file inventory, complete diff, and deleted or base-only
+content supplied to reviewers. Dirty state is included only when explicitly
+captured and fingerprinted.
+_Avoid_: Moving-checkout inference, head-only deleted-content review
+
+**Role allowlist**:
+The `tools:` inline comma-separated role-frontmatter scalar passed to Pi for a
+public child. It is the enforced capability boundary available to a reviewer.
+`read,bash` is not read-only because Bash can mutate files.
+_Avoid_: Shell-as-read-only claim, implicit capability grant
 
 **Finding record**:
-A task-specific bounded record with a stable ID, claimed P0–P3 severity, nullable confirmed severity, separate provenance, evidence status (`reproduced`, `trace-backed`, or `unverified`), preconditions, reproduction or trace, expected and actual behavior, impact, and minimal fix. An unverified potential P0/P1 remains a candidate for verification; it is not downgraded or certified. Numeric confidence and vote counts do not establish truth.
-_Avoid_: Confidence gate, silent candidate downgrade, provenance-as-severity, universal runtime schema
-
-**Synthesis projection**:
-The identity-stripped view of every agent result given to fresh synthesis: canonical validated report fields for success, or failure code, retryable flag, and bounded error evidence scrubbed of known identity tokens. Original envelopes remain in script state; journal/session evidence retains their audit references. Session paths, child/runtime/provider names, and the separate audit mapping stay outside the synthesis prompt. Anonymization is presentation hygiene, not a sandbox or proof against bias.
-_Avoid_: Filtered result, raw identity-bearing envelope, security claim
-
-**Review-policy boundary**:
-The bundled skill authors review fan-out and synthesis, and exact-script approval binds that task strategy; the runner enforces operational capabilities and evidence without a fixed review receipt or data-flow state machine.
-_Avoid_: Hidden task semantics, runner-certified review completeness
-
-**Review workflow**:
-The first product flow: an approved JavaScript run fans out to fresh read-only reviewers, retains every explicit result, then sends every outcome through a synthesis projection to one fresh reviewer.
-_Avoid_: Parent-scheduled review nodes, filtered result, prose-only aggregation
-
-**Review synthesis**:
-The final fresh read-only review node that receives exact materialized source evidence and identity-stripped projections for every discovery and verification outcome, preserves finding provenance, resolves claims from evidence, and returns one task-specific result. Reviewer aliases and a predetermined report order reduce identity/order cues while the approval packet and journal retain auditable runtime provenance.
-_Avoid_: Filtered failures, raw identity metadata, mechanical worst-verdict rule, confidence voting, parent-side synthesis
-
-**Parent-guided recovery**:
-Current runtime child failures are explicit non-retryable evidence. The parent can approve a new smaller workflow for missing coverage. The bundled skill also contains one dormant same-node replacement branch, used only when a required failure explicitly has `retryable: true`; it never infers retryability from prose or runtime error text.
-_Avoid_: Error-text retry classification, silent model fallback, unbounded retries
+A bounded review record with a stable ID, claimed P0–P3 severity, nullable
+confirmed severity, separate provenance, evidence status (`reproduced`,
+`trace-backed`, or `unverified`), preconditions, reproduction or trace, expected
+and actual behavior, impact, and minimal fix. An unverified potential P0/P1 is
+a candidate for verification, not a certified finding.
+_Avoid_: Confidence gate, provenance-as-severity, vote count
 
 **Incomplete review**:
-A review-workflow task-result state chosen by the script when drift, failure, missing or truncated evidence, malformed task output, a child-reported coverage gap, or unresolved material verification leaves coverage unknown. Valid discovery, verification, or synthesis output with `status: INCOMPLETE` propagates even through `ok: true`. It is not a runner-owned terminal state.
-_Avoid_: Hidden missing coverage, runtime-wide review semantics, invented or certified-uncertain findings
-
-**Ready for integration (deferred)**:
-A possible later writer-workflow result containing retained commits, verification, and review evidence. It is not a first-flow result and cannot claim automatic acceptance.
-_Avoid_: First-flow handoff, ship verdict, automatic integration
-
-**Run assembly (deferred)**:
-A possible later post-writing step that combines writer commits on a run-owned branch without modifying the parent checkout; adoption requires a separate end-to-end prototype.
-_Avoid_: First-flow assembly, parent integration, automatic conflict repair
-
-**Delivery verdict (deferred)**:
-A possible later delivery workflow's task-specific recommendation, assembled in JavaScript from review evidence and accepted or rejected by the parent; its vocabulary would remain outside the runtime contract.
-_Avoid_: First-flow verdict requirement, runtime-wide verdict enum, automatic acceptance, worker self-acceptance
-
-**Workflow-script authority**:
-The parent is the only actor that may author or revise a workflow script; children can only return findings or recommendations.
-_Avoid_: Child-authored workflow script, self-modifying workflow
-
-**Execution approval**:
-An explicit `APPROVE <8-character SHA-256 prefix>` authorization entered by the user after preparation in the same active parent session to execute one exact workflow-script revision once. Preparation also binds resolved role behavior and tools; any change requires preparation and approval again. Parent-guided recovery creates a new run.
-_Avoid_: Pre-prepare approval, cross-session approval, friendly-ID mapping, reusable approval, implicit approval
-
-**Preflight discovery**:
-A parent-directed, read-only investigation after an orchestration request and before execution approval; it is not workflow execution.
-_Avoid_: Unapproved node, workflow execution
-
-## Prototype evidence
-
-### JavaScript review workflow — validated
-
-- **Question:** Can JavaScript await real Pi-backed Herdr children internally, fan review out, synthesize every final result, and return one value without public subagent steers?
-- **Primary source:** branch `prototype/js-review-workflow`, commit `4622e08731d31ccda1c33eb01cff5610d86d0166`
-- **Run:** `npm run prototype:review-workflow`
-- **Observed:** three parallel Luna reviewers and one Luna synthesizer completed; the prototype's synthetic replacement is historical evidence only and is not part of the shipped flow; every real child used only read-only tools; no child result entered the parent session; completed panes closed; the exact-base shared checkout was disposed; sessions and a 15-event journal remained.
-- **VM result:** `agent.constructor(...)` reached the host `process`, confirming that Node `vm` is not a security boundary.
-- **Event-loop result:** a separate Node 26.3 probe showed that the VM timeout stops a synchronous infinite loop but not one started after `await`; production workflow code must run in a terminable Worker thread rather than Pi's main event loop.
-- **Self-hosting result:** child `pi -ne -e subagent-done.ts` avoided duplicate loading of the repository and globally installed subagent extensions.
-- **Answered later:** cancel-all is shipped as `herdr_workflow cancel` under a process-global terminal gate: active panes capture Herdr process identities before close, checkout dispose requires confirmed exit, and unconfirmed termination retains the checkout and ends `failed` with `cancel_termination_failed`.
-- **Not answered:** writer review visibility; typed retryability remains deferred, while real launch-failure classification is covered by the shipped workflow failure envelope and same-process `/reload` ownership is covered by the process-global workflow owner.
+A review outcome for drift, failure, missing or truncated evidence, malformed
+output, coverage gaps, or unresolved serious candidates. A child-reported
+`INCOMPLETE` propagates to the parent result.
+_Avoid_: Hidden missing coverage, certified uncertainty
+
+**Persistent specialist**:
+A logical subagent that retains one policy-bound Pi session between sequential
+tasks until it is stopped or crashes.
+_Avoid_: Immortal process, reusable pane
+
+**Session generation**:
+One concrete Pi session serving a persistent specialist's logical identity.
+_Avoid_: Logical specialist, revived session
+
+**Task outcome**:
+The recorded terminal result for one persistent-specialist task, including
+`delivered`, `rejected-busy`, or a stop-pending task's eventual terminal state.
+_Avoid_: Assumed completion, replay candidate
+
+**Delivery ledger**:
+The append-only evidence record of persistent task dispatch and terminal
+outcomes for one session generation.
+_Avoid_: Work queue, mutable task list
+
+**Agents tab**:
+An extension-owned Herdr tab grouping delegated child panes in an existing
+checkout workspace. Ownership comes from returned IDs, not its display label.
+The pane cap includes every live pane; overflow creates another tab, not a
+workspace. Separate parent processes own separate groups.
+_Avoid_: Agent workspace, label-based ownership, automatic rearrangement
+
+**Retained checkout shell**:
+The interactive shell in a managed worktree's root pane, preserved after the
+child Pi process exits. Temporary review panes can close without deleting this
+surface or its checkout.
+_Avoid_: Completed agent process, disposable pane, automatic worktree cleanup
+
+**Worktree lease**:
+The lifetime-exclusive binding between a persistent specialist generation and
+one managed worktree, when that specialist writes in a worktree.
+_Avoid_: Rebindable checkout, shared worktree ownership