@luminascale/shepherd 0.0.0-stage → 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.
Files changed (203) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,583 @@
1
+ # Asynchronous Shepherd Tasks and Agent Messaging
2
+
3
+ ## Status
4
+
5
+ Implemented specification.
6
+
7
+ ## Summary
8
+
9
+ Add asynchronous task coordination and conversational messaging to
10
+ pi-shepherd. A delegated task and an agent conversation are separate concerns:
11
+
12
+ a delegated task is tracked until it explicitly completes, while messages can
13
+ be sent between the Shepherd and agents, or between agents, without blocking
14
+ the sender or consuming the recipient's task slot.
15
+
16
+ The design must not infer task completion from a Pi turn ending, an `agent_end`
17
+ event, an `agent_settled` event, or the child process becoming idle. An agent
18
+ may finish a turn because it is waiting for another agent's response and may
19
+ resume the same delegated task later.
20
+
21
+ The intended workflow is:
22
+
23
+ ```text
24
+ shepherd_delegate
25
+ -> tracked task starts
26
+ -> child sends shepherd_message to another participant
27
+ -> child task enters waiting state
28
+ -> child's current Pi turn settles
29
+ -> recipient eventually replies with shepherd_message
30
+ -> child receives a queued follow-up and resumes
31
+ -> child calls shepherd_done
32
+ -> shepherd_watch reports task completion
33
+ ```
34
+
35
+ The preferred coordination model is asynchronous. `shepherd_wait` is not
36
+ required for the new workflow. If retained for compatibility, it must observe
37
+ task completion and must not be required for message delivery or task
38
+ settlement.
39
+
40
+ ## Problem
41
+
42
+ The current lifecycle associates a `shepherd_prompt` with one child turn and
43
+ uses completion signals derived from the child Pi process. This creates an
44
+ incorrect result when a child asks another participant a question:
45
+
46
+ ```text
47
+ scout task starts
48
+ scout asks planner a question
49
+ scout's current turn ends while planner is busy
50
+ scout becomes idle
51
+ Shepherd incorrectly treats scout's task as complete
52
+ ```
53
+
54
+ Pi's queueing APIs provide the correct local delivery primitive:
55
+ `sendUserMessage(..., { deliverAs: "followUp" })` can queue a regular message
56
+ until an agent is ready. However, queue delivery does not by itself provide:
57
+
58
+ - a cross-process route between child pi sessions and the parent;
59
+ - a distinction between a task and an ordinary message;
60
+ - request/reply correlation;
61
+ - task-level completion semantics; or
62
+ - stale-wait notifications.
63
+
64
+ Those concerns must be represented explicitly by Shepherd.
65
+
66
+ ## Goals
67
+
68
+ - Add a tracked, non-blocking delegation operation.
69
+ - Add asynchronous messaging between the Shepherd and agents.
70
+ - Add asynchronous messaging between agents through a parent-owned broker.
71
+ - Deliver messages into a child using Pi's normal user-message queueing
72
+ semantics.
73
+ - Allow an agent to wait for a reply while its current Pi turn is over without
74
+ completing its delegated task.
75
+ - Make task completion explicit and independent of Pi turn completion.
76
+ - Preserve `shepherd_watch` as the preferred non-blocking completion mechanism.
77
+ - Notify the Shepherd when a task has been waiting for a reply for too long.
78
+ - Expose waiting task state and elapsed wait time through status and the TUI
79
+ status widget.
80
+ - Keep task messages and conversational messages distinguishable.
81
+ - Preserve opaque lifecycle identifiers and pane ownership protections.
82
+ - Keep fieldnote/artifact allocation associated with delegated tasks rather
83
+ than casual messages.
84
+
85
+ ## Non-goals
86
+
87
+ - Do not make ordinary messages block the parent Shepherd turn.
88
+ - Do not infer task completion from textual phrases such as "done" in an
89
+ assistant response.
90
+ - Do not infer task completion from Pi's `agent_end`, `agent_settled`, idle, or
91
+ Herdr state alone.
92
+ - Do not require agents to remain actively streaming while waiting for a
93
+ response.
94
+ - Do not expose Herdr pane IDs as message, request, or task identifiers.
95
+ - Do not allow child processes to access the parent's in-memory registry
96
+ directly.
97
+ - Do not introduce automatic unrestricted peer-to-peer execution without a
98
+ parent-owned routing and permission boundary.
99
+ - Do not require a workflow-specific `parallel`, `chain`, or `fan-in` mode.
100
+ - Do not make a message create a fieldnote unless explicitly designated as a
101
+ delegated task.
102
+
103
+ ## Terminology
104
+
105
+ ### Shepherd
106
+
107
+ The parent pi session and its extension. It owns task records, routing policy,
108
+ message delivery to the parent session, and the parent side of the IPC broker.
109
+
110
+ ### Agent
111
+
112
+ A persistent child pi session launched in a Herdr pane. An agent has a stable
113
+ opaque Shepherd agent ID for the lifetime of the parent Shepherd session.
114
+
115
+ ### Task
116
+
117
+ A tracked unit of work started by `shepherd_delegate`. A task may span many Pi
118
+ turns and may be paused while waiting for one or more replies. A task has one
119
+ owner agent and one terminal outcome.
120
+
121
+ ### Message
122
+
123
+ An asynchronous piece of conversational information. A message can be sent to
124
+ the Shepherd or to another agent. It is accepted or rejected independently of
125
+ task completion.
126
+
127
+ ### Request
128
+
129
+ A message that expects a reply. Requests have a message ID and may be linked to
130
+ a task. A request remains pending until a matching reply, cancellation, or
131
+ timeout is recorded.
132
+
133
+ ### Turn
134
+
135
+ One Pi model execution cycle, including its tool calls. A turn ending is a
136
+ runtime event, not a task lifecycle event.
137
+
138
+ ### Waiting task
139
+
140
+ A task with at least one unresolved request that the task has declared it needs
141
+ before proceeding. Its owner agent may be idle while the task remains open.
142
+
143
+ ## Public API
144
+
145
+ ### `shepherd_delegate`
146
+
147
+ `shepherd_delegate` is the parent-facing operation for starting tracked work.
148
+ It returns immediately after the task has been accepted or queued.
149
+
150
+ Representative request:
151
+
152
+ ```json
153
+ {
154
+ "target": "shepherd-agent-scout",
155
+ "task": "Investigate how authentication is currently implemented.",
156
+ "timeout": 20
157
+ }
158
+ ```
159
+
160
+ Representative result:
161
+
162
+ ```json
163
+ {
164
+ "taskId": "shepherd-task-...",
165
+ "agentId": "shepherd-agent-...",
166
+ "accepted": true
167
+ }
168
+ ```
169
+
170
+ The delegated task message is delivered to the child as a task-designated
171
+ regular user message. The child receives the task ID in its task context and
172
+ must use it when explicitly completing the task.
173
+
174
+ An agent has at most one active delegated task by default. This restriction
175
+ applies to tasks only. It does not prevent the agent from receiving or sending
176
+ ordinary queued messages while its task is active or waiting.
177
+
178
+ A later version may support multiple tasks per agent, but that requires an
179
+ explicit task execution context and must not be inferred from multiple
180
+ messages.
181
+
182
+ ### `shepherd_message`
183
+
184
+ `shepherd_message` is the asynchronous communication operation. It may be
185
+ used by the Shepherd or by a child agent, subject to routing permissions.
186
+
187
+ Representative request:
188
+
189
+ ```json
190
+ {
191
+ "target": "shepherd-agent-planner",
192
+ "message": "What have you found about the authentication flow?",
193
+ "expectsReply": true,
194
+ "taskId": "shepherd-task-scout-...",
195
+ "delivery": "followUp"
196
+ }
197
+ ```
198
+
199
+ The operation returns immediately:
200
+
201
+ ```json
202
+ {
203
+ "messageId": "shepherd-message-...",
204
+ "accepted": true,
205
+ "delivery": "queued"
206
+ }
207
+ ```
208
+
209
+ Required semantics:
210
+
211
+ - `followUp` is the default delivery mode and waits until the recipient's
212
+ current work is finished before starting the next model call.
213
+ - `steer` may be requested for an urgent message and is delivered at the next
214
+ safe steering point. It must not silently interrupt a tool call.
215
+ - An accepted message means the broker accepted it for delivery. It does not
216
+ mean the recipient has read it or replied.
217
+ - A message may target the Shepherd, an agent, or a reply destination encoded
218
+ by `replyTo`.
219
+ - A message does not create a task, settle a task, or consume the recipient's
220
+ active-task slot.
221
+ - A message that expects a reply creates a tracked pending request. If it is
222
+ associated with the sender's active task, that task enters `waiting`. When
223
+ the Shepherd answers a child-originated request with a matching `replyTo`,
224
+ the parent resolves that pending request after successfully queueing the
225
+ answer; the child may then call `shepherd_done` without sending a redundant
226
+ acknowledgment. Peer replies continue to resolve through the parent broker
227
+ when the reply envelope is consumed.
228
+
229
+ Incoming child-to-Shepherd messages must be injected into the parent as a
230
+ Shepherd custom message. They must use the parent pi session's message
231
+ queueing policy and must not be presented as an unsolicited ordinary user
232
+ message without provenance.
233
+
234
+ Incoming messages to children should use the child-side pi API equivalent to:
235
+
236
+ ```ts
237
+ pi.sendUserMessage(renderedMessage, {
238
+ deliverAs: "followUp"
239
+ });
240
+ ```
241
+
242
+ The rendered message must preserve sender identity, message ID, task ID when
243
+ present, and reply metadata.
244
+
245
+ ### `shepherd_done`
246
+
247
+ `shepherd_done` is a child-facing task lifecycle operation. It is not an
248
+ ordinary message and is not used for casual conversations.
249
+
250
+ Representative request:
251
+
252
+ ```json
253
+ {
254
+ "taskId": "shepherd-task-...",
255
+ "status": "completed",
256
+ "summary": "Authentication is implemented in src/auth/session.ts."
257
+ }
258
+ ```
259
+
260
+ Supported terminal statuses are:
261
+
262
+ ```text
263
+ completed
264
+ blocked
265
+ failed
266
+ ```
267
+
268
+ The broker must validate that the caller owns the task. Completion should be
269
+ idempotent. A task with unresolved required requests must not be marked
270
+ `completed` unless those requests are explicitly cancelled or the caller
271
+ provides an override reason accepted by the task policy.
272
+
273
+ `shepherd_done` must not shut down a persistent agent. It only completes the
274
+ current delegated task; the agent remains available for later messages or new
275
+ tasks.
276
+
277
+ Normal completion should be explicit. The child runtime may report turn and
278
+ process state to Shepherd, but those events must not substitute for
279
+ `shepherd_done`.
280
+
281
+ ### `shepherd_watch`
282
+
283
+ `shepherd_watch` observes task IDs and returns immediately. It should retain the
284
+ current one-shot watcher behavior, but its primary subject becomes a task
285
+ rather than an individual Pi turn.
286
+
287
+ A watcher reports only terminal task outcomes:
288
+
289
+ ```json
290
+ {
291
+ "taskId": "shepherd-task-...",
292
+ "agentId": "shepherd-agent-...",
293
+ "status": "completed",
294
+ "ok": true,
295
+ "returnCode": 0,
296
+ "text": "The task summary."
297
+ }
298
+ ```
299
+
300
+ The watcher must not settle when the child emits `agent_end`, becomes idle, or
301
+ enters the `waiting` task state. Failed, cancelled, blocked, and timed-out
302
+ tasks are terminal watcher results.
303
+
304
+ `shepherd_wait` may remain as a compatibility operation, but new orchestration
305
+ flows should use `shepherd_watch`. No task or message may depend on the parent
306
+ calling `shepherd_wait` in order to make progress.
307
+
308
+ ## Task state machine
309
+
310
+ Task state is independent of Herdr and Pi process state.
311
+
312
+ ```text
313
+ +----------------+
314
+ | v
315
+ created -> running -> waiting -> running
316
+ | | | |
317
+ | | | +--> completed
318
+ | | +--------------> blocked
319
+ | +-------------------------> failed
320
+ +------------------------------------> cancelled
321
+ +------------------------------------> timed_out
322
+ ```
323
+
324
+ Required transitions:
325
+
326
+ - `created -> running`: delegated task is accepted and delivered.
327
+ - `running -> waiting`: the task sends one or more messages marked as
328
+ expecting replies.
329
+ - `waiting -> running`: a required reply is received and delivered to the
330
+ owner agent.
331
+ - `running -> completed`: the owner calls `shepherd_done` with `completed`.
332
+ - `running|waiting -> blocked`: the owner reports that it cannot continue.
333
+ - `running|waiting -> failed`: the child process or provider fails.
334
+ - `running|waiting -> cancelled`: Shepherd closes or cancels the task.
335
+ - `running|waiting -> timed_out`: the task exceeds its configured deadline.
336
+
337
+ A task may have an owner agent in Herdr state `idle` while its task state is
338
+ `waiting`. This is expected and must be represented in status output.
339
+
340
+ ## Request and reply correlation
341
+
342
+ Every message has a unique opaque `messageId`. Requests additionally have a
343
+ `threadId` or can be addressed by their `messageId`. Replies carry `replyTo`.
344
+
345
+ A message envelope must contain at least:
346
+
347
+ ```ts
348
+ interface ShepherdMessage {
349
+ messageId: string;
350
+ senderId: string;
351
+ targetId: string;
352
+ message: string;
353
+ taskId?: string;
354
+ threadId?: string;
355
+ replyTo?: string;
356
+ expectsReply?: boolean;
357
+ delivery: "followUp" | "steer";
358
+ createdAt: number;
359
+ }
360
+ ```
361
+
362
+ The broker clears a pending request only when a valid reply is accepted for
363
+ that request. Delivery of a question to a busy recipient is not a reply and
364
+ must not clear the sender's waiting state.
365
+
366
+ If multiple required requests are outstanding, the task remains `waiting`
367
+ until the task policy considers the required set satisfied. The initial
368
+ implementation may restrict a task to one outstanding request at a time.
369
+
370
+ ## Stale-wait notifications
371
+
372
+ A waiting task must record `waitingSince`. After a configurable threshold, the
373
+ parent receives one stale-wait notification for that waiting episode.
374
+
375
+ The notification should include:
376
+
377
+ - task ID and owning agent;
378
+ - task description;
379
+ - elapsed waiting time;
380
+ - pending request ID and question;
381
+ - target recipient;
382
+ - recipient process/task state; and
383
+ - suggested actions such as answer, remind, reroute, cancel, or inspect.
384
+
385
+ Example:
386
+
387
+ ```text
388
+ Scout has been waiting for 2m 14s for planner.
389
+ Task: Investigate authentication flow
390
+ Question: What have you found about the authentication flow?
391
+ Planner state: working
392
+ Request: shepherd-message-...
393
+ ```
394
+
395
+ A stale notification must not complete, fail, or cancel the task. It is an
396
+ escalation signal only.
397
+
398
+ The notification should be delivered to the parent using a Shepherd custom
399
+ message with follow-up semantics. It may trigger a parent turn when the parent
400
+ is idle, but it must not wake the parent on every normal message or polling
401
+ interval. Repeated notifications require a separate escalation threshold and
402
+ must be rate limited.
403
+
404
+ Generic agent idleness must not produce this notification unless there is an
405
+ associated waiting task or an explicitly configured stale-running policy.
406
+
407
+ ## Runtime and completion interception
408
+
409
+ The child completion extension must distinguish runtime events from task
410
+ completion:
411
+
412
+ - `agent_end` indicates that a low-level Pi run ended.
413
+ - `agent_settled` indicates that Pi has no immediate queued continuation.
414
+ - neither event indicates that a delegated task completed;
415
+ - `shepherd_done` is the normal task completion signal;
416
+ - process exit, provider errors, cancellation, and deadline expiry remain
417
+ external terminal signals.
418
+
419
+ The existing completion sidecar must therefore become task-aware. It must not
420
+ write a successful task completion sidecar merely because an agent turn ended
421
+ while a request is pending. A task completion event must include the task ID
422
+ and terminal status.
423
+
424
+ The child may report a `turn_settled` event so the parent can update live
425
+ status, but the task watcher must remain pending until a terminal task event is
426
+ received.
427
+
428
+ If the child forgets to call `shepherd_done`, the task remains open until its
429
+ deadline or external cancellation. The delegated task prompt and child system
430
+ context must clearly instruct the child to call `shepherd_done`; Shepherd must
431
+ not silently convert an idle task into success based on a heuristic.
432
+
433
+ ## Transport and ownership
434
+
435
+ The parent owns a session-scoped message broker. Children communicate with it
436
+ through an authenticated, parent-created IPC endpoint or equivalent
437
+ session-scoped mailbox.
438
+
439
+ The launch context must provide the child with:
440
+
441
+ - its opaque agent ID;
442
+ - its current task ID when a task is active;
443
+ - the parent Shepherd session identity; and
444
+ - the scoped broker endpoint and capability necessary to send messages.
445
+
446
+ The broker must validate sender identity and target availability. A child must
447
+ not be able to claim another child's agent ID, close another session's pane, or
448
+ write directly to the parent's in-memory lifecycle registry.
449
+
450
+ The transport must provide:
451
+
452
+ - atomic message writes or equivalent framing;
453
+ - request/reply correlation;
454
+ - bounded queue size and message size;
455
+ - cleanup after the parent session ends; and
456
+ - safe behavior when a child or parent disappears.
457
+
458
+ Raw Herdr pane IDs remain internal diagnostics and must not be used as public
459
+ message or task handles.
460
+
461
+ ## Status and user interface
462
+
463
+ `shepherd_status` should report process state and task state separately:
464
+
465
+ ```json
466
+ {
467
+ "id": "shepherd-agent-...",
468
+ "agentState": "idle",
469
+ "taskState": "waiting",
470
+ "taskId": "shepherd-task-...",
471
+ "waitingSince": "...",
472
+ "waitingFor": "shepherd-agent-planner",
473
+ "stale": true
474
+ }
475
+ ```
476
+
477
+ The working-agent widget must not hide a waiting task merely because its Pi
478
+ process is idle. It should display a waiting row with elapsed time and the
479
+ recipient when available.
480
+
481
+ ## Fieldnotes and artifacts
482
+
483
+ `shepherd_delegate` may create one fieldnote reservation for the delegated
484
+ task, preserving the existing parent-bound fieldnotes contract.
485
+
486
+ `shepherd_message` must not create a fieldnote by default. Conversational
487
+ messages may be included in the delegated task's note only when the task
488
+ implementation explicitly records them as task context.
489
+
490
+ Task completion, failure, blocked state, and final summary should finalize the
491
+ delegated task's artifact. A waiting task must leave its artifact open rather
492
+ than marking it completed merely because a turn ended.
493
+
494
+ ## Failure and timeout behavior
495
+
496
+ - Sending to a closed or unknown target is rejected with a structured error.
497
+ - A message accepted into a queue may later produce a delivery failure; that
498
+ failure must be correlated with its message ID.
499
+ - A child process exit while a task is running or waiting fails the task unless
500
+ the exit was an intentional task completion path.
501
+ - A pending request must have a deadline. On expiry, the task becomes blocked or
502
+ timed out according to task policy, and the Shepherd receives a notification.
503
+ - Closing an agent cancels its active task and unresolved requests.
504
+ - Repeated `shepherd_done`, reply, timeout, or cancellation events must be
505
+ idempotent.
506
+ - Queue limits and rate limits must prevent agents from creating unbounded
507
+ message storms.
508
+
509
+ ## Security and safety
510
+
511
+ - Only the parent Shepherd may create delegated tasks.
512
+ - Child messages may target only the parent or agents visible through the
513
+ parent-owned routing registry.
514
+ - Agent definitions and project approval rules remain unchanged.
515
+ - Existing pane ownership checks remain unchanged.
516
+ - Messages must carry provenance so a child cannot impersonate the Shepherd or
517
+ another agent through message text alone.
518
+ - Direct peer delivery should remain parent-mediated in the initial version.
519
+ - The implementation must prevent recursive notification loops and should
520
+ enforce a maximum message hop count for any future automatic relay feature.
521
+
522
+ ## Compatibility
523
+
524
+ The existing `shepherd_spawn`, `shepherd_status`, `shepherd_close`,
525
+ `shepherd_read`, and `shepherd_watch` concepts remain. `shepherd_prompt` should
526
+ be deprecated or retained as a compatibility alias during migration, but its
527
+ old one-active-prompt completion semantics must not be mixed silently with the
528
+ new message semantics.
529
+
530
+ Recommended migration:
531
+
532
+ ```text
533
+ old shepherd_prompt task call -> shepherd_delegate
534
+ old prompt completion tracking -> shepherd_watch(taskId)
535
+ new child/peer communication -> shepherd_message
536
+ new child task completion -> shepherd_done
537
+ ```
538
+
539
+ If `shepherd_wait` remains available, it should wait on task IDs or provide a
540
+ clearly documented compatibility mapping. It must not be required by the new
541
+ asynchronous protocol.
542
+
543
+ ## Verification requirements
544
+
545
+ Focused tests must verify:
546
+
547
+ - delegation returns without blocking;
548
+ - multiple messages can be queued without violating the one-active-task
549
+ invariant;
550
+ - a child can send a question to a busy recipient;
551
+ - the sender becomes `waiting` while its Pi process becomes idle;
552
+ - the Shepherd does not settle the task on `agent_end`, `agent_settled`, or
553
+ idle state;
554
+ - a matching reply returns the task to `running` and triggers child delivery;
555
+ - a parent-originated matching reply resolves the pending request without
556
+ requiring a second child acknowledgment;
557
+ - `shepherd_done` is the only normal successful completion path;
558
+ - task watchers report terminal outcomes exactly once;
559
+ - stale-wait notifications fire once per waiting episode and include useful
560
+ correlation data;
561
+ - pending-request timeout, child failure, close cancellation, and duplicate
562
+ events are handled idempotently;
563
+ - message routing rejects unknown targets and invalid sender capabilities;
564
+ - messages do not create fieldnotes unless explicitly associated with a task;
565
+ - status and the TUI widget show an idle process with a waiting task; and
566
+ - parent shutdown cleans up broker resources without losing already-persisted
567
+ task outcomes.
568
+
569
+ Live Herdr verification must cover at least:
570
+
571
+ 1. Shepherd delegates a task to scout.
572
+ 2. Scout sends a question to a busy planner.
573
+ 3. Scout's turn settles and its task remains waiting.
574
+ 4. Planner eventually receives and answers the queued question.
575
+ 5. Scout resumes and calls `shepherd_done`.
576
+ 6. `shepherd_watch` receives the final task result.
577
+ 7. A stale-wait notification is delivered when the planner does not answer
578
+ within the configured threshold.
579
+ 8. Closing or timing out either participant produces the correct terminal
580
+ task state.
581
+
582
+ `npm test` must pass, and new schema tests must verify that all new model-facing
583
+ registrations use flat root object schemas with explicit required fields.