pi-herdr-agents 3.0.2 → 3.1.0

package/AGENTS.md

@@ -96,6 +96,8 @@ npm pack --dry-run
 git diff --check
 ```
 
+`npm run lint` needs Node.js 22.18+ (or 22.6–22.17 with `NODE_OPTIONS=--experimental-strip-types`) because oxlint imports `oxlint.config.ts` and its `tools/oxlint/anti-slop/index.ts` plugin as TypeScript.
+
 Run LSP diagnostics on every changed TypeScript file; lint and tests do not catch every TypeScript error.
 
 For Herdr or lifecycle changes, run the deterministic suite from inside Herdr. Run only one integration suite at a time on a Herdr instance; concurrent suites compete for terminal focus and process capacity and can cause false timeouts or leaked test resources.

package/CHANGELOG.md

@@ -7,12 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v3.0.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.1...v3.0.2)
+## [v3.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.3...v3.1.0)
+
+### Commits
+
+- feat: route task-model init through pack approval [`1b6bacd`](https://github.com/giuseppecrj/pi-herdr-agents/commit/1b6bacd0b5eecb6f83ffba1d5a5ee57a8b0fa944)
+- test: dispatch all Pi lifecycle handlers in placement fixtures [`f96e59d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f96e59de8890d39ce6c79be8de245d287fc2485e)
+
+## [v3.0.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.2...v3.0.3) - 2026-10-08
+
+### Merged
+
+- Release 3.0.3 [`#82`](https://github.com/giuseppecrj/pi-herdr-agents/pull/82)
+- test(integration): re-read worktree row before asserting its open workspace [`#81`](https://github.com/giuseppecrj/pi-herdr-agents/pull/81)
+- Fix Pi readiness check when Pi rewrites argv [`#80`](https://github.com/giuseppecrj/pi-herdr-agents/pull/80)
+- Fix tsc errors and git-version-sensitive index test; document lint Node floor [`#79`](https://github.com/giuseppecrj/pi-herdr-agents/pull/79)
+- fix(worktrees): report the primary workspace creation opened [`#78`](https://github.com/giuseppecrj/pi-herdr-agents/pull/78)
+- fix: keep parked supervision wakes alive until they settle [`#77`](https://github.com/giuseppecrj/pi-herdr-agents/pull/77)
+
+### Commits
+
+- remove openspec [`5e31900`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5e31900ea96fdaab6fcf26fc9a335497dcbc528d)
+- fix(worktrees): bound the primary workspace report and hedge its note [`44a18a8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/44a18a8145549801bd17007f05beb8a8cddf41b9)
+- Confirm Pi startup by launch environment, not rewritten argv [`bbfe7e7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bbfe7e7093bd76d8803562ddb6263c27cfe4a982)
+- fix: settle stranded supervision waits and test wake retain accounting [`d18df1c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d18df1cb83bedf86951d2f9702a4a6185b44a8e8)
+- test: bound the identity-capture loop anchor and close supervision test gaps [`4a0e71a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4a0e71a97ebc9ba3f21a5377504f24c3d837d9a2)
+- Treat an unreadable Pi environment as unproven, not fatal [`b69151a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b69151ae85bd13c45bdf3e980c0b36e315c7c863)
+- chore: release v3.0.3 [`1c75adb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/1c75adb0864af9b922d1471734b086943435f238)
+- test(worktree-cleanup): make the index-restore test hermetic and deterministic [`16840f6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/16840f64b9481983cf44fc928061fd4e6822434d)
+- test(worktree-cleanup): clear inherited git repository variables in the fixture [`323e1fb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/323e1fbf6e6240eb5e7000d63fc84e23b391259a)
+- test(worktrees): expect launch snapshots in scoped inventory [`f733040`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f73304088c8a781b1ed7333a5a09175ec7c896e9)
+- fix(types): resolve strict tsc errors in activity scope guard and recorder [`26bc9ef`](https://github.com/giuseppecrj/pi-herdr-agents/commit/26bc9ef2e8a2afc23901641efdd19661fcd3f756)
+- docs: limit the lint type-stripping fallback to Node 22.6-22.17 [`ccab597`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ccab597cfaf2bcf6e37889ae3103dd6e9c78c6ef)
+- docs: note that npm run lint needs Node.js 22.18 or newer [`b8ffa8d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b8ffa8d1d83419588db8d4aed506d5d236360673)
+- test(integration): check cancel manifest workspace id; clarify Herdr Node note [`aac18d9`](https://github.com/giuseppecrj/pi-herdr-agents/commit/aac18d926385582ccc36783fd8a9475db7df7e3d)
+- test(worktree-cleanup): snapshot the index after git status [`aa869b2`](https://github.com/giuseppecrj/pi-herdr-agents/commit/aa869b2a62c8868d377b134d3f05b029692f2eb0)
+- docs: integration tests need the Herdr server on Node.js 22.19+ [`bdd791b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bdd791bd934ea3174db32e1fcf1353353506224b)
+
+## [v3.0.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.1...v3.0.2) - 2026-10-06
 
 ### Merged
 
 - fix(subagents): resolve submodule sources and refresh fallback context [`#76`](https://github.com/giuseppecrj/pi-herdr-agents/pull/76)
 
+### Commits
+
+- chore: release v3.0.2 [`245e54e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/245e54e7ccc937f69bee6093906d26b03b8a92c9)
+
 ## [v3.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.0...v3.0.1) - 2026-10-06
 
 ### Merged

package/CONTEXT.md

@@ -71,6 +71,13 @@ verified by the parent against the Herdr pane. A worktree cancel signals and
 judges exit only by it.
 _Avoid_: argv match, foreground process, shell visibility
 
+**Pi startup confirmation**:
+The bounded check that a `/worktree` handoff's Pi is running before its
+workspace is focused: a Pi process in the root pane with the worktree cwd whose
+launch-time environment names the launched session in
+`PI_HERDR_AGENTS_SESSION`. Nothing inside Pi reads that marker.
+_Avoid_: argv match, `--session` visibility, child-context hint
+
 **No-progress advisory**:
 An internal warning that an active child shows no durable progress in its session
 JSONL or activity snapshot. It is advisory only and never changes the child's
@@ -182,9 +189,13 @@ 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
+A parent-requested removal of one named managed checkout and its open worktree
+workspace, with absence verification and retained branch history. Never automatic
+reaping. It never closes the source repository's primary workspace. When this
+process recorded that worktree creation appeared to open that workspace and a
+read taken just before the report still shows it untouched, removal suggests
+the `herdr workspace close` command, to use only if the workspace is unused.
+_Avoid_: Branch deletion, completion cleanup, automatic close of a workspace the user may have used
 
 **Dirty-state preservation**:
 Explicit opt-in staging and WIP commitment of a worktree's uncommitted and
@@ -199,7 +210,9 @@ 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
+choices, with source-based research when available. A single loaded extension
+that offers on the task-model init approval event owns approval and the write
+instead of the host writer. 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
@@ -216,6 +229,14 @@ the independence boundary; project policy may separately require a
 different provider.
 _Avoid_: Generic tier, reviewer-family enforcement, per-step routing
 
+**Ranking basis**:
+What a task-model proposal's ranking rests on, as the proposing model submitted
+it: `registry-only`, or `research` with the http(s) sources consulted in that
+run, how each influenced the ranking, and the remaining uncertainty. It travels
+with one write for review and is never saved; `tasksMeta.method` keeps its kind.
+Code checks its shape, not that a source was read.
+_Avoid_: Verified research, evidence store
+
 **Loop template**:
 A future reusable orchestration definition beside `models`, describing stages,
 task categories, and a termination/report contract. Loop templates are not

package/README.md

@@ -192,7 +192,7 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | `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, optionally conditional on `expectedConfigRevision` |
+| `subagents_write_task_models` | Parent-only internal tool that validates and atomically writes `models.tasks` preferences, optionally conditional on `expectedConfigRevision` and carrying an unsaved ranking `basis` |
 
 | Skill | Description |
 | ----- | ----------- |
@@ -207,7 +207,7 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | -------------------------- | ------------------------------------ |
 | `/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 |
+| `/subagents-init [preferences]` | Draft task-category model preferences from the live authenticated registry, with optional ranking preferences; a loaded approval extension can own the write |
 
 ### Taxonomy and discovery
 
@@ -461,7 +461,10 @@ 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.
+network for availability. The brief also includes `configRevision`, the
+revision of the exact config bytes that supplied the saved preferences. Init
+does not start while a turn runs or messages are queued, and an empty registry
+ends with a notice instead of a prompt. Neither case writes anything.
 
 The draft considers current saved task, default, and per-agent preferences.
 Optional command arguments set ranking preferences. Otherwise it favors
@@ -482,8 +485,23 @@ 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.
+quality evidence. No live model probes run.
+
+The proposal carries a ranking `basis`. It is `{"kind":"registry-only"}` when
+search is unavailable or yields no usable evidence. It is `{"kind":"research"}`
+only with the http(s) `sources` consulted in this run, the `influence` each had
+on the ranking, and the remaining `uncertainty`. Code checks the basis's shape,
+not whether a source was read, so the basis is labeled as submitted and
+unverified.
+
+While init runs, it emits `pi-herdr-subagents:task-models:init:approval:v1`.
+With no offer, the prompt directs the model to `subagents_write_task_models`
+with `expectedConfigRevision`. When exactly one loaded extension offers, init
+opens that extension's flow, and the extension's instructions replace the
+writer instruction; the extension then owns approval and the write. Two or more
+offers, or an invalid one, stop init before any extension opens or a prompt is
+sent. Once an offer is recorded, a refusal or failure also stops init: it never
+falls back to the direct writer. See [Task-model init events](#task-model-init-events).
 
 The writer validates and atomically replaces `models.tasks` and `tasksMeta`,
 preserving unrelated settings. Its tool schema accepts partial nonempty
@@ -491,9 +509,15 @@ 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`, `missingCategories`, and `configRevision`. 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.
+and a before/after table based on that saved result, not the unsaved draft, and
+must explain missing categories or changed choices.
+
+Optional `basis` must have the same kind as `tasksMeta.method`. A research basis
+needs at least one source with an http(s) URL that has a host and a nonblank
+`influence`, plus a nonblank `uncertainty`. The writer validates it before
+writing, returns it in the result, and never saves it; only `tasksMeta.method`
+persists. Calls without `basis`, including research calls, keep the earlier
+contract.
 
 Optional `expectedConfigRevision` makes a write conditional on the config the
 proposal was read from. A revision is `sha256:` followed by 64 lowercase hex
@@ -549,13 +573,94 @@ rewrites the file. Other values remain configuration errors, as do unknown keys
 under `roles`. Registered role packs are the entire package layer, and global and
 project definitions keep their precedence over them.
 
+### Task-model init events
+
+Two versioned `pi.events` channels let another extension take part in
+`/subagents-init` without importing this package. Both carry the invoking
+command's live `ExtensionCommandContext`, so they are for trusted extensions in
+the same process. The context is current only while the event is emitted.
+
+The host emits `pi-herdr-subagents:task-models:init:approval:v1` while init
+runs:
+
+```typescript
+type ApprovalRequest = {
+  apiVersion: 1;
+  brief: TaskModelBrief; // frozen: operatorPreferences, categories, configRevision, current, models (never empty)
+  context: ExtensionCommandContext;
+  offer(offer: { owner: string; open(): OpenResult }): "recorded" | "closed";
+};
+type OpenResult =
+  | {
+      kind: "ready";
+      destination: { toolName: string; instructions: string };
+      cancel(): void; // closes the flow this open created
+    }
+  | { kind: "blocked"; reason: string };
+```
+
+- Call `offer` synchronously, before the listener's first `await`. After `emit`
+  returns, `offer` answers `"closed"` and records nothing.
+- Offer whenever your extension owns task-model approval, even when it is busy,
+  and refuse from `open`. `owner` is one printable token without spaces.
+- The host opens nothing until collection ends. Two offers (even with the same
+  owner) or an invalid offer stop init. With one offer, the host calls `open()`
+  once, and it must return synchronously.
+- `ready` must leave `toolName` active. Its `instructions` replace the host's
+  writer instruction in the prompt the host sends.
+- `ready` must include `cancel`. When the host does not hand the prompt to Pi
+  (the tool is inactive, or `pi.sendUserMessage` throws), it calls `cancel()`
+  once before reporting `not-started`. `cancel` must close only the flow that
+  this `open` created, never a later one. A `cancel` that throws is reported
+  with the outcome.
+- A throw, a promise, an invalid result (including a missing `cancel`), or
+  `blocked` stops init with a notice and no prompt. The host cannot undo what
+  `open` changed before failing.
+- Pi accepts the prompt asynchronously. It can still reject it after `start`
+  reports `started`, for example when the selected model has no configured
+  auth; the host refuses up front only when no model is selected. Pi delivers
+  the prompt to `input` handlers (source `"extension"`) before that check and
+  emits `before_agent_start` and `agent_start` only after it passes. An
+  extension whose flow outlives one prompt should close it when other input or
+  a run arrives before those events, so a later request cannot inherit it.
+- Pi's event bus logs and swallows listener exceptions. A listener that throws
+  before offering looks the same as no listener, so init uses the direct
+  writer. An extension that guards the writer still refuses that write.
+
+Another extension's command emits `pi-herdr-subagents:task-models:init:start:v1`
+to start the same init:
+
+```typescript
+type StartRequest = {
+  apiVersion: 1;
+  context: ExtensionCommandContext;
+  preferences: string; // ranking preferences, passed through as typed
+  offer(offer: { owner: string; start(): InitOutcome }): "recorded" | "closed";
+};
+type InitOutcome =
+  | { kind: "started"; destination: string }
+  | { kind: "not-started"; reason: string };
+```
+
+The host offers synchronously as `pi-herdr-agents` and starts nothing until the
+emitter calls `start()`. Call it only when exactly one host offered. `start`
+runs init with the request's context and returns synchronously; the emitter
+shows a `not-started` reason. The host does not listen in subagent sessions
+and unsubscribes at `session_shutdown`. Unsubscribe an approval listener there
+too, as the role-pack bridge does.
+
 ### Supervision transport
 
 On supported local filesystems, supervision uses file wake-ups plus one shared
 4.8-second pane reconciliation. A wake-up only prompts fresh evidence
-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.
+collection; it never establishes a result by itself. While any child's wait for
+that check is parked, the coordinator's file watches stay referenced, so the
+sidecar is still observed when the parent has no other event-loop work. The
+reference is released when the wait settles, is aborted, or its child is
+unregistered. With no parked wait, the watches stay unreferenced and do not
+keep the process running. 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 durable user `config.json` to
 disable wake-ups and use that legacy cadence deliberately. The setting is read
@@ -866,15 +971,19 @@ is no other parent/child protocol.
 
 `/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.
 
+The destination workspace is focused only after Pi startup is confirmed. Every fresh launch, including the handoff, sets `PI_HERDR_AGENTS_SESSION` to its session file; confirmation requires a Pi process in the root pane with the worktree cwd whose launch-time environment carries that value. Pi rewrites its process title, so command-line text is never evidence. Nothing inside Pi reads the variable, and it is not a child-context hint. Confirmation reads Linux `/proc`; see [Worktree subagents](docs/worktree-subagents.md).
+
 ---
 
 ### 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. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses 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 that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. A source repository that is a Git submodule is located through the `core.worktree` setting of its shared Git directory under the superproject's `.git/modules`, not through that directory's parent. 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.
+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. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses 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 that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. A source repository that is a Git submodule is located through the `core.worktree` setting of its shared Git directory under the superproject's `.git/modules`, not through that directory's parent. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open worktree workspaces use Herdr removal. The source repository's primary workspace is never closed automatically. If this process recorded that worktree creation appeared to open it and a read taken just before the report still shows it untouched, removal adds `wX appears to have been opened by worktree creation; if you haven't used it, close it with herdr workspace close wX`; a missing or wrong-typed field, another open workspace for the repository, another session, or a restarted process reports nothing. 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.
+
+A worktree launch may add three synchronous Herdr snapshots (`worktree list` before create, `worktree list` after create, and `pane list` for the opened primary), each bounded at 3 seconds, 9 seconds if all three run to their timeouts. A failed snapshot claims nothing and is returned as a launch diagnostic, shown in the `subagent` acknowledgement and the `/worktree` notice; it is not written to the console. Claims are kept only in this process and are not written to the manifest. Ordinary non-worktree launches add no Herdr calls. Explicit removal adds a primary-workspace report only when this process holds a claim for the removed source repository: `worktree list`, `workspace get`, and `pane list`, each asynchronous and bounded at 3 seconds, taken after the checkout is removed. That is at most three calls and 9 seconds of wall time, without blocking the event loop. These report calls sit on top of the existing cleanup Git and Herdr calls, which stay at 30 seconds each.
 
-Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. 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.
+Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. It never closes the source repository's primary workspace. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. 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
 
@@ -1258,12 +1367,16 @@ npm run lint
 npm pack --dry-run
 ```
 
+`npm run lint` needs Node.js 22.18+ (or 22.6–22.17 with `NODE_OPTIONS=--experimental-strip-types`) because oxlint imports TypeScript directly: its configuration, `oxlint.config.ts`, and the JavaScript plugin it loads, `tools/oxlint/anti-slop/index.ts`. Without type stripping, oxlint fails before linting with `Unknown file extension ".ts"`. This is a contributor tooling requirement, not a runtime requirement for package users.
+
 Run the required end-to-end suite from inside Herdr:
 
 ```bash
 npm run test:integration
 ```
 
+Start the Herdr server with Node.js 22.19+ on its `PATH`, because test panes inherit the server's environment, not the test runner's: Pi 1.0.0 needs Node.js 22.19+ and crashes at startup on versions older than 22.15.
+
 The deterministic suite launches real Pi sessions, Herdr panes, and worktrees without provider credentials. The optional live-provider smoke test is not a merge gate:
 
 ```bash

package/RELEASING.md

@@ -10,6 +10,8 @@ The published version must be unique on npm.
 
 `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.
 
+`3.1.0` is a compatible minor release. It adds the request-scoped task-model init events that let a loaded pack approve `/subagents-init` proposals; with no pack offering, the direct writer is unchanged. It was prepared from feature commit `1b6bacd0b5eecb6f83ffba1d5a5ee57a8b0fa944`. It is not published until the release workflow succeeds.
+
 Do not design a release that creates a GitHub Release without a successful npm publish for a new version. The workflow publishes first, then tags and creates the GitHub Release.
 
 ## Prerequisites

package/docs/README.md

@@ -60,10 +60,11 @@ real implementations; in-memory fakes are conformance fixtures only.
 | [`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. |
+| [`0011`](adr/0011-explicit-worktree-cleanup.md) | Accepted; amended by 0015 | 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. |
+| [`0015`](adr/0015-report-opened-primary-workspace.md) | Accepted | Report, and never automatically close, a primary workspace that worktree creation opened. |
 
 ## Historical material
 

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

@@ -1,6 +1,6 @@
 # ADR-0011: Authorize explicit worktree cleanup by cwd containment
 
-- **Status:** Accepted
+- **Status:** Accepted; amended by [ADR-0015](0015-report-opened-primary-workspace.md)
 - **Date:** 2026-09-17
 - **Scope:** Managed subagent worktree cleanup (issue #45)
 

package/docs/adr/0015-report-opened-primary-workspace.md

@@ -0,0 +1,121 @@
+# ADR-0015: Report the primary workspace worktree creation opened
+
+- **Status:** Accepted
+- **Date:** 2026-10-07
+- **Amends:** [ADR-0011](0011-explicit-worktree-cleanup.md)
+
+## Context
+
+`herdr worktree create` groups a new worktree with the source repository's
+primary workspace and opens that workspace when none is open. `herdr worktree
+remove` removes only the linked checkout, so the first worktree of an idle
+repository leaves an empty shell workspace behind.
+
+Herdr's `WorktreeCreated` result does not include `created_parent`, so this
+extension cannot ask Herdr which workspace the create call opened. The only
+signal is a `herdr worktree list --cwd` snapshot before create and another
+after it. A workspace the user or another session opens during a long checkout
+can be attributed to this create. That race is inherent in the snapshots.
+
+## Decision
+
+Explicit worktree removal never closes the source repository's primary
+workspace.
+
+On a worktree launch, this process may record one claim: workspace id, the
+source `repo_key`, the only pane's `terminal_id`, and the checkout path the
+workspace was opened at. A workspace that was already open is not claimed. A
+snapshot that fails, times out, or lacks a required field claims nothing. The
+failure is returned as a launch diagnostic, shown in the `subagent`
+acknowledgement and the `/worktree` notice, and never written to the console.
+Ordinary non-worktree launches do not take these snapshots.
+
+The claim lives only in the creating process and is not written to the
+manifest. Removal from another session, or after this process restarts,
+reports nothing. Extension reload inside the same process keeps the in-memory
+claim.
+
+On explicit removal, core checks whether this process holds a claim whose
+checkout is the removed source repository. If not, removal makes no report
+calls at all. Otherwise the Herdr surface reads the source once more, after
+the checkout is removed and immediately before any sentence. It may tell the
+parent:
+
+`wX appears to have been opened by worktree creation; if you haven't used it, close it with herdr workspace close wX`
+
+only when that read shows the workspace untouched: the default label equal to
+the repository name (both present), not focused, one tab, not a linked
+worktree, the claimed `repo_key`, one pane, the recorded terminal, and `cwd`
+and `foreground_cwd` at the recorded checkout. No other workspace may be open
+for the repository; a listed row with an open workspace and no boolean
+`is_linked_worktree` blocks the sentence too. Any missing or wrong-typed field
+a check uses means the workspace is not untouched, so removal says nothing
+about it. Shell idleness and child processes are not checked: the sentence is
+advisory and hedged, and the extra reads would double the removal cost
+without making a close safe.
+
+The surface method is `SurfaceProvider.reportOpenedPrimaryWorkspace`. Herdr
+implements it. Other surfaces return no report. Core does not import Herdr.
+
+A failed report is a warning. The checkout removal still succeeds. Nothing in
+this path polls, retries, or sleeps.
+
+### Blocking time
+
+A worktree launch adds at most three synchronous Herdr calls, each bounded at
+3 seconds:
+
+1. `herdr worktree list --cwd` before create
+2. `herdr worktree list --cwd` after create, only when the before snapshot
+   succeeded and showed no primary workspace
+3. `herdr pane list --workspace` for that workspace's terminal, only when the
+   after snapshot shows a new primary workspace with a repo key and checkout
+   path
+
+If each runs to its timeout, the extra blocking time is 9 seconds. A failed
+before-snapshot skips the later two. `herdr worktree create` itself is an
+existing call and is not given a new timeout here.
+
+Explicit removal adds at most three asynchronous calls, each bounded at
+3 seconds, and only when this process holds a claim for the removed source
+repository:
+
+1. `herdr worktree list --cwd`
+2. `herdr workspace get`
+3. `herdr pane list --workspace`
+
+If each runs to its timeout, removal takes up to 9 more seconds of wall time.
+The calls do not block the event loop. A failed or decisive call stops the
+rest. These calls are in addition to the existing cleanup Git and Herdr calls,
+which stay at 30 seconds each.
+
+## Rejected alternatives
+
+- **Automatic close from the untouched-workspace heuristic.** One tab, one
+  pane, the same terminal id, cwd at the checkout, and the default label, even
+  with an idle shell and no children, cannot tell whether the user worked in
+  the workspace. `git
+  log`, a test run, and `cd` back to the checkout leave that same picture, and
+  closing it would destroy the scrollback.
+- **Pane fingerprinting.** Reading `herdr pane read --source recent` at claim
+  time and requiring the same text before a close would catch some commands
+  the heuristic misses. It is not clearly better than reporting. Prompt
+  redraws, hooks, and Herdr's own startup change the text without a user
+  command; a cleared screen looks untouched; a read can fail; and the gap
+  between the confirming read and a close is still a race. A mistaken close
+  is destructive. A mistaken report is a command the user can ignore.
+- **Trusting the manifest after restart.** The creating process is the only
+  observer of the before/after snapshots. A later process would be acting on
+  a claim it did not make.
+
+## Consequences
+
+Cwd containment, branch retention, and the rejection of automatic reaping in
+ADR-0011 are unchanged. A misattributed claim can name a workspace this create
+did not open, so the sentence says the workspace "appears" to have been opened
+and asks the user to close it only if they have not used it. The message does
+not close it. There is no second re-check: the single set of reads is taken
+immediately before the sentence, and a workspace that changes after those
+reads can still be named. The sentence is still only a suggestion.
+
+See the [operating guide](../worktree-subagents.md#cleanup).

package/docs/worktree-subagents.md

@@ -48,11 +48,12 @@ For a worktree launch:
 - `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`.
+- Herdr groups the new worktree with the source repository's primary workspace and opens one when none is open. The extension reads `herdr worktree list --cwd` before and after creation, and `herdr pane list` for the opened workspace's terminal, only to record a claim in this process. Each of those reads has a 3-second timeout. A worktree launch runs at most three of them; if each runs to its timeout, that is 9 seconds on top of create. A workspace you already had open is not claimed. An unreadable, timed-out, or incomplete snapshot claims nothing and is reported as a launch diagnostic in the `subagent` acknowledgement or `/worktree` notice, never on the console. A failed before-snapshot skips the later reads. Ordinary pane launches do not make these calls. The claim is not written to the manifest and is not kept after this process exits.
 - 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.
 
-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.
+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 Pi startup is confirmed: a Pi process in the root pane's Herdr foreground list must have the worktree cwd and, in its launch-time environment (`/proc/<pid>/environ`), `PI_HERDR_AGENTS_SESSION` naming the forked session file. An unreadable environment (for example, a process that is exiting) never confirms startup. Command-line text is never evidence, because Pi rewrites its process title and Herdr then reports only `pi`. The confirmation reads Linux `/proc`; on other hosts it fails within its bounded wait and the launch-failure retention below applies. 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.
 
@@ -235,7 +236,7 @@ Dirty work requires an explicit `--preserve` or `preserve: true`. This stages al
 
 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.
+Open worktree workspaces are removed through Herdr. That removal never closes the source repository's primary workspace. If this process recorded that worktree creation opened it, removal reads the workspace after the checkout is removed and may report `wX appears to have been opened by worktree creation; if you haven't used it, close it with herdr workspace close wX` only when those reads, taken immediately before that sentence, show the workspace untouched: the default label equal to the repository name, not focused, one tab, not a linked worktree, the claimed `repo_key`, one pane, the recorded terminal, and both `cwd` and `foreground_cwd` at the recorded checkout, with no other workspace open for the repository. A listed row with an open workspace but no boolean `is_linked_worktree` blocks the sentence. A missing or wrong-typed `label`, `repo_name`, `focused`, `tab_count`, `foreground_cwd`, `terminal_id`, or any other field a check uses means the workspace is not untouched, so removal says nothing about it. Shell idleness and child processes are not checked; the sentence is a hedged suggestion, not a close. The before/after list can attribute a workspace that you or another session opened during a long checkout, because Herdr does not say which workspace create opened; the message does not close anything, so a wrong id is only a suggestion. Claims live only in the creating process: removal from another session, or after a restart, reports nothing. The report's longest path is three asynchronous calls — `worktree list`, `workspace get`, and `pane list`, 3 seconds each — 9 seconds of wall time if every call runs to its timeout, without blocking the event loop. A failed call stops the rest. With no claim for the removed source repository, removal adds none of these calls. 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. 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.
 
@@ -246,7 +247,8 @@ This first version intentionally does not provide:
 - automatic push, PR creation, merge, or cherry-pick
 - automatic worktree or branch removal
 - worktree-aware `subagent_resume`
-- durable restart reconciliation
+- durable restart reconciliation (an opened-primary-workspace claim does not survive process restart)
+- automatic close of the source repository's primary workspace
 - dependency DAG scheduling or merge queues
 - stacked-branch management
 - multi-repository workspaces

package/maestro/adapters/pi/activity-file.ts

@@ -316,8 +316,18 @@ export function createSubagentActivityRecorder(params: {
 	const runningChildId = params.runningChildId?.trim();
 	const activityFile = params.activityFile?.trim();
 	if (!runningChildId || !activityFile) return createNoopRecorder();
+	return createFileActivityRecorder(
+		runningChildId,
+		activityFile,
+		params.now ?? (() => Date.now()),
+	);
+}
 
-	const now = params.now ?? (() => Date.now());
+function createFileActivityRecorder(
+	runningChildId: string,
+	activityFile: string,
+	now: () => number,
+): SubagentActivityRecorder {
 	const createdAt = now();
 	const activity: SubagentActivityState = {
 		version: 1,