pi-herdr-agents 0.0.1

package/AGENTS.md

@@ -0,0 +1,116 @@
+# Repository instructions for agents
+
+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 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.
+
+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.
+
+## Read these first
+
+- [`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
+- [`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).
+
+## 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/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/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
+- `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
+
+## Worktree contract
+
+Preserve these invariants when changing worktree behavior:
+
+1. `worktree: { branch, base? }` is opt-in per `subagent` call.
+2. `cwd` selects the source repository; the child starts at the created worktree root.
+3. `base` resolves to an exact commit before creation and defaults to committed `HEAD`.
+4. Parent uncommitted/untracked files are not copied.
+5. An ownership manifest is written before Herdr resource creation.
+6. Herdr creates the workspace without stealing focus; launch targets the returned root pane explicitly.
+7. Successful, failed, and help-requesting runs retain their worktree workspace.
+8. Completion reports reviewable Git state; inspection failures are unknown, never guessed clean or conflict-free.
+9. The extension does not push, create PRs, merge, cherry-pick, switch the parent checkout, or remove worktrees/branches automatically.
+10. Ordinary non-worktree subagent behavior remains unchanged.
+
+Read [`docs/worktree-subagents.md`](docs/worktree-subagents.md) before changing any of these semantics.
+
+## Orchestration guidance
+
+- Use ordinary panes for read-only scouts and reviewers.
+- Use unique worktree branches for independent parallel writing tasks.
+- Keep overlapping or dependent writing tasks sequential unless the dependency is committed and used as the next exact base.
+- Tell worktree workers whether to commit. A good default is: edit, test, commit, report the SHA, and do not push/merge/remove.
+- The parent owns review, integration, publication, and cleanup.
+- Do not use `subagent_resume` as if it reattached worktree ownership; v1 resumes into an ordinary pane.
+
+## Documentation synchronization
+
+When behavior changes, update every affected surface in the same commit:
+
+- public tool parameters, role-pack protocol, or lifecycle → `README.md`
+- role-pack discovery, precedence, or collision policy → `docs/adr/0003-installable-role-packs.md`
+- worktree behavior, handoff, recovery, or cleanup → `docs/worktree-subagents.md`
+- agent operating expectations → relevant files in `agents/`
+- `/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`
+- 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.
+
+## Verification
+
+For normal changes:
+
+```bash
+npm test
+npm run lint
+npm pack --dry-run
+git diff --check
+```
+
+Run LSP diagnostics on every changed TypeScript file; lint and tests do not catch every TypeScript error.
+
+For Herdr or lifecycle changes, run the deterministic suite from inside Herdr. Run only one integration suite at a time on a Herdr instance; concurrent suites compete for terminal focus and process capacity and can cause false timeouts or leaked test resources.
+
+```bash
+npm run test:integration
+```
+
+Use `PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run test:integration:live` only for optional provider-compatibility smoke coverage. Do not use skipped Herdr tests as passing evidence.
+
+Before committing:
+
+- inspect `git status` and the final diff;
+- confirm the package preview includes `skills/orchestrate/SKILL.md` 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:
+
+```bash
+test -z "$(find . -mindepth 1 -maxdepth 1 -type d -empty -print)"
+```
+
+## Release safety
+
+Do not bump `package.json` merely to land documentation or implementation work. A version change on `main` triggers the release workflow. Never commit npm credentials, generated review artifacts, session artifacts, or local `config.json`.

package/CONTEXT.md

@@ -0,0 +1,159 @@
+# 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.
+
+## 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. The first workflow supports Pi-backed agents only; existing public Claude subagents remain unchanged.
+_Avoid_: Runtime tiers, silent fallback, inherited runtime, v1 Claude workflow 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**:
+Completed read and review panes close after result capture while child session files and run evidence remain. 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.
+_Avoid_: Extension command, separate skill package, raw runner API
+
+**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
+
+**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
+
+**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 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
+
+**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
+
+**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
+
+**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
+
+**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-role 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
+
+**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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HazAT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.