pi-herdr-agents 1.7.0 → 2.0.1

package/AGENTS.md

@@ -48,7 +48,7 @@ Preserve these invariants when changing worktree behavior:
 6. Herdr creates the workspace without stealing focus; launch targets the returned root pane explicitly.
 7. Successful, failed, and help-requesting runs retain their worktree workspace.
 8. Completion reports reviewable Git state; inspection failures are unknown, never guessed clean or conflict-free.
-9. The extension does not push, create PRs, merge, cherry-pick, switch the parent checkout, or remove worktrees/branches automatically.
+9. The extension does not push, create PRs, merge, cherry-pick, switch the parent checkout, or remove worktrees automatically. Explicit parent-owned cleanup uses cwd containment and fail-closed eligibility; branches are never deleted.
 10. Ordinary non-worktree subagent behavior remains unchanged.
 
 Read [`docs/worktree-subagents.md`](docs/worktree-subagents.md) before changing any of these semantics.
@@ -105,8 +105,8 @@ Use `PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run te
 Before committing:
 
 - inspect `git status` and the final diff;
-- confirm the package preview includes `CHANGELOG.md`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, and `skills/orchestrate/adversarial-review-example.js`, while excluding `pi-extension/subagents/workflow-worker.js`, plans, journals, sessions, prototypes, generated evidence, and local config;
-- run `npm pack --dry-run` when package contents or documentation paths changed;
+- confirm the package preview includes `CHANGELOG.md`, `skills/orchestrate/SKILL.md`, `skills/orchestrate/adversarial-review.md`, and `skills/orchestrate/adversarial-review-example.js`, while excluding `pi-extension/subagents/workflow-worker.js`, plans, journals, sessions, prototypes, generated evidence, local config, and `openspec/`;
+- run `npm pack --dry-run` when package contents or documentation paths changed; durable configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`, never package-root `config.json` (move old files manually or re-run `/subagents-init`);
 - confirm that no generated plans, journals, sessions, provider configuration, test scripts, or review artifacts are staged; and
 - confirm that no accidental empty directory exists at the repository root:
 

package/CHANGELOG.md

