@howaboua/pi-shepherdr 0.2.27 → 0.2.28-core.12.1.gda85fa2e8a0f

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.
Files changed (112) hide show
  1. package/README.md +48 -48
  2. package/index.ts +7 -1
  3. package/package.json +2 -9
  4. package/src/agent-identity.ts +3 -3
  5. package/src/agents-contract.ts +10 -14
  6. package/src/agents-discovery.ts +34 -54
  7. package/src/agents-focus.ts +23 -35
  8. package/src/agents-spawn.ts +24 -23
  9. package/src/agents-tool.ts +4 -19
  10. package/src/agents-work.ts +4 -3
  11. package/src/attachment-notes.ts +8 -7
  12. package/src/attachment-protocol.ts +3 -2
  13. package/src/attachment-routing.ts +1 -1
  14. package/src/attachment-target.ts +10 -18
  15. package/src/attachment.ts +14 -9
  16. package/src/board/discovery.ts +67 -0
  17. package/src/board/host.ts +93 -63
  18. package/src/board/membership.ts +16 -11
  19. package/src/board/records.ts +185 -0
  20. package/src/close-idle.ts +2 -9
  21. package/src/context-briefing.ts +230 -0
  22. package/src/context-routing.ts +1 -1
  23. package/src/control-panel/index.ts +2 -4
  24. package/src/control-panel/items.ts +1 -11
  25. package/src/control-panel/view.ts +3 -9
  26. package/src/controller.ts +50 -63
  27. package/src/core/AGENTS.md +7 -4
  28. package/src/core/admission-broker.mjs +235 -0
  29. package/src/core/admission-endpoint.ts +180 -0
  30. package/src/core/admission-owner.mjs +52 -0
  31. package/src/core/admission-startup.ts +130 -0
  32. package/src/core/admission.ts +181 -0
  33. package/src/core/agents.ts +102 -0
  34. package/src/core/backend.ts +110 -84
  35. package/src/core/client.ts +16 -0
  36. package/src/core/focus-channel-helper.mjs +6 -27
  37. package/src/core/focus-channel-wire.mjs +9 -6
  38. package/src/core/focus-channel.ts +5 -3
  39. package/src/core/focus-window.ts +15 -4
  40. package/src/core/helper-bootstrap.mjs +70 -0
  41. package/src/core/helper-context.mjs +98 -0
  42. package/src/core/helper-core.mjs +121 -0
  43. package/src/core/machines.ts +30 -0
  44. package/src/core/registration.ts +7 -2
  45. package/src/core/remote-endpoint.ts +80 -74
  46. package/src/core/remote-helper.ts +330 -0
  47. package/src/core/remote-reader.ts +3 -42
  48. package/src/core/remote-service.mjs +239 -0
  49. package/src/core/remote-transport.ts +290 -0
  50. package/src/core/spawn.ts +20 -20
  51. package/src/core/terminal-peer.mjs +57 -0
  52. package/src/core/terminal.ts +4 -2
  53. package/src/delivery.ts +39 -0
  54. package/src/fleet/catalog.ts +16 -58
  55. package/src/fleet/connection.ts +9 -18
  56. package/src/fleet/index.ts +38 -76
  57. package/src/fleet/inspection.ts +9 -22
  58. package/src/fleet/machine.ts +28 -12
  59. package/src/fleet/monitor.ts +8 -29
  60. package/src/fleet/persistence.ts +2 -2
  61. package/src/fleet/reconnect.ts +5 -3
  62. package/src/fleet/setup.ts +6 -16
  63. package/src/launch-contract.ts +0 -3
  64. package/src/launch-location.ts +4 -132
  65. package/src/launch.ts +18 -144
  66. package/src/messages/attachments.ts +1 -1
  67. package/src/messages/attribution.ts +9 -14
  68. package/src/messages/events.ts +5 -9
  69. package/src/messages/focus.ts +2 -7
  70. package/src/messages/guidance.ts +2 -43
  71. package/src/messages/peer-sharing.ts +133 -0
  72. package/src/monitor-events.ts +14 -43
  73. package/src/monitor-extension-messages.ts +5 -6
  74. package/src/monitor-record.ts +4 -0
  75. package/src/monitor-state.ts +1 -101
  76. package/src/monitor.ts +38 -66
  77. package/src/notes-discovery.ts +67 -0
  78. package/src/peer-inbox.ts +21 -27
  79. package/src/remote/context-relay.ts +25 -10
  80. package/src/remote/notes-reader.mjs +67 -0
  81. package/src/remote/shepherdr-channel.mjs +1 -1
  82. package/src/remote/shepherdr-checkpoints.mjs +49 -102
  83. package/src/remote/shepherdr-context.mjs +1 -1
  84. package/src/remote/shepherdr-peer.mjs +19 -24
  85. package/src/remote/shepherdr-session.mjs +18 -7
  86. package/src/saved-context.ts +62 -0
  87. package/src/settlement/collector.ts +29 -9
  88. package/src/settlement/index.ts +35 -6
  89. package/src/shared-context-host.ts +27 -33
  90. package/src/shared-context.ts +44 -15
  91. package/src/spawn-context.ts +11 -3
  92. package/src/spawn-ownership.ts +1 -1
  93. package/src/ssh-setup.ts +40 -73
  94. package/src/types.ts +4 -8
  95. package/src/voice-handoff.ts +1 -1
  96. package/src/widget.ts +7 -2
  97. package/src/worker-ownership.ts +2 -8
  98. package/src/worker-service.ts +6 -14
  99. package/src/core/context-relay.mjs +0 -111
  100. package/src/core/remote-exec.ts +0 -122
  101. package/src/core/remote-helper.mjs +0 -244
  102. package/src/core/remote-relay.ts +0 -191
  103. package/src/core/request.ts +0 -124
  104. package/src/herdr-client.ts +0 -364
  105. package/src/herdr.ts +0 -268
  106. package/src/machine-catalog.ts +0 -83
  107. package/src/monitor-event.ts +0 -84
  108. package/src/remote/client.ts +0 -127
  109. package/src/remote/deployment.ts +0 -179
  110. package/src/remote/focus-channels.ts +0 -89
  111. package/src/remote/shepherdr.mjs +0 -504
  112. package/src/remote/transport.ts +0 -369
