pi-herdr-agents 3.0.3 → 3.2.0

package/AGENTS.md

@@ -27,12 +27,13 @@ Former bundled roles, `/plan`, its plan skill, and `/skill:orchestrate` now belo
 - `pi-extension/subagents/index.ts` — Pi composition root: public tools/commands, role-pack event bridge, host policy, widgets, and parent delivery
 - `pi-extension/subagents/model-registry.ts`, `config-path.ts` — permanent host-local SDK capability glue and configuration-path conventions
 - `maestro/core/` — seam interfaces and types; activity/lifecycle/status projection, routing, wake-ups, and supervision
+- `plugins/sidebar/` — optional standalone Node companion Herdr plugin; it imports nothing from the extension
 - `maestro/core/roles/discovery.ts`, `maestro/core/config/` — role parsing/discovery, injected-directory config loaders, and task-model init prompt construction
 - `maestro/core/worktree.ts`, `worktree-cleanup.ts` — manifest schema/state, handoff types, and cleanup eligibility/formatting
 - `maestro/adapters/pi/` — `PiHarnessAdapter`, launch transactions, completion evidence, session I/O, activity files, SDK model glue, and task-model registry projection
 - `maestro/adapters/pi/child/subagent-done.ts` — child protocol: `caller_ping`, `subagent_done`, and activity recording
-- `maestro/surfaces/herdr/` — `HerdrSurfaceProvider`, Herdr CLI driver, and terminal scripts/placement
-- `maestro/runtime/` — `RunSession`, Pi composition, run ownership, controls/retries, observation, delivery-gated cleanup, worktree operations/handoff, and task-model init composition
+- `maestro/surfaces/herdr/` — `HerdrSurfaceProvider`, Herdr CLI driver, and terminal scripts/placement, plus `herdr-socket.ts` for socket pane metadata
+- `maestro/runtime/` — `RunSession`, Pi composition, run ownership, controls/retries, observation, delivery-gated cleanup, worktree operations/handoff, and task-model init composition, plus `delegated-marker.ts` for delegated-child sidebar markers
 - `maestro/adapters/fake/`, `maestro/surfaces/fake/`, `test/maestro/` — conformance fakes, seam tests, and the dependency-rule test
 - `CONTEXT.md` — orchestration-domain glossary
 - `docs/adr/` — hard-to-reverse architectural decisions; [ADR-0012](docs/adr/0012-adopt-maestro-seams-in-repo.md) records the maestro seams decision

package/CHANGELOG.md

