pi-herdr-agents 3.1.0 → 3.2.1

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,12 +7,29 @@ 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.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.3...v3.1.0)
+## [v3.2.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.2.0...v3.2.1)
+
+### Commits
+
+- add sidebar plan [`675b4af`](https://github.com/giuseppecrj/pi-herdr-agents/commit/675b4af4eadd26c764974ba0257aef861da8a3de)
+- docs: guide agents through sidebar plugin setup [`a65d9ae`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a65d9aec41b694d5c5d72585784e83ddb1922035)
+
+## [v3.2.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.1.0...v3.2.0) - 2026-10-09
+
+### 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)
+- chore: release v3.2.0 [`a663716`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a663716d679a3cddc7bc9b7727918409c590b921)
+
+## [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
 

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

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
 
@@ -649,6 +651,52 @@ 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
@@ -1347,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

@@ -37,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:
 
@@ -45,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 },
 			},

package/maestro/core/config/sidebar-config.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isBoolean, isRecord } from "./type-guards.ts";
+
+export interface SidebarConfig {
+	/** Mark delegated children's panes for the Herdr sidebar plugin. */
+	enabled: boolean;
+}
+
+function invalid(source: string, message: string): never {
+	throw new Error(`Invalid subagent sidebar config in ${source}: ${message}`);
+}
+
+export function parseSidebarConfig(
+	rawConfig: any,
+	source = "config.json",
+): SidebarConfig {
+	if (!isRecord(rawConfig)) invalid(source, "root must be an object");
+	if (!Object.hasOwn(rawConfig, "sidebar")) return { enabled: false };
+	const sidebar = rawConfig.sidebar;
+	if (!isRecord(sidebar)) invalid(source, "sidebar must be an object");
+	const unsupported = Object.keys(sidebar).filter((key) => key !== "enabled");
+	if (unsupported.length > 0)
+		invalid(
+			source,
+			`sidebar has unsupported key(s): ${unsupported.join(", ")}`,
+		);
+	const enabled = Object.hasOwn(sidebar, "enabled") ? sidebar.enabled : false;
+	if (!isBoolean(enabled)) invalid(source, "sidebar.enabled must be a boolean");
+	return { enabled };
+}
+
+export function loadSidebarConfig(
+	configDir: string,
+	examplePath: string,
+): SidebarConfig {
+	let sourcePath = join(configDir, "config.json");
+	let rawConfig: string;
+	try {
+		rawConfig = readFileSync(sourcePath, "utf8");
+	} catch (error) {
+		// SAFETY: readFileSync only throws Node fs errors here, which carry code.
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		sourcePath = examplePath;
+		try {
+			rawConfig = readFileSync(examplePath, "utf8");
+		} catch (exampleError) {
+			// SAFETY: readFileSync only throws Node fs errors here, which carry code.
+			if ((exampleError as NodeJS.ErrnoException).code === "ENOENT")
+				return { enabled: false };
+			throw exampleError;
+		}
+	}
+	try {
+		return parseSidebarConfig(JSON.parse(rawConfig), sourcePath);
+	} catch (error) {
+		if (error instanceof SyntaxError)
+			throw new Error(
+				`Invalid JSON in subagent config ${sourcePath}: ${error.message}`,
+			);
+		throw error;
+	}
+}

package/maestro/runtime/delegated-marker.ts