package/README.md CHANGED
@@ -14,47 +14,43 @@ With Pi Codex's compatible custom developer-message API active, asynchronous wor
14
14
  pi install npm:@howaboua/pi-shepherdr
15
15
  ```
16
16
 
17
- Requires Pi 1.2.0 or newer and Node.js 22.18 or newer. Run Pi inside Herdr Core 0.1.14 or newer, or the Herdr app, to use the new Herdr backend. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed.
18
-
19
- For the older Herdr TUI, install its Pi integration:
20
-
21
- ```bash
22
- herdr integration install pi
23
- ```
17
+ Requires Pi 1.5 or newer, Node.js 22.18 or newer and Herdr Core 0.1.18 or newer. Run Pi in a Core terminal, through `hc` or a Herdr app connected to that Core. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed. No separate Pi integration is needed.
24
18
 
25
19
  Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; they own the same agent surface.
26
20
 
27
- Pi Codex is optional. Without it, Shepherdr remains a normal Pi extension.
21
+ Shepherdr installs and runs on its own. Pi Codex, shared Notes and boards are optional. Delegation, supervision, messages, focus and orchestration work without them. Shared Notes require Notes Compaction 0.0.15 or newer; boards require Agent Board 0.0.5 or newer. [Agent Comms](../pi-agent-comms) also provides both integrations when loaded. Enable each shared feature in every participating session.
28
22
 
29
- Herdr Core workers start as background terminals by default. Explicit new-tab and new-workspace placements appear when an app connected to that Core adopts them. Focus requires a Herdr app window connected to the target Core. Existing Herdr TUI sessions cannot be moved into Core.
23
+ Workers start as background Core terminals by default. Use `placement: "new_workspace"` for a new app workspace, or `placement: "new_tab"` with a `workspace` ID advertised by a live terminal on the target Core. A connected Herdr app adopts these terminals. Pane placement is no longer supported. Focus requires a Herdr app window running on the target Core's machine and connected to that Core.
30
24
 
31
25
  For remote Core workers, add machines with `hc machine add` and install Node.js, Herdr Core and Shepherdr on each target. Delegation, supervision, shared context and boards work across those machines.
32
26
 
27
+ ### Migrating from the older Herdr TUI
28
+
29
+ Update and restart controllers and workers together. The older Herdr backend, SSH bridge, machine catalogue and legacy environment overrides are no longer used. Existing Herdr TUI sessions cannot migrate to Core. Start fresh Core terminals and configure remote machines with `hc machine add` on the host running Pi.
30
+
31
+ When switching from the older TUI or another Core namespace, explicitly select the agents you want to watch again. Saved addresses from the previous namespace are not transferable.
32
+
33
33
  ## Control panel
34
34
 
35
- The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi inside Herdr to connect the fleet and start monitoring automatically. Open the control panel with:
35
+ The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi inside Core to connect the fleet and start monitoring automatically. Open the control panel with:
36
36
 
37
37
  ```text
38
38
  /herdr