@@ -7,10 +7,27 @@ 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.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.2...v3.0.3)
+## [v3.2.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.1.0...v3.2.0)
+
+### Commits
+
+- feat: add optional Herdr sidebar focus plugin [`9d2fb03`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9d2fb039b006e0d389d19b1105dd54e277f695ba)
+- fix: update dependencies to resolve security advisories [`028ebd6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/028ebd62fa8c8e967c15a9677c0d4a1abc52505a)
+- docs: match sidebar README to main package style [`918db68`](https://github.com/giuseppecrj/pi-herdr-agents/commit/918db68bd5f56782198182aa48eb6586a46a0ef7)
+
+## [v3.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.3...v3.1.0) - 2026-10-09
+
+### 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)
+- chore: release v3.1.0 [`0bb8bcd`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0bb8bcdc328d152c5cab5eaaf4d261f109055ee4)
+
+## [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)
@@ -25,6 +42,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - 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)

package/CONTEXT.md

@@ -65,12 +65,30 @@ taken first stays authoritative.
 _Avoid_: Interrupt, suppression, persistent stop, pane-close fallback
 
 **Process identity**:
-A managed worktree child's Pi process named by immutable kernel facts (PID,
-start time, boot, and PID namespace), recorded by the child at launch and
-verified by the parent against the Herdr pane. A worktree cancel signals and
-judges exit only by it.
+A child's Pi process named by immutable kernel facts (PID, start time, boot,
+and PID namespace), recorded by the child at launch and verified by the parent
+against the Herdr pane. Every managed worktree child records it; other children
+record it when sidebar markers are on. A worktree cancel signals and judges
+exit only by it, and a delegated marker renews only while it is alive.
 _Avoid_: argv match, foreground process, shell visibility
 
+**Delegated marker**:
+The display-only pane token `piha_delegated_v1=live` that a parent reports on
+a delegated child's pane when `sidebar.enabled` is on. It means the parent
+classified the pane's process as its child within the last 15 seconds, not
+that the process is alive when Herdr draws the row. One stable source, a
+15-second TTL, and increasing sequence numbers bound a leftover marker;
+renewal requires the original process identity. A `/worktree` handoff is
+never marked.
+_Avoid_: liveness proof, ownership record, security boundary, per-run source
+
+**Sidebar Focus**:
+The Herdr agent view that the optional `pi-herdr-agents.sidebar` plugin sets
+on request. It hides rows whose delegated marker is `live` while their status
+is idle, working, or done, and keeps blocked, unknown, and unmarked rows. All
+clears only this plugin's view and reports a view that another tool owns.
+_Avoid_: hiding processes, notification filter, automatic view, popup
+
 **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
@@ -210,7 +228,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
@@ -227,6 +247,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

@@ -17,6 +17,7 @@ Delegate investigation, implementation, and review without blocking the parent s
 - **Conversation handoff** — continue the active Pi conversation in a new worktree with `/worktree` while preserving the parent session.
 - **Pack-neutral roles** — use project or global definitions and installable role packs; this package ships no default roles or workflows.
 - **Persistent specialists** — retain one policy-bound Pi session for sequential, turn-based tasks.
+- **Optional sidebar focus** — the companion [Pi Herdr Agents Sidebar](plugins/sidebar/README.md) Herdr plugin hides marked delegated children from Herdr's Agents view while you run Focus. Markers are display-only and follow the pane, so see its [limits](plugins/sidebar/README.md#reusing-a-delegated-pane).
 
 ## Requirements
 
@@ -57,7 +58,7 @@ Restart or `/reload` Pi after installation. Review package source before install
 - [Requirements](#requirements), [Install](#install), [Safety and uninstall](#safety-and-uninstall)
 - [Quick start](#quick-start), [Release notes](#release-notes), [How it works](#how-it-works)
 - [What's Included](#whats-included): tools, commands, the operating skill, role packs
-- [Async Subagent Flow](#async-subagent-flow): status, configuration, model routing
+- [Async Subagent Flow](#async-subagent-flow): status, configuration, model routing, [sidebar markers](#sidebar-markers)
 - [Spawning Subagents](#spawning-subagents), [Persistent specialists](#persistent-specialists), [Interrupting](#interrupting-a-running-subagent), [Cancelling](#cancelling-a-running-subagent)
 - [The `/worktree` Workflow](#the-worktree-workflow), [Custom Agents](#custom-agents), [Tool Access Control](#tool-access-control)
 - [Development](#development), [License](#license)
@@ -67,7 +68,8 @@ Restart or `/reload` Pi after installation. Review package source before install
 - Child agents are real Pi processes running with your user account's permissions, inside Herdr panes. Worktrees isolate Git checkouts, not processes or permissions.
 - The extension creates Herdr panes, tabs and managed worktrees only when a launch asks for them. It never pushes, merges, opens pull requests, deletes branches or removes worktrees on its own; cleanup is an explicit parent action ([worktree cleanup](#explicit-worktree-cleanup)).
 - What it writes: `$PI_CODING_AGENT_DIR/herdr-agents/config.json` (only through `/subagents-init` or the writer tool, never on startup); per-launch artifacts under the parent session's `artifacts/<session-id>/` directory beside Pi's session store, which hold the child's full task text and any `systemPrompt` as Markdown files, activity snapshots and worktree manifests; and the child's own Pi session file. A managed worktree that carries its own `.pi/agent` directory receives that child's session inside the checkout. Treat task text as potentially sensitive when you share or inspect those files.
-- To uninstall: first list and remove any retained worktrees while the extension is still loaded (`/worktree list`, then `/worktree remove <target>`), because those commands leave with the package. Then run `pi remove npm:pi-herdr-agents`, and delete `$PI_CODING_AGENT_DIR/herdr-agents/` and the `artifacts/` directories above if you no longer want the configuration and launch records.
+- Managed worktree children record their PID, process start time, boot ID, and PID namespace in `<session>.process.json` beside their session. With [`sidebar.enabled`](#sidebar-markers), every other child records the same facts, and a resumed child records them under `artifacts/<session-id>/process-identity/`. The parent then reports one display-only pane token, `piha_delegated_v1`, on each child's pane through the Herdr socket. With the setting off, the extension writes no pane metadata.
+- To uninstall: first list and remove any retained worktrees while the extension is still loaded (`/worktree list`, then `/worktree remove <target>`), because those commands leave with the package. If you installed the optional sidebar plugin, remove it with `herdr plugin uninstall pi-herdr-agents.sidebar` (or `herdr plugin unlink` for a linked copy). Then run `pi remove npm:pi-herdr-agents`, and delete `$PI_CODING_AGENT_DIR/herdr-agents/` and the `artifacts/` directories above if you no longer want the configuration and launch records.
 
 ## Quick start
 
@@ -192,7 +194,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 +209,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 +463,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 +487,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 +511,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,6 +575,128 @@ 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.
+
+### Sidebar markers
+
+Set `sidebar.enabled` to `true` to mark delegated children for the optional
+[Pi Herdr Agents Sidebar](plugins/sidebar/README.md) Herdr plugin, whose Focus
+action hides marked children from Herdr's Agents view. The setting defaults to
+`false`.
+
+```json
+{
+  "sidebar": {
+    "enabled": true
+  }
+}
+```
+
+Add the key to your existing `config.json`. The extension rejects a
+`config.json` without its `status` section, so copy `config.json.example`
+first if the file does not exist. Run `/reload` after changing the setting.
+Children launched before the change stay unmarked.
+
+Setting `sidebar.enabled` to `false` and running `/reload` retires every
+existing marker and clears the markers of running children. A clear can fail to
+reach Herdr, so a token still expires at most 15 seconds after the last write
+Herdr accepted. Setting it back to `true` marks only later launches; a child
+that was already running when you turned it off is never marked again.
+
+With markers on, every fresh, resumed, and persistent child records its own
+process identity, as managed worktree children always do. After the parent
+verifies that identity, it reports the pane token `piha_delegated_v1` with the
+value `live`, a 15-second time-to-live, and an increasing sequence number
+through `HERDR_SOCKET_PATH`. It renews the token on supervision checks while
+that exact process is alive. It clears the token when the run finalizes or is
+suppressed, or when the process exits or can no longer be verified. A
+`/worktree` handoff session is never marked.
+
+Marker writes never fail a launch or keep Pi running. Each write has a 2-second
+timeout on an unreferenced socket, failed writes are not retried, and three
+failures in a row stop that child's marker. Process identity reads Linux
+`/proc`, so on other systems, and outside Herdr, nothing is marked. After a
+parent crash, a marker can remain for up to 15 seconds after the last write
+Herdr applied. A marker belongs to the pane, so a different process started by
+hand in a delegated pane stays hidden by Focus while the original process is
+alive and supervised, even if it is suspended. Run All first or use a fresh
+pane. See [what a marker proves](plugins/sidebar/README.md#what-a-marker-proves)
+and [reusing a delegated pane](plugins/sidebar/README.md#reusing-a-delegated-pane).
+
 ### Supervision transport
 
 On supported local filesystems, supervision uses file wake-ups plus one shared
@@ -1247,11 +1395,15 @@ provider; fakes are for conformance tests only.
 - `maestro/adapters/pi/` — Pi launch, completion, session I/O, activity files,
   model SDK glue, and registry projection behind `PiHarnessAdapter`;
   `child/subagent-done.ts` implements the child protocol.
-- `maestro/surfaces/herdr/` — `HerdrSurfaceProvider`, Herdr CLI driver, and
-  terminal scripts/placement.
+- `maestro/surfaces/herdr/` — `HerdrSurfaceProvider`, Herdr CLI driver,
+  terminal scripts/placement, and `herdr-socket.ts`, the bounded socket
+  client for pane metadata.
 - `maestro/runtime/` — run ownership, controls/retries, observation,
-  delivery-gated cleanup, Pi composition, worktree operations/handoff, and
-  task-model init composition.
+  delivery-gated cleanup, Pi composition, worktree operations/handoff,
+  task-model init composition, and sidebar markers (`delegated-marker.ts`).
+- `plugins/sidebar/` — the optional Herdr plugin. Its `sidebar.mjs` uses Node
+  built-ins only and imports nothing from the extension, so Herdr can install
+  the directory by itself.
 - `maestro/adapters/fake/`, `maestro/surfaces/fake/`, `test/maestro/` —
   conformance fakes, seam tests, and the import dependency-rule test.
 

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
@@ -35,7 +37,7 @@ Manual deterministic Herdr integration (required before you push a release commi
 npm run test:integration
 ```
 
-Run that suite from inside Herdr. It uses real Pi and Herdr processes with the local deterministic provider, so it needs no provider credentials or network access.
+Run that suite from inside Herdr. It uses real Pi and Herdr processes with the local deterministic provider, so it needs no provider credentials or network access. `test/integration/sidebar.test.ts` also starts two disposable Herdr servers with their own HOME, configuration, sockets, and plugin registry under the system temporary directory, and removes them afterwards. It needs Linux and skips elsewhere.
 
 The optional live-provider smoke test is not a release gate:
 
@@ -43,7 +45,7 @@ The optional live-provider smoke test is not a release gate:
 PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 npm run test:integration:live
 ```
 
-Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `config.json.example`, and `examples/role-pack/`, contains no `agents/` resources, no `skills/` resources other than the host-owned `skills/pi-herdr-agents/SKILL.md`, and no `pi-extension/subagents/plan-skill.md`, and excludes `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, local `config.json` and `openspec/`, and that the worktree integration tests leave no test workspace behind. Durable user configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`; package-root configuration is ignored, so users must move an older file manually or re-run `/subagents-init`.
+Do not release from skipped Herdr tests. Confirm the package preview includes `README.md`, `CHANGELOG.md`, `AGENTS.md`, `docs/`, `config.json.example`, `examples/role-pack/`, and exactly `README.md`, `herdr-plugin.toml`, and `sidebar.mjs` under `plugins/sidebar/`, excludes the active `docs/sidebar-plan.md`, contains no `agents/` resources, no `skills/` resources other than the host-owned `skills/pi-herdr-agents/SKILL.md`, and no `pi-extension/subagents/plan-skill.md`, and excludes `pi-extension/subagents/workflow-worker.js`. Confirm it excludes plans, journals, sessions, prototypes, generated evidence, local `config.json` and `openspec/`, and that the worktree integration tests leave no test workspace behind. Durable user configuration is `$PI_CODING_AGENT_DIR/herdr-agents/config.json`; package-root configuration is ignored, so users must move an older file manually or re-run `/subagents-init`.
 
 ## npm authentication
 

package/docs/README.md

@@ -11,6 +11,9 @@ are evidence, not shipped contracts, when a later ADR supersedes them.
 - [`../CONTEXT.md`](../CONTEXT.md) — orchestration glossary.
 - [`worktree-subagents.md`](worktree-subagents.md) — worktree operation,
   review, recovery, and cleanup.
+- [`../plugins/sidebar/README.md`](../plugins/sidebar/README.md) — the
+  optional Herdr sidebar plugin: installation, Focus and All, the delegated
+  marker contract, and its staleness limits.
 
 The package is a pack-neutral execution host: it launches asynchronous Pi
 children in Herdr and supports managed worktrees for writing tasks, but ships no
@@ -66,6 +69,12 @@ real implementations; in-memory fakes are conformance fixtures only.
 | [`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. |
 
+## Active design
+
+- `sidebar-plan.md` — local plan and audit record for the sidebar plugin and
+  its marker bridge. It is excluded from the npm package, so it has no link
+  here. It is not a shipped contract; the plugin README is.
+
 ## Historical material
 
 - [`orchestrated-review-workflow-plan.md`](orchestrated-review-workflow-plan.md)

package/docs/worktree-subagents.md

@@ -194,6 +194,7 @@ The extension never pushes, creates a PR, merges, cherry-picks, or changes the p
 - **Ordinary launch failure:** if a fresh launch or `subagent_resume` fails after the extension creates its pane, the extension closes that pane and preserves the original launch error. It does not close a caller-supplied surface.
 - **Creation failure:** the manifest is marked failed. If Herdr created the branch but returned an incomplete response, the extension reconciles a unique branch match through `/worktree list` and records any recovered workspace/path.
 - **Launch failure after creation:** the manifest is marked failed and the workspace, forked session, and path are retained. The destination is not focused unless Pi startup is confirmed.
+- **Sidebar marker:** with `sidebar.enabled`, the worktree child's root pane carries the delegated marker only while the child's own Pi process runs. The parent clears it when the run finalizes, so the retained shell, and any agent you later start in it, is not marked. After a parent crash the marker expires within 15 seconds of the last write Herdr applied. See the [sidebar plugin README](../plugins/sidebar/README.md#what-a-marker-proves).
 - **Worker failure:** summary and available Git state are returned; the workspace remains open. Auto-exit waits until Pi is fully settled, so a transient provider error followed by automatic compaction or retry does not end the worker early.
 - **Operator cancel:** `subagent_cancel` never closes the retained root pane or workspace. At launch, the child's protocol extension records its own process identity (PID, `/proc` start time, boot ID, and PID-namespace link) in `<session>.process.json`, and the parent accepts it only while that process is alive in the parent's PID namespace as the Herdr pane shell or a descendant of it. Cancel sends SIGTERM only to that identity, re-verified (PID and start time) immediately before the signal, then confirms that the identity no longer exists, or that the pane is gone while it is not known alive. Command-line text and Herdr's foreground list are never evidence: Pi rewrites its process title, and Herdr lists foreground processes only. A live identity (such as a suspended Pi with SIGTERM pending), or one whose SIGTERM fails while it is still alive, leaves termination `unconfirmed` even if the pane is gone. An identity that was not captured (including on non-Linux hosts), is unreadable, belongs to another boot or PID namespace, or whose PID now has another start time is never signalled and also leaves it `unconfirmed` unless pane absence confirms termination. The PID could still be reused between the final check and the signal, because Node has no pidfd signal. Every Herdr query is bounded by the cancel deadline, and an answer that arrives after the deadline, even before the timer runs, never changes the reported outcome. The run stays live, and retrying `subagent_cancel` re-checks; if the launch capture expired, the retry captures the identity again within its own deadline. On confirmation, the manifest is marked `cancelled` and the normal Git handoff is delivered once. A parent shutdown while termination is unconfirmed records the plain shutdown state, never `cancelled`. No Git cleanup, branch change, or removal happens.
 - **`caller_ping`:** the child exits with `needs_help`; continue worktree-bound follow-up in the retained workspace rather than through `subagent_resume`. Public `subagent_resume` rejects managed-worktree child sessions before creating a pane so it cannot silently lose worktree ownership or policy.

package/maestro/adapters/pi/launch.ts

@@ -54,6 +54,8 @@ export interface FreshPiLaunchRequest {
 	fork?: boolean;
 	handoff?: { leafId: string };
 	surface?: string;
+	/** Ordinary children record their process identity too (sidebar markers). */
+	recordProcessIdentity?: boolean;
 	parent: {
 		cwd: string;
 		invocationCwd?: string;
@@ -86,6 +88,8 @@ export interface ResumePiLaunchRequest {
 	name: string;
 	sessionFile: string;
 	message?: string;
+	/** Record the resumed process's identity (sidebar markers). */
+	recordProcessIdentity?: boolean;
 	parent: {
 		sessionId: string;
 		sessionDir: string;
@@ -125,9 +129,15 @@ export interface PiRunningChild {
 	stopState?: "requested" | "pending" | "failed";
 	stopFailure?: string;
 	crashNotified?: boolean;
-	/** Managed worktree children: where the child records its own process identity. */
+	/**
+	 * Where the child records its own process identity: every managed worktree
+	 * child, and other children when the launch asks for it.
+	 */
 	processIdentityFile?: string;
-	/** Verified at launch readiness; a worktree cancel's only signal and exit evidence. */
+	/**
+	 * Verified at launch readiness. A worktree cancel's only signal and exit
+	 * evidence; sidebar markers renew only while it is alive.
+	 */
 	processIdentity?: PiProcessIdentity;
 	/** Settles when launch-readiness capture verifies or gives up; never rejects. */
 	processIdentityCapture?: Promise<PiProcessIdentity | undefined>;
@@ -718,7 +728,8 @@ function prepareChildSession(
 		activityFile,
 		// A handoff Pi loads no child protocol extension, so it records nothing.
 		processIdentityFile:
-			surface.worktree && !resolved.request.handoff
+			(surface.worktree || resolved.request.recordProcessIdentity) &&
+			!resolved.request.handoff
 				? getSubagentProcessIdentityFile(sessionFile)
 				: undefined,
 	};
@@ -1034,6 +1045,11 @@ async function launchResumedPiSubagent(
 		await operations.waitForShellReady(surface);
 		const activityFile = getSubagentActivityFile(artifactDir, id);
 		mkdirSync(dirname(activityFile), { recursive: true });
+		// The session file is reused, and its sidecar keeps the first identity
+		// ever published for it, so each resumed run records under its own ID.
+		const processIdentityFile = request.recordProcessIdentity
+			? join(artifactDir, "process-identity", `${id}.json`)
+			: undefined;
 
 		let messageFile: string | undefined;
 		if (request.message) {
@@ -1058,6 +1074,9 @@ async function launchResumedPiSubagent(
 			`PI_SUBAGENT_ID=${shellQuote(id)}`,
 			`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(activityFile)}`,
 			`PI_SUBAGENT_AUTO_EXIT=${autoExit ? "1" : "0"}`,
+			...(processIdentityFile
+				? [`PI_SUBAGENT_PROCESS_FILE=${shellQuote(processIdentityFile)}`]
+				: []),
 		];
 		const toolAllowlist = buildSubagentToolAllowlist(
 			policy.tools?.join(","),
@@ -1093,7 +1112,7 @@ async function launchResumedPiSubagent(
 				].join("\n"),
 			},
 		);
-		return {
+		const running: PiRunningChild = {
 			id,
 			name: request.name,
 			task: request.message ?? "resumed session",
@@ -1105,7 +1124,10 @@ async function launchResumedPiSubagent(
 			interactive,
 			runtimePlan: undefined,
 			lifecycle: createLifecycle(startTime),
+			processIdentityFile,
 		};
+		startProcessIdentityCapture(running, operations);
+		return running;
 	} catch (error) {
 		try {
 			await operations.closePane(surface);

package/maestro/adapters/pi/pi-harness-adapter.ts

@@ -97,6 +97,8 @@ export interface PiHarnessAdapterOptions {
 	worktreeOperations?: WorktreeOperations;
 	/** Kernel process facts for a retained worktree child's identity; tests inject it. */
 	processProbe?: ProcessIdentityProbe;
+	/** Ordinary and resumed children also record their identity (sidebar markers). */
+	recordProcessIdentity?: boolean;
 	/** Bound for confirming a retained worktree child's exit. Default: 5000ms. */
 	killTimeoutMs?: number;
 	/** Explicit local evidence/lifecycle bridge. The host still owns delivery and deduplication. */
@@ -209,6 +211,7 @@ export class PiHarnessAdapter implements HarnessAdapter {
 							: undefined
 					: undefined,
 				surface: opts.surface?.id,
+				recordProcessIdentity: this.options.recordProcessIdentity,
 				parent: this.options.parent,
 				runtimePlan:
 					resolved?.runtimePlan ??
@@ -294,6 +297,7 @@ export class PiHarnessAdapter implements HarnessAdapter {
 				name: opts.name,
 				sessionFile: opts.sessionId,
 				message: opts.message,
+				recordProcessIdentity: this.options.recordProcessIdentity,
 				parent: this.options.parent,
 				behavior: { autoExit: opts.autoExit },
 			},