pi-herdr-agents 1.4.0 → 1.4.2

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

package/CHANGELOG.md

@@ -7,11 +7,33 @@ 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.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.3.1...v1.4.0)
+## [v1.4.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.1...v1.4.2)
+
+### 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)
+- 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
 
 ### Commits
 
 - test: disable commit signing in git fixtures [`c87e20d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c87e20dd3d4d7ff058b555759904de36bf881875)
+- chore: release v1.4.0 [`0480689`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0480689cc6914738406d0dab9c260744c7666df3)
 - feat: state the coordinator contract in always-visible guidelines [`08b1dc6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/08b1dc6ffdfbb4ef03289b0871cc4fbc48883032)
 - fix: stop implying every writing subagent needs a worktree [`114c239`](https://github.com/giuseppecrj/pi-herdr-agents/commit/114c239f71666a8a9c9a2c8705197b70c5f4e7a2)
 - fix: point reviewers of worktree results at the retained worktree path [`4d84718`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4d84718ada823eba830195e865c327155f37a8dd)

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
 
@@ -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. |
+| Adversarial review | `adversarial-reviewer` | Directly runnable coordinator role that selects eligible authenticated Pi runtimes, launches leaf `reviewer` children in ordinary panes for generic review passes, and uses a fresh reviewer synthesis pass. It does not write artifacts in the reviewed checkout. |
 
 ### 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** | Coordinator agent role | Three distinct eligible authenticated Pi model IDs, preferring provider diversity | Runs evidence-backed Optimizer and Skeptic passes through leaf `reviewer` children in ordinary panes, then a fresh reviewer synthesis pass. |
 
 All subagents execute through Pi. Claude models remain available through normal
 Pi provider/model routing. Legacy role definitions that contain `cli` fail before
@@ -423,6 +423,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 +439,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.
@@ -514,11 +522,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
 ```
 
@@ -727,7 +735,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 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 +765,12 @@ 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 `agent_end` 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
+- The session closes on `agent_end` when the latest assistant turn does not have `stopReason: "aborted"`; a normal or error stop exits, while an aborted stop stays open.
+- User input does not permanently disable auto-exit; the latest 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 +841,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` | Launches leaf reviewer passes and synthesis. |
+| 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

package/docs/adr/0002-agent-workflow-skill-runtime-taxonomy.md

@@ -194,7 +194,8 @@ project authors can still add their own namespaced fields.
   `chrome-cdp` dependency declared through canonical `skills` metadata.
 - `claude-reviewer` — Removed. Use the generic `reviewer` role with an
   authenticated Claude model through Pi provider/model routing.
-- `adversarial-reviewer` — Transitional workflow implementation. It applies
+- `adversarial-reviewer` — Transitional workflow implementation (now shipped
+  and documented as a coordinator agent role). It applies
   project review constraints, selects three distinct eligible exact
   authenticated Pi model IDs, and launches generic `reviewer` children followed
   by fresh reviewer synthesis. Do not clone this pattern for new outcomes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",
@@ -30,6 +30,8 @@
   "type": "module",
   "scripts": {
     "changelog": "auto-changelog",
+    "format": "biome format --write pi-extension test",
+    "format:check": "biome format pi-extension test",
     "lint": "oxlint pi-extension test",
     "test": "node --experimental-strip-types --test test/test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/workflow.test.ts test/package-skill.test.js",
     "test:integration": "node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
@@ -57,11 +59,13 @@
     "image": "https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.5.11",
     "@earendil-works/pi-ai": "^0.84.0",
     "@earendil-works/pi-coding-agent": "^0.84.0",
     "@earendil-works/pi-tui": "^0.84.0",
+    "@oxlint/plugins": "^1.80.0",
     "@sinclair/typebox": "^0.34.52",
     "auto-changelog": "^2.6.0",
-    "oxlint": "^1.73.0"
+    "oxlint": "^1.80.0"
   }
 }