@luminascale/shepherd 0.0.0-stage → 0.6.1

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 (204) 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 +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,1093 @@
1
+ # Implementation Plan: Asynchronous Shepherd Tasks and Agent Messaging
2
+
3
+ ## Status
4
+
5
+ Proposed implementation plan for
6
+ `docs/specs/005-agent-messaging-and-task-lifecycle/spec.md`.
7
+
8
+ No implementation is included in this plan. The plan is intentionally staged so
9
+ that task lifecycle correctness is established before peer messaging and UI
10
+ conveniences are added.
11
+
12
+ ## 1. Implementation decisions
13
+
14
+ The following decisions are normative for the implementation unless the
15
+ specification is amended first.
16
+
17
+ ### 1.1 Public operations
18
+
19
+ The new canonical operations are:
20
+
21
+ ```text
22
+ shepherd_delegate parent -> child, tracked task, returns taskId
23
+ shepherd_message Shepherd/child -> Shepherd/child, asynchronous message
24
+ shepherd_done child -> parent, explicit task terminal signal
25
+ shepherd_watch parent -> task completion subscription
26
+ ```
27
+
28
+ Existing operations remain available where they are still meaningful:
29
+
30
+ ```text
31
+ shepherd_spawn
32
+ shepherd_status
33
+ shepherd_close
34
+ shepherd_read
35
+ ```
36
+
37
+ `shepherd_wait` is not used by the new workflow. It may remain as a
38
+ compatibility adapter, but no new message or task path may depend on it.
39
+
40
+ `shepherd_prompt` becomes a deprecated compatibility name for the old
41
+ parent-to-child task submission path. It must not retain a separate completion
42
+ model after the new task registry is active. Compatibility calls should map to
43
+ a task record and return an identifier that can be observed through the task
44
+ watcher. The migration behavior must be documented and tested explicitly.
45
+
46
+ ### 1.2 Task completion
47
+
48
+ A child Pi turn is not a task. The following are non-terminal runtime events:
49
+
50
+ - `agent_end`;
51
+ - `agent_settled`;
52
+ - Herdr `idle`;
53
+ - a child becoming quiet while waiting for another agent; and
54
+ - an intermediate assistant response.
55
+
56
+ The normal successful terminal event is an explicit child `shepherd_done` call.
57
+ The parent may also settle a task as failed, cancelled, or timed out when an
58
+ external lifecycle event requires it.
59
+
60
+ This is the central correctness rule. No implementation may restore the old
61
+ behavior of treating a successful `agent_end` sidecar as task completion.
62
+
63
+ ### 1.3 Message delivery
64
+
65
+ Messages are accepted asynchronously. The initial delivery mode is:
66
+
67
+ - `followUp` by default;
68
+ - `steer` only when explicitly requested; and
69
+ - no synchronous parent wait.
70
+
71
+ The child-side extension calls Pi's local API, equivalent to:
72
+
73
+ ```ts
74
+ pi.sendUserMessage(renderedMessage, { deliverAs: "followUp" });
75
+ ```
76
+
77
+ The implementation must not try to access a child `AgentSession` object from
78
+ the parent process. Parent and child processes communicate through the
79
+ Shepherd broker.
80
+
81
+ ### 1.4 Transport
82
+
83
+ Use a parent-owned, session-scoped filesystem mailbox for the first
84
+ implementation rather than a Unix socket. A mailbox is easier to inspect,
85
+ works from separate Herdr panes, and does not require a long-lived socket
86
+ server or reconnect protocol.
87
+
88
+ The mailbox must use:
89
+
90
+ - a directory created with owner-only permissions;
91
+ - one immutable JSON envelope per message or control event;
92
+ - temporary-file-plus-rename writes for atomic publication;
93
+ - polling with bounded intervals on both parent and child sides;
94
+ - sender and target identity validation; and
95
+ - bounded queue, message-size, and retention limits.
96
+
97
+ The transport boundary must be replaceable later by a socket without changing
98
+ the task or message records.
99
+
100
+ ### 1.5 Task concurrency
101
+
102
+ An agent has at most one active delegated task in the first version. This
103
+ restriction applies only to delegated tasks. An agent may send and receive
104
+ ordinary messages while its task is running or waiting.
105
+
106
+ Messages do not create an active-task slot and do not settle a task.
107
+
108
+ ### 1.6 Waiting semantics
109
+
110
+ A message with `expectsReply: true` creates a pending request. If it is linked
111
+ to the sender's active task, the task enters `waiting`.
112
+
113
+ A task can therefore be represented as:
114
+
115
+ ```text
116
+ Pi process: idle
117
+ Task: waiting
118
+ Pending request: request-123
119
+ ```
120
+
121
+ A reply clears the pending request and returns the task to `running`. A task
122
+ remains open until `shepherd_done`, cancellation, failure, or timeout.
123
+
124
+ ### 1.7 Explicit completion tool
125
+
126
+ `shepherd_done` is a child-facing lifecycle tool, not a conversational
127
+ message. It is the reliable semantic completion signal. The child prompt and
128
+ runtime context must instruct the model to call it only when the delegated
129
+ task is actually complete.
130
+
131
+ The child runtime may report turn-settled events for observability, but those
132
+ events must never substitute for `shepherd_done`.
133
+
134
+ ## 2. Target architecture
135
+
136
+ ```text
137
+ Parent Shepherd process
138
+ ┌──────────────────────────────────────────────────────────────────────┐
139
+ │ parent tools: delegate/message/watch/status/close/read │
140
+ │ │
141
+ │ TaskRegistry MessageBroker TaskWatcher/StaleWaitMonitor │
142
+ │ │ │ │ │
143
+ │ └──────────────┬─────┴─────────────────────────┘ │
144
+ │ │ │
145
+ │ session mailbox directory │
146
+ └─────────────────────┼───────────────────────────────────────────────────┘
147
+ │ atomic JSON envelopes
148
+ ┌────────────────┴───────────────────┐
149
+ │ │
150
+ Child scout process Child planner process
151
+ ┌─────────────────────────┐ ┌─────────────────────────┐
152
+ │ shepherd-agent.ts │ │ shepherd-agent.ts │
153
+ │ shepherd_message tool │ │ shepherd_message tool │
154
+ │ shepherd_done tool │ │ shepherd_done tool │
155
+ │ Pi sendUserMessage() │ │ Pi sendUserMessage() │
156
+ └─────────────────────────┘ └─────────────────────────┘
157
+ ```
158
+
159
+ The existing `LifecycleRegistry` remains the parent-session authority for
160
+ opaque identifiers, but task and message records should be separated from the
161
+ old prompt-specific assumptions. The likely split is:
162
+
163
+ ```text
164
+ src/core/orchestration.ts opaque ids, task records, message/request records
165
+ src/core/messaging.ts envelopes, mailbox transport, routing and polling
166
+ src/core/lifecycle.ts delegate, done, watch, status, close adapters
167
+ ```
168
+
169
+ A separate `task-registry.ts` may be used if `orchestration.ts` becomes too
170
+ large. It must still use the same parent-session identity and opaque-ID rules.
171
+
172
+ ## 3. Data model and contracts
173
+
174
+ ### 3.1 Task record
175
+
176
+ Add an internal task record with at least:
177
+
178
+ ```ts
179
+ interface TaskRecord {
180
+ taskId: string;
181
+ agentId: string;
182
+ description: string;
183
+ state: 'created' | 'running' | 'waiting' | 'completed' |
184
+ 'blocked' | 'failed' | 'cancelled' | 'timed_out';
185
+ createdAt: number;
186
+ startedAt?: number;
187
+ waitingSince?: number;
188
+ deadlineAt?: number;
189
+ pendingRequestIds: Set<string>;
190
+ staleNotifiedAt?: number;
191
+ result?: TaskResult;
192
+ artifactSession?: ShepherdSession;
193
+ artifact?: ArtifactReservation;
194
+ }
195
+ ```
196
+
197
+ `Set` is an internal representation only. Any data crossing the tool or
198
+ mailbox boundary must use arrays and JSON-safe values.
199
+
200
+ The task registry must provide methods equivalent to:
201
+
202
+ ```text
203
+ createTask(agent, description, options)
204
+ getTask(taskId)
205
+ canonicalTaskId(input)
206
+ setRunning(taskId)
207
+ addPendingRequest(taskId, requestId)
208
+ resolvePendingRequest(taskId, requestId)
209
+ setWaiting(taskId)
210
+ settleTask(taskId, result)
211
+ cancelTask(taskId, reason)
212
+ listTasks()
213
+ ```
214
+
215
+ All terminal settlement must be idempotent. A second `done`, timeout, failure,
216
+ or cancellation event must return the existing terminal result without
217
+ modifying it.
218
+
219
+ ### 3.2 Task result
220
+
221
+ Use a task-oriented result shape:
222
+
223
+ ```ts
224
+ interface TaskResult {
225
+ taskId: string;
226
+ agentId: string;
227
+ status: 'completed' | 'blocked' | 'failed' |
228
+ 'cancelled' | 'timed_out';
229
+ ok: boolean;
230
+ returnCode: number;
231
+ text?: string;
232
+ error?: string;
233
+ completedAt: number;
234
+ }
235
+ ```
236
+
237
+ `text` should contain the explicit `shepherd_done` summary when present, with
238
+ the child's latest assistant text as a fallback for diagnostic results. A
239
+ fallback must not turn an otherwise idle child into a successful task.
240
+
241
+ ### 3.3 Message envelope
242
+
243
+ Create a JSON-safe envelope shared by parent and child:
244
+
245
+ ```ts
246
+ interface ShepherdMessageEnvelope {
247
+ kind: 'message' | 'task' | 'reply' | 'task_done' | 'runtime';
248
+ messageId: string;
249
+ senderId: string;
250
+ targetId: string;
251
+ taskId?: string;
252
+ threadId?: string;
253
+ replyTo?: string;
254
+ expectsReply?: boolean;
255
+ delivery: 'followUp' | 'steer';
256
+ content?: string;
257
+ status?: 'completed' | 'blocked' | 'failed';
258
+ summary?: string;
259
+ error?: string;
260
+ createdAt: number;
261
+ }
262
+ ```
263
+
264
+ Use a dedicated `task_done` envelope for `shepherd_done` rather than
265
+ pretending that completion is an ordinary chat message. `runtime` envelopes
266
+ may be used for non-terminal turn status and diagnostics, but they must never
267
+ settle a task.
268
+
269
+ The public tool result should expose only the relevant opaque identifier and
270
+ structured acceptance status. Internal sender/session capabilities must not be
271
+ returned as public handles.
272
+
273
+ ### 3.4 Pending requests
274
+
275
+ Maintain a request record or request fields on the message record:
276
+
277
+ ```ts
278
+ interface RequestRecord {
279
+ requestId: string;
280
+ messageId: string;
281
+ senderId: string;
282
+ targetId: string;
283
+ taskId?: string;
284
+ state: 'pending' | 'replied' | 'cancelled' | 'timed_out';
285
+ createdAt: number;
286
+ deadlineAt?: number;
287
+ repliedAt?: number;
288
+ }
289
+ ```
290
+
291
+ The first implementation may allow only one unresolved required request per
292
+ task. The data model should use a collection so multiple-request support can
293
+ be added without changing the task state representation.
294
+
295
+ ## 4. Implementation phases
296
+
297
+ ### Phase 0 — Baseline and specification guardrails
298
+
299
+ Before changing runtime behavior:
300
+
301
+ 1. Run `npm test` and record the current baseline.
302
+ 2. Add a small test helper for deterministic clock control where stale-wait
303
+ behavior needs time advancement.
304
+ 3. Add schema placeholders for the new tools to
305
+ `test/verify-tool-schemas.mjs`.
306
+ 4. Add comments or assertions documenting that Pi idle/settled state is not
307
+ task completion.
308
+ 5. Keep the existing prompt/watcher tests green until the compatibility
309
+ adapter is introduced.
310
+
311
+ Files:
312
+
313
+ ```text
314
+ test/verify-tool-schemas.mjs
315
+ package.json
316
+ ```
317
+
318
+ Acceptance:
319
+
320
+ - Existing tests pass.
321
+ - The new test harness can inspect parent and child tool registrations.
322
+
323
+ ### Phase 1 — Add task records and task-state transitions
324
+
325
+ Implement the task registry before adding mailbox traffic.
326
+
327
+ 1. Add task IDs with the same parent-session-scoped opaque-ID strategy used by
328
+ agent and prompt IDs.
329
+ 2. Add `TaskRecord` and `TaskResult` types.
330
+ 3. Implement the task state transition methods.
331
+ 4. Reject invalid transitions with structured lifecycle errors.
332
+ 5. Ensure `waiting` does not clear the task's active ownership.
333
+ 6. Ensure task settlement clears any pending request associations and runs
334
+ artifact finalization exactly once.
335
+ 7. Keep the existing prompt registry intact temporarily, but introduce an
336
+ explicit mapping type for compatibility prompt IDs to task IDs.
337
+
338
+ Files:
339
+
340
+ ```text
341
+ src/core/orchestration.ts
342
+ src/core/lifecycle.ts
343
+ possibly src/core/task-registry.ts
344
+
345
+ test/verify-task-registry.mjs
346
+ ```
347
+
348
+ Required unit cases:
349
+
350
+ ```text
351
+ created -> running
352
+ running -> waiting
353
+ waiting -> running
354
+ running -> completed
355
+ waiting -> completed only after requests are resolved/cancelled
356
+ running/waiting -> failed
357
+ running/waiting -> cancelled
358
+ running/waiting -> timed_out
359
+ idle process + waiting task remains non-terminal
360
+ repeated terminal events are idempotent
361
+ ```
362
+
363
+ Acceptance:
364
+
365
+ - No task can settle from a synthetic idle or turn-ended event.
366
+ - A task can remain waiting while its child process is idle.
367
+
368
+ ### Phase 2 — Implement the parent-owned mailbox
369
+
370
+ Create the transport independently of Pi and Herdr behavior.
371
+
372
+ 1. Add a parent-session mailbox directory under the Shepherd runtime area.
373
+ 2. Create the directory with mode `0700`.
374
+ 3. Create per-agent inboxes and a parent inbox.
375
+ 4. Publish each envelope by writing a random temporary file and atomically
376
+ renaming it to a filename containing the message ID.
377
+ 5. Read only complete JSON files.
378
+ 6. Move processed files to an archive or delete them after an acknowledgement,
379
+ while retaining enough state to deduplicate repeated delivery.
380
+ 7. Enforce maximum message size and queue depth.
381
+ 8. Validate the envelope schema before routing.
382
+ 9. Add sender capability validation so a child can only publish as its own
383
+ agent ID.
384
+ 10. Add parent-session and broker identity fields so a child cannot submit to
385
+ another Shepherd session's mailbox by guessing a path.
386
+
387
+ Files:
388
+
389
+ ```text
390
+ src/core/messaging.ts
391
+ src/core/messaging-types.ts (if useful)
392
+ src/core/herdr.ts mailbox creation and launch environment
393
+
394
+ test/verify-messaging.mjs
395
+ ```
396
+
397
+ The initial polling API should support:
398
+
399
+ ```text
400
+ createParentBroker(sessionOwner)
401
+ registerChild(agentId)
402
+ publishFromParent(envelope)
403
+ publishFromChild(capability, envelope)
404
+ pollParentInbox()
405
+ pollAgentInbox(agentId)
406
+ acknowledge(messageId)
407
+ closeBrokerWhenChildrenGone()
408
+ ```
409
+
410
+ Acceptance:
411
+
412
+ - Parent-to-child and child-to-parent envelopes survive partial writes.
413
+ - Duplicate files do not result in duplicate task settlement or duplicate
414
+ message delivery.
415
+ - Invalid sender, target, session, and envelope data are rejected.
416
+ - Transport tests do not require a running Herdr instance.
417
+
418
+ ### Phase 3 — Add the child-side Shepherd extension
419
+
420
+ Create the child extension that bridges the mailbox to the local Pi session.
421
+
422
+ 1. Add `src/extension/shepherd-agent.ts` as the child-only extension, or
423
+ refactor `shepherd-done.ts` into a shared child extension while preserving
424
+ its default entrypoint behavior.
425
+ 2. Register `shepherd_message` with a flat TypeBox object schema.
426
+ 3. Register `shepherd_done` with a flat TypeBox object schema.
427
+ 4. Obtain the child identity, broker path, parent identity, and current task ID
428
+ from launch environment/context.
429
+ 5. Publish outgoing messages and task-done envelopes to the mailbox.
430
+ 6. Poll the child inbox at a bounded interval.
431
+ 7. Deliver incoming messages through `pi.sendUserMessage` using the requested
432
+ `followUp` or `steer` behavior.
433
+ 8. Include sender, message ID, task ID, thread ID, and reply metadata in the
434
+ rendered message text.
435
+ 9. Return an acknowledgement from the child tool once the envelope has been
436
+ accepted by the broker; do not wait for the recipient to answer.
437
+ 10. Make child polling timers `unref`-safe and clean them up on shutdown.
438
+
439
+ The child message presentation should be explicit, for example:
440
+
441
+ ```text
442
+ [Shepherd message from planner]
443
+ Message ID: shepherd-message-...
444
+ Reply to: shepherd-message-...
445
+
446
+ <message content>
447
+ ```
448
+
449
+ The child task context should be explicit, for example:
450
+
451
+ ```text
452
+ [Shepherd delegated task]
453
+ Task ID: shepherd-task-...
454
+
455
+ <task description>
456
+
457
+ Do not consider the task complete merely because this Pi turn ends. If you
458
+ need information, use shepherd_message. Call shepherd_done only when the
459
+ whole delegated task is complete.
460
+ ```
461
+
462
+ Files:
463
+
464
+ ```text
465
+ src/extension/shepherd-agent.ts
466
+ src/extension/shepherd-done.ts
467
+ src/core/herdr.ts
468
+ index.ts
469
+
470
+ test/verify-child-surface.mjs
471
+ test/verify-launch.mjs
472
+ ```
473
+
474
+ Acceptance:
475
+
476
+ - Child sessions receive only child messaging/completion tools, never the
477
+ parent-only lifecycle surface.
478
+ - A child can send a message without blocking its current model workflow.
479
+ - A child can call `shepherd_done` and publish a task terminal event.
480
+ - Incoming follow-up messages are delivered through Pi's supported queue API.
481
+
482
+ ### Phase 4 — Replace prompt submission with tracked delegation
483
+
484
+ Implement the parent-side delegation path.
485
+
486
+ 1. Add `delegateAgent()` in `src/core/lifecycle.ts`.
487
+ 2. Resolve the target agent using the existing opaque agent registry.
488
+ 3. Enforce one active delegated task per agent.
489
+ 4. Create the task record before publishing the task envelope.
490
+ 5. Reserve and attach the fieldnote artifact to the task, not to an ordinary
491
+ message.
492
+ 6. Add the task context to the delegated child message.
493
+ 7. Publish the task envelope through the broker.
494
+ 8. Return as soon as the broker accepts the task.
495
+ 9. If publication fails, settle the task as failed and finalize its artifact.
496
+ 10. Do not use Herdr's current `agent_end` completion sidecar as the task
497
+ success signal.
498
+
499
+ Add the `shepherd_delegate` registration in `src/extension/shepherd.ts`:
500
+
501
+ ```text
502
+ required: target, task
503
+ optional: timeout
504
+ returns: taskId, agentId, accepted
505
+ ```
506
+
507
+ The tool must follow the repository convention that `name`, `label`,
508
+ `description`, `promptSnippet`, and `parameters` are written directly in the
509
+ registration.
510
+
511
+ Files:
512
+
513
+ ```text
514
+ src/core/lifecycle.ts
515
+ src/core/orchestration.ts
516
+ src/extension/shepherd.ts
517
+ src/core/types.ts
518
+ src/core/herdr.ts
519
+
520
+ test/verify-delegate.mjs
521
+ ```
522
+
523
+ Acceptance:
524
+
525
+ - Delegation is non-blocking.
526
+ - A second delegated task to the same agent is rejected clearly while the
527
+ first task remains active.
528
+ - Messages to that agent are still accepted while the task is active.
529
+ - Fieldnotes are created for tasks only.
530
+
531
+ ### Phase 5 — Consume `shepherd_done` and external terminal events
532
+
533
+ Connect child task-done events to the parent task registry.
534
+
535
+ 1. Add a parent broker handler for `task_done` envelopes.
536
+ 2. Validate child identity and task ownership.
537
+ 3. Reject completion of unknown, closed, or foreign tasks.
538
+ 4. Reject successful completion when unresolved required requests remain,
539
+ unless the task explicitly cancels those requests.
540
+ 5. Settle the task once and record its final summary/status.
541
+ 6. Finalize the task's artifact through the existing artifact callback path.
542
+ 7. Preserve the child session and pane according to existing `keepOpen` and
543
+ `stayOpen` settings.
544
+ 8. Map child provider errors, unexpected process exit, close, and timeout to
545
+ task failure/cancellation/timeout.
546
+ 9. Remove any logic that interprets a normal `agent_end` sidecar as successful
547
+ completion for a delegated task.
548
+ 10. If the child extension reports `agent_settled`, treat it as an observation
549
+ only. Do not settle the task.
550
+
551
+ Refactor `shepherd-done.ts` so its completion responsibilities are task-aware.
552
+ The launch script and sidecar may remain as a process-health fallback, but the
553
+ sidecar must include an explicit task ID and must not claim task success for a
554
+ turn that ended while the task is waiting.
555
+
556
+ Files:
557
+
558
+ ```text
559
+ src/extension/shepherd-done.ts
560
+ src/core/lifecycle.ts
561
+ src/core/orchestration.ts
562
+ src/core/herdr.ts
563
+
564
+ test/verify-task-completion.mjs
565
+ ```
566
+
567
+ Acceptance scenario:
568
+
569
+ ```text
570
+ delegate scout task
571
+ scout sends question
572
+ scout turn settles
573
+ no task completion is emitted
574
+ scout calls shepherd_done later
575
+ watcher receives exactly one completed result
576
+ ```
577
+
578
+ ### Phase 6 — Implement asynchronous message routing
579
+
580
+ Add parent and child `shepherd_message` behavior.
581
+
582
+ 1. Register the parent-side `shepherd_message` tool.
583
+ 2. Register the child-side tool with the same conceptual name but a
584
+ child-specific adapter.
585
+ 3. Permit child targets of `shepherd` and validated peer agent IDs.
586
+ 4. Permit parent targets of owned child IDs.
587
+ 5. Resolve `replyTo` and `threadId` without exposing pane IDs.
588
+ 6. When `expectsReply` is true and a task ID is supplied, add the request to
589
+ the task's pending set and transition the task to `waiting`.
590
+ 7. Queue incoming child messages into the parent with `pi.sendMessage` as a
591
+ custom Shepherd message using follow-up delivery.
592
+ 8. Queue incoming child messages into child Pi sessions with
593
+ `pi.sendUserMessage`.
594
+ 9. On a valid reply, clear the request and transition the owner task from
595
+ `waiting` to `running`.
596
+ 10. Trigger a waiting child when a reply is delivered and the child is idle.
597
+ 11. Keep ordinary messages independent of task completion and artifact
598
+ finalization.
599
+ 12. Add a reply deadline and settle unresolved requests as blocked or timed out
600
+ according to task policy.
601
+
602
+ The initial implementation should keep routing parent-mediated. Do not add
603
+ automatic final-answer forwarding from one child to another; a recipient
604
+ should send its answer explicitly with `shepherd_message` and `replyTo`.
605
+
606
+ Files:
607
+
608
+ ```text
609
+ src/core/messaging.ts
610
+ src/core/lifecycle.ts
611
+ src/extension/shepherd.ts
612
+ src/extension/shepherd-agent.ts
613
+ src/extension/types.ts or src/core/types.ts
614
+
615
+ test/verify-message-routing.mjs
616
+ ```
617
+
618
+ Acceptance:
619
+
620
+ - Worker can ask planner while planner is busy.
621
+ - Planner receives the question as a queued follow-up.
622
+ - Worker remains waiting rather than completed.
623
+ - Planner can reply to worker.
624
+ - Worker resumes from the reply and can complete its task.
625
+ - A regular message with no `expectsReply` does not alter task state.
626
+
627
+ ### Phase 7 — Generalize watching from prompts to tasks
628
+
629
+ Adapt the watcher implementation while preserving non-blocking delivery.
630
+
631
+ 1. Add task watcher registration keyed by task IDs.
632
+ 2. Accept one task ID or an array of task IDs.
633
+ 3. Report only terminal task states.
634
+ 4. Preserve one-shot, idempotent delivery.
635
+ 5. Keep completion order deterministic for arrays while allowing individual
636
+ notifications as tasks settle.
637
+ 6. Include task ID, agent ID, task status, summary, error, and return code.
638
+ 7. Deliver completion notifications as custom parent messages with follow-up
639
+ semantics.
640
+ 8. Do not trigger a parent turn for every intermediate message or waiting
641
+ transition.
642
+ 9. Decide whether to preserve the current public prompt-ID spelling through a
643
+ compatibility adapter; document the decision in the migration section.
644
+ 10. Remove any watcher path that reads child idle state as task success.
645
+
646
+ The new watcher flow is:
647
+
648
+ ```text
649
+ shepherd_delegate -> taskId
650
+ shepherd_watch(taskId) -> immediate registration
651
+ child sends messages / waits / resumes
652
+ child shepherd_done -> task settlement
653
+ watcher -> parent custom completion notification
654
+ ```
655
+
656
+ Files:
657
+
658
+ ```text
659
+ src/core/lifecycle.ts
660
+ src/core/orchestration.ts
661
+ src/extension/shepherd.ts
662
+ src/core/types.ts
663
+
664
+ test/verify-task-watchers.mjs
665
+ ```
666
+
667
+ Acceptance:
668
+
669
+ - Watching a waiting task remains pending.
670
+ - Watching a completed task returns its result immediately.
671
+ - Multiple watchers receive independent, idempotent notifications.
672
+ - Parent shutdown stops polling without corrupting settled task records.
673
+
674
+ ### Phase 8 — Add stale-wait monitoring
675
+
676
+ Implement notification for tasks waiting too long for replies.
677
+
678
+ 1. Add a configurable `staleWaitThreshold` setting, defaulting to a conservative
679
+ value such as two minutes.
680
+ 2. Preserve the existing two-layer user/project settings model.
681
+ 3. Add the setting to config validation, defaults, settings UI, and docs.
682
+ 4. Start a parent-owned monitor only while there are waiting tasks.
683
+ 5. Inspect task state, not raw Herdr idle state.
684
+ 6. Require at least one unresolved `expectsReply` request.
685
+ 7. Emit one stale notification per waiting episode.
686
+ 8. Include task ID, agent, task description, waiting age, request ID, question,
687
+ target recipient, and recipient status.
688
+ 9. Mark the notification as delivered without changing the task's lifecycle
689
+ state.
690
+ 10. Clear the notification marker when a reply returns the task to `running`.
691
+ 11. Add a separate long escalation interval only if real usage demonstrates a
692
+ need; do not repeatedly notify by default.
693
+ 12. Do not trigger a parent model turn for every normal waiting transition.
694
+ A stale notification may use `pi.sendMessage` with follow-up delivery and
695
+ `triggerTurn: true` when the parent is idle.
696
+
697
+ Files:
698
+
699
+ ```text
700
+ src/extension/config.ts
701
+ src/extension/settings-ui.ts
702
+ src/core/lifecycle.ts or src/core/task-monitor.ts
703
+ src/extension/shepherd.ts
704
+
705
+ test/verify-stale-wait.mjs
706
+ test/verify-settings.mjs
707
+ ```
708
+
709
+ Acceptance:
710
+
711
+ - A waiting scout produces one notification after the threshold.
712
+ - A reply prevents additional notifications for that waiting episode.
713
+ - A later waiting episode can produce a new notification.
714
+ - A completed task never produces a stale-wait notification.
715
+
716
+ ### Phase 9 — Update status and the TUI widget
717
+
718
+ Expose process and task state separately.
719
+
720
+ 1. Extend `shepherd_status` to include task ID, task state, waiting age, pending
721
+ request, recipient, and stale flag when applicable.
722
+ 2. Keep Herdr process state as a separate field.
723
+ 3. Update `workingSubagents()` or add a task-aware status projection so an idle
724
+ process with a waiting task remains visible.
725
+ 4. Render waiting rows distinctly from completed or working rows.
726
+ 5. Preserve the current pane ownership filtering.
727
+ 6. Avoid making widget rendering depend on direct mailbox reads on every frame;
728
+ poll into a snapshot at the existing widget interval.
729
+
730
+ Files:
731
+
732
+ ```text
733
+ src/core/herdr.ts
734
+ src/core/lifecycle.ts
735
+ src/extension/shepherd.ts
736
+ index.ts
737
+
738
+ test/verify-status-widget.mjs
739
+ ```
740
+
741
+ Acceptance example:
742
+
743
+ ```text
744
+ ○ 02:14 scout idle / waiting for planner
745
+ ```
746
+
747
+ The status widget must not display the scout as completed merely because its
748
+ Pi process is idle.
749
+
750
+ ### Phase 10 — Artifacts, cleanup, and compatibility
751
+
752
+ Integrate the new lifecycle with existing persistence and ownership rules.
753
+
754
+ 1. Allocate one artifact reservation for each delegated task when the task is
755
+ created.
756
+ 2. Do not allocate artifacts for ordinary messages or replies.
757
+ 3. Keep the task artifact open during `waiting`.
758
+ 4. Finalize it on completed, blocked, failed, cancelled, or timed-out task
759
+ settlement.
760
+ 5. Include message/request references in the task artifact only if they are
761
+ useful task context; do not create one note per chat message.
762
+ 6. Ensure broker cleanup happens only after all child panes are confirmed gone,
763
+ following the existing temporary-resource invariant.
764
+ 7. Ensure closing an agent cancels its active task and unresolved requests.
765
+ 8. Ensure a parent restart cannot accidentally claim another session's tasks or
766
+ panes.
767
+ 9. Update the compatibility adapter for `shepherd_prompt` and
768
+ `shepherd_wait`, or remove them with an explicit migration note. Do not
769
+ silently expose two different meanings for the same prompt ID.
770
+ 10. Update the shared Shepherd narrative and child instructions.
771
+
772
+ Files:
773
+
774
+ ```text
775
+ src/core/artifact-sessions.ts
776
+ src/core/lifecycle.ts
777
+ src/core/herdr.ts
778
+ src/core/orchestration.ts
779
+ src/extension/shepherd.ts
780
+ src/extension/shepherd-agent.ts
781
+ index.ts
782
+ README.md
783
+ docs/guides/tool-reference.md
784
+ docs/reference/dictionary
785
+ docs/plans/architecture.md
786
+ ```
787
+
788
+ Acceptance:
789
+
790
+ - Task artifacts remain open while a child waits.
791
+ - Message-only conversations do not create artifacts.
792
+ - Close, crash, timeout, and parent shutdown leave no unsafe temporary
793
+ resources.
794
+ - Public documentation describes task IDs, message IDs, and their different
795
+ lifetimes.
796
+
797
+ ## 5. Tool schemas and model-facing surface
798
+
799
+ Every registration must use a flat root `Type.Object` schema and spell out
800
+ `name`, `label`, `description`, `promptSnippet`, and `parameters` directly in
801
+ the registration.
802
+
803
+ ### `shepherd_delegate`
804
+
805
+ Parent-only:
806
+
807
+ ```text
808
+ target: required opaque agent ID
809
+ task: required non-empty string
810
+ timeout: optional integer task deadline in minutes
811
+ ```
812
+
813
+ Returns `taskId`, `agentId`, and acceptance state.
814
+
815
+ ### `shepherd_message`
816
+
817
+ Parent and child adapters:
818
+
819
+ ```text
820
+ target: required Shepherd, parent, or opaque agent ID
821
+ message: required non-empty string
822
+ taskId: optional active task ID
823
+ threadId: optional conversation ID
824
+ replyTo: optional request/message ID
825
+ expectsReply: optional boolean, default false
826
+ delivery: optional followUp|steer, default followUp
827
+ ```
828
+
829
+ The child adapter may restrict `target` based on the child capability, but it
830
+ must use the same conceptual envelope.
831
+
832
+ ### `shepherd_done`
833
+
834
+ Child-only:
835
+
836
+ ```text
837
+ taskId: required opaque task ID
838
+ status: required completed|blocked|failed
839
+ summary: optional completion or failure summary
840
+ ```
841
+
842
+ ### `shepherd_watch`
843
+
844
+ Parent-only:
845
+
846
+ ```text
847
+ id: required task ID or non-empty task ID array
848
+ ```
849
+
850
+ If compatibility prompt IDs remain accepted, the adapter must explicitly state
851
+ that they resolve to associated task IDs and must not guess from agent IDs or
852
+ pane IDs.
853
+
854
+ ## 6. Compatibility and migration strategy
855
+
856
+ The existing implementation has prompt records, prompt watchers, completion
857
+ sidecars, fieldnote callbacks, and tests built around one unresolved prompt per
858
+ agent. The migration must avoid a period where a single child can be governed
859
+ by two contradictory completion mechanisms.
860
+
861
+ Recommended migration sequence:
862
+
863
+ 1. Introduce task records and task IDs without changing existing public calls.
864
+ 2. Add the mailbox and child extension behind new `shepherd_delegate` and
865
+ `shepherd_message` tools.
866
+ 3. Route new delegated tasks exclusively through task records.
867
+ 4. Make `shepherd_watch` task-aware.
868
+ 5. Add a compatibility mapping from old prompt IDs to task IDs.
869
+ 6. Update `shepherd_prompt` to call the compatibility delegation adapter.
870
+ 7. Update `shepherd_wait` to wait on the mapped task only if it is retained.
871
+ 8. Remove prompt-specific successful completion detection from the child
872
+ sidecar.
873
+ 9. Update all active documentation and tests.
874
+ 10. Retain historical prompt terminology only in migration notes or archived
875
+ plans.
876
+
877
+ Do not support both of these simultaneously for the same delegated task:
878
+
879
+ ```text
880
+ agent_end sidecar means success
881
+ shepherd_done means success
882
+ ```
883
+
884
+ The explicit task protocol must be authoritative.
885
+
886
+ ## 7. Test plan
887
+
888
+ ### 7.1 Registry and state tests
889
+
890
+ Add `test/verify-task-registry.mjs` covering:
891
+
892
+ - opaque task IDs are session-scoped;
893
+ - one active task per agent;
894
+ - messages do not consume the task slot;
895
+ - waiting tasks remain non-terminal;
896
+ - all valid state transitions;
897
+ - invalid transitions;
898
+ - idempotent terminal settlement;
899
+ - request resolution and cancellation;
900
+ - task timeout and close cancellation.
901
+
902
+ ### 7.2 Mailbox tests
903
+
904
+ Add `test/verify-messaging.mjs` covering:
905
+
906
+ - atomic publication and complete-file reads;
907
+ - parent-to-child delivery;
908
+ - child-to-parent delivery;
909
+ - duplicate envelope handling;
910
+ - malformed envelope rejection;
911
+ - invalid sender capability rejection;
912
+ - unknown target rejection;
913
+ - queue depth and message-size limits;
914
+ - broker cleanup after child disappearance.
915
+
916
+ ### 7.3 Child surface tests
917
+
918
+ Add `test/verify-child-surface.mjs` covering:
919
+
920
+ - child sessions receive `shepherd_message` and `shepherd_done` only;
921
+ - parent sessions receive parent lifecycle tools;
922
+ - child message tools return acceptance without waiting for replies;
923
+ - `shepherd_done` publishes a task-done control envelope;
924
+ - incoming messages invoke Pi queue APIs with the requested delivery mode.
925
+
926
+ Update `test/verify-launch.mjs` to verify:
927
+
928
+ - broker environment wiring;
929
+ - child identity wiring;
930
+ - task identity wiring;
931
+ - child extension wiring; and
932
+ - no parent-only surface in the child.
933
+
934
+ ### 7.4 Conversation and task tests
935
+
936
+ Add `test/verify-task-messaging.mjs` covering the canonical scenario:
937
+
938
+ ```text
939
+ 1. delegate task to scout
940
+ 2. scout sends expectsReply question to busy planner
941
+ 3. scout turn settles
942
+ 4. scout process is idle
943
+ 5. scout task remains waiting
944
+ 6. no watcher completion is delivered
945
+ 7. planner receives the queued question
946
+ 8. planner replies with replyTo
947
+ 9. scout receives the reply as followUp
948
+ 10. scout task returns to running
949
+ 11. scout calls shepherd_done
950
+ 12. watcher receives exactly one completed result
951
+ ```
952
+
953
+ Also cover:
954
+
955
+ - a non-reply message while a task is running;
956
+ - a message to the Shepherd;
957
+ - multiple independent messages;
958
+ - a peer reply arriving while the child is idle;
959
+ - reply timeout;
960
+ - planner closure while scout waits;
961
+ - scout closure while planner has a queued question; and
962
+ - duplicate replies and duplicate done events.
963
+
964
+ ### 7.5 Watcher and notification tests
965
+
966
+ Add `test/verify-task-watchers.mjs` covering:
967
+
968
+ - immediate registration;
969
+ - already-completed tasks;
970
+ - one and multiple task IDs;
971
+ - independent watcher delivery;
972
+ - completion ordering;
973
+ - failed, blocked, cancelled, and timed-out outcomes;
974
+ - no settlement on `agent_end`, `agent_settled`, or idle; and
975
+ - no parent turn after watcher shutdown.
976
+
977
+ Add `test/verify-stale-wait.mjs` covering:
978
+
979
+ - threshold crossing;
980
+ - one notification per waiting episode;
981
+ - notification content and correlation IDs;
982
+ - reset after a reply;
983
+ - no notification for completed tasks;
984
+ - no notification for ordinary idle agents; and
985
+ - request timeout/escalation behavior.
986
+
987
+ ### 7.6 Schema and documentation tests
988
+
989
+ Update:
990
+
991
+ ```text
992
+ test/verify-tool-schemas.mjs
993
+ test/verify-parent-surface.mjs
994
+ test/verify-status-widget.mjs
995
+ ```
996
+
997
+ The schema test must verify that every new model-facing registration has a
998
+ flat object root and explicit required fields. The parent-surface test must
999
+ verify role-specific registration in parent and child processes.
1000
+
1001
+ ### 7.7 Live Herdr verification
1002
+
1003
+ After focused tests pass, run the live matrix:
1004
+
1005
+ 1. Start or attach to Herdr.
1006
+ 2. Spawn scout and planner as persistent agents.
1007
+ 3. Delegate a task to scout.
1008
+ 4. Prompt scout, through its task context, to ask planner a question.
1009
+ 5. Keep planner busy so scout's current turn settles first.
1010
+ 6. Confirm scout's Herdr state becomes idle while task state remains waiting.
1011
+ 7. Confirm no `shepherd_watch` completion occurs.
1012
+ 8. Confirm the stale-wait notification after the configured threshold.
1013
+ 9. Allow planner to answer.
1014
+ 10. Confirm scout receives the answer and resumes.
1015
+ 11. Confirm scout calls `shepherd_done`.
1016
+ 12. Confirm exactly one watcher completion notification.
1017
+ 13. Verify status and widget output during the waiting interval.
1018
+ 14. Repeat with close, timeout, provider failure, and parent shutdown.
1019
+ 15. Verify pane ownership and temporary-resource cleanup.
1020
+
1021
+ Finally run:
1022
+
1023
+ ```bash
1024
+ npm test
1025
+ ```
1026
+
1027
+ ## 8. Documentation updates
1028
+
1029
+ Update active documentation only after the API and compatibility behavior are
1030
+ settled.
1031
+
1032
+ Required updates:
1033
+
1034
+ ```text
1035
+ README.md
1036
+ docs/guides/tool-reference.md
1037
+ docs/reference/dictionary
1038
+ docs/plans/architecture.md
1039
+ ```
1040
+
1041
+ Document:
1042
+
1043
+ - task IDs versus message IDs;
1044
+ - `shepherd_delegate` versus `shepherd_message`;
1045
+ - explicit `shepherd_done` completion;
1046
+ - `shepherd_watch` as the preferred non-blocking observer;
1047
+ - waiting tasks whose agents may be idle;
1048
+ - `followUp` versus `steer` delivery;
1049
+ - stale-wait notifications; and
1050
+ - the compatibility status of `shepherd_prompt` and `shepherd_wait`.
1051
+
1052
+ The umbrella Shepherd description should explain that a Pi turn ending does
1053
+ not complete a delegated task and that agents should use `shepherd_message`
1054
+ for questions and `shepherd_done` only for actual task completion.
1055
+
1056
+ ## 9. Delivery order and review gates
1057
+
1058
+ Each phase should be implemented and reviewed before the next phase begins.
1059
+
1060
+ ```text
1061
+ Phase 0 baseline and guardrails
1062
+ Phase 1 task registry
1063
+ Phase 2 mailbox transport
1064
+ Phase 3 child extension
1065
+ Phase 4 delegation
1066
+ Phase 5 explicit completion
1067
+ Phase 6 message routing
1068
+ Phase 7 task watchers
1069
+ Phase 8 stale-wait monitor
1070
+ Phase 9 status and widget
1071
+ Phase 10 artifacts, cleanup, compatibility, docs
1072
+ ```
1073
+
1074
+ Review gates:
1075
+
1076
+ - After Phase 1: verify that idle is not completion.
1077
+ - After Phase 3: verify child and parent surfaces are isolated.
1078
+ - After Phase 5: verify explicit `shepherd_done` is authoritative.
1079
+ - After Phase 6: verify the scout/planner waiting scenario manually.
1080
+ - After Phase 8: verify stale notifications do not create message storms.
1081
+ - After Phase 10: run the full test suite and live Herdr matrix.
1082
+
1083
+ The feature is complete only when the canonical waiting scenario is correct:
1084
+
1085
+ ```text
1086
+ scout's Pi turn ends
1087
+ scout is idle
1088
+ scout's task is waiting, not done
1089
+ planner replies
1090
+ scout resumes
1091
+ scout explicitly calls shepherd_done
1092
+ shepherd_watch reports completion
1093
+ ```