pi-herdr-agents 3.0.2 → 3.0.3

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,44 @@ 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.0.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.2...v3.0.3)
+
+### Merged
+
+- 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)
+- 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

package/README.md

@@ -553,9 +553,14 @@ project definitions keep their precedence over them.
 
 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 +871,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 +1267,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/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,

package/maestro/adapters/pi/launch.ts

@@ -24,9 +24,11 @@ import type {
 import {
 	getSubagentProcessIdentityFile,
 	linuxProcessProbe,
+	readLinuxProcessEnvironment,
 	readProcessIdentityRecord,
 	verifyProcessIdentityRecord,
 	type PiProcessIdentity,
+	type ProcessEnvironmentReader,
 	type ProcessIdentityProbe,
 } from "./process-identity.ts";
 import {
@@ -141,11 +143,12 @@ export interface ProcessIdentityExpectation {
 
 type MaybePromise<T> = T | Promise<T>;
 
-interface WorktreeSurfaceForLaunch {
+export interface WorktreeSurfaceForLaunch {
 	path: string;
 	branch: string;
 	workspaceId: string;
 	paneId: string;
+	diagnostics?: string[];
 }
 
 export interface PiLaunchOperations {
@@ -190,30 +193,38 @@ function placementFromPaneConfig(config: PaneConfig) {
 function worktreeSurfaceForLaunch(
 	worktree: WorktreeSurface,
 ): WorktreeSurfaceForLaunch {
-	return {
+	const surface: WorktreeSurfaceForLaunch = {
 		path: worktree.path,
 		branch: worktree.branch,
 		workspaceId: worktree.workspaceId,
 		paneId: worktree.surfaceId,
 	};
+	if (worktree.diagnostics?.length) surface.diagnostics = worktree.diagnostics;
+	return surface;
 }
 
+/**
+ * Names the launched session in the Pi process's exec-time environment. Pi
+ * rewrites its command line, so `--session` is never readiness evidence.
+ * Nothing inside Pi reads it.
+ */
+export const PI_LAUNCH_SESSION_ENV = "PI_HERDR_AGENTS_SESSION";
+
 export function isExpectedPiProcess(
 	process: {
+		pid: number;
 		name?: string;
 		argv0?: string;
-		argv?: string[];
 		cwd?: string;
 	},
 	sessionFile: string,
 	cwd: string,
+	readEnvironment: ProcessEnvironmentReader = readLinuxProcessEnvironment,
 ): boolean {
-	const sessionIndex = process.argv?.indexOf("--session") ?? -1;
 	return (
 		(process.name === "pi" || process.argv0?.split("/").pop() === "pi") &&
-		sessionIndex >= 0 &&
-		process.argv?.[sessionIndex + 1] === sessionFile &&
-		process.cwd === cwd
+		process.cwd === cwd &&
+		readEnvironment(process.pid)?.get(PI_LAUNCH_SESSION_ENV) === sessionFile
 	);
 }
 
@@ -232,15 +243,17 @@ async function waitForSurfacePiReady(
 	while (Date.now() <= deadline) {
 		try {
 			const info = await Promise.resolve(provider.getProcessInfo(surface));
-			if (
-				info.foregroundProcesses.some((process) =>
-					isExpectedPiProcess(process, sessionFile, cwd),
-				)
-			) {
-				return;
+			// An unreadable process (one that is exiting) proves nothing, but must
+			// not hide a matching sibling.
+			for (const process of info.foregroundProcesses) {
+				try {
+					if (isExpectedPiProcess(process, sessionFile, cwd)) return;
+				} catch (error) {
+					lastError = errorMessage(error);
+				}
 			}
 		} catch (error) {
-			lastError = error instanceof Error ? error.message : String(error);
+			lastError = errorMessage(error);
 		}
 		if (Date.now() >= deadline) break;
 		await new Promise((resolve) => setTimeout(resolve, intervalMs));
@@ -636,6 +649,7 @@ async function prepareLaunchSurface(
 		baseSha,
 		manifestFile,
 	};
+	if (created.diagnostics?.length) worktree.diagnostics = created.diagnostics;
 	worktreeOps.writeWorktreeManifest(manifestFile, {
 		state: "provisioned",
 		...ownership,
@@ -857,7 +871,7 @@ function buildPiCommand(
 		}
 	}
 
-	const env: string[] = [];
+	const env = [`${PI_LAUNCH_SESSION_ENV}=${shellQuote(artifacts.sessionFile)}`];
 	if (artifacts.localAgentDir) {
 		env.push(`PI_CODING_AGENT_DIR=${shellQuote(artifacts.localAgentDir)}`);
 	} else if (process.env.PI_CODING_AGENT_DIR) {

package/maestro/adapters/pi/process-identity.ts

@@ -123,6 +123,44 @@ export function createLinuxProcessProbe(
 
 export const linuxProcessProbe = createLinuxProcessProbe();
 
+/**
+ * A process's environment as it was at exec. Unlike its command line, Pi's
+ * process-title rewrite leaves this intact. `undefined` only when no such PID
+ * exists; throws on non-Linux hosts and any other read failure.
+ */
+export type ProcessEnvironmentReader = (
+	pid: number,
+) => Map<string, string> | undefined;
+
+export function createLinuxProcessEnvironmentReader(
+	read: (path: string) => string = (path) => readFileSync(path, "utf8"),
+): ProcessEnvironmentReader {
+	return (pid) => {
+		if (process.platform !== "linux")
+			throw new Error(
+				`process environment is unreadable on ${process.platform}; only Linux /proc is read`,
+			);
+		let text: string;
+		try {
+			text = read(`/proc/${pid}/environ`);
+		} catch (error) {
+			const code = error instanceof Error ? errnoCode(error) : undefined;
+			if (code === "ENOENT" || code === "ESRCH") return undefined;
+			throw error;
+		}
+		const environment = new Map<string, string>();
+		for (const entry of text.split("\0")) {
+			const separator = entry.indexOf("=");
+			if (separator > 0 && !environment.has(entry.slice(0, separator)))
+				environment.set(entry.slice(0, separator), entry.slice(separator + 1));
+		}
+		return environment;
+	};
+}
+
+export const readLinuxProcessEnvironment =
+	createLinuxProcessEnvironmentReader();
+
 /** The calling process's identity; throws when this host cannot establish it. */
 export function readOwnProcessIdentity(
 	probe: ProcessIdentityProbe = linuxProcessProbe,

package/maestro/core/activity.ts

@@ -5,7 +5,7 @@ import type {
 	SubagentActivityState,
 } from "./types.ts";
 
-const KNOWN_SCOPES = new Set<SubagentActivityScope>([
+const KNOWN_SCOPES: ReadonlySet<string> = new Set<SubagentActivityScope>([
 	"agent",
 	"turn",
 	"provider",

package/maestro/core/opened-primary-workspace.ts

@@ -0,0 +1,108 @@
+import { isNonEmptyString } from "./config/type-guards.ts";
+
+/**
+ * A primary workspace this process saw Herdr open while creating a worktree.
+ * The record lives only in this process. Another session is another process,
+ * and a restart starts empty, so neither reports a claim. Nothing is persisted.
+ */
+export interface PrimaryWorkspaceClaim {
+	workspaceId: string;
+	repoKey: string;
+	terminalId: string;
+	checkoutPath: string;
+}
+
+export interface ReleasedPrimaryWorkspaceClaim {
+	workspaceId: string;
+	repoKey: string;
+	terminalId: string;
+}
+
+/**
+ * A report never closes a workspace. `note` is absent when nothing is safe to
+ * suggest, and never states the attribution as fact.
+ */
+export interface OpenedPrimaryWorkspaceReport {
+	note?: string;
+	repoKey: string;
+	releasedClaims: ReleasedPrimaryWorkspaceClaim[];
+}
+
+const openedPrimaryWorkspacesKey = Symbol.for(
+	"pi-herdr-agents:opened-primary-workspaces",
+);
+
+interface OpenedPrimaryWorkspaceStore {
+	claims: PrimaryWorkspaceClaim[];
+}
+
+function store(): OpenedPrimaryWorkspaceStore {
+	// SAFETY: this extension alone writes this process-local symbol.
+	const globalStore = globalThis as typeof globalThis & {
+		[openedPrimaryWorkspacesKey]?: OpenedPrimaryWorkspaceStore;
+	};
+	return (globalStore[openedPrimaryWorkspacesKey] ??= { claims: [] });
+}
+
+export function isCompletePrimaryWorkspaceClaim(
+	value: PrimaryWorkspaceClaim,
+): boolean {
+	return (
+		isNonEmptyString(value.workspaceId) &&
+		isNonEmptyString(value.repoKey) &&
+		isNonEmptyString(value.terminalId) &&
+		isNonEmptyString(value.checkoutPath)
+	);
+}
+
+function sameClaim(
+	left: PrimaryWorkspaceClaim,
+	right: PrimaryWorkspaceClaim,
+): boolean {
+	return (
+		left.workspaceId === right.workspaceId &&
+		left.repoKey === right.repoKey &&
+		left.terminalId === right.terminalId &&
+		left.checkoutPath === right.checkoutPath
+	);
+}
+
+export function rememberOpenedPrimaryWorkspace(
+	claim: PrimaryWorkspaceClaim,
+): void {
+	if (!isCompletePrimaryWorkspaceClaim(claim)) return;
+	const claims = store().claims;
+	if (claims.some((existing) => sameClaim(existing, claim))) return;
+	claims.push({
+		workspaceId: claim.workspaceId,
+		repoKey: claim.repoKey,
+		terminalId: claim.terminalId,
+		checkoutPath: claim.checkoutPath,
+	});
+}
+
+export function openedPrimaryWorkspaceClaims(): PrimaryWorkspaceClaim[] {
+	return store()
+		.claims.filter(isCompletePrimaryWorkspaceClaim)
+		.map((claim) => ({ ...claim }));
+}
+
+export function forgetOpenedPrimaryWorkspaceClaims(
+	released: readonly ReleasedPrimaryWorkspaceClaim[],
+): void {
+	if (!released.length) return;
+	const claims = store().claims;
+	store().claims = claims.filter(
+		(claim) =>
+			!released.some(
+				(entry) =>
+					entry.workspaceId === claim.workspaceId &&
+					entry.repoKey === claim.repoKey &&
+					entry.terminalId === claim.terminalId,
+			),
+	);
+}
+
+export function clearOpenedPrimaryWorkspaceClaims(): void {
+	store().claims = [];
+}