@@ -7,7 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.7.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.6.0...v1.7.0)
+## [v2.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.0...v2.0.1)
+
+### Merged
+
+- fix: initialize task routing from the live model registry [`#51`](https://github.com/giuseppecrj/pi-herdr-agents/pull/51)
+
+## [v2.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.7.0...v2.0.0) - 2026-09-18
+
+### Merged
+
+- feat(subagents): task-category model routing, durable global config, and /subagents-init [`#49`](https://github.com/giuseppecrj/pi-herdr-agents/pull/49)
+- feat(subagents): managed worktree inventory and explicit cleanup [`#50`](https://github.com/giuseppecrj/pi-herdr-agents/pull/50)
+
+### Commits
+
+- feat(subagents): explicit worktree cleanup (astra build) [`76736b2`](https://github.com/giuseppecrj/pi-herdr-agents/commit/76736b23f661331d028c56f95541c5b859b0f6e2)
+- fix(subagents): verify cleanup safety and disclose process visibility [`5ec8631`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5ec86310bb4a33c737557cb1664fda669a971ff8)
+- add openspec [`7a73e0c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7a73e0c9cd3fadfaae941fabd6c71e07226f8214)
+- fix(subagents): harden worktree cleanup after adversarial review [`d3c7e7f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d3c7e7f732b88b895077e8a8c2a946d5f616562c)
+- feat(subagents): add task model routing [`07fce0d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/07fce0d10febce30d21db862c2ae91f435f627de)
+- fix(subagents): repair task model routing review findings [`912ac78`](https://github.com/giuseppecrj/pi-herdr-agents/commit/912ac78fadbb5ab2011f6b9ec680ffb51ad7f9d5)
+- docs(openspec): propose task-model-routing change [`6b97fc7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/6b97fc73bd9cf68dce2275db4882622d1fcee6e2)
+- docs(openspec): address adversarial review of task-model-routing [`7942440`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7942440c0fe21b8900f56aba2563f57330037e82)
+- chore: release v2.0.0 [`211a43b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/211a43b01c304b59e867ee7003b6f68573cebeda)
+- test(integration): harden cleanup test against wrap and holder races [`635c79b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/635c79b5fe4f5cda35ad46be9575144ed7f9bf7a)
+- docs(openspec): check off 5.2 after live /subagents-init verification [`879438d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/879438d50b1944631c42cec6009bab9ba8226a6c)
+
+## [v1.7.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.6.0...v1.7.0) - 2026-09-09
 
 ### Merged
 
@@ -23,6 +50,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - fix(subagents): keep no-progress recovery guidance evidence-based (#40) [`9cbf155`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9cbf155e291c063f70ef86800ef3bfe3c742c6c6)
 - test(integration): hang advisory coverage (#40) [`075f4fe`](https://github.com/giuseppecrj/pi-herdr-agents/commit/075f4feb17938df28a92fa00851d606e5a83b258)
 - fix(subagents): preserve boundary-aligned records in bounded session tails (#40) [`f096fdb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f096fdb681921e9ab460610d53e456758802725f)
+- chore: release v1.7.0 [`371265e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/371265e74fb7485afbfbc7c028d60dc4f98d2779)
 
 ## [v1.6.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.1...v1.6.0) - 2026-09-08
 

package/CONTEXT.md

@@ -99,3 +99,64 @@ _Avoid_: Completed agent process, disposable pane, automatic worktree cleanup
 The lifetime-exclusive binding between a persistent specialist generation and
 one managed worktree, when that specialist writes in a worktree.
 _Avoid_: Rebindable checkout, shared worktree ownership
+
+**Worktree inventory**:
+An inspect-only view joining managed checkout discovery, Git registration/state,
+Herdr workspace association, and reachable owned manifests, including orphans.
+_Avoid_: Session-only resource list, cleanup action
+
+**Cwd containment**:
+Cleanup authorization requiring the canonical source repository root to equal or
+be a descendant of the invoking session's canonical cwd.
+_Avoid_: Managed-path containment, manifest ownership authorization
+
+**Cleanup eligibility**:
+Fresh evidence of cwd containment, registered checkout identity, a named branch,
+no detected process holder, known live child, or persistent lease, and clean Git
+state. Only Herdr-confirmed idle retained shells are exempt from process checks,
+never runtimes at the same PID. Ignored files and individual process-visibility
+gaps are disclosed, not blockers. Other unknown evidence blocks removal.
+_Avoid_: Guessed idle, presumed clean
+
+**Process-inspection warning**:
+Non-blocking disclosure of incomplete same-user process visibility, separate
+from cleanup blockers and requiring no override flag. Scanning continues after
+unreadable details; detected holders still block. Other-user processes are not
+inspected, and a protected process could hold the checkout undetected. Failed
+global enumeration and unsupported platforms remain blockers.
+_Avoid_: Proven unrelated, machine-wide inactivity, bypass permission
+
+**Explicit worktree removal**:
+A parent-requested removal of one named managed checkout and its open workspace,
+with absence verification and retained branch history. Never automatic reaping.
+_Avoid_: Branch deletion, completion cleanup
+
+**Dirty-state preservation**:
+Explicit opt-in staging and WIP commitment of a worktree's uncommitted and
+untracked files on its retained branch before rechecking removal eligibility.
+Ignored files are not captured. Commit failure restores the original index.
+_Avoid_: Implicit commit, stash, discard
+
+**Task-category model preference**:
+An ordered authenticated model shortlist in `models.tasks` for `coding`,
+`review`, `recon`, `qa`, `architecture`, or `docs`. Recon maps to scouts,
+architecture to planning and diagnosis, coding to workers, review to reviewers,
+QA to software and test runners, and docs to documentation workers. Categories
+describe work, not complexity. `/subagents-init [preferences]` drafts them from
+the active extension-loaded registry's synchronous snapshot and existing saved
+choices, with source-based research when available. A dynamic provider awaiting
+its initial catalog refresh might be absent. `task:<category>` is a subagent
+model selector, not a command or parent model change. Ordered authenticated
+candidate plans resolve before launch; ordinary nonpersistent runs can retry
+after launch failure or a running child's provider/agent error, not a completed
+negative task result. Persistent specialists do not advance after a running-child
+error. Worktrees select the first authenticated candidate only, without fallback
+retries. Reviews use exact IDs from a different author family when the author
+is known.
+_Avoid_: Generic tier, reviewer-family enforcement, per-step routing
+
+**Loop template**:
+A future reusable orchestration definition beside `models`, describing stages,
+task categories, and a termination/report contract. Loop templates are not
+implemented by task-model routing.
+_Avoid_: Current executable workflow

package/README.md

@@ -119,7 +119,7 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 
 ### Extensions
 
-**Subagents** — 6 main-session tools + 6 commands, plus 2 child-only tools:
+**Subagents** — 9 parent-session tools + 7 commands, plus 2 child-only tools:
 
 | Tool                 | Description                                                                                 |
 | -------------------- | ------------------------------------------------------------------------------------------- |
@@ -128,7 +128,10 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | `subagent_send`      | Deliver a follow-up task to an idle persistent specialist                                   |
 | `subagent_stop`      | Gracefully stop a persistent specialist after its active task settles                      |
 | `subagents_list`     | List available agent definitions                                                            |
+| `worktree_list` | Parent-only inspect-only inventory of managed worktrees and cleanup blockers |
+| `worktree_remove` | Parent-only explicit removal by `target` path, branch, or workspace ID; optional `preserve: true` commits dirty state first |
 | `subagent_resume`    | Resume a previous Pi-backed sub-agent session in a new ordinary pane (async)                          |
+| `subagents_write_task_models` | Parent-only internal tool that validates and atomically writes `models.tasks` preferences |
 
 | Pi child-only tool | Description |
 | ---------------- | ------------------------------------------------------------------------- |
@@ -143,6 +146,7 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | `/btw-close`               | Close the current BTW session        |
 | `/worktree <name> [task]`  | Continue this session in a new managed worktree (`/worktree list` lists them) |
 | `/subagent <agent> <task>` | Spawn a named agent directly (`/subagent list` lists available agents) |
+| `/subagents-init [preferences]` | Draft task-category model preferences from the live authenticated registry, with optional ranking preferences |
 
 ### Taxonomy and discovery
 
@@ -271,20 +275,13 @@ A fixed internal watchdog marks a run as `stalled` when pane inspection fails or
 
 #### Configuration
 
-The extension reads `config.json` from the installed package root—the directory
-containing this README and `package.json`, not `pi-extension/subagents/` or
-Herdr's `config.toml`. That file is package-local: npm or git package updates may
-overwrite it. Common global package roots are:
-
-- npm: `~/.pi/agent/npm/node_modules/pi-herdr-agents/`
-- git: `~/.pi/agent/git/<host>/<owner>/pi-herdr-agents/`
-
-Project-local installs use the corresponding `.pi/npm/` or `.pi/git/` root.
-From the actual package root, copy the example when you want local overrides:
-
-```bash
-cp config.json.example config.json
-```
+The durable user configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`,
+defaulting to `~/.pi/agent/herdr-agents/config.json`. It is not read from the
+installed package root, so npm and git package upgrades do not overwrite it.
+Create it by copying the installed package's `config.json.example`, or run
+`/subagents-init` to seed and draft model task preferences. This is a breaking
+migration: manually move an existing package-local `config.json` to this path,
+or re-run `/subagents-init`.
 
 ```json
 {
@@ -327,11 +324,93 @@ exact IDs from your authenticated model catalog:
     "agents": {
       "scout": "your-provider/your-fast-model",
       "reviewer": "your-provider/your-review-model"
+    },
+    "tasks": {
+      "coding": ["your-provider/your-coding-model"],
+      "review": ["your-provider/your-review-model"],
+      "recon": ["your-provider/your-fast-model"],
+      "qa": ["your-provider/your-qa-model"],
+      "architecture": ["your-provider/your-architecture-model"],
+      "docs": ["your-provider/your-docs-model"]
+    },
+    "tasksMeta": {
+      "generatedAt": "2026-09-17T00:00:00Z",
+      "method": "research"
     }
   }
 }
 ```
 
+`models.tasks` candidates are ordered exact authenticated IDs. Use
+`task:<category>` only in the `subagent` tool's `model` argument; it is not
+valid in frontmatter or model defaults. For review when the authoring family is
+known, choose an exact shortlist ID from a different family rather than
+`task:review`; this is guidance, not extension enforcement.
+
+Run `/subagents-init [preferences]` to draft task-model preferences. For example:
+
+```text
+/subagents-init Prefer capability over price for implementation; keep recon inexpensive
+```
+
+The command supplies a sanitized snapshot of **all available models from the
+active session registry**, including extension-registered providers, exact IDs,
+display names, reported base token costs, context/output limits, input
+modalities, reasoning, and supported thinking levels. Safe extension-registration and auth-source
+metadata is included when Pi exposes it; credentials, endpoints, and raw auth
+labels are not. Configured authentication does not prove account access or a
+successful request. Missing costs remain unknown; reported zero does not mean
+free, and OAuth does not establish subscription billing. The brief uses compact
+JSON without truncating models and reports its model count and JSON character
+count (not a token estimate); large catalogs still consume context. This is the
+current synchronous snapshot: a dynamic provider whose initial catalog refresh
+has not completed might be absent. Init does not refresh providers or probe the
+network for availability.
+
+The draft considers current saved task, default, and per-agent preferences.
+Optional command arguments set ranking preferences. Otherwise it favors
+capability for substantive work and efficiency for bounded reconnaissance and
+test execution. Categories describe work, not complexity tiers:
+
+| Category | Work |
+| --- | --- |
+| `coding` | Implementation workers |
+| `review` | Code reviewers |
+| `recon` | Reconnaissance scouts |
+| `qa` | Software and test runners |
+| `architecture` | Planning and diagnosis |
+| `docs` | Documentation workers |
+
+Init asks the agent to research major candidates across providers using primary
+sources, disclose uncertainty and notable exclusions, and avoid duplicate
+upstream models across routes unless deliberate redundancy is explained. Display
+names help identify candidates but, like aliases, do not prove upstream
+equivalence; research is still required. Price or context size alone is not
+quality evidence. It reports `registry-only` when
+search is unavailable or yields no usable evidence; no live model probes run.
+
+The writer validates and atomically replaces `models.tasks` and `tasksMeta`,
+preserving unrelated settings. Its tool schema accepts partial nonempty
+categories (omitted categories are removed), rejects empty `tasks: {}` input,
+and rejects exact duplicate refs within a category after trimming;
+IDs remain case-sensitive. Its result includes normalized saved `tasks`,
+`tasksMeta`, `configPath`, and `missingCategories`. Init requests all six categories
+and a before/after table based on that saved result, not the unsaved draft. It
+must explain missing categories or changed choices; with no available models,
+it must report the limitation without writing.
+
+`task:<category>` values select subagent models; they are not slash commands and
+do not change the parent model. Ordered authenticated candidate plans resolve
+before launch. Ordinary nonpersistent runs can retry later candidates after
+launch failure or after a running child settles with a provider/agent error,
+not after a completed negative task result. Persistent specialists do not
+advance after a running-child error. This is not per-step routing; worktrees
+use the first authenticated candidate only, without fallback retries.
+Shortlists do not enforce reviewer independence: select an exact reviewer from
+a different author family when the author is known, and a different provider
+when project policy requires it. Another route to the same family is not
+independent review. Run `/reload` (or start a new session) after writing preferences.
+
 Set `persistent.maxAgents` to the maximum concurrently retained persistent specialists. It defaults to `3`; a persistent spawn at the cap is rejected before Herdr creates a pane or workspace, and no specialist is evicted.
 
 Set `roles.bundled` to `false` to exclude this package's bundled role definitions from listing and exact-name launch. It defaults to `true`. Registered role packs remain available, and global and project definitions keep their existing precedence. A role-pack name collides with a bundled role only while that bundled layer is enabled; when it is disabled, the role pack can supply that name.
@@ -344,7 +423,7 @@ collection; it never establishes a result by itself. If the watcher or shared
 pane inspection becomes unavailable, supervision quietly returns to the legacy
 one-second polling cadence. No caller action is required.
 
-Set `supervision.forcePolling` to `true` in the package-local `config.json` to
+Set `supervision.forcePolling` to `true` in the durable user `config.json` to
 disable wake-ups and use that legacy cadence deliberately. The setting is read
 when the coordinator is created, so run `/reload` after changing it.
 `subagents_list` reports the active transport mode (`wake+batch`,
@@ -405,7 +484,9 @@ Run `/reload` after changing role, model, or pane settings.
 followed by agent frontmatter, per-agent config, the global default, and finally
 the parent model. Model values must be exact authenticated `provider/model-id`
 references. A value can contain an ordered comma-separated fallback list, for
-example `provider/preferred, provider/fallback`. The extension validates every
+example `provider/preferred, provider/fallback`. The tool argument also accepts
+`task:<category>` as its complete value (not in a list), for configured
+`coding`, `review`, `recon`, `qa`, `architecture`, or `docs` preferences. The extension validates every
 candidate before launch, then launches later candidates only after the selected
 child settles with a provider/agent error. Pi owns any automatic transient
 retrying inside that child; the extension does not infer retry counts or
@@ -425,10 +506,9 @@ claim a permanent failure or a retry count that Pi has not exposed. Reliable
 structured permanence and retry counts require an upstream Pi/ExtensionAPI
 diagnostics seam for final provider errors and retry outcomes.
 
-`config.json` is gitignored in the source tree so local overrides are not
-committed from a checkout. On an installed package root, treat it as disposable
-local state that package updates may replace. Run `/reload` after changing it;
-status, model, role, and pane configuration are loaded when the extension starts.
+`config.json` is durable user state under the Pi agent directory and is loaded
+when the extension starts. Run `/reload` after changing it. Package-root
+`config.json` files are ignored; move them manually or re-run `/subagents-init`.
 
 ---
 
@@ -468,7 +548,7 @@ subagent({
 | `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `persistent`           | boolean | `false`        | Keep one specialist session alive for sequential tasks; follow-ups use `subagent_send` only       |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
-| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; fallback lists are unavailable for worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
+| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, ordered fallback list, or whole-value `task:<category>` (coding, review, recon, qa, architecture, docs). Task routing is tool-only; worktrees use its first authenticated candidate. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
 | `thinking`             | string  | parent level   | Pick the model tier first, then set thinking within that model's range: minimal/low for bounded mechanical work, medium for ordinary implementation or review, high+ for architecture, security, or hard diagnosis. Omitting still inherits the parent level; this is a discouraged fallback for orchestrated children. |
 | `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; named agents keep their definition body                  |
 | `skills`               | string  | —              | Comma-separated skill names                                                                       |
@@ -636,10 +716,18 @@ BTW shares the current working directory. It treats inherited work as reference
 
 ## The `/worktree` Workflow
 
-`/worktree <worktree> [task]` creates a Herdr-managed worktree from the current committed branch and launches a new interactive Pi session there with the active conversation branch. The original session remains available. Use `/worktree list` to list worktrees for the current repository. This is a new-process handoff, not an in-place move of the existing shell or Pi process.
+`/worktree <worktree> [task]` creates a Herdr-managed worktree from the current committed branch and launches a new interactive Pi session there with the active conversation branch. The original session remains available. Use `/worktree list` or `worktree_list({})` to inspect managed worktrees, including cross-session orphans, whose canonical source repositories are inside the session's cwd subtree. This is a new-process handoff, not an in-place move of the existing shell or Pi process.
 
 ---
 
+### Explicit worktree cleanup
+
+Parent sessions can call `worktree_remove({ target: "<path|branch|workspace-id>", preserve: true })` or `/worktree remove <target> [--preserve]`. Preservation is optional and never implied: dirty work is blocked unless explicitly committed first or preserved as a WIP commit. The result reports its SHA even if removal later fails or is refused. A failed preservation commit restores the pre-preservation index and never proceeds to removal. Inventory and removal reports disclose exact ignored-file counts: enumeration is streamed rather than buffered as one listing. Ignored files do not block cleanup and are not captured by preservation; failed counting still blocks removal.
+
+Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
+
+Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session start only reports retained-worktree counts. Child sessions retain `/worktree list` and `/worktree <name>`, but receive neither cleanup tools nor the remove subcommand. Their repository-local listing labels detached entries `(detached HEAD)`; a detached sibling does not prevent inspection of named branches. See [cleanup and recovery](docs/worktree-subagents.md#cleanup) for details.
+
 ## Custom Agents
 
 Custom agent roles are the package's primary extension mechanism. Create one

package/RELEASING.md

@@ -41,7 +41,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, and local `config.json`, and that the worktree integration tests leave no test workspace behind.
+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`.
 
 ## npm authentication
 

package/agents/adversarial-reviewer.md

@@ -40,7 +40,9 @@ identify missing evidence.
    `fork: false` does not override role `session-mode: fork`. Stop for a
    non-standalone or unknown mode so no reviewer inherits coordinator context.
 4. Use the model-catalog source identified by the `subagent` tool guidance or
-   another project-approved source. Record that source, how authentication was
+   another project-approved source. Curated task shortlists can inform selection,
+   but review must name an exact ID and exclude known author families; never use
+   `task:review` when that exclusion is required. Record that source, how authentication was
    confirmed, eligible distinct exact IDs, and only IDs actually considered but
    omitted, with reasons. Never guess unknown catalog entries. Identify every
    provider/model family that authored the reviewed material, or confirm that it

package/docs/README.md

@@ -41,6 +41,7 @@ uses an isolated Herdr server and writes uncommitted raw samples to
 | [`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. |
 | [`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. |
 
 ## Historical material
 

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

@@ -143,7 +143,7 @@ Apply these rules:
 
 1. Prefer per-invocation `model` and `thinking` for a workflow's deliberate
    diversity or cost/quality policy.
-2. Use ignored local `config.json` for a person's durable role preferences.
+2. Use `$PI_CODING_AGENT_DIR/herdr-agents/config.json` for a person's durable role preferences; package-root configuration is ignored, so move an older file manually or re-run `/subagents-init`.
 3. Leave bundled role `model` unset unless a particular model is a functional
    prerequisite.
 4. State runtime prerequisites before launch and fail closed when a required

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

@@ -81,7 +81,7 @@ Within the package layer:
 
 - bundled roles are protected fallbacks while enabled;
 - a role pack colliding with an enabled bundled name is rejected;
-- copying `config.json.example` to package-local `config.json` and setting `roles.bundled` to `false` removes only the bundled layer; registered role packs remain package roles and may supply those names;
+- 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;
 - collisions never resolve through incidental extension load order.
 
@@ -95,7 +95,7 @@ before Herdr creates a pane or worktree.
 ## Reload and security
 
 Role files are read on each list or launch, so editing Markdown does not require
-`/reload`. Changing package-local role configuration, installing, removing,
+`/reload`. Changing durable user role configuration, installing, removing,
 updating, or changing a role-pack extension uses Pi's normal reload flow.
 Contributor `session_shutdown` cleanup removes the
 old event listener before replacement extensions register. Already-running

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

@@ -0,0 +1,74 @@
+# ADR-0011: Authorize explicit worktree cleanup by cwd containment
+
+- **Status:** Accepted
+- **Date:** 2026-09-17
+- **Scope:** Managed subagent worktree cleanup (issue #45)
+
+## Decision
+
+A parent may explicitly remove one managed worktree when its canonical source
+repository is within the session's canonical cwd subtree. This supersedes the
+session-manifest-only ownership policy discussed in issue #45, per its
+2026-09-17 scope update: ended sessions leave orphans whose manifests are no
+longer reachable. A reachable owned manifest enriches inventory and is marked
+removed after successful cleanup, but is not the authorization boundary.
+
+Discovery joins the managed filesystem root, Git registration and working-tree
+state, live Herdr workspace state, and current-session manifests. Unknown or
+conflicting eligibility evidence blocks removal, subject to the approved
+individual process-visibility exception below. Detected same-user process
+holders, known live children, and persistent leases block removal; process
+names are not a runtime allowlist. Only Herdr-confirmed idle retained shell
+PIDs are exempt, never active runtimes at those PIDs. Dirty work requires an
+explicit WIP preservation commit on the retained branch; detached HEAD,
+conflicts, locks, and initialized submodules cannot be bypassed.
+
+The approved process-visibility policy treats unreadable individual process
+details as non-blocking warnings, without an override flag. Inspection continues
+so one hidden process cannot mask an observable holder. Inventory and removal
+results report incomplete coverage separately from blockers, retaining warnings
+through rechecks, preservation, and failures when available. Reports use counts
+and bounded PID samples, not commands or environments. Linux uses `/proc`;
+macOS uses same-user `lsof` cwd records and warns for individual unreadable
+records. Unsupported platforms and failed global enumeration remain blockers;
+partial output from a failed `lsof` is not successful enumeration.
+
+Paths are canonicalized, so symlinked ancestors are supported while checkout
+symlinks escaping the managed root are blocked. Ignored files are counted and
+disclosed, but do not block removal and are not captured by preservation. A
+failed preservation commit restores the original index. A created preservation
+SHA remains in the report even when subsequent removal fails.
+
+Removed manifests are no-op evidence only and never classify a recreated
+checkout. Post-removal manifest-write failures are warnings, not removal
+failures. Cleanup Git and Herdr calls have bounded 30-second timeouts. Child
+sessions retain their existing `/worktree list` and `/worktree <name>` surfaces;
+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.
+
+## Rejected alternatives
+
+- Session-only ownership cannot recover cross-session orphans.
+- Global authorization would allow one project to remove another's review state.
+- Automatic reaping at completion, shutdown, or on a timer erases the parent's
+  opportunity to review retained work.
+- Force removal and branch deletion are outside this feature's authority.
+- Repo-global stashes make preserved work less visible than retained commits.
+- Recursive filesystem deletion to bypass submodule protection is not supported.
+
+## Consequences
+
+Broad cwd values authorize broad repository subtrees, so callers must choose cwd
+deliberately. Worktrees are not sandboxes. Fresh eligibility checks reduce but
+cannot eliminate races with external writers; underlying refusals are surfaced,
+not overridden. Same-user process inspection is permission-limited, and
+other-user processes are not inspected. A protected process could hold the
+checkout undetected; unreadability is not proof that it is unrelated. This
+accepted blind spot replaces the earlier strict individual-unreadability
+blocker, not the global enumeration or identity guards. Restart inventory does
+not reattach watchers or rewrite other sessions' manifests.
+
+See the [operating guide](../worktree-subagents.md#cleanup) for the shipped API.

package/docs/worktree-subagents.md

@@ -50,7 +50,7 @@ For a worktree launch:
 - 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.
 
-For an explicit interactive handoff, use `/worktree <worktree> [task]`. It creates the worktree from the current committed branch, forks the active conversation branch into the target-cwd session, launches a normal long-lived Pi process in the returned root pane, and focuses the destination workspace only after Herdr confirms Pi is running with the expected session and worktree cwd. Use `/worktree list` to inspect worktrees for the current repository. The original process and session remain intact; pane movement is not used to change a running shell's cwd.
+For an explicit interactive handoff, use `/worktree <worktree> [task]`. It creates the worktree from the current committed branch, forks the active conversation branch into the target-cwd session, launches a normal long-lived Pi process in the returned root pane, and focuses the destination workspace only after Herdr confirms Pi is running with the expected session and worktree cwd. Use `/worktree list` to inspect managed worktrees whose source repositories are inside the current cwd subtree, including cross-session orphans. The original process and session remain intact; pane movement is not used to change a running shell's cwd.
 
 `worktree` cannot be set in agent frontmatter and is not exposed by the `/subagent <agent> <task>` shorthand. It is selected per call to the `subagent` tool. Ordered model fallback lists are not supported for worktree subagents: a failed attempt retains its worktree and branch for review, so a retry cannot safely reuse the requested branch. A persistent specialist either holds one worktree lease for its full lifetime or runs read-only in an ordinary pane; it cannot be re-bound.
 
@@ -112,6 +112,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 |
+| `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.
 
@@ -131,7 +132,7 @@ The parent receives the normal child summary plus:
 
 `clean` means there are no staged, unstaged, or untracked files. It does **not** mean the branch has no commits or diff relative to its base.
 
-If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it. Every retained handoff also includes the exact `herdr worktree remove --workspace <workspace-id>` command, but run it only after useful state is preserved.
+If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it. Every retained handoff points to `/worktree remove` and `worktree_remove`, with the raw Herdr command as an operator override after independent safety checks.
 
 ## Parallel pull-request review without new worktrees
 
@@ -207,21 +208,30 @@ This manual continuation is not watched by the original parent lifecycle. Do not
 
 Worktree and branch cleanup is always explicit. Ordinary temporary reviewer panes close after result delivery; Herdr removes their tab only if its last pane closes. The retained worktree root shell is excluded from automatic cleanup, and user-added panes are preserved. Persistent specialists retain their pane between tasks and follow the existing explicit stop semantics.
 
-First make sure commits, patches, or uncommitted files are no longer needed. Then remove the Herdr worktree workspace:
+Parent sessions have an inspect-only inventory and an explicit removal surface:
 
-```bash
-herdr worktree remove --workspace <workspace-id>
+```text
+/worktree list
+/worktree remove <path|branch|workspace-id> [--preserve]
 ```
 
-Herdr removes the workspace and linked checkout. Without `--force`, dirty worktrees are protected. Do not use `--force` unless discarding all remaining work is intentional and verified.
+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.
 
-The branch is a separate Git ref; inspect and delete it separately only when repository policy allows:
+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.
 
-```bash
-git branch -d <branch>
-```
+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.
+
+Unreadable individual process details are **warnings, not blockers**, with no override flag. Scanning continues after each unreadable entry, so another observable holder still blocks removal. Unknown processes are not classified as unrelated. Inventory rows expose separate `blockers` and `warnings` arrays; removal results expose `warnings` and retain warnings from earlier inspections, including refusals and preservation/removal failures when available. Human-readable output includes the same warnings, with counts and at most ten sampled PIDs per inspection, not process commands or environments. Pi tool refusals and failures use thrown errors, so their warnings travel in the error message rather than structured tool details.
+
+This is not proof of machine-wide inactivity: same-user inspection is permission-limited, other-user processes are not inspected, and a protected process could hold the checkout undetected. Linux enumerates `/proc` and checks readable cwd paths; disappeared processes and confirmed zombies do not hold a checkout. macOS uses same-user `lsof` cwd records; unreadable or missing details in individual returned records warn, but a failed global `lsof` blocks even when it returns partial output. Neither platform can establish coverage of processes hidden by the OS. Unsupported platforms, failed or empty global enumeration, and unknown Git, containment, or ownership state remain blockers.
+
+Dirty work requires an explicit `--preserve` or `preserve: true`. This stages all uncommitted and untracked files and creates a WIP commit on the retained branch. A failed commit restores the pre-preservation index and leaves the checkout and its uncommitted files in place; removal does not proceed. Success reports the preservation SHA even if the subsequent recheck or removal fails. Conflicts, detached HEAD, and other blockers cannot be bypassed with preservation.
+
+Ignored files do not block cleanup. Inventory shows their exact file count, and a successful removal reports how many were deleted. Counting streams the NUL-delimited Git listing rather than buffering all paths; errors and the 30-second timeout still block removal, never report a guessed zero. Preservation does not capture ignored files; attempted and successful preservation reports disclose that exclusion when ignored files are present.
+
+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.
 
-Use `git branch -D` only when you have independently verified that discarding unmerged commits is safe.
+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. Parent session start emits only one compact inventory count when contained worktrees remain. Unsupported platforms or failed global process enumeration block removal; individual visibility gaps are disclosed warnings, never proof that an orphan is idle.
 
 ## Current limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.7.0",
+  "version": "2.0.1",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",
@@ -33,7 +33,7 @@
     "format": "biome format --write pi-extension test skills/orchestrate/adversarial-review-example.js",
     "format:check": "biome format pi-extension test skills/orchestrate/adversarial-review-example.js",
     "lint": "oxlint pi-extension test skills/orchestrate/adversarial-review-example.js",
-    "test": "node --experimental-strip-types --test test/test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/package-skill.test.js test/evals/*.test.mjs",
+    "test": "node --experimental-strip-types --test test/test.ts test/worktree-cleanup.test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/package-skill.test.js test/evals/*.test.mjs",
     "test:integration": "node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
     "test:integration:live": "PI_TEST_LIVE=1 node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
     "version": "auto-changelog --package && git add CHANGELOG.md"

package/pi-extension/subagents/config-path.ts

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+export function getAgentConfigDir(): string {
+	return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+export function getSubagentsConfigPath(): string {
+	return join(getAgentConfigDir(), "herdr-agents", "config.json");
+}
+
+export function getSubagentsConfigExamplePath(): string {
+	return join(PACKAGE_ROOT, "config.json.example");
+}
+
+export function getSubagentsPackageRoot(): string {
+	return PACKAGE_ROOT;
+}