39
39
  ```
40
40
 
41
- **Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines for the older Herdr TUI. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
41
+ **Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds machines to Core's catalogue. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
42
42
 
43
- Run `/herdr close-idle` to close idle child sessions spawned by the current session branch. Attached or assigned existing sessions are never included. Busy, blocked, unavailable or unverified children stay open. Children spawned before this feature was installed have no ownership receipt and stay open too. Pi shuts down gracefully before its pane closes.
43
+ Run `/herdr close-idle` to close idle child sessions spawned by the current session branch. Attached or assigned existing sessions are never included. Busy, blocked, unavailable or unverified children stay open. Children spawned before this feature was installed have no ownership receipt and stay open too. Pi shuts down gracefully before its Core terminal closes.
44
44
 
45
45
  `/herdr` is Shepherdr's only entry point. Outside the TUI, it reports status without changing it. An orchestration change records one visible guidance message without triggering a turn. Resumed sessions restore their last mode; new sessions start with normal guidance. The current guidance returns when a new model context no longer contains it, including turns started by worker messages. Tool availability and monitoring do not depend on this mode.
46
46
 
47
- For the older Herdr TUI, add a machine by entering an SSH target or alias, a label and an optional remote session under **Connections**. Herdr performs setup in the terminal and asks before installing or replacing its remote server. OpenSSH owns authentication; Shepherdr does not store credentials. Profiles remain in Herdr's existing catalog, where they can also be renamed, disabled or removed.
48
-
49
- With the older TUI, Shepherdr connects enabled profiles at session startup. **Status** refreshes the catalog and retries failed connections or incomplete monitoring without dropping working connections. A catalog refresh stops watches for disabled or removed profiles without stopping remote agents.
50
-
51
- Profiles belong to the host running Pi, not the machine displaying its terminal. Omit `machine` for local agent calls. `list` and `find` search all machines unless filtered. Explicit `local` also means the host running Pi. For remote calls, use the opaque profile ID returned by `list`, not its label or hostname. Renaming a profile changes its label, not its routing identity.
47
+ Under **Connections**, enter an SSH target or alias, a machine name and an optional Core session. The panel runs `hc machine add <target> --name <name>` with `--session <session>` when supplied. Core owns installation approvals and the catalogue. OpenSSH owns authentication; Shepherdr does not store credentials or maintain another catalogue.
52
48
 
53
- With the older TUI, remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs managed transport helpers under `~/.pi/agent` on each remote, runs them only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
49
+ **Status** refreshes the Core catalogue and retries failed connections or incomplete monitoring without dropping working connections. Removing a machine stops its watches without stopping its agents.
54
50
 
55
- ### Migrating from separate Shepherdr machines
51
+ Machines belong to the host running Pi, not the machine displaying its terminal. Omit `machine` for local agent calls. `list` and `find` search all machines unless filtered. The reserved selector `local` always means the host running Pi. Remote calls accept an exact current machine name or a stable Core ID returned by `list`. Duplicate names require an ID. Hostnames and old aliases are not inferred. Refresh **Status** after renaming a machine. Watches and saved routes retain its stable ID across name changes.
56
52
 
57
- `shepherdr.json` is no longer read. Existing Herdr profiles are used directly. Configure any missing profiles in Herdr on the host running Pi. Old machine aliases are not migrated. Legacy watches, including local watches, are cleared with a notice because they cannot distinguish explicit subscriptions from accidental ones. Re-select any ongoing watches explicitly.
53
+ Remote file watches, Notes, shared-context calls and peer messages use a private Core-owned helper, started lazily and kept alive over a flow-controlled terminal attachment. Shepherdr does not install SSH bridge files or poll through `machine.exec`. Voice focus uses a separate private helper so large Notes transfers do not block its channel. Monitoring uses each Core's own snapshot rather than treating a missing machine in an aggregate terminal list as closed agents.
58
54
 
59
55
  ## Agent calls
60
56
 
@@ -85,17 +81,17 @@ Nonblocking extension messages notify the controller once; blocking messages arr
85
81
 
86
82
  Use `send` for messages and work updates without adding supervision. Use `assign` to delegate work and receive its monitored result, automatically or through an explicit blocking call. It also accepts updates to running work, sharing that work's pending result rather than replacing it. If another call is already waiting, the update returns after submission and leaves that waiter intact. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
87
83
 
88
- Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's pane closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
84
+ Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's terminal closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
89
85
 
90
- Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session, and also names the tab in the older Herdr TUI. The routing `name` remains optional and is derived from the label when omitted.
86
+ Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session. The routing `name` remains optional and is derived from the label when omitted.
91
87
 
92
88
  Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
93
89
 
94
90
  After Pi compaction or Notes context rollover, the controller receives its supervised agents' exact machine and target, submitted tasks and follow-up instructions, and last observed status, including settled and blocked workers. Read a target for its reply or pending extension messages. This reminder does not start a turn or bypass normal turn preparation.
95
91
 
96
- Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host and session identity. The older TUI also includes workspace, tab and pane details. Core reports use terminal addresses and include app location IDs when available. These are runtime locations, not the desktop window showing a pane.
92
+ Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host and session identity. Core reports use terminal addresses and include app location IDs when available. These are runtime locations, not the desktop window showing a terminal.
97
93
 
98
- Messages sent through `agents` bypass the receiving Pi editor, preserving unsent drafts. Update and reload Shepherdr on receiving agents as well as controllers. If a receiver is unavailable, delivery fails without pasting into its terminal. On the older TUI, raw `herdr agent prompt` still uses terminal input and does not provide this protection.
94
+ Messages sent through `agents` bypass the receiving Pi editor, preserving unsent drafts. Update and restart Shepherdr on receiving agents as well as controllers. If a receiver is unavailable, delivery fails without pasting into its terminal.
99
95
 
100
96
  Messages beginning with `/` use the target Pi session's command, skill and prompt-template expansion, with sender attribution kept out of the arguments. Skills and templates retain normal task waiting. Prompt templates remain supported, but you must tell your agent which templates exist separately. When Pi Codex Conversion is installed, update and reload it too.
101
97
 
@@ -105,16 +101,16 @@ Call `agents` with `{ commands: true }` to list this session's available slash c
105
101
 
106
102
  These built-in commands are available through agent messages without an allowlist:
107
103
 
108
- | Command | Result |
109
- | ------------------------- | ------------------------------------------------ |
110
- | `/quit` | Shut down Pi gracefully and close its Herdr pane |
111
- | `/model <provider/model>` | Change the model |
112
- | `/thinking <level>` | Change the thinking level |
113
- | `/name <name>` | Rename the session |
114
- | `/new` | Start a new session |
115
- | `/reload` | Reload Pi resources |
116
- | `/resume <path>` | Resume the session at the supplied path |
117
- | `/compact [instructions]` | Compact the session with optional instructions |
104
+ | Command | Result |
105
+ | ------------------------- | --------------------------------------------------- |
106
+ | `/quit` | Shut down Pi gracefully and close its Core terminal |
107
+ | `/model <provider/model>` | Change the model |
108
+ | `/thinking <level>` | Change the thinking level |
109
+ | `/name <name>` | Rename the session |
110
+ | `/new` | Start a new session |
111
+ | `/reload` | Reload Pi resources |
112
+ | `/resume <path>` | Resume the session at the supplied path |
113
+ | `/compact [instructions]` | Compact the session with optional instructions |
118
114
 
119
115
  Custom extension commands must be both registered in the receiving Pi session and allowed in its global user config. **Settings → Agent commands** shows the actual config path. The file is `pi-shepherdr.json` in Pi's agent directory, normally `~/.pi/agent`. Add `extensionCommands`, preserving any existing fields:
120
116
 
@@ -128,7 +124,7 @@ Custom extension commands must be both registered in the receiving Pi session an
128
124
 
129
125
  Keys are command names without `/`; values are nonempty descriptions. Only the global user config grants permission. A repository's `.pi/pi-shepherdr.json` cannot allow commands. The config is read on each call. A missing allowlist allows no custom extension commands; malformed config grants none.
130
126
 
131
- Blocked commands return the built-in commands and currently registered, allowed extension commands. Commands return `commandSubmitted: true` without adding a task watch, even through `spawn` or `assign`. Submission does not confirm command success, except `/quit`, which waits for Pi to exit and its pane to close. Built-in commands other than `/quit` require an idle target. Skills and prompt templates keep their existing behavior.
127
+ Blocked commands return the built-in commands and currently registered, allowed extension commands. Commands return `commandSubmitted: true` without adding a task watch, even through `spawn` or `assign`. Submission does not confirm command success, except `/quit`, which waits for Pi to exit and its terminal to close. Built-in commands other than `/quit` require an idle target. Skills and prompt templates keep their existing behavior.
132
128
 
133
129
  Idle messages start a custom-message turn through Pi’s complete preparation chain. Messages arriving during a run use steering, promoted to developer messages when Pi Codex developer delivery is active. Otherwise they remain ordinary Pi custom messages.
134
130
 
@@ -177,45 +173,49 @@ await tools.agents({
177
173
  });
178
174
  ```
179
175
 
