pi-agent-replicate 0.0.0-stage → 1.4.1

package/AGENTS.md

@@ -0,0 +1,27 @@
+# Pi Agent Replicate
+
+`CONTEXT.md` holds the product intent and the contracts of the `replicate` tool. Read it before changing the tool, its schema or how it is presented. Read the matching document before changing its contract:
+
+- `docs/settled-lifecycle-contract.md`: how child turns settle into one parent result.
+- `docs/worktree-subagents.md`: worktree snapshots, joins and retained worktrees.
+- `docs/public-subagent-tree-api.md`: the package-root API.
+- `docs/adr/`: past decisions; don't revive removed surfaces.
+
+Keep exactly one model-facing tool, `replicate`, with only `name` and `task` in its schema.
+
+## Code map
+
+- `pi-extension/subagents/index.ts`: tools, discovery, launch/watch lifecycle and delivery.
+- `pi-extension/subagents/launch.ts`: Pi and worktree launch transaction.
+- `pi-extension/subagents/lineage.ts`: durable recursive ownership.
+- `pi-extension/subagents/runtime-routing.ts`: role-to-parent runtime resolution.
+- `pi-extension/subagents/completion.ts`, `session.ts`, `subagent-done.ts`: completion evidence.
+- `index.ts`, `index.js`, `index.d.ts`: package-root API. Edit all three together.
+
+TypeScript modules under `pi-extension/subagents` that have JavaScript mirrors must stay aligned.
+
+## Checks
+
+- If `index.ts`, `index.js` or `index.d.ts` changes, run `npx tsc --noEmit index.ts` and `node --check index.js`.
+- Inspect package contents with `npm pack --dry-run`.
+- Run lifecycle and Herdr cases through `test/integration/run-isolated.ts` with an explicit file list (see `README.md`). Never point tests at the user's persistent Herdr server.

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Earlier entries were generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+
+## [v1.4.1](https://github.com/alexshpunt/pi-agent-replicate/compare/v1.4.0...v1.4.1) - 2026-11-01
+
+- Rewrote the README to explain replication, inherited context, installation, and directory modes.
+- Updated the package image so the full artwork fits in the Pi Packages preview.
+
+## v1.4.0 - 2026-11-01
+
+First npm release of Pi Agent Replicate under its own package name.
+
+### Highlights
+
+- Give a Pi agent a `replicate` tool to work on independent tasks in parallel while it continues its own work. Replica results return to the originating session.
+- Use separate Git worktrees by default, or select a shared project directory with `/replica-directory` when replicas need the same files and dependencies.
+- Recover replica ownership and results across reloads, with durable settlement and cleanup after descendant work drains.
+- Expose the subagent tree through the package-root API for programmatic integrations.
+- Introduce the Pi Agent Replicate mascot and refreshed README.
+
+Shared-directory changes are immediately visible and are not automatically rolled back if a replica fails. Coordinate concurrent edits to avoid overwriting work.
+
+## [v1.3.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.3...v1.3.0)
+
+### Commits
+
+- feat: identify workflow review nodes [`6919ab1`](https://github.com/giuseppecrj/pi-herdr-agents/commit/6919ab1c655f0e6c50944011889df14800cf2021)
+
+## [v1.2.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.2...v1.2.3) - 2026-08-18
+
+### Commits
+
+- fix: shorten worktree labels [`4caeabb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4caeabb4db088b8c60d0caf701ec49fe538f8df2)
+- docs: add release workflow skill [`9937f34`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9937f3402ab672023525c19a50dee3cbd7d579bb)
+- chore: release v1.2.3 [`cd5036e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/cd5036e6254ee5d28d8da3ddfd55e8cc4e0db413)
+
+## [v1.2.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.1...v1.2.2) - 2026-08-18
+
+### Commits
+
+- fix: hide completion tool from auto-exit children [`e4cad6b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e4cad6bdbe5d1952f5bb838640493c20ab332dbd)
+- chore: release v1.2.2 [`ab7843b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ab7843b4919574789029c985f27509b968242b05)
+
+## [v1.2.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.0...v1.2.1) - 2026-08-13
+
+### Commits
+
+- docs: polish package readme and artwork [`908dd76`](https://github.com/giuseppecrj/pi-herdr-agents/commit/908dd76875c91871b8d91113e6d1633d5112d5b3)
+- chore: release v1.2.1 [`df87f12`](https://github.com/giuseppecrj/pi-herdr-agents/commit/df87f126ec5cad4735c441752471aa8bd724f2e9)
+
+## [v1.2.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.1.0...v1.2.0) - 2026-08-13
+
+### Commits
+
+- feat: add worktree session handoff [`8b6f928`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8b6f928c0b61a97f66614054340a68c023df0c95)
+- style: format worktree handoff changes [`c1cdc44`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c1cdc4480f0e29268194bc80809959215d13044f)
+- fix: confirm worktree handoff startup [`0e4a97c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0e4a97c46b6dd1d9fc56d9c74511e380dca6e6d0)
+- feat: simplify worktree command [`4dc88e0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4dc88e0a962625eec10240d57cf67548510e6a9a)
+- docs: add worktree handoff research [`00f95c6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/00f95c65e0f050492259a0de625c35e4eef9aae8)
+- test: cover failed worktree handoff recovery [`dd27c0a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/dd27c0a8f17e51cff635e5b77e18ff7f05896650)
+- chore: release v1.2.0 [`dba1ab5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/dba1ab5564b9ef64ae1f0f57b6df4bb40502970c)
+- ci: upgrade release actions to node24 [`ec9158d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ec9158d838cb0fae914c94fc448a6677b4ab1696)
+
+## [v1.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.0.0...v1.1.0) - 2026-08-11
+
+### Commits
+
+- chore: initialize generated changelog [`77ca8eb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/77ca8eb000e1d06f6d23bfbd8fdcac491bef581d)
+- feat: label coordinated subagents [`e2d15ab`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e2d15abf2cbe9f0557d14ab768dd39e64352577e)
+- chore: release v1.1.0 [`732c0dc`](https://github.com/giuseppecrj/pi-herdr-agents/commit/732c0dcef0f0a85be737b9dd6023a59eb2771178)
+
+## [v1.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.1.4...v1.0.0) - 2026-08-11
+
+### Commits
+
+- refactor: extract fresh Pi launch transaction [`2241084`](https://github.com/giuseppecrj/pi-herdr-agents/commit/22410845f8b62765fd2ac391cbd94156010abba6)
+- refactor: remove external CLI subagent execution [`9c31fe7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9c31fe7e566c1fdb3fa8ac3c8a5879fbc25f0fb8)
+- refactor: route Pi session resumes through launch module [`f16f42b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f16f42b003813852039be9ec1e91b65f28b87bb6)
+- refactor: deliver subagent results through one message [`52c4e02`](https://github.com/giuseppecrj/pi-herdr-agents/commit/52c4e029bbe39170d16a0178b369ab2f68a2d40d)
+- test: stabilize asynchronous subagent integration [`3d2cebb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/3d2cebb41894f2c66038d636998a9b2e0b781431)
+- _No commit message_ [`d5a5c2d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d5a5c2d0baa1b25a362e0c02de5f6d48342d9393)
+- updates [`e345303`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e345303338857ca19b8ce880c0707173505ad78b)
+- chore: release v1.0.0 [`ccc0045`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ccc0045f3bd6b937bf6acd238b97fe48341bd8ba)
+- merge: deepen Pi subagent launch and resume [`674da9d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/674da9dc5d752deca3538c0d8d7ffdbdecc00a4c)
+
+## [v0.1.4](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.1.3...v0.1.4) - 2026-08-10
+
+### Commits
+
+- chore: release v0.1.4 [`0ce2fe4`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0ce2fe45b3c76a2bffe1df561076d1c62537c139)
+
+## [v0.1.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.1.2...v0.1.3) - 2026-08-07
+
+### Commits
+
+- fix: reject empty workflow completions [`338a788`](https://github.com/giuseppecrj/pi-herdr-agents/commit/338a788855c9ea7ac8b3f6214ff8b3130bc4b007)
+- test: verify fallback completion from session evidence [`b2eb4b0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b2eb4b0fec5bd7d5ec9f473168cf3710e600052d)
+- chore: release v0.1.3 [`a2cd1b5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a2cd1b5ab424226e371ee6388e79d8ccf3e9a304)
+
+## [v0.1.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.1.1...v0.1.2) - 2026-08-07
+
+### Commits
+
+- chore: release v0.1.2 [`67608a5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/67608a5b1950222b522277c2fb4a246cbffb91f8)
+
+## [v0.1.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.1.0...v0.1.1) - 2026-08-07
+
+### Commits
+
+- fix: wait for Herdr shell readiness [`58bfa99`](https://github.com/giuseppecrj/pi-herdr-agents/commit/58bfa99c150963b4c7f7cc8348b8e2ead00399af)
+- chore: release v0.1.1 [`9b9a3c9`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9b9a3c9ded45f65be7c2814cb34230ee5bf82532)
+
+## [v0.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.0.4...v0.1.0) - 2026-08-05
+
+### Commits
+
+- feat: add ordered subagent model fallbacks [`2ce041b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/2ce041b51f1eb1906623bc0c361fea6a3acf019d)
+- chore: release v0.1.0 [`b409457`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b409457f58b738734b48a4e7cf3418da957db271)
+
+## [v0.0.4](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.0.3...v0.0.4) - 2026-08-05
+
+### Merged
+
+- agents: extract Claude CLI adapter [`#5`](https://github.com/giuseppecrj/pi-herdr-agents/pull/5)
+
+### Commits
+
+- release: update version to 0.0.4 [`c685c35`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c685c3553ec76d987972c1786d966b704ad9197b)
+
+## [v0.0.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v0.0.2...v0.0.3) - 2026-08-05
+
+### Commits
+
+- docs: enhance documentation for adversarial-reviewer and runtime adapter policies; clarify model selection process and permissions [`ddf4a34`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ddf4a3411e018c7335bc66e191d5d84b187d8d07)
+- agents: remove bundled Claude reviewer adapter [`ed12ddf`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ed12ddf774046dd0a708fd54d53f12d25118d006)
+- docs: align release baseline with 0.0.2 [`c136b16`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c136b1659370bc4265b1ed4c67c2b670c764a8b1)
+- release: update version to 0.0.3 [`c6ce52c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c6ce52c6af3b9a3157c073aa257ea69f826597ad)
+
+## v0.0.2 - 2026-08-05
+
+### Commits
+
+- feat: launch Pi Herdr Agents 0.2.0 [`4fa3f26`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4fa3f26d743defa68ce1c068fbc80cc5f3062934)
+- release: prepare 0.0.2 [`5d6e65d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5d6e65d4c25a8df427dd057b77267985bb505d1a)
+- update version [`4ffd68f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4ffd68f55f58cedbfb9fd84cd139f81c107552eb)

package/CONTEXT.md

@@ -0,0 +1,63 @@
+# Project context
+
+`pi-agent-replicate` lets an agent split independent work into copies of its current Pi session in Herdr.
+
+## Shipped surface
+
+The experimental model-facing surface is exactly one tool: `replicate({ name, task })`. Its schema never gains continuation parameters. One invocation creates one fresh copy in a pane, using a dedicated worktree by default or the parent directory when configured for the project. A user command selects the directory mode. The package ships no bundled roles, review workflows or orchestration skills.
+
+The old model-facing role, completion and help tools are removed. The internal launcher and package-root tree API remain available for callers that need custom roles, bare children or managed worktrees. Their contracts are separate from replication.
+
+## Replication
+
+Replication is parallel work by copies of one agent, not delegation. The caller must already be at its intended working location and understand the task. It must identify independent parts, specify the copy's work and expected result, and continue a different part itself. Do not replicate while deciding the task or just to wait. Waiting after completing useful parallel work is allowed.
+
+Use progressive disclosure. The initial description explains purpose and use, not Git, worktrees, checkpoints, delivery routing or host mechanics. Results retain a full summary without host reference footers or saved-copy choices. A failure or conflict explains the work problem. The parent continues with that information or creates a fresh replica.
+
+A clone inherits the parent's model, thinking level, full system prompt, active tools and current active conversation, including the triggering user turn. Explicit CLI extensions follow it. The snapshot is captured before asynchronous launch work, so another turn or sibling tool result cannot change its context. Inherited pending tool calls are settled without executing them again.
+
+Copied extension control state must not wake a parent-side background operation before the replica receives its own assignment. Keep the active conversation, not ownership of the parent's pending operations.
+
+The bounded assignment, parallel-copy identity and required summary belong in a normal task message. Internal original-session references stay in host metadata. Replication must not change the system prompt or its cache prefix. There are no role, model, cwd, worktree or batch choices on this tool.
+
+By default each clone gets a source snapshot with tracked working files and nonignored untracked files. The host uses a private index and protected checkpoint refs without changing parent HEAD or staging. Ignored files are not copied. Worktrees isolate files, not shared processes, ports or databases. The project can instead select a shared directory for new clones: no source snapshot or join is made, files are immediately shared, and failure does not undo changes. A clone can replicate its own independent work. It remains responsible until its descendants drain, then returns a nonempty final summary. No help or explicit completion tool is registered for clones.
+
+The immediate parent's host saves completion and session evidence. In worktree mode it also saves source evidence; only successful children attempt a three-way join after their descendants drain. Sibling joins are serial, including across overlapping Pi incarnations. Costly replica checkpoint, join and cleanup work runs in a separate host process so it cannot block Pi's input or model loop. Durable ownership gates and existing journals recover interrupted work. Revalidate the original parent's location before file application and delivery. Task completion and integration are separate outcomes. A Git-clean join does not prove program correctness. Conflicts apply no child files; failures and empty summaries never auto-join partial work. Saved work remains available for manual resolution and recovery.
+
+Every settled replica closes its owned pane and empty Herdr workspace after descendant drain and process exit, including failure and conflict. Failed or unjoined checkouts and saved sessions remain available for recovery. Applied worktrees are removed only after durable integration and checkpointing, verified ownership and process exit. Later edits or uncertain ownership prevent removal. Sessions and source checkpoints remain reconstructable. Closed parents defer successful joins until their exact session reopens.
+
+Each invocation uses fresh source and conversation from the immediate parent. Model-facing resume and fork choices are removed; internal saved sessions and checkpoints remain recovery evidence. Terminal model failure is also terminal: report honest error facts and a file of every post-fork textual assistant answer. Exclude inherited answers, tool calls, tool results and hidden reasoning. Do not truncate the history. An empty required summary is a failure.
+
+The caller must choose an explicit task-specific name in lowercase kebab-case for every invocation. Reject missing or invalid names before launch. The runtime adds the immediate parent's origin as `task-name ← parent-name`, using the first nonempty parent session name, current Herdr pane name, or project directory name. Do not generate task names or copy numbers. Keep the same combined title in the child session, host surfaces, status, and result; internal IDs still own recovery and delivery.
+
+New replica branches must show their origin and supplied task name as `replica/<origin>/<name>`, not an opaque copy ID. Use a lowercase ASCII origin slug, transliterating Cyrillic so Herdr does not drop the origin from the checkout directory. Reserve each branch atomically at its exact snapshot commit. Serialize allocation across the repository and check both branch names and flattened checkout names; occupied names get numeric suffixes without changing session titles or reusing another copy's source. Preserve parent HEAD and staging, and leave existing branches and recovery paths unchanged.
+
+## Durable lifecycle
+
+Replication is fire-and-forget. The caller gets an acknowledgement and later automatic delivery that starts a turn. Parents do not poll. Every fully stopped replica returns one truthful result, even after user input or Escape, and closes after durable settlement and descendant drain. Interruption and unsaved closure are failures with preserved post-fork answers and source work. Process loss does not automatically relaunch a replica; its immediate parent continues the work or creates a fresh copy.
+
+Routine supervision must leave the parent's input and tools responsive while copies run. Bound-session discovery uses its exact ownership index, attachment and same-session artifacts, not unrelated historical sessions. Reuse validated binding metadata and consume appended records without rereading whole conversations on every tick. File replacement, truncation and identity changes must invalidate that reuse; the cache is not ownership evidence on its own.
+
+A missing or damaged answer-history boundary must not prevent terminal failure delivery or pane cleanup. Report the export error rather than guessing which answers belong to the copy. A failed session checkpoint must not prevent saving terminal facts and source work; retain the checkout and block integration when no usable session checkpoint exists.
+
+A replica may fail before it can register its own runtime. Record the allocated shell's boot and process incarnation from the parent before dispatch. A confirmed failed startup can close that owned pane without a child location record, while retaining its checkout. Include available loader diagnostics in the parent error. A native launch tool error already saved in the parent is not delivered again as a recovered replica result. An ambiguous dispatch error must not declare a process finished if it actually started.
+
+Replica shutdown requires a stopped agent, no active tools, no pending background terminal/request receipts or queued results, no reported live Linux descendants, and drained child replicas. Background completions are processed by the copy before it returns; a new run invalidates an older closure attempt. Persist receipt/process ownership only for the exact session so reload does not abandon its work or transfer another session's jobs. Count reported child processes and their observed descendants, not the host shell or unrelated runtime helpers. Unreported daemons and remote jobs without receipts are outside this guard.
+
+Return the settled hook's finalization promise to Pi. Request shutdown before interactive mode checks the settled boundary; an async request started without that promise can leave a finished copy idle forever.
+
+Normal settlement follows this drain without an extra model confirmation. Ten continuously idle seconds provide a safety net for missed handoff, not a limit on active work. Queued messages, requests, tools, retries, compaction, movement and descendant drain suspend that clock. A saved settlement can be retried after reload; missing settlement evidence cannot become success. The retained non-replica recovery and intervention policies remain separate.
+
+Session identity, not a file path or pane ID, owns delivery. A binding inside each session carries its durable store and child settings. Teleport preserves that entry and session ID. The ownership index and lineage inboxes survive Pi and Herdr process replacement. Reopening the exact parent replays pending answers and starts a turn; a closed parent is never opened automatically. New-ID forks cannot claim the original answers. A delivery is acknowledged only after its exact result entry is saved, not merely queued. Cleanup requires the recorded shell incarnation to still own the pane.
+
+Each tool-launched attempt also retains its actual execution ID and visible outer root from Pi's execution events. Persist both with launch metadata and delivery inboxes; do not recover them from ID syntax, names, paths, completion order or timing. Publish the root as `parentToolCallId` on delayed result/help messages so existing consumers can group searchable output without rewriting history. Each fresh invocation records its own owner; automatic recovery preserves it. Missing ownership stays missing. This display linkage must not change result payloads, consumption, wakeups or source integration.
+
+## Retained launch paths
+
+For the internal launcher and package-root API, model and thinking resolve independently: use custom role frontmatter when present, otherwise inherit the parent. Role models must be exact authenticated `provider/model-id` values; fallback lists are unsupported.
+
+Roles come from project, global or installed role-pack directories, in that priority order. Legacy external CLI roles fail closed. The retained API does not register model-facing completion or help controls.
+
+Managed worktrees remain opt-in on these retained paths. Ownership is recorded before Herdr creates resources. They use an exact committed base without copying parent dirty files, retain the workspace after every outcome, and never push, merge or remove it automatically. Replication has its own snapshot and automatic-join contract, separate from these retained worktrees.
+
+The package-root API keeps these contracts through `createSubagentTree` and `attachSubagentTree` without registering model-facing tools.

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.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/banner.png" alt="Pi Agent Replicate: one agent branches into two copies" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Pi Agent Replicate</h1>
+
+<p align="center">One agent. Parallel work.</p>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/pi-agent-replicate)](https://www.npmjs.com/package/pi-agent-replicate)
+[![MIT license](https://img.shields.io/npm/l/pi-agent-replicate)](./LICENSE)
+
+</div>
+
+Give your [Pi](https://github.com/earendil-works/pi) agent the ability to work in parallel in [Herdr](https://herdr.dev). It creates copies of itself for independent parts of a task, keeps working, and receives their results automatically.
+
+Each copy starts with the current conversation, system prompt, model, thinking level and active tools. It has the context it needs to continue the work, rather than starting from scratch.
+
+## Install
+
+```bash
+pi install npm:pi-agent-replicate
+```
+
+Start Pi inside Herdr, then restart Pi or run `/reload`.
+
+## How it works
+
+The extension adds one tool, `replicate`. The agent calls it with a task-specific name and a bounded assignment:
+
+```typescript
+replicate({
+  name: "check-auth-risks",
+  task: "Check authentication risks while I implement the settings change. Return concrete findings with file references.",
+});
+```
+
+The name uses lowercase kebab-case. The copy works in its own Pi session and can create copies of its own. When its work and any child work finish, the result returns to the original agent automatically. The original can continue independent work or end its turn while it waits; it does not need to poll.
+
+Use replication when there are genuinely independent tasks to do in parallel, not simply to hand off a task and wait. Copies inherit the conversation and tools, but their subsequent conversations are separate.
+
+## Where copies work
+
+By default, each copy works in a separate Git worktree. It starts with a snapshot of the parent's tracked changes and non-ignored new files. Ignored files, dependencies and build outputs are not copied. On success, the host attempts to apply the copy's changes to the parent without changing its HEAD or staging. A conflict or failure leaves the copy's work available for review rather than applying partial changes. A clean join does not guarantee the combined code is correct.
+
+Worktree mode requires a non-bare Git checkout with a commit. Snapshots do not support unresolved index conflicts, sparse or assume-unchanged index entries, submodules or nested Git repositories. Worktrees isolate files, not shared processes, ports or databases.
+
+When copies need the same directory, switch to shared mode:
+
+```text
+/replica-directory shared
+```
+
+Shared copies work in the parent's current directory, including ignored files and dependencies. They do not create a worktree or branch, and there is no snapshot or automatic join. Changes are visible immediately and can remain even if a copy fails. Coordinate assignments: parallel edits to the same files can overwrite each other, and there is no automatic rollback.
+
+Use `/replica-directory worktree` to switch back, or `/replica-directory` to choose interactively. The setting is saved in `.pi/replicate.json` in the current project directory and applies to new copies only.
+
+## When a copy stops
+
+A completed copy returns its summary automatically. If it fails, is interrupted or loses its process, the parent receives a failure and any available answer information. Copies do not restart automatically; the parent can create a fresh copy if needed. In worktree mode, failed or conflicted work remains available for recovery; in shared mode, changes may already be in the shared directory.
+
+## More information
+
+See the [documentation](docs/README.md) for technical contracts and [development instructions](docs/development.md).
+
+## License
+
+[MIT](LICENSE)

package/RELEASING.md

@@ -0,0 +1,132 @@
+# Release guide
+
+GitHub Actions publishes this package when the version in `package.json` changes on `main`. The release workflow reads the package name and version from `package.json`, validates the package, publishes to npm, creates a matching `vX.Y.Z` tag, and creates a GitHub Release. If `.github/release-notes/<version>.md` exists, the release uses that file. Otherwise GitHub generates the notes and adds the npm package link.
+
+The published version must be unique on npm.
+
+## Public versioning
+
+`pi-agent-replicate` is a new npm package name and needs its first publication. The upstream `pi-herdr-agents` package used `0.0.1` for its manual bootstrap and `0.0.2` for its first trusted-publishing release. Those versions are upstream history, not publications of this renamed package.
+
+Do not design a release that creates a GitHub Release without a successful npm publish for a new version. The workflow publishes first, then tags and creates the GitHub Release.
+
+## Prerequisites
+
+You need:
+
+- Permission to manage this repository's GitHub Actions settings and npm package access for `pi-agent-replicate`
+- A clean local `main` branch
+
+Automated release gates (run by the workflow and required locally):
+
+```bash
+npm ci
+npm run lint
+npm test
+npm pack --dry-run
+```
+
+Manual deterministic Herdr integration (required before you push a release commit; not run in GitHub Actions):
+
+```bash
+npm run test:integration
+```
+
+Run that suite from inside Herdr. The shipped command bootstraps a separate test-owned headless Herdr server with a private socket, config, state directory, and worktree directory. It clears inherited Herdr identity and fails closed if the private endpoint cannot start, so it never falls back to the persistent user server. Normal exit and `SIGINT`, `SIGTERM`, or `SIGHUP` use one idempotent shutdown that verifies child and server process groups have exited, escalates after bounded grace, and removes only owned paths. Concurrent runs use separate endpoints and need no shared Herdr test slot. It uses real Pi and Herdr processes with the local deterministic provider, so it needs no provider credentials or network access. A focused file can be passed after `--`, for example `npm run test:integration -- test/integration/mux-surface.test.ts`.
+The optional live-provider smoke test is not a release gate:
+
+```bash
+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/`, the package-root API files, and the files under `pi-extension/subagents/`. 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
+
+### Steady state: trusted publishing (tokenless)
+
+After the package exists on npm, steady-state releases use npm trusted publishing (OIDC). No long-lived `NPM_TOKEN` is required.
+
+1. Open the package settings for `pi-agent-replicate` on [npmjs.com](https://www.npmjs.com/).
+2. Add a trusted publisher for GitHub Actions with:
+   - Organization or user: `alexshpunt`
+   - Repository: `pi-agent-replicate`
+   - Workflow filename: `publish.yml`
+   - Allowed action: `npm publish`
+3. Confirm the release job has `permissions.id-token: write` and runs on a GitHub-hosted runner (already set in `.github/workflows/publish.yml`).
+4. Confirm the workflow uses the exactly pinned Node `26.3.0`, whose bundled npm supports trusted publishing.
+5. Publish stays tokenless: `npm publish --access public --provenance`.
+
+When the repository secret `NPM_TOKEN` is absent, the publish step unsets `NODE_AUTH_TOKEN` and relies on OIDC. Once the package exists, the workflow fails if `NPM_TOKEN` is still configured, so steady-state releases cannot silently keep using the bootstrap credential. Manual dispatch runs only from `main`; other refs are rejected.
+
+A new trusted publisher expires 48 hours after creation unless it completes a successful publish. Create or recreate it shortly before the next release; an expired configuration cannot authorize publishing. The first successful trusted publish validates the configuration.
+
+### Bootstrap history
+
+The upstream `0.0.1` publication and documented trusted publisher for `giuseppecrj/pi-herdr-agents` do not establish the renamed npm package or authorize its releases.
+
+Only during an explicitly requested first release, configure a temporary `NPM_TOKEN` if `pi-agent-replicate` does not yet exist on npm. After that publication, revoke and remove the token, then configure the trusted publisher above. The workflow rejects `NPM_TOKEN` once the package exists. Renaming the project does not publish a package or configure its trusted publisher.
+
+## Publish a release
+
+Choose the semantic version increment:
+
+- `patch`: compatible bug fixes, such as `0.0.2` to `0.0.3`
+- `minor`: compatible features, such as `0.0.2` to `0.1.0`
+- `major`: breaking changes, such as `0.0.2` to `1.0.0`
+
+Save approved release notes as `.github/release-notes/<version>.md` and commit that file before the version commit. The workflow uses its contents verbatim for the matching release. An empty notes file stops release creation. Without a matching file, GitHub generates the release notes.
+
+Create the version commit without a local tag:
+
+```bash
+git fetch --tags --prune
+npm version patch --no-git-tag-version
+git add package.json package-lock.json CHANGELOG.md
+git commit -m "chore: release v$(node -p \"require('./package.json').version\")"
+git push origin main
+```
+
+The `npm version` hook regenerates `CHANGELOG.md` with `auto-changelog`. Use `npm run changelog` to regenerate it without changing the version.
+
+Replace `patch` with `minor` or `major` when appropriate. The push triggers the **Release** workflow, which installs dependencies, runs lint and unit tests, previews package contents, publishes to npm with provenance, creates and pushes the version tag, and creates the GitHub Release.
+
+You can rerun a failed or incomplete release from **Actions → Release → Run workflow**. If npm already has `PACKAGE_NAME@VERSION`, the workflow reads that version's `gitHead` and continues only when it matches `GITHUB_SHA` (exact-commit retry). A foreign publish fails before tag or GitHub Release creation. Existing tags are verified to point at the release commit. The workflow does not create a GitHub Release for a version that still needs publish and failed to publish.
+
+## Verify the release
+
+After the workflow succeeds, inspect the published package:
+
+```bash
+npm view pi-agent-replicate
+```
+
+Test installation through Pi:
+
+```bash
+pi install npm:pi-agent-replicate
+```
+
+The package should appear at <https://pi.dev/packages/pi-agent-replicate> after the gallery indexes the npm release.
+
+## Troubleshooting
+
+### Tag points to another commit
+
+The workflow stops if the matching version tag already points to a different commit. Do not move or reuse release tags. Increment the package version and push a new release commit instead.
+
+### npm rejects authentication
+
+Confirm that the trusted publisher matches owner `alexshpunt`, repository `pi-agent-replicate`, and workflow `publish.yml`, that the job has `id-token: write`, and that the runner is GitHub-hosted. If a release reports that `NPM_TOKEN` is bootstrap-only, remove the secret and use the trusted publisher.
+
+### npm reports that the version already exists
+
+If the published `gitHead` does not match this commit, the workflow fails before tagging. npm versions are immutable: increment the package version and push a new release commit. If it is a retry of the exact same commit, the workflow skips publish and continues with tag/release.
+
+### Initial branch creation did not release
+
+A clean repository's first push has `github.event.before` all zeroes. The workflow treats that as `release=false`. For the renamed package's first publication, follow the bootstrap instructions above. Once it exists on npm, use tokenless trusted publishing for later releases.
+
+### The package is absent from pi.dev
+
+Confirm that npm published the package publicly and that `package.json` contains the `pi-package` keyword. Gallery indexing may take some time.

package/config.json.example

@@ -0,0 +1,6 @@
+{
+  "status": {
+    "enabled": true,
+    "quietThresholdMs": 120000
+  }
+}

package/docs/README.md

@@ -0,0 +1,23 @@
+# Documentation
+
+## Active contracts
+
+- [Worktree subagents](worktree-subagents.md) — isolation, retained state, review, and cleanup.
+- [Public subagent tree API](public-subagent-tree-api.md) — package-root API and ownership contract.
+- [Settled lifecycle contract](settled-lifecycle-contract.md) — completion and delivery semantics.
+- [Retained role launcher](retained-roles.md) — role definitions and discovery for the package-root API.
+- [Status configuration](configuration.md) — status display settings.
+- [Development](development.md) — checks and isolated integration testing.
+
+## Architecture decisions
+
+- [ADR-0003](adr/0003-installable-role-packs.md) — installable custom role packs.
+- [ADR-0008](adr/0008-adopt-pi-only-subagent-execution.md) — Pi-only child execution.
+- [ADR-0009](adr/0009-durable-recursive-subagent-ownership.md) — durable recursive ownership.
+- [ADR-0010](adr/0010-public-subagent-tree-registry.md) — public process-local tree registry.
+
+Older workflow and command decisions were removed with the surfaces they described. Historical release notes remain in `CHANGELOG.md`.
+
+## Background research
+
+Files under [research](research/) are evidence and alternatives, not shipped contracts. When research conflicts with the README or an accepted ADR, the active contract wins.

package/docs/adr/0003-installable-role-packs.md

@@ -0,0 +1,29 @@
+# ADR-0003: Installable role packs
+
+- Status: Accepted
+
+## Context
+
+Projects need reusable custom subagent roles without copying them into every repository. The extension itself no longer ships built-in roles.
+
+## Decision
+
+Discover role files from three sources, in this order:
+
+1. project `.pi/agents`;
+2. global Pi agent directories;
+3. installable packages that contribute agent directories through `pi-herdr-subagents:roles:discover:v1`.
+
+Project roles override global roles. Global roles override package roles. If two packages contribute the same role name, discovery reports a collision instead of choosing by package order.
+
+A role is a Markdown file with frontmatter and an optional prompt body. Role frontmatter may own model, thinking, tools, skills, cwd, session mode, prompt mode, and interaction defaults. Legacy roles that request an external CLI fail closed before Herdr creates resources.
+
+The runtime does not scan arbitrary `node_modules` folders. Installed packages register their directories through the discovery event.
+
+## Consequences
+
+- Role packs are reusable and explicit.
+- Local policy can override package defaults.
+- Package collisions are visible and deterministic.
+- There is no protected built-in namespace.
+- Role packs contribute roles only; they do not add commands or executable workflow engines.

package/docs/adr/0008-adopt-pi-only-subagent-execution.md

@@ -0,0 +1,22 @@
+# ADR-0008: Adopt Pi-only subagent execution
+
+- **Status:** Accepted (implemented)
+- **Date:** 2026-08-10
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Supersedes:** The external CLI runtime-adapter provisions of ADR-0002
+
+## Decision
+
+Make every public subagent run Pi-backed. Remove the Claude terminal adapter and its `cli`, `cli-model`, and `resumeSessionId` interface fields. Existing role files that request an external CLI must fail with a clear error instead of silently running through Pi.
+
+A single deep launch module will own the complete launch transaction behind one small interface. Pi and Herdr remain implementation details of that module; do not add a runtime adapter seam without a second real execution path.
+
+Completion delivery will use one custom message whose content contains the bounded result and triggers the parent turn. Completion detection will keep the Pi sidecar as primary evidence and the terminal exit marker as its best-effort fallback.
+
+## Why
+
+The Claude terminal path duplicates launch, completion, transcript, cleanup, status, resume, and interruption behavior. It also requires `--dangerously-skip-permissions`, has no bundled role, and reduces locality and test leverage. Pi already provides Claude models through normal provider/model routing.
+
+## Consequences
+
+This is an immediate breaking change with no deprecation adapter. Custom roles that request an external CLI fail closed before Herdr creates resources.

package/docs/adr/0009-durable-recursive-subagent-ownership.md

@@ -0,0 +1,23 @@
+# ADR-0009: Durable recursive subagent ownership
+
+- Status: Accepted
+
+## Context
+
+A child may launch descendants and then settle before they do. Process-local maps cannot preserve correct ownership through extension reloads or independent child processes.
+
+## Decision
+
+Publish immutable lineage events under the parent session artifacts. Register each child before Herdr creates its pane or worktree. Each node records its parent node and parent Pi session sink.
+
+A node drains only after its own terminal result has been delivered and every recursive descendant has drained. Inbox materialization uses durable claims and acknowledgements so recovery can avoid duplicate delivery. Cancellation becomes terminal only after pane absence and process exit are proven.
+
+Lineage identity belongs to the launched Pi process. Unrelated subprocesses that inherit environment variables do not become descendants.
+
+## Consequences
+
+- Nested ownership survives extension reloads and independent processes.
+- A parent cannot report final completion while a descendant remains undrained.
+- Results route to the exact parent Pi session.
+- Corrupt, cyclic, or unattributable state fails closed instead of guessing.
+- Cleanup is separate from delivery, so retained evidence remains inspectable.

package/docs/adr/0010-public-subagent-tree-registry.md

@@ -0,0 +1,16 @@
+# ADR 0010: Public subagent tree registry
+
+- Status: Accepted
+- Date: 2026-08-30
+
+## Decision
+
+The package-root public subagent tree API uses a lazy process-local registry and one single-writer branch journal per Pi process. Tree artifacts live below the original caller session's artifact directory. Published node, terminal, and callback records use temporary files and same-filesystem rename; exclusive claims prevent competing owners.
+
+Nested Pi children receive only a package-owned context-file path outside model task text. They attach with validated caller, tree, token, and parent identities. The existing `launchPiSubagent()` remains the only Pi/Herdr launch owner.
+
+`/reload`, `/new`, and `/resume` rebind fresh context in the same process. `/fork` is accepted only when the fresh session's `parentSession` header matches the previously bound session and `previousSessionFile`; stale callbacks are rejected by binding generation. Terminal completion is one compare-and-set record, and cancellation is authoritative only after pane absence and captured process exit are confirmed.
+
+## Consequences
+
+The API is intentionally for installed Pi extensions inside Herdr and does not promise arbitrary Node use or full process restart recovery. A process crash can leave retained evidence for inspection, but the filesystem protocol is not a general job engine. Clean and explicit-empty roots may complete while descendant error or abort panes remain open and are reported in bounded lifecycle rows.

package/docs/configuration.md

@@ -0,0 +1,14 @@
+# Status configuration
+
+Status settings are read from `config.json` at the installed package root. If that file is absent, `config.json.example` supplies the defaults:
+
+```json
+{
+  "status": {
+    "enabled": true,
+    "quietThresholdMs": 120000
+  }
+}
+```
+
+`PI_SUBAGENT_QUIET_THRESHOLD_MS` overrides the quiet threshold for the current process. It must be a positive integer. Package updates may replace changes made inside the installed package directory.