@@ -0,0 +1,206 @@
+import {
+	judgeProcessIdentity,
+	linuxProcessProbe,
+	type PiProcessIdentity,
+	type ProcessIdentityProbe,
+	type ProcessIdentityState,
+} from "../adapters/pi/process-identity.ts";
+import {
+	reportPaneToken,
+	type PaneTokenOutcome,
+	type PaneTokenWrite,
+} from "../surfaces/herdr/herdr-socket.ts";
+
+/** The pane token the Pi Herdr Agents Sidebar plugin reads. */
+export const DELEGATED_MARKER_TOKEN = "piha_delegated_v1";
+/** Recently classified as a delegated child; never proof of a live occupant. */
+export const DELEGATED_MARKER_VALUE = "live";
+/** One stable source: a pane accepts sequenced reports from at most 32. */
+export const DELEGATED_MARKER_SOURCE = "pi-herdr-agents";
+/** Bounds a leftover marker after the last write Herdr applied, not liveness. */
+export const DELEGATED_MARKER_TTL_MS = 15_000;
+/**
+ * Renewal rides on supervision observations: the 4.8s reconciliation, or
+ * 1s fallback polling. Both leave several renewals inside one TTL.
+ */
+export const DELEGATED_MARKER_RENEW_MS = 4_000;
+/** Consecutive failed writes before a marker stops trying; its TTL ends it. */
+export const DELEGATED_MARKER_MAX_FAILURES = 3;
+
+export type MarkerWriter = (write: {
+	paneId: string;
+	seq: number;
+	live: boolean;
+}) => Promise<PaneTokenOutcome>;
+
+export function herdrMarkerWriter(socketPath: string): MarkerWriter {
+	return ({ paneId, seq, live }) => {
+		const write: PaneTokenWrite = {
+			paneId,
+			source: DELEGATED_MARKER_SOURCE,
+			seq,
+			token: DELEGATED_MARKER_TOKEN,
+			value: null,
+		};
+		if (live) {
+			write.value = DELEGATED_MARKER_VALUE;
+			write.ttlMs = DELEGATED_MARKER_TTL_MS;
+		}
+		return reportPaneToken(socketPath, write);
+	};
+}
+
+type MarkerState =
+	| { kind: "pending" }
+	| { kind: "live"; identity: PiProcessIdentity; lastSentAt: number }
+	| { kind: "retired" };
+
+/**
+ * This parent process's marker writes. Every pane shares one sequence that
+ * starts at wall-clock microseconds, so a restarted parent still outranks
+ * its predecessor's writes unless the clock moved backwards.
+ */
+export class DelegatedMarkers {
+	readonly write: MarkerWriter;
+	readonly now: () => number;
+	private readonly probe: ProcessIdentityProbe;
+	private lastSeq = 0;
+
+	constructor(options: {
+		write: MarkerWriter;
+		probe?: ProcessIdentityProbe;
+		now?: () => number;
+	}) {
+		this.write = options.write;
+		this.probe = options.probe ?? linuxProcessProbe;
+		this.now = options.now ?? Date.now;
+	}
+
+	/**
+	 * A marker for one launched child. It publishes only after the child's
+	 * own process identity is verified; without one it never writes.
+	 */
+	attach(child: {
+		surface: string;
+		processIdentityCapture?: Promise<PiProcessIdentity | undefined>;
+	}): DelegatedMarker {
+		return new DelegatedMarker(
+			this,
+			child.surface,
+			child.processIdentityCapture,
+		);
+	}
+
+	judge(identity: PiProcessIdentity): ProcessIdentityState {
+		return judgeProcessIdentity(identity, this.probe);
+	}
+
+	nextSeq(): number {
+		this.lastSeq = Math.max(this.lastSeq + 1, this.now() * 1000);
+		return this.lastSeq;
+	}
+}
+
+/**
+ * One child's marker. Writes are serialized: at most one renewal is queued or
+ * in flight, followed by at most one clear. Renewal continues only while the
+ * launch-verified process identity is alive, so a later process in the same
+ * pane never inherits it.
+ */
+export class DelegatedMarker {
+	readonly paneId: string;
+	private readonly owner: DelegatedMarkers;
+	private state: MarkerState = { kind: "pending" };
+	private sentLive = false;
+	private liveQueued = false;
+	private failures = 0;
+	private queue: Promise<void> = Promise.resolve();
+
+	constructor(
+		owner: DelegatedMarkers,
+		paneId: string,
+		capture: Promise<PiProcessIdentity | undefined> | undefined,
+	) {
+		this.owner = owner;
+		this.paneId = paneId;
+		if (!capture) {
+			this.state = { kind: "retired" };
+			return;
+		}
+		void capture.then(
+			(identity) => this.start(identity),
+			() => this.start(undefined),
+		);
+	}
+
+	get kind(): MarkerState["kind"] {
+		return this.state.kind;
+	}
+
+	/** Resolves when every write queued so far has settled. */
+	settled(): Promise<void> {
+		return this.queue;
+	}
+
+	/** Called on each supervision observation; renews at most every 4s. */
+	renew(): void {
+		const state = this.state;
+		const at = this.owner.now();
+		if (
+			state.kind !== "live" ||
+			this.liveQueued ||
+			at - state.lastSentAt < DELEGATED_MARKER_RENEW_MS
+		)
+			return;
+		if (this.owner.judge(state.identity).kind !== "alive") {
+			this.retire();
+			return;
+		}
+		state.lastSentAt = at;
+		this.queueWrite(true);
+	}
+
+	/** Idempotent. Clears the token if any live write may have reached Herdr. */
+	retire(): void {
+		if (this.state.kind === "retired") return;
+		this.state = { kind: "retired" };
+		if (this.sentLive) this.queueWrite(false);
+	}
+
+	private start(identity: PiProcessIdentity | undefined): void {
+		if (this.state.kind !== "pending") return;
+		if (!identity || this.owner.judge(identity).kind !== "alive") {
+			this.state = { kind: "retired" };
+			return;
+		}
+		this.state = { kind: "live", identity, lastSentAt: this.owner.now() };
+		this.queueWrite(true);
+	}
+
+	private queueWrite(live: boolean): void {
+		if (live) this.liveQueued = true;
+		this.queue = this.queue.then(() => this.send(live));
+	}
+
+	private async send(live: boolean): Promise<void> {
+		if (live) this.liveQueued = false;
+		// A renewal queued before retirement is dropped, never sent after it.
+		if (live && this.state.kind !== "live") return;
+		if (live) this.sentLive = true;
+		let outcome: PaneTokenOutcome;
+		try {
+			outcome = await this.owner.write({
+				paneId: this.paneId,
+				seq: this.owner.nextSeq(),
+				live,
+			});
+		} catch {
+			outcome = "failed";
+		}
+		// A late result never revives or reclassifies a retired marker.
+		if (!live || this.state.kind !== "live") return;
+		if (outcome === "answered") this.failures = 0;
+		else if (outcome === "pane-missing") this.state = { kind: "retired" };
+		else if (++this.failures >= DELEGATED_MARKER_MAX_FAILURES) this.retire();
+	}
+}