pi-herdr-agents 1.4.1 → 1.5.0

package/AGENTS.md

@@ -84,6 +84,7 @@ For normal changes:
 
 ```bash
 npm test
+npm run format:check
 npm run lint
 npm pack --dry-run
 git diff --check
@@ -104,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`, 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`, `skills/orchestrate/adversarial-review-example.js`, and `pi-extension/subagents/workflow-worker.js`, while excluding 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,12 +7,48 @@ 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.4.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.0...v1.4.1)
+## [v1.5.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.2...v1.5.0)
+
+### Merged
+
+- Add configurable split-pane subagent launches (#16) [`#23`](https://github.com/giuseppecrj/pi-herdr-agents/pull/23)
+- Close owned panes after failed subagent launches (#18) [`#22`](https://github.com/giuseppecrj/pi-herdr-agents/pull/22)
+- Allow disabling bundled agent roles (#14) [`#21`](https://github.com/giuseppecrj/pi-herdr-agents/pull/21)
+- Fix premature subagent completion during compaction (#17) [`#20`](https://github.com/giuseppecrj/pi-herdr-agents/pull/20)
+- Harden adversarial review workflows and add evaluation coverage [`#19`](https://github.com/giuseppecrj/pi-herdr-agents/pull/19)
+
+### Commits
+
+- feat: harden adversarial review workflows and evaluation [`38a69e8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/38a69e80c92d684f104c22f9f435a5ae30468750)
+- fix: enforce lint and format coverage for shipped review helper [`116c9ff`](https://github.com/giuseppecrj/pi-herdr-agents/commit/116c9ffd301e7b72e99feb677d11531643c0dba3)
+- fix: enforce adversarial review workflow contracts [`7920e1a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7920e1ad3231a893284f716c017d918ade9d4410)
+- feat: support split panes for public subagent launches [`4b9f217`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4b9f2179dae252cb2ea708adcceb9219d5604181)
+- fix: wait for settled agent runs before auto-exit [`b6a5ab8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b6a5ab82ad0b948194a85c3e1116e6fb4b22ffc0)
+- fix: close transaction-owned panes after failed launches [`266301a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/266301a30c352f4fb66802d17e9cb766d3a00b7f)
+- feat: allow disabling bundled agent roles [`e866ade`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e866ade49f35c7bd51931c1e216fd9749abca2e8)
+- fix: distinguish role-pack replacements from bundled warnings [`d4452c8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d4452c8994c61607d2c1d1259679c1b7f7be8780)
+- fix: address evaluation validator review findings [`406d1ab`](https://github.com/giuseppecrj/pi-herdr-agents/commit/406d1ab9e1a129d336ed0b850508d335b130e156)
+
+## [v1.4.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.1...v1.4.2) - 2026-08-31
+
+### Commits
+
+- style: format source with Biome [`06d67d7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/06d67d7c2fa48be6eb5ae7a11e165208da9a228e)
+- style: format workflow-review integration test [`1215dc5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/1215dc58db7e98abb1a18278ca892432c519f6ac)
+- chore: add Biome formatter [`5b6aef3`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5b6aef316c1183bf094d893c88624972762380d5)
+- fix: neutralize line breaks in launch script comments [`ae3c52f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ae3c52f4a66c9075a14526c30fe8801ab85b35f4)
+- docs: align README with shipped coordinator and workflow behavior [`cc55c68`](https://github.com/giuseppecrj/pi-herdr-agents/commit/cc55c68fc1cc03a28642797eaf1a19c0317aec6c)
+- chore: release v1.4.2 [`5c38516`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5c38516bb78707c55682ee0e85ad991719332027)
+- fix: correct the adversarial-reviewer worktree warning [`7518567`](https://github.com/giuseppecrj/pi-herdr-agents/commit/75185675d589adc3511f40722420387c2dc647fd)
+- ci: run format:check in the release workflow [`bc5b998`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bc5b99819833158623b115587e75c37ae8ead009)
+
+## [v1.4.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.0...v1.4.1) - 2026-08-31
 
 ### Commits
 
 - chore: install anti-slop lint rules [`633766b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/633766b434e9558df67650b458a7d4536ac9ffd6)
 - refactor: satisfy anti-slop lint rules [`d9cbf1d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d9cbf1dbc9442971260414fd52ff20a49a2cde88)
+- chore: release v1.4.1 [`49d50e2`](https://github.com/giuseppecrj/pi-herdr-agents/commit/49d50e2cd64abed8a74db46c103b22e944a5c614)
 - test: stop asserting a deterministic reviewer start order [`edd848e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/edd848ee8057290a7d47f7260b65ba29d832bec5)
 
 ## [v1.4.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.3.1...v1.4.0) - 2026-08-31

package/CONTEXT.md

@@ -53,8 +53,16 @@ A user-selected PRD, ticket set, URL, or combination that the orchestration skil
 _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.
-_Avoid_: Extension command, separate skill package, raw runner API
+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.
@@ -107,32 +115,40 @@ A native Node Worker thread containing the restricted `vm` that executes an appr
 _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 base. It cannot write files, create commits, mutate the parent checkout, integrate work, or mutate external systems.
-_Avoid_: Writer node, ticket mutation, deployment, publishing, messaging, PR action, late-bound base
+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
 
 **Fresh review**:
-Independent read-only review nodes with fresh contexts and the exact source or candidate evidence; the bundled authoring skill requires them in every first-flow script.
-_Avoid_: Worker self-review, inherited-context 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
+
+**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 independent read-only reviewers, then passes every explicit result to one fresh review synthesizer.
-_Avoid_: Parent-scheduled review nodes, prose-only aggregation
+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 every explicit reviewer success or failure plus exact source evidence, deduplicates or resolves findings, and returns one review verdict.
-_Avoid_: Filtered failures, mechanical worst-verdict rule, parent-side 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
 
 **Incomplete review**:
-A review-workflow task-result state chosen by the script when a declared reviewer fails; it is not a runner-owned terminal state.
-_Avoid_: Hidden missing coverage, runtime-wide review semantics
+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.

package/README.md

@@ -76,7 +76,7 @@ subagent({ name: "DB scout", agent: "scout", model: "<provider>/<fast-tier-id>",
 // Both return immediately; each result comes back independently.
 ```
 
-Use ordinary panes for read-only agents. A single or sequential writer can work in the parent checkout; give each parallel independent writing agent a unique managed worktree. See [Worktree subagents](docs/worktree-subagents.md).
+Use ordinary panes for read-only agents. A single or sequential writer can work in the parent checkout; give each parallel independent writing agent a unique managed worktree. The parent acts as coordinator: decompose work, give each child one bounded outcome with its goal, allowed files, verification, and commit instruction, and keep dependent writes sequential. Children are leaves by default; the parent owns integration and final verification. See [Worktree subagents](docs/worktree-subagents.md).
 
 ## How it works
 
@@ -112,7 +112,7 @@ pi install git:github.com/giuseppecrj/pi-herdr-agents@main
 
 Smoke-test delivery with an autonomous subagent instructed to return one exact marker. Success means the marker itself—not only a generic wake-up notice—automatically appears in the parent turn.
 
-Subagent tabs, panes, and worktree workspaces are created without stealing keyboard focus. Launch commands target child panes by explicit ID, so focus and command delivery are independent. Note: the `interactive` option controls parent status notifications, not terminal focus.
+Subagent tabs, panes, and worktree workspaces are created without stealing keyboard focus. Launch commands target child panes by explicit ID, so focus and command delivery are independent. If a fresh or resumed launch fails, the extension closes the ordinary pane that it created and preserves the original launch error. It does not close a caller-supplied surface, and managed worktree workspaces remain retained on failure. Note: the `interactive` option controls parent status notifications, not terminal focus.
 
 ## What's Included
 
@@ -162,12 +162,12 @@ The current workflow inventory is:
 
 | Workflow | Entry point | Composition, artifacts, and runtime |
 | -------- | ----------- | ----------------------------------- |
-| Planning | `/plan` | Scout → interactive planner → workers → reviewer; writes `.pi/plans/...` artifacts; runs on Pi. |
+| Planning | `/plan` | Autonomous scout → interactive planner → workers → reviewer; writes `.pi/plans/...` artifacts; runs on Pi. |
 | Iteration | `/iterate` | Opens one interactive full-context Pi fork and returns its completion summary. |
 | Side question | `/btw`, `/btw-close` | Opens one replaceable interactive Pi side session; its answer stays outside the parent transcript. |
 | Worktree handoff | `/worktree <name> [task]`, `/worktree list` | Forks the active conversation into a long-lived interactive Pi process in a new worktree created from committed `HEAD`; retains the parent session. |
-| Approved review runner | `herdr_workflow` (low-level control tool) | Validates and runs exact approved project-local JavaScript with bounded read-only Pi reviewers. The bundled `orchestrate` skill authors this first-flow topology. |
-| Adversarial review | `adversarial-reviewer` | Transitional workflow implementation that selects eligible authenticated Pi runtimes for generic reviewer passes, verifies findings, and uses a fresh reviewer synthesis pass. It does not write artifacts in the reviewed checkout. |
+| Approved review runner | `herdr_workflow` (low-level control tool) | Validates and runs exact approved project-local JavaScript with bounded read-only Pi reviewers. The bundled `orchestrate` skill authors generic and adversarial review topologies. |
+| Adversarial review | `/skill:orchestrate` (preferred), `adversarial-reviewer` (compatibility) | The preferred procedure uses exact approval, a pinned runner-owned checkout, risk-based discovery, candidate-dependent verification, and fresh synthesis. The compatibility coordinator uses public asynchronous children when the hardened prerequisites are unavailable. |
 
 ### Bundled visible definitions
 
@@ -179,7 +179,7 @@ The current workflow inventory is:
 | **reviewer** | Leaf agent role | Config, then parent | Reviews changes for correctness, security, and maintainability. |
 | **visual-tester** | Leaf agent role | Config, then parent | Performs visual QA through the `chrome-cdp` skill. |
 | **poteto** | Coordinator agent role | Config, then parent | Autonomously investigates, edits minimally, delegates independent work, and verifies. |
-| **adversarial-reviewer** | Transitional workflow implementation | Three distinct eligible authenticated Pi model IDs, preferring provider diversity | Runs evidence-backed Optimizer and Skeptic passes through generic `reviewer` children, then a fresh reviewer synthesis pass. |
+| **adversarial-reviewer** | Compatibility coordinator role | Exact eligible authenticated Pi models selected by risk and project policy | Runs two routine or three high-risk discovery reviewers, candidate-dependent cross-family verification, and fresh synthesis through public asynchronous children. |
 
 All subagents execute through Pi. Claude models remain available through normal
 Pi provider/model routing. Legacy role definitions that contain `cli` fail before
@@ -189,7 +189,7 @@ authenticated Pi `provider/model-id`.
 Optional prerequisites fail closed and are not bundled:
 
 - `visual-tester` needs an external `chrome-cdp` skill that provides `scripts/cdp.mjs`.
-- `adversarial-reviewer` needs three distinct exact authenticated Pi model IDs that meet project review constraints; it prefers IDs from different providers when available.
+- Adversarial review needs a resolved standalone `reviewer` role, confirmed human-only authorship or known author model families, and enough distinct exact authenticated Pi models to satisfy project author-family exclusion and cross-family verification. Routine discovery uses two distinct IDs; concrete high-risk surfaces use three distinct lenses. The preferred `orchestrate` procedure fails closed when its pinned committed checkout, complete diff evidence, origin, or runtime prerequisites are unavailable. The compatibility coordinator can use a project-approved reduced topology only when it discloses the omitted coverage.
 - `/plan` uses the bundled scout and planner roles and records ordered tasks in
   `plan.md`; it does not require a researcher role, todo tool, or `write-todos` skill.
 
@@ -298,11 +298,18 @@ cp config.json.example config.json
   },
   "models": {
     "agents": {}
+  },
+  "roles": {
+    "bundled": true
+  },
+  "panes": {
+    "mode": "tab",
+    "direction": "right"
   }
 }
 ```
 
-If `config.json` is absent, status settings fall back to `config.json.example`.
+If `config.json` is absent, status, role, and pane settings fall back to `config.json.example`.
 Model routing does not read the example: no model overrides apply until a real
 `config.json` exists.
 
@@ -322,6 +329,12 @@ exact IDs from your authenticated model catalog:
 }
 ```
 
+Set `roles.bundled` to `false` to exclude this package's bundled role definitions from listing and exact-name launch. It defaults to `true`. Registered role packs remain available, and global and project definitions keep their existing precedence. A role-pack name collides with a bundled role only while that bundled layer is enabled; when it is disabled, the role pack can supply that name.
+
+Set `panes.mode` to `"split"` to open ordinary public `subagent` and `subagent_resume` launches, including bare forks and `/iterate`, as splits of the stable parent pane. Set `panes.direction` to `"right"` or `"down"`; it defaults to `"right"` and is ignored when mode is `"tab"`. The default `"tab"` mode preserves existing behavior. Managed worktrees still use separate workspaces, while approved workflow readers and `/btw` keep their existing tab behavior.
+
+Run `/reload` after changing role, model, or pane settings.
+
 `models.default` sets the model for subagents that do not specify a model.
 `models.agents` sets per-agent defaults, keyed by the agent name passed to
 `subagent({ agent: ... })`. Explicit `model` tool arguments take precedence,
@@ -339,7 +352,7 @@ only, to keep approved workflow runtimes deterministic.
 `config.json` is gitignored in the source tree so local overrides are not
 committed from a checkout. On an installed package root, treat it as disposable
 local state that package updates may replace. Run `/reload` after changing it;
-status and model configuration are loaded when the extension starts.
+status, model, role, and pane configuration are loaded when the extension starts.
 
 ---
 
@@ -399,7 +412,7 @@ prompts, handoffs, and results.
 
 Use one worktree per parallel independent writing task; a single or sequential writer can work in the parent checkout, and read-only agents use ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
 
-A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a coordinator that uses an ordinary pane for its child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings.
+A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a compatibility coordinator that uses an ordinary pane for its child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings. A `read,bash` allowlist is not an enforced read-only boundary because shell commands can mutate files; report-only roles must restrict Bash to safe inspection and avoid artifact-generating verification in the reviewed checkout.
 
 The child starts at the returned worktree root. Tell writing agents to test and commit when you want a commit-based handoff, and tell them not to push, merge, switch branches, or remove the worktree. The parent owns review and integration.
 
@@ -423,6 +436,8 @@ subagent_interrupt({ name: "Scout" });
 
 This sends Escape to the child pane, cancelling the in-progress model turn. The subagent session stays alive — the pane, session file, and background polling all remain intact. After the interrupt, the widget immediately labels the child as `interrupted` (counted as **open**, not active processing). Stale pre-interrupt activity snapshots are ignored so a lagging Herdr/`active` reading cannot overwrite the interrupt. The process elapsed timer keeps running because the pane is still open; only the interrupted-state duration freezes relative to the interrupt request. If the child starts work later, newer observations return it to `active`; completion, failure, and `caller_ping` still flow through normally.
 
+`id` and `name` are each optional, but execution requires one usable target: an exact running ID or an exact, unambiguous display name. When both are supplied, `id` is used. Duplicate names are rejected.
+
 This is a turn-level interrupt, not a method for forcibly terminating a subagent session.
 
 ---
@@ -437,11 +452,17 @@ herdr_workflow({ action: "start", runId: "run-1" }); // after APPROVE <hash pref
 herdr_workflow({ action: "cancel", runId: "run-1" });
 ```
 
+Parameters:
+
+- `action` (required): `prepare`, `start`, or `cancel`.
+- `path` (required for `prepare`): Path to the workflow script.
+- `runId` (required for `cancel` and `start`): For `start`, it must match the pending run.
+
 ### Prepare and start contract
 
 - The script must be `<project>/.pi/plans/<run>/workflow.js` in a trusted Git repository with no existing adjacent `run.jsonl`.
-- Its first comment contains strict version-1 JSON metadata that binds the exact committed base, source provenance, distinct review-node IDs and their roles, authenticated `provider/model` references, thinking levels, and per-run caps that cannot exceed the fixed limits.
-- Fixed workflow caps: 256 KiB source, 8 agents, concurrency 4, 30-minute deadline, 100,000-character prompts, 100 logs × 4,000 characters, and 64 KiB serialized task result. Metadata may only lower caps.
+- Its first comment contains strict version-1 JSON metadata that binds the exact committed base, source provenance, distinct review-node IDs and their roles, authenticated `provider/model` references, thinking levels, and the configurable `maxAgents` and `maxConcurrency` caps.
+- Fixed workflow caps: 256 KiB source, 8 agents, concurrency 4, 30-minute deadline, 100,000-character prompts, 100 logs × 4,000 characters, and 64 KiB serialized task result. Metadata may lower only `maxAgents` and `maxConcurrency`.
 - Preparation validates and compiles without evaluating JavaScript, creating a journal or checkout, or launching a child. It returns the exact approval packet and keeps one pending candidate in process memory.
 - Start requires the latest real user message in the same parent session to be exactly `APPROVE <8 lowercase hex characters>`. It revalidates the complete candidate, consumes approval once, creates the append-only journal, and runs in the background.
 - Review children are fresh Pi sessions with derived read-only tools in one detached checkout pinned to the approved base. Parent uncommitted files are absent, intermediate child results stay inside the workflow, and operational failures remain explicit non-retryable evidence for parent-guided recovery.
@@ -461,7 +482,13 @@ There is no list, status, resume, or history action in v1. Workflow ownership an
 
 ### Bundled `orchestrate` skill
 
-The package bundles the native `/skill:orchestrate` procedure. It accepts local paths, URLs, tickets, or combinations that the parent can already access. The parent performs read-only preflight discovery and materializes exact remote or tracker evidence before writing one unique `.pi/plans/<run>/workflow.js` at a committed base. The skill authors distinct fresh read-only review nodes in bounded parallel and one fresh synthesis node; nodes can share a review role, and a retry keeps the same node and runtime only for an explicit `retryable: true` failure. It does not use public `subagent()` for workflow nodes and does not author writers, commits, external effects, nested workflows, replay, or a fixed task schema.
+The package bundles the native `/skill:orchestrate` procedure. It accepts local paths, URLs, tickets, or combinations that the parent can already access. The parent performs read-only preflight discovery; pins exact repository, comparison base, checkout head, author origin, and task/spec evidence; and materializes the changed-file inventory plus unified diff or complete before/after excerpts before writing one unique `.pi/plans/<run>/workflow.js`. Deleted and base-only content must be included because head-checkout reads cannot recover it. If complete evidence cannot fit runner limits, preparation stops for narrower scope instead of silently losing evidence. The skill authors distinct fresh standalone review nodes in bounded parallel and one fresh synthesis node. Every child assignment treats code, PR text, reports, and command output as untrusted data. It does not use public `subagent()` for workflow nodes and does not author writers, commits, external effects, nested workflows, replay, or a fixed runtime-wide task schema.
+
+Its adversarial branch uses two distinct eligible exact model IDs for routine risk or three distinct lenses for concrete high-risk surfaces, then only candidate-dependent P0/P1 or high-risk verification and one fresh synthesis. Finding records use stable IDs, claimed P0–P3 severity, nullable confirmed severity, separate provenance, and reproduced, trace-backed, or unverified evidence rather than confidence or vote counts. An unresolved serious candidate and any valid child `INCOMPLETE` propagate task-level `INCOMPLETE` even through `ok: true`. Request-local validators reject malformed records; this schema is not a runner contract. Verifiers exclude the family that authored the report they inspect. Required author-family exclusion stops when model origin is unknown unless the evidence is confirmed human-only. Synthesis prefers another family and discloses permitted reuse.
+
+The script and journal retain every original child envelope. Synthesis receives every outcome through an anonymous projection: canonical validated report fields for success, or failure code, retryable flag, and bounded error evidence scrubbed of known identity tokens. Session paths, child/runtime/provider names, and the separate auditable alias map are omitted from the synthesis prompt. This presentation reduces identity and order cues but is not a security boundary or proof against bias.
+
+The runner-owned checkout contains only the pinned commit. Parent staged, unstaged, and untracked state is not review evidence. Effective child tools are the resolved role allowlist intersected with the runner maximum (`read`, `grep`, `find`, and `ls`) and deny rules. Public `subagent` results can be abbreviated above 16,000 characters, but workflow scripts receive complete child reports within their explicit bounds. Operational failures are preserved without silent fallback; recovery is a new exact approved run.
 
 The parent calls `herdr_workflow prepare`, presents its packet unchanged, and waits for the exact `APPROVE <8-character lowercase hash prefix>` reply before calling `start`. After start, one final delivery is sent without polling. Cancellation is fail-closed and retains evidence when process exit cannot be confirmed. Same-process `/reload` preserves ownership; full restart records interruption without replay, restart, cleanup, or history. Workflow JavaScript runs in a Worker-hosted `vm` for event-loop availability only; neither the Worker nor `vm` is a security boundary, and worktrees do not provide process or security isolation.
 
@@ -480,7 +507,7 @@ The `caller_ping` tool lets a Pi-backed subagent request help from its parent ag
 - `sessionPath` (required): Path to the child session `.jsonl` file
 - `name` (optional): Display name for the resumed pane (defaults to `Resume`)
 - `message` (optional): Follow-up prompt to send after resuming
-- `autoExit` (optional): Whether the resumed session should auto-exit after its next response. Defaults to `true` for autonomous follow-up work; set `false` when resuming for an interactive handoff.
+- `autoExit` (optional): Whether the resumed session should auto-exit after its next response fully settles. Defaults to `true` for autonomous follow-up work; set `false` when resuming for an interactive handoff.
 
 **Interaction flow:**
 
@@ -514,11 +541,11 @@ The `/plan` command orchestrates a full planning-to-implementation pipeline.
 ```
 
 ```
-Phase 1: Investigation    → Quick codebase scan
+Phase 1: Investigation    → Autonomous scout maps the codebase
 Phase 2: Planning         → Interactive planner subagent (user collaborates)
 Phase 3: Review Plan      → Confirm ordered tasks, adjust if needed
-Phase 4: Execute          → Sequential workers, or isolated parallel workers for independent tasks
-Phase 5: Integrate        → Parent reviews and integrates worktree branches one at a time
+Phase 4: Execute          → Shared-checkout sequential workers by default; isolated parallel workers for independent tasks
+Phase 5: Integrate        → Parent reviews and integrates worktree branches one at a time, only when worktrees are used
 Phase 6: Review           → Reviewer subagent checks the integrated changes
 ```
 
@@ -691,9 +718,9 @@ the files, derives package name/version from the nearest `package.json`, and
 reports invalid paths, missing descriptions, filename/name mismatches, and
 package-layer collisions in the listing surfaces.
 
-Role packs cannot replace bundled roles, and duplicate role names from multiple
-role packs are disabled rather than resolved by extension load order. Use a
-global or project definition for an intentional override.
+Role packs cannot replace an enabled bundled role, and duplicate role names
+from multiple role packs are disabled rather than resolved by extension load
+order. Use a global or project definition for an intentional override.
 
 See [ADR-0003](docs/adr/0003-installable-role-packs.md) for the registration seam,
 collision rules, and rejected alternatives.
@@ -727,7 +754,7 @@ and verify them with `/subagent list` plus a smoke launch.
 | `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |
 | `spawning`    | boolean | Set `false` to deny all subagent-spawning tools                                                                                                                                                                                                                             |
 | `deny-tools`  | string  | Comma-separated `pi-herdr-agents` tool names to suppress; this is not a universal cross-extension deny list                                                                                                                                                                  |
-| `auto-exit`   | boolean | Auto-shutdown when the agent finishes its turn — no `subagent_done` call needed. If the user sends any input, auto-exit is permanently disabled and the user takes over the session. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
+| `auto-exit`   | boolean | Auto-shutdown after Pi fully settles when the latest assistant turn does not end with `stopReason: "aborted"` — no `subagent_done` call needed. User input does not permanently disable auto-exit. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
 | `interactive` | boolean | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |
 | `cwd`         | string  | Default working directory. Absolute paths are unambiguous; relative agent-frontmatter paths resolve from Pi's agent config directory (`PI_CODING_AGENT_DIR` or `~/.pi/agent`), not the project root                                                                                                                                                                                                            |
 | `disable-model-invocation` | boolean | Hide a role from discovery surfaces like `subagents_list`. The definition remains directly invocable by exact name via `subagent({ agent: "name", ... })`. |
@@ -757,12 +784,13 @@ session-mode: lineage-only
 
 ### `auto-exit`
 
-When set to `true`, the agent session shuts down automatically as soon as the agent finishes its turn — no explicit `subagent_done` call is needed.
+When set to `true`, the agent session shuts down on Pi's `agent_settled` event unless the latest assistant message has `stopReason: "aborted"` — no explicit `subagent_done` call is needed.
 
 **Behavior:**
 
-- The session closes after the agent's final message (on the `agent_end` event)
-- If the user sends **any input** before the agent finishes, auto-exit is permanently disabled for that session — the user takes over interactively
+- Low-level `agent_end` events do not close the session because Pi may still retry, compact and retry, or process a queued continuation.
+- After `agent_settled`, a normal or error stop exits, while an aborted stop stays open.
+- User input does not permanently disable auto-exit; the latest settled assistant stop reason determines whether the session exits.
 - The modeHint injected into the agent's task is adjusted accordingly: autonomous agents see "Complete your task autonomously." rather than instructions to call `subagent_done`
 
 **When to use:**
@@ -833,12 +861,15 @@ deny-tools: subagent
 
 ### Recommended Configuration
 
-| Agent      | `spawning`  | Rationale                                    |
-| ---------- | ----------- | -------------------------------------------- |
-| planner    | *(default)* | Legitimately spawns scouts for investigation |
-| worker     | `false`     | Should implement tasks, not delegate         |
-| reviewer   | `false`     | Should review, not spawn                     |
-| scout      | `false`     | Should gather context, not spawn             |
+| Agent | `spawning` | Rationale |
+| --- | --- | --- |
+| planner | *(default)* | Can spawn scouts for investigation. |
+| poteto | `true` | Delegates independent work. |
+| adversarial-reviewer | `true` | Compatibility coordinator; launches bounded discovery, conditional verification, and synthesis children. It sets `auto-exit: false` so automatic child-result steers can drive every wave, then calls `subagent_done`. |
+| worker | `false` | Implements bounded tasks. |
+| reviewer | `false` | Reviews without delegation. |
+| scout | `false` | Gathers context without delegation. |
+| visual-tester | `false` | Performs visual QA without delegation. |
 
 ---
 

package/RELEASING.md

@@ -21,6 +21,7 @@ Automated release gates (run by the workflow and required locally):
 
 ```bash
 npm ci
+npm run format:check
 npm run lint
 npm test
 npm pack --dry-run
@@ -40,7 +41,7 @@ The optional live-provider smoke test is not a release gate:
 PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run test:integration:live
 ```
 
-Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `agents/`, `skills/orchestrate/SKILL.md`, and `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, and local `config.json`, and that the worktree integration tests leave no test workspace behind.
+Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `agents/`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, `skills/orchestrate/adversarial-review-example.js`, and `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, and local `config.json`, and that the worktree integration tests leave no test workspace behind.
 
 ## npm authentication