pi-herdr-agents 2.0.4 → 3.0.0

package/RELEASING.md

@@ -6,7 +6,9 @@ The published version must be unique on npm.
 
 ## Public versioning
 
-`0.0.1` was a manual bootstrap publication that established the npm package. `0.0.2` is the first release published through the trusted GitHub Actions workflow and is the current public baseline.
+`0.0.1` was a manual bootstrap publication that established the npm package. `0.0.2` is the first release published through the trusted GitHub Actions workflow; every later release uses trusted publishing.
+
+`3.0.0` is the pack-neutral baseline. It is a major release because it removes the bundled roles, `/plan`, `/skill:orchestrate`, `/iterate`, `/btw`, and `/btw-close`, and makes `roles.bundled` a deprecated no-op. Its hand-written breaking changes and migration notes are in the README [Release notes](README.md#release-notes) section, because `npm version` regenerates `CHANGELOG.md` and would discard hand edits there. Record later breaking-release notes in the same section.
 
 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.
 
@@ -41,7 +43,7 @@ The optional live-provider smoke test is not a release gate:
 PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run test:integration:live
 ```
 
-Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `agents/`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, `skills/orchestrate/adversarial-review-example.js`, and excludes `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, local `config.json` and `openspec/`, and that the worktree integration tests leave no test workspace behind. Durable user configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`; package-root configuration is ignored, so users must move an older file manually or re-run `/subagents-init`.
+Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `config.json.example`, and `examples/role-pack/`, contains no `agents/` resources, no `skills/` resources other than the host-owned `skills/pi-herdr-agents/SKILL.md`, and no `pi-extension/subagents/plan-skill.md`, and excludes `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, local `config.json` and `openspec/`, and that the worktree integration tests leave no test workspace behind. Durable user configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`; package-root configuration is ignored, so users must move an older file manually or re-run `/subagents-init`.
 
 ## npm authentication
 

package/config.json.example

@@ -5,9 +5,6 @@
   "models": {
     "agents": {}
   },
-  "roles": {
-    "bundled": true
-  },
   "persistent": {
     "maxAgents": 3
   },

package/docs/README.md

@@ -9,43 +9,66 @@ are evidence, not shipped contracts, when a later ADR supersedes them.
 - [`../README.md`](../README.md) — installation, public tools, configuration,
   lifecycle, and role authoring.
 - [`../CONTEXT.md`](../CONTEXT.md) — orchestration glossary.
-- [`../skills/orchestrate/SKILL.md`](../skills/orchestrate/SKILL.md) — public
-  subagent review fan-out and parent synthesis procedure.
-- [`../skills/orchestrate/adversarial-review.md`](../skills/orchestrate/adversarial-review.md)
-  — adversarial topology, finding records, and incomplete-coverage policy.
 - [`worktree-subagents.md`](worktree-subagents.md) — worktree operation,
   review, recovery, and cleanup.
 
-The package launches asynchronous Pi children in Herdr and supports managed
-worktrees for writing tasks. Orchestrated review materializes pinned evidence,
-launches fresh public reviewers, receives automatic completion delivery, and
-has the parent synthesize outcomes. Role frontmatter tool allowlists are the
-available enforcement boundary; `read,bash` is not read-only. Automated package
+The package is a pack-neutral execution host: it launches asynchronous Pi
+children in Herdr and supports managed worktrees for writing tasks, but ships no
+agent roles, planning or review workflows, or skills. Roles come from project or
+global definitions and installed role packs; workflows such as `/plan` and
+`/skill:orchestrate` belong to those packs
+([ADR-0013](adr/0013-pack-neutral-execution-host.md)). Role frontmatter tool
+allowlists are the available enforcement boundary; `read,bash` is not
+read-only. Automated package
 acceptance covers unit tests, lint, and `npm pack --dry-run`. Deterministic
 Herdr integration is a manual release gate run from inside Herdr. The manual
 supervision transport benchmark is `../test/bench/supervision-bench.mjs`; it
 uses an isolated Herdr server and writes uncommitted raw samples to
 `/tmp/issue29-bench/`.
 
+## Architecture and code map
+
+[ADR-0012](adr/0012-adopt-maestro-seams-in-repo.md) records the accepted seams
+decision. The [migration design](superpowers/specs/2026-10-02-maestro-seams-design.md)
+is implemented in the feature branch, with local unit and deterministic
+integration gates passed and the implementation checkpoint signed. It is not
+yet a shipped contract.
+
+- `../maestro/core/` — harness-neutral interfaces, domain rules, roles, and config.
+- `../maestro/adapters/pi/` — Pi harness and child protocol.
+- `../maestro/surfaces/herdr/` — Herdr provider and CLI driver.
+- `../maestro/runtime/` — run ownership and real Pi/Herdr composition.
+- `../pi-extension/subagents/index.ts` — Pi host entry point;
+  `model-registry.ts` and `config-path.ts` remain permanent host-local owners.
+- `../test/maestro/` — seam conformance and dependency-rule tests; real
+  conformance runs in `../test/integration/`.
+
+See the [full code map](../README.md#code-map). Pi and Herdr remain the only
+real implementations; in-memory fakes are conformance fixtures only.
+
 ## ADRs
 
 | ADR | Status | Decision |
 | --- | --- | --- |
-| [`0001`](adr/0001-btw-ephemeral-side-questions.md) | Accepted | Add `/btw` as an ephemeral side-question child. |
-| [`0002`](adr/0002-agent-workflow-skill-runtime-taxonomy.md) | Partially superseded by 0009 | Keep agent execution, skills, and Pi runtimes distinct. |
-| [`0003`](adr/0003-installable-role-packs.md) | Accepted | Define installable role-pack discovery and collision rules. |
+| [`0001`](adr/0001-btw-ephemeral-side-questions.md) | Superseded by 0013 | Historical `/btw` side-question decision; the command was removed. |
+| [`0002`](adr/0002-agent-workflow-skill-runtime-taxonomy.md) | Partially superseded by 0009 and 0013 | Keep agent execution, skills, and Pi runtimes distinct. |
+| [`0003`](adr/0003-installable-role-packs.md) | Accepted; bundled layer superseded by 0013 | Define installable role-pack discovery and collision rules. |
 | [`0004`](adr/0004-require-active-user-approval-for-workflow-execution.md) | Superseded by 0009 | Historical exact-script approval decision. |
 | [`0005`](adr/0005-parent-owns-workflow-script-authority.md) | Superseded by 0009 | Historical workflow-script authority decision. |
 | [`0006`](adr/0006-limit-v1-execution-effects-to-isolated-worktrees.md) | Partially superseded by 0009 | Historical runner effect boundary; managed worktree rules remain. |
 | [`0007`](adr/0007-require-fresh-review-for-workflow-scripts.md) | Superseded by 0009 | Historical workflow-review decision. |
-| [`0008`](adr/0008-adopt-pi-only-subagent-execution.md) | Accepted; implemented | Remove the external CLI adapter and make subagent execution Pi-only. |
-| [`0009`](adr/0009-remove-workflow-subsystem.md) | Accepted | Remove the workflow subsystem; use public subagent fan-out and parent synthesis. |
+| [`0008`](adr/0008-adopt-pi-only-subagent-execution.md) | Partially superseded by 0012 | Keep Pi-only execution; 0012 supersedes only the adapter-seam restriction. |
+| [`0009`](adr/0009-remove-workflow-subsystem.md) | Accepted; skill ownership moved by 0013 | Remove the workflow subsystem; use public subagent fan-out and parent synthesis. |
 | [`0010`](adr/0010-persistent-specialists-as-session-generations.md) | Accepted | Define persistent specialists as logical identities with policy-bound session generations. |
 | [`0011`](adr/0011-explicit-worktree-cleanup.md) | Accepted | Authorize explicit worktree cleanup by cwd containment; retain branches and reject automatic reaping. |
+| [`0012`](adr/0012-adopt-maestro-seams-in-repo.md) | Accepted | Adopt in-repo seams and conformance fakes; keep one package, Pi-only execution, and Herdr-only surfaces. |
+| [`0013`](adr/0013-pack-neutral-execution-host.md) | Accepted | Ship a pack-neutral execution host; roles and workflows move to optional packs, and `/iterate` and `/btw` are removed. |
+| [`0014`](adr/0014-operator-cancel-terminal-intent.md) | Accepted | Operator cancel records terminal intent before owned termination: no fallback, one confirmed cancelled result, unconfirmed runs stay live. |
 
 ## Historical material
 
 - [`orchestrated-review-workflow-plan.md`](orchestrated-review-workflow-plan.md)
-  — superseded workflow design, retained as history.
+  — superseded workflow design, retained as history. Its `skills/orchestrate`
+  and review-evaluation paths now belong to the `pi-herdr-roles` pack.
 - [`research/`](research/) — background evidence and alternatives, not shipped
   behavior.

package/docs/adr/0001-btw-ephemeral-side-questions.md

@@ -1,6 +1,6 @@
 # ADR-0001: Add `/btw` as an ephemeral side-question child
 
-- **Status:** Accepted
+- **Status:** Superseded by [ADR-0013](0013-pack-neutral-execution-host.md); `/btw` and `/btw-close` were removed, not relocated
 - **Date:** 2026-07-31
 - **Decision owners:** `acrnm`
 - **Scope:** `giuseppecrj/pi-herdr-agents`

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

@@ -1,6 +1,6 @@
 # ADR-0002: Adopt the agent, workflow, skill, and runtime taxonomy
 
-**Status:** Partially superseded by ADR-0009 for workflow-runner taxonomy; retained for agent, skill, and runtime terminology.
+**Status:** Partially superseded by ADR-0009 for workflow-runner taxonomy and by [ADR-0013](0013-pack-neutral-execution-host.md) for shipped roles and workflows; retained for agent, skill, and runtime terminology. The role and workflow mapping below is historical: this package no longer ships those roles, `/plan`, `/iterate`, `/btw`, or `orchestrate`.
 
 - **Status:** Accepted in part; external CLI provisions superseded
 - **Date:** 2026-08-02

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

@@ -1,7 +1,7 @@
 # ADR-0003: Discover installable role packs through Pi's event bus
 
-- **Status:** Accepted
-- **Date:** 2026-08-02
+- **Status:** Accepted; bundled-role provisions superseded by [ADR-0013](0013-pack-neutral-execution-host.md)
+- **Date:** 2026-08-02 (bundled layer retired 2026-10-05)
 - **Decision owners:** `acrnm`
 - **Scope:** `giuseppecrj/pi-herdr-agents`
 
@@ -62,10 +62,9 @@ leaving stale roles.
 
 Listing and exact-name launch use one resolved catalog. Collection order is:
 
-1. enabled bundled package roles;
-2. registered role-pack definitions;
-3. global definitions;
-4. project definitions.
+1. registered role-pack definitions;
+2. global definitions;
+3. project definitions.
 
 Effective precedence remains:
 
@@ -73,18 +72,27 @@ Effective precedence remains:
 project > global > package
 ```
 
-Role-pack definitions remain in the `package` source layer and add package name,
-version, and path provenance. Global and project definitions can intentionally
-override them.
+Role-pack definitions form the entire `package` source layer and add package
+name, version, and path provenance. Global and project definitions can
+intentionally override them. The host ships no roles, so an empty catalog is
+valid.
 
 Within the package layer:
 
-- bundled roles are protected fallbacks while enabled;
-- a role pack colliding with an enabled bundled name is rejected;
-- copying the packaged `config.json.example` to `$PI_CODING_AGENT_DIR/herdr-agents/config.json` and setting `roles.bundled` to `false` removes only the bundled layer; registered role packs remain package roles and may supply those names; package-root configuration is ignored, so manually move older files or re-run `/subagents-init`; 
-- a name contributed by multiple role packs is disabled;
+- registered packs have no priority over one another, and no pack is a
+  privileged default;
+- a name contributed by multiple role packs is disabled with a diagnostic naming
+  every contributor;
 - collisions never resolve through incidental extension load order.
 
+Earlier versions collected an enabled bundled layer first, rejected role packs
+that collided with it, and let `roles.bundled: false` remove it. ADR-0013
+retires that layer. Valid `roles.bundled` booleans in
+`$PI_CODING_AGENT_DIR/herdr-agents/config.json` are now accepted as deprecated
+no-ops with one parent-session warning per extension load; malformed values and
+unknown `roles` keys remain errors, and the file is never rewritten. Package-root
+configuration is still ignored.
+
 Invalid registrations do not suppress unrelated roles. Listing surfaces report
 concise diagnostics, and an exact-name launch reports the matching diagnostic
 instead of treating an invalid contribution as a bare agent. An invalid

package/docs/adr/0009-remove-workflow-subsystem.md

@@ -1,6 +1,6 @@
 # ADR-0009: Remove the workflow subsystem
 
-**Status:** Accepted
+**Status:** Accepted; the `orchestrate` skill described below has since moved to the `pi-herdr-roles` pack ([ADR-0013](0013-pack-neutral-execution-host.md))
 
 ## Context
 

package/docs/adr/0011-explicit-worktree-cleanup.md

@@ -47,7 +47,7 @@ only the cleanup tools and removal subcommand are parent-only.
 
 Open workspaces are removed through Herdr. Git-only orphans use Git removal,
 verify checkout absence, and then prune stale registrations. Branches and their
-commits are retained. Session start only reports inventory counts.
+commits are retained. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory.
 
 ## Rejected alternatives
 

package/docs/adr/0012-adopt-maestro-seams-in-repo.md

@@ -0,0 +1,45 @@
+# ADR-0012: Adopt maestro seams in-repo
+
+- **Status:** Accepted
+- **Date:** 2026-10-04
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Supersedes:** Only ADR-0008's restriction on adding a runtime adapter seam without a second real execution path
+
+## Decision
+
+Adopt explicit `HarnessAdapter`, `SurfaceProvider`, and `RunSession` interfaces
+under `maestro/` in this repository. Keep one npm package and the existing
+`pi-extension/subagents/index.ts` Pi extension entry point.
+
+Pi remains the sole real harness and Herdr the sole real surface provider.
+In-memory fakes provide conformance coverage, not supported execution paths.
+Runtime composition wires the real adapter and provider; the Pi host calls
+runtime operations and core modules without importing adapters or surfaces
+directly. A dependency-rule test enforces the directory boundaries.
+
+Preserve the existing public tools, commands, role-pack protocol, completion
+evidence and delivery, worktree invariants, and persistent-specialist semantics.
+Do not add adapter registries, name-based runtime dispatch, or a second real
+harness or provider.
+
+## Why
+
+Conformance fakes make run ownership and orchestration testable without real
+Pi or Herdr resources. Explicit boundaries also prepare `maestro/` for later
+extraction without maintaining a second implementation. These needs justify
+the seam without a second real execution path.
+
+## Consequences
+
+The Pi launch module still owns each launch transaction; the run session owns
+run coordination, retries, observation, and delivery-gated cleanup. Pi-specific
+protocol code lives in `maestro/adapters/pi/`, Herdr operations in
+`maestro/surfaces/herdr/`, and harness-neutral rules in `maestro/core/`.
+
+The rest of [ADR-0008](0008-adopt-pi-only-subagent-execution.md) remains in
+force, including Pi-only execution and rejection of legacy external CLI roles.
+[ADR-0003](0003-installable-role-packs.md) continues to govern role packs.
+This decision does not extract or publish a new package, promise another
+harness, or establish that migration verification is complete. See the
+[design and migration status](../superpowers/specs/2026-10-02-maestro-seams-design.md)
+and [code map](../../README.md#code-map).

package/docs/adr/0013-pack-neutral-execution-host.md

@@ -0,0 +1,63 @@
+# ADR-0013: Ship a pack-neutral execution host
+
+- **Status:** Accepted
+- **Date:** 2026-10-05
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Supersedes:** [ADR-0001](0001-btw-ephemeral-side-questions.md); the bundled-role
+  provisions of [ADR-0003](0003-installable-role-packs.md); the shipped role and
+  workflow mapping in [ADR-0002](0002-agent-workflow-skill-runtime-taxonomy.md)
+  and the bundled-skill provision of [ADR-0009](0009-remove-workflow-subsystem.md)
+
+## Decision
+
+`pi-herdr-agents` is an execution host. It owns child execution, supervision,
+sessions, persistence, worktrees, model routing, role parsing and discovery, and
+parent delivery. It ships no agent roles and no planning or review workflows.
+The only Pi skill it ships is `pi-herdr-agents`, a general operating guide to its
+own control tools; methodology and workflow skills stay in separate packs.
+
+- The seven formerly bundled roles move to separately installed role packs:
+  `scout`, `planner`, `worker`, `reviewer`, `adversarial-reviewer`, and
+  `visual-tester` to the optional general-purpose `pi-herdr-roles` pack, and
+  `poteto` to `pi-herdr-pstack`. Neither pack has privileged discovery status.
+- `/plan`, its plan prompt, and the top-level `orchestrate` skill with its
+  supporting resources and evaluation corpus move to `pi-herdr-roles`.
+- `/iterate`, `/btw`, and `/btw-close` are removed, not relocated, together with
+  their exclusive session snapshot, surface, and launch code. Direct
+  `subagent({ fork: true, interactive: true, ... })` launches, resume,
+  persistent specialists, and `/worktree` handoff remain.
+- Registered role packs are the entire package layer. Effective precedence stays
+  project > global > package. An empty catalog is valid; bare launches need no
+  role; a missing or invalid named role fails before Herdr creates resources.
+- Existing valid `roles.bundled` booleans are accepted as deprecated no-ops. A
+  parent session reports one warning per extension load and never rewrites the
+  file. Malformed values and unknown `roles` keys remain errors.
+- The bundled-role worktree warning table is removed. The host keeps only
+  role-independent worktree guidance and does not infer write capability from
+  a `tools` allowlist.
+- Host guidance describes model-selection mechanics, not named pack workflows.
+- `PI_SUBAGENT_ID` is documented as a child-context hint: set for fresh and
+  resumed children, absent from `/worktree` handoffs, inherited by nested
+  processes, and not a security boundary. No new parent/child protocol is added.
+
+## Why
+
+Bundled roles were privileged fallbacks that blocked same-named pack roles, and
+the bundled workflows made one methodology the default for every installation.
+Separate packs let users choose the generic roles, pstack, another pack, their
+own definitions, or bare launches, and let packs release independently.
+
+The existing v1 role-pack event already supports independently installed packs,
+so no new contribution registry is needed. `/iterate` and `/btw` were unused in
+production and duplicated generic fork and session behavior.
+
+## Consequences
+
+- This is a breaking product change. Users install the packs they want; nothing
+  is installed or migrated automatically, and user role files are not edited.
+- Older hosts that still bundle the roles, `/plan`, or `orchestrate` collide with
+  the replacement packs. `roles.bundled: false` on an older host removes only the
+  role layer. Replacement packs must not claim compatibility with those hosts.
+- Lifecycle tests use test-only role fixtures instead of production roles.
+- The release version, deprecation removal date, and published compatibility
+  ranges are decided at release planning, not by this ADR.

package/docs/adr/0014-operator-cancel-terminal-intent.md

@@ -0,0 +1,134 @@
+# ADR-0014: Operator cancel records terminal intent before termination
+
+- **Status:** Accepted
+- **Date:** 2026-10-05
+- **Scope:** Public `subagent_cancel` for ordinary managed Pi subagents
+
+## Context
+
+An operator could interrupt a turn (`subagent_interrupt`) but not end a run.
+`subagent_stop` is the persistent-specialist graceful stop and rejects ordinary
+children. Closing a child's pane by hand made the watcher report "pane
+disappeared" as a provider/agent error, which the run session treated as a
+retryable failure and launched the next configured fallback model. Wrapping the
+existing primitives does not fix this: `suppress` drops delivery entirely, and
+`kill` alone produces exactly that fallback-eligible error.
+
+## Decision
+
+`RunSession.cancel(taskId)` is the one cancellation path, owned by the existing
+kernel producer, adapter, and finalization. It is not a second engine.
+
+1. **Terminal intent first.** The call records the cancel intent synchronously,
+   before any abort, kill, or await. Every later decision reads it: no fallback,
+   acquisition, retry, or recovery starts after it.
+2. **Settle point.** The producer's synchronous check after an attempt's wait
+   settles decides the race. Intent recorded before it makes the run cancelled,
+   even if natural evidence (including the kill's own pane-loss evidence)
+   arrived first. A natural result that cannot start a fallback, taken before
+   the intent, stays authoritative and cancel reports `already-terminal`. A
+   cancel during a fallback-eligible attempt's finalization still wins because
+   that result was not terminal.
+3. **Owned termination.** The kernel calls the owning adapter's `kill` for the
+   current attempt, one kill at a time; concurrent cancels join it. Only a
+   resolved kill confirms termination, and only then is the producer's wait
+   aborted, so a failed kill leaves the run supervised.
+4. **Pending acquisition.** With an acquisition in flight, cancel reports
+   `requested`. The acquired owner is registered as usual, so it is never
+   leaked, and killed immediately; no later candidate is attempted. The
+   kernel projects the cancel state (`requested`, then each kill's outcome,
+   including kills it starts itself) onto whichever owner is current, so a
+   transferred owner's unconfirmed kill is visible. A cancel
+   before any acquisition rejects the launch without acquiring anything. If
+   the in-flight acquisition fails, the settled previous attempt is still owned
+   and is terminated before delivery. Once every fallback launch has failed,
+   the natural failure is terminal before its delivery starts, so a later
+   cancel reports `already-terminal`.
+5. **One result.** A confirmed cancel is finalized once by the attempt that owns
+   it and delivered once with the existing `killed` outcome and a
+   `cancellation` record (`requestedAt`, `termination`, `confirmedAt`). Pi
+   presents it with its existing "Subagent cancelled." summary and `cancelled`
+   error marker, never as a provider failure.
+6. **Unconfirmed is not terminal.** A failed kill reports `unconfirmed` with the
+   error. The run keeps its live ownership, watcher, row, and panes; nothing is
+   delivered, retired, or released. A retry repeats the kill and keeps the first
+   `requestedAt`. If the wait later settles on its own, the producer makes one
+   kill attempt itself, then waits for an operator retry or shutdown
+   suppression, which settles without delivery and is not a cancellation:
+   a worktree manifest records what a plain shutdown would, never
+   `cancelled`.
+7. **Surface ownership.** Pi `kill` closes an ordinary pane and confirms its
+   absence through Herdr; a close error on an already-absent pane is still
+   confirmed by that absence. A managed-worktree root pane is the retained
+   review workspace, and Herdr refuses to close it. For that child, `kill`
+   acts only on the child's **process identity**, established at launch from
+   immutable kernel facts, never from command-line text: Pi assigns
+   `process.title`, which rewrites `/proc/<pid>/cmdline` and erases
+   `--session`, and Herdr lists foreground processes only.
+   - *Capture.* The child protocol extension records its own PID, `/proc`
+     start time, boot ID, and PID-namespace link into a once-only sidecar
+     beside its session (`<session>.process.json`). In the background after
+     launch, the parent accepts the record only for this run and session,
+     only while that PID is alive with that start time on this boot in the
+     parent's own PID namespace (also proven by `/proc/self` naming the
+     parent), and only as Herdr's pane shell or a descendant of it. The
+     identity lives on the run record. A shell PID merely existing locally is
+     not namespace evidence; the recorded namespace link is.
+   - *Signal.* SIGTERM goes only to that identity, re-read (PID and start
+     time) immediately before `kill(2)`; a mismatch or read error is never
+     signalled. Node exposes no pidfd signal, so the kernel could still reuse
+     the PID between that read and the signal; this needs the Pi to exit and
+     its PID to be recycled within that window. There is no SIGKILL.
+   - *Confirm.* Confirmed only when that identity no longer exists (PID
+     absent, or a zombie), or when the pane is gone while the identity is not
+     known alive; an identity captured during that pane check is judged
+     before confirming. A live identity (including a suspended Pi with
+     SIGTERM pending) stays unconfirmed. An identity not captured (no record,
+     capture still pending at the kill deadline, a non-Linux host, a handoff
+     or resumed child), unreadable, from another boot or PID namespace, or
+     whose PID now has another start time is not signalled and is
+     unconfirmed unless pane absence confirms termination.
+   - *Bound.* Every provider await (Herdr process info during capture, pane
+     inspection during cancel) is bounded by the remaining capture or kill
+     deadline, so `unconfirmed` is reported on time; a late answer is
+     dropped and never flips a reported outcome. A cancel after the launch
+     capture expired starts one fresh capture bounded by that cancel's own
+     deadline, so a retry can pick up a sidecar written late.
+
+   The manifest records `cancelled` only for
+   confirmed termination, and the handoff is captured as for any completion.
+   There is no Git cleanup.
+8. **Persistent specialists are rejected** before any kill; `subagent_stop`
+   keeps its graceful v1 semantics.
+
+## Consequences
+
+- Cancel never confirms more than its evidence: ordinary confirmation is Herdr
+  pane absence, which terminates the pane's PTY, not an OS PID check. Worktree
+  confirmation is the launch-captured process identity ceasing to exist; a
+  stopped Pi keeps SIGTERM pending and stays unconfirmed until it is resumed
+  or exits. The identity is the child's own report, trusted like its other
+  sidecars and bounded by liveness, namespace, and pane-ancestry checks at
+  capture.
+- Worktree cancel is Linux-only in effect: elsewhere no identity is captured,
+  nothing is signalled, and only a gone pane confirms.
+- An unconfirmed cancel can leave a live row indefinitely until a retry, the
+  child's exit, manual pane closure, or parent shutdown.
+- Late callbacks after delivery change nothing: the retired ID answers
+  `already-terminal`.
+
+## Rejected alternatives
+
+- **Boolean flag plus gate around `kill`:** it misses pending acquisitions, the
+  abort-before-confirmation race, and finalization provenance.
+- **`suppress` then `kill`:** it drops the one result the parent is waiting for.
+- **Deliver `unconfirmed` and retire:** it would release live ownership whose
+  process may still be writing.
+- **Close the worktree root pane:** it would discard the retained review
+  workspace that worktree runs promise to keep.
+- **Match the owned process by argv (`--session`):** Pi's process-title
+  rewrite erases it, so a live Pi looked exited.
+- **Treat a visible pane-shell PID as a shared PID namespace:** an unrelated
+  local process can hold the same number.
+- **Escalate to SIGKILL automatically:** an operator retry repeats the bounded
+  SIGTERM check instead; forced escalation stays outside this decision.

package/docs/worktree-subagents.md

@@ -4,7 +4,7 @@ This guide is the operational reference for running writing agents in isolated G
 
 ## Quick start
 
-Run Pi inside Herdr from a Git checkout, then give each independent writing task a unique branch:
+Run Pi inside Herdr from a Git checkout, then give each independent writing task a unique branch. The examples name `worker`, `scout`, and `reviewer` roles; `pi-herdr-agents` ships no roles, so those names must come from an installed role pack or a project/global definition. Omit `agent` for a bare child.
 
 ```typescript
 subagent({
@@ -36,17 +36,19 @@ subagent({
 });
 ```
 
+Omit `worktree` for an ordinary pane. If a generated tool client requires every declared property, pass `worktree: null`; the extension treats it exactly like omission and starts the child in `cwd` without calling `herdr worktree create`.
+
 Worktrees isolate checkouts, indexes, and `HEAD`. They are **not security sandboxes**: worktrees still share the repository's object database and most refs, and the child process has the same host permissions as Pi.
 
 ## Launch contract
 
 For a worktree launch:
 
-- `cwd` selects the source Git repository. A relative tool argument is resolved from the parent Pi process's current directory.
+- `cwd` selects the source Git repository. A relative tool argument is resolved from the parent Pi process's current directory. When `cwd` is a linked checkout, Herdr provisioning uses its principal checkout while the requested checkout supplies the base SHA and manifest provenance.
 - `worktree.branch` is a new, unique branch name. Git/Herdr rejects a branch that cannot be created or is already checked out elsewhere.
 - `worktree.base` may be any revision that resolves to a commit in the source repository. It defaults to committed `HEAD`.
 - The extension resolves `base` to an exact SHA, writes an ownership manifest, then calls `herdr worktree create --no-focus`.
-- The child starts at the root of the returned worktree, in that workspace's retained root pane and newly owned `Agents` tab. Finishing Pi returns to the interactive checkout shell; it does not close the root pane.
+- The child starts at the root of the returned worktree, in that workspace's retained root pane and newly owned `Agents` tab. Finishing Pi returns to the interactive checkout shell; it does not close the root pane. A successful launch from a linked checkout does not itself authorize cleanup there: cleanup checks the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd.
 - Uncommitted and untracked files from the parent checkout are not copied. Commit anything the child must see before spawning it, or pass the needed context in the task.
 - Worktree creation does not steal terminal focus.
 
@@ -112,6 +114,7 @@ Possible states are:
 | `ready_for_review` | Child exited successfully; workspace retained |
 | `needs_help` | Child called `caller_ping`; workspace retained |
 | `failed` | Creation, launch, or execution failed; any created workspace is retained |
+| `cancelled` | The parent cancelled the run with `subagent_cancel` and the exit of the child's launch-verified Pi process identity was confirmed; workspace, checkout, and commits retained |
 | `removed` | Explicit parent cleanup verified checkout absence; branch and manifest retained |
 
 The manifest supports ownership and inspection; v1 does not provide automatic reconciliation after a full Pi/Herdr restart. Do not edit manifests by hand.
@@ -146,7 +149,7 @@ For parallel read-only review, prepare one stable existing checkout of the pull
 
 A `read,bash` tool allowlist does not enforce read-only behavior because Bash can mutate the checkout. Tell public reviewers to use only safe inspection, avoid artifact-generating verification, and consume supplied mechanical evidence. Public completion reports above 16,000 characters are abbreviated; when a completed report is needed, retrieve its final assistant message once from the supplied session path with bounded output. This is evidence retrieval, not live-session polling.
 
-For a committed candidate, prefer the `/skill:orchestrate` adversarial procedure. Its approved runner creates one detached checkout pinned to the review head. Effective tools are the resolved role allowlist intersected with the runner maximum (`read`, `grep`, `find`, and `ls`) and deny rules; an override can reduce that set. The parent must materialize the changed-file inventory and unified diff, or complete before/after excerpts, because head-checkout reads cannot recover deleted or base-only blobs. Parent dirty and untracked state is absent. Use the `adversarial-reviewer` compatibility coordinator only when its weaker public-child boundary is intentional and project policy permits it.
+Review workflows supplied by role packs, such as `/skill:orchestrate` in `pi-herdr-roles`, build on this public-child pattern and document their own methodology. The host provides no review runner and creates no private review checkout. Reviewers read a head checkout, so the parent must materialize the changed-file inventory and unified diff, or complete before/after excerpts, because head-checkout reads cannot recover deleted or base-only blobs. Effective tools are the resolved role allowlist and deny rules.
 
 ```typescript
 subagent({
@@ -191,6 +194,7 @@ The extension never pushes, creates a PR, merges, cherry-picks, or changes the p
 - **Creation failure:** the manifest is marked failed. If Herdr created the branch but returned an incomplete response, the extension reconciles a unique branch match through `/worktree list` and records any recovered workspace/path.
 - **Launch failure after creation:** the manifest is marked failed and the workspace, forked session, and path are retained. The destination is not focused unless Pi startup is confirmed.
 - **Worker failure:** summary and available Git state are returned; the workspace remains open. Auto-exit waits until Pi is fully settled, so a transient provider error followed by automatic compaction or retry does not end the worker early.
+- **Operator cancel:** `subagent_cancel` never closes the retained root pane or workspace. At launch, the child's protocol extension records its own process identity (PID, `/proc` start time, boot ID, and PID-namespace link) in `<session>.process.json`, and the parent accepts it only while that process is alive in the parent's PID namespace as the Herdr pane shell or a descendant of it. Cancel sends SIGTERM only to that identity, re-verified (PID and start time) immediately before the signal, then confirms that the identity no longer exists, or that the pane is gone while it is not known alive. Command-line text and Herdr's foreground list are never evidence: Pi rewrites its process title, and Herdr lists foreground processes only. A live identity (such as a suspended Pi with SIGTERM pending), or one whose SIGTERM fails while it is still alive, leaves termination `unconfirmed` even if the pane is gone. An identity that was not captured (including on non-Linux hosts), is unreadable, belongs to another boot or PID namespace, or whose PID now has another start time is never signalled and also leaves it `unconfirmed` unless pane absence confirms termination. The PID could still be reused between the final check and the signal, because Node has no pidfd signal. Every Herdr query is bounded by the cancel deadline, and an answer that arrives after the deadline, even before the timer runs, never changes the reported outcome. The run stays live, and retrying `subagent_cancel` re-checks; if the launch capture expired, the retry captures the identity again within its own deadline. On confirmation, the manifest is marked `cancelled` and the normal Git handoff is delivered once. A parent shutdown while termination is unconfirmed records the plain shutdown state, never `cancelled`. No Git cleanup, branch change, or removal happens.
 - **`caller_ping`:** the child exits with `needs_help`; continue worktree-bound follow-up in the retained workspace rather than through `subagent_resume`. Public `subagent_resume` rejects managed-worktree child sessions before creating a pane so it cannot silently lose worktree ownership or policy.
 - **Parent `/reload`, `/new`, `/resume`, or `/fork`:** active in-memory watchers transfer to the replacement parent session.
 - **Full process restart or crash:** the worktree remains, but v1 does not automatically rediscover and resume its watcher.
@@ -217,7 +221,7 @@ Parent sessions have an inspect-only inventory and an explicit removal surface:
 
 The equivalent tools are `worktree_list({})` and `worktree_remove({ target, preserve?: true })`. Use the exact path when a branch name is ambiguous. Children are not offered these tools or `/worktree remove`. Their existing `/worktree list` (repository-local Herdr listing) and `/worktree <name>` handoff remain available. Detached entries are labeled `(detached HEAD)` in the child listing and do not prevent cleanup inspection of named-branch siblings; the detached checkout itself remains blocked.
 
-Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
+Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. For linked checkouts, this means the canonical principal/source repository under the invoking parent session's cwd; a successful launch does not itself authorize cleanup, and authorization does not use `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
 
 Removal rechecks containment, Git registration, no detected process holder, known live child, or persistent-specialist lease, and no uncommitted, untracked, or conflicted files. Liveness checks observable same-user processes from any session with a cwd inside the checkout, regardless of runtime name (including thread-suffixed Node names). Only Herdr-confirmed idle retained shell PIDs are exempt; an active runtime at the same PID is not. Detached HEAD, locked checkouts, initialized submodules, and conflicting identity evidence block removal. For initialized submodules, deinitialize them deliberately or use operator removal. No force option is provided.
 
@@ -231,7 +235,7 @@ Ignored files do not block cleanup. Inventory shows their exact file count, and
 
 Open workspaces are removed through Herdr. Git-only orphans use `git worktree remove`, verify checkout absence, and then prune stale Git registrations. Failed removal is reported, never forced. A reachable owned manifest is merge-updated to `removed` with `workspaceRemovedAt` only after success; absent cross-session manifests are reported and are not rewritten. A manifest update failure after removal is a removed-with-warning result, not a failed removal. Removed manifests provide already-removed no-op evidence only; a new checkout at the same path is classified independently. Missing and dangling manifest paths are non-matches. Permission errors, symlink loops, and other undecidable manifest identities remain blockers, as do genuine identity disagreements. Cleanup Git and Herdr calls have 30-second timeouts; a timed-out operation fails closed rather than proceeding with removal.
 
-Branches and their commits are always retained: cleanup never deletes, force-updates, or rewrites a branch. It never runs on completion, shutdown, or a timer. Inside Herdr with its CLI available, parent session start emits only one compact inventory count when contained worktrees remain. Outside Herdr, startup skips the automatic inventory; explicit inventory tools remain available and report unavailable inspection as unknown. Unsupported platforms or failed global process enumeration block removal; individual visibility gaps are disclosed warnings, never proof that an orphan is idle.
+Branches and their commits are always retained: cleanup never deletes, force-updates, or rewrites a branch. It never runs on completion, shutdown, or a timer. Session startup skips worktree inventory to avoid blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. Outside Herdr, explicit inventory tools remain available and report unavailable inspection as unknown. Unsupported platforms or failed global process enumeration block removal; individual visibility gaps are disclosed warnings, never proof that an orphan is idle.
 
 ## Current limits