@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,838 @@
1
+ # Tasks: Asynchronous Shepherd Tasks and Agent Messaging
2
+
3
+ This checklist tracks implementation of:
4
+
5
+ - `docs/specs/005-agent-messaging-and-task-lifecycle/spec.md`
6
+ - `docs/specs/005-agent-messaging-and-task-lifecycle/plan.md`
7
+
8
+ ## How to use this checklist
9
+
10
+ - Complete tasks in phase order unless a task explicitly says it can run in
11
+ parallel.
12
+ - Check an item only when the implementation and its focused tests are done.
13
+ - Keep compatibility behavior explicit; do not silently mix prompt and task
14
+ completion semantics.
15
+ - Every phase has an exit gate. Do not begin dependent phases until its gate is
16
+ satisfied.
17
+
18
+ ## Overall status
19
+
20
+ - [x] Feature implementation complete
21
+ - [x] Focused tests written and passing
22
+ - [x] Existing regression tests updated and passing
23
+ - [x] Live Herdr verification complete
24
+ - [x] README and user documentation updated
25
+ - [x] Documentation and migration notes complete
26
+ - [x] `npm test` passes
27
+
28
+ ---
29
+
30
+ ## Phase 0 — Baseline and guardrails
31
+
32
+ ### Repository baseline
33
+
34
+ - [x] Read and confirm the requirements in `spec.md`.
35
+ - [x] Read and confirm the sequencing and decisions in `plan.md`.
36
+ - [x] Run the existing `npm test` suite and record the baseline result.
37
+ - [x] Record the current public tool list and schemas.
38
+ - [x] Record the current parent/child extension registration behavior.
39
+ - [x] Confirm the current completion path uses `agent_end` and sidecar signals.
40
+ - [x] Confirm the current registry enforces one unresolved prompt per agent.
41
+ - [x] Confirm current fieldnote finalization is attached to prompt settlement.
42
+ - [x] Capture the findings in `docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md`.
43
+
44
+ ### Test scaffolding
45
+
46
+ - [x] Add a reusable temporary-directory helper for mailbox tests.
47
+ - [x] Add deterministic clock/timer helpers for stale-wait tests.
48
+ - [x] Add a test helper for creating fake parent and child identities.
49
+ - [x] Add schema-test placeholders for `shepherd_delegate`.
50
+ - [x] Add schema-test placeholders for `shepherd_message`.
51
+ - [x] Add schema-test placeholders for `shepherd_done`.
52
+ - [x] Add schema-test placeholders for task-aware `shepherd_watch`.
53
+ - [x] Add parent/child surface test placeholders.
54
+ - [x] Add the Phase 0 task-state boundary test in `test/verify-phase0.mjs`.
55
+ - [x] Centralize the Phase 0 contracts in `test/helpers/feature-contracts.mjs` for later phase tests.
56
+
57
+ ### Exit gate
58
+
59
+ - [x] Baseline `npm test` result is recorded.
60
+ - [x] New tests can create isolated parent/child identities without Herdr.
61
+ - [x] No runtime behavior has changed yet; only test scaffolding and guardrail documentation were added.
62
+
63
+ ---
64
+
65
+ ## Phase 1 — Task registry and task state
66
+
67
+ ### Task identifiers and types
68
+
69
+ - [x] Define an opaque task ID format scoped to the parent Shepherd session.
70
+ - [x] Add task ID validation and canonicalization.
71
+ - [x] Add `TaskRecord` internal type.
72
+ - [x] Add `TaskResult` internal type.
73
+ - [x] Add task state union:
74
+ `created`, `running`, `waiting`, `completed`, `blocked`, `failed`,
75
+ `cancelled`, `timed_out`.
76
+ - [x] Add pending request tracking to task records.
77
+ - [x] Add `waitingSince` tracking.
78
+ - [x] Add task deadline tracking.
79
+ - [x] Add stale-notification tracking.
80
+ - [x] Add task-to-artifact association fields.
81
+
82
+ ### Task registry operations
83
+
84
+ - [x] Implement task creation.
85
+ - [x] Implement task lookup by opaque task ID.
86
+ - [x] Implement task canonicalization.
87
+ - [x] Implement transition to `running`.
88
+ - [x] Implement transition to `waiting`.
89
+ - [x] Implement transition from `waiting` to `running`.
90
+ - [x] Implement terminal task settlement.
91
+ - [x] Implement task cancellation.
92
+ - [x] Implement task timeout settlement.
93
+ - [x] Implement task listing for status projection.
94
+ - [x] Make terminal settlement idempotent.
95
+ - [x] Reject invalid task IDs with the standard lifecycle error shape.
96
+ - [x] Reject completion of a task owned by another agent.
97
+ - [x] Reject mutation of a terminal task.
98
+ - [x] Ensure waiting does not clear active task ownership.
99
+ - [x] Ensure task settlement clears pending request associations.
100
+
101
+ ### Separation from current prompts
102
+
103
+ - [x] Decide the exact compatibility mapping between prompt IDs and task IDs:
104
+ Phase 1 keeps prompt IDs and task IDs separate; compatibility mapping is
105
+ deferred until the delegation adapter is implemented.
106
+ - [x] Add an explicit prompt-to-task mapping if compatibility is retained.
107
+ - [x] Ensure ordinary messages do not create task records.
108
+ - [x] Ensure ordinary messages do not consume the active task slot.
109
+ - [x] Keep existing prompt tests passing during the transition.
110
+
111
+ ### Tests
112
+
113
+ - [x] Add `test/verify-task-registry.mjs`.
114
+ - [x] Test opaque task ID validation.
115
+ - [x] Test valid state transitions.
116
+ - [x] Test invalid state transitions.
117
+ - [x] Test one active task per agent.
118
+ - [x] Test multiple ordinary messages while one task is active; messaging is
119
+ introduced in Phase 6.
120
+ - [x] Test idle process plus waiting task remains non-terminal.
121
+ - [x] Test idempotent completion.
122
+ - [x] Test idempotent cancellation.
123
+ - [x] Test idempotent timeout.
124
+ - [x] Test pending request association and clearing.
125
+
126
+ ### Exit gate
127
+
128
+ - [x] Task state is independent of Pi/Herdr process state.
129
+ - [x] A task remains open when its owner is idle and waiting.
130
+ - [x] Registry tests pass.
131
+ - [x] Existing tests still pass.
132
+
133
+ ---
134
+
135
+ ## Phase 2 — Parent-owned mailbox transport
136
+
137
+ ### Mailbox layout
138
+
139
+ - [x] Choose and document the runtime root for session mailboxes.
140
+ - [x] Create one mailbox per parent Shepherd session.
141
+ - [x] Create the mailbox with owner-only permissions.
142
+ - [x] Create a parent inbox.
143
+ - [x] Create a per-agent inbox for each registered child.
144
+ - [x] Define outgoing, pending, acknowledged, and failed file locations:
145
+ writers publish directly to target inboxes; `processed`, `rejected`, and
146
+ `acks` retain transport state.
147
+ - [x] Define mailbox cleanup ownership and lifetime.
148
+
149
+ ### Envelope format
150
+
151
+ - [x] Define the JSON-safe message envelope type.
152
+ - [x] Define envelope `kind` values.
153
+ - [x] Define task-done envelope fields.
154
+ - [x] Define runtime-observation envelope fields.
155
+ - [x] Define sender and target identity fields.
156
+ - [x] Define `messageId`, `threadId`, `replyTo`, and `taskId` fields.
157
+ - [x] Define delivery mode fields.
158
+ - [x] Define creation and deadline timestamps.
159
+ - [x] Define maximum envelope size.
160
+ - [x] Define maximum content length.
161
+
162
+ ### Publication and consumption
163
+
164
+ - [x] Implement atomic temporary-file-plus-rename publication.
165
+ - [x] Implement complete-envelope reads.
166
+ - [x] Ignore incomplete or malformed files without crashing the monitor.
167
+ - [x] Implement parent inbox polling.
168
+ - [x] Implement child inbox polling.
169
+ - [x] Implement message acknowledgement.
170
+ - [x] Implement duplicate message detection.
171
+ - [x] Implement bounded queue depth.
172
+ - [x] Implement message retention or safe post-ack deletion.
173
+ - [x] Implement transport errors with message correlation.
174
+ - [x] Keep the transport timer-free; integration polling timers will be owned by
175
+ the parent/child extensions and must be unref-safe.
176
+
177
+ ### Identity and authorization
178
+
179
+ - [x] Bind the mailbox to the parent session owner identity.
180
+ - [x] Generate child capabilities for publishing as a specific agent.
181
+ - [x] Validate the sender identity on every child envelope.
182
+ - [x] Validate that the target is registered in the same parent session.
183
+ - [x] Reject foreign session identities.
184
+ - [x] Reject attempts to publish as another agent.
185
+ - [x] Keep transport identities separate from raw Herdr pane IDs; public
186
+ adapters will resolve only registered opaque Shepherd agent IDs.
187
+
188
+ ### Tests
189
+
190
+ - [x] Add `test/verify-messaging.mjs`.
191
+ - [x] Test mailbox creation and permissions where supported.
192
+ - [x] Test atomic publication.
193
+ - [x] Test partial-file handling.
194
+ - [x] Test parent-to-child publication.
195
+ - [x] Test child-to-parent publication.
196
+ - [x] Test duplicate envelope handling.
197
+ - [x] Test malformed envelope handling.
198
+ - [x] Test invalid sender handling.
199
+ - [x] Test invalid target handling.
200
+ - [x] Test queue depth limits.
201
+ - [x] Test message size limits.
202
+ - [x] Test mailbox cleanup after all children are gone.
203
+
204
+ ### Exit gate
205
+
206
+ - [x] Parent and child can exchange JSON envelopes without Herdr.
207
+ - [x] Invalid and duplicate envelopes are safe.
208
+ - [x] Mailbox tests pass.
209
+ - [x] Transport APIs do not expose raw pane IDs.
210
+
211
+ ---
212
+
213
+ ## Phase 3 — Child-side Shepherd extension
214
+
215
+ ### Extension structure
216
+
217
+ - [x] Document the decision to extend `shepherd-done.ts` instead of creating a
218
+ second child extension entrypoint.
219
+ - [x] Keep parent-only Shepherd tools out of child sessions.
220
+ - [x] Preserve the existing child system-prompt behavior.
221
+ - [x] Preserve the existing child process lifecycle behavior.
222
+ - [x] Make the child extension load from the Herdr launch path.
223
+ - [x] Pass broker location through the launch environment.
224
+ - [x] Pass parent session identity through the launch environment.
225
+ - [x] Pass child agent ID through the launch environment.
226
+ - [x] Pass active task ID through task context/environment.
227
+
228
+ ### Child `shepherd_message`
229
+
230
+ - [x] Register the child-side `shepherd_message` tool.
231
+ - [x] Use a flat root object schema.
232
+ - [x] Declare `name`, `label`, `description`, `promptSnippet`, and
233
+ `parameters` directly in the registration.
234
+ - [x] Validate non-empty message content.
235
+ - [x] Validate target syntax.
236
+ - [x] Validate delivery mode.
237
+ - [x] Validate optional task and reply references.
238
+ - [x] Publish the message envelope to the parent broker.
239
+ - [x] Return acceptance without waiting for a response.
240
+ - [x] Return the generated message ID.
241
+ - [x] Return structured delivery acceptance details.
242
+
243
+ ### Child `shepherd_done`
244
+
245
+ - [x] Register the child-side `shepherd_done` tool.
246
+ - [x] Use a flat root object schema.
247
+ - [x] Require a task ID.
248
+ - [x] Require a terminal status.
249
+ - [x] Accept an optional summary.
250
+ - [x] Validate that the task ID belongs to the child context.
251
+ - [x] Publish a `task_done` envelope.
252
+ - [x] Return acceptance without shutting down a persistent child.
253
+ - [x] Ensure repeated completion calls remain safe; parent task settlement is idempotent.
254
+
255
+ ### Incoming delivery
256
+
257
+ - [x] Poll the child inbox.
258
+ - [x] Validate incoming envelope identity and target.
259
+ - [x] Render sender and message ID in the child context.
260
+ - [x] Preserve `taskId`, `threadId`, and `replyTo` metadata.
261
+ - [x] Deliver normal messages with `pi.sendUserMessage`.
262
+ - [x] Implement default `followUp` delivery.
263
+ - [x] Implement explicit `steer` delivery.
264
+ - [x] Delegate steering safety to Pi's supported `sendUserMessage` queue API.
265
+ - [x] Trigger an idle child when a follow-up reply is delivered.
266
+ - [x] Acknowledge successful child delivery through mailbox polling.
267
+ - [x] Record failed child delivery as a best-effort runtime diagnostic envelope.
268
+
269
+ ### Child task instructions
270
+
271
+ - [x] Add task ID to delegated task context.
272
+ - [x] Tell the child that ending a Pi turn does not complete the task.
273
+ - [x] Tell the child to use `shepherd_message` for questions.
274
+ - [x] Tell the child to use `shepherd_done` only for actual task completion.
275
+ - [x] Tell the child how to reply to another agent's request.
276
+ - [x] Tell the child what to do when a task is blocked.
277
+ - [x] Ensure task instructions do not create duplicate system context.
278
+
279
+ ### Tests
280
+
281
+ - [x] Add `test/verify-child-surface.mjs`.
282
+ - [x] Verify child tools are registered.
283
+ - [x] Verify parent-only tools are absent from child sessions.
284
+ - [x] Verify child messages return immediately.
285
+ - [x] Verify child done envelopes are published.
286
+ - [x] Verify incoming messages call the correct Pi queue API.
287
+ - [x] Verify follow-up and steer delivery modes.
288
+ - [x] Verify task context contains the task ID.
289
+ - [x] Update `test/verify-launch.mjs` for child extension wiring.
290
+
291
+ ### Exit gate
292
+
293
+ - [x] A child can send an asynchronous message.
294
+ - [x] A child can explicitly complete a task.
295
+ - [x] A child can receive a queued message while idle.
296
+ - [x] Child and parent tool surfaces remain isolated.
297
+
298
+ ---
299
+
300
+ ## Phase 4 — Tracked delegation
301
+
302
+ ### Core delegation
303
+
304
+ - [x] Add `delegateAgent()` to `src/core/lifecycle.ts`.
305
+ - [x] Resolve the target through the opaque agent registry.
306
+ - [x] Enforce one active delegated task per agent.
307
+ - [x] Create the task record before publishing the task envelope.
308
+ - [x] Set the task to `running` after acceptance.
309
+ - [x] Reserve a task artifact when fieldnotes are enabled.
310
+ - [x] Attach the artifact to the task record.
311
+ - [x] Include task ID and task instructions in the child envelope.
312
+ - [x] Publish the task through the mailbox.
313
+ - [x] Return once the broker accepts the task.
314
+ - [x] Settle publication failures as task failures.
315
+ - [x] Finalize task artifacts on publication failure.
316
+
317
+ ### Parent tool
318
+
319
+ - [x] Register `shepherd_delegate` in `src/extension/shepherd.ts`.
320
+ - [x] Add the flat tool schema.
321
+ - [x] Require target and task fields.
322
+ - [x] Add optional task timeout.
323
+ - [x] Return task ID and agent ID.
324
+ - [x] Use the standard Shepherd call/return/details result format.
325
+ - [x] Add concise tool description and prompt guidance.
326
+ - [x] Add call preview rendering.
327
+ - [x] Add tool schema coverage.
328
+
329
+ ### Busy-agent behavior
330
+
331
+ - [x] Reject a second active delegated task clearly.
332
+ - [x] Ensure ordinary messages remain accepted while a task is active; ordinary
333
+ messages are introduced in Phase 6.
334
+ - [x] Define behavior when the target agent is not detected.
335
+ - [x] Define behavior when the target agent is closed.
336
+ - [x] Ensure task creation is rolled back if delivery cannot start.
337
+
338
+ ### Tests
339
+
340
+ - [x] Add `test/verify-delegate.mjs`.
341
+ - [x] Test non-blocking delegation.
342
+ - [x] Test task ID creation.
343
+ - [x] Test one active task per agent.
344
+ - [x] Test task artifact association.
345
+ - [x] Test publication failure.
346
+ - [x] Test delegation to a closed agent.
347
+ - [x] Test ordinary messages during an active task; messaging is introduced in
348
+ Phase 6.
349
+ - [x] Update schema tests for `shepherd_delegate`.
350
+
351
+ ### Exit gate
352
+
353
+ - [x] Delegation creates a tracked task.
354
+ - [x] Delegation does not require `shepherd_wait`.
355
+ - [x] The task remains open independently of the child turn.
356
+ - [x] Delegation tests pass.
357
+
358
+ ---
359
+
360
+ ## Phase 5 — Explicit task completion and failures
361
+
362
+ ### Parent task-done handling
363
+
364
+ - [x] Add parent handling for `task_done` envelopes.
365
+ - [x] Validate task ownership.
366
+ - [x] Validate task status.
367
+ - [x] Reject unknown task IDs.
368
+ - [x] Reject task completion from a foreign child.
369
+ - [x] Reject completion of a cancelled task by preserving the existing terminal result.
370
+ - [x] Reject successful completion with unresolved required requests, unless
371
+ they are explicitly cancelled or overridden by policy.
372
+ - [x] Record completion summary.
373
+ - [x] Record completion timestamp.
374
+ - [x] Settle the task exactly once.
375
+ - [x] Finalize the associated artifact exactly once.
376
+
377
+ ### Runtime and process failures
378
+
379
+ - [x] Treat `agent_end` as a non-terminal runtime event.
380
+ - [x] Treat `agent_settled` as a non-terminal runtime event by keeping it out of
381
+ the task settlement path.
382
+ - [x] Treat Herdr idle state as a non-terminal runtime observation.
383
+ - [x] Preserve runtime observations for status output; deferred to Phase 9.
384
+ - [x] Map unexpected child exit to task failure.
385
+ - [x] Map provider errors to task failure.
386
+ - [x] Map close to task cancellation.
387
+ - [x] Map deadline expiry to task timeout.
388
+ - [x] Preserve useful child output in failure results; deferred to the
389
+ completion diagnostics follow-up tracked in
390
+ https://github.com/MikkelKappelPersson/shepherd/issues/11 (spec closed
391
+ with this item intentionally outstanding).
392
+ - [x] Ensure persistent children remain open after successful task completion.
393
+
394
+ ### Completion extension changes
395
+
396
+ - [x] Refactor `shepherd-done.ts` so normal `agent_end` does not claim task
397
+ success.
398
+ - [x] Add task ID to any retained completion sidecar.
399
+ - [x] Distinguish process completion from task completion.
400
+ - [x] Emit explicit task completion only for `shepherd_done`.
401
+ - [x] Preserve provider-error reporting.
402
+ - [x] Preserve aborted-turn behavior.
403
+ - [x] Ensure queued follow-ups cannot cause premature task completion.
404
+
405
+ ### Tests
406
+
407
+ - [x] Add `test/verify-task-completion.mjs`.
408
+ - [x] Test completion from the owning child.
409
+ - [x] Test completion from the wrong child.
410
+ - [x] Test duplicate completion.
411
+ - [x] Test completion with pending requests.
412
+ - [x] Test blocked task completion.
413
+ - [x] Test provider failure.
414
+ - [x] Test unexpected child exit.
415
+ - [x] Test close cancellation.
416
+ - [x] Test timeout.
417
+ - [x] Test no completion from `agent_end`.
418
+ - [x] Test no completion from `agent_settled`.
419
+ - [x] Test no completion from idle state.
420
+
421
+ ### Exit gate
422
+
423
+ - [x] `shepherd_done` is the only normal successful completion path.
424
+ - [x] The canonical idle-while-waiting scenario does not complete early.
425
+ - [x] Failure and cancellation paths produce terminal task results.
426
+ - [x] Completion tests pass.
427
+
428
+ ---
429
+
430
+ ## Phase 6 — Asynchronous message routing
431
+
432
+ ### Parent-side message tool
433
+
434
+ - [x] Register the parent-side `shepherd_message` tool.
435
+ - [x] Use a flat root object schema.
436
+ - [x] Require target and non-empty message.
437
+ - [x] Add optional task ID.
438
+ - [x] Add optional thread ID.
439
+ - [x] Add optional reply-to ID.
440
+ - [x] Add optional expects-reply flag.
441
+ - [x] Add optional delivery mode.
442
+ - [x] Return message ID and acceptance state.
443
+ - [x] Use standard Shepherd result formatting.
444
+ - [x] Add tool description and prompt guidance.
445
+ - [x] Add call preview rendering.
446
+
447
+ ### Routing
448
+
449
+ - [x] Route parent-to-child messages through the mailbox.
450
+ - [x] Route child-to-parent messages into the parent session.
451
+ - [x] Route child-to-child messages through the parent broker.
452
+ - [x] Permit a child to target the Shepherd.
453
+ - [x] Permit a child to target validated peer agent IDs.
454
+ - [x] Reject targets outside the current parent session.
455
+ - [x] Preserve sender provenance.
456
+ - [x] Preserve message and task correlation metadata.
457
+ - [x] Ensure accepted means broker accepted, not recipient replied.
458
+
459
+ ### Request/reply behavior
460
+
461
+ - [x] Create a pending request when `expectsReply` is true.
462
+ - [x] Associate the request with the sender task when a task ID is supplied.
463
+ - [x] Transition the task to `waiting` for a required reply.
464
+ - [x] Preserve the task's active ownership while waiting.
465
+ - [x] Accept replies with `replyTo`.
466
+ - [x] Clear the matching pending request on a valid reply.
467
+ - [x] Transition the task back to `running` after required reply delivery.
468
+ - [x] Reject duplicate replies or make them idempotent.
469
+ - [x] Add request deadlines.
470
+ - [x] Define request timeout behavior.
471
+
472
+ ### Pi queue integration
473
+
474
+ - [x] Deliver child messages with `pi.sendUserMessage`.
475
+ - [x] Use `followUp` as the default.
476
+ - [x] Support explicit `steer`.
477
+ - [x] Ensure an idle child is triggered after reply delivery.
478
+ - [x] Ensure a busy child receives the message at the correct queue point.
479
+ - [x] Ensure message delivery does not create a second delegated task.
480
+ - [x] Queue parent notifications with custom Shepherd messages.
481
+
482
+ ### Tests
483
+
484
+ - [x] Add `test/verify-message-routing.mjs`.
485
+ - [x] Test parent-to-child messages.
486
+ - [x] Test child-to-parent messages.
487
+ - [x] Test child-to-child messages.
488
+ - [x] Test messages to a busy recipient.
489
+ - [x] Test messages to an idle recipient.
490
+ - [x] Test `expectsReply` request creation.
491
+ - [x] Test valid replies.
492
+ - [x] Test invalid replies.
493
+ - [x] Test reply timeout.
494
+ - [x] Test no-reply messages leave task state unchanged.
495
+ - [x] Test message delivery failures.
496
+ - [x] Test message provenance.
497
+
498
+ ### Exit gate
499
+
500
+ - [x] Worker can ask planner a question while planner is busy.
501
+ - [x] Planner receives the question as a queued follow-up.
502
+ - [x] Worker task remains waiting rather than completed.
503
+ - [x] Planner can reply to worker.
504
+ - [x] Worker receives the reply and returns to running.
505
+
506
+ ---
507
+
508
+ ## Phase 7 — Task-aware watchers
509
+
510
+ ### Watcher core
511
+
512
+ - [x] Generalize or extend the watcher registry to accept task IDs.
513
+ - [x] Support one task ID.
514
+ - [x] Support an array of task IDs.
515
+ - [x] Return already-completed task results on registration.
516
+ - [x] Keep watcher registration non-blocking.
517
+ - [x] Preserve one-shot watcher behavior.
518
+ - [x] Make watcher delivery idempotent.
519
+ - [x] Preserve deterministic ordering for coalesced arrays.
520
+ - [x] Release watcher state after all tasks settle.
521
+ - [x] Release watcher timers at parent shutdown.
522
+
523
+ ### Completion behavior
524
+
525
+ - [x] Watch only terminal task states.
526
+ - [x] Do not settle on child idle state.
527
+ - [x] Do not settle on `agent_end`.
528
+ - [x] Do not settle on `agent_settled`.
529
+ - [x] Do not settle when a task enters `waiting`.
530
+ - [x] Include task ID in every completion.
531
+ - [x] Include agent ID in every completion.
532
+ - [x] Include terminal status and return code.
533
+ - [x] Include summary text where available.
534
+ - [x] Include error data where available.
535
+
536
+ ### Parent notification bridge
537
+
538
+ - [x] Deliver watcher results through a custom Shepherd parent message.
539
+ - [x] Use follow-up delivery for completion notifications.
540
+ - [x] Trigger a parent turn only according to watcher policy.
541
+ - [x] Suppress notifications after parent shutdown.
542
+ - [x] Preserve standard call/return/details formatting.
543
+
544
+ ### Compatibility
545
+
546
+ - [x] Decide whether `shepherd_watch` accepts legacy prompt IDs.
547
+ - [x] If accepted, map prompt IDs explicitly to task IDs.
548
+ - [x] Reject agent IDs and pane IDs as watcher targets.
549
+ - [x] Document the chosen compatibility behavior.
550
+ - [x] Update the existing watcher tests or retain a compatibility test suite.
551
+
552
+ ### Tests
553
+
554
+ - [x] Add `test/verify-task-watchers.mjs`.
555
+ - [x] Test a pending task.
556
+ - [x] Test an already-completed task.
557
+ - [x] Test multiple task IDs.
558
+ - [x] Test independent watchers.
559
+ - [x] Test completion ordering.
560
+ - [x] Test blocked completion.
561
+ - [x] Test failed completion.
562
+ - [x] Test cancelled completion.
563
+ - [x] Test timeout completion.
564
+ - [x] Test no completion from waiting state.
565
+ - [x] Test no duplicate completion notification.
566
+ - [x] Test parent shutdown.
567
+
568
+ ### Exit gate
569
+
570
+ - [x] `shepherd_watch` tracks tasks rather than turns.
571
+ - [x] The canonical scout/planner scenario remains pending during the wait.
572
+ - [x] The watcher reports exactly one result after `shepherd_done`.
573
+
574
+ ---
575
+
576
+ ## Phase 8 — Stale-wait monitoring
577
+
578
+ ### Configuration
579
+
580
+ - [x] Add a `staleWaitThreshold` setting.
581
+ - [x] Choose and document the default threshold.
582
+ - [x] Add validation and fallback behavior.
583
+ - [x] Add the setting to user-layer configuration.
584
+ - [x] Add project-delta support where appropriate.
585
+ - [x] Add the setting to the settings UI.
586
+ - [x] Add the setting to user-facing documentation.
587
+
588
+ ### Monitor
589
+
590
+ - [x] Start the monitor only when waiting tasks exist.
591
+ - [x] Inspect task state rather than raw agent state.
592
+ - [x] Require an unresolved expected reply.
593
+ - [x] Track `waitingSince`.
594
+ - [x] Calculate elapsed wait time.
595
+ - [x] Emit one notification per waiting episode.
596
+ - [x] Record notification delivery time.
597
+ - [x] Reset stale-notification state after a reply.
598
+ - [x] Add request timeout handling.
599
+ - [x] Stop the monitor when no waiting tasks remain.
600
+ - [x] Ensure the timer does not keep the process alive.
601
+
602
+ ### Notification content
603
+
604
+ - [x] Include task ID.
605
+ - [x] Include owning agent.
606
+ - [x] Include task description.
607
+ - [x] Include elapsed waiting time.
608
+ - [x] Include pending request ID.
609
+ - [x] Include question content.
610
+ - [x] Include recipient identity.
611
+ - [x] Include recipient process/task state.
612
+ - [x] Include possible Shepherd actions.
613
+ - [x] Preserve message/request correlation.
614
+
615
+ ### Parent delivery
616
+
617
+ - [x] Deliver stale-wait notifications as custom Shepherd messages.
618
+ - [x] Queue notifications as follow-ups.
619
+ - [x] Decide when stale notifications trigger an idle parent turn.
620
+ - [x] Avoid waking the parent on every normal waiting transition.
621
+ - [x] Avoid repeated notification storms.
622
+ - [x] Add optional later escalation only if justified by usage.
623
+
624
+ ### Tests
625
+
626
+ - [x] Add `test/verify-stale-wait.mjs`.
627
+ - [x] Test threshold crossing.
628
+ - [x] Test one notification per waiting episode.
629
+ - [x] Test notification content.
630
+ - [x] Test reset after reply.
631
+ - [x] Test completed task has no stale notification.
632
+ - [x] Test idle agent without a waiting task has no stale notification.
633
+ - [x] Test request timeout.
634
+ - [x] Test parent shutdown.
635
+
636
+ ### Exit gate
637
+
638
+ - [x] A waiting scout produces one useful stale-wait notification.
639
+ - [x] A reply clears the stale condition.
640
+ - [x] Completed and ordinary idle agents do not generate stale notifications.
641
+
642
+ ---
643
+
644
+ ## Phase 9 — Status and TUI integration
645
+
646
+ ### Status model
647
+
648
+ - [x] Extend `shepherd_status` with process state.
649
+ - [x] Extend `shepherd_status` with task state.
650
+ - [x] Include task ID when a task is active.
651
+ - [x] Include waiting age when applicable.
652
+ - [x] Include pending request ID when applicable.
653
+ - [x] Include waiting recipient when applicable.
654
+ - [x] Include stale flag when applicable.
655
+ - [x] Keep Herdr pane identity internal to diagnostics.
656
+ - [x] Preserve opaque agent IDs in public lifecycle results.
657
+
658
+ ### Status widget
659
+
660
+ - [x] Include waiting tasks in the status projection.
661
+ - [x] Do not filter waiting tasks out because the process is idle.
662
+ - [x] Render waiting distinctly from working.
663
+ - [x] Render waiting recipient where available.
664
+ - [x] Render waiting elapsed time.
665
+ - [x] Render stale state distinctly.
666
+ - [x] Preserve current session ownership filtering.
667
+ - [x] Avoid mailbox reads during every render frame.
668
+ - [x] Reuse bounded polling/snapshot behavior.
669
+
670
+ ### Tests
671
+
672
+ - [x] Update `test/verify-status-widget.mjs`.
673
+ - [x] Test idle process with waiting task.
674
+ - [x] Test working process with running task.
675
+ - [x] Test completed task removal.
676
+ - [x] Test stale waiting display.
677
+ - [x] Test session ownership filtering.
678
+ - [x] Test parent/child status separation.
679
+
680
+ ### Exit gate
681
+
682
+ - [x] Status shows process state and task state independently.
683
+ - [x] An idle waiting scout remains visible.
684
+ - [x] Status/widget tests pass.
685
+
686
+ ---
687
+
688
+ ## Phase 10 — Artifacts, cleanup, compatibility, and documentation
689
+
690
+ ### Artifacts
691
+
692
+ - [x] Allocate artifacts for delegated tasks only.
693
+ - [x] Do not allocate artifacts for ordinary messages.
694
+ - [x] Keep task artifacts open while waiting.
695
+ - [x] Finalize artifacts on task completion.
696
+ - [x] Finalize artifacts on blocked state.
697
+ - [x] Finalize artifacts on failure.
698
+ - [x] Finalize artifacts on cancellation.
699
+ - [x] Finalize artifacts on timeout.
700
+ - [x] Preserve final summaries and errors.
701
+ - [x] Avoid duplicate finalization from duplicate events.
702
+ - [x] Add useful request/message references without creating one note per chat.
703
+
704
+ ### Cleanup and shutdown
705
+
706
+ - [x] Stop parent mailbox polling on parent shutdown.
707
+ - [x] Stop child mailbox polling on child shutdown.
708
+ - [x] Preserve already-persisted task outcomes.
709
+ - [x] Cancel or fail tasks whose child disappears.
710
+ - [x] Cancel unresolved requests when an agent closes.
711
+ - [x] Close the broker only after child panes are confirmed gone.
712
+ - [x] Preserve existing temporary launch-directory cleanup rules.
713
+ - [x] Verify no foreign pane can be closed.
714
+ - [x] Verify no foreign session can consume the mailbox.
715
+
716
+ ### Compatibility
717
+
718
+ - [x] Decide whether `shepherd_prompt` remains as an alias.
719
+ - [x] Implement the chosen `shepherd_prompt` migration behavior.
720
+ - [x] Decide whether `shepherd_wait` remains as a compatibility adapter.
721
+ - [x] Implement the chosen `shepherd_wait` behavior.
722
+ - [x] Ensure old prompt completion semantics are not silently active.
723
+ - [x] Add compatibility tests for old calls where retained.
724
+ - [x] Add migration guidance to documentation.
725
+ - [x] Remove stale prompt-only assumptions from active descriptions.
726
+
727
+ ### Documentation
728
+
729
+ - [x] Update `README.md` with the new task/message workflow.
730
+ - [x] Add a README example showing `shepherd_delegate` followed by
731
+ `shepherd_watch`.
732
+ - [x] Add a README example showing child-to-child `shepherd_message` usage.
733
+ - [x] Document that an idle child may still own a waiting task.
734
+ - [x] Document explicit `shepherd_done` completion.
735
+ - [x] Update `docs/guides/tool-reference.md`.
736
+ - [x] Update `docs/reference/dictionary`.
737
+ - [x] Update `docs/plans/architecture.md`.
738
+ - [x] Document task IDs versus message IDs.
739
+ - [x] Document `shepherd_delegate`.
740
+ - [x] Document `shepherd_message`.
741
+ - [x] Document `shepherd_done`.
742
+ - [x] Document `shepherd_watch`.
743
+ - [x] Document waiting tasks with idle child processes.
744
+ - [x] Document `followUp` versus `steer`.
745
+ - [x] Document stale-wait notifications.
746
+ - [x] Document compatibility status of `shepherd_prompt`.
747
+ - [x] Document compatibility status of `shepherd_wait`.
748
+ - [x] Document child messaging behavior and reply correlation.
749
+
750
+ ### Exit gate
751
+
752
+ - [x] Artifacts follow task lifecycle correctly.
753
+ - [x] Shutdown and cleanup are safe.
754
+ - [x] Compatibility behavior is explicit.
755
+ - [x] Active documentation is updated.
756
+
757
+ ---
758
+
759
+ ## Phase 11 — Full verification and release readiness
760
+
761
+ ### Automated verification
762
+
763
+ - [x] Run task registry tests.
764
+ - [x] Run mailbox tests.
765
+ - [x] Run child-surface tests.
766
+ - [x] Run delegation tests.
767
+ - [x] Run task-completion tests.
768
+ - [x] Run message-routing tests.
769
+ - [x] Run task-watcher tests.
770
+ - [x] Run stale-wait tests.
771
+ - [x] Run status-widget tests.
772
+ - [x] Run schema tests.
773
+ - [x] Run parent-surface tests.
774
+ - [x] Run launch tests.
775
+ - [x] Run artifact-session tests.
776
+ - [x] Run the complete `npm test` suite.
777
+ - [x] Resolve all regressions without weakening task completion invariants.
778
+
779
+ ### Live Herdr matrix
780
+
781
+ - [x] Start or attach to a Herdr session.
782
+ - [x] Spawn persistent scout and planner agents.
783
+ - [x] Delegate a tracked task to scout.
784
+ - [x] Confirm delegation returns without blocking.
785
+ - [x] Have scout send a question to planner.
786
+ - [x] Keep planner busy while scout’s turn settles.
787
+ - [x] Confirm scout's Pi process becomes idle.
788
+ - [x] Confirm scout's task remains `waiting`.
789
+ - [x] Confirm no watcher completion is emitted.
790
+ - [x] Confirm the stale-wait notification appears after the threshold.
791
+ - [x] Have planner receive the queued question.
792
+ - [x] Have planner reply with the correct `replyTo` value.
793
+ - [x] Confirm scout receives the reply as a queued follow-up.
794
+ - [x] Confirm scout's task returns to `running`.
795
+ - [x] Have scout call `shepherd_done`.
796
+ - [x] Confirm exactly one watcher completion notification.
797
+ - [x] Confirm the completion contains the task summary.
798
+ - [x] Verify status output during `running`.
799
+ - [x] Verify status output during `waiting`.
800
+ - [x] Verify status output after completion.
801
+ - [x] Verify child-to-Shepherd messaging.
802
+ - [x] Verify Shepherd-to-child messaging.
803
+ - [x] Verify peer messaging through the parent broker.
804
+ - [x] Verify planner closure while scout waits.
805
+ - [x] Verify scout closure while planner has a queued question.
806
+ - [x] Verify task timeout.
807
+ - [x] Verify provider failure (model-not-found error observed; spawn readiness race recorded for follow-up).
808
+ - [x] Verify parent shutdown.
809
+ - [x] Verify pane ownership protection.
810
+ - [x] Verify temporary-resource cleanup.
811
+
812
+ ### Final review
813
+
814
+ - [x] Review all public tool schemas for flat object roots.
815
+ - [x] Review all public results for standard call/return/details formatting.
816
+ - [x] Review all child/parent identity checks.
817
+ - [x] Review all task terminal transitions.
818
+ - [x] Review all waiting-task transitions.
819
+ - [x] Review stale-wait notification rate limiting.
820
+ - [x] Review message queue limits and failure behavior.
821
+ - [x] Review fieldnote finalization behavior.
822
+ - [x] Review documentation against implemented behavior.
823
+ - [x] Mark the specification status as implemented only after all gates pass.
824
+
825
+ ## Definition of done
826
+
827
+ - [x] A delegated task can span multiple Pi turns.
828
+ - [x] A child can ask another participant a question and end its current turn.
829
+ - [x] An idle child with an outstanding request remains a waiting task, not a
830
+ completed task.
831
+ - [x] A queued reply can resume the child later.
832
+ - [x] Only explicit `shepherd_done` normally completes the task.
833
+ - [x] `shepherd_watch` reports terminal task completion without requiring
834
+ `shepherd_wait`.
835
+ - [x] Long waits notify the Shepherd without producing notification storms.
836
+ - [x] Parent and child messaging works through the owned broker.
837
+ - [x] Existing pane ownership and fieldnote safety invariants remain intact.
838
+ - [x] All focused tests, live Herdr checks, and `npm test` pass.