pi-agent-replicate 0.0.0-stage → 1.4.0

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,147 @@
+# 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.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,240 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/banner.png" alt="PiAgent 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)
+[![npm downloads](https://img.shields.io/npm/dm/pi-agent-replicate)](https://www.npmjs.com/package/pi-agent-replicate)
+[![MIT license](https://img.shields.io/npm/l/pi-agent-replicate)](./LICENSE)
+
+</div>
+
+## Summary
+
+Pi Agent Replicate gives your [Pi](https://github.com/earendil-works/pi) agent a `replicate` tool for parallel work in [Herdr](https://herdr.dev). The original agent keeps working on the task while copies of itself handle independent parts. Each copy inherits the current conversation and tools, then returns its result automatically to the original.
+
+Copies work in separate Git worktrees by default. For projects that need the same directory, such as Unity projects, you can choose a shared directory instead.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-agent-replicate
+```
+
+Start Pi inside Herdr, then restart Pi or run `/reload`.
+
+## Agent-facing tool
+
+The extension registers exactly one model-facing tool:
+
+```typescript
+replicate({ name: "check-auth-risks", task: "Check authentication risks while I implement the settings change. Return concrete findings with file references." });
+```
+
+Use it only from a task-ready state: the agent is already in the intended working location, understands its task, and has identified independent parts that can run in parallel. Before calling, it must know the copy's assignment, the expected result, and the separate work it will continue itself.
+
+This is parallel work by one agent, not a tool for handing off a task. Do not replicate while still deciding the task, its scope, or where to work. If the next step would be waiting for the copy, do the work yourself. After finishing real parallel work, the original may end its turn and wait for automatic delivery. Do not poll.
+
+The schema always requires only `name` and `task`. Each call starts a fresh copy with the caller's current context. After a result, continue in the original session or create another copy. Routine replies omit host paths and checkpoint details. A work problem is explained when it occurs.
+
+The caller must choose a task-specific `name` in lowercase kebab-case, such as `check-auth-risks`. The runtime adds the origin: `check-auth-risks ← Settings`. The origin comes from the parent's session name, then its current Herdr pane name, then the project directory name. The same combined title appears in the copy's session, Herdr workspace and pane, active status, and result. There is no automatic numbering. Internal IDs remain separate.
+
+Git branches use `replica/<origin>/<name>`, for example `replica/settings/check-auth-risks`. The origin is lowercased and made safe for a path; Cyrillic is transliterated (`Настройки` becomes `nastroiki`). Herdr uses the branch to name the checkout directory, such as `replica-nastroiki-check-auth-risks`. Repeated or simultaneous launches reserve separate branches with `-2`, `-3`, and so on, without changing the displayed session title. These suffixes also avoid different origin/task pairs that would produce the same checkout directory. Existing branches and worktrees are not renamed.
+
+## Project directory mode
+
+Run `/replica-directory` to choose a mode, or use `/replica-directory shared` or `/replica-directory worktree`. The choice is saved in `.pi/replicate.json` in the current project directory and applies to new copies. The default is `worktree`.
+
+In `shared` mode, copies use their parent's current directory, including ignored files and dependencies. They do not create a Git worktree or branch, and there is no snapshot or automatic join. Changes are visible immediately and remain even if the copy fails. Coordinate assignments: simultaneous edits to the same files can overwrite each other, and there is no automatic rollback or conflict isolation. This mode can be useful when copies need the same Unity project directory. Changing the mode does not move already-running copies.
+
+## Replication runtime
+
+The following details describe the implementation, not instructions added to the agent's prompt.
+
+Each call copies the current active conversation, including the current user turn. It inherits the model, thinking level, full system prompt and active tools. Explicit CLI extensions follow the copy too. The bounded assignment and summary requirement are sent as a normal task message, without changing the system prompt.
+
+A fresh call requires `name` and `task`. There are no model-facing role, model, cwd, worktree or batch choices. In the default worktree mode, each copy gets tracked working files and nonignored untracked files from the moment of launch. The snapshot does not change the parent's HEAD or staging. Ignored files, dependencies and builds are not copied. Worktrees isolate source files, not shared processes, ports or databases.
+
+There are no model-facing continuation, resume or fork choices. Saved sessions and source checkpoints remain recovery evidence; the tool always creates a fresh copy.
+
+A copy can call `replicate` for an independent part of its assignment. It must wait for its own copies and return a nonempty final summary. The runtime delivers that summary and closes its pane and empty Herdr workspace after descendants drain and the process exits. Failed and conflicted copies close too; their files and saved sessions stay available for recovery. Copies do not get `caller_ping` or `subagent_done`.
+
+The old subagent tools and child completion/help tools are removed. The internal launcher and package-root API remain available without registering model-facing controls. The package ships no workflows, skills or built-in roles.
+
+## Retained runtime policy
+
+Model and thinking are resolved independently:
+
+1. Use the value from the selected role's frontmatter.
+2. If the role omits it, inherit the value from the parent session.
+
+This role policy applies only to the retained internal launcher and package-root API. `replicate` uses the parent runtime without resolving a role. Bare spawns remain supported by those retained paths. They inherit both values. Role models must be one exact authenticated `provider/model-id`. Model fallback lists and `config.json` model routing are not supported.
+
+## Custom roles for the retained API
+
+The package has no built-in roles. Add roles in one of these places:
+
+| Source | Path |
+| --- | --- |
+| Project | `.pi/agents/<name>.md` |
+| Global | `$PI_CODING_AGENT_DIR/agents/<name>.md` (normally `~/.pi/agent/agents/<name>.md`) |
+| Role pack | An installed Pi package registered through the role discovery event |
+
+Priority is project, then global, then role pack. Duplicate role-pack names are rejected.
+
+Example:
+
+```markdown
+---
+name: security-reviewer
+description: Reviews a bounded change for security problems
+model: provider/exact-model-id
+thinking: high
+tools: read, bash
+spawning: false
+auto-exit: true
+---
+
+Review only the requested change. Report concrete findings with file references.
+```
+
+Useful frontmatter fields:
+
+- `name`, `description`
+- `model`, `thinking`
+- `tools`, `skills`, `deny-tools`
+- `spawning`, `allow-self-spawn`
+- `auto-exit`, `interactive`
+- `session-mode`: `standalone`, `lineage-only`, or `fork`
+- `cwd`
+- `system-prompt`: `append` or `replace`
+- `disable-model-invocation`
+
+Requested skills are saved in the child's conversation once. Reloading or resuming that conversation reuses the saved skills instead of adding another initialization message.
+
+Definitions that request an external `cli` fail before Herdr creates resources.
+
+### Role packs
+
+A Pi package can register one absolute Markdown file or a directory of direct `.md` children through this event:
+
+```typescript
+pi.events.on(
+  "pi-herdr-subagents:roles:discover:v1",
+  (request: { apiVersion: number; register(path: string): void }) => {
+    if (request.apiVersion === 1) request.register(absoluteRolesDirectory);
+  },
+);
+```
+
+A role-pack extension must remove its listener on `session_shutdown`.
+
+## Lifecycle
+
+`replicate` is fire-and-forget. Do not poll, sleep, tail session files or check panes to wait for it. Continue independent work or end your turn until automatic delivery starts the next turn.
+
+Delayed result and help cards keep the launch call that owns that attempt. In Stereo fullscreen they appear beside that call in Activity, not as a second Conversation card. Nested calls link to their actual visible outer call. Saved ownership follows delivery through reload, receiver recovery and Teleport. Older or API-launched work without a recorded tool owner stays unlinked. This changes presentation only: the parent still receives the complete result, and saved history stays chronological.
+
+Host metadata retains the saved session and immutable Markdown result-file paths. Routine model-visible results carry the copy's summary, without saved-copy choices or internal references. Terminal model failures report error facts; host metadata also retains a separate file containing every post-fork textual assistant answer in order. That file excludes the original's answers, tool calls, tool results and hidden reasoning. Answers are not truncated. An empty required summary is a failure, not success.
+
+Every fully stopped replica reports and closes, including after user input or Escape. An interrupted copy reports interruption; an unsaved close or process loss reports failure with preserved answers, not success or an automatic restart. The parent continues with the returned information or creates a fresh copy.
+
+If Pi fails while loading extensions or before its session initializes, the parent uses its saved launch ownership to close the failed attempt pane and reports the available startup error. It does not wait for completion hooks that never started. The failed checkout stays available. A warning alone or a terminal marker printed while Pi is still running does not count as process failure.
+
+Missing or damaged answer history does not block a failure report or pane cleanup. The result explains why history is unavailable without exporting answers of unknown origin. If the session itself cannot be checkpointed, source work is still saved where possible and retained, and no changes are applied automatically.
+
+Automatic closure waits for active tools, pending background terminal completions, background request receipts, reported Linux child PIDs and their observed descendants, and owned replicas. Completion messages wake the copy so it can process the result before returning. New input or work cancels a stale shutdown decision. This ownership state follows the exact session through reload.
+
+The process guard uses reported descendant PIDs, not every process in the terminal or every runtime helper. It cannot discover unreported daemonized jobs or remote CI jobs without a background receipt/completion message. A running open-ended job keeps its copy open until stopped.
+
+Once session work is finished, settlement reports without an extra model confirmation. A ten-second safety net retries a missed handoff only while Pi is truly idle, with no queued work, movement or undrained descendants. Active tools, requests, retries and compaction are not subject to that deadline. Durable ownership restores pending results, join plans and cleanup after restart. The retained non-replica API keeps its existing recovery and interactive policies.
+
+The binding is saved inside the Pi session and follows its stable session ID through Teleport. A new file, cwd, process, or pane does not change the receiver. A fork with a new session ID does not inherit pending answers. Children restore their own lifecycle and follow their moved immediate parent, including nested launches. A move suspends source-side delivery and completion while the replacement binds; an abandoned child handoff has a bounded recovery gate.
+
+Ownership and current locations are indexed under `$PI_CODING_AGENT_DIR/subagent-sessions` (default: `~/.pi/agent/subagent-sessions`). The session carries this store path through moves. Answers stay in durable lineage inboxes until their exact result entry is saved in the parent session. When the parent is closed, nothing opens it automatically: reopening that session restores observers, replays pending answers, and wakes its agent. A Herdr restart does not erase the store. An interrupted active child uses bounded recovery or reports failure; unfinished computation is not a saved answer.
+
+Keep the binding store, session artifacts, and saved sessions together when backing up or moving to another machine. Pane IDs alone are never permission to close a pane after a restart.
+
+No child receives a model-facing completion or help tool.
+
+## Managed worktrees
+
+In the default worktree mode, replication creates a snapshot worktree. The immediate parent's host saves the completed child's source and session, then attempts a three-way join against the original snapshot. Sibling joins run serially through durable ownership gates. Checkpointing, Git joins and owned cleanup run in background host processes, not Pi's input thread. The host revalidates the original session before applying files and delivering its result. Parent HEAD and staging stay unchanged. A clean Git join means no detected text conflict, not that the combined program is correct.
+
+Task completion and integration are separate outcomes: `applied`, `conflict`, `blocked`, or `not-attempted`. Conflicts do not apply any of the child's files to the parent. Failed or empty-summary children never auto-join partial work. Their worktrees, sessions and checkpoints stay available for recovery. A new replica starts from the current parent's context and files.
+
+Successful worktrees are removed only after durable integration and source/session checkpointing, with ownership, process-exit and unchanged-source checks. Unknown ownership or later edits keep the worktree. Saved sessions and GC-protected source refs remain recoverable. If the parent is closed, successful integration waits for its exact session to reopen; no replacement parent is opened automatically.
+
+In shared mode, no source checkpoint or join is performed. The shared files remain as edited regardless of the result.
+
+The package-root API and retained internal role launcher have a separate opt-in worktree contract:
+
+- `cwd` selects the source repository.
+- `base` resolves to an exact commit and defaults to committed `HEAD`.
+- Parent uncommitted and untracked files are not copied.
+- Ownership is recorded before Herdr resources are created.
+- Success, failure, and help requests retain the workspace.
+- Completion reports branch, commits, changed files, and clean/conflicted state.
+- Unknown Git inspection results remain unknown; they are never guessed clean.
+
+See [Worktree subagents](docs/worktree-subagents.md) for review and cleanup commands.
+
+## Package-root API
+
+Other Pi extensions can import the side-effect-free package root:
+
+```typescript
+import { createSubagentTree, attachSubagentTree } from "pi-agent-replicate";
+```
+
+The tree API supports nested ownership, exact-parent reattachment, cancellation, worktree children, and one final callback. Its child runtime retains role frontmatter, then parent inheritance; this is separate from session replication. See [Public subagent tree API](docs/public-subagent-tree-api.md).
+
+## Configuration
+
+`config.json.example` contains status settings only:
+
+```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.
+
+## Development
+
+```bash
+npm test
+npm run lint
+npm pack --dry-run
+npx tsc --noEmit index.ts
+node --check index.js
+git diff --check
+```
+
+Run selected isolated real-Pi and Herdr cases from inside Herdr:
+
+```bash
+npm run test:integration -- test/integration/replication.test.ts
+```
+
+For a manual TUI check with a deterministic provider, set `PI_INTEGRATION_TUI_DIR` to a fresh ignored directory and `PI_INTEGRATION_IDE_ENTRY` to the current IDE source entry. Run only this case with the intended Pi binary on `PATH`:
+
+```bash
+node --experimental-strip-types test/integration/run-isolated.ts \
+  --test-name-pattern='renders an active isolated replica' test/integration/replication.test.ts
+```
+
+The case reloads Pi and records the loaded IDE in `runtime.json`. The applied and failed cases each write to their own subdirectory. Use its `pane.json` to attach a read-only observer to the private Herdr endpoint. Capture the active pane, then create `release-child` in the inspection directory. Capture the delivered result, then create `finish` so the runner can clean up. Both observation gates time out after five minutes. Do not use the user's persistent Herdr server.
+
+See [RELEASING.md](RELEASING.md) for release checks.