@luminascale/shepherd 0.0.0-stage → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (203) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,139 @@
1
+ # Implementation Plan: Non-blocking Shepherd Prompt Watchers
2
+
3
+ This plan implements `spec.md` by adding a background completion observer and a
4
+ parent notification bridge. The existing `shepherd_wait` implementation and
5
+ public behavior remain unchanged.
6
+
7
+ ## Target architecture
8
+
9
+ ```text
10
+ shepherd_prompt
11
+ │
12
+ ▼
13
+ existing PromptRecord
14
+ │
15
+ ├── shepherd_wait (existing blocking consumer)
16
+ │
17
+ └── shepherd_watch
18
+ │
19
+ ▼
20
+ watcher registry + background monitor
21
+ │
22
+ ├── settle existing prompt result
23
+ ├── buffer/deduplicate completion
24
+ └── notify parent via callback
25
+ │
26
+ ▼
27
+ pi.sendMessage
28
+ followUp + triggerTurn
29
+ ```
30
+
31
+ ## Design decisions
32
+
33
+ 1. **Prompt-level identity** — watchers accept prompt ids, not agent ids. A
34
+ persistent agent can receive multiple prompts, so an agent-level watcher
35
+ would be ambiguous.
36
+ 2. **Immediate registration** — `shepherd_watch` returns an acknowledgment and
37
+ never awaits child completion. The eventual completion is a custom parent
38
+ message, not a delayed return from the original tool call.
39
+ 3. **Result shape** — the registration response includes `watcherId`, the
40
+ normalized prompt ids, pending ids, and already-completed structured results.
41
+ Completion notifications include prompt id, agent id, status, return code,
42
+ error, and the last assistant message.
43
+ 4. **One-shot watchers** — each watched prompt is delivered once per watcher.
44
+ A watcher automatically finishes when all its prompts settle; there is no
45
+ separate cancellation operation for watcher delivery.
46
+ 5. **Existing wait remains authoritative for its callers** — do not modify the
47
+ `shepherd_wait` tool, its schemas, its public result format, or its current
48
+ timeout/cancellation semantics. Watcher observation may settle the shared
49
+ prompt record idempotently so a simultaneous wait sees the same result.
50
+ 6. **Narrow notification boundary** — core code receives an injected callback
51
+ for parent notifications. It does not import or access a global `pi` object.
52
+ 7. **Follow-up delivery** — use a custom Shepherd message with follow-up
53
+ delivery. Queue while the parent is active and trigger a new turn when the
54
+ parent is idle.
55
+ 8. **Burst coalescing** — report individual completions as they arrive, but
56
+ coalesce completions observed in a short window into one parent message when
57
+ possible.
58
+
59
+ ## Phase 1 — Define watcher state and protocol
60
+
61
+ Add internal watcher types and registry operations without changing existing
62
+ wait types:
63
+
64
+ - watcher handle and watcher result types;
65
+ - watcher records with prompt ids, delivery state, and lifecycle state;
66
+ - prompt-to-watcher indexes;
67
+ - registration, completion, and automatic cleanup operations;
68
+ - normalization and validation for one id or an array of ids.
69
+
70
+ The existing prompt result type should be reused for completed entries wherever
71
+ possible. No Herdr pane id should be part of the public watcher protocol.
72
+
73
+ ## Phase 2 — Add background observation
74
+
75
+ Implement a monitor that starts only when a watcher is registered:
76
+
77
+ - inspect all active watched prompts from one parent session;
78
+ - use the existing completion sidecar, state sequence, result file, and
79
+ provider-error detection rules;
80
+ - handle prompts already settled before registration;
81
+ - settle the existing prompt record exactly once;
82
+ - notify watcher records after settlement;
83
+ - deduplicate polling and completion delivery;
84
+ - stop the monitor when no active watched prompts remain.
85
+
86
+ The monitor must not leave the `shepherd_watch` tool execution pending. It may
87
+ share low-level read helpers with wait, but must not change wait's code path or
88
+ external semantics.
89
+
90
+ ## Phase 3 — Add parent notification bridge
91
+
92
+ At tool registration time, provide the watcher service with a narrow callback
93
+ that sends a custom message through the current parent `ExtensionAPI`:
94
+
95
+ - create a structured Shepherd completion message;
96
+ - include the watcher id, prompt id(s), agent id(s), labels, statuses, return
97
+ codes, errors, and final assistant text;
98
+ - use follow-up delivery so an active parent turn is not interrupted;
99
+ - trigger a parent turn when the parent is idle;
100
+ - coalesce close-together completions;
101
+ - suppress new turns during shutdown/reload.
102
+
103
+ The core service should continue buffering results even if message delivery is
104
+ unavailable or fails. Message delivery failure must not corrupt prompt
105
+ settlement or fieldnote finalization.
106
+
107
+ ## Phase 4 — Register tools and integrate guidance
108
+
109
+ Add `shepherd_watch` to the extension surface:
110
+
111
+ - declare all tool metadata directly in each `pi.registerTool` call;
112
+ - use the existing public result formatting and opaque-id conventions;
113
+ - add watcher descriptions and guidance to the umbrella tool;
114
+ - keep the array input shape aligned with `shepherd_wait`;
115
+ - expose registration and completion details without exposing raw Herdr ids.
116
+
117
+ Update README/lifecycle examples to show both explicit blocking waits and
118
+ non-blocking watch-based workflows.
119
+
120
+ ## Phase 5 — Resource and session boundaries
121
+
122
+ Ensure watcher state is bounded to the parent extension session:
123
+
124
+ - clean active monitors at `session_shutdown`;
125
+ - remove watcher registrations on reload/session replacement;
126
+ - do not close child panes as part of watcher completion;
127
+ - retain existing child result files and fieldnotes;
128
+ - avoid duplicate monitors after reload or repeated registration;
129
+ - ensure completion remains available to `shepherd_wait` after notification delivery.
130
+
131
+ ## Phase 6 — Verification and rollout
132
+
133
+ Add focused registry, notification, and tool-schema tests, then run the full
134
+ suite. Perform live Herdr checks with one and multiple prompts, including
135
+ completion while the parent is active and completion while it is idle.
136
+
137
+ After all checks pass, update the implementation status in the specification
138
+ and add a completed-watcher entry to the repository's documentation index if
139
+ one exists.
@@ -0,0 +1,202 @@
1
+ # Non-blocking Shepherd Prompt Watchers
2
+
3
+ ## Status
4
+
5
+ Implemented. Focused registry, notification, schema, and lifecycle tests pass;
6
+ live Herdr verification remains an operational follow-up.
7
+
8
+ ## Summary
9
+
10
+ Add an asynchronous watcher to pi-shepherd for prompt completions. A watcher
11
+ registers interest in one or more existing prompt ids and returns immediately.
12
+ When a watched prompt settles, Shepherd stores the result and sends a custom
13
+ follow-up message to the parent pi session so the parent model can process the
14
+ completion in a later turn.
15
+
16
+ The watcher is an additional synchronization mechanism. It does not replace,
17
+ modify, or change the public behavior of `shepherd_wait`.
18
+
19
+ The intended workflow is:
20
+
21
+ ```text
22
+ spawn
23
+ → prompt
24
+ → watcher registration returns immediately
25
+ → parent turn continues or ends
26
+ → child completes
27
+ → watcher records the result
28
+ → watcher sends a custom follow-up message to the parent
29
+ → parent model processes the completion
30
+ ```
31
+
32
+ ## Goals
33
+
34
+ - Allow the parent model to continue while child prompts run.
35
+ - Watch one prompt or an array of prompt ids.
36
+ - Report each completion with the exact prompt id and persistent agent id.
37
+ - Include the child agent's final assistant message in completion notifications.
38
+ - Handle prompts that finish before watcher registration without losing results.
39
+ - Preserve the existing `shepherd_wait` API and semantics.
40
+ - Make watcher completion idempotent and safe when `wait` is also polling.
41
+ - Keep watcher lifetime and notification delivery bounded to the parent session.
42
+ - Preserve existing fieldnote/artifact finalization through the prompt registry.
43
+
44
+ ## Non-goals
45
+
46
+ - Do not replace or change `shepherd_wait`.
47
+ - Do not add workflow-specific `parallel`, `chain`, or fan-in modes.
48
+ - Do not watch by Herdr pane id or infer a prompt from an agent id.
49
+ - Do not make watcher registration block until a child completes.
50
+ - Do not use a synthetic user message for a Shepherd-generated notification.
51
+ - Do not automatically close agents when watched prompts complete.
52
+ - Do not make watcher notifications depend on the parent calling another
53
+ blocking tool.
54
+
55
+ ## Terminology
56
+
57
+ ### Prompt id
58
+
59
+ The opaque id returned by `shepherd_prompt`. A watcher observes a specific
60
+ prompt invocation, not all future work submitted to an agent.
61
+
62
+ ### Watcher
63
+
64
+ A one-shot subscription associated with one or more prompt ids. It remains
65
+ active until all watched prompts settle or the parent session shuts down.
66
+
67
+ ### Completion notification
68
+
69
+ A custom message injected into the parent pi session after one or more watched
70
+ prompts settle. It is not the return value of the original watcher tool call.
71
+
72
+ ## Public API
73
+
74
+ ### `shepherd_watch({ id })`
75
+
76
+ `id` accepts either one opaque prompt id or an array of opaque prompt ids. The
77
+ array behavior is completion-oriented rather than wait-oriented: prompts are
78
+ reported as they finish, not only after every prompt has completed.
79
+
80
+ Examples:
81
+
82
+ ```text
83
+ shepherd_watch({ id: "shepherd-prompt-a" })
84
+ shepherd_watch({ id: ["shepherd-prompt-a", "shepherd-prompt-b"] })
85
+ ```
86
+
87
+ The tool returns immediately with a registration acknowledgment. Its result
88
+ contains:
89
+
90
+ - `watcherId`: opaque watcher id;
91
+ - `promptIds`: normalized watched prompt ids;
92
+ - `pending`: prompt ids not yet settled;
93
+ - `completed`: results already available at registration time.
94
+
95
+ An already-completed prompt must appear in `completed` so a fast completion
96
+ cannot be lost between `prompt` and `watch`.
97
+
98
+ A representative result is:
99
+
100
+ ```json
101
+ {
102
+ "watcherId": "shepherd-watch-...",
103
+ "promptIds": ["shepherd-prompt-a", "shepherd-prompt-b"],
104
+ "pending": ["shepherd-prompt-a"],
105
+ "completed": [
106
+ {
107
+ "promptId": "shepherd-prompt-b",
108
+ "agentId": "shepherd-agent-...",
109
+ "status": "done",
110
+ "ok": true,
111
+ "returnCode": 0,
112
+ "text": "The agent's last assistant message."
113
+ }
114
+ ]
115
+ }
116
+ ```
117
+
118
+ The public Shepherd tool result must continue to use the standard service
119
+ message, `call:`, `return:`, and `details:` structure.
120
+
121
+ ## Completion notifications
122
+
123
+ When a watched prompt settles, Shepherd sends a custom message through the
124
+ parent extension using the equivalent of:
125
+
126
+ ```text
127
+ pi.sendMessage(custom Shepherd completion message, {
128
+ deliverAs: "followUp",
129
+ triggerTurn: true
130
+ })
131
+ ```
132
+
133
+ The notification must be queued as a follow-up rather than interrupting an
134
+ active parent tool chain. If the parent is idle, it should trigger a new model
135
+ turn. The message should be a custom Shepherd message, not a normal user
136
+ message.
137
+
138
+ Each notification includes:
139
+
140
+ - `watcherId`;
141
+ - `promptId`;
142
+ - `agentId`;
143
+ - agent name and label when available;
144
+ - terminal status;
145
+ - `ok` and process-style `returnCode`;
146
+ - error information for failed, blocked, timed-out, or cancelled prompts; and
147
+ - `text`, containing the last assistant message when available.
148
+
149
+ The prompt id is the primary correlation key because one persistent agent may
150
+ receive several prompts over its lifetime. Herdr pane ids must not be exposed
151
+ as watcher correlation ids.
152
+
153
+ For an array watcher, completions should be delivered independently as they
154
+ arrive. Completions occurring close together may be coalesced into one custom
155
+ message containing an array of completion results to avoid triggering one
156
+ parent turn per child. Coalesced completion arrays preserve the watcher's input
157
+ prompt order so their presentation is deterministic.
158
+
159
+ ## Lifecycle and correctness
160
+
161
+ - A watcher is one-shot. Each watched prompt produces at most one notification
162
+ per watcher.
163
+ - Registering a watcher for an already-settled prompt returns that result in
164
+ the immediate `completed` collection and must not produce a duplicate event.
165
+ - Multiple watchers may observe the same prompt. Each watcher has independent
166
+ delivery state, while prompt settlement remains globally idempotent.
167
+ - A watcher may settle the existing prompt record using the existing lifecycle
168
+ settlement path. If `shepherd_wait` is also active, its promise resolves with
169
+ the same result and duplicate settlement is ignored.
170
+ - The final result remains stored in the prompt registry. Notifications are a
171
+ delivery mechanism, not the only copy of the result.
172
+ - Existing completion signals, state transitions, result files, and provider
173
+ error handling should be reused. The watcher must apply the same safeguards
174
+ against pre-submit idle state and stale completion signals.
175
+ - Successful, failed, blocked, timed-out, and close-cancelled prompts all
176
+ produce terminal watcher results.
177
+ - Watchers and monitor timers are released after completion or parent session
178
+ shutdown.
179
+ - The watcher must not delete child session files, fieldnotes, or other
180
+ existing retained lifecycle resources.
181
+ - When the parent is shutting down or reloading, no new parent turn should be
182
+ triggered. Active watcher resources must still be cleaned up safely.
183
+
184
+ ## Integration boundaries
185
+
186
+ The watcher service may live in the core lifecycle/orchestration layer, but it
187
+ must not directly depend on a global pi singleton. The extension registration
188
+ layer should provide a narrow notification callback backed by `pi.sendMessage`.
189
+
190
+ The watcher may use the existing `LifecycleRegistry` prompt records and
191
+ settlement callbacks. It must not repurpose `LifecycleRegistry.sessionId` or
192
+ change public lifecycle id validation.
193
+
194
+ The parent extension owns message delivery policy. Core watcher state owns
195
+ prompt observation, result buffering, deduplication, and cleanup.
196
+
197
+ ## Verification requirements
198
+
199
+ The implementation is complete only when focused unit tests and live Herdr
200
+ checks verify single and array watchers, fast completions, notification
201
+ queuing, completion ordering, failure states, duplicate observation, and parent
202
+ session cleanup. `npm test` must pass.
@@ -0,0 +1,126 @@
1
+ # Tasks: Non-blocking Shepherd Prompt Watchers
2
+
3
+ Implement in order. Mark a task complete only after its code and focused
4
+ verification pass. Do not modify `shepherd_wait` as part of this feature.
5
+
6
+ ## Phase 1 — Protocol and registry
7
+
8
+ - [x] **1.1 Define watcher types**
9
+ - Add watcher handle, registration result, and notification types.
10
+ - Reuse existing prompt result fields for terminal outcomes.
11
+ - Keep watcher ids opaque and distinct from agent, prompt, and Herdr pane ids.
12
+
13
+ - [x] **1.2 Add watcher registry state**
14
+ - Track watcher records and prompt-to-watcher relationships.
15
+ - Track per-watcher delivered prompt ids.
16
+ - Enforce one notification per watched prompt per watcher.
17
+ - Support watcher lookup, completion, and removal.
18
+
19
+ - [x] **1.3 Validate watch input**
20
+ - Accept one prompt id or a non-empty array of prompt ids.
21
+ - Resolve every id through the existing prompt registry.
22
+ - Reject unknown, malformed, duplicate, or closed references according to the
23
+ existing lifecycle error conventions.
24
+
25
+ ## Phase 2 — Background observation
26
+
27
+ - [x] **2.1 Start non-blocking monitoring**
28
+ - Start monitoring when `shepherd_watch` registers a prompt.
29
+ - Return from the tool without awaiting prompt completion.
30
+ - Deduplicate monitors for prompts watched by multiple watchers.
31
+
32
+ - [x] **2.2 Reuse completion detection**
33
+ - Apply completion sidecar and state-transition safeguards.
34
+ - Read the final assistant response from the existing result source.
35
+ - Detect provider errors, blocked states, timeout states, and cancellation.
36
+ - Handle completion before watcher registration.
37
+
38
+ - [x] **2.3 Settle and buffer results**
39
+ - Use the existing prompt settlement path exactly once.
40
+ - Preserve artifact/fieldnote callbacks.
41
+ - Keep results available after watcher delivery.
42
+ - Ensure a simultaneous existing `shepherd_wait` receives the same result.
43
+
44
+ - [x] **2.4 Clean monitoring resources**
45
+ - Stop monitors after all watched prompts settle.
46
+ - Stop monitors after completion and on parent session shutdown.
47
+ - Avoid timers or callbacks surviving session replacement/reload.
48
+
49
+ ## Phase 3 — Parent notifications
50
+
51
+ - [x] **3.1 Add notification callback boundary**
52
+ - Inject a narrow parent notification callback into the watcher service.
53
+ - Keep core lifecycle code independent of a global `pi` object.
54
+
55
+ - [x] **3.2 Send custom follow-up messages**
56
+ - Use `pi.sendMessage`, not `pi.sendUserMessage`.
57
+ - Queue as `deliverAs: "followUp"`.
58
+ - Trigger a new parent turn when idle.
59
+ - Suppress new turns during shutdown/reload.
60
+
61
+ - [x] **3.3 Define completion payload**
62
+ - Include watcher id, prompt id, agent id, agent name/label, status, `ok`,
63
+ return code, error, and last assistant message.
64
+ - Preserve structured result information for array completions.
65
+
66
+ - [x] **3.4 Coalesce notification bursts**
67
+ - Report completions independently as they become available.
68
+ - Coalesce close-together completions into one notification where practical.
69
+ - Ensure coalescing does not lose ordering or individual prompt identity.
70
+
71
+ ## Phase 4 — Tool surface
72
+
73
+ - [x] **4.1 Register `shepherd_watch`**
74
+ - Add the direct TypeBox schema for one id or an array of ids.
75
+ - Return watcher id, normalized prompt ids, pending ids, and completed results.
76
+ - Handle already-completed prompts without duplicate notifications.
77
+ - Preserve standard Shepherd call/return/details formatting.
78
+
79
+ - [x] **4.2 Update model guidance**
80
+ - Add watcher guidance to the umbrella tool and registered tool descriptions.
81
+ - Explain prompt-id arrays and asynchronous completion notifications.
82
+ - Explain that `wait` remains available for deterministic barriers.
83
+
84
+ ## Phase 5 — Documentation and tests
85
+
86
+ - [x] **5.1 Add registry tests**
87
+ - Single watcher registration.
88
+ - Array watcher registration.
89
+ - Already-completed prompts.
90
+ - Multiple watchers for one prompt.
91
+ - Duplicate settlement and one-shot cleanup.
92
+
93
+ - [x] **5.2 Add result-state tests**
94
+ - Successful, failed, blocked, timed-out, and cancelled prompts.
95
+ - Final assistant text and all correlation ids.
96
+ - Concurrent watch and wait observing one shared result.
97
+
98
+ - [x] **5.3 Add notification tests**
99
+ - Follow-up delivery while the parent is active.
100
+ - Automatic triggering while the parent is idle.
101
+ - Burst coalescing.
102
+ - Notification delivery failure without lifecycle corruption.
103
+ - Shutdown/reload cleanup.
104
+
105
+ - [x] **5.4 Add tool and documentation coverage**
106
+ - Validate schemas and public result formatting.
107
+ - Update README and lifecycle examples.
108
+ - Document the watcher contract and distinction from `wait`.
109
+
110
+ - [x] **5.5 Run verification** (automated checks; live Herdr verification pending)
111
+ - Run `git diff --check`.
112
+ - Run focused watcher tests.
113
+ - Run `npm test`.
114
+ - Perform live Herdr verification with single and multi-prompt watchers.
115
+
116
+ ## Phase 6 — Completion
117
+
118
+ - [x] **6.1 Review against specification**
119
+ - Confirm `shepherd_wait` was not replaced or behaviorally changed.
120
+ - Confirm no raw Herdr pane ids are exposed as watcher ids.
121
+ - Confirm watcher completion does not close agents.
122
+ - Confirm no retained child result or fieldnote resources are deleted.
123
+
124
+ - [x] **6.2 Mark the specification complete**
125
+ - Update `spec.md` status after implementation and verification pass.
126
+ - Record any intentional deviations from the specification.