180
- Supply both booleans and enable at least one. `context` shares notes and history through aliases without changing either session's original context identity or moving its notes. `contextAgent` addresses the target from the controller; `controllerContextAgent` addresses the controller from the target. Use these paths as `history`'s `agent_name` or as `<agent>/notes/<path>` for notes. Each agent's relative note paths remain its own. The target receives its controller alias without starting a turn.
176
+ Enable one or both choices. Omitted choices are false. `context` shares notes and history through aliases without changing either session's original context identity or moving its notes. The returned `agent` is the target's Pi session reference. Use it as `history`'s `agent_name` or as `<agent>/notes/<path>` for notes. Each agent's relative note paths remain its own. The target receives its controller reference without starting a turn.
181
177
 
182
- Context attachment requires compatible Notes Compaction in both sessions. Each owner keeps its original identity and local notes. Optional encrypted historical reads require compatible PCC transport and the original account and backend. The explicit `context: true` choice does not depend on the controller's spawn-sharing setting. If attachment changes context access during an exec cell, start a new cell before using notes or history.
178
+ Context attachment requires active Notes in both sessions, through Notes Compaction or Agent Comms. Each owner keeps its original identity and local notes. Optional encrypted historical reads require compatible PCC transport and the original account and backend. The explicit `context: true` choice does not depend on the controller's spawn-sharing setting. If attachment changes context access during an exec cell, start a new cell before using notes or history.
183
179
 
184
- `board: true` requires Pi Agent Board loaded in both sessions. It joins the controller's enabled board and returns `boardAgent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Notes or Codex Conversion.
180
+ `board: true` requires Agent Board or Agent Comms loaded in both sessions. It joins the controller's enabled board. Use the returned `agent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Notes or Codex Conversion.
185
181
 
186
182
  The target must be idle and both Pi sessions must be saved. Existing shared-context members and controllers with context children cannot be context targets. Existing board members and roots with board children cannot switch boards. A target supports one controller and one fixed set of attachment choices. Attachment starts no task or watch; `assign` and `send` never attach implicitly.
187
183
 
188
- Attachments survive resume, not forks. Live notes and history access needs the owning Pi processes and machine connections. After an interrupted attachment, resume the original sessions and retry the same target and choices. Retries reuse the original aliases and membership.
184
+ Attachments survive resume, not forks. Saved checkpoints remain readable without the owning Pi process when its saved session and machine are accessible. Writes and live history access need the owner. After an interrupted attachment, resume the original sessions and retry the same target and choices. Retries reuse the original aliases and membership.
189
185
 
190
- To detach, call `agents` with `action: "detach"`, the same target, and both booleans. Enable each membership you want to leave. Context detach retains counterpart notes under the existing aliases read-only. Local notes use captured checkpoints. Historical Remote references retain their original authenticated address, not a plaintext snapshot. Counterpart history and writes stop at detach. Native identities remain unchanged. Board detach restores the target's previous board without deleting either archive. Board members with children cannot detach. Reattachment is unsupported.
186
+ To detach, call `agents` with `action: "detach"`, the same target, and each membership you want to leave set to true. Omitted memberships are unchanged. Context detach retains counterpart notes under the existing aliases read-only. Local notes use captured checkpoints. Historical Remote references retain their original authenticated address, not a plaintext snapshot. Counterpart history and writes stop at detach. Native identities remain unchanged. Board detach restores the target's previous board without deleting either archive. Board members with children cannot detach. Reattachment is unsupported.
191
187
 
192
188
  If an attached owner closes, local note reads use its latest saved checkpoints when the source machine and session file remain reachable. Otherwise they return the timestamped attachment snapshot, marked stale with the access failure. This never writes to the owner's session. Historical encrypted reads require their original account and backend. Backend failures remain visible. An incomplete detach fails with a retry instruction rather than claiming success.
193
189
 
194
190
  ## Message board
195
191
 
196
- Boards are provided by the separate [Pi Agent Board](../pi-agent-board) extension. Install it in every participating Pi session, then reload:
192
+ Install Agent Board in every participating Pi session, then reload:
197
193
 
198
194
  ```sh
199
195
  pi install npm:@howaboua/pi-agent-board
200
196
  ```
201
197
 
202
- The same discussions, subscriptions and saved history continue without migration. Pi Agent Board owns the `board` tool, settings and `/board` browser viewer. Shepherdr has no fallback board or board controls under `/herdr`. If a saved board setting is on but the extension is missing, Shepherdr displays an installation warning once per session. Saved settings and archives remain untouched. Pi Codex Conversion is optional.
198
+ The loaded Board extension owns the `board` tool, `/board` settings and read-only browser viewer. Agent Comms can provide the same integration instead of Agent Board, retaining discussions, subscriptions and saved history. Do not load both Board providers together. Shepherdr has no fallback board or board controls under `/herdr`. If a saved session board setting is on but its provider is missing, Shepherdr displays a warning once per session. Saved settings and archives remain untouched. Pi Codex Conversion is optional.
203
199
 
204
- Shepherdr supplies family membership, attachments and remote routing. Children spawned while the board is enabled inherit its location and board ID even with another working directory. The spawn result's `boardAgent` is their address for subscriptions and explicit notifications, distinct from a pane or shared-notes identity. Independently started agents, existing `assign` targets and children spawned while it is off do not join automatically. Use explicit `attach` to join an existing agent. Board identity is independent of orchestration mode, shared notes and `share_context`.
200
+ Shepherdr supplies family membership, attachments and remote routing. Children spawned while the board is enabled inherit its location and board ID even with another working directory. The spawn result's `agent` is their Pi session reference for subscriptions, notifications and shared notes. The `sharing` flags report which memberships are active. Independently started agents, existing `assign` targets and children spawned while it is off do not join automatically. Use explicit `attach` to join an existing agent. Board identity is independent of orchestration mode, shared notes and `share_context`.
205
201
 
206
- Child board calls use the owning Pi sessions and existing SSH connections, not a separately provisioned service. The root and intermediate controllers must be running as processes, but need not be in an active model turn. Resume the owner and reconnect under `/herdr` → **Status** after a lost connection. Future root sessions can browse the archive even when the old owner is offline. A fork starts a new independent identity. Profiles selecting an existing session cannot bind to an enabled board through `spawn`; use `attach` followed by `assign` instead.
202
+ Child board calls use the owning Pi sessions and Core connections, not a separately provisioned service. The root and intermediate controllers must be running as processes, but need not be in an active model turn. Resume the owner and reconnect under `/herdr` → **Status** after a lost connection. Future root sessions can browse the archive even when the old owner is offline. A fork starts a new independent identity. Profiles selecting an existing session cannot bind to an enabled board through `spawn`; use `attach` followed by `assign` instead.
207
203
 
