@narumitw/pi-herdr 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # @narumitw/pi-herdr
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - b746e66: Add hc (herdr-core) status and terminal ancestry to the agent widget without duplicating Pi's native status reports. Keep legacy Herdr status, `/herdr`, and display of existing session-validated provenance. Do not ship legacy peer spawning or a `pane.run` fallback.
8
+
9
+ Add the `pi-herdr` skill and `herdr_peer` tool for independent parallel work in hc. The tool requires a valid, complete inherited hc binding. It starts peers with the current Pi runtime's checked absolute Node and Pi CLI paths and the same package resources. Each spawn requires explicit confirmation in an interactive Pi TUI that the local core on that connection was launched by a trusted host with a pre-spawn allowlist for the core's effective program environment. The prompt does not filter that environment or authenticate the endpoint. Headless spawn is rejected.
10
+
11
+ Use a fresh observation token and canonical terminal address to send peer messages. The tool checks sampled identity and idle status before one conditional send. It does not expose terminal text or raw process arguments, and it cannot prevent draft or takeover races.
12
+
13
+ ### Patch Changes
14
+
15
+ - Updated dependencies [df62c83]
16
+ - @narumitw/pi-tui-kit@0.70.1
17
+
18
+ ## 0.5.0
19
+
20
+ ### Minor Changes
21
+
22
+ - 97fdd84: Show sibling agents across all workspaces in the connected Herdr session, with each workspace's label and live status, name, and topology updates. Keep the widget updating during sustained events with bounded read discards and immediate catch-up.
23
+ - 2735f56: Remove the bundled `herdr` and `hc` bootstrap skills. Install operating skills separately if needed; this package no longer provides `/skill:herdr` or `/skill:hc`. Keep lifecycle reporting, pane metadata, the agent widget, and `/herdr` unchanged.
24
+
3
25
  ## 0.4.1
4
26
 
5
27
  ### Patch Changes