208
204
  ## Shared notes and history
209
205
 
210
206
  With compatible Pi Codex Conversion on both ends, Shepherdr marks fresh spawned workers before their first task with their immediate parent's native Pi session ID and `subagentKind: "collab_spawn"`. Workers also inherit the parent's effective cache routing identity, including nested and remote spawns. Each worker keeps its own native session, sockets and history. Cache routing works with shared notes disabled and does not grant notes access or copy the parent's transcript. Only matching prompt prefixes can benefit. Resume preserves the relationship; forks and profiles selecting existing sessions do not acquire it. Older PCC versions retain ordinary delegation and any supported parent linkage. The [extension API guide](../../docs/extension-apis.md#parent-and-worker-relationships) documents PCC's service contract for other orchestrators. Shepherdr owns transport, not a separate public relationship RPC API.
211
207
 
212
- With Notes Compaction on both ends, enable **Share subagent context** under `/notes` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; `contextAgent` identifies its notes and history. Nested spawns stay in the same family. Turning sharing off affects new spawns only. Existing identity survives resume. `assign` and independently started agents remain unchanged.
208
+ Install Notes Compaction in every participating session and reload, or use Agent Comms' Notes feature. Do not load both Notes providers together. With Notes active on both ends, enable **Share subagent context** under `/notes` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; the returned `agent` identifies its notes and history. Nested spawns stay in the same family. Turning sharing off affects new spawns only. Existing identity survives resume. `assign` and independently started agents remain unchanged.
209
+
210
+ ```sh
211
+ pi install npm:@howaboua/pi-notes-compaction
212
+ ```
213
213
 
214
214
  Set `"share_context": false` in a profile to keep its new workers' notes and history independent even when controller sharing is enabled. Omission or `true` follows the controller setting, never turns sharing on itself. This separates context, not filesystem permissions or information included in the task.
215
215
 
216
216
  Pi creates each worker session normally. The worker records its shared identity before Shepherdr delivers the first task; no pre-created session file or launch override is needed.
217
217
 
218
- Shared notes route through their owning Pi sessions and existing SSH connections. Those owners and intermediate controllers must be running. Resume the owner and reconnect under `/herdr` → **Status** after a connection loss. No note store is copied or silently substituted. New writes stay local; optional hybrid lookup is read-only.
218
+ Shared local checkpoints remain readable after workers or intermediate controllers close. Notes verifies saved family membership and reads the selected session branch. Saved reads also require the Notes provider's public reader package installed alongside Shepherdr on the controller. Cross-machine reads need a Core connection and access to the saved session, not a running Pi owner. Older sessions without a saved parent location can find family checkpoints across connected machines through their Notes index or standard Pi session directory. Writes and optional hybrid lookup still use their owning services. Reconnect machines under `/herdr` → **Status** after a connection loss.
219
219
 
220
220
  Shepherdr works without Notes or PCC. A target without active Notes sharing still starts independently with a warning. Invalid bindings fail before task delivery. Profiles selecting existing sessions cannot participate in shared `spawn`; use `attach`, then `assign`.
221
221
 
@@ -257,7 +257,7 @@ Optional profile settings:
257
257
 
258
258
  ## Advanced Herdr control
259
259
 
260
- Ordinary delegation stays inside `agents`. For terminal operations on Core, run `hc --skill`. For window operations, use `herdr-app --skill`. The older TUI provides its own guide through `herdr --skill`.
260
+ Ordinary delegation stays inside `agents`. For terminal operations on Core, run `hc --skill`. For window operations, use `herdr-app --skill`.
261
261
 
262
262
  Herdr still owns terminals, layout, agent processes and restored sessions. Shepherdr owns event subscriptions, remote routing, the fleet widget and purple settlement messages.
263
263
 
@@ -283,7 +283,7 @@ No reply means Shepherdr is unavailable. The query adds no model instructions or
283
283
 
284
284
  Shepherdr implements Pulses' optional detached-runner contract through Pi events. Pulses owns scheduling. Each worker runs in a separate Pi process, so the main agent remains available. Its final response returns through the same monitored waking delivery as asynchronous `agents` calls, including ordinary kickoff preparation and rollover admission. There is no passive-result or blocking execution mode.
285
285
 
286
- The adapter reuses owned saved sessions, refuses overlapping work and verifies parent session, branch and pane identity. Worker receipts are opaque to Pulses. Use ordinary Shepherdr controls to manage worker panes. Detached pulse workers cannot become schedulers themselves.
286
+ The adapter reuses owned saved sessions, refuses overlapping work and verifies parent session, branch and terminal identity. Worker receipts are opaque to Pulses. Use ordinary Shepherdr controls to manage worker terminals. Detached pulse workers cannot become schedulers themselves.
287
287
 
288
288
  Fresh and restored workers use the `general` profile's model, thinking level and explicit Pi arguments without its implementation-role prompt. Ordinary agent spawns still use the complete profile. Fresh workers inherit the existing family board independently of their working directory, alongside optional shared Notes and cache affinity. The adapter does not choose an output destination or keep the controlling Pi alive.
289
289
 
package/index.ts CHANGED
@@ -36,7 +36,13 @@ export default async function shepherdrExtension(
36
36
  acceptFocus(pi, ctx, fleet, pane, request),
37
37
  );
38
38
  const board = AgentBoard.create(pi, fleet);
39
- registerPeerInbox(pi, peerCommands, fleet, (ctx) => board.promptCatchup(ctx));
39
+ registerPeerInbox(
40
+ pi,
41
+ peerCommands,
42
+ fleet,
43
+ (ctx) => board.promptCatchup(ctx),
44
+ (ctx) => workerRole.isWorker(ctx.sessionManager),
45
+ );
40
46
  const sharedContext = await registerSharedAgentContext(pi, fleet, board);
41
47
  registerWorkerService(pi, fleet, sharedContext, board, workerRole);
42
48
  let promptMode: { readonly active: boolean } | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.27",
3
+ "version": "0.2.28-core.12.1.gda85fa2e8a0f",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -42,7 +42,6 @@
42
42
  "pack:dry": "npm pack --dry-run"
43
43
  },
44
44
  "peerDependencies": {
45
- "@howaboua/pi-notes-compaction": ">=0.0.14",
46
45
  "@howaboua/pi-codex-conversion": ">=4.0.9",
47
46
  "@earendil-works/pi-ai": ">=1.1.0",
48
47
  "@earendil-works/pi-coding-agent": ">=1.5.0",
@@ -50,18 +49,12 @@
50
49
  "typebox": "*"
51
50
  },
52
51
  "peerDependenciesMeta": {
53
- "@howaboua/pi-notes-compaction": {
54
- "optional": true
55
- },
56
52
  "@howaboua/pi-codex-conversion": {
57
53
  "optional": true
58
54
  }
59
55
  },
60
- "dependencies": {
61
- "@howaboua/pi-agent-board": "0.0.5"
62
- },
63
56
  "devDependencies": {
64
- "@howaboua/pi-notes-compaction": "0.0.14",
57
+ "@howaboua/pi-agent-comms": "0.0.0",
65
58
  "@howaboua/pi-codex-conversion": "4.0.9",
66
59
  "@biomejs/biome": "^2.6.3",
67
60
  "@earendil-works/pi-ai": "1.5.0",
@@ -1,12 +1,12 @@
1
+ import { sessionPath } from "./core/agents.js";
2
+ import type { CoreConnection } from "./core/backend.js";
1
3
  import type { AgentFleet } from "./fleet/index.js";
2
- import { sessionPath } from "./herdr.js";
3
- import type { HerdrConnection } from "./herdr-client.js";
4
4
  import { sessionContextPath } from "./remote/shepherdr-context.mjs";
5
5
  import type { PaneInfo } from "./types.js";
6
6
 
7
7
  /** Read the live Pi owner, never infer identity from a filename or terminal ID. */
8
8
  export async function nativeAgentName(
9
- client: HerdrConnection,
9
+ client: CoreConnection,
10
10
  panel: PaneInfo,
11
11
  signal?: AbortSignal,
12
12
  ): Promise<string> {
@@ -38,7 +38,6 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
38
38
  "label",
39
39
  "placement",
40
40
  "workspace",
41
- "pane",
42
41
  "cwd",
43
42
  "message",
44
43
  "base",
@@ -62,9 +61,7 @@ const AgentsRequest = Type.Object(
62
61
  machine: Type.Optional(Type.String()),
63
62
  voice: Type.Optional(Type.Boolean()),
64
63
  handoff: Type.Optional(Type.String()),
65
- target: Type.Optional(
66
- Type.String({ description: "Agent name or pane ID" }),
67
- ),
64
+ target: Type.Optional(Type.String()),
68
65
  agent_type: Type.Optional(Type.String()),
69
66
  name: Type.Optional(
70
67
  Type.String({
@@ -74,7 +71,6 @@ const AgentsRequest = Type.Object(
74
71
  label: Type.Optional(Type.String()),
75
72
  placement: Type.Optional(StringEnum(START_PLACEMENTS)),
76
73
  workspace: Type.Optional(Type.String()),
77
- pane: Type.Optional(Type.String()),
78
74
  cwd: Type.Optional(Type.String()),
79
75
  message: Type.Optional(
80
76
  Type.String({ description: "Task, follow-up or extension reply" }),
@@ -164,15 +160,15 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
164
160
  throw new Error(
165
161
  "machine requires target for command discovery; omit both for this session",
166
162
  );
167
- if (
168
- (action === "attach" || action === "detach") &&
169
- (typeof request["context"] !== "boolean" ||
170
- typeof request["board"] !== "boolean" ||
171
- (!request["context"] && !request["board"]))
172
- )
173
- throw new Error(
174
- `${action} requires context and board booleans; enable at least one`,
175
- );
163
+ if (action === "attach" || action === "detach") {
164
+ for (const field of ["context", "board"]) {
165
+ if (field in request && typeof request[field] !== "boolean")
166
+ throw new Error(`${field} must be a boolean`);
167
+ }
168
+ if (request["context"] !== true && request["board"] !== true)
169
+ throw new Error(`${action} requires context:true or board:true`);
170
+ request = { context: false, board: false, ...request };
171
+ }
176
172
  if (action === "reply") {
177
173
  for (const field of ["extension", "id", "target"]) {
178
174
  if (typeof request[field] !== "string" || !request[field].trim())
@@ -1,5 +1,6 @@
1
1
  import { nativeAgentName } from "./agent-identity.js";
2
2
  import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
3
+ import { readTerminal } from "./core/agents.js";
3
4
  import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
4
5
  import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
5
6
  import type { AgentStatus, PaneInfo, SessionSnapshot } from "./types.js";
@@ -27,7 +28,6 @@ function describeProfiles(profiles: Map<string, AgentProfile>) {
27
28
  export async function agentsHelp(
28
29
  boardAvailable = false,
29
30
  gpt = false,
30
- core = false,
31
31
  ): Promise<Record<string, unknown>> {
32
32
  const profiles = await loadAgentProfiles();
33
33
  return {
@@ -40,35 +40,36 @@ export async function agentsHelp(
40
40
  find: "query? status? machine?",
41
41
  focus: "target machine? voice? handoff?",
42
42
  spawn:
43
- "agent_type label message name? machine? placement? workspace? pane? cwd? base? blocking?" +
43
+ "agent_type label message name? machine? placement? workspace? cwd? base? blocking?" +
44
44
  (boardAvailable ? " board_thread_id?" : ""),
45
45
  watch: "target machine?",
46
46
  unwatch: "target machine?",
47
47
  send: "target message machine?",
48
48
  assign: "target message machine? blocking?",
49
- attach: "target context board machine?",
50
- detach: "target context board machine?",
49
+ attach: "target context? board? machine?",
50
+ detach: "target context? board? machine?",
51
51
  read: "target machine? source=latest|visible|recent? lines?",
52
52
  reply: "target extension id message machine?",
53
53
  },
54
54
  rules: {
55
+ peers: gpt
56
+ ? "Existing session≠your sub-agent; send/watch need no attach. Contact≠shared Notes/Board; attach changes membership"
57
+ : "Existing sessions may be independent peers, not your sub-agents. Messaging and watching need no attachment. Contact does not imply shared Notes or Board membership; attach changes sharing",
58
+ read: gpt
59
+ ? "latest(default)=last reply+pending extension messages; visible=current TUI screen; recent=TUI scrollback, lines default 40. Findings→returned Notes path if shared Notes available"
60
+ : "latest (default) returns the last reply and pending extension messages; visible reads the current TUI screen; recent reads TUI scrollback, lines default 40. For findings, read the returned Notes path when shared Notes is available",
55
61
  reply: gpt
56
62
  ? "Extension report/read template required; send≠resolve; blocking waits resumed work; others return after semantic delivery"
57
63
  : "Use the extension-authored template from its report/read; send does not resolve it. Blocking messages wait for resumed work; other replies return after semantic delivery",
58
64
  machine: gpt
59
- ? "machine omitted=local Pi host; list/find omitted=all machines; remote=list profile ID, NOT label/hostname"
60
- : "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
65
+ ? "machine omitted=local Pi host; list/find omitted=all machines; select current machine name or ID from list"
66
+ : "Omit for local (host running Pi); list/find omit for all machines. Select a current machine name or ID from list",
61
67
  target: gpt
62
68
  ? "target=agent (same Notes/Board ID) or terminal target; /root=this family live root"
63
69
  : "Use agent for the same identity as Notes/Board, or the terminal target; /root selects this family's live root",
64
- label: core
65
- ? "Short Pi session name; app tabs use default names"
66
- : gpt
67
- ? "Short tab/session name; two words IF useful"
68
- : "Short tab/session name; prefer two words when useful",
69
- placement: core
70
- ? "terminal (default), new_tab, new_workspace; new_tab needs space ID"
71
- : "new_tab, new_workspace, pane",
70
+ label: "Short Pi session name; app tabs use default names",
71
+ placement:
72
+ "terminal (default), new_tab, new_workspace; new_tab needs space ID",
72
73
  ...(boardAvailable
73
74
  ? {
74
75
  board_thread_id: gpt
@@ -87,14 +88,14 @@ export async function agentsHelp(
87
88
  : "Select a running session; passive arrival with return call, no task/watch. voice defaults false; true carries the active microphone asynchronously. handoff adds context. Remote focus selects the target's Herdr session, not the client's machine",
88
89
  attach: boardAvailable
89
90
  ? gpt
90
- ? "Idle target; context/board=independent sharing/membership; NO task/watch"
91
- : "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
91
+ ? "Idle target; context/board=independent sharing/membership; omitted=false, at least one true; NO task/watch"
92
+ : "Idle target; context/board choose shared access and board membership independently; omitted=false, at least one true; no task/watch"
92
93
  : gpt
93
- ? "Idle target; context=shared notes/history; boards unavailable→board:false; NO task/watch"
94
- : "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
94
+ ? "Idle target; context:true=shared notes/history; boards unavailable; NO task/watch"
95
+ : "Idle target; context:true shares notes/history; shared boards unavailable; no task/watch",
95
96
  detach: gpt
96
- ? "Idle target; stop selected membership; counterpart checkpoints remain readonly"
97
- : "Stop selected membership; retain counterpart checkpoints read-only; idle target",
97
+ ? "Idle target; stop context/board independently; omitted=false, at least one true; counterpart checkpoints remain readonly"
98
+ : "Stop context/board independently; omitted=false, at least one true; retain counterpart checkpoints read-only; idle target",
98
99
  blocking: gpt
99
100
  ? "spawn/assign default false→dispatch then return; true→wait for result; profile overrides spawn. Parallel blocking calls: await Promise.allSettled. Background reports automatic→do other work/end turn, NO poll or await timers/extra Promises"
100
101
  : "spawn/assign return after dispatch by default. Set blocking:true to wait for the result; profile blocking overrides spawn. Use await Promise.allSettled for parallel blocking calls, including failures. Background reports arrive automatically: do other work or end this turn, never poll or await timers or extra Promises for reports",
@@ -108,8 +109,8 @@ export async function agentsHelp(
108
109
  ? "Distinct scope/outcome/project context/issue refs; define success, NOT forbidden investigations"
109
110
  : "Give each worker a distinct scope, desired outcome, relevant project context and issue references. Describe success rather than lists of forbidden investigations",
110
111
  slash: gpt
111
- ? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes pane"
112
- : "Leading / routes target commands/skills/templates. Commands skip task waiting, even with assign/spawn; blocked commands return available choices. /quit shuts down Pi and closes its pane",
112
+ ? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes terminal"
113
+ : "Leading / routes target commands/skills/templates. Commands skip task waiting, even with assign/spawn; blocked commands return available choices. /quit shuts down Pi and closes its terminal",
113
114
  reuse: gpt
114
115
  ? "Reuse ONLY same investigation; reviews independent; new scope=new agent"
115
116
  : "Reuse only same investigation; reviews independent; new scope = new agent",
@@ -120,9 +121,7 @@ export async function agentsHelp(
120
121
  : {}),
121
122
  },
122
123
  profiles: describeProfiles(profiles),
123
- advanced: core
124
- ? "hc --skill: terminal processes and machines"
125
- : "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
124
+ advanced: "hc --skill: terminal processes and machines",
126
125
  };
127
126
  }
128
127
 
@@ -209,10 +208,7 @@ export async function listFleetAgents(
209
208
  (agent) =>
210
209
  agent.agent === "pi" &&
211
210
  (!machine.local ||
212
- agent.pane_id !==
213
- (agent.backend === "core"
214
- ? process.env["HC_TERMINAL_ID"]
215
- : process.env["HERDR_PANE_ID"])),
211
+ agent.terminal_id !== process.env["HC_TERMINAL_ID"]),
216
212
  )
217
213
  .map(async (agent) => {
218
214
  const result = compactAgent(
@@ -283,35 +279,19 @@ export async function readAgentTerminal(
283
279
  source: Exclude<(typeof READ_SOURCES)[number], "latest">,
284
280
  lines: number,
285
281
  ): Promise<Record<string, unknown>> {
286
- const value = await runtime.client.request<unknown>("agent.read", {
287
- target: panel.pane_id,
288
- source,
289
- format: "text",
290
- lines,
291
- strip_ansi: true,
292
- });
293
- if (
294
- typeof value !== "object" ||
295
- value === null ||
296
- !("read" in value) ||
297
- typeof value.read !== "object" ||
298
- value.read === null ||
299
- !("text" in value.read) ||
300
- typeof value.read.text !== "string"
301
- ) {
302
- throw new Error("Herdr agent.read returned no text");
303
- }
304
- const truncated = value.read.text.length > MAX_TERMINAL_READ_CHARS;
282
+ const value = await readTerminal(
283
+ runtime.client,
284
+ panel.terminal_id,
285
+ source === "visible" ? 0 : lines,
286
+ );
287
+ const truncated = value.text.length > MAX_TERMINAL_READ_CHARS;
305
288
  return {
306
289
  machine: runtime.machine,
307
290
  target: panel.pane_id,
308
291
  status: panel.agent_status,
309
292
  text: truncated
310
- ? `${value.read.text.slice(0, MAX_TERMINAL_READ_CHARS)}\n…`
311
- : value.read.text,
312
- ...(truncated ||
313
- ("truncated" in value.read && value.read.truncated === true)
314
- ? { truncated: true }
315
- : {}),
293
+ ? `${value.text.slice(0, MAX_TERMINAL_READ_CHARS)}\n…`
294
+ : value.text,
295
+ ...(truncated || value.truncated ? { truncated: true } : {}),
316
296
  };
317
297
  }
@@ -6,16 +6,18 @@ import type {
6
6
  import {
7
7
  recordContextBriefing,
8
8
  registerContextBriefing,
9
- } from "@howaboua/pi-agent-board/integration";
10
- import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
9
+ } from "./context-briefing.js";
11
10
  import {
12
11
  getAgent,
13
12
  getCurrentPane,
14
13
  resolvePiAgent,
15
14
  sessionPath,
16
- } from "./herdr.js";
17
- import { isDispatchRejected } from "./herdr-client.js";
15
+ } from "./core/agents.js";
16
+ import { focusCoreWindow } from "./core/focus-window.js";
17
+ import { RemoteCoreEndpoint } from "./core/remote-endpoint.js";
18
+ import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
18
19
  import { focusArrivalContent } from "./messages/focus.js";
20
+ import { isDispatchRejected } from "./remote/shepherdr-peer.mjs";
19
21
  import type { FocusRequest, PaneInfo } from "./types.js";
20
22
  import { activeVoiceService, observeVoiceTransfer } from "./voice-handoff.js";
21
23
 
@@ -52,9 +54,7 @@ export async function focusAgent(
52
54
  const request: FocusRequest = {
53
55
  source: {
54
56
  ...(await local.client.machineIdentity()),
55
- ...(source.backend === "core"
56
- ? { backend: "core" as const }
57
- : { pane: source.pane_id }),
57
+ backend: "core",
58
58
  terminal: source.terminal_id,
59
59
  sessionFile,
60
60
  },
@@ -116,13 +116,10 @@ export function readFocus(value: unknown): FocusRequest {
116
116
  )
117
117
  throw new Error("Invalid focus source");
118
118
  }
119
- if (source["backend"] !== undefined && source["backend"] !== "core")
120
- throw new Error("Invalid focus backend");
121
- if (
122
- source["backend"] !== "core" &&
123
- (typeof source["pane"] !== "string" || !source["pane"].trim())
124
- )
125
- throw new Error("Invalid focus pane");
119
+ if (source["backend"] !== "core")
120
+ throw new Error(
121
+ "Focus return requires a Core session; focus again from the source session",
122
+ );
126
123
  if ("handoff" in value && typeof value.handoff !== "string")
127
124
  throw new Error("Invalid focus handoff");
128
125
  if ("voice" in value && typeof value.voice !== "boolean")
@@ -151,12 +148,9 @@ export async function acceptFocus(
151
148
  const runtime = fleet.connected(status.id);
152
149
  try {
153
150
  const identity = await runtime.client.machineIdentity();
154
- if (identity.host !== source.host || identity.session !== source.session)
155
- continue;
156
- const agent = await getAgent(
157
- runtime.client,
158
- source.backend === "core" ? source.terminal : source.pane!,
159
- );
151
+ // Host labels may differ from OS hostnames; the Core ID owns routing.
152
+ if (identity.session !== source.session) continue;
153
+ const agent = await getAgent(runtime.client, source.terminal);
160
154
  if (
161
155
  agent.agent === "pi" &&
162
156
  agent.terminal_id === source.terminal &&
@@ -192,8 +186,15 @@ export async function acceptFocus(
192
186
  sessionPath(current) !== sessionPath(pane)
193
187
  )
194
188
  throw new Error("Destination session changed; resolve it again");
189
+ if (local.client.core instanceof RemoteCoreEndpoint)
190
+ throw Object.assign(
191
+ new Error("Focus requires the destination's local Core"),
192
+ {
193
+ code: "SHEPHERDR_DELIVERY_REJECTED",
194
+ },
195
+ );
195
196
  try {
196
- await local.client.request("agent.focus", { target: pane.pane_id });
197
+ await focusCoreWindow(local.client.core, pane.terminal_id);
197
198
  } catch (error) {
198
199
  if (isDispatchRejected(error)) throw error;
199
200
  throw Object.assign(
@@ -231,18 +232,5 @@ export async function acceptFocus(
231
232
  }
232
233
 
233
234
  export function registerFocusArrivals(pi: ExtensionAPI): void {
234
- registerContextBriefing(
235
- pi,
236
- "session arrivals",
237
- (ctx) =>
238
- ctx.sessionManager
239
- .getBranch()
240
- .some(
241
- (entry) =>
242
- entry.type === "custom" &&
243
- (entry.customType === ARRIVAL ||
244
- entry.customType === "herdr-voice-focus-report"),
245
- ),
246
- async () => undefined,
247
- );
235
+ registerContextBriefing(pi, async () => undefined);
248
236
  }