package/README.md CHANGED
@@ -1,20 +1,18 @@
1
- # 🐑 pi-herdr — Herdr Integration for Pi
1
+ # 🐑 pi-herdr — Herdr and hc Integration for Pi
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@narumitw/pi-herdr)](https://www.npmjs.com/package/@narumitw/pi-herdr) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
4
 
5
- Connect Pi's interactive lifecycle to Herdr and load operating guidance from the installed Herdr and Herdr Core CLIs.
5
+ Show Pi agent status in hc (herdr-core) or legacy Herdr. In hc, start independent Pi peers and exchange messages.
6
6
 
7
7
  ## ✨ Features
8
8
 
9
- - Reports Pi session identity and `working`, `blocked`, and `idle` lifecycle states to the current Herdr pane.
10
- - Publishes bounded `model`, `provider`, `thinking`, `session`, and `context_usage` tokens for Herdr sidebar rows.
11
- - Shows recognized sibling agents from the current Herdr workspace in a passive widget above Pi's editor, with a saved visibility toggle in `/herdr`.
12
- - Refreshes the widget on Herdr pane, workspace-name, and agent-status updates without polling the CLI.
9
+ - Shows hc's native Pi status and terminal ancestry, or legacy Herdr status and existing session-validated provenance.
10
+ - Reports Pi session identity and `working`, `blocked`, and `idle` lifecycle states to legacy Herdr, with bounded `model`, `provider`, `thinking`, `session`, and `context_usage` sidebar tokens.
11
+ - Shows recognized agents in a passive widget above Pi's editor, with a saved visibility toggle in `/herdr`.
12
+ - Bundles the `pi-herdr` skill for independent parallel work and peer messages through the hc-only `herdr_peer` tool.
13
+ - Refreshes the widget from authoritative event-driven reads without polling the CLI.
13
14
  - Coalesces rapid state changes and retries short-lived local socket failures without interrupting Pi.
14
- - Derives blocked state from Pi's public `ui_prompt_start` and `ui_prompt_end` lifecycle events.
15
- - Bundles thin `herdr` and `hc` bootstrap skills for explicit inspection and control requests.
16
- - Loads version-matched operating guidance from `herdr --skill` or `hc --skill`.
17
- - Keeps extension and skill installation in one Pi package.
15
+ - Derives legacy Herdr blocked state from Pi's public `ui_prompt_start` and `ui_prompt_end` lifecycle events.
18
16
 
19
17
  ## 📦 Install
20
18
 
@@ -39,47 +37,54 @@ pi --no-extensions -e ./packages/pi-herdr
39
37
 
40
38
  An unbuilt local checkout has no generated entrypoint and cannot be loaded by package directory.
41
39
 
42
- Pi extensions and skills run with your user permissions.
43
- Install only trusted packages, and review the source and bundled instructions before loading this package.
40
+ Pi extensions run with your user permissions.
41
+ Install only trusted packages, and review the source before loading this package.
44
42
 
45
43
  ## 🚀 Quick start
46
44
 
47
- Start Pi inside a Herdr-managed pane after installing the package.
48
- The extension activates automatically when `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID` are present.
49
- When the current Herdr workspace contains another recognized agent, Pi shows its state in a widget above the editor.
50
- Ask Pi to use Herdr, or invoke `/skill:herdr`, when you want it to inspect or control the current Herdr session.
51
- Before the first control command, the bootstrap loads `herdr --skill` once and reuses those instructions while they remain in the current context.
52
- For Herdr Core terminals, invoke `/skill:hc` instead; it loads `hc --skill` without requiring a Herdr-managed pane.
45
+ Start interactive Pi in a managed terminal after installation. When another recognized agent is present, Pi shows its state in a widget above the editor.
53
46
 
54
- If the standalone integration and skill are already installed, remove them after installing this package to avoid duplicate state reports and skill-name collisions:
47
+ - **hc:** A valid, complete inherited `HC_TERMINAL_ID` and `HC_TERMINAL_SOCKET` binding selects hc and enables `herdr_peer`. An invalid or partial binding does not fall back to legacy Herdr.
48
+ - **Legacy Herdr:** If neither hc binding variable is set, `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID` enable legacy status and the widget, not peer spawning.
49
+
50
+ In hc, run `/skill:pi-herdr` for authorized independent parallel work. Before spawning, verify that the selected local core was launched by a trusted host with a pre-spawn environment allowlist. If you cannot confirm that for this connection in the Pi TUI, do not spawn. See [Security and privacy](#-security-and-privacy).
51
+
52
+ If the standalone integration is already installed, remove it after installing this package to avoid duplicate state reports:
55
53
 
56
54
  ```bash
57
55
  rm ~/.pi/agent/extensions/herdr-agent-state.ts
58
- rm -rf ~/.agents/skills/herdr
59
56
  ```
60
57
 
61
58
  Run `/reload` or restart Pi after changing the installed resources.
62
59
 
63
- ## 🧠 Skills
60
+ ## 💬 Commands
64
61
 
65
- The bundled skills load CLI-owned guidance once and reuse it while it remains in the current context:
62
+ `/herdr` opens a menu to toggle the agent widget and view status or help, inspired by `/tool`.
63
+ It accepts no arguments and is available inside either backend in TUI and RPC modes; print and JSON modes reject it.
64
+ RPC can save the preference but does not display the widget.
65
+ Changes apply immediately and closing the menu does not undo saved changes.
66
66
 
67
- - [`herdr`](./skills/herdr/SKILL.md), invoked with `/skill:herdr`, loads `herdr --skill` for legacy Herdr panes and requires `HERDR_ENV=1`.
68
- - [`hc`](./skills/hc/SKILL.md), invoked with `/skill:hc`, loads `hc --skill` for Herdr Core persistent terminals and agents; it requires neither `HERDR_ENV=1` nor `HC_TERMINAL_ID`.
67
+ ## 🛠️ Tools
69
68
 
70
- Both skills apply only after an explicit request for their CLI, not merely because a task could use background work or delegation.
71
- The CLIs are separate; neither skill substitutes the other CLI when its command fails.
69
+ `herdr_peer` uses the inherited hc socket. It is registered only with a valid, complete hc binding.
72
70
 
73
- The `herdr` skill treats panes created for background work as temporary and attempts to close them after collecting the required output.
74
- Ask Pi explicitly to keep a pane open after the task when you want to inspect or use it later.
75
- Automatic cleanup runs only when the installed Herdr guidance provides a conditional close that atomically confirms the recorded pane ownership and acceptable agent or shell state; otherwise Pi leaves the pane open and reports the limitation.
71
+ | Action | Input and result |
72
+ | --- | --- |
73
+ | `spawn` | Supply a name and the complete task text, not a file path. Starts an independent Pi peer after operator confirmation in an interactive Pi TUI. Headless spawn is rejected. |
74
+ | `inspect` | Supply an explicit canonical terminal address. Returns sampled facts and an observation token, not terminal text or raw process arguments. |
75
+ | `send` | Supply the same address, a fresh observation token, and the peer message text. Checks freshly sampled identity and idle status before one idle-conditional send. |
76
76
 
77
- ## 💬 Commands
77
+ Use the token promptly after `inspect`. See [hc integration](./docs/hc-integration.md#peer-tool) for launch, delivery, and recovery limits.
78
78
 
79
- `/herdr` opens a menu to toggle the agent widget and view status or help, inspired by `/tool`.
80
- It accepts no arguments and is available inside Herdr in TUI and RPC modes; print and JSON modes reject it.
81
- RPC can save the preference but does not display the widget.
82
- Changes apply immediately and closing the menu does not undo saved changes.
79
+ ## 🧠 Skills
80
+
81
+ Run [`/skill:pi-herdr`](./skills/pi-herdr/SKILL.md) for authorized independent parallel work inside hc. Tasks must use different mutable resources and must not need another active task's intermediate results. Keep dependent work in sequence.
82
+ The skill uses `herdr_peer` only. There is no Bash, CLI, template, or standalone helper path. The package does not spawn peers in legacy Herdr and does not fall back to `pane.run`.
83
+
84
+ ## 🔌 hc status and terminal ancestry
85
+
86
+ Pi emits native OSC 7501 status, including `idle`, `working`, `blocked`, `done`, and `error`. The extension does not duplicate those reports or publish legacy metadata to hc. Turning off the widget does not stop Pi's reports.
87
+ hc relationships show **terminal ancestry**, not Pi session identity. They can survive program replacement and recovery. See [hc integration](./docs/hc-integration.md).
83
88
 
84
89
  ## ⚙️ Settings
85
90
 
@@ -97,9 +102,12 @@ Manual edits apply after `/reload` or the next session start.
97
102
  Missing files are not created until an explicit save. Invalid files trigger a warning, use defaults, and block saves until repaired.
98
103
  Saves preserve unknown fields and use atomic temporary-file-plus-rename publication, with reads and writes ordered within one Pi process, not across processes.
99
104
  Failed saves restore the previous effective value and leave the existing file untouched.
100
- Turning the widget off closes its subscription and pending requests without disabling lifecycle or metadata reporting.
105
+ Turning the widget off closes its subscription and pending requests without disabling legacy lifecycle/metadata reporting or Pi-owned hc status reporting.
106
+ Both backends retain the same settings file, `/herdr` command, widget key, and process-local runtime claim; there are no new extension-owned settings or environment variables.
107
+
108
+ ## 🔄 Legacy Herdr lifecycle reporting
101
109
 
102
- ## 🔄 Lifecycle reporting
110
+ This section applies only to legacy Herdr, not hc.
103
111
 
104
112
  The extension reports only interactive TUI sessions because Herdr displays agents attached to terminal panes.
105
113
  A session report contains the Herdr pane ID, the integration source, Pi's agent kind, a monotonic sequence, the session start reason, and an absolute Pi session path when available.
@@ -116,22 +124,28 @@ Replacement aborts pending metadata cleanup.
116
124
  Native quit cleanup remains Herdr-owned: the extension does not release native Pi identity or clear reporting authority and restore references.
117
125
  Herdr ignores official-source release requests, while authority clearing also removes session restore data; neither operation is used during shutdown.
118
126
 
119
- ## 🏷️ Pane metadata
127
+ ## 🏷️ Legacy Herdr pane metadata
120
128
 
121
- The extension publishes only the `model`, `provider`, `thinking`, `session`, and `context_usage` token keys through `pane.report_metadata` under the `herdr:pi` source.
129
+ This section applies only to legacy Herdr; hc does not receive these tokens or session-reference records.
130
+ Lifecycle integration publishes the `model`, `provider`, `thinking`, `session`, and `context_usage` token keys through `pane.report_metadata` under the `herdr:pi` source.
122
131
  `model` and `provider` come from Pi's selected model, `thinking` comes from Pi's effective Thinking level, and `session` comes only from Pi's explicit session display name.
123
132
  `context_usage` is Pi's current context percentage rounded to the nearest whole percent.
124
- Every report is a full five-key patch, and an unavailable value is sent as JSON `null` so old data is cleared instead of retained.
133
+ Each lifecycle metadata report is a full five-key patch, and an unavailable value is sent as JSON `null` so old data is cleared instead of retained.
125
134
  Values are stripped of terminal controls, trimmed, and limited to 80 Unicode characters before crossing the socket.
126
135
  The extension never publishes prompts, conversation text, tool arguments, credentials, raw session paths, or inferred session titles as metadata tokens.
127
136
  It also never sets Herdr's pane `title`, `display_agent`, `state_labels`, agent lifecycle state, or session restore fields through metadata.
128
137
 
129
138
  Metadata is evaluated after `session_start`, `session_info_changed`, `model_select`, `thinking_level_select`, `agent_settled`, and successful `session_compact` events.
130
- Unchanged event snapshots are suppressed, rapid changes are coalesced, and the latest unchanged snapshot is refreshed no more often than every 30 minutes.
139
+ Unchanged ordinary event snapshots are suppressed, rapid changes are coalesced, and the latest unchanged snapshot is refreshed no more often than every 30 minutes.
140
+ Session start forces a TTL refresh after the session report completes so observers re-read session identity even when Herdr emits no dedicated identity-change event.
131
141
  Each token has a one-hour TTL, so data from a crashed Pi process expires without steady socket traffic.
132
142
  Orderly shutdown sends one best-effort five-key clear patch, while abrupt shutdown and failed clears fall back to the TTL.
133
143
  Metadata uses the lifecycle reporter's monotonic sequence allocator and bounded best-effort sender, so older delayed reports cannot replace newer accepted values and socket failures never interrupt Pi.
134
144
 
145
+ The widget can display existing legacy `pi_spawn_*` records. The package does not create those records or spawn legacy peers.
146
+ The widget checks terminal and session identities before it shows an annotation. An annotation does not give a peer authority or process ownership.
147
+ See [Peer spawn provenance](./docs/peer-provenance.md) for the record format and display rules.
148
+
135
149
  Herdr custom pane tokens use a `$name` row entry.
136
150
  For example, this Herdr configuration displays Pi's model context without replacing pane labels or agent identity:
137
151
 
@@ -146,7 +160,11 @@ rows = [
146
160
 
147
161
  ## 🐑 Agent widget
148
162
 
149
- The widget lists only recognized agents in the current Herdr workspace and excludes the pane running the current Pi session.
163
+ Both backends share the passive five-row widget, separator, visibility setting, and collapse/restore behavior.
164
+ For hc, native error state and explicit terminal-ancestry annotations are described in [hc integration](./docs/hc-integration.md#widget-and-terminal-ancestry).
165
+ The pane, workspace, metadata, session-provenance, and subscription details below apply only to legacy Herdr.
166
+
167
+ The widget lists recognized agents across all workspaces in the connected Herdr session and excludes the pane running the current Pi session.
150
168
  Each row presents state, agent, pane, and workspace in that order, using theme hierarchy instead of repeating field labels.
151
169
  State icons follow Herdr's distinct static symbols: `×` blocked, `◐` working, `✓` done, `○` idle, and `·` unknown.
152
170
  Pi theme roles map blocked to `error`, working to `warning`, done to `accent`, idle to `success`, and unknown to `dim` without hard-coded terminal colors.
@@ -154,14 +172,20 @@ Agent identity prefers the name assigned by `herdr agent rename`, then Herdr dis
154
172
  Pane identity uses its label or metadata title with a short pane ID, while workspace identity uses its label with a short workspace ID.
155
173
  Terminal titles are not used as agent identity.
156
174
  The widget orders agents by `blocked`, `done`, `working`, `idle`, and `unknown`, shows at most five rows, and reports any remaining count.
175
+ Verified spawn annotations use muted text: `spawned by you`, `spawned you`, or `spawned by <peer>`.
176
+ The list stays flat and status-prioritized; provenance confers no privileges.
177
+ Relationships are resolved from the full recognized-agent snapshot before excluding the current pane or limiting rows, so a hidden origin can still be named.
178
+ Missing or mismatched identity evidence does not create a relationship.
157
179
  A state label published through Herdr metadata can replace the raw state name.
158
180
  Herdr's public pane responses do not expose the blocked prompt message, so the widget cannot show that reason.
159
181
  The widget does not focus panes, read terminal output, send prompts, or mark a background `done` state as seen.
160
182
  Its separator is named **Herdr**. In fullscreen TUI mode, click anywhere in the widget, including blank columns, to collapse it to that separator. Click the separator to restore the latest agents without moving keyboard focus.
161
183
  Opening `/herdr` in TUI mode also restores disclosure when the widget is enabled, without changing or saving the enable setting.
162
184
  Disclosure survives updates, temporary absence, and host remounts; session start or restarting the observer resets it. Collapse does not change Herdr data, reporting, subscriptions, or saved settings.
163
- The extension discovers the current workspace, pane list, and agent names, opens pane-scoped status subscriptions plus pane-update and workspace-name subscriptions, and then reloads those identities.
164
- Events trigger serialized, coalesced reads rather than replacing current state with event payloads. If an event arrives during a read, the extension reads again before publishing that result.
185
+ The extension discovers the current pane, session-wide pane list, workspace labels, and agent names, opens pane-scoped status subscriptions plus pane and workspace subscriptions, and then reloads those identities.
186
+ Events trigger serialized, coalesced reads rather than replacing current state with event payloads.
187
+ If events arrive during reads, the extension discards up to two consecutive reads. On the third invalidated read, it publishes that complete snapshot and immediately reads again, so sustained events cannot prevent updates.
188
+ Snapshots can briefly lag newer events; changes to the current pane or recognized-agent subscription set are reconciled before publication.
165
189
  Agent names, workspace labels, and cleared presentation fields update from these authoritative reads.
166
190
  Changes to the current pane, workspace, or recognized-agent set rebuild the pane-scoped subscriptions without consuming the bounded failure retry.
167
191
  Unexpected disconnection or `events_lost` clears the widget before one bounded reconnect attempt, and a second failure leaves it hidden until the next Pi session or `/reload`.
@@ -169,34 +193,37 @@ Session replacement and shutdown abort the subscription, pending reads, reconnec
169
193
 
170
194
  ## 🔒 Security and privacy
171
195
 
172
- The extension connects only to the Unix socket or Windows named pipe provided by `HERDR_SOCKET_PATH`.
196
+ In legacy Herdr mode, the extension connects only to the Unix socket or Windows named pipe provided by `HERDR_SOCKET_PATH`.
173
197
  Lifecycle reporting sends the current Herdr pane ID, Pi session path or ID, lifecycle state, session start reason, and blocked label to that endpoint.
174
198
  Metadata reporting sends the current Herdr pane ID plus only the selected model ID, provider ID, effective Thinking level, explicit Pi session name, and rounded context-usage percentage.
175
- For the widget, it reads the canonical current pane, current workspace metadata, current workspace pane list, and session agent list, then subscribes to pane creation, updates, closure, movement, exit, agent detection, agent-status changes, and workspace renames.
176
- The session agent list can contain agent metadata from other workspaces, but the extension retains names only for panes in the current workspace list.
199
+ For the widget, it reads the canonical current pane and session-wide pane, workspace, and agent lists, then subscribes to pane creation, updates, closure, movement, exit, agent detection, agent-status changes, and workspace creation, closure, and renames.
200
+ Agent names are joined only to matching pane and workspace identities in the session-wide pane list.
177
201
  Widget fields can include workspace, tab, pane, terminal, agent, display, name, title, label, state-label, and lifecycle identifiers supplied by Herdr.
178
- The subscription can deliver matching pane events from other workspaces in the same Herdr session, and the extension ignores them after resolving the current workspace.
179
- The extension filters presentation to the current workspace, strips terminal controls at the display boundary, and never reads sibling terminal output for the widget.
202
+ Events from every workspace in the connected Herdr session can refresh the widget.
203
+ The extension strips terminal controls at the display boundary and never reads sibling terminal output for the widget.
180
204
  The package does not authenticate the endpoint, so trust the environment that launches Pi and controls these variables.
181
205
 
182
- The bundled skills load operating guidance from the local CLI only after an explicit request for Herdr or Herdr Core.
183
- The returned CLI-owned instructions can direct Pi to inspect terminals, create panes or persistent terminals, start agents, send input, and run local or remote commands.
184
- Those commands execute with the same user permissions as Pi and can affect live terminal sessions.
185
- Both bootstraps stop when their CLI is unavailable or its `--skill` command fails; the `herdr` bootstrap also stops when `HERDR_ENV` is not `1`.
186
- Command recipes, approval handling, and other operating safety rules come from the selected CLI's installed version instead of being duplicated by this package.
206
+ In hc mode, the extension uses the inherited socket without starting a core. `inspect` and the widget do not read terminal output. Status reports and sampled process facts do not authenticate peers.
207
+
208
+ **Spawn is denied by default.** For each spawn, an operator at an interactive Pi TUI must explicitly confirm that the selected local hc core on this connection was launched by a trusted host with a pre-spawn environment allowlist. The allowlist must govern the effective environment of programs started by hc, not just the environment of the calling Pi process. hc merges launch overrides into its own base environment and retains most of that base. The prompt does not filter the environment or authenticate the endpoint. Task text, environment values, and tool arguments are not proof. Approval applies to one spawn on the same socket. There is no silent retry, reconnect, force, or alternate backend for that spawn.
209
+
210
+ The extension starts the new peer with absolute Node and Pi CLI paths from the current Pi runtime and loads this package's extension and skill. Both executables must resolve outside the topmost Git checkout that contains the current working directory, or outside that directory if there is no Git checkout. The launch does not forward Pi's caller environment. It overrides `NODE_OPTIONS` and `NODE_PATH` as an additional precaution, not as a substitute for the host allowlist. The peer has ordinary user permissions and can incur provider costs. Do not include secrets in tasks or messages. Peer content does not grant user permission.
211
+
212
+ A fresh observation and idle status do not guarantee input ownership. hc can wait on a draft, and a person can take over after the check. The tool cannot check process identity and send atomically. See [hc trust and delivery limits](./docs/hc-integration.md#trust-and-delivery-limits).
187
213
 
188
214
  ## 🚧 Limitations
189
215
 
190
- - Lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes.
191
- - The widget has no settings for placement, workspace scope, or row count.
192
- - The widget cannot show blocked prompt text because Herdr does not expose it through public pane responses.
193
- - The widget requires compatible pane-update and workspace-name subscriptions; unsupported subscriptions hide the widget without disabling lifecycle or metadata reporting.
194
- - A pane-label change appears on its next update event or authoritative refresh; an agent rename emits a pane-update event.
195
- - Integration requires a running compatible Herdr session and valid injected environment variables.
196
- - Each skill requires its matching CLI with `--skill` support; `hc` does not enable the legacy Herdr lifecycle reports or widget.
216
+ - Extension-owned lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes; hc status remains Pi-owned.
217
+ - The widget has no settings for placement, workspace scope, or row count; it does not configure other sessions or saved machines. hc may expose already configured mirrored terminals in its native list.
218
+ - Peer delivery uses terminal input, not a mailbox. Acknowledgement does not prove that the peer read or completed the task. Results are not forwarded automatically.
219
+ - Real provider collaboration and physical terminal behavior remain unverified.
220
+ - Neither widget reads blocked dialog text from terminal output; legacy Herdr also does not expose it through public pane responses.
221
+ - Legacy Herdr requires compatible pane and workspace subscriptions; unsupported subscriptions hide the widget without disabling lifecycle or metadata reporting.
222
+ - In legacy Herdr, a pane-label change appears on its next update event or authoritative refresh; an agent rename emits a pane-update event.
223
+ - Integration requires a compatible running backend and valid inherited bindings; hc's bounded native readiness checks do not provide legacy `interactive_ready` or authenticated session identity.
197
224
  - Socket failures are intentionally silent after the bounded retry.
198
- - Skill cleanup tracking exists only in the active model context, so compaction, session replacement, `/reload`, or shutdown can leave temporary panes open.
199
- - The package does not install, start, update, or configure Herdr or Herdr Core itself.
225
+ - Older Herdr integrations without the runtime-claim protocol must not be enabled alongside this package; remove the legacy integration as described in Quick start.
226
+ - The package does not install, start, update, or configure either backend. hc does not arrange windows; the separate herdr-app does and is not integrated here.
200
227
 
201
228
  ## 🗂️ Package layout
202
229
 
@@ -206,14 +233,15 @@ packages/pi-herdr/
206
233
  │ ├── index.ts # Thin repository entrypoint
207
234
  │ └── herdr-agent-state.ts # Herdr lifecycle integration
208
235
  ├── dist/ # Generated TypeScript runtime loaded by Pi
209
- ├── scripts/ # Deterministic runtime builder
210
- ├── skills/ # Published herdr and hc bootstraps for CLI-owned guidance
211
- └── test/ # Behavior and lifecycle coverage
236
+ ├── scripts/ # Repository-only build and verification tools
237
+ ├── docs/ # Legacy provenance and hc integration
238
+ ├── skills/pi-herdr/ # Published hc peer skill
239
+ └── test/ # Behavior, lifecycle, and resource coverage
212
240
  ```
213
241
 
214
242
  ## 🔎 Keywords
215
243
 
216
- Pi, Herdr, Herdr Core, hc, terminal multiplexer, persistent terminals, coding agents, agent orchestration, lifecycle state.
244
+ Pi, hc, herdr-core, Herdr, terminal multiplexer, coding agents, independent peers, terminal ancestry, spawn provenance, agent status, lifecycle state, pane metadata.
217
245
 
218
246
  ## 📄 License
219
247
 
@@ -3,18 +3,20 @@
3
3
 
4
4
  // src/herdr-menu.ts
5
5
  function createHerdrMenu(options) {
6
+ const hc = options.backend === "hc";
7
+ const label = hc ? "hc" : "Herdr";
6
8
  return {
7
9
  start: "main",
8
10
  screens: {
9
11
  // One setting stays on the main menu, matching /tool rather than adding a submenu.
10
12
  main: () => ({
11
13
  kind: "actions",
12
- title: "Herdr",
14
+ title: label,
13
15
  items: [
14
16
  {
15
17
  id: "widget",
16
18
  label: `Agent widget: ${options.isEnabled() ? "On" : "Off"}`,
17
- description: "Show or hide sibling agents above the editor",
19
+ description: hc ? "Show or hide reporting agents across the connected hc core and machines" : "Show or hide agents across all workspaces above the editor",
18
20
  action: "toggle"
19
21
  },
20
22
  { id: "status", label: "Status", to: "status" },
@@ -25,18 +27,20 @@ function createHerdrMenu(options) {
25
27
  }),
26
28
  status: () => ({
27
29
  kind: "detail",
28
- title: "Herdr Status",
30
+ title: `${label} Status`,
29
31
  lines: [
30
32
  `Agent widget setting: ${options.isEnabled() ? "on" : "off"}`,
31
33
  "The widget appears only in TUI mode with recognized sibling agents.",
32
- "Lifecycle and metadata reporting are independent of this setting.",
34
+ hc ? "Scope: the connected hc core and its connected machines." : "Scope: all workspaces in the connected Herdr session.",
35
+ hc ? "Pi owns native OSC 7501 lifecycle reports; this setting changes only the widget." : "Lifecycle and metadata reporting are independent of this setting.",
36
+ ...hc ? ["Spawn annotations describe terminal ancestry, not Pi session identity or authority."] : [],
33
37
  `User settings file: ${options.settingsPath}`
34
38
  ],
35
39
  hint: "back"
36
40
  }),
37
41
  help: () => ({
38
42
  kind: "detail",
39
- title: "Herdr Help",
43
+ title: `${label} Help`,
40
44
  lines: [
41
45
  "Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.",
42
46
  "Manual pi-herdr.json changes apply after /reload or the next session start.",
@@ -53,4 +57,4 @@ function createHerdrMenu(options) {
53
57
  export {
54
58
  createHerdrMenu
55
59
  };
56
- //# sourceMappingURL=herdr-menu-IUPFF5YK.ts.map
60
+ //# sourceMappingURL=herdr-menu-CA4DI2LZ.ts.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../src/herdr-menu.ts"],
4
+ "sourcesContent": ["import type { MenuDefinition } from \"@narumitw/pi-tui-kit\";\n\nexport function createHerdrMenu(options: {\n settingsPath: string;\n backend?: \"herdr\" | \"hc\";\n isEnabled(): boolean;\n toggle(signal: AbortSignal): Promise<boolean>;\n}): MenuDefinition<undefined, \"main\" | \"status\" | \"help\", \"toggle\"> {\n const hc = options.backend === \"hc\";\n const label = hc ? \"hc\" : \"Herdr\";\n return {\n start: \"main\",\n screens: {\n // One setting stays on the main menu, matching /tool rather than adding a submenu.\n main: () => ({\n kind: \"actions\",\n title: label,\n items: [\n {\n id: \"widget\",\n label: `Agent widget: ${options.isEnabled() ? \"On\" : \"Off\"}`,\n description: hc\n ? \"Show or hide reporting agents across the connected hc core and machines\"\n : \"Show or hide agents across all workspaces above the editor\",\n action: \"toggle\",\n },\n { id: \"status\", label: \"Status\", to: \"status\" },\n { id: \"help\", label: \"Help\", to: \"help\" },\n { id: \"close\", label: \"Close\", close: true },\n ],\n hint: \"close\",\n }),\n status: () => ({\n kind: \"detail\",\n title: `${label} Status`,\n lines: [\n `Agent widget setting: ${options.isEnabled() ? \"on\" : \"off\"}`,\n \"The widget appears only in TUI mode with recognized sibling agents.\",\n hc\n ? \"Scope: the connected hc core and its connected machines.\"\n : \"Scope: all workspaces in the connected Herdr session.\",\n hc\n ? \"Pi owns native OSC 7501 lifecycle reports; this setting changes only the widget.\"\n : \"Lifecycle and metadata reporting are independent of this setting.\",\n ...(hc ? [\"Spawn annotations describe terminal ancestry, not Pi session identity or authority.\"] : []),\n `User settings file: ${options.settingsPath}`,\n ],\n hint: \"back\",\n }),\n help: () => ({\n kind: \"detail\",\n title: `${label} Help`,\n lines: [\n \"Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.\",\n \"Manual pi-herdr.json changes apply after /reload or the next session start.\",\n \"The widget defaults to on. Project overrides are not read.\",\n ],\n hint: \"back\",\n }),\n },\n actions: {\n toggle: async ({ signal }) => ((await options.toggle(signal)) ? { kind: \"stay\" } : { kind: \"rejected\" }),\n },\n };\n}\n"],
5
+ "mappings": ";;;;AAEO,SAAS,gBAAgB,SAKoC;AAClE,QAAM,KAAK,QAAQ,YAAY;AAC/B,QAAM,QAAQ,KAAK,OAAO;AAC1B,SAAO;AAAA,IACL,OAAO;AAAA,IACP,SAAS;AAAA;AAAA,MAEP,MAAM,OAAO;AAAA,QACX,MAAM;AAAA,QACN,OAAO;AAAA,QACP,OAAO;AAAA,UACL;AAAA,YACE,IAAI;AAAA,YACJ,OAAO,iBAAiB,QAAQ,UAAU,IAAI,OAAO,KAAK;AAAA,YAC1D,aAAa,KACT,4EACA;AAAA,YACJ,QAAQ;AAAA,UACV;AAAA,UACA,EAAE,IAAI,UAAU,OAAO,UAAU,IAAI,SAAS;AAAA,UAC9C,EAAE,IAAI,QAAQ,OAAO,QAAQ,IAAI,OAAO;AAAA,UACxC,EAAE,IAAI,SAAS,OAAO,SAAS,OAAO,KAAK;AAAA,QAC7C;AAAA,QACA,MAAM;AAAA,MACR;AAAA,MACA,QAAQ,OAAO;AAAA,QACb,MAAM;AAAA,QACN,OAAO,GAAG,KAAK;AAAA,QACf,OAAO;AAAA,UACL,yBAAyB,QAAQ,UAAU,IAAI,OAAO,KAAK;AAAA,UAC3D;AAAA,UACA,KACI,6DACA;AAAA,UACJ,KACI,qFACA;AAAA,UACJ,GAAI,KAAK,CAAC,qFAAqF,IAAI,CAAC;AAAA,UACpG,uBAAuB,QAAQ,YAAY;AAAA,QAC7C;AAAA,QACA,MAAM;AAAA,MACR;AAAA,MACA,MAAM,OAAO;AAAA,QACX,MAAM;AAAA,QACN,OAAO,GAAG,KAAK;AAAA,QACf,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,QACA,MAAM;AAAA,MACR;AAAA,IACF;AAAA,IACA,SAAS;AAAA,MACP,QAAQ,OAAO,EAAE,OAAO,MAAQ,MAAM,QAAQ,OAAO,MAAM,IAAK,EAAE,MAAM,OAAO,IAAI,EAAE,MAAM,WAAW;AAAA,IACxG;AAAA,EACF;AACF;",
6
+ "names": []
